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 Releaseziele 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 die folgende Struktur:

apiVersion: imagebuilder.gcp.com/v1
kind: OSImageCustomization
metadata:
  # Recipe metadata and identifying details
  name: CONFIG_NAME
  description: DESCRIPTION
infrastructureConfig:
  # VM machine type, zone, and network settings
  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: ACCELERATOR_TYPE
  acceleratorCount: ACCELERATOR_COUNT
  debug: DEBUG_BOOLEAN
  instanceDurationHours: DURATION_HOURS
  reservations:
    - RESERVATION_NAME
  validationConcurrency: VALIDATION_CONCURRENCY
source:
  # Base source image profile
  imageFamily: projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY
  # Alternatively, use a direct image version URI:
  # imagePath: projects/IMAGE_PROJECT/global/images/IMAGE_NAME
destinations:
  # Output OS image release targets
  - 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:
        - STORAGE_LOCATION
spec:
  config:
    # Build options and validation test flags
    skipSystemTests: false
  steps:
    # Customization actions (Shell, FileCopy, UpdateKernelCommandLine, InstallGPU)
    - name: STEP_NAME
      action: ACTION_TYPE
      inputs:
        # Action-specific input parameters

Metadaten

Hier finden Sie identifizierende Details für diese benutzerdefinierte Build-Vorlage:

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

Infrastrukturkonfiguration

Gibt die Hardware- und Netzwerkeigenschaften temporärer VM-Instanzen an, die Image Builder während 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: ACCELERATOR_TYPE
  acceleratorCount: ACCELERATOR_COUNT
  debug: DEBUG_BOOLEAN
  instanceDurationHours: DURATION_HOURS
  reservations:
    - RESERVATION_NAME
  validationConcurrency: VALIDATION_CONCURRENCY
  • machineType (string, erforderlich): Der Compute Engine-Maschinentyp, der für die Worker- und Test-VMs verwendet werden soll. Achten Sie darauf, dass der Maschinentyp der Architektur des Quell-Images entspricht, 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 externer IP-Adressen 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 private VPC-Netzwerke verwenden. Wenn der Wert auf none festgelegt ist, muss in Ihrem VPC-Subnetzwerk der privater Google-Zugriff oder Cloud NAT aktiviert sein, damit die VMs auf die erforderlichen Cloud de Confiance 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 festlegen, 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 über SSH untersuchen oder Fehler beheben. Die Standardeinstellung ist false.
  • instanceDurationHours (Zahl, optional): Beschränkt die Laufzeit der Worker-VM. Das Zeitlimit beginnt, wenn die Anpassung abgeschlossen ist oder ein Skriptfehler auftritt. So können Sie während interaktiver Debugging-Sitzungen eine Verbindung zur aktiven VM herstellen. Die maximale Dauer beträgt 2.0 Stunden.
  • reservations (Array von Strings, optional): Namen von Kapazitätsreservierungsressourcen (z. B. test-reservation im selben Projekt), die verwendet werden sollen, wenn Image Builder VMs erstellt.
  • validationConcurrency (Zahl, optional): Gibt die maximale Anzahl der Validierungstests an, die parallel auf der temporären Compute-Instanz für Validierungstests ausgeführt werden sollen. Zulässige Werte:
    • 0 oder ausgelassen (Standard): Image Builder erkennt die Parallelität automatisch anhand des Maschinentyps und der Beschleunigerkonfiguration und legt sie so fest:
      • 1 (sequenziell) für Bare-Metal-Maschinentypen oder Konfigurationen mit angehängten GPU-Beschleunigern, um eine Überschreitung von Kontingentlimits oder eine Erschöpfung von Ressourcen zu verhindern.
      • 4 (parallel) für alle anderen Maschinentypen.
    • 1: Führt Validierungstests sequenziell aus. Wenn Ihr Projekt ein begrenztes Kontingent für die angegebene machineType hat, kann es hilfreich sein, die Parallelität auf 1 festzulegen, da so verhindert wird, dass mehrere Compute-Instanzen gleichzeitig gestartet werden.
    • 2 oder höher: Führt die angegebene Anzahl von Validierungstests parallel aus. Wenn Sie über genügend Kapazität oder Reservierungen verfügen, kann die Gesamtausführungszeit für Validierungstests durch eine höhere Parallelität verkürzt werden.

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 für eine bestimmte 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 veröffentlicht wird. Diese Eigenschaft enthält eine Liste von Objekten für das Releaseziel 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:
        - STORAGE_LOCATION
  • name (String, erforderlich): Das Basisnamenspräfix, das der endgültigen Compute Engine-Bildressource zugewiesen wird. Image Builder hängt automatisch die eindeutige Build-ID an dieses Präfix an und kürzt den endgültigen Image-Namen auf 63 Zeichen.
  • family (String, optional): Die Image-Familie, die auf das neu generierte Bild angewendet werden soll.
  • project (String, erforderlich): Das Cloud de Confiance Projekt, in das Image Builder das Ausgabebild schreibt.
  • description (String, optional): Beschreibungstext, der an die generierten Bildmetadaten angehängt wird.
  • licenses (Array von 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 Datei mit einer Datenbank für Secure Boot-Signaturen.
  • storageLocations (Array von Strings, optional): Zielspeicherregion oder ‑regionen, z. B. us-central1 oder us, in denen Compute Engine die endgültigen Festplattenblöcke speichert. Hinweis: Obwohl dieses Attribut als Liste formatiert ist, können Sie nur einen Standort pro Bildziel angeben.

Spezifikationskonfiguration

Allgemeine Ausführungsoptionen anwenden:

spec:
  config:
    skipSystemTests: false
  • skipSystemTests (boolescher Wert, 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 Worker-VM in der angegebenen Reihenfolge ausführt. Vollständige Schemas für Eingabeparameter und Anwendungsbeispiele für die einzelnen Schritttypen finden Sie unter Unterstützte Anpassungsaktionen.

Alle Anpassungsschrittobjekte haben die folgenden gemeinsamen Eigenschaften:

spec:
  steps:
    - name: STEP_NAME
      action: ACTION_TYPE
      inputs:
        # Action-specific input parameters
  • name (String, erforderlich): Benutzerdefinierter Name für diesen Anpassungsschritt.
  • action (string, erforderlich): Die Helferaktion, die aufgerufen werden soll. Unterstützte Aktionen:
  • inputs (object, Required): Die Schlüssel/Wert-Eigenschaften, die für die ausgewählte Aktion erforderlich sind. Vollständige Parameterverweise 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