Arquivo de personalização de imagem

Este documento descreve a estrutura e os parâmetros do arquivo de receita de personalização imagebuilder.yaml, que você usa para definir a imagem do SO base, as configurações de hardware, os destinos de lançamento e as ações de personalização para seu pipeline do Image Builder.

Visão geral do esquema

A configuração de personalização usa a versão da API imagebuilder.gcp.com/v1 e o tipo de recurso OSImageCustomization.

Um arquivo de receita padrão tem a seguinte estrutura:

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

Metadados

Fornece detalhes de identificação para este modelo de build personalizado:

metadata:
  name: CONFIG_NAME
  description: DESCRIPTION
  • name (string, obrigatório): o identificador desta configuração.
  • description (string, opcional): uma descrição da finalidade do build.

Configuração da infraestrutura

Especifica as propriedades de hardware e rede de instâncias temporárias de máquina virtual que o Image Builder cria durante as tarefas de build e validação:

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 (string, obrigatório): o tipo de máquina do Compute Engine a ser usado para as VMs de worker e de teste. Verifique se o tipo de máquina corresponde à arquitetura da imagem de origem especificada em imageFamily ou imagePath. Por exemplo, use e2-standard-4 para imagens x86 e c4a-standard-4 para imagens Arm. Os tipos de máquina bare-metal não são compatíveis.
  • zone (string, obrigatório): a zona em que as VMs de trabalho e de teste são executadas, como us-central1-a.
  • network (string, opcional): a rede VPC a ser anexada às VMs de teste de validação e de worker, como projects/<var>PROJECT_ID</var>/global/networks/<var>NETWORK_NAME</var> ou default. Se omitido, o Image Builder usará a rede padrão.
  • subnetwork (string, opcional): a sub-rede VPC a ser anexada às VMs de teste de validação e de worker, como projects/<var>PROJECT_ID</var>/regions/<var>REGION</var>/subnetworks/<var>SUBNET_NAME</var>.
  • externalIP (string, opcional): especifica a alocação de endereço IP externo para as VMs de trabalho e de teste de validação. Valores permitidos:
    • ephemeral (padrão): aloca um endereço IPv4 público temporário de um pool compartilhado.
    • none: cria VMs sem um endereço IP externo, usando apenas redes VPC privadas. Quando definido como none, verifique se a sub-rede VPC tem o Acesso privado do Google ou o Cloud NAT ativado para que as VMs possam acessar os serviços Cloud de Confiance e os repositórios de pacotes necessários.
  • acceleratorType (string, opcional): o tipo de acelerador de GPU a ser anexado à VM de worker, como nvidia-tesla-t4 ou nvidia-l4.
  • acceleratorCount (número, opcional): o número de aceleradores de GPU a serem anexados à VM de worker.
  • debug (booleano, opcional): se você definir debug como true, o Image Builder vai preservar a VM de worker, seja concluída ou não a personalização. Assim, você pode inspecionar ou resolver problemas da instância ativa usando SSH. O padrão é false.
  • instanceDurationHours (número, opcional): limita o tempo de execução da VM de worker. O limite de tempo começa quando a personalização é concluída ou encontra um erro de script, permitindo que você se conecte à VM ativa durante sessões de depuração interativa. Limitado a um máximo de 2.0 horas.
  • reservations (matriz de strings, opcional): nomes de recursos de reserva de capacidade (como test-reservation no mesmo projeto) a serem consumidos quando o Image Builder cria VMs.
  • validationConcurrency (número, opcional): especifica o número máximo de testes de validação a serem executados em paralelo na instância de computação temporária de teste de validação. Os valores permitidos incluem:
    • 0 ou omitido (padrão): o Image Builder detecta automaticamente a simultaneidade com base no tipo de máquina e na configuração do acelerador e a define da seguinte maneira:
      • 1 (sequencial) para tipos de máquinas bare-metal ou configurações com aceleradores de GPU anexados, o que ajuda a evitar o excesso de limites de cota ou o esgotamento de recursos.
      • 4 (paralelo) para todos os outros tipos de máquinas.
    • 1: executa testes de validação em sequência. Se o projeto tiver uma cota limitada para o machineType especificado, definir a simultaneidade como 1 pode ser útil porque evita que várias instâncias de computação sejam iniciadas ao mesmo tempo.
    • 2 ou maior: executa o número especificado de testes de validação em paralelo. Se você tiver capacidade ou reservas suficientes, aumentar a simultaneidade poderá reduzir o tempo geral de execução dos testes de validação.

