기본적으로 Artifact Registry에서 호스팅되는 gcr.io

Artifact Registry에서 gcr.io 저장소를 설정하는 방법을 알아보고 Artifact Registry와 Container Registry 권한 사이의 차이점 그리고 스토리지 버킷 구성에 대해 알아봅니다.

이 문서에서 설명하는 수동 단계는 자동 마이그레이션 도구를 사용하여 완료할 수 있습니다. 자동 마이그레이션 도구를 사용해서 현재 Container Registry를 사용 중인 프로젝트를 Artifact Registry 표준 저장소 또는 gcr.io 저장소로 전환하고 싶으면 Artifact Registry로 마이그레이션 자동화를 참조하세요.

Container Registry 지원 중단

2024년 5월 15일 이전에 Container Registry를 사용하지 않은 Google Cloud 프로젝트는 Artifact Registry에서 이미지 호스팅 및 관리만 지원합니다. 이 변경사항은 다음에 영향을 미칩니다.

새로 만든 프로젝트
이미지를 Container Registry로 내보내지 않은 기존 프로젝트

2024년 1월 8일 이전에 Container Registry를 사용한 적이 없는 조직의 경우 기본적으로 Artifact Registry에서 새로운 gcr.io 저장소가 호스팅됩니다.

이러한 프로젝트에서 Artifact Registry API를 사용 설정하면 Artifact Registry는 Artifact Registry의 gcr.io 저장소 생성을 자동으로 처리하고 gcr.io 도메인에 대한 요청을 적절한 Artifact Registry 저장소로 리디렉션합니다. 현재 Container Registry를 사용 중인 프로젝트의 기존 gcr.io 도메인 지원과 달리 Artifact Registry로의 리디렉션은 자동으로 수행됩니다.

2024년 5월 15일 이전에 다음 작업 중 하나가 발생한 프로젝트에서도 Container Registry를 계속 사용할 수 있습니다.

프로젝트에서 Container Registry API를 사용 설정했습니다.
프로젝트의 레지스트리 호스트로 이미지를 내보냈습니다.

예정된 변경에 대비하기 위해서는 다음이 권장됩니다.

이 문서의 안내에 따라 Container Registry를 사용하지 않는 프로젝트를 구성하여 변경사항이 적용될 때 gcr.io 요청을 자동으로 처리할 수 있게 합니다.
gcr.io 도메인 지원을 테스트하여 기존 자동화가 계속 작동하는지 확인합니다.

Artifact Registry에서 호스팅되는 gcr.io 저장소는 Container Registry가 지원하는 동일한 멀티 리전에 생성됩니다. 다른 리전에 이미지를 저장하려면 pkg.dev 도메인에서 표준 저장소로 전환해야 합니다.

필요한 역할

'gcr.io' 저장소를 설정하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

Artifact Registry 저장소를 만들고 개별 저장소에 액세스 권한 부여: 프로젝트의 Artifact Registry 관리자(roles/artifactregistry.admin)
Cloud Storage 스토리지 버킷에 적용된 기존 Container Registry 구성 보기 및 관리: 프로젝트의 스토리지 관리자 (roles/storage.admin)
프로젝트 수준에서 저장소 액세스 권한 부여: 프로젝트, 폴더 또는 조직에 대하여 프로젝트 IAM 관리자(roles/resourcemanager.projectIamAdmin) 또는 폴더 관리자(roles/resourcemanager.folderAdmin)나 조직 관리자(roles/resourcemanager.organizationAdmin) 등에 상응하는 권한이 포함된 역할
조직의 사용 설정된 서비스 나열: 조직의 Cloud 애셋 뷰어(roles/cloudasset.viewer)

역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

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

시작하기 전에

하나 이상의 이미지가 Container Registry에 저장된 프로젝트를 나열할 수 있습니다. 그런 후 이 문서의 안내에 따라 Artifact Registry에 gcr.io 요청을 호스팅하기 위해 다른 프로젝트를 설정하는 데 집중할 수 있습니다.

