Google Cloud 빌드 및 배포 변경사항

이 문서에서는 Cloud Build로 컨테이너 이미지를 빌드하고 Cloud Run 또는 Google Kubernetes Engine과 같은 Google Cloud 런타임 환경에 배포할 때 Container Registry와 Artifact Registry의 차이점을 설명합니다.

이 가이드에서는 표준 Artifact Registry 저장소, Container Registry와 별개로 모든 아티팩트 레지스트리 기능을 지원하는 일반 Artifact Registry 저장소를 비교합니다. 관리자가 gcr.io 도메인 지원이 포함된 저장소를 설정한 경우 gcr.io 호스트 이름에 대한 요청이 해당 Artifact Registry 저장소로 자동으로 리디렉션되고 Container Registry에 액세스할 수 있는 기본 서비스 계정에 Artifact Registry에 대해 상응하는 기본 권한이 포함됩니다.

Docker 클라이언트를 사용하는 Container Registry와 Artifact Registry의 차이점에 대한 자세한 내용은 Docker를 사용한 가져오기 및 내보내기 변경사항을 참조하세요.

이 정보를 사용하여 Container Registry와 관련된 기존 명령어, 구성 또는 문서를 Cloud Build에 맞게 조정할 수 있습니다.

시작하기 전에

이 문서에서는 다음 작업이 완료되었다고 가정합니다.

1. 프로젝트에서 Artifact Registry 사용 설정
2. Artifact Registry에서 사용 중인 다른 Google Cloud 서비스에 대해 Cloud Build API 및 API 사용 설정

워크플로 변경사항

같은 프로젝트 내에서 Container Registry와 함께 Cloud Build를 사용하는 경우 워크플로는 다음과 같습니다.

1. Dockerfile 또는 빌드 구성 파일을 사용하여 Cloud Build에서 이미지를 저장소에 빌드, 태그 푸시합니다.

   다음 예시에서는 my-image 이미지를 빌드하고 tag1로 태그를 지정하고 my-project 프로젝트의 gcr.io 호스트에 푸시합니다.

   gcloud builds submit --tag gcr.io/my-project/my-image:tag1
   

2. Cloud Run 및 Google Kubernetes Engine과 같은 Google Cloud 런타임 환경은 레지스트리에서 이미지를 가져옵니다.

   예를 들어 이 명령어는 이전 단계의 이미지를 my-service로 Cloud Run에 배포합니다.

   gcloud run deploy my-service --image gcr.io/my-project/my-image:tag1
   

Container Registry 워크플로는 관리자의 책임을 빌드 및 배포와 결합합니다.

• 일부 Google Cloud API를 사용 설정하면 Container Registry API가 자동으로 사용 설정됩니다. 즉, 이러한 서비스 사용자에게 동일 프로젝트에 있는 Container Registry에 대한 암시적 액세스 권한이 포함됩니다. 예를 들어 Cloud Build에서 빌드를 실행할 수 있는 사용자는 기본적으로 레지스트리에 이미지를 내보내고 레지스트리 호스트를 추가할 수 있습니다.
• Cloud Build 서비스 계정에는 Cloud Storage 스토리지 버킷을 만들 수 있는 권한이 포함되어 있습니다. 즉, 이 계정은 이미지를 처음으로 호스트에 푸시할 때 Container Registry 호스트를 프로젝트에 자동으로 추가할 수 있습니다. 또한 계정은 Container Registry에서 사용하지 않는 버킷을 포함하여 전체 프로젝트에서 스토리지 버킷을 생성하고 읽고 쓸 수 있습니다.

Artifact Registry에서는 빌드 및 배포 워크플로의 단계를 변경하는 관리자 역할과 빌드 역할이 명확하게 분리되어 있습니다. Artifact Registry에 맞게 Container Registry 워크플로를 조정하려면 다음과 같이 변경합니다. 각 단계는 워크플로 수정을 위한 추가 정보로 연결됩니다.

1. 신규: Artifact Registry API를 사용 설정합니다.

   Artifact Registry API를 사용 설정해야 합니다. Cloud Build와 Cloud Run 및 GKE와 같은 런타임 환경에서는 API가 자동으로 사용 설정되지 않습니다.

2. 신규: 대상 Docker 저장소를 만듭니다(아직 없는 경우). 이미지를 내보내려면 먼저 저장소를 만들어야 합니다. 이미지를 내보내면 저장소 만들기가 트리거되지 않으며 Cloud Build 서비스 계정에 저장소를 만들 권한이 없습니다.

3. 변경: Dockerfile 또는 빌드 구성 파일을 사용하여 Cloud Build에서 이미지를 저장소에 빌드, 태그 푸시합니다.

   다음 예시 명령어는 Container Registry 예시와 동일하지만 이미지에 대해 Artifact Registry 저장소 경로를 사용합니다.

   gcloud builds submit --tag us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
   

