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 bestimmte Hilfsaktionen im Block spec.steps 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, eine 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 auf dem Gastbetriebssystem des Workers aus.
  • UpdateKernelCommandLine: Ändert Bootparameter und Befehlszeilen-Flags des Kernels.
  • FileCopy: Überträgt Konfigurationsdateien, Skripts oder Assets aus Cloud Storage oder lokalen Arbeitsbereichen auf die VM.
  • InstallGPU: Lädt NVIDIA-GPU-Treiber herunter, kompiliert sie und registriert sie.

Shell-Aktion

Mit der Aktion Shell können Sie Inline-Terminalskripts oder einzelne Shell-Befehle auf dem Gastbetriebssystem der temporären Worker-VM ausführen, um Anpassungen vorzunehmen, z. B. Pakete zu aktualisieren, Nutzerkonten zu konfigurieren oder Software zu kompilieren.

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

  • inlineScript (String): Roh-Shell-Befehle mit mehreren Zeilen, die ausgeführt werden sollen.
  • command (String): Eine einzelne Systembefehlszeile oder ein 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-Skript ausführen

Die folgende Konfiguration führt ein mehrzeiliges Skript aus, 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

Die folgende Konfiguration führt einen einzelnen Shell-Befehl aus, um die aktive Betriebssystem-Kernel-Version zu prüfen:

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

Besonderes Verhalten

Wenn Sie Shell-Aktionen ausführen, verwaltet der Anpassungsbereitsteller die Sicherheitsprü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 Anpassungsbereitsteller die Rohzeilen Ihrer Skripts nur aus, wenn das interaktive Debugging aktiviert ist (debug: true). Stattdessen protokolliert er den SHA-256-Integritätshash Ihrer Skriptnutzlast in den Build-Logs. Dieser Hash bietet einen unveränderlichen Audit-Trail, der genau zeigt, welcher Code auf dem Image ausgeführt wurde.

Systemneustarts (Exit-Code 3010)

Für einige Shell-Aktionen, z. B. Kernel-Patch-Updates oder Anpassungen der Speicherpartition, ist ein Systemneustart 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 Neustartzyklus so gehandhabt:

  1. Der Bereitsteller erkennt den Exit-Code 3010, pausiert die Ausführung und markiert den Index des Schrittfortschritts.
  2. Der Bereitsteller startet die Worker-VM neu.
  3. Nach dem Neustart der VM stellt der Bereitsteller den Arbeitsbereich bereit und setzt die Pipeline automatisch mit dem nächsten Schritt in der Warteschlange fort.
Beispiel für einen 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 können Sie Befehlszeilen-Flags suchen, ersetzen, einfügen oder entfernen, die beim Systemstart an den Kernel übergeben werden, z. B. wenn Sie Konsolenlogs konfigurieren oder Kernelparameter anpassen.

Geben Sie die folgenden Attribute in der Map steps.inputs an:

  • oldArguments (String, erforderlich): Die genauen Befehlszeilenargumente, die in der Bootloader-Konfiguration gesucht, entfernt oder ersetzt werden sollen.
  • newArguments (String, optional): Die Ersatzargumente, 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:

Bootargumente ersetzen

Die folgende Konfiguration sucht den Kernel-Logebenen-Schlüssel loglevel=4 und ersetzt ihn durch ausführlichere Parameter loglevel=6 console=ttyS0:

- 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 Bootargumenten, um während der Startprüfungsphasen eine ausführliche Protokollierung zu aktivieren:

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

Betriebssystemspezifische Ausführungsdetails

Auf den folgenden Tabs wird beschrieben, wie der Anpassungsbereitsteller Image-Änderungen je nach Quellgastbetriebssystem verarbeitet:

Container-Optimized OS (COS)

Da COS ein schreibgeschütztes Partitionsschema verwendet, werden keine Standardkonfigurationstools verwendet. Der Anpassungsbereitsteller führt folgende Schritte aus:

  1. Er bestimmt den aktiven Bootgerätpfad.
  2. Er stellt Partition 12, die EFI-Partition, des Bootgeräts bereit.
  3. Er aktualisiert die Bootloader-Parameter direkt in /efi/boot/grub.cfg.
  4. Er hebt die Bereitstellung von Partition 12 sicher auf.

Ubuntu

Bei Ubuntu-Images führt der Anpassungsbereitsteller folgende Schritte aus:

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

Aktion „FileCopy“