Imagem de origem

Identifica a imagem do sistema operacional de base que o Image Builder usa para iniciar a VM de worker. Você precisa especificar uma das seguintes opções:

Para especificar uma família de imagens padrão:

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

Para especificar um URI direto da versão de imagem:

source:
  imagePath: projects/IMAGE_PROJECT/global/images/IMAGE_NAME
  • imageFamily (string): o caminho para um grupo familiar de imagens padrão, como projects/ubuntu-os-cloud/global/images/family/ubuntu-2204-lts.
  • imagePath (string): o URI direto do recurso para uma versão específica da imagem do Compute Engine, como projects/cos-cloud/global/images/cos-105-17412-226-28.

Destinos

Define onde e como liberar a imagem personalizada compilada do SO. Essa propriedade contém uma lista de objetos de destino de lançamento em 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 (string, obrigatório): o prefixo do nome base atribuído ao recurso de imagem final do Compute Engine. O Image Builder adiciona automaticamente o ID de build exclusivo a esse prefixo e trunca o nome da imagem final para 63 caracteres.
  • family (string, opcional): a família de imagens a ser aplicada à imagem recém-gerada.
  • project (string, obrigatório): o projeto Cloud de Confiance em que o Image Builder grava a imagem de saída.
  • description (string, opcional): texto de descrição anexado aos metadados da imagem gerada.
  • licenses (matriz de strings, opcional): caminhos de recursos de licenças de software específicas aplicadas a esta imagem.
  • labels (mapa, opcional): pares de chave-valor de metadados de inclusão de tag, como env: production.
  • signatureDatabaseFile (string, opcional): caminho do recurso para um arquivo de banco de dados de assinatura de inicialização segura.
  • storageLocations (matriz de strings, opcional): região ou multirregião de armazenamento de destino, como us-central1 ou us, em que o Compute Engine armazena os blocos de disco finais. Observação: embora essa propriedade seja formatada como uma lista, você só pode especificar um local por destino de imagem.

Configuração de especificação

Aplica opções gerais de execução:

spec:
  config:
    skipSystemTests: false
  • skipSystemTests (booleano, opcional): alterna se a VM de teste avalia condições de inicialização, rede e estruturas UEFI. O padrão é false.

Etapas de especificação

Especifica uma lista de objetos de etapa que o Image Builder executa em ordem na VM de worker. Para ver exemplos de uso e esquemas de parâmetros de entrada completos para cada tipo de etapa, consulte Ações de personalização compatíveis.

Todos os objetos de etapa de personalização compartilham as seguintes propriedades comuns:

spec:
  steps:
    - name: STEP_NAME
      action: ACTION_TYPE
      inputs:
        # Action-specific input parameters
  • name (string, obrigatório): nome definido pelo usuário para esta etapa de personalização.
  • action (string, obrigatório): a ação de assistente a ser invocada. Ações compatíveis:
    • Shell: executa scripts de terminal na VM.
    • FileCopy: Transfere recursos de buckets ou espaços de trabalho do Cloud Storage.
    • UpdateKernelCommandLine: atualiza os parâmetros de inicialização.
    • InstallGPU: Registra drivers de GPU NVIDIA.
  • inputs (objeto, obrigatório): as propriedades de chave-valor exigidas pela ação selecionada. Para referências e exemplos completos de parâmetros, consulte Ações de personalização compatíveis.

O snippet a seguir mostra uma etapa de exemplo usando a ação Shell:

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

A seguir