Archivo de configuración de Cloud Build

En este documento, se describen la estructura y los parámetros del archivo de configuración de Cloud Build (cloudbuild.yaml) que se usa para coordinar los pasos de la canalización de Image Builder: análisis, compilación, validación y publicación de versiones.

Descripción general del esquema

Un archivo cloudbuild.yaml estándar de Image Builder sigue la estructura estándar del archivo de configuración de Cloud Build y coordina tres pasos secuenciales de compilación de contenedores: /build, /validate y /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'

Variables de sustitución

El archivo cloudbuild.yaml usa las siguientes variables de sustitución para asignar directamente las variables de entorno para la ejecución:

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: Es la ruta de acceso regional de Cloud Storage que se usa como ubicación de etapa de pruebas temporal para artefactos como registros seriales, archivos de imágenes temporales y registros de ejecución de invitados. El bucket ya debe existir.

  • _IMAGE_BUILDER_CONFIG_PATH: Es la ruta de acceso a tu receta de personalización de imagebuilder.yaml. Puede ser una ruta de Cloud Storage remota (por ejemplo, gs://BUCKET_NAME/imagebuilder.yaml) o una ruta relativa en tu repositorio de GitHub o espacio de trabajo, según la fuente.

  • _SERVICE_ACCOUNT: Es el nombre completo del recurso de Identity and Access Management (IAM) de la cuenta de servicio configurada para ejecutar la compilación y autorizar los pasos del orquestador.

  • _IMAGE_OUTPUT_PATH: Es la ruta de acceso de salida del archivo tar exportado dentro del directorio /workspace/ de Cloud Build.

  • _ARTIFACT_REGISTRY_RESOURCE_URI (opcional): Es el URI del recurso para el repositorio genérico en Artifact Registry. Si se proporciona, la canalización envía el archivo tar de imagen inmutable generado y genera certificaciones en esta ubicación.

Pasos

Image Builder ejecuta tres pasos de contenedor distintos en secuencia para coordinar la compilación de la imagen de SO. Reemplaza REGION en la ruta de acceso de la imagen de contenedor por la región de destino Cloud de Confiance en la que configuraste tus canalizaciones, como us-central1, europe-west1 o 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 telemetría y del ID de paso

El contenedor del orquestador identifica y hace un seguimiento del progreso de cada fase de compilación (personalización, validación y publicación) leyendo el campo id de cada paso en tu archivo cloudbuild.yaml.

Los IDs de paso deben comenzar con el prefijo imagebuilder-, como imagebuilder-customize, imagebuilder-validate y imagebuilder-publish, para permitir que Image Builder recopile métricas de telemetría específicas del servicio.

Cuando incluyes image_builder_telemetry_metrics en el bloque results de cada paso, Image Builder recopila de forma segura métricas de ejecución de la canalización de alto nivel para supervisar y hacer un seguimiento de la confiabilidad del servicio de la siguiente manera:

  • Ejecución y estado de la compilación: Estado de éxito o error y duración de la finalización de cada paso de compilación y acción de personalización.
  • Detalles del entorno: El tipo de máquina, la zona y la etiqueta de versión del contenedor de Compute Engine que se usaron durante la ejecución.
  • Metadatos de la imagen: Distribución del SO base, versión y funciones configuradas del SO invitado
  • Resultados de las pruebas de validación: Estado de aprobación, falla o omisión de las pruebas de validación del sistema automatizadas, como el inicio de la VM, el inicio seguro, el estado del almacenamiento en bloque, el estado del agente invitado y la vinculación del controlador de red.

Paso de personalización

El paso de personalización valida el esquema de imagebuilder.yaml, verifica los permisos de IAM, inicia la instancia de VM de trabajador, activa el disco binario de personalización, ejecuta el aprovisionador de personalización y exporta de forma segura la partición del disco de arranque.

  • Imagen de contenedor: us-central1-docker.pkg.dev/image-builder-official/release/builder:stable
  • Comando de secuencia de comandos: /build
  • Subbloque de resultados:
    • image_builder_telemetry_metrics: Recopila métricas de ejecución de compilaciones de personalización.
    • base_image (opcional): Registra los detalles de la imagen fuente base en los metadatos de certificación de compilación cuando especificas un destino de repositorio genérico de Artifact Registry. Configura attestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions" para crear un registro verificable de los orígenes de tu imagen.

Paso de validación

En el paso de validación, se inicia una VM de prueba temporal a partir de la imagen de SO personalizada y se ejecutan conjuntos de pruebas de validación automatizadas activas.

  • Imagen de contenedor: us-central1-docker.pkg.dev/image-builder-official/release/validator:stable
  • Comando de secuencia de comandos: /validate
  • Sub-bloque de resultados: image_builder_telemetry_metrics recopila métricas de ejecución de pruebas de validación.

Paso de publicación

El paso de publicación registra la imagen final del SO, borra los discos intermedios temporales, sube la carga útil del archivo tar a Artifact Registry si está configurado y escribe los registros de procedencia de los Niveles de la cadena de suministro para artefactos de software (SLSA).

  • Imagen de contenedor: us-central1-docker.pkg.dev/image-builder-official/release/builder:stable
  • Comando de secuencia de comandos: /publish
  • Sub-bloque de resultados: image_builder_telemetry_metrics recopila métricas de ejecución de la versión de publicación.

Opciones

Las marcas de opciones definen la configuración de ejecución en el servidor de Cloud Build. Debes configurar las siguientes opciones:

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

Para obtener más información sobre estos parámetros de configuración, consulta Opciones en el archivo de configuración de Cloud Build.

  • automapSubstitutions: Se establece en true para garantizar que las variables de sustitución se asignen al entorno del contenedor.
  • requestedVerifyOption: Configurado como VERIFIED. Este parámetro de configuración indica a Cloud Build que genere automáticamente certificaciones de procedencia de compilación de SLSA. Esta procedencia proporciona una verificación criptográfica de que la imagen se compiló exactamente como se definió en tu canalización, lo que ayuda a evitar la manipulación y garantiza la integridad de la cadena de suministro de software.
  • substitutionOption: Configurado como ALLOW_LOOSE. Este parámetro de configuración es obligatorio para forzar a Cloud Build a ignorar los parámetros dinámicos o los argumentos de secuencia de comandos no utilizados.
  • dynamicSubstitutions: Se establece en true para permitir que las variables de evaluación del sistema, como ${BUILD_ID}, se resuelvan correctamente.
  • logging: Se establece en CLOUD_LOGGING_ONLY para restringir los registros de compilación estrictamente a Cloud Logging.

Artefactos

Configura el bloque artifacts cuando exportes archivos y certificaciones de imágenes a Artifact Registry:

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