Archivo de personalización de imágenes

En este documento, se describen la estructura y los parámetros del archivo de receta de personalización, imagebuilder.yaml, que usas para definir la imagen base del SO, las configuraciones de hardware, los destinos de lanzamiento y las acciones de personalización para tu canalización de Image Builder.

Descripción general del esquema

La configuración de personalización usa la versión de la API imagebuilder.gcp.com/v1 y el tipo de recurso OSImageCustomization.

Un archivo de receta estándar tiene la siguiente estructura:

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)

Metadatos

Proporciona detalles de identificación para esta plantilla de compilación personalizada:

metadata:
  name: CONFIG_NAME
  description: DESCRIPTION
  • name (cadena, obligatorio): Es el identificador de esta configuración.
  • description (cadena, opcional): Es una descripción del propósito de la compilación.

Configuración de la infraestructura

Especifica las propiedades de hardware y de red de las instancias de máquina virtual temporales que Image Builder crea durante las tareas de compilación y validación:

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 (cadena, obligatorio): Es el tipo de máquina de Compute Engine que se usará para las VMs de trabajador y de prueba. Asegúrate de que el tipo de máquina coincida con la arquitectura de la imagen de origen que especificas en imageFamily o imagePath. Por ejemplo, usa e2-standard-4 para imágenes x86 y c4a-standard-4 para imágenes Arm. No se admiten los tipos de máquinas sin sistema operativo.
  • zone (cadena, obligatorio): Es la zona en la que se ejecutan las VMs de trabajador y de prueba, como us-central1-a.
  • network (cadena, opcional): Es la red de VPC que se conectará a las VMs de trabajador y de prueba de validación, como projects/<var>PROJECT_ID</var>/global/networks/<var>NETWORK_NAME</var> o default. Si se omite, Image Builder usa la red predeterminada.
  • subnetwork (cadena, opcional): Es la subred de VPC que se conectará a las VMs de trabajador y de prueba de validación, como projects/<var>PROJECT_ID</var>/regions/<var>REGION</var>/subnetworks/<var>SUBNET_NAME</var>.
  • externalIP (cadena, opcional): Especifica la asignación de direcciones IP externas para las VMs de trabajador y de prueba de validación. Valores permitidos:
    • ephemeral (predeterminado): Asigna una dirección IPv4 pública efímera de un grupo compartido.
    • none: Crea VMs sin dirección IP externa, que solo usa redes de VPC privadas. Cuando se establece en none, asegúrate de que tu subred de VPC tenga habilitado el Acceso privado a Google o Cloud NAT para que las VMs puedan acceder a los servicios y repositorios de paquetes requeridos Google Cloud .
  • acceleratorType (cadena, opcional): Es el tipo de acelerador de GPU que se conectará a la VM de trabajador, como nvidia-tesla-t4 o nvidia-l4.
  • acceleratorCount (número, opcional): Es la cantidad de aceleradores de GPU que se conectarán a la VM de trabajador.
  • debug (booleano, opcional): Si estableces debug en true, Image Builder conserva la VM de trabajador, ya sea que la personalización se complete o falle, para que puedas inspeccionar o solucionar problemas de la instancia activa con SSH. El valor predeterminado es false.
  • instanceDurationHours (número, opcional): Limita el tiempo de ejecución de la VM de trabajador. El límite de tiempo comienza cuando se completa la personalización o se produce un error de secuencia de comandos, lo que te permite conectarte a la VM activa durante las sesiones de depuración interactivas. El límite máximo es de 2.0 horas.
  • reservations (array de cadenas, opcional): Son los nombres de los recursos de reserva de capacidad (como test-reservation en el mismo proyecto) que se consumirán cuando Image Builder cree VMs.

Imagen de origen

Identifica la imagen del sistema operativo base que Image Builder usa para iniciar la VM de trabajador. Debes especificar una de las siguientes opciones:

Para especificar una familia de imágenes estándar:

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

Para especificar un URI de versión de imagen directa:

source:
  imagePath: projects/IMAGE_PROJECT/global/images/IMAGE_NAME
  • imageFamily (cadena): Es la ruta de acceso a un grupo familiar de imágenes estándar, como projects/ubuntu-os-cloud/global/images/family/ubuntu-2204-lts.
  • imagePath (cadena): Es el URI de recurso directo a una versión específica de la imagen de Compute Engine, como projects/cos-cloud/global/images/cos-105-17412-226-28.

Destinos

Define dónde y cómo lanzar la imagen personalizada compilada del SO. Esta propiedad contiene una lista de objetos de destino de lanzamiento en 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 (cadena, obligatorio): Es el prefijo del nombre base asignado al recurso de imagen final de Compute Engine. Image Builder agrega automáticamente el ID de compilación único a este prefijo y trunca el nombre de la imagen final a 63 caracteres.
  • family (cadena, opcional): Es la familia de imágenes que se aplicará a la imagen recién generada.
  • project (cadena, obligatorio): Es el Google Cloud proyecto en el que Image Builder escribe la imagen de salida.
  • description (cadena, opcional): Es el texto de descripción adjunto a los metadatos de la imagen generada.
  • licenses (array de cadenas, opcional): Son las rutas de acceso de recursos de licencias de software específicas que se aplican a esta imagen.
  • labels (mapa, opcional): Son los pares clave-valor de metadatos de etiquetado, como env: production.
  • signatureDatabaseFile (cadena, opcional): Es la ruta de acceso de recursos a un archivo de base de datos de firma de arranque seguro.
  • storageLocations (array de cadenas, opcional): Es la región o multirregión de almacenamiento de destino, como us-central1 o us, en la que Compute Engine almacena los bloques de disco finales. Nota: Aunque esta propiedad tiene el formato de una lista, solo puedes especificar una ubicación por destino de imagen.

Configuración de especificación

Aplica opciones de ejecución generales:

spec:
  config:
    skipSystemTests: false
  • skipSystemTests (booleano, opcional): Activa o desactiva si la VM de prueba evalúa las condiciones de arranque, las redes y las estructuras UEFI. El valor predeterminado es false.

Pasos de especificación

Especifica una lista de objetos de paso que Image Builder ejecuta en orden en la VM de trabajador. Para obtener esquemas de parámetros de entrada completos y ejemplos de uso para cada tipo de paso, consulta Acciones de personalización compatibles.

Todos los objetos de paso de personalización comparten las siguientes propiedades comunes:

spec:
  steps:
    - name: STEP_NAME
      action: ACTION_TYPE
      inputs:
        # Action-specific input parameters
  • name (cadena, obligatorio): Es el nombre definido por el usuario para este paso de personalización.
  • action (cadena, obligatorio): Es la acción auxiliar que se invocará. Acciones compatibles:
    • Shell: Ejecuta secuencias de comandos de la terminal en la VM.
    • FileCopy: Transfiere recursos desde buckets o espacios de trabajo de Cloud Storage.
    • UpdateKernelCommandLine: Actualiza los parámetros de arranque.
    • InstallGPU: Registra los controladores de GPU de NVIDIA.
  • inputs (objeto, obligatorio): Son las propiedades par clave-valor que requiere la acción seleccionada. Para obtener referencias y ejemplos de parámetros completos, consulta Acciones de personalización compatibles.

En el siguiente fragmento, se muestra un paso de ejemplo con la acción Shell:

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

¿Qué sigue?