Acciones de personalización compatibles

Para personalizar las imágenes de tus máquina virtual, como ejecutar secuencias de comandos de terminal, actualizar parámetros de arranque, transferir archivos binarios o instalar controladores de GPU, puedes definir acciones auxiliares específicas dentro del bloque spec.steps de tu receta de personalización (imagebuilder.yaml).

Descripción general

Durante la fase de ejecución de una compilación de Image Builder, el orquestador ejecuta los pasos declarados en tu receta de personalización (spec.steps) de forma secuencial en la VM de trabajador temporal.

Cada paso debe especificar un bloque name, action y inputs adaptado a ese tipo de acción. Image Builder admite las siguientes acciones de personalización:

  • Shell: Ejecuta secuencias de comandos o comandos de terminal intercalados en el SO invitado del trabajador.
  • UpdateKernelCommandLine: Modifica los parámetros de arranque y las marcas de línea de comandos del kernel.
  • FileCopy: Transfiere archivos de configuración, secuencias de comandos o recursos de Cloud Storage o de espacios de trabajo locales a la VM.
  • InstallGPU: Descarga, compila y registra los controladores de GPU de NVIDIA.

Acción de shell

La acción Shell te permite ejecutar secuencias de comandos de terminal intercaladas o comandos de shell únicos en el SO invitado de la VM de trabajador temporal para realizar personalizaciones, como actualizar paquetes, configurar cuentas de usuario o compilar software.

Especifica cualquiera de las siguientes entradas en steps.inputs:

  • inlineScript (string): Comandos de shell sin procesar de varias líneas para ejecutar.
  • command (string): Una sola cadena de comandos del sistema o una ruta de acceso relativa a un archivo binario ejecutable.

Configuraciones de muestra

En las siguientes pestañas, se muestran configuraciones de pasos de muestra para ejecutar una secuencia de comandos intercalada en comparación con la ejecución de un solo comando:

Ejecuta una secuencia de comandos intercalada

La siguiente configuración ejecuta una secuencia de comandos de varias líneas que actualiza paquetes con apt:

- 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

Ejecuta un solo comando

La siguiente configuración ejecuta un solo comando de shell para verificar la versión de kernel activa del sistema operativo:

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

Comportamientos especiales

Cuando ejecutas acciones Shell, el aprovisionador de personalización administra las auditorías de seguridad y los reinicios automáticos del sistema como se describe en las siguientes secciones:

Auditorías de seguridad

Para evitar que los tokens sensibles, los secretos o el código propietario se filtren en los registros de ejecución, el aprovisionador de personalización no imprime las líneas sin procesar de tus secuencias de comandos, a menos que se habilite la depuración interactiva (debug: true). En su lugar, registra el hash de integridad SHA-256 de tu carga útil de secuencia de comandos en los registros de compilación. Este hash proporciona un seguimiento de auditoría inmutable de exactamente qué código se ejecutó en la imagen.

Reinicios del sistema (código de salida 3010)

Algunas acciones de shell, como las actualizaciones de parches del kernel o los ajustes de partición de almacenamiento, requieren un reinicio del sistema antes de que se puedan ejecutar los pasos posteriores.

Para solicitar un reinicio del sistema durante la personalización, tu secuencia de comandos de shell debe terminar con el comando exit 3010. Cuando el aprovisionador de personalización recibe el código de salida 3010, controla el ciclo de vida de reinicio de la siguiente manera:

  1. El aprovisionador detecta el código de salida 3010, pausa la ejecución y marca el índice de progreso del paso.
  2. El aprovisionador reinicia la VM de trabajador.
  3. Después de que se reinicia la VM, el aprovisionador activa el espacio de trabajo y reanuda automáticamente la canalización en el siguiente paso de la cola.
Ejemplo de reinicio:

En el siguiente ejemplo, se muestra una configuración de paso que actualiza paquetes y solicita un reinicio:

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

Acción de UpdateKernelCommandLine

La acción UpdateKernelCommandLine ubica, reemplaza, inserta o quita las marcas de línea de comandos que se pasan al kernel en el arranque del sistema, como cuando configuras registros de consola o ajustas los parámetros del kernel.

Especifica las siguientes propiedades en el mapa steps.inputs:

  • oldArguments (string, obligatorio): Los argumentos exactos de la línea de comandos para ubicar, quitar o reemplazar dentro de la configuración del bootloader.
  • newArguments (string, opcional): Los argumentos de reemplazo que se escribirán en lugar de las marcas de destino. Si omites la propiedad newArguments, Image Builder quita por completo los parámetros configurados en la oldArguments propiedad de la línea de arranque.

