Ações de personalização com suporte

Para personalizar as imagens de máquina virtual, como executar scripts de terminal, atualizar parâmetros de inicialização, transferir binários ou instalar drivers de GPU, você pode definir ações auxiliares específicas dentro do bloco spec.steps da receita de personalização (imagebuilder.yaml).

Visão geral

Durante a fase de execução de um build do Image Builder, o orquestrador executa as etapas declaradas na receita de personalização (spec.steps) sequencialmente na VM de worker temporária.

Cada etapa precisa especificar um bloco name, action e inputs adaptado a esse tipo de ação. O Image Builder é compatível com as seguintes ações de personalização:

• Shell: executa scripts ou comandos de terminal inline no SO convidado do worker.
• UpdateKernelCommandLine: modifica os parâmetros de inicialização e as flags de linha de comando do kernel.
• FileCopy: transfere arquivos de configuração, scripts ou recursos do Cloud Storage ou de espaços de trabalho locais para a VM.
• InstallGPU: baixa, compila e registra drivers de GPU NVIDIA.

Ação do shell

A ação Shell permite executar scripts de terminal inline ou comandos de shell únicos no SO convidado da VM de worker temporária para realizar personalizações como atualizar pacotes, configurar contas de usuário ou compilar software.

Especifique uma das seguintes entradas em steps.inputs:

• inlineScript (string): comandos brutos de shell de várias linhas a serem executados.
• command (string): uma única string de comando do sistema ou caminho relativo para um arquivo binário executável.

Configurações de amostra

As guias a seguir mostram exemplos de configurações de etapa para executar um script in-line em vez de um único 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"

Comportamentos especiais

Ao executar ações de Shell, o provisionador de personalização gerencia a auditoria de segurança e as reinicializações automáticas do sistema, conforme descrito nas seções a seguir:

Auditoria de segurança

Para evitar que tokens, segredos ou códigos proprietários sensíveis vazem para os registros de execução, o provisionador de personalização não imprime as linhas brutas dos seus scripts, a menos que a depuração interativa esteja ativada (debug: true). Em vez disso, ele registra o hash de integridade SHA-256 da carga útil do script nos registros de build. Esse hash fornece um rastreamento de auditoria imutável de exatamente qual código foi executado na imagem.

Reinicializações do sistema (código de saída 3010)

Algumas ações do shell, como atualizações de patch do kernel ou ajustes de partição de armazenamento, exigem uma reinicialização do sistema antes que as etapas subsequentes possam ser executadas.

Para solicitar uma reinicialização do sistema durante a personalização, o script de shell precisa terminar com o comando exit 3010. Quando o provisionador de personalização recebe o código de saída 3010, ele processa o ciclo de vida de reinicialização da seguinte maneira:

1. O provisionador detecta o código de saída 3010, pausa a execução e marca o índice de progresso da etapa.
2. O provisionador reinicia a VM de worker.
3. Depois que a VM é reiniciada, o provisionador monta o espaço de trabalho e retoma automaticamente o pipeline na próxima etapa da fila.

Exemplo de reinicialização:

O exemplo a seguir mostra uma configuração de etapa que atualiza pacotes e solicita uma reinicialização:

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

Ação UpdateKernelCommandLine

A ação UpdateKernelCommandLine localiza, substitui, insere ou remove flags de linha de comando transmitidos ao kernel na inicialização do sistema, como quando você configura registros do console ou ajusta parâmetros do kernel.

Especifique as seguintes propriedades no mapa steps.inputs:

• oldArguments (string, obrigatório): os argumentos exatos da linha de comando para localizar, remover ou substituir na configuração do carregador de inicialização.
• newArguments (string, opcional): os argumentos de substituição a serem gravados no lugar das flags de destino. Se você omitir a propriedade newArguments, o Image Builder vai remover completamente da linha de inicialização os parâmetros configurados na propriedade oldArguments.

Configurações de amostra

As guias a seguir mostram exemplos de configurações de etapas para substituir ou remover argumentos de inicialização do 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"

Detalhes de execução específicos do SO

As guias a seguir descrevem como o provisionador de personalização processa as modificações de imagem dependendo do sistema operacional convidado de origem:

Ação FileCopy

A ação FileCopy copia arquivos de configuração, binários ou certificados de um bucket remoto ou do seu repositório local para sua imagem personalizada. O provisionador de personalização baixa ou lê o arquivo de origem, grava no caminho de convidado especificado na VM de worker e configura as permissões.

Especifique as seguintes entradas em steps.inputs:

• destination (string, obrigatório): o caminho absoluto no SO convidado em que o arquivo é criado.
• permissions (string, obrigatório): a representação octal das permissões de configuração de destino, como "0755" ou "0644".
• Especifique uma das seguintes propriedades de origem:
  • gcsSourcePath (string): o URI do Cloud Storage do arquivo de origem, que precisa seguir o formato gs://BUCKET_NAME/OBJECT_NAME.
  • localSourcePath (string): o caminho relativo para o arquivo na pasta do repositório do espaço de trabalho local. A travessia de caminhos usando ../ é bloqueada por segurança.

Configurações de amostra

As guias a seguir mostram exemplos de configurações de etapa para copiar um arquivo do Cloud Storage ou do seu espaço de trabalho 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"

Diretrizes específicas do SO

As guias a seguir descrevem as diretrizes de localização de arquivos dependendo do sistema operacional convidado de destino:

Ação InstallGPU

Use a ação InstallGPU para criar imagens de VM otimizadas para machine learning, ciência de dados ou cargas de trabalho científicas. O Image Builder baixa, compila e registra drivers de GPU NVIDIA nas suas imagens personalizadas. Dependendo do tipo de imagem de base e do hardware de destino, é possível instalar drivers pré-compilados ou compilar arquivos .run de driver personalizados.

Especifique uma das seguintes entradas em steps.inputs:

• version (string): o número da versão do driver NVIDIA de destino, como "595.129.03". Se você especificar apenas version, o orquestrador fará o download do driver do repositório oficial da NVIDIA (https://us.download.nvidia.com/tesla/<version>).
• gcsRunfile (string): o caminho do Cloud Storage de um arquivo instalador de driver NVIDIA personalizado, que precisa usar o formato gs://BUCKET_NAME/OBJECT_NAME.run.
• sourceRunfile (string): o caminho relativo para um arquivo .run do instalador na pasta do repositório do espaço de trabalho local.

Configurações de amostra

As guias a seguir mostram exemplos de configurações de etapa para instalar uma versão específica de driver pré-empacotado em vez de instalar um arquivo de execução 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 configuração

As guias a seguir descrevem os métodos compatíveis para configurar drivers de GPU NVIDIA nas suas imagens personalizadas:

A seguir

• Revise os blocos de esquema de nível superior no Esquema de arquivo de personalização de imagem.
• Configure os parâmetros de orquestração do pipeline no esquema do arquivo de configuração do Cloud Build.
• Siga o tutorial para criar um pipeline do Image Builder.