Unterstützte Anpassungsaktionen

Wenn Sie Ihre VM-Images anpassen möchten, z. B. durch Ausführen von Terminalskripts, Aktualisieren von Bootparametern, Übertragen von Binärdateien oder Installieren von GPU-Treibern, können Sie im spec.steps-Block Ihres Anpassungsrezepts (imagebuilder.yaml) bestimmte Hilfsaktionen definieren.

Übersicht

Während der Ausführungsphase eines Image Builder-Builds führt der Orchestrator die in Ihrem Anpassungsrezept (spec.steps) deklarierten Schritte sequenziell auf der temporären Worker-VM aus.

Für jeden Schritt müssen ein name-, ein action- und ein inputs-Block angegeben werden, die auf den jeweiligen Aktionstyp zugeschnitten sind. Image Builder unterstützt die folgenden Anpassungsaktionen:

• Shell: Führt Inline-Terminalskripts oder -Befehle im Gastbetriebssystem des Workers aus.
• UpdateKernelCommandLine: Ändert Bootparameter und Kernel-Befehlszeilen-Flags.
• FileCopy: Überträgt Konfigurationsdateien, Skripts oder Assets aus Cloud Storage oder lokalen Arbeitsbereichen auf die VM.
• InstallGPU: Lädt NVIDIA-GPU-Treiber herunter, kompiliert und registriert sie.

Shell-Aktion

Mit der Aktion Shell können Sie Inline-Terminalskripts oder einzelne Shell-Befehle im Gastbetriebssystem der temporären Worker-VM ausführen, um Anpassungen wie das Aktualisieren von Paketen, das Konfigurieren von Nutzerkonten oder das Kompilieren von Software vorzunehmen.

Geben Sie unter steps.inputs einen der folgenden Werte ein:

• inlineScript (String): Rohformatierte mehrzeilige Shell-Befehle, die ausgeführt werden sollen.
• command (String): Ein einzelner Systembefehlsstring oder relativer Pfad zu einer ausführbaren Binärdatei.

Beispielkonfigurationen

Auf den folgenden Tabs finden Sie Beispielkonfigurationen für Schritte zum Ausführen eines Inline-Skripts im Vergleich zum Ausführen eines einzelnen Befehls:

- 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"

Besonderheiten

Wenn Sie Shell-Aktionen ausführen, verwaltet der Anpassungsbereitsteller die Sicherheitsüberprüfung und automatische Systemneustarts, wie in den folgenden Abschnitten beschrieben:

Sicherheitsprüfung

Damit keine vertraulichen Tokens, Secrets oder proprietären Codes in Ausführungsprotokolle gelangen, gibt der Anpassungs-Bereitsteller die Rohzeilen Ihrer Skripts nur aus, wenn das interaktive Debugging aktiviert ist (debug: true). Stattdessen wird der SHA‑256-Integritätshash Ihrer Skript-Nutzlast in den Build-Protokollen protokolliert. Dieser Hash bietet einen unveränderlichen Audit-Trail, der genau zeigt, welcher Code für das Bild ausgeführt wurde.

Systemneustarts (Exitcode 3010)

Für einige Shell-Aktionen, z. B. Kernel-Patch-Updates oder Anpassungen von Speicherpartitionen, ist ein Neustart des Systems erforderlich, bevor nachfolgende Schritte ausgeführt werden können.

Wenn Sie während der Anpassung einen Systemneustart anfordern möchten, muss Ihr Shell-Skript mit dem Befehl exit 3010 enden. Wenn der Anpassungsbereitsteller den Exit-Code 3010 empfängt, wird der Neustart-Lebenszyklus so behandelt:

1. Der Provisioner erkennt den Exit-Code 3010, pausiert die Ausführung und markiert den Schrittfortschrittsindex.
2. Der Provisioner startet die Worker-VM neu.
3. Nach dem Neustart der VM wird der Arbeitsbereich vom Provisioner bereitgestellt und die Pipeline wird automatisch mit dem nächsten Schritt in der Warteschlange fortgesetzt.

Beispiel für Neustart:

Das folgende Beispiel zeigt eine Schrittkonfiguration, die Pakete aktualisiert und einen Neustart anfordert:

- 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"

Aktion „UpdateKernelCommandLine“

Mit der Aktion UpdateKernelCommandLine werden Befehlszeilen-Flags, die beim Systemstart an den Kernel übergeben werden, gesucht, ersetzt, eingefügt oder entfernt. Das ist z. B. der Fall, wenn Sie Konsolenprotokolle konfigurieren oder Kernelparameter anpassen.

Geben Sie die folgenden Attribute unter der Karte steps.inputs an:

