Unterstützte Anpassungsaktionen

Wenn Sie Ihre VM-Images anpassen möchten, z. B. durch Ausführen von Terminalskripts, Aktualisieren von Startparametern, Übertragen von Binärdateien oder Installieren von GPU-Treibern, können Sie bestimmte Hilfsaktionen im spec.steps-Block Ihres Anpassungsrezepts (imagebuilder.yaml) 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-Terminal-Scripts 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:

Inline-Script ausführen

Mit der folgenden Konfiguration wird ein mehrzeiliges Script ausgeführt, das Pakete mit apt aktualisiert:

- 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

Einzelnen Befehl ausführen

Bei der folgenden Konfiguration wird ein einzelner Shell-Befehl ausgeführt, um die aktive Betriebssystem-Kernelversion zu prüfen:

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

Besonderheiten

Wenn Sie Shell-Aktionen ausführen, übernimmt der Anpassungsbereitsteller die Sicherheitsprüfung und die automatischen 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). Andernfalls wird der SHA‑256-Integritätshash Ihrer Skript-Nutzlast in den Build-Protokollen protokolliert. Dieser Hash bietet einen unveränderlichen Audit-Trail, der genau angibt, welcher Code auf dem 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 Anpassungs-Provisioner 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 der Eigenschaft 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-Bootargumenten:

Boot-Argumente ersetzen

In der folgenden Konfiguration wird der Schlüssel für die Kernel-Logebene loglevel=4 gesucht und durch die ausführlicheren Parameter loglevel=6 console=ttyS0 ersetzt:

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

Bootargumente entfernen

Die folgende Konfiguration sucht nach dem Parameter quiet und entfernt ihn aus den Boot-Argumenten, um während der Startprüfungsphasen ausführliches Logging zu aktivieren:

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

Container-Optimized OS (COS)

Da COS ein schreibgeschütztes Partitionslayout hat, sind keine Standardkonfigurationstools enthalten. Der Bereitsteller für die Anpassung führt folgende Schritte aus:

  1. Bestimmt den Pfad des aktiven Bootgeräts.
  2. Hängt Partition 12, die EFI-Partition, des Bootgeräts ein.
  3. Aktualisiert Bootloader-Parameter direkt in /efi/boot/grub.cfg.
  4. Hebt die Bereitstellung von Partition 12 sicher auf.

Ubuntu