Mit der Aktion FileCopy können Sie Konfigurationsdateien, Binärdateien oder Zertifikate aus einem Remote-Bucket oder Ihrem lokalen Repository in Ihr benutzerdefiniertes Image kopieren. Der Anpassungsbereitsteller lädt die Quelldatei herunter oder liest sie, schreibt sie in den 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 Oktaldarstellung der Ziel konfigurationsberechtigungen, z. B. "0755" oder "0644".
  • Geben Sie eine der folgenden Quelleigenschaften an:
    • gcsSourcePath (String): Der Cloud Storage-URI der Quelldatei, die das Format gs://BUCKET_NAME/OBJECT_NAME haben muss.
    • localSourcePath (String): Der relative Pfad zur Datei im Ordner des lokalen Arbeitsbereichs-Repositorys. Path Traversal mit ../ ist aus Sicherheitsgründen blockiert.

Beispielkonfigurationen

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

Cloud Storage

Die folgende Konfiguration kopiert eine Konfigurationsvorlage aus einem Cloud Storage-Bucket in das Gast-VM-Image:

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

Lokaler Arbeitsbereich

Die folgende Konfiguration kopiert ein Anwendungsskript, 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 finden Sie Richtlinien für den Speicherort von Dateien je nach Zielgastbetriebssystem:

Container-Optimized OS (COS)

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

Beim Konfigurieren von Dateizielen unter COS gilt Folgendes:

Ubuntu

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

Aktion „InstallGPU“

Mit der Aktion InstallGPU können Sie VM-Images erstellen, die für maschinelles Lernen, 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 Basistyp des Images und Zielhardware können Sie vorkompilierte Treiber installieren oder benutzerdefinierte .run-Treiberdateien kompilieren.

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-Treiber installationsdatei, die das Format gs://BUCKET_NAME/OBJECT_NAME.run haben muss.
  • sourceRunfile (String): Der relative Pfad zu einer Installationsdatei .run im Ordner des lokalen Arbeitsbereichs-Repositorys.

Beispielkonfigurationen

Auf den folgenden Tabs finden Sie Beispielkonfigurationen für Schritte zum Installieren einer bestimmten vorkonfigurierten Treiberversion im Vergleich zum Installieren einer benutzerdefinierten ausführbaren Datei:

Download der Standardversion

Die folgende Konfiguration lädt eine bestimmte NVIDIA-Treiber Version aus dem offiziellen Repository herunter und installiert sie:

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

Ausführbare Datei in Cloud Storage

Die folgende Konfiguration stellt ein benutzerdefiniertes NVIDIA-Treiberinstallationsprogramm .run direkt aus einem Cloud Storage-Bucket bereit:

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

Ausführbare Datei im lokalen Arbeitsbereich

Die folgende Konfiguration stellt ein benutzerdefiniertes NVIDIA-Treiberinstallationsprogramm .run aus Ihrem lokalen Repository-Arbeitsbereich bereit:

- 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 in Ihren benutzerdefinierten Images beschrieben:

Vorkompilierte Treiber

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

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

    Die Liste der unterstützten vorkompilierten Treiberversionen für Ihren COS-Release finden Sie unter GPU-Treiberversion ermitteln oder indem Sie sudo cos-extensions list auf einer aktiven COS-Instanz ausführen.

  • 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 CLI aus, um die verfügbaren Beschleuniger-Images aufzulisten:

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

Benutzerdefinierte ausführbare Dateien

Wenn Sie eine benutzerdefinierte Treiberversion installieren müssen, die nicht von Google oder Canonical vorkompiliert wurde, können Sie direkte ausführbare Installationsdateien für die Kompilierung angeben:

  • Ubuntu: Führt die Kompilierung im Gastbetriebssystem aus. Der Anpassungsbereitsteller installiert automatisch die passenden Kernel-Header (linux-headers-$(uname -r)), kompiliert die .run-Datei des NVIDIA-Treibers auf der Worker-VM und registriert sie mit 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 Ihres Quellbasis-VM-Images:
    • ARM64-Images: Da ARM64-COS-VMs die Header-Kompilierung im Gastbetriebssystem nicht unterstützen, führt Image Builder automatisch eine Cross-Kompilierung Ihres benutzerdefinierten Treibers .run Dienstprogramms im Build-Container durch und installiert das resultierende Bundle in /var/lib/nvidia auf der Worker-VM.
    • x86-64 Images: Führt die Kompilierung im Gastbetriebssystem direkt auf der Worker-VM aus.

Nächste Schritte