4. 변경: Cloud Run 또는 GKE와 같은 Google Cloud 런타임 환경에 이미지를 배포합니다.

   다음 예시 명령어는 Container Registry 예시와 동일하지만 이미지에 대해 Artifact Registry 저장소 경로를 사용합니다.

   gcloud run deploy my-service --image us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
   

또한 Artifact Registry는 Container Registry와 다른 역할을 사용하여 이미지에 대한 액세스를 제어합니다. 다음과 같은 상황에서는 권한을 구성해야 합니다.

• Cloud Build 또는 Google Cloud 런타임 환경은 Artifact Registry와 다른 프로젝트에 있습니다.
• 기본 서비스 계정 대신 Cloud Build 또는 GKE와 같은 Google Cloud 서비스에 커스텀 서비스 계정을 사용합니다.
• 다른 사용자나 서비스 계정에 권한을 부여한 경우

API 사용 설정

핵심 사항:

• Cloud Build, Cloud Run, GKE와 같은 다른 Google Cloud 서비스에 대한 API 외에도 Artifact Registry API를 사용 설정해야 합니다.

다음 비교 정보는 각 서비스의 API 사용 설정에 대해 설명합니다.

Container Registry

다음 Google Cloud API를 사용 설정하면 Container Registry API도 자동으로 사용 설정됩니다.

• App Engine 가변형 환경
• Cloud Build
• Cloud Functions
• Cloud Run
• Artifact Analysis의 Container Scanning 또는 On-Demand Scanning
• Google Kubernetes Engine

기본 권한이 있으면 Cloud Build에서 빌드를 실행하거나 Artifact Analysis를 사용하여 컨테이너를 스캔하거나, Google Cloud 런타임에 컨테이너를 배포할 수 있는 사용자는 레지스트리가 동일한 프로젝트에 있을 때 Container Registry의 이미지에 암묵적으로 액세스할 수 있습니다.

Artifact Registry

Artifact Registry API를 사용 설정해야 합니다. Cloud Build, Cloud Run, GKE와 같은 서비스는 Artifact Registry API를 자동으로 사용 설정하지 않습니다.

gcloud를 사용하여 동일한 프로젝트에서 여러 API를 사용 설정할 수 있습니다. 예를 들어 Cloud Build API 및 Artifact Registry API를 사용 설정하려면 다음 명령어를 실행합니다.

gcloud services enable
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com

레지스트리 및 저장소 추가

핵심 사항:

• 이미지를 내보내려면 먼저 Artifact Registry Docker 저장소를 만들어야 합니다.
• Container Registry는 동일한 스토리지 버킷의 단일 멀티 리전에 모든 이미지를 저장합니다. Artifact Registry에서는 개별 액세스 정책이 있는 동일 리전 또는 멀티 리전에서 여러 저장소를 만들 수 있습니다.

다음 비교에서는 각 서비스의 저장소 설정에 대해 설명합니다.

Container Registry

Container Registry에서는 프로젝트에 최대 4개의 레지스트리 호스트를 추가할 수 있습니다. 첫 번째 이미지를 내보내서 레지스트리 호스트를 추가합니다.

1. gcr.io와 같은 레지스트리를 프로젝트에 추가하기 위해 프로젝트 수준에서 스토리지 관리자 역할이 있는 계정이 초기 이미지를 내보냅니다.

   예를 들어 my-project 프로젝트에 gcr.io 호스트가 없는 경우 이미지 gcr.io/my-project/my-image:1.0을 내보내면 다음 단계가 트리거됩니다.

   1. 프로젝트에 gcr.io 호스트를 추가합니다.
   2. 프로젝트에서 gcr.io에 대해 스토리지 버킷을 만듭니다.
   3. 이미지를 gcr.io/my-project/my-image:1.0으로 저장합니다.

2. 이러한 초기 내보내기 이후 다른 사용자에 대해 스토리지 버킷에 권한을 부여할 수 있습니다.

기본적으로 Cloud Build에는 스토리지 버킷을 만드는 데 필요한 권한이 있으므로 초기 이미지 푸시 및 후속 푸시를 식별할 수 없습니다.

프로젝트 내에서 레지스트리 호스트는 모든 이미지를 동일한 스토리지 버킷에 저장합니다. 다음 예시에서는 my-project 프로젝트의 gcr.io 레지스트리에 web-app이라는 이미지 두 개가 있습니다. 하나는 프로젝트 ID my-project 바로 아래에 있습니다. 다른 이미지는 team1 저장소에 있습니다.

gcr.io/my-project/web-app
gcr.io/my-project/team1/web-app

