Actions de personnalisation acceptées

Pour personnaliser vos images de machines virtuelles (par exemple, en exécutant des scripts de terminal, en mettant à jour les paramètres de démarrage, en transférant des binaires ou en installant des pilotes de GPU), vous pouvez définir des actions d'assistance spécifiques dans le bloc spec.steps de votre recette de personnalisation (imagebuilder.yaml).

Présentation

Pendant la phase d'exécution d'une compilation Image Builder, l'orchestrateur exécute séquentiellement les étapes déclarées dans votre recette de personnalisation (spec.steps) sur la VM de nœud de calcul temporaire.

Chaque étape doit spécifier un bloc name, un bloc action et un bloc inputs adaptés à ce type d'action. Image Builder est compatible avec les actions de personnalisation suivantes :

• Shell : exécute des scripts ou des commandes de terminal intégrés sur l'OS invité du worker.
• UpdateKernelCommandLine : modifie les paramètres de démarrage et les flags de ligne de commande du noyau.
• FileCopy : transfère les fichiers de configuration, les scripts ou les composants depuis Cloud Storage ou des espaces de travail locaux vers la VM.
• InstallGPU : télécharge, compile et enregistre les pilotes de GPU NVIDIA.

Action du shell

L'action Shell vous permet d'exécuter des scripts de terminal intégrés ou des commandes shell uniques sur l'OS invité de la VM de nœud de calcul temporaire pour effectuer des personnalisations telles que la mise à jour de packages, la configuration de comptes utilisateur ou la compilation de logiciels.

Spécifiez l'une des entrées suivantes sous steps.inputs :

• inlineScript (chaîne) : commandes shell brutes multilignes à exécuter.
• command (chaîne) : chaîne de commande système unique ou chemin d'accès relatif à un fichier binaire exécutable.

Exemples de configurations

Les onglets suivants présentent des exemples de configurations d'étapes pour exécuter un script intégré ou une seule commande :

- name: "Update guest packages and configure groups"
  action: Shell
  inputs:
    inlineScript: |
      #!/bin/bash
      apt-get update -y
      apt-get install -y fail2ban build-essential
      groupadd -r adminusers

- name: "Log kernel identifier"
  action: Shell
  inputs:
    command: "uname -a"

Comportements spéciaux

Lorsque vous exécutez des actions Shell, le provisionneur de personnalisation gère l'audit de sécurité et les redémarrages système automatisés, comme décrit dans les sections suivantes :

Audits de sécurité

Pour éviter que des jetons, des secrets ou du code propriétaire sensibles ne soient divulgués dans les journaux d'exécution, le provisionneur de personnalisation n'imprime pas les lignes brutes de vos scripts, sauf si le débogage interactif est activé (debug: true). Au lieu de cela, il enregistre le hachage d'intégrité SHA-256 de la charge utile de votre script dans les journaux de compilation. Ce hachage fournit une trace d'audit immuable du code exécuté sur l'image.

