표준 저장소로 전환

이 페이지에서는 현재 Container Registry를 사용하여 컨테이너 이미지를 관리하는 경우 표준 Artifact Registry 저장소를 설정하는 방법을 설명하고 저장소 사용과 Container Registry 사용의 차이를 알아봅니다.

이 안내는 주로 저장소 관리자를 대상으로 합니다. 이미지 빌드, 푸시, 가져오기, 배포가 어떻게 변경되었는지 알아보려면 다음 정보를 참조하세요.

시작하기 전에

Google Cloud 콘솔 또는 다음 명령어를 사용하여 Artifact Registry API를 사용 설정합니다.
```
gcloud services enable artifactregistry.googleapis.com
```
gcloud CLI가 아직 설치되어 있지 않으면 설치합니다. 기존 설치의 경우 다음 명령어를 실행하여 구성요소를 최신 버전으로 업데이트합니다.
```
gcloud components update
```
전환을 시작하기 전에 Artifact Registry의 가격 책정에 대해 알아보세요.

필요한 역할

gcr.io 저장소를 설정하는 데 필요한 권한을 얻으려면 관리자에게 Google Cloud 프로젝트에서 다음 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)와 같은 상응하는 권한이 포함된 역할

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

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

개요

표준 저장소는 모든 기능을 지원하는 일반 Artifact Registry 저장소입니다.

편의상 이 페이지의 안내에서는 Container Registry와 Artifact Registry가 모두 동일한 Google Cloud 프로젝트에 있다고 가정합니다. Artifact Registry로 전환할 때 두 서비스를 모두 계속 사용하면 설정 단계를 점진적으로 실행하고 자동화를 업데이트할 수 있습니다. 필요한 경우 별도의 프로젝트에서 Artifact Registry를 설정하고 동일한 전체 단계를 수행할 수 있습니다.

Artifact Registry는 gcr.io 저장소도 제공합니다. 이러한 저장소는 기존 레지스트리에서 해당 Artifact Registry 저장소로 gcr.io 트래픽을 리디렉션할 수 있습니다. Container Registry와의 하위 호환성을 제공하지만 일부 기능 제한사항도 있습니다. 하지만 gcr.io 참조가 있는 도구 구성, 스크립트 또는 코드가 많으면 Artifact Registry로 전환하기 위해 보다 전술적 접근이 필요할 수 있습니다. 적절한 결정을 내릴 수 있도록 gcr.io 도메인 지원이 있는 저장소의 전환 문서를 검토하세요.

전환 단계

이 가이드에서는 다음 단계를 완료하는 방법을 보여줍니다.

컨테이너를 위한 Docker 저장소를 만듭니다. 이미지를 푸시하려면 먼저 저장소를 만들어야 합니다.
저장소에 권한을 부여합니다.
새 저장소와 연결할 수 있도록 인증을 구성합니다.
필요한 경우 새 저장소에 사용할 Container Registry에서 이미지를 복사합니다.
컨테이너를 가져오고 내보냅니다.
런타임 환경에 이미지를 배포합니다.
추가 기능을 구성합니다.
전환이 완료되면 Container Registry에서 이미지를 삭제합니다.

저장소 만들기

Container Registry는 이전에 이미지를 내보내지 않은 경우 멀티 리전에 스토리지 버킷을 자동으로 만듭니다.

Artifact Registry에서는 저장소를 만들어야 이미지를 업로드할 수 있습니다. 저장소를 만들 때 다음을 지정해야 합니다.

저장소 형식. Artifact Registry는 Docker 저장소에 컨테이너를 저장합니다.
저장소의 리전 또는 멀티 리전 위치.

Artifact Registry 저장소의 위치를 선택할 때 저장소와 다른 인프라 및 사용자의 근접성을 고려합니다. Container Registry에서 Artifact Registry로 이미지를 복사하려는 경우 위치 차이로 인해 복사 비용이 영향을 받을 수 있습니다.
Cloud Key Management Service 키(암호화를 위해 고객 관리 암호화 키(CMEK)를 사용하는 경우).

Container Registry에서 CMEK를 사용하도록 Container Registry 스토리지 버킷을 구성합니다. Artifact Registry에서 저장소를 만들 때 CMEK를 사용하도록 저장소를 구성합니다. Artifact Registry에서 CMEK를 사용하는 방법에 관한 자세한 내용은 고객 관리 암호화 키 사용 설정을 참조하세요.