Artifact Registry

Cloud Build에는 Artifact Registry pkg.dev 도메인에서 표준 저장소를 만들 수 있는 권한이 없습니다.

이미지를 내보내려면 먼저 Artifact Registry 저장소 관리자 역할이 있는 계정으로 저장소를 만들어야 합니다. 그런 다음 다른 사용자에 대해 저장소에 권한을 부여할 수 있습니다.

Artifact Registry에서 각 저장소는 별개의 리소스입니다. 따라서 모든 이미지 경로에 저장소가 있어야 합니다.

올바른 이미지 경로:

us-central1-docker.pkg.dev/my-project/team1/web-app:1.0
us-central1-docker.pkg.dev/my-project/team2/web-app:1.0

잘못된 이미지 경로(저장소는 포함되지 않음):

us-central1-docker.pkg.dev/my-project/web-app:1.0

다음 예시는 누락된 저장소에 이미지 내보내기가 실패하는 상황을 보여줍니다.

• us-central1-docker.pkg.dev/my-project/team1이 없으면 이미지를 us-central1-docker.pkg.dev/my-project/team1로 푸시합니다.
• us-central1-docker.pkg.dev/my-project/team1이 있을 때 이미지를 us-central1-docker.pkg.dev/my-project/team2로 내보내기는 하지만 us-central1-docker.pkg.dev/my-project/team2가 없습니다.

권한 부여

핵심 사항:

• Google Cloud 서비스에는 Container Registry 및 Artifact Registry 모두에 대해 상응하는 읽기 또는 쓰기 액세스 권한이 있습니다. 그러나 기본 Cloud Build 서비스 계정은 pkg.dev 도메인에서 표준 저장소를 만들 수 없습니다.
• Artifact Registry에 액세스하는 다른 계정에 적합한 Artifact Registry 역할을 부여합니다.
• Container Registry는 저장소 버킷 수준에서 액세스 제어를 지원합니다. Artifact Registry는 저장소 수준에서 액세스 제어를 지원합니다.

다음 비교는 각 서비스의 권한을 설명합니다.

Container Registry

Container Registry는 Cloud Storage 역할을 사용하여 액세스를 제어합니다. Cloud Build에는 스토리지 관리자 역할에 프로젝트에 Container Registry 호스트를 추가하는 데 필요한 권한이 있습니다.

스토리지 버킷 수준의 스토리지 객체 뷰어

프로젝트의 기존 레지스트리 호스트에서 이미지를 가져옵니다(읽기).

스토리지 버킷 수준의 스토리지 레거시 버킷 작성자

프로젝트의 기존 레지스트리 호스트에 대한 이미지를 내보내고(쓰기) 가져옵니다(읽기).

프로젝트 수준의 스토리지 관리자

초기 이미지를 호스트에 내보내 레지스트리 호스트를 프로젝트에 추가합니다.

초기 이미지를 레지스트리로 내보낸 후에는 스토리지 버킷에 액세스해야 하는 다른 계정에 Cloud Storage 역할을 부여합니다. 스토리지 관리자 역할의 모든 권한이 있는 어떤 계정이든 전체 프로젝트에서 스토리지 버킷 및 스토리지 객체를 읽고, 쓰고, 삭제할 수 있습니다.

스토리지 버킷의 권한은 레지스트리에 있는 모든 저장소에 적용됩니다. 예를 들어 gcr.io/my-project의 버킷에서 스토리지 객체 뷰어 권한이 있는 사용자는 이러한 모든 저장소에서 이미지를 읽을 수 있습니다.

gcr.io/my-project/team1
gcr.io/my-project/team2
gcr.io/my-project/test
gcr.io/my-project/production

Artifact Registry

Artifact Registry에는 액세스 제어를 위한 자체 역할이 있습니다. 이러한 역할에 따라 관리자 및 저장소 사용자 역할이 명확하게 구분됩니다.

Cloud Build는 pkg.dev 도메인에서 표준 저장소로 이미지를 내보내고 가져오기만 수행하면 되기 때문에 Artifact Registry 작성자 역할의 권한이 포함되어 있습니다.

저장소를 관리하는 계정에만 Artifact Registry 저장소 관리자 또는 Artifact Registry 관리자 역할이 포함됩니다.

Artifact Registry 리더

아티팩트 및 저장소를 나열합니다. 아티팩트를 다운로드합니다.

Artifact Registry 작성자

아티팩트 및 저장소를 나열합니다. 아티팩트를 다운로드하고, 새 아티팩트 버전을 업로드하고, 태그를 추가하거나 업데이트합니다.

Artifact Registry 저장소 관리자

Artifact Registry 작성자 권한 및 아티팩트 및 태그를 삭제하는 권한입니다.

