환경 준비

Linux

참고: Image Builder는 일반적으로 제공되지만 사용하려면 프로젝트를 허용 목록에 추가해야 합니다. 액세스를 요청하려면 액세스 요청 양식을 제출하거나 Google Cloud계정팀에 문의하세요. 허용 목록은 프로젝트의 서비스 계정만 포함하며 Google 소유 서비스 계정은 포함하지 않습니다. 자세한 내용은 허용 목록에 포함된 서비스 계정을 참고하세요.

Image Builder 파이프라인을 만들기 전에 먼저 Google Cloud 환경을 준비해야 합니다. 환경을 준비하려면 다음 작업을 완료하세요.

• 온보딩 요청 제출하기
• 필요한 Cloud API 사용 설정
• Image Builder 서비스 계정 구성
• 신뢰할 수 있는 이미지 조직 정책 구성
• VPC 네트워크 및 액세스 요구사항 구성
• Artifact Registry 구성

시작하기 전에

• 아직 인증을 설정하지 않았다면 설정합니다. 인증은 Google Cloud 서비스 및 API에 액세스하기 위해 ID를 확인합니다. 로컬 개발 환경에서 코드 또는 샘플을 실행하려면 다음 옵션 중 하나를 선택하여 Compute Engine에 인증하면 됩니다.

  이 페이지의 샘플 사용 방법에 대한 탭을 선택하세요.

  콘솔

  Google Cloud 콘솔을 사용하여 Google Cloud 서비스 및 API에 액세스하는 경우 인증을 설정할 필요가 없습니다.

  gcloud

  1. Google Cloud CLI를 설치합니다. 설치 후 다음 명령어를 실행하여 Google Cloud CLI를 초기화합니다.

     gcloud init

     외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

     참고: 이전에 gcloud CLI를 설치했으면 gcloud components update를 실행하여 최신 버전이 설치되어 있는지 확인하세요.
• 기본 리전 및 영역을 설정합니다.

REST

로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공한 사용자 인증 정보를 사용합니다.

Google Cloud CLI를 설치합니다.

외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

자세한 내용은 Google Cloud 인증 문서의 REST 사용을 위한 인증을 참조하세요.

필요한 역할

환경을 준비하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

• 서비스 사용량 관리자(roles/serviceusage.serviceUsageAdmin)
• 프로젝트 ID 및 액세스 관리 (IAM) 관리자 (roles/resourcemanager.projectIamAdmin) 또는 서비스 계정 관리자 (roles/iam.serviceAccountAdmin)
• Artifact Registry 관리자(roles/artifactregistry.admin)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

온보딩 요청

Image Builder는 허용 목록 추가 방식으로 정식 제공되고 있습니다. 이미지 맞춤설정 파이프라인에 Google Cloud 프로젝트를 온보딩하려면 액세스 요청 양식을 제출하거나 Google Cloud 계정팀에 문의하세요.

허용 목록에 포함된 서비스 계정

허용 목록은 프로젝트 번호별로 프로젝트에 대한 액세스 권한을 부여합니다. 따라서 허용 목록에는 다음을 포함하는 서비스 계정만 포함됩니다.

• 프로젝트에서 만드는 사용자 관리 서비스 계정
• Compute Engine 기본 서비스 계정([e-mail])과 같이 Google Cloud 프로젝트에서 생성하는 기본 서비스 계정

허용 목록은 Google 소유 서비스 계정을 포함하지 않습니다.Google Cloud 에서 이러한 서비스 계정을 프로젝트가 아닌 Google 소유 프로젝트에 만들기 때문입니다. Google 소유 서비스 계정에는 다음이 포함됩니다.

• 서비스 에이전트(예: [e-mail])
• 기존 Cloud Build 서비스 계정([e-mail]): Google에서 소유하고 관리합니다.

이러한 서비스 계정 유형에 대한 자세한 내용은 서비스 계정 유형을 참고하세요.

