Datei für die Bildanpassung

In diesem Dokument werden die Struktur und die Parameter der Anpassungsrezeptdatei imagebuilder.yaml beschrieben, mit der Sie das Basisbetriebssystem-Image, die Hardwarekonfigurationen, die Release-Ziele und die Anpassungsaktionen für Ihre Image Builder-Pipeline definieren.

Schemaübersicht

Für die Anpassungskonfiguration wird die API-Version imagebuilder.gcp.com/v1 und die Ressourcenart OSImageCustomization verwendet.

Eine Standardrezeptdatei hat folgende Struktur:

apiVersion: imagebuilder.gcp.com/v1
kind: OSImageCustomization
metadata:
  # Recipe metadata and identifying details
infrastructureConfig:
  # VM machine type, zone, and network settings
source:
  # Base source image profile
destinations:
  # Output OS image release targets
spec:
  config:
    # Build options and validation test flags
  steps:
    # Customization actions (Shell, FileCopy, UpdateKernelCommandLine, InstallGPU)

Metadaten

Enthält identifizierende Details für diese benutzerdefinierte Build-Vorlage:

metadata:
  name: CONFIG_NAME
  description: DESCRIPTION
  • name (String, erforderlich): Die ID für diese Konfiguration.
  • description (String, optional): Eine Beschreibung des Zwecks des Builds.

Infrastrukturkonfiguration

Gibt die Hardware- und Netzwerkeigenschaften der temporären VM-Instanzen an, die Image Builder während der Build- und Validierungsaufgaben erstellt:

infrastructureConfig:
  machineType: MACHINE_TYPE
  zone: ZONE
  network: projects/PROJECT_ID/global/networks/NETWORK_NAME
  subnetwork: projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME
  externalIP: ephemeral
  acceleratorType: nvidia-l4
  acceleratorCount: 1
  debug: false
  instanceDurationHours: 2.0
  reservations:
    - RESERVATION_NAME
  • machineType (String, erforderlich): Der Compute Engine-Maschinentyp, der für die Worker- und Test-VMs verwendet werden soll. Achten Sie darauf, dass der Maschinentyp mit der Architektur des Quell-Images übereinstimmt, das Sie in imageFamily oder imagePath angeben. Verwenden Sie beispielsweise e2-standard-4 für x86-Images und c4a-standard-4 für Arm-Images. Bare-Metal-Maschinentypen werden nicht unterstützt.
  • zone (String, erforderlich): Die Zone, in der die Worker- und Test-VMs ausgeführt werden, z. B. us-central1-a.
  • network (String, optional): Das VPC-Netzwerk, das an die Worker- und Validierungstest-VMs angehängt werden soll, z. B. projects/<var>PROJECT_ID</var>/global/networks/<var>NETWORK_NAME</var> oder default. Wenn nichts angegeben ist, verwendet Image Builder das Standardnetzwerk.
  • subnetwork (String, optional): Das VPC-Subnetzwerk, das an die Worker- und Validierungstest-VMs angehängt werden soll, z. B. projects/<var>PROJECT_ID</var>/regions/<var>REGION</var>/subnetworks/<var>SUBNET_NAME</var>.
  • externalIP (String, optional): Gibt die Zuweisung der externen IP-Adresse für die Worker- und Validierungstest-VMs an. Zulässige Werte:
    • ephemeral (Standard): Weist eine öffentliche sitzungsspezifische IPv4-Adresse aus einem freigegebenen Pool zu.
    • none: Erstellt VMs ohne externe IP-Adresse, die nur das private VPC-Netzwerk verwenden. Wenn none festgelegt ist, muss für Ihr VPC-Subnetzwerk der privater Google-Zugriff oder Cloud NAT aktiviert sein, damit die VMs auf erforderliche Google Cloud Dienste und Paket Repositories zugreifen können.
  • acceleratorType (String, optional): Der GPU-Beschleunigertyp, der an die Worker-VM angehängt werden soll, z. B. nvidia-tesla-t4 oder nvidia-l4.
  • acceleratorCount (Zahl, optional): Die Anzahl der GPU-Beschleuniger, die an die Worker-VM angehängt werden sollen.
  • debug (boolesch, optional): Wenn Sie debug auf true setzen, behält Image Builder die Worker-VM bei, unabhängig davon, ob die Anpassung abgeschlossen wird oder fehlschlägt. So können Sie die aktive Instanz mit SSH untersuchen oder Fehler beheben. Die Standardeinstellung ist false.
  • instanceDurationHours (Zahl, optional): Beschränkt die Laufzeit der Worker-VM. Die Zeitbegrenzung beginnt, wenn die Anpassung abgeschlossen ist oder ein Skriptfehler auftritt. So können Sie sich während interaktiver Debugging-Sitzungen mit der aktiven VM verbinden. Die maximale Laufzeit beträgt 2.0 Stunden.
  • reservations (Array aus Strings, optional): Namen von Kapazitätsreservierungsressourcen (z. B. test-reservation im selben Projekt), die verwendet werden sollen, wenn Image Builder VMs erstellt.