다음 명령어를 실행하여 Google Cloud 조직에서 Container Registry 사용량을 찾습니다.

  gcloud container images list-gcr-usage \
      --organization=ORGANIZATION

ORGANIZATION을 Google Cloud 조직 ID로 바꿉니다.

또한 프로젝트 또는 폴더의 Container Registry 사용량을 나열할 수 있습니다. Container Registry 사용량을 찾는 방법은 Container Registry 사용량 확인을 참조하세요.

API 사용 설정

자동 gcr.io 호스팅이 수행될 때 gcr.io 도메인 요청이 Artifact Registry에서 자동으로 처리되도록 Artifact Registry API를 사용 설정합니다.

다음 명령어를 실행합니다.

gcloud services enable \
    artifactregistry.googleapis.com

Container Registry API를 일반적으로 VPC 서비스 제어 서비스 경계에 배치하는 경우 Artifact Registry API도 경계에 배치해야 합니다. 자세한 내용은 서비스 경계에서 저장소 보호를 참조하세요.

저장소에 권한 부여

Container Registry는 Cloud Storage 역할을 사용하여 액세스를 제어합니다. Artifact Registry에는 자체 IAM 역할이 있으며 이러한 역할은 Container Registry보다 읽기, 쓰기, 저장소 관리 역할을 더 명확하게 구분합니다.

스토리지 버킷에 부여된 기존 권한을 제안된 Artifact Registry 역할에 빠르게 매핑하려면 역할 매핑 도구를 사용하세요.

또는 Google Cloud 콘솔을 사용하여 스토리지 버킷에 액세스할 수 있는 주 구성원 목록을 볼 수 있습니다.

Google Cloud 콘솔에서 Cloud Storage 버킷 페이지로 이동합니다.
버킷으로 이동
보려는 레지스트리 호스트의 스토리지 버킷을 클릭합니다. 버킷 이름에서 PROJECT-ID는 Google Cloud 프로젝트 ID입니다.
- gcr.io: artifacts.PROJECT-ID.appspot.com
- asia.gcr.io: asia.artifacts.PROJECT-ID.appspot.com
- eu.gcr.io: eu.artifacts.PROJECT-ID.appspot.com
- us.gcr.io: us.artifacts.PROJECT-ID.appspot.com
권한 탭을 클릭합니다.
권한 탭에서 역할별 보기 하위 탭을 클릭합니다.
역할을 확장하여 해당 역할이 있는 주 구성원을 확인합니다.

이 목록에는 버킷에서 직접 부여된 IAM 역할과 상위 프로젝트에서 상속된 역할이 포함됩니다. 역할에 따라 부여할 가장 적절한 Artifact Registry 역할을 선택할 수 있습니다.

Cloud Storage 및 기본 역할

현재 Container Registry에 액세스하는 사용자 및 서비스 계정에 Artifact Registry 저장소 액세스 권한을 부여합니다. 상위 프로젝트에서 상속된 Cloud Storage 역할의 경우 주 구성원이 현재 Container Registry를 사용하는지 확인해야 합니다. 일부 주 구성원은 Container Registry와 관련이 없는 다른 Cloud Storage 버킷에만 액세스할 수 있습니다.

IAM 이전에 존재하는 기본 역할 소유자, 편집자, 뷰어는 스토리지 버킷에 대해 제한된 액세스 권한을 갖습니다. 이것들은 본질적으로 이름이 암시하는 Cloud Storage 리소스에 대한 모든 액세스 권한을 부여하고 다른 Google Cloud 서비스에 대한 추가 권한을 제공합니다. 사용자 및 서비스 계정에 Artifact Registry 액세스 권한이 필요한지 확인하고 역할 매핑 테이블을 사용하여 Artifact Registry 액세스가 적합한 경우 올바른 권한을 부여하도록 합니다.