Auf Ubuntu-Images führt der Anpassungs-Provisioner folgende Aktionen aus:

  1. Öffnet /etc/default/grub und Dateien unter /etc/default/grub.d/*.cfg.
  2. Fügt die Zielargumente unter dem Block GRUB_CMDLINE_LINUX ein, ändert oder löscht sie.
  3. Führt den Paketbefehl update-grub aus, um die Bootloader-Konfigurationen neu zu generieren.

FileCopy-Aktion

Mit der FileCopy-Aktion 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 unter steps.inputs die folgenden Eingaben 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 Quellattribute 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 mit ../ ist 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:

Cloud Storage

Mit der folgenden Konfiguration wird eine Konfigurationsvorlage aus einem Cloud Storage-Bucket in das Gast-VM-Image kopiert:

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

Lokaler Arbeitsbereich

Mit der folgenden Konfiguration wird ein Anwendungsskript kopiert, das in vorherigen Cloud Build-Schritten kompiliert wurde:

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

Container-Optimized OS (COS)

COS-Images enthalten aus Sicherheitsgründen ein schreibgeschütztes Partitionslayout. Einige Standard-Systemziele wie /usr/ oder /bin/ sind schreibgeschützt.

Beim Konfigurieren von Dateizielen in COS gilt Folgendes:

Ubuntu

Ubuntu-Images haben ein standardmäßiges Linux-Layout für die Root-Partition mit Lese-/Schreibzugriff (/). Sie können Dateiziele in einem beliebigen Standardsystempfad angeben, z. B. /etc, /usr/local/bin, /var oder /home, sofern das Nutzerprofil oder der Zielordner die entsprechenden Konfigurationsberechtigungen auf der Worker-VM hat.

InstallGPU-Aktion

Mit der Aktion InstallGPU können Sie VM-Images erstellen, die für ML-, Data-Science- oder wissenschaftliche Arbeitslasten 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 dem Kompilieren benutzerdefinierter .run-Treiberdateien wählen.

Geben Sie unter steps.inputs eine der folgenden Eingaben 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 Schritte zum Installieren einer bestimmten vorab verpackten Treiberversion im Vergleich zur Installation einer benutzerdefinierten Runfile:

Standardversion herunterladen

Mit der folgenden Konfiguration wird eine bestimmte NVIDIA-Treiberversion aus dem offiziellen Repository heruntergeladen und installiert:

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

Cloud Storage-Laufzeitdatei

Bei der folgenden Konfiguration wird ein benutzerdefiniertes NVIDIA-Treiberinstallationsprogramm .run direkt aus einem Cloud Storage-Bucket bereitgestellt:

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

Lokale Runfile des Arbeitsbereichs

Bei der folgenden Konfiguration wird ein benutzerdefiniertes NVIDIA-Treiberinstallationsprogramm .run aus Ihrem lokalen Repository-Arbeitsbereich bereitgestellt:

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

Vorkompilierte Treiber

Wir empfehlen die Verwendung vorgefertigter Treiberversionen, um den Rechenaufwand und die Build-Zeit für das Kompilieren von Treibern von Grund auf zu vermeiden.

  • Container-Optimized OS (COS): Wenn Sie eine von Google vorab verpackte Treiberversion angeben, führt der Anpassungs-Provisioner das Gasttool cos-extensions install gpu aus, um es zu aktivieren.

    Eine Liste der unterstützten vorkompilierten Treiberversionen für Ihr COS-Release finden Sie, indem Sie sudo cos-extensions list auf einer laufenden COS-Instanz ausführen oder GPU-Treiberversion ermitteln aufrufen.

  • Ubuntu: Um die Build-Zeit unter Ubuntu zu verkürzen, empfehlen wir, vorkonfigurierte Basis-Images aus dem öffentlichen ubuntu-os-accelerator-images-Projekt auszuwählen, in dem NVIDIA-Treiber vorinstalliert sind.

    Führen Sie den folgenden Befehl in der gcloud-Befehlszeile aus, um verfügbare Beschleuniger-Images aufzulisten:

    gcloud compute images list \
    --project=ubuntu-os-accelerator-images \
    --no-standard-images

Benutzerdefinierte Ausführungsdateien

Wenn Sie eine benutzerdefinierte Treiberversion installieren müssen, die nicht von Google oder Canonical vorkompiliert wurde, können Sie die direkten Installer-Ausführungsdateien für die Kompilierung so angeben:

  • Ubuntu: Führt die In-Guest-Kompilierung durch. Der Anpassungs-Bereitsteller installiert automatisch die passenden Kernel-Header (linux-headers-$(uname -r)), kompiliert die NVIDIA-Treiberdatei .run auf der Worker-VM und registriert sie bei Dynamic Kernel Module Support (DKMS). Durch die Registrierung bei DKMS bleiben die Treiber auch bei kleineren Kernel-Updates aktiv.
  • Container-Optimized OS (COS): Das Kompilierungsverhalten variiert je nach CPU-Architektur des Quell-VM-Basis-Images:
    • ARM64-Images: Da ARM64-COS-VMs die In-Guest-Header-Kompilierung nicht unterstützen, führt Image Builder automatisch eine Cross-Kompilierung des .run-Dienstprogramms für benutzerdefinierte Treiber im Build-Container durch und installiert das resultierende Bundle in /var/lib/nvidia auf der Worker-VM.
    • x86-64-Images: Die In-Guest-Kompilierung erfolgt direkt auf der Worker-VM.

Nächste Schritte