빌드가 Google 소유 서비스 계정으로 실행되면 빌드에서 Artifact Registry의 Image Builder 오케스트레이터 컨테이너 이미지를 읽을 수 없습니다. 따라서 파이프라인이 권한 거부 오류로 인해 실패합니다. 이 오류를 방지하려면 프로젝트에서 만든 사용자 관리형 서비스 계정으로 파이프라인을 실행하고 빌드를 제출할 때 해당 서비스 계정을 지정하세요. 자세한 내용은 Image Builder 서비스 계정 구성 및 기본 Cloud Build 서비스 계정을 참고하세요.

API 사용 설정

Image Builder를 사용하려면 Compute Engine, Cloud Build, Artifact Registry, 서비스 사용량, Resource Manager API를 사용 설정해야 합니다. Google Cloud 콘솔 또는 Google Cloud CLI를 사용하여 API를 사용 설정하려면 다음 탭 중 하나를 선택하세요.

콘솔

Compute Engine, Cloud Build, Artifact Registry, 서비스 사용량, Cloud Resource Manager API를 아직 사용 설정하지 않은 경우 사용 설정합니다.

API 사용 설정에 필요한 역할

API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않은 경우 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할을 부여하는 방법 알아보기

API 사용 설정

gcloud

Compute Engine, Cloud Build, Artifact Registry, 서비스 사용량, Cloud Resource Manager API를 아직 사용 설정하지 않은 경우 사용 설정합니다.

API 사용 설정에 필요한 역할

API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않은 경우 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할을 부여하는 방법 알아보기

gcloud services enable compute.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com serviceusage.googleapis.com cloudresourcemanager.googleapis.com

Image Builder 서비스 계정 구성

Image Builder 오케스트레이터는 사용자 관리형 서비스 계정을 사용하여 실행됩니다. 이미지 빌드 파이프라인을 실행하면 Cloud Build가 이 서비스 계정을 임시 작업자 VM 및 테스트 VM 인스턴스에 연결하여 맞춤설정 및 검증 작업을 실행합니다. 이 서비스 계정에는 다음 역할이 필요합니다.

• Compute 관리자 (roles/compute.admin): VM 인스턴스, 영구 디스크, 게스트 OS 이미지를 관리합니다.
• 서비스 계정 사용자 (roles/iam.serviceAccountUser): Cloud Build가 서비스 계정을 임시 작업자 및 테스트 VM 인스턴스에 연결할 수 있습니다.
• 스토리지 관리자 (roles/storage.admin): Cloud Storage workdir 스테이징 버킷에서 임시 빌드 아티팩트와 로그를 읽고 씁니다.
• Logging 로그 작성자 (roles/logging.logWriter): 실행 로그를 Cloud Logging에 작성합니다.
• 서비스 사용량 뷰어 (roles/serviceusage.serviceUsageViewer): 파이프라인 실행 중에 프로젝트 서비스 상태를 확인합니다.
• Cloud Build 편집자 (roles/cloudbuild.builds.editor): Cloud Build 작업을 트리거하고 실행하며 이미지를 내보냅니다.
• (선택사항) Artifact Registry 관리자 (roles/artifactregistry.admin): 생성된 OS 이미지 tar 파일을 Artifact Registry에 업로드합니다.

기존 서비스 계정을 사용하거나 빌드 파이프라인을 위한 새 전용 서비스 계정을 만들 수 있습니다. 프로젝트에 있는 서비스 계정을 사용합니다. 이미지 빌더 허용 목록에 이러한 서비스 계정이 포함되지 않으므로 기존 Cloud Build 서비스 계정과 같은 Google 소유 서비스 계정으로 파이프라인을 실행하지 마세요. 자세한 내용은 허용 목록에 포함된 서비스 계정 및 기본 Cloud Build 서비스 계정을 참고하세요.

Google Cloud 콘솔 또는 gcloud CLI를 사용하여 새 전용 서비스 계정을 만들고 필요한 역할을 부여하려면 다음 탭 중 하나를 선택하세요.

콘솔

서비스 계정 만들기 IAM 역할(roles/iam.serviceAccountCreator)과 프로젝트 IAM 관리자 역할(roles/resourcemanager.projectIamAdmin)이 있는지 확인합니다. 역할 부여 방법 알아보기

