이미지 맞춤설정 파일

이 문서에서는 이미지 빌더 파이프라인의 기본 OS 이미지, 하드웨어 구성, 출시 대상, 맞춤설정 작업을 정의하는 데 사용하는 맞춤설정 레시피 파일 imagebuilder.yaml의 구조와 매개변수를 설명합니다.

스키마 개요

맞춤설정 구성은 API 버전 imagebuilder.gcp.com/v1 및 리소스 종류 OSImageCustomization를 사용합니다.

표준 레시피 파일의 구조는 다음과 같습니다.

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

메타데이터

이 맞춤 빌드 템플릿의 식별 세부정보를 제공합니다.

metadata:
  name: CONFIG_NAME
  description: DESCRIPTION
  • name (문자열, 필수): 이 구성의 식별자입니다.
  • description (문자열, 선택사항): 빌드의 목적에 대한 설명입니다.

인프라 구성

빌드 및 검증 작업 중에 Image Builder가 만드는 임시 가상 머신 인스턴스의 하드웨어 및 네트워크 속성을 지정합니다.

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 (문자열, 필수): 작업자 및 테스트 VM에 사용할 Compute Engine 머신 유형입니다. 머신 유형이 imageFamily 또는 imagePath에 지정한 소스 이미지의 아키텍처와 일치하는지 확인합니다. 예를 들어 x86 이미지에는 e2-standard-4을 사용하고 Arm 이미지에는 c4a-standard-4을 사용합니다. 베어메탈 머신 유형은 지원되지 않습니다.
  • zone(문자열, 필수): 작업자 및 테스트 VM이 실행되는 영역입니다(예: us-central1-a).
  • network(문자열, 선택사항): 작업자 및 유효성 검사 테스트 VM에 연결할 VPC 네트워크입니다(예: projects/<var>PROJECT_ID</var>/global/networks/<var>NETWORK_NAME</var> 또는 default). 생략하면 Image Builder에서 기본 네트워크를 사용합니다.
  • subnetwork(문자열, 선택사항): 작업자 및 검증 테스트 VM에 연결할 VPC 서브네트워크입니다(예: projects/<var>PROJECT_ID</var>/regions/<var>REGION</var>/subnetworks/<var>SUBNET_NAME</var>).
  • externalIP (문자열, 선택사항): 작업자 및 검증 테스트 VM의 외부 IP 주소 할당을 지정합니다. 허용되는 값:
    • ephemeral (기본값): 공유 풀에서 공개 임시 IPv4 주소를 할당합니다.
    • none: 비공개 VPC 네트워킹만 사용하는 외부 IP 주소가 없는 VM을 만듭니다. none로 설정된 경우 VM이 필요한 Cloud de Confiance 서비스 및 패키지 저장소에 액세스할 수 있도록 VPC 서브넷에 비공개 Google 액세스 또는 Cloud NAT가 사용 설정되어 있는지 확인합니다.
  • acceleratorType(문자열, 선택사항): 작업자 VM에 연결할 GPU 가속기 유형입니다(예: nvidia-tesla-t4 또는 nvidia-l4).
  • acceleratorCount (숫자, 선택사항): 작업자 VM에 연결할 GPU 가속기 수입니다.
  • debug (불리언, 선택사항): debug를 true로 설정하면 맞춤설정이 완료되든 실패하든 Image Builder가 작업자 VM을 유지하므로 SSH를 사용하여 활성 인스턴스를 검사하거나 문제를 해결할 수 있습니다. 기본값은 false입니다.
  • instanceDurationHours (숫자, 선택사항): 작업자 VM 런타임을 제한합니다. 시간 제한은 맞춤설정이 완료되거나 스크립트 오류가 발생할 때 시작되므로 대화형 디버깅 세션 중에 활성 VM에 연결할 수 있습니다. 최대 2.0시간으로 제한됩니다.
  • reservations (문자열 배열, 선택사항): Image Builder가 VM을 생성할 때 사용할 용량 예약 리소스 이름 (예: 동일한 프로젝트의 test-reservation)입니다.
  • validationConcurrency (숫자, 선택사항): 임시 유효성 검사 테스트 컴퓨팅 인스턴스에서 동시에 실행할 유효성 검사 테스트의 최대 수를 지정합니다. 허용되는 값은 다음과 같습니다.
    • 0 또는 생략됨 (기본값): Image Builder가 머신 유형 및 가속기 구성을 기반으로 동시 실행을 자동 감지하고 다음과 같이 설정합니다.
      • GPU 가속기가 연결된 베어메탈 머신 유형 또는 구성의 경우 1 (순차적)를 사용하면 할당량 한도를 초과하거나 리소스가 소진되는 것을 방지할 수 있습니다.
      • 4 (병렬) - 기타 모든 머신 유형
    • 1: 검증 테스트를 순차적으로 실행합니다. 프로젝트의 지정된 machineType 할당량이 제한적인 경우 동시 실행을 1로 설정하면 여러 컴퓨팅 인스턴스가 동시에 시작되지 않으므로 유용할 수 있습니다.
    • 2 이상: 지정된 수의 유효성 검사 테스트를 병렬로 실행합니다. 용량이나 예약이 충분한 경우 동시 실행을 높이면 검증 테스트의 전체 실행 시간을 줄일 수 있습니다.

