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 do 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
infrastructureConfig:
  # VM machine type, zone, and network settings
source:
  # Base source image profile
destinations:
  # Output OS image release targets
spec:
  config:
    # Build options and validation test flags
  steps:
    # Customization actions (Shell, FileCopy, UpdateKernelCommandLine, InstallGPU)

Metadados

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

metadata:
  name: CONFIG_NAME
  description: DESCRIPTION
  • name (string, obrigatório): o identificador dessa 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 de máquina virtual temporárias 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: nvidia-l4
  acceleratorCount: 1
  debug: false
  instanceDurationHours: 2.0
  reservations:
    - RESERVATION_NAME
  • 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. Não há suporte para tipos de máquinas bare-metal.
  • zone (string, obrigatório): a zona em que as VMs de worker e de teste são executadas, como us-central1-a.
  • network (string, opcional): a rede VPC a ser anexada às VMs de worker e de teste de validação, 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 worker e de teste de validação, 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 worker e de teste de validação. Valores permitidos:
    • ephemeral (padrão): aloca um endereço IPv4 público efêmero de um pool compartilhado.
    • none: cria VMs sem endereço IP externo, que usa apenas a rede VPC privada. 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 necessários Google Cloud e os repositórios de pacotes.
  • 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 a personalização concluída ou falhe, para que você possa inspecionar ou solucionar 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. O limite 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.

Imagem de origem

Identifica a imagem do sistema operacional base que o Image Builder usa para iniciar a VM de worker. É necessário 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 de versão de imagem direta:

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 de recurso direto 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 do SO personalizada compilada. 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:
        - us-central1
  • name (string, obrigatório): o prefixo do nome base atribuído ao recurso de imagem final do Compute Engine. O Image Builder anexa 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 Google Cloud projeto 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 essa imagem.
  • labels (mapa, opcional): pares de chave-valor de metadados 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, é possível especificar apenas 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 as condições de inicialização, a rede e as 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 esquemas de parâmetros de entrada completos e exemplos de uso para cada tipo de etapa, consulte Ações de personalização com suporte.

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 essa etapa de personalização.
  • action (string, obrigatório): a ação auxiliar a ser invocada. Ações com suporte:
    • 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 de parâmetros completos, consulte Ações de personalização com suporte.

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

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

A seguir