Configuraciones de muestra

En las siguientes pestañas, se muestran configuraciones de pasos de muestra para reemplazar o quitar argumentos de arranque del kernel:

Reemplaza los argumentos de arranque

La siguiente configuración ubica la clave de nivel de registro del kernel loglevel=4 y la reemplaza por parámetros más detallados loglevel=6 console=ttyS0:

- name: "Configure detailed boot logging"
  action: UpdateKernelCommandLine
  inputs:
    oldArguments: "loglevel=4"
    newArguments: "loglevel=6 console=ttyS0"

Quita los argumentos de arranque

La siguiente configuración busca el parámetro quiet y lo quita de los argumentos de arranque para habilitar el registro detallado durante las fases de verificación de inicio:

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

Detalles de ejecución específicos del SO

En las siguientes pestañas, se describe cómo el aprovisionador de personalización controla las modificaciones de imágenes según el sistema operativo invitado de origen:

Container-Optimized OS (COS)

Debido a que COS cuenta con un diseño de partición de solo lectura, omite las herramientas de configuración estándar. El aprovisionador de personalización hace lo siguiente:

  1. Determina la ruta de acceso del dispositivo de arranque activo.
  2. Activa la partición 12, la partición EFI, del dispositivo de arranque.
  3. Actualiza directamente los parámetros del bootloader dentro de /efi/boot/grub.cfg.
  4. Desactiva de forma segura la partición 12.

Ubuntu

