이 페이지의 일부 또는 모든 정보는 S3NS의 Cloud de Confiance에 적용되지 않을 수 있습니다. 자세한 내용은 Google Cloud와의 차이점을 참조하세요.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Cloud Build 구성 파일

이 문서에서는 Image Builder 파이프라인의 단계(파싱, 빌드, 검증, 출시 게시)를 오케스트레이션하는 데 사용되는 Cloud Build 구성 파일(cloudbuild.yaml)의 구조와 파라미터를 설명합니다.

스키마 개요

표준 Image Builder cloudbuild.yaml 파일은 표준 Cloud Build 빌드 구성 파일 구조를 따르고 /build, /validate, /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'

대체 변수

cloudbuild.yaml 파일은 다음 대체 변수를 사용하여 실행을 위한 환경 변수에 직접 매핑합니다.

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: 직렬 로그, 임시 이미지 보관 파일, 게스트 실행 기록과 같은 아티팩트의 임시 스테이징 위치로 사용되는 리전 Cloud Storage 경로입니다. 버킷은 이미 있어야 합니다.
_IMAGE_BUILDER_CONFIG_PATH: imagebuilder.yaml 맞춤설정 레시피의 경로입니다. 소스에 따라 원격 Cloud Storage 경로(예: gs://BUCKET_NAME/imagebuilder.yaml) 또는 작업공간이나 GitHub 저장소의 상대 경로일 수 있습니다.

참고: 원격 Cloud Storage 위치에서 구성 파일을 가져오는 경우 객체 크기는 1MB를 초과할 수 없습니다.
_SERVICE_ACCOUNT: 빌드를 실행하고 오케스트레이터 단계를 승인하도록 구성된 서비스 계정의 전체 Identity and Access Management (IAM) 리소스 이름입니다.
_IMAGE_OUTPUT_PATH: Cloud Build /workspace/ 디렉터리 내에서 내보낸 tar 파일의 출력 경로입니다.
_ARTIFACT_REGISTRY_RESOURCE_URI (선택사항): Artifact Registry의 일반 저장소 리소스 URI입니다. 제공된 경우 파이프라인은 생성된 변경할 수 없는 이미지 tar 파일을 푸시하고 이 위치에서 증명을 생성합니다.

단계

Image Builder는 OS 이미지 빌드를 오케스트레이션하기 위해 순서대로 세 가지 고유한 컨테이너 단계를 실행합니다. 컨테이너 이미지 경로의 REGION을 파이프라인을 설정한 대상 Cloud de Confiance 리전(예: us-central1, europe-west1, 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'

원격 분석 및 단계 ID 요구사항

오케스트레이터 컨테이너는 cloudbuild.yaml 파일에 있는 각 단계의 id 필드를 읽어 각 빌드 단계(맞춤설정, 유효성 검사, 게시)의 진행 상황을 식별하고 추적합니다.

이미지 빌더가 서비스별 원격 분석 측정항목을 수집할 수 있도록 단계 ID는 imagebuilder- 접두사(예: imagebuilder-customize, imagebuilder-validate, imagebuilder-publish)로 시작해야 합니다.

각 단계의 results 블록에 image_builder_telemetry_metrics를 포함하면 Image Builder가 다음과 같이 서비스 안정성을 모니터링하고 추적하기 위해 대략적인 파이프라인 실행 측정항목을 안전하게 수집합니다.

빌드 실행 및 상태: 각 빌드 단계 및 맞춤설정 작업의 성공 또는 실패 상태와 완료 기간입니다.
환경 세부정보: 실행 중에 사용된 Compute Engine 머신 유형, 영역, 컨테이너 버전 태그입니다.
이미지 메타데이터: 기본 OS 배포, 버전, 구성된 게스트 OS 기능
유효성 검사 테스트 결과: VM 부팅, 보안 부팅, 블록 스토리지 상태, 게스트 에이전트 상태, 네트워크 드라이버 바인딩과 같은 자동 시스템 유효성 검사 테스트의 통과, 실패 또는 건너뜀 상태입니다.

맞춤설정 단계

맞춤설정 단계에서는 imagebuilder.yaml의 스키마를 검증하고, IAM 권한을 확인하고, 작업자 VM 인스턴스를 실행하고, 맞춤설정 바이너리 디스크를 마운트하고, 맞춤설정 프로비저닝 도구를 실행하고, 부팅 디스크 파티션을 안전하게 내보냅니다.

컨테이너 이미지: us-central1-docker.pkg.dev/image-builder-official/release/builder:stable
스크립트 명령어: /build
결과 하위 블록:
- image_builder_telemetry_metrics: 맞춤설정 빌드 실행 측정항목을 수집합니다.
- base_image (선택사항): Artifact Registry 일반 저장소 대상을 지정할 때 빌드 증명 메타데이터에 기본 소스 이미지 세부정보를 기록합니다. attestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions"를 설정하여 이미지의 출처를 확인할 수 있는 기록을 만듭니다.

유효성 검사 단계

검증 단계에서는 맞춤설정된 OS 이미지에서 임시 테스트 VM을 부팅하고 활성 자동 검증 테스트 모음을 실행합니다.

컨테이너 이미지: us-central1-docker.pkg.dev/image-builder-official/release/validator:stable
스크립트 명령어: /validate
결과 하위 블록: image_builder_telemetry_metrics는 유효성 검사 테스트 실행 측정항목을 수집합니다.

게시 단계

게시 단계에서는 최종 OS 이미지를 등록하고, 임시 중간 디스크를 삭제하고, 구성된 경우 tar 파일 페이로드를 Artifact Registry에 업로드하고, 소프트웨어 아티팩트에 대한 공급망 수준 (SLSA) 출처 레코드를 작성합니다.

컨테이너 이미지: us-central1-docker.pkg.dev/image-builder-official/release/builder:stable
스크립트 명령어: /publish
결과 하위 블록: image_builder_telemetry_metrics는 게시 버전 실행 측정항목을 수집합니다.

옵션

옵션 플래그는 Cloud Build 서버의 실행 설정을 정의합니다. 다음 옵션을 구성해야 합니다.

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

이러한 설정에 대한 자세한 내용은 Cloud Build 구성 파일의 옵션을 참고하세요.

automapSubstitutions: 대체 변수가 컨테이너 환경에 매핑되도록 true로 설정합니다.
requestedVerifyOption: VERIFIED로 설정합니다. 이 설정은 Cloud Build에 SLSA 빌드 출처 기록 증명을 자동으로 생성하도록 지시합니다. 이 출처는 이미지가 파이프라인에 정의된 대로 정확하게 빌드되었음을 암호화 방식으로 확인하여 조작을 방지하고 소프트웨어 공급망 무결성을 보장합니다.
substitutionOption: ALLOW_LOOSE로 설정합니다. 이 설정은 Cloud Build가 동적 매개변수 또는 사용되지 않는 스크립트 인수를 무시하도록 강제하는 데 필요합니다.
dynamicSubstitutions: ${BUILD_ID}와 같은 시스템 평가 변수가 올바르게 확인되도록 true로 설정합니다.
logging: 빌드 로그를 Cloud Logging으로만 제한하려면 CLOUD_LOGGING_ONLY로 설정합니다.

아티팩트

이미지 보관 파일과 증명서를 Artifact Registry로 내보낼 때 artifacts 블록을 구성합니다.

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