• oldArguments (String, erforderlich): Die genauen Befehlszeilenargumente, die in der Bootloader-Konfiguration gesucht, entfernt oder ersetzt werden sollen.
• newArguments (String, optional): Die Ersetzungsargumente, die anstelle der Zielflags geschrieben werden sollen. Wenn Sie das Attribut newArguments weglassen, entfernt Image Builder die in oldArguments konfigurierten Parameter vollständig aus der Bootzeile.

Beispielkonfigurationen

Auf den folgenden Tabs finden Sie Beispielkonfigurationen für Schritte zum Ersetzen oder Entfernen von Kernel-Boot-Argumenten:

- 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"

Betriebssystemspezifische Ausführungsdetails

Auf den folgenden Tabs wird beschrieben, wie der Anpassungsbereitsteller Bildänderungen je nach Quellbetriebssystem des Gastes verarbeitet:

FileCopy-Aktion

Mit der Aktion FileCopy werden Konfigurationsdateien, Binärdateien oder Zertifikate aus einem Remote-Bucket oder Ihrem lokalen Repository in Ihr benutzerdefiniertes Image kopiert. Der Anpassungs-Provisioner lädt die Quelldatei herunter oder liest sie, schreibt sie in den von Ihnen angegebenen Gastpfad auf der Worker-VM und konfiguriert die Berechtigungen.

Geben Sie die folgenden Eingaben unter steps.inputs an:

• destination (String, erforderlich): Der absolute Pfad im Gastbetriebssystem, in dem die Datei erstellt wird.
• permissions (String, erforderlich): Die oktale Darstellung der Berechtigungen für die Zielkonfiguration, z. B. "0755" oder "0644".
• Geben Sie eine der folgenden Quelleigenschaften an:
  • gcsSourcePath (string): Der Cloud Storage-URI der Quelldatei, der dem Format gs://BUCKET_NAME/OBJECT_NAME entsprechen muss.
  • localSourcePath (String): Der relative Pfad zur Datei im lokalen Arbeitsbereichs-Repository-Ordner. Der Pfad-Traversal-Angriff mit ../ wird aus Sicherheitsgründen blockiert.

Beispielkonfigurationen

Auf den folgenden Tabs finden Sie Beispielkonfigurationen für das Kopieren einer Datei aus Cloud Storage im Vergleich zum Kopieren aus Ihrem lokalen Arbeitsbereich:

- 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"

Betriebssystemspezifische Richtlinien

Auf den folgenden Tabs werden Richtlinien für den Speicherort von Dateien je nach Zielbetriebssystem beschrieben:

InstallGPU-Aktion

Mit der Aktion InstallGPU können Sie VM-Images erstellen, die für Arbeitslasten in den Bereichen maschinelles Lernen, Data Science oder Wissenschaft optimiert sind. Image Builder lädt NVIDIA-GPU-Treiber herunter, kompiliert sie und registriert sie in Ihren benutzerdefinierten Images. Je nach Art des Basis-Images und der Zielhardware können Sie zwischen der Installation vorkompilierter Treiber und der Kompilierung benutzerdefinierter Treiberdateien .run wählen.

Geben Sie unter steps.inputs einen der folgenden Werte an:

• version (String): Die Zielversionsnummer des NVIDIA-Treibers, z. B. "595.129.03". Wenn Sie nur version angeben, lädt der Orchestrator den Treiber aus dem offiziellen NVIDIA-Repository (https://us.download.nvidia.com/tesla/<version>) herunter.
• gcsRunfile (String): Der Cloud Storage-Pfad einer benutzerdefinierten NVIDIA-Treiberinstallationsdatei, die das Format gs://BUCKET_NAME/OBJECT_NAME.run haben muss.
• sourceRunfile (String): Der relative Pfad zu einer .run-Installationsdatei im lokalen Arbeitsbereichs-Repository-Ordner.

Beispielkonfigurationen

Auf den folgenden Tabs finden Sie Beispielkonfigurationen für die Installation einer bestimmten vorab verpackten Treiberversion im Vergleich zur Installation einer benutzerdefinierten Runfile-Datei:

- 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"

Konfigurationsmethoden

Auf den folgenden Tabs werden die unterstützten Methoden zum Konfigurieren von NVIDIA-GPU-Treibern auf Ihren benutzerdefinierten Images beschrieben:

Nächste Schritte

• Sehen Sie sich die Schemablöcke der obersten Ebene im Schema der Datei zur Anpassung von Bildern an.
• Konfigurieren Sie die Parameter für die Pipeline-Orchestrierung im Cloud Build-Konfigurationsdateischema.
• Folgen Sie der Anleitung unter Image Builder-Pipeline erstellen.