En las imágenes de Ubuntu, el aprovisionador de personalización hace lo siguiente:

  1. Abre /etc/default/grub y los archivos en /etc/default/grub.d/*.cfg.
  2. Inserta, modifica o borra los argumentos de destino en el bloque GRUB_CMDLINE_LINUX.
  3. Ejecuta el comando de paquete update-grub para regenerar las configuraciones del bootloader.

Acción de FileCopy

La acción FileCopy copia archivos de configuración, archivos binarios o certificados de un bucket remoto o de tu repositorio local a tu imagen personalizada. El aprovisionador de personalización descarga o lee el archivo de origen, lo escribe en la ruta de acceso invitada especificada en la VM de trabajador y configura los permisos.

Especifica cualquiera de las siguientes entradas en steps.inputs:

  • destination (string, obligatorio): La ruta de acceso absoluta en el SO invitado donde se crea el archivo.
  • permissions (string, obligatorio): La representación octal de los permisos de configuración de destino, como "0755" o "0644".
  • Especifica cualquiera de las siguientes propiedades de origen:
    • gcsSourcePath (string): El URI de Cloud Storage del archivo de origen, que debe seguir el formato gs://BUCKET_NAME/OBJECT_NAME.
    • localSourcePath (string): La ruta de acceso relativa al archivo dentro de la carpeta del repositorio del espacio de trabajo local. El salto de directorio con ../ está bloqueado por seguridad.

Configuraciones de muestra

En las siguientes pestañas, se muestran configuraciones de pasos de muestra para copiar un archivo de Cloud Storage en comparación con la copia desde tu espacio de trabajo local:

Cloud Storage

La siguiente configuración copia una plantilla de configuración de un bucket de Cloud Storage en la imagen de VM invitada:

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

Espacio de trabajo local

La siguiente configuración copia una secuencia de comandos de aplicación compilada durante los pasos anteriores de Cloud Build:

- name: "Deploy setup automation daemon"
  action: FileCopy
  inputs:
    localSourcePath: "bin/setup-daemon"
    destination: "/usr/local/bin/setup-daemon"
    permissions: "0755"

Lineamientos específicos del SO

En las siguientes pestañas, se describen los lineamientos de ubicación de archivos según el sistema operativo invitado de destino:

Container-Optimized OS (COS)

Las imágenes de COS contienen un diseño de partición de solo lectura por motivos de seguridad. Algunos destinos del sistema estándar, como /usr/ o /bin/, están protegidos contra escritura.

Cuando configures destinos de archivos en COS, haz lo siguiente:

Ubuntu

Las imágenes de Ubuntu cuentan con un diseño de partición raíz de lectura y escritura de Linux estándar (/). Puedes especificar destinos de archivos dentro de cualquier ruta de acceso del sistema estándar, como /etc, /usr/local/bin, /var, o /home, siempre que el perfil de usuario o la carpeta de destino tengan los permisos de configuración adecuados en la VM de trabajador.

Acción de InstallGPU

Usa la acción InstallGPU para compilar imágenes de VM optimizadas para cargas de trabajo de aprendizaje automático, ciencia de datos o científicas. Image Builder descarga, compila y registra los controladores de GPU de NVIDIA en tus imágenes personalizadas. Según el tipo de imagen base y el hardware de destino, puedes elegir entre instalar controladores precompilados o compilar archivos .run de controladores personalizados.

Especifica cualquiera de las siguientes entradas en steps.inputs:

  • version (string): El número de versión del controlador NVIDIA de destino, como "595.129.03". Si especificas solo version, el orquestador descarga el controlador del repositorio oficial de NVIDIA (https://us.download.nvidia.com/tesla/<version>).
  • gcsRunfile (string): La ruta de acceso de Cloud Storage de un archivo instalador de controlador NVIDIA personalizado, que debe usar el formato gs://BUCKET_NAME/OBJECT_NAME.run.
  • sourceRunfile (string): La ruta de acceso relativa a un archivo .run instalador dentro de la carpeta del repositorio del espacio de trabajo local.

Configuraciones de muestra

En las siguientes pestañas, se muestran configuraciones de pasos de muestra para instalar una versión específica del controlador preempaquetado en comparación con la instalación de un archivo ejecutable personalizado:

Descarga de la versión estándar

La siguiente configuración descarga e instala una versión especificada del controlador NVIDIA del repositorio oficial:

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

Archivo ejecutable de Cloud Storage

La siguiente configuración implementa un instalador .run de controlador NVIDIA personalizado directamente desde un bucket de Cloud Storage:

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

Archivo ejecutable del espacio de trabajo local

La siguiente configuración implementa un instalador .run de controlador NVIDIA personalizado desde tu espacio de trabajo del repositorio local:

- name: "Deploy custom GPU driver from workspace"
  action: InstallGPU
  inputs:
    sourceRunfile: "drivers/NVIDIA-Linux-x86_64-<var>DRIVER_VERSION</var>.run"

Métodos de configuración

En las siguientes pestañas, se describen los métodos admitidos para configurar los controladores de GPU de NVIDIA en tus imágenes personalizadas:

Controladores precompilados

Te recomendamos que uses versiones de controladores preempaquetados para evitar la sobrecarga de procesamiento y el tiempo de compilación de los controladores desde cero.

  • Container-Optimized OS (COS): Si especificas una versión del controlador preempaquetada por Google, el aprovisionador de personalización ejecuta la herramienta invitada cos-extensions install gpu para activarla.

    Para ver la lista de versiones de controladores precompilados compatibles con tu versión de COS, ejecuta sudo cos-extensions list en una instancia de COS en ejecución, o consulta Identifica la versión del controlador de GPU.

  • Ubuntu: Para ahorrar tiempo de compilación en Ubuntu, te recomendamos que selecciones imágenes base preconfiguradas del proyecto público ubuntu-os-accelerator-images , en el que los controladores de NVIDIA están preinstalados.

    Para mostrar una lista de las imágenes de acelerador disponibles, ejecuta el siguiente comando en la CLI de gcloud:

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

Archivos ejecutables personalizados

Si debes instalar una versión de controlador personalizada que no esté precompilada por Google o Canonical, puedes especificar archivos ejecutables de instalador directos para la compilación de la siguiente manera:

  • Ubuntu: Realiza la compilación en el invitado. El aprovisionador de personalización instala automáticamente los encabezados del kernel coincidentes (linux-headers-$(uname -r)), compila el archivo .run del controlador NVIDIA en la VM de trabajador y lo registra con la compatibilidad con módulos de kernel dinámicos (DKMS). El registro con DKMS garantiza que los controladores permanezcan activos en las actualizaciones menores del kernel.
  • Container-Optimized OS (COS): El comportamiento de compilación varía según la arquitectura de la CPU de la imagen de VM base de origen:
    • Imágenes de ARM64: Debido a que las VMs de COS de ARM64 no admiten la compilación de encabezados en el invitado, Image Builder compila automáticamente de forma cruzada tu utilidad .run de controlador personalizado dentro del contenedor de compilación y luego instala el paquete resultante en /var/lib/nvidia en la VM de trabajador.
    • Imágenes de x86-64: Realiza la compilación en el invitado directamente en la VM de trabajador.

¿Qué sigue?