이미지 맞춤설정 파일

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

스키마 개요

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

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

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)

메타데이터

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

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: nvidia-l4
  acceleratorCount: 1
  debug: false
  instanceDurationHours: 2.0
  reservations:
    - RESERVATION_NAME
  • 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: 외부 IP 주소가 없는 VM을 만듭니다. 비공개 VPC 네트워킹만 사용합니다. none으로 설정하면 VM이 required Google Cloud services 및 패키지 저장소에 액세스할 수 있도록 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).

소스 이미지

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:
        - us-central1
  • name (문자열, 필수): 최종 Compute Engine 이미지 리소스에 할당된 기본 이름 프리픽스입니다. Image Builder는 이 프리픽스에 고유한 빌드 ID를 자동으로 추가하고 최종 이미지 이름을 63자로 자릅니다.
  • family (문자열, 선택사항): 새로 생성된 이미지에 적용할 이미지 계열입니다.
  • project (문자열, 필수): Image Builder가 출력 이미지를 쓰는 Google Cloud 프로젝트입니다.
  • 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..."

다음 단계