1. Google Cloud 콘솔에서 서비스 계정 만들기 페이지로 이동합니다.

   서비스 계정 만들기로 이동
2. 프로젝트를 선택합니다.

3. 서비스 계정 이름 필드에 이름을 입력합니다. Google Cloud 콘솔은 이 이름을 기반으로 서비스 계정 ID 필드를 채웁니다.

   서비스 계정 설명 필드에 설명을 입력합니다. 예를 들면 Service account for quickstart입니다.

4. 만들고 계속하기를 클릭합니다.

5. 서비스 계정에 다음 역할을 부여합니다. Compute Engine > Compute 관리자, 서비스 계정 > 서비스 계정 사용자, Cloud Storage > 스토리지 관리자, Cloud Logging > 로그 작성자, 서비스 사용량 > 서비스 사용량 뷰어, Cloud Build > Cloud Build 편집자, Artifact Registry > Artifact Registry 관리자

   역할을 부여하려면 역할 선택 목록을 찾은 후 역할을 선택합니다.

   역할을 추가로 부여하려면 다른 역할 추가를 클릭하고 각 역할을 추가합니다.

   참고: 역할 필드는 서비스 계정이 프로젝트에서 액세스할 수 있는 리소스에 영향을 줍니다. 이러한 역할을 취소하거나 나중에 추가 역할을 부여할 수 있습니다.
6. 계속을 클릭합니다.

7. 서비스 계정 사용자 역할 필드에 서비스 계정을 Compute Engine 인스턴스와 같은 다른 리소스에 연결할 주 구성원의 식별자를 입력합니다.

   일반적으로 Google 계정의 이메일 주소입니다.

8. 완료를 클릭하여 서비스 계정 만들기를 마칩니다.

gcloud

1. 빌드 파이프라인의 서비스 계정을 만듭니다.

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
       --display-name="Image Builder Service Account"
   

2. 서비스 계정에 필요한 역할 (roles/compute.admin, roles/iam.serviceAccountUser, roles/storage.admin, roles/logging.logWriter, roles/serviceusage.serviceUsageViewer, roles/cloudbuild.builds.editor)을 부여합니다.

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
       --role="roles/compute.admin"
   
   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
       --role="roles/iam.serviceAccountUser"
   
   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
       --role="roles/storage.admin"
   
   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
       --role="roles/logging.logWriter"
   
   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
       --role="roles/serviceusage.serviceUsageViewer"
   
   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
       --role="roles/cloudbuild.builds.editor"
   

3. 선택사항: 서비스 계정에 선택적 역할 (roles/artifactregistry.admin)을 부여합니다.

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
       --role="roles/artifactregistry.admin"
   

다음을 바꿉니다.

• SERVICE_ACCOUNT_NAME: 생성할 빌드 서비스 계정의 이름입니다. 예를 들면 custom-builder-sa입니다.
• PROJECT_ID: Google Cloud 프로젝트 ID입니다.
• SERVICE_ACCOUNT_EMAIL: 빌드 서비스 계정의 이메일 주소입니다.

신뢰할 수 있는 이미지 조직 정책 구성

Image Builder는 빌드 실행 중에 표준 Compute Engine 이미지 가져오기 및 내보내기 도구를 내부적으로 사용하므로 프로젝트의 신뢰할 수 있는 이미지 정책 (compute.trustedImageProjects)에서 다음 프로젝트의 이미지를 명시적으로 허용해야 합니다.

• projects/compute-image-import

조직 정책에서 이 프로젝트를 제한하는 경우 이미지 내보내기 단계가 실패합니다.

조직 정책을 업데이트하려면 다음 단계를 따르세요.

1. compute.trustedImageProjects 제약 조건에 대한 조직 정책에서 허용된 게시자 목록에 projects/compute-image-import를 추가합니다.
2. 조직 정책 제약 조건을 구성하는 방법에 관한 자세한 안내는 신뢰할 수 있는 이미지 정책 설정 및 커스텀 이미지를 Cloud Storage로 내보내기를 참고하세요.