Artifact Registry 관리자

Artifact Registry 저장소 관리자 권한과 저장소의 생성, 업데이트, 삭제 권한과 이러한 권한을 부여할 수 있는 권한입니다.

저장소 수준에서 이러한 권한을 적용할 수 있습니다. 예를 들면 다음과 같습니다.

• us-central1-docker.pkg.dev/my-project/team1의 팀 1에 액세스 권한을 부여합니다.
• us-central1-docker.pkg.dev/my-project/team2의 팀 2에 액세스 권한을 부여합니다.

Artifact Registry 권한 부여에 대한 자세한 내용은 액세스 제어 문서를 참조하세요.

이미지 빌드 및 내보내기

핵심 사항:

• 이미지를 내보내려면 먼저 Artifact Registry Docker 저장소를 만들어야 합니다.
• Artifact Registry 호스트 이름은 Container Registry 호스트 이름과 다릅니다.

Cloud Build는 한 번에 이미지를 빌드, 태그 지정, 푸시할 수 있습니다.

Container Registry를 사용하면 Cloud Build가 Google Cloud 프로젝트에 아직 존재하지 않는 레지스트리 호스트로 이미지를 성공적으로 내보낼 수 있습니다. 초기 이미지 내보내기의 경우 Cloud Build에 프로젝트에 레지스트리 호스트를 자동으로 추가할 수 있는 권한이 있습니다.

Container Registry 워크플로를 조정하려면 다음 안내를 따르세요.

1. 이미지를 내보내기 전에 저장소를 설정합니다.
2. 빌드 구성 파일 또는 gcloud builds submit 명령어의 이미지 경로를 업데이트합니다.

빌드 구성 파일로 빌드

빌드할 이미지의 Container Registry 경로를 기존 Artifact Registry 저장소의 경로로 바꿉니다.

다음 예시 cloudbuild.yaml 파일은 us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1 이미지를 빌드합니다.

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: [ 'build', '-t', 'us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1', '.' ]
images:
- 'us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1'

그런 후 다음 명령어로 이미지를 빌드할 수 있습니다.

gcloud builds submit --config cloudbuild.yaml

Dockerfile로 빌드

빌드할 이미지의 Container Registry 경로를 기존 Artifact Registry 저장소의 경로로 바꿉니다.

다음 예시 명령어는 현재 디렉터리에서 Dockerfile을 사용하여 us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1 이미지를 빌드합니다.

gcloud builds submit --tag us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

이미지 배포

요점:

• Artifact Registry 호스트 이름은 Container Registry 호스트 이름과 다릅니다.

Container Registry 워크플로를 조정하려면 배포 구성 및 배포 명령어에서 이미지 경로를 업데이트합니다. 다음 섹션에서는 Cloud Build, Cloud Run, GKE의 예시를 보여주지만 이미지를 배포하는 다른 Google Cloud 서비스에도 동일한 방법이 적용됩니다.

Cloud Build

배포하는 이미지의 Container Registry 경로를 기존 Artifact Registry 저장소의 경로로 바꿉니다.

다음 cloudbuild.yaml 파일 예시에서는 샘플 이미지 us-docker.pkg.dev/cloudrun/container/hello를 배포합니다.

steps:
- name: 'gcr.io/cloud-builders/gcloud'
  args:
  - 'run'
  - 'deploy'
  - 'cloudrunservice'
  - '--image'
  - 'us-docker.pkg.dev/cloudrun/container/hello'
  - '--region'
  - 'us-central1'
  - '--platform'
  - 'managed'
  - '--allow-unauthenticated'

Cloud Run

배포하는 이미지의 Container Registry 경로를 기존 Artifact Registry 저장소의 경로로 바꿉니다.

예를 들어 이 명령어는 샘플 이미지 us-docker.pkg.dev/cloudrun/container/hello를 배포합니다.

gcloud run deploy my-service --image us-docker.pkg.dev/cloudrun/container/hello

GKE

빌드할 이미지의 Container Registry 경로를 기존 Artifact Registry 저장소의 경로로 바꿉니다.

Artifact Registry의 다음 예시에서는 샘플 이미지 us-docker.pkg.dev/artifact-registry-samples/containers/gke/hello-app:1.0을 사용합니다.

명령줄에서 클러스터 만들기:

kubectl create deployment hello-server --image=us-docker.pkg.dev/artifact-registry-samples/containers/gke/hello-app:1.0

배포 매니페스트에서 이미지 지정:

In a deployment manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      run: my-app
  template:
    metadata:
      labels:
        run: my-app
    spec:
      containers:
      - name: hello-app
        image: us-docker.pkg.dev/artifact-registry-samples/containers/gke/hello-app:1.0