Arquivo de configuração do Cloud Build

Este documento descreve a estrutura e os parâmetros do arquivo de configuração do Cloud Build (cloudbuild.yaml) usado para orquestrar as etapas do pipeline do Image Builder: análise, criação, validação e publicação de lançamento.

Visão geral do esquema

Um arquivo cloudbuild.yaml padrão do Image Builder segue a estrutura padrão de arquivo de configuração do Cloud Build e orquestra três etapas sequenciais de build de contêiner: /build, /validate e /publish.

substitutions:
  _GCS_WORKDIR: 'gs://BUCKET_NAME/workdir/'
  _IMAGE_BUILDER_CONFIG_PATH: 'imagebuilder.yaml'
  _SERVICE_ACCOUNT: 'projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL'
  _IMAGE_OUTPUT_PATH: 'image-builder/binaryOut'
  _ARTIFACT_REGISTRY_RESOURCE_URI: 'projects/PROJECT_ID/locations/REGION/repositories/REPOSITORY_NAME/packages/PACKAGE_NAME/versions/v${BUILD_ID}'

steps:
  # Step 1: Parse configs and run OS customization on the worker VM
  - name: 'REGION-docker.pkg.dev/image-builder-official/release/builder:stable'
    script: |
      #!/usr/bin/env bash
      /build
    id: 'imagebuilder-customize'
    results:
      - name: image_builder_telemetry_metrics
      - name: base_image
        attestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions"
        attestationContent: base_image

  # Step 2: Validate by running system boot checks on the test VM
  - name: 'REGION-docker.pkg.dev/image-builder-official/release/validator:stable'
    script: |
      #!/usr/bin/env bash
      /validate
    id: 'imagebuilder-validate'
    results:
      - name: image_builder_telemetry_metrics

  # Step 3: Register OS image and publish tar file to Artifact Registry
  - name: 'REGION-docker.pkg.dev/image-builder-official/release/builder:stable'
    script: |
      #!/usr/bin/env bash
      /publish
    id: 'imagebuilder-publish'
    results:
      - name: image_builder_telemetry_metrics

options:
  automapSubstitutions: true
  requestedVerifyOption: VERIFIED
  substitutionOption: ALLOW_LOOSE
  dynamicSubstitutions: true
  logging: CLOUD_LOGGING_ONLY

artifacts:
  generic_artifacts:
    - folder: '${_IMAGE_OUTPUT_PATH}'
      registry_path: '${_ARTIFACT_REGISTRY_RESOURCE_URI}'

timeout: '3600s'

Variáveis de substituição

O arquivo cloudbuild.yaml usa as seguintes variáveis de substituição para mapear diretamente as variáveis de ambiente para execução:

