Acciones de personalización compatibles

Para personalizar las imágenes de tu máquina virtual, como ejecutar secuencias de comandos de la terminal, actualizar parámetros de arranque, transferir archivos binarios o instalar controladores de GPU, puedes definir acciones de ayuda 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, un bloque action y un bloque inputs adaptados a ese tipo de acción. Image Builder admite las siguientes acciones de personalización:

• Shell: Ejecuta comandos o secuencias de comandos de terminal intercalados en el SO invitado del trabajador.
• UpdateKernelCommandLine: Modifica los parámetros de inicio 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 la 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 (cadena): Comandos de shell sin procesar de varias líneas para ejecutar.
• command (cadena): Es una sola cadena de comando del sistema o una ruta de acceso relativa a un archivo binario ejecutable.

Configuraciones de muestra

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

- 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

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

Comportamientos especiales

Cuando ejecutas acciones de Shell, el aprovisionador de personalización administra la auditoría 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 cambio, registra el hash de integridad SHA-256 de la carga útil de tu secuencia de comandos en los registros de compilación. Este hash proporciona un registro de auditoría inmutable de exactamente qué código se ejecutó en la imagen.

Reinicio del sistema (código de salida 3010)

Algunas acciones de shell, como las actualizaciones de parches del kernel o los ajustes de particiones 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 finalizar con el comando exit 3010. Cuando el aprovisionador de personalización recibe el código de salida 3010, controla el ciclo de vida del 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 UpdateKernelCommandLine

La acción UpdateKernelCommandLine ubica, reemplaza, inserta o quita marcas de línea de comandos que se pasan al kernel durante el inicio del sistema, por ejemplo, cuando configuras registros de la consola o ajustas parámetros del kernel.

Especifica las siguientes propiedades en el mapa steps.inputs:

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

Configuraciones de muestra

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

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

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

Acción FileCopy

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

Especifica las siguientes entradas en steps.inputs:

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

Configuraciones de muestra

En las siguientes pestañas, se muestran ejemplos de configuraciones de pasos para copiar un archivo desde Cloud Storage y desde tu espacio de trabajo local:

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

- 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 para la ubicación de archivos según el sistema operativo invitado de destino:

Acción 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 una de las siguientes entradas en steps.inputs:

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

Configuraciones de muestra

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

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

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

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

¿Qué sigue?

• Revisa los bloques de esquema de nivel superior en el esquema del archivo de personalización de imágenes.
• Configura los parámetros de orquestación de la canalización en el esquema del archivo de configuración de Cloud Build.
• Sigue el instructivo para crear una canalización de Image Builder.