Container Registry는 gcr.io 도메인에서 컨테이너를 호스팅합니다. Artifact Registry는 pkg.dev 도메인에서 컨테이너를 호스팅합니다.

암호화에 CMEK를 사용하는 저장소를 포함하여 저장소를 만드는 방법에 대한 자세한 내용은 저장소 만들기를 참조하세요.

권한 부여

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 역할은 사전 정의된 Cloud Storage 역할에서 제공되지 않는 몇 가지 권한을 추가로 분리합니다.

필수 액세스 권한	현재 역할	Artifact Registry 역할	역할을 부여할 위치
이미지 가져오기 전용(읽기 전용)	스토리지 객체 뷰어 (`roles/storage.objectViewer`)	Artifact Registry 리더 (`roles/artifactregistry.reader)`	Artifact Registry 저장소 또는 Google Cloud 프로젝트
이미지 내보내기 및 가져오기(읽기 및 쓰기)	스토리지 기존 버킷 작성자 (`roles/storage.legacyBucketWriter`)	Artifact Registry 작성자 (`roles/artifactregistry.writer)`)	Artifact Registry 저장소 또는 Google Cloud 프로젝트
이미지 내보내기, 가져오기, 삭제	스토리지 기존 버킷 작성자 (`roles/storage.legacyBucketWriter`)	Artifact Registry 저장소 관리자 (`roles/artifactregistry.repoAdmin)`	Artifact Registry 저장소 또는 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는 Container Registry와 동일한 인증 방식을 지원합니다.

Docker 사용자 인증 정보 도우미를 사용하는 경우:

Artifact Registry 저장소와 상호작용하려면 버전 2.0 이상을 사용해야 합니다. 이 독립형 버전은 GitHub에서 제공됩니다.
사용할 Artifact Registry 위치로 사용자 인증 정보 도우미를 구성해야 합니다. 기본적으로 사용자 인증 정보 도우미는 Container Registry 호스트에 대한 액세스만 구성합니다.

인증 설정에 대한 자세한 내용은 Docker 인증 설정을 참조하세요.

Container Registry에서 컨테이너 복사

Container Registry에 Artifact Registry에서 계속 사용할 컨테이너가 있는 경우 복사할 수 있는 몇 가지 방법이 있습니다. 자세한 안내는 Container Registry에서 이미지 복사를 참조하세요.

이미지 내보내기 및 가져오기

Artifact Registry에서 이미지를 태그 지정하고 내보내고 가져오는 데 사용하는 Docker 명령어는 Container Registry에서 사용하는 명령어와 유사합니다. 하지만 다음과 같은 두 가지 주된 차이점이 있습니다.

Artifact Registry Docker 저장소의 호스트 이름에는 위치 프리픽스와 이어서 -docker.pkg.dev가 붙습니다. 예를 들어 australia-southeast1-docker.pkg.dev, europe-north1-docker.pkg.dev, europe-docker.pkg.dev가 있습니다.
Artifact Registry는 단일 프로젝트에서 여러 Docker 저장소를 지원하므로 명령어에 저장소 이름을 지정해야 합니다.

예를 들어 Container Registry에서 이 명령어는 my-image 이미지를 my-project 프로젝트의 레지스트리 eu.gcr.io로 내보냅니다.

docker push eu.gcr.io/my-project/my-image

Artifact Registry에서 이 명령어는 이미지 my-image를 저장소 my-repo와 프로젝트 my-project 내 지역 저장소 europe-north1-docker.pkg.dev로 내보냅니다.

docker push europe-north1-docker.pkg.dev/my-project/my-repo/my-image

Artifact Registry에서 이미지를 내보내고 가져오는 방법에 대한 자세한 내용은 이미지 가져오기 및 내보내기를 참조하세요.

이미지 배포

일반적인 Google Cloud 통합을 위한 서비스 계정은 동일한 프로젝트의 저장소에 대한 기본 권한으로 구성됩니다.

Cloud Build를 사용하여 이미지를 빌드하고 저장소에 내보내는 것은 일반적으로 Container Registry와 동일한 방식으로 작동합니다. Artifact Registry의 주요 차이점은 첫 번째로 내보내는 이미지를 포함하여 이미지를 대상 저장소에 내보내기 전에 대상 저장소가 존재해야 한다는 것입니다.

Docker 명령어 docker push 및 Cloud Build 명령어 gcloud builds submit를 포함하여 이미지를 푸시하는 명령어를 실행하기 전에 필요한 저장소를 만들어야 합니다.

Cloud Build 빌더는 여전히 gcr.io에서 호스팅됩니다. 자세한 내용은 Cloud Build와 통합을 참조하세요.

기타 기능

이 섹션에서는 Container Registry에서 설정했을 수 있는 다른 기능에 대한 구성을 설명합니다.

Artifact Analysis

Artifact Analysis는 Container Registry와 Artifact Registry를 모두 지원합니다. Artifact Analysis 문서에는 두 제품이 모두 포함되어 있습니다.

두 제품 모두 동일한 Artifact Analysis API를 사용합니다. Container Registry 또는 Artifact Registry에서 Artifact Analysis API를 사용 설정하면 두 제품 모두에 대해 API가 사용 설정됩니다.
두 제품 모두 Artifact Analysis 알림에 대해 동일한 Pub/Sub 주제를 사용합니다.
gcloud container images 명령어를 계속 사용하여 gcr.io 이미지 경로와 관련된 메모 및 일치하는 항목을 나열할 수 있습니다.

Container Registry	Artifact Registry
지원되는 OS가 포함된 이미지에서 주문형 스캔을 통해 OS 및 언어 패키지 취약점을 스캔합니다. 자동 스캔은 OS 취약점 정보만 반환합니다. 스캔 유형에 대해 자세히 알아보세요. 주문형 스캔 Google Cloud CLI 명령어인 gcloud artifacts docker images scan은 로컬 이미지의 취약점 또는 Container Registry의 이미지를 스캔합니다. Google Cloud CLI 명령어 gcloud artifacts docker images list-vulnerabilities는 취약점 스캔 결과를 반환합니다. 스캔은 지원되는 운영체제가 있는 Container Registry의 이미지에 대한 OS 및 언어 패키지 취약점 정보를 반환합니다. 자동 스캔 Google Cloud CLI 명령어 gcloud container images에는 취약점 및 기타 메타데이터를 포함한 스캔 결과를 보는 플래그가 포함됩니다. 스캔은 지원되는 운영체제가 있는 Container Registry의 이미지에 대한 OS 취약점 정보만 반환합니다.	주문형 스캔과 자동 스캔을 모두 사용하여 OS 및 언어 패키지 취약점을 스캔합니다. 스캔 유형에 대해 자세히 알아보세요. 주문형 스캔 Google Cloud CLI 명령어인 gcloud artifacts docker images scan은 로컬 이미지의 취약점 또는 Artifact Registry의 이미지를 검색합니다. Google Cloud CLI 명령어 gcloud artifacts docker images list-vulnerabilities는 취약점 스캔 결과를 반환합니다. 스캔은 지원되는 운영체제가 있는 Artifact Registry의 이미지에 대한 OS 및 언어 패키지 취약점 정보를 반환합니다. 자동 스캔 Google Cloud CLI 명령어 gcloud artifacts docker images에는 취약점 및 기타 메타데이터를 포함한 스캔 결과를 보는 플래그가 포함됩니다. 스캔은 지원되는 운영 체제와 지원되지 않는 운영 체제 모두에 대한 지원되는 운영체제 및 언어 패키지 취약성 정보가 있는 Artifact Registry의 이미지에 대한 OS 취약점 정보를 반환합니다.

Container Registry

Artifact Registry

지원되는 OS가 포함된 이미지에서 주문형 스캔을 통해 OS 및 언어 패키지 취약점을 스캔합니다. 자동 스캔은 OS 취약점 정보만 반환합니다. 스캔 유형에 대해 자세히 알아보세요.

주문형 스캔

Google Cloud CLI 명령어인 gcloud artifacts docker images scan은 로컬 이미지의 취약점 또는 Container Registry의 이미지를 스캔합니다.
Google Cloud CLI 명령어 gcloud artifacts docker images list-vulnerabilities는 취약점 스캔 결과를 반환합니다.
스캔은 지원되는 운영체제가 있는 Container Registry의 이미지에 대한 OS 및 언어 패키지 취약점 정보를 반환합니다.

자동 스캔

Google Cloud CLI 명령어 gcloud container images에는 취약점 및 기타 메타데이터를 포함한 스캔 결과를 보는 플래그가 포함됩니다.
스캔은 지원되는 운영체제가 있는 Container Registry의 이미지에 대한 OS 취약점 정보만 반환합니다.

주문형 스캔과 자동 스캔을 모두 사용하여 OS 및 언어 패키지 취약점을 스캔합니다. 스캔 유형에 대해 자세히 알아보세요.

주문형 스캔

Google Cloud CLI 명령어인 gcloud artifacts docker images scan은 로컬 이미지의 취약점 또는 Artifact Registry의 이미지를 검색합니다.
Google Cloud CLI 명령어 gcloud artifacts docker images list-vulnerabilities는 취약점 스캔 결과를 반환합니다.
스캔은 지원되는 운영체제가 있는 Artifact Registry의 이미지에 대한 OS 및 언어 패키지 취약점 정보를 반환합니다.

자동 스캔

Google Cloud CLI 명령어 gcloud artifacts docker images에는 취약점 및 기타 메타데이터를 포함한 스캔 결과를 보는 플래그가 포함됩니다.
스캔은 지원되는 운영 체제와 지원되지 않는 운영 체제 모두에 대한 지원되는 운영체제 및 언어 패키지 취약성 정보가 있는 Artifact Registry의 이미지에 대한 OS 취약점 정보를 반환합니다.

Pub/Sub 알림

Artifact Registry는 Container Registry와 동일한 gcr 주제에 대한 변경사항을 게시합니다. Artifact Registry와 동일한 프로젝트에서 Container Registry와 함께 Pub/Sub을 이미 사용하는 경우 추가 구성이 필요하지 않습니다.

별도의 프로젝트에서 Artifact Registry를 설정하면 gcr 주제가 존재하지 않을 수 있습니다. 설정 안내는 Pub/Sub 알림 구성을 참조하세요.

서비스 경계

VPC 서비스 제어를 사용하면 Google 관리형 서비스의 리소스 주위에 보안 경계를 구성하고 경계를 넘는 데이터 이동을 제어할 수 있습니다.

자세한 내용은 서비스 경계에서 저장소 보호를 참조하세요.

Container Registry 이미지 삭제

Container Registry 사용을 중지할 준비가 되었으면 Container Registry의 스토리지 버킷을 삭제하여 나머지 이미지를 삭제합니다.

각 Container Registry 스토리지 버킷을 삭제하려면 다음 안내를 따르세요.

콘솔

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
삭제를 클릭합니다. 확인 대화상자가 나타납니다.
삭제를 확인하려면 버킷 이름을 입력한 다음 삭제를 클릭합니다.

gcloud

버킷에서 수십만 개 이상의 이미지를 일괄 삭제하려면 삭제 프로세스 완료에 오랜 시간이 걸리므로 gcloud CLI를 사용하지 마세요. 대신 Google Cloud 콘솔을 사용하여 작업을 수행합니다. 자세한 내용은 Cloud Storage 객체 일괄 삭제를 참조하세요.

버킷을 삭제하려면 gcloud storage rm 명령어를 --recursive 플래그와 함께 사용합니다.

gcloud storage rm gs://BUCKET-NAME --recursive

BUCKET-NAME을 Container Registry 스토리지 버킷 이름으로 바꿉니다. 버킷 이름에서 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

응답은 다음 예시와 같습니다.

Removing gs://artifacts.my-project.appspot.com/...

다른 Google Cloud 서비스가 동일한 Google Cloud 프로젝트에서 실행 중이면 Container Registry API를 사용 설정된 상태로 둡니다. Container Registry API를 사용 중지하려고 하면 구성된 종속 항목이 있는 다른 서비스가 프로젝트에서 사용 설정되어 있으면 Container Registry에 경고가 표시됩니다. Container Registry API를 사용 중지하면 해당 서비스를 사용하는 Container Registry를 현재 사용하지 않더라도 구성된 종속 항목이 있는 동일한 프로젝트의 모든 서비스가 자동으로 사용 중지됩니다.

다음 단계

Docker 빠른 시작 사용해 보기