다음 표에서는 Container Registry 액세스에 대해 미리 정의된 Cloud Storage 역할로 부여되는 권한에 따라 Artifact Registry 역할을 매핑합니다.

필수 액세스 권한	현재 역할	Artifact Registry 역할	역할을 부여할 위치
이미지 가져오기 전용(읽기 전용)	스토리지 객체 뷰어 (`roles/storage.objectViewer`)	Artifact Registry 리더 (`roles/artifactregistry.reader)`	Artifact Registry 저장소 또는 Google Cloud 프로젝트
이미지 내보내기 및 가져오기(읽기 및 쓰기) 이미지 삭제	스토리지 기존 버킷 작성자 (`roles/storage.legacyBucketWriter`)	Artifact Registry 저장소 관리자 (`roles/artifactregistry.repoAdmin)`	Artifact Registry 저장소 또는 Google Cloud 프로젝트
프로젝트의 gcr.io 호스트 이름에 이미지를 처음 내보낼 때 Artifact Registry에서 gcr.io 저장소를 만듭니다.	스토리지 관리자 (`roles/storage.admin`)	Artifact Registry Create-on-push 저장소 관리자 `(roles/artifactregistry.createOnPushRepoAdmin)`	Google Cloud 프로젝트
저장소 만들기, 관리, 삭제	스토리지 관리자 (`roles/storage.admin`)	Artifact Registry 관리자 `(roles/artifactregistry.Admin)`	Google Cloud 프로젝트

프로젝트에서 상속된 서비스 에이전트 역할

Google Cloud 서비스의 기본 서비스 계정에는 프로젝트 수준에서 부여된 자체 역할이 있습니다. 예를 들어 Cloud Run용 서비스 에이전트에는 Cloud Run 서비스 에이전트 역할이 있습니다.

대부분의 경우 이러한 서비스 에이전트 역할에는 Container Registry 및 Artifact Registry에 대한 동일한 기본 권한이 포함되어 있으므로 기존 Container Registry 서비스와 동일한 프로젝트에서 Artifact Registry를 실행하는 경우 추가로 변경할 필요가 없습니다.

서비스 에이전트 역할의 권한에 대한 자세한 내용은 서비스 에이전트 역할 참조를 확인하세요.

커스텀 역할

역할 매핑 테이블을 사용하여 필요한 액세스 수준에 따라 사용자 또는 서비스 계정에 부여할 역할을 결정할 수 있습니다.

Artifact Registry 역할 부여에 대한 자세한 내용은 역할 및 권한 구성을 참조하세요.

스토리지 버킷 구성

Artifact Registry에서 저장소를 만들면 Artifact Registry는 프로젝트에 해당 Cloud Storage 버킷을 만들지 않습니다. 스토리지 버킷과 직접 상호작용하는 Container Registry에 대한 자동화가 있으면 Artifact Registry 저장소에 해당 변경사항을 적용하도록 이를 업데이트해야 합니다.

예를 들어 Container Registry의 스토리지 버킷에 대한 Cloud Storage 권한을 프로그래매틱 방식으로 부여하면 gcr.io 도메인의 이미지를 호스팅하는 Artifact Registry 저장소에 대한 Artifact Registry 권한을 부여하도록 자동화를 업데이트해야 합니다.

Artifact Registry에서 스토리지 버킷 대신 저장소에 저장된 데이터에 대해 암호화 메서드를 설정합니다. Artifact Registry에서 자동 gcr.io 호스팅을 수행하면 Google 관리형 암호화 키로 암호화되는 gcr.io 저장소가 생성됩니다. 고객 관리 암호화 키(CMEK)를 사용하려면 gcr.io 저장소를 직접 만들고 이를 만들 때 암호화 방법으로 CMEK를 지정해야 합니다.

gcr.io 저장소를 수동으로 만들려면 다음 안내를 따르세요.

CMEK를 사용하는 경우 이 저장소에서 사용할 키를 만들고 키를 사용할 권한을 부여합니다. 고객 관리 암호화 키 사용 설정을 참조하세요.

저장소를 추가합니다.

콘솔

Google Cloud 콘솔에서 저장소 페이지를 엽니다.

저장소 페이지 열기
저장소 만들기를 클릭합니다.
저장소 이름을 지정합니다.

Container Registry 호스트 이름 Artifact Registry 저장소 이름

gcr.io gcr.io

asia.gcr.io asia.gcr.io

eu.gcr.io eu.gcr.io

us.gcr.io us.gcr.io
Docker를 저장소 형식으로 지정합니다.

Container Registry 호스트 이름	Artifact Registry 저장소 이름
gcr.io	gcr.io
asia.gcr.io	asia.gcr.io
eu.gcr.io	eu.gcr.io
us.gcr.io	us.gcr.io

위치 유형에서 저장소의 멀티 리전을 지정합니다.

Container Registry 호스트 이름	Artifact Registry 저장소 위치
gcr.io	대한민국
asia.gcr.io	asia
eu.gcr.io	europe
us.gcr.io	대한민국

저장소에 대한 설명을 추가합니다. 저장소 설명은 암호화되지 않으므로 민감한 정보는 포함하지 마세요.
암호화 섹션에서 저장소의 암호화 메커니즘을 선택합니다.
- Google 관리 키 - Google 관리 암호화 키로 저장소 콘텐츠를 암호화합니다.
- 고객 관리 키 - Cloud Key Management Service를 통해 제어하는 키로 저장소 콘텐츠를 암호화합니다. 키 설정 안내는 저장소의 CMEK 설정을 참조하세요.
만들기를 클릭합니다.

gcloud

다음 명령어를 실행하여 새 저장소를 만듭니다.

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=LOCATION \
    --description=DESCRIPTION \
    --kms-key=KMS-KEY

다음 값을 바꿉니다.

REPOSITORY는 저장소 이름입니다.

Container Registry 호스트 이름 Artifact Registry 저장소 이름

gcr.io gcr.io

asia.gcr.io asia.gcr.io

eu.gcr.io eu.gcr.io

us.gcr.io us.gcr.io

Container Registry 호스트 이름	Artifact Registry 저장소 이름
gcr.io	gcr.io
asia.gcr.io	asia.gcr.io
eu.gcr.io	eu.gcr.io
us.gcr.io	us.gcr.io

LOCATION은 저장소의 멀티 리전입니다.

Container Registry 호스트 이름	Artifact Registry 저장소 위치
gcr.io	대한민국
asia.gcr.io	asia
eu.gcr.io	europe
us.gcr.io	대한민국

DESCRIPTION은 저장소에 대한 설명입니다. 저장소 설명은 암호화되지 않으므로 민감한 정보는 포함하지 마세요.
고객 관리 암호화 키를 사용하여 저장소 콘텐츠를 암호화하는 경우 KMS-KEY는 Cloud KMS 암호화 키의 전체 경로입니다. 경로 형식은 다음과 같습니다.
```
projects/KMS-PROJECT/locations/KMS-LOCATION/keyRings/KEY-RING/cryptoKeys/KEY
```
다음 값을 바꿉니다.
- KMS-PROJECT는 키가 저장된 프로젝트입니다.
- KMS-LOCATION은 키의 위치입니다.
- KEY-RING은 키링의 이름입니다.
- KEY는 키의 이름입니다.

다음 명령어로 저장소를 나열하여 저장소가 생성되었는지 확인할 수 있습니다.

gcloud artifacts repositories list

다음 단계

테스트 프로젝트에서 gcr.io 도메인 지원을 설정하여 기존 자동화 및 서비스(예: Cloud Build, Google Kubernetes Engine 또는 Cloud Functions)와의 통합이 예상대로 작동하는지 확인합니다.