Quell-Image

Gibt das Basisbetriebssystem-Image an, das Image Builder zum Starten der Worker-VM verwendet. Sie müssen eine der folgenden Optionen angeben:

So geben Sie eine Standard-Image-Familie an:

source:
  imageFamily: projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY

So geben Sie einen direkten URI für die Image-Version an:

source:
  imagePath: projects/IMAGE_PROJECT/global/images/IMAGE_NAME
  • imageFamily (String): Der Pfad zu einer Standard-Image-Familiengruppe, z. B. projects/ubuntu-os-cloud/global/images/family/ubuntu-2204-lts.
  • imagePath (String): Der direkte Ressourcen-URI zu einer bestimmten Compute Engine-Image-Version, z. B. projects/cos-cloud/global/images/cos-105-17412-226-28.

Ziele

Definiert, wo und wie das kompilierte benutzerdefinierte Betriebssystem-Image freigegeben werden soll. Diese Eigenschaft enthält eine Liste von Objekten für Release-Ziele unter diskImage:

destinations:
  - diskImage:
      name: IMAGE_NAME
      project: PROJECT_ID
      family: IMAGE_FAMILY
      description: DESCRIPTION
      licenses:
        - projects/PROJECT_ID/global/licenses/LICENSE_NAME
      labels:
        env: production
      signatureDatabaseFile: SIGNATURE_DB_PATH
      storageLocations:
        - us-central1
  • name (String, erforderlich): Das Basisnamenspräfix, das der endgültigen Compute Engine-Image-Ressource zugewiesen wird. Image Builder hängt automatisch die eindeutige Build-ID an dieses Präfix an und kürzt den endgültigen Imagenamen auf 63 Zeichen.
  • family (String, optional): Die Image-Familie, die auf das neu generierte Image angewendet werden soll.
  • project (String, erforderlich): Das Google Cloud Projekt, in dem Image Builder das Ausgabebild schreibt.
  • description (String, optional): Beschreibungstext, der an die generierten Image-Metadaten angehängt wird.
  • licenses (Array aus Strings, optional): Ressourcenpfade bestimmter Softwarelizenzen, die auf dieses Image angewendet werden.
  • labels (Map, optional): Schlüssel/Wert-Paare für Tagging-Metadaten, z. B. env: production.
  • signatureDatabaseFile (String, optional): Ressourcenpfad zu einer Signaturdatenbankdatei für den sicheren Start.
  • storageLocations (Array aus Strings, optional): Zielspeicherregion oder ‑multiregion, z. B. us-central1 oder us, in der Compute Engine die endgültigen Festplattenblöcke speichert. Hinweis: Obwohl diese Eigenschaft als Liste formatiert ist, können Sie nur einen einzelnen Speicherort pro Image-Ziel angeben.

Spezifikationskonfiguration

Wendet allgemeine Ausführungsoptionen an:

spec:
  config:
    skipSystemTests: false
  • skipSystemTests (boolesch, optional): Legt fest, ob die Test-VM Startbedingungen, Netzwerk und UEFI-Strukturen auswertet. Die Standardeinstellung ist false.

Spezifikationsschritte

Gibt eine Liste von Schrittobjekten an, die Image Builder in der angegebenen Reihenfolge auf der Worker-VM ausführt. Vollständige Schemas für Eingabeparameter und Anwendungsbeispiele für jeden Schritt typ finden Sie unter Unterstützte Anpassungsaktionen.

Alle Objekte für Anpassungsschritte haben die folgenden gemeinsamen Eigenschaften:

spec:
  steps:
    - name: STEP_NAME
      action: ACTION_TYPE
      inputs:
        # Action-specific input parameters
  • name (String, erforderlich): Der benutzerdefinierte Name für diesen Anpassungsschritt.
  • action (String, erforderlich): Die Hilfsaktion, die aufgerufen werden soll. Unterstützte Aktionen:
  • inputs (Objekt, erforderlich): Die Schlüssel/Wert-Eigenschaften, die für die ausgewählte Aktion erforderlich sind. Vollständige Parameterreferenzen und Beispiele finden Sie unter Unterstützte Anpassungsaktionen.

Das folgende Snippet zeigt einen Beispielschritt mit der Aktion Shell:

spec:
  steps:
    - name: setup-environment
      action: Shell
      inputs:
        inlineScript: |
          #!/usr/bin/env bash
          echo "Running customization..."

Nächste Schritte