substitutions:
  _GCS_WORKDIR: 'gs://BUCKET_NAME/workdir/'
  _IMAGE_BUILDER_CONFIG_PATH: 'imagebuilder.yaml'
  _SERVICE_ACCOUNT: 'projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL'
  _IMAGE_OUTPUT_PATH: 'image-builder/binaryOut'
  _ARTIFACT_REGISTRY_RESOURCE_URI: 'projects/PROJECT_ID/locations/REGION/repositories/REPOSITORY_NAME/packages/PACKAGE_NAME/versions/v${BUILD_ID}'
  • _GCS_WORKDIR: o caminho regional do Cloud Storage usado como um local de preparo temporário para artefatos como registros seriais, arquivos de imagem temporários e históricos de execução de convidados. O bucket já precisa existir.

  • _IMAGE_BUILDER_CONFIG_PATH: o caminho para sua receita de personalização imagebuilder.yaml. Pode ser um caminho remoto do Cloud Storage (por exemplo, gs://BUCKET_NAME/imagebuilder.yaml) ou um caminho relativo no seu espaço de trabalho ou repositório do GitHub, dependendo da origem.

  • _SERVICE_ACCOUNT: o nome completo do recurso do Identity and Access Management (IAM) da conta de serviço configurada para executar o build e autorizar as etapas do orquestrador.

  • _IMAGE_OUTPUT_PATH: o caminho de saída do arquivo tar exportado no diretório /workspace/ do Cloud Build.

  • _ARTIFACT_REGISTRY_RESOURCE_URI (opcional): o URI do recurso para o repositório genérico no Artifact Registry. Se fornecido, o pipeline vai enviar o arquivo tar de imagem imutável gerado e criar atestados nesse local.

Etapas

O Image Builder executa três etapas de contêiner distintas em sequência para orquestrar a criação da imagem do SO. Substitua REGION no caminho da imagem do contêiner pela região de destino Cloud de Confiance em que você configurou seus pipelines, como us-central1, europe-west1 ou asia-east1:

steps:
  - name: 'REGION-docker.pkg.dev/image-builder-official/release/builder:stable'
    script: |
      #!/usr/bin/env bash
      /build
    id: 'imagebuilder-customize'

  - name: 'REGION-docker.pkg.dev/image-builder-official/release/validator:stable'
    script: |
      #!/usr/bin/env bash
      /validate
    id: 'imagebuilder-validate'

  - name: 'REGION-docker.pkg.dev/image-builder-official/release/builder:stable'
    script: |
      #!/usr/bin/env bash
      /publish
    id: 'imagebuilder-publish'

Requisitos de telemetria e ID da etapa

O contêiner orquestrador identifica e acompanha a progressão de cada fase do build (personalização, validação e publicação) lendo o campo id de cada etapa no arquivo cloudbuild.yaml.

Os IDs de etapa precisam começar com o prefixo imagebuilder-, como imagebuilder-customize, imagebuilder-validate e imagebuilder-publish, para permitir que o Image Builder colete métricas de telemetria específicas do serviço.

Quando você inclui image_builder_telemetry_metrics no bloco results de cada etapa, o Image Builder coleta com segurança métricas de execução de pipeline de alto nível para monitorar e rastrear a confiabilidade do serviço da seguinte maneira:

  • Execução e status da build: status de sucesso ou falha e duração da conclusão de cada etapa de build e ação de personalização.
  • Detalhes do ambiente: o tipo de máquina, a zona e a tag da versão do contêiner do Compute Engine usados durante a execução.
  • Metadados da imagem: distribuição e versão do SO base e recursos do SO convidado configurado.
  • Resultados do teste de validação: status de aprovação, falha ou ignorado dos testes de validação automatizados do sistema, como inicialização da VM, inicialização segura, integridade do armazenamento em blocos, status do agente convidado e vinculação do driver de rede.

Etapa de personalização

A etapa de personalização valida o esquema de imagebuilder.yaml, verifica as permissões do IAM, inicia a instância de VM de worker, monta o disco binário de personalização, executa o provisionador de personalização e exporta com segurança a partição do disco de inicialização.

  • Imagem do contêiner: us-central1-docker.pkg.dev/image-builder-official/release/builder:stable
  • Comando de script: /build
  • Subbloco de resultados:
    • image_builder_telemetry_metrics: coleta métricas de execução de build de personalização.
    • base_image (opcional): registra detalhes da imagem de origem base nos metadados de atestado de build quando você especifica um destino de repositório genérico do Artifact Registry. Defina attestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions" para criar um registro verificável das origens da sua imagem.

Etapa de validação

A etapa de validação inicializa uma VM de teste temporária da imagem do SO personalizada e executa conjuntos de testes de validação automatizada ativos.

  • Imagem do contêiner: us-central1-docker.pkg.dev/image-builder-official/release/validator:stable
  • Comando de script: /validate
  • Sub-bloco "Resultados": o image_builder_telemetry_metrics coleta métricas de execução de testes de validação.

Etapa de publicação

A etapa de publicação registra a imagem final do SO, exclui discos intermediários temporários, faz upload da carga útil do arquivo tar para o Artifact Registry (se configurado) e grava registros de procedência dos Níveis da cadeia de suprimentos para artefatos de software (SLSA).

  • Imagem do contêiner: us-central1-docker.pkg.dev/image-builder-official/release/builder:stable
  • Comando de script: /publish
  • Sub-bloco de resultados: image_builder_telemetry_metrics coleta métricas de execução de lançamento de publicação.

Opções

As flags de opções definem as configurações de execução no servidor do Cloud Build. Você precisa configurar as seguintes opções:

options:
  automapSubstitutions: true
  requestedVerifyOption: VERIFIED
  substitutionOption: ALLOW_LOOSE
  dynamicSubstitutions: true
  logging: CLOUD_LOGGING_ONLY

Para mais informações sobre essas configurações, consulte Opções no arquivo de configuração do Cloud Build.

  • automapSubstitutions: defina como true para garantir que as variáveis de substituição sejam mapeadas no ambiente do contêiner.
  • Defina requestedVerifyOption como VERIFIED. Essa configuração instrui o Cloud Build a gerar automaticamente atestações de procedência do build do SLSA. Essa origem fornece verificação criptográfica de que a imagem foi criada exatamente como definido no pipeline, ajudando a evitar adulterações e garantindo a integridade da cadeia de suprimentos de software.
  • Defina substitutionOption como ALLOW_LOOSE. Essa configuração é necessária para forçar o Cloud Build a ignorar parâmetros dinâmicos ou argumentos de script não usados.
  • dynamicSubstitutions: defina como true para permitir que variáveis de avaliação do sistema, como ${BUILD_ID}, sejam resolvidas corretamente.
  • logging: defina como CLOUD_LOGGING_ONLY para restringir os registros de build estritamente ao Cloud Logging.

Artefatos

Configure o bloco artifacts ao exportar arquivos e atestados de imagens para o Artifact Registry:

artifacts:
  generic_artifacts:
    - folder: '${_IMAGE_OUTPUT_PATH}'
      registry_path: '${_ARTIFACT_REGISTRY_RESOURCE_URI}'