Redémarrages du système (code d'erreur 3010)

Certaines actions shell, telles que les mises à jour des correctifs du noyau ou les ajustements des partitions de stockage, nécessitent un redémarrage du système avant que les étapes suivantes puissent s'exécuter.

Pour demander un redémarrage du système lors de la personnalisation, votre script shell doit se terminer par la commande exit 3010. Lorsque le provisionneur de personnalisation reçoit le code de sortie 3010, il gère le cycle de vie du redémarrage comme suit :

1. Le provisionneur détecte le code de sortie 3010, met l'exécution en pause et marque l'index de progression de l'étape.
2. Le provisionneur redémarre la VM de nœud de calcul.
3. Une fois la VM redémarrée, le provisionneur monte l'espace de travail et reprend automatiquement le pipeline à l'étape suivante de la file d'attente.

Exemple de redémarrage :

L'exemple suivant montre une configuration d'étape qui met à jour les packages et demande un redémarrage :

- name: "Install core updates and request reboot"
  action: Shell
  inputs:
    inlineScript: |
      #!/bin/bash
      echo "Applying configuration package upgrades..."
      apt-get dist-upgrade -y
      # Terminate with return code 3010 to trigger a system reboot
      exit 3010
- name: "Post-reboot verification"
  action: Shell
  inputs:
    command: "uname -r"

Action UpdateKernelCommandLine

L'action UpdateKernelCommandLine permet de localiser, de remplacer, d'insérer ou de supprimer des indicateurs de ligne de commande transmis au noyau au démarrage du système, par exemple lorsque vous configurez les journaux de la console ou ajustez les paramètres du noyau.

Spécifiez les propriétés suivantes dans la carte steps.inputs :

• oldArguments (chaîne, obligatoire) : arguments de ligne de commande exacts pour localiser, supprimer ou remplacer dans la configuration du bootloader.
• newArguments (chaîne, facultatif) : arguments de remplacement à écrire à la place des indicateurs cibles. Si vous omettez la propriété newArguments, Image Builder supprime entièrement les paramètres configurés dans la propriété oldArguments de la ligne de démarrage.

Exemples de configurations

Les onglets suivants présentent des exemples de configurations d'étapes pour remplacer ou supprimer des arguments de démarrage du noyau :

- name: "Configure detailed boot logging"
  action: UpdateKernelCommandLine
  inputs:
    oldArguments: "loglevel=4"
    newArguments: "loglevel=6 console=ttyS0"

- name: "Enable verbose startup diagnostics"
  action: UpdateKernelCommandLine
  inputs:
    oldArguments: "quiet"

Détails d'exécution spécifiques à l'OS

Les onglets suivants décrivent comment le provisionneur de personnalisation gère les modifications d'image en fonction du système d'exploitation invité source :

Action FileCopy

L'action FileCopy copie les fichiers de configuration, les binaires ou les certificats d'un bucket distant ou de votre dépôt local vers votre image personnalisée. Le provisionneur de personnalisation télécharge ou lit le fichier source, l'écrit dans le chemin d'accès invité que vous avez spécifié sur la VM de nœud de calcul et configure les autorisations.

Spécifiez les entrées suivantes sous steps.inputs :

• destination (chaîne, obligatoire) : chemin absolu dans l'OS invité où le fichier est créé.
• permissions (chaîne, obligatoire) : représentation octale des autorisations de configuration cibles, telles que "0755" ou "0644".
• Spécifiez l'une des propriétés de source suivantes :
  • gcsSourcePath (chaîne) : URI Cloud Storage du fichier source, qui doit respecter le format gs://BUCKET_NAME/OBJECT_NAME.
  • localSourcePath (chaîne) : chemin d'accès relatif au fichier dans le dossier du dépôt de l'espace de travail local. La traversée de répertoire à l'aide de ../ est bloquée pour des raisons de sécurité.

Exemples de configurations

Les onglets suivants présentent des exemples de configurations d'étapes pour copier un fichier depuis Cloud Storage ou depuis votre espace de travail local :

- name: "Import licensing configuration"
  action: FileCopy
  inputs:
    gcsSourcePath: "gs://enterprise-configs-bucket/licensing/license.key"
    destination: "/etc/app/license.key"
    permissions: "0600"

- name: "Deploy setup automation daemon"
  action: FileCopy
  inputs:
    localSourcePath: "bin/setup-daemon"
    destination: "/usr/local/bin/setup-daemon"
    permissions: "0755"

Consignes spécifiques à l'OS

Les onglets suivants décrivent les consignes concernant l'emplacement des fichiers en fonction du système d'exploitation invité cible :

Action InstallGPU

Utilisez l'action InstallGPU pour créer des images de VM optimisées pour les charges de travail de machine learning, de data science ou scientifiques. Image Builder télécharge, compile et enregistre les pilotes de GPU NVIDIA sur vos images personnalisées. Selon le type d'image de base et le matériel cible, vous pouvez choisir d'installer des pilotes précompilés ou de compiler des fichiers .run de pilote personnalisé.

Spécifiez l'une des entrées suivantes sous steps.inputs :

• version (chaîne) : numéro de version du pilote NVIDIA cible, tel que "595.129.03". Si vous ne spécifiez que version, l'orchestrateur télécharge le pilote à partir du dépôt NVIDIA officiel (https://us.download.nvidia.com/tesla/<version>).
• gcsRunfile (chaîne) : chemin d'accès Cloud Storage d'un fichier d'installation de pilote NVIDIA personnalisé, qui doit utiliser le format gs://BUCKET_NAME/OBJECT_NAME.run.
• sourceRunfile (chaîne) : chemin d'accès relatif à un fichier .run d'installation dans le dossier du dépôt de l'espace de travail local.

Exemples de configurations

Les onglets suivants présentent des exemples de configurations d'étapes pour l'installation d'une version spécifique de pilote préconfiguré par rapport à l'installation d'un fichier .run personnalisé :

- name: "Configure default NVIDIA drivers"
  action: InstallGPU
  inputs:
    version: "<var>DRIVER_VERSION</var>"

- name: "Deploy custom GPU driver from Cloud Storage"
  action: InstallGPU
  inputs:
    gcsRunfile: "gs://<var>BUCKET_NAME</var>/drivers/NVIDIA-Linux-aarch64-<var>DRIVER_VERSION</var>.run"

- name: "Deploy custom GPU driver from workspace"
  action: InstallGPU
  inputs:
    sourceRunfile: "drivers/NVIDIA-Linux-x86_64-<var>DRIVER_VERSION</var>.run"

Méthodes de configuration

Les onglets suivants décrivent les méthodes compatibles pour configurer les pilotes de GPU NVIDIA sur vos images personnalisées :

Étapes suivantes

• Consultez les blocs de schéma de premier niveau dans le schéma du fichier de personnalisation des images.
• Configurez les paramètres d'orchestration du pipeline dans le schéma du fichier de configuration de compilation Cloud Build.
• Suivez le tutoriel Créer un pipeline Image Builder.