VPC 네트워크 및 액세스 요구사항 구성

빌드 및 검증 단계에서 Image Builder는 Google Cloud 프로젝트에 임시 작업자 및 테스트 VM을 프로비저닝합니다. 기본적으로 Image Builder는 인스턴스를 default VPC 네트워크에 연결하고 임시 외부 IP 주소를 할당합니다.

imagebuilder.yaml 레시피 파일에서 맞춤 network 또는 subnetwork를 지정하거나 externalIP: none를 구성하는 경우:

• 비공개 Google 액세스 및 Cloud NAT: 작업자 또는 테스트 VM이 externalIP: none (외부 IP 없음)로 구성된 경우 인스턴스가 Google API 및 서비스 (예: Cloud Storage 및 Artifact Registry)에 연결할 수 있도록 VPC 서브네트워크에 비공개 Google 액세스가 사용 설정되어 있어야 합니다. 맞춤설정 단계에서 외부 인터넷 저장소에서 OS 패키지 또는 종속 항목을 다운로드하는 경우 서브넷에서 Cloud NAT도 구성해야 합니다.
• 방화벽 규칙: VPC 방화벽 규칙이 Google API 및 필요한 소프트웨어 저장소로의 이그레스 트래픽을 허용하는지 확인합니다. 활성 작업자 VM에 연결하여 대화형 디버깅(debug: true)을 하려는 경우 방화벽 규칙이 TCP 포트 22에서 인그레스를 허용하는지 확인하세요. VM 인스턴스에 외부 IP가 없는 경우 TCP 전달을 위해 Identity-Aware Proxy (IAP) IP 범위 35.235.240.0/20로부터의 인그레스를 허용합니다.

Artifact Registry 구성

커스텀 OS 이미지, 보안 메타데이터, SLSA 빌드 출처 증명을 저장하고 관리하려면 Artifact Registry에 일반 저장소를 설정해야 합니다. Artifact Registry에 이미지를 저장하면 게시된 이미지의 보안이 유지되고 변경할 수 없는 기록을 유지할 수 있습니다.

Artifact Registry 대상을 구성하면 Image Builder는 다음 단계를 실행합니다.

• 완료된 VM 부팅 디스크를 표준 tar 파일 (.tar.gz)로 내보냅니다.
• Artifact Registry의 일반 저장소에 tar 파일을 업로드합니다.
• 아티팩트의 SLSA 빌드 출처 기록 증명을 생성하고 서명하여 소스 메타데이터에 연결합니다.
• Artifact Registry tar 파일 URI를 템플릿 소스로 사용하여 프로덕션 준비가 완료된 Compute Engine 이미지를 Compute Engine에 등록합니다.

일반 Artifact Registry를 구성하려면 다음 작업을 완료하세요.

1. Image Builder 파이프라인을 실행하는 데 사용되는 서비스 계정에 저장소 또는 프로젝트 수준에서 Artifact Registry 관리자 역할(roles/artifactregistry.admin)이 있는지 확인합니다. 자세한 내용은 Image Builder 서비스 계정 구성을 참고하세요.

2. generic 형식의 저장소를 만듭니다. 저장소를 만들려면 gcloud artifacts repositories create 명령어를 실행합니다.

   gcloud artifacts repositories create REPOSITORY_NAME \
       --repository-format=generic \
       --location=REPOSITORY_LOCATION
   

   다음 자리표시자를 바꿉니다.

   • REPOSITORY_NAME: 일반 저장소의 이름입니다. 예를 들면 custom-os-images입니다.
   • REPOSITORY_LOCATION: 지원되는 지역 예를 들면 us-central1입니다.

다음 단계

• Google Cloud 콘솔을 사용하여 파이프라인을 만들고 관리합니다.
• 프로그래매틱 방식으로 파이프라인 만들기 및 관리
• 맞춤설정 레시피 스키마에서 맞춤설정 레시피를 정의하는 방법을 알아보세요.
• 빌드 구성 (cloudbuild.yaml) 파일 구조를 검토합니다.