소스 이미지

Image Builder가 작업자 VM을 실행하는 데 사용하는 기본 운영체제 이미지를 식별합니다. 다음 옵션 중 하나를 지정해야 합니다.

표준 이미지 계열을 지정하려면 다음 단계를 따르세요.

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

직접 이미지 버전 URI를 지정하려면 다음 단계를 따르세요.

source:
  imagePath: projects/IMAGE_PROJECT/global/images/IMAGE_NAME
  • imageFamily(문자열): 표준 이미지 가족 그룹의 경로입니다(예: projects/ubuntu-os-cloud/global/images/family/ubuntu-2204-lts).
  • imagePath(문자열): 특정 Compute Engine 이미지 버전의 직접 리소스 URI입니다(예: projects/cos-cloud/global/images/cos-105-17412-226-28).

대상

컴파일된 맞춤 OS 이미지를 출시할 위치와 방법을 정의합니다. 이 속성에는 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 (문자열, 필수): 최종 Compute Engine 이미지 리소스에 할당된 기본 이름 접두사입니다. Image Builder는 이 접두사에 고유한 빌드 ID를 자동으로 추가하고 최종 이미지 이름을 63자로 자릅니다.
  • family (문자열, 선택사항): 새로 생성된 이미지에 적용할 이미지 계열입니다.
  • project (문자열, 필수사항): Image Builder가 출력 이미지를 쓰는 Cloud de Confiance 프로젝트입니다.
  • description (문자열, 선택사항): 생성된 이미지 메타데이터에 첨부된 설명 텍스트입니다.
  • licenses (문자열 배열, 선택사항): 이 이미지에 적용된 특정 소프트웨어 라이선스의 리소스 경로입니다.
  • labels (지도, 선택사항): env: production과 같은 태그 지정 메타데이터 키-값 쌍입니다.
  • signatureDatabaseFile (문자열, 선택사항): 보안 부팅 서명 데이터베이스 파일의 리소스 경로입니다.
  • storageLocations(문자열 배열, 선택사항): Compute Engine에서 최종 디스크 블록을 저장하는 대상 스토리지 리전 또는 멀티 리전입니다(예: us-central1 또는 us). 참고: 이 속성은 목록으로 형식이 지정되지만 이미지 대상당 하나의 위치만 지정할 수 있습니다.

사양 구성

일반 실행 옵션을 적용합니다.

spec:
  config:
    skipSystemTests: false
  • skipSystemTests (불리언, 선택사항): 테스트 VM이 부팅 조건, 네트워킹, UEFI 구조를 평가할지 전환합니다. 기본값은 false입니다.

사양 단계

Image Builder가 작업자 VM에서 순서대로 실행하는 단계 객체 목록을 지정합니다. 각 단계 유형의 전체 입력 매개변수 스키마와 사용 예시는 지원되는 맞춤설정 작업을 참고하세요.

모든 맞춤설정 단계 객체는 다음과 같은 공통 속성을 공유합니다.

spec:
  steps:
    - name: STEP_NAME
      action: ACTION_TYPE
      inputs:
        # Action-specific input parameters
  • name (문자열, 필수): 이 맞춤설정 단계의 사용자 정의 이름입니다.
  • action (문자열, 필수): 호출할 도우미 작업입니다. 지원되는 작업:
    • Shell: VM에서 터미널 스크립트를 실행합니다.
    • FileCopy: Cloud Storage 버킷 또는 워크스페이스에서 애셋을 전송합니다.
    • UpdateKernelCommandLine: 부팅 매개변수를 업데이트합니다.
    • InstallGPU: NVIDIA GPU 드라이버를 등록합니다.
  • inputs (객체, 필수): 선택한 작업에 필요한 키-값 속성입니다. 전체 파라미터 참조 및 예시는 지원되는 맞춤설정 작업을 참고하세요.

다음 스니펫은 Shell 작업을 사용하는 단계의 예를 보여줍니다.

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

다음 단계