Archivo de personalización de imágenes

En este documento, se describen la estructura y los parámetros del archivo de recetas de personalización, imagebuilder.yaml, que usas para definir la imagen de SO base, 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
  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

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: ACCELERATOR_TYPE
  acceleratorCount: ACCELERATOR_COUNT
  debug: DEBUG_BOOLEAN
  instanceDurationHours: DURATION_HOURS
  reservations:
    - RESERVATION_NAME
  validationConcurrency: VALIDATION_CONCURRENCY
  • 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 de metal desnudo.
  • 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 a la que se adjuntarán 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 adjuntará 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 desde un grupo compartido.
    • none: Crea VMs sin dirección IP externa, que solo usan 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 Cloud de Confiance y a los repositorios de paquetes necesarios.
  • 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 deben conectar a la VM de trabajador.
  • debug (booleano, opcional): Si configuras debug como true, Image Builder conserva la VM de trabajador, ya sea que se complete o falle la personalización, para que puedas inspeccionar o solucionar problemas de la instancia activa con SSH. La configuración predeterminada es false.
  • instanceDurationHours (número, opcional): Limita el tiempo de ejecución de la VM de trabajador. El límite de tiempo comienza cuando finaliza 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. Se limita a un máximo de 2.0 horas.
  • reservations (array de cadenas, opcional): Nombres de recursos de reserva de capacidad (como test-reservation en el mismo proyecto) para consumir cuando Image Builder crea VMs.
  • validationConcurrency (número, opcional): Especifica la cantidad máxima de pruebas de validación que se ejecutarán en paralelo en la instancia de procesamiento temporal de pruebas de validación. Los valores permitidos incluyen los siguientes:
    • 0 o se omite (predeterminado): Image Builder detecta automáticamente la simultaneidad según el tipo de máquina y la configuración del acelerador, y la establece de la siguiente manera:
      • 1 (secuencial) para los tipos de máquinas o las configuraciones de metal desnudo con aceleradores de GPU adjuntos, lo que ayuda a evitar que se excedan los límites de cuota o se agoten los recursos
      • 4 (paralelo) para todos los demás tipos de máquinas.
    • 1: Ejecuta pruebas de validación de forma secuencial. Si tu proyecto tiene una cuota limitada para el machineType especificado, establecer la simultaneidad en 1 puede ser útil porque evita que se inicien varias instancias de procesamiento al mismo tiempo.
    • 2 o superior: Ejecuta la cantidad especificada de pruebas de validación en paralelo. Si tienes capacidad o reservas suficientes, aumentar la simultaneidad puede reducir el tiempo total de ejecución de las pruebas de validación.

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, haz lo siguiente:

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

Para especificar un URI de versión de imagen directa, haz lo siguiente:

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 directo del recurso para 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 de SO personalizada compilada. 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:
        - STORAGE_LOCATION
  • 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 proyecto Cloud de Confiance 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 los recursos de licencias de software específicas que se aplican a esta imagen.
  • labels (map, opcional): Pares clave-valor de metadatos de etiquetado, como env: production.
  • signatureDatabaseFile (cadena, opcional): Es la ruta de acceso del recurso a un archivo de base de datos de firmas 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: Si bien esta propiedad tiene el formato de una lista, solo puedes especificar una ubicación por destino de la imagen.

Configuración de especificaciones

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 inicio, las redes y las estructuras de UEFI. La configuración predeterminada es false.

Pasos de especificación

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

Todos los objetos de pasos 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 de ayuda que se invocará. Acciones admitidas:
    • Shell: Ejecuta secuencias de comandos de terminal en la VM.
    • FileCopy: Transfiere recursos de buckets o espacios de trabajo de Cloud Storage.
    • UpdateKernelCommandLine: Actualiza los parámetros de arranque.
    • InstallGPU: Registra los controladores de la GPU de NVIDIA.
  • inputs (objeto, obligatorio): Son las propiedades de par clave-valor que requiere la acción seleccionada. Para obtener referencias y ejemplos completos de los parámetros, consulta Acciones de personalización admitidas.

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

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

¿Qué sigue?