Docker 변경사항

이 문서에서는 Docker에서 컨테이너 이미지 인증, 내보내기, 가져오기에 대한 Container Registry와 Artifact Registry 사이의 차이점을 안내합니다.

이 가이드에서는 표준 Artifact Registry 저장소, Container Registry와 별개로 모든 아티팩트 레지스트리 기능을 지원하는 일반 Artifact Registry 저장소를 비교합니다.

관리자가 gcr.io 도메인 지원이 포함된 저장소를 설정한 경우 gcr.io 호스트 이름에 대한 요청이 해당 Artifact Registry 저장소로 자동으로 리디렉션됩니다. Artifact Registry에서 호스팅되는 gcr.io 저장소를 사용하려면 적합한 Artifact Registry 역할 또는 상응하는 권한이 포함된 역할이 있어야 합니다.

Cloud Build로 빌드하고 Cloud Run 또는 Google Kubernetes Engine에 배포할 때 Container Registry와 Artifact Registry 사이의 차이점을 알아보려면 Cloud Build, Cloud Run, GKE의 변경사항을 참조하세요.

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

시작하기 전에

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

1. 프로젝트에서 Artifact Registry를 사용 설정했습니다.
2. Docker를 설치했는지 여부 Docker는 Cloud Shell에 포함되어 있습니다.

개요

대략적으로 Container Registry 또는 Artifact Registry에서 Docker 사용 워크플로는 동일합니다.

Container Registry	Artifact Registry
관리자 Container Registry API 사용 설정 호스트로 초기 이미지를 내보내서 'gcr.io'와 같은 레지스트리 호스트를 추가합니다. 이미지에 액세스할 수 있도록 스토리지 버킷에서 레지스트리 호스트에 대해 Cloud Storage에 역할을 부여합니다.	관리자 Artifact Registry API 사용 설정 Docker 저장소를 추가합니다. 이미지에 액세스하도록 Artifact Registry에 역할을 부여합니다.
레지스트리 사용자 이미지를 Dockerfile 파일로 정의합니다. 이미지를 빌드합니다. 레지스트리에 인증을 수행합니다. 이미지에 태그를 지정하고 레지스트리로 내보냅니다. 레지스트리에서 이미지를 가져오거나 Google Cloud 런타임에 배포합니다.	레지스트리 사용자 이미지를 Dockerfile 파일로 정의합니다. 이미지를 빌드합니다. 레지스트리에 인증을 수행합니다. 이미지에 태그를 지정하고 레지스트리로 내보냅니다. 레지스트리에서 이미지를 가져오거나 Google Cloud 런타임에 배포합니다.

그러나 Container Registry의 바로가기는 관리자 및 사용자 역할을 단일 워크플로로 결합하는 것입니다. 이 바로가기는 다음 위치에서 일반적으로 사용됩니다.

• 포괄적인 권한이 있는 환경에서 테스트하는 빠른 시작 및 튜토리얼
• Cloud Build를 사용하는 Workflows. Cloud Build 서비스 계정에는 동일한 Google Cloud 프로젝트에서 레지스트리 호스트를 추가하는 권한이 있습니다.

바로가기 워크플로는 다음과 같습니다.

1. Container Registry API를 사용 설정합니다.
2. Container Registry에 액세스할 계정에 권한을 부여합니다.

3. 레지스트리에 인증을 수행합니다. 가장 간단한 인증 옵션은 Google Cloud CLI에서 Docker 사용자 인증 정보 도우미를 사용하는 것입니다 이 단계는 일회성 구성 단계입니다.

   gcloud auth configure-docker
   

4. 이미지를 빌드하고 태그를 지정합니다. 예를 들어 이 명령어는 gcr.io/my-project/my-image:tag1 이미지를 빌드하고 태그를 지정합니다.

   docker build -t gcr.io/my-project/my-image:tag1
   

5. 레지스트리로 이미지를 내보냅니다. 예를 들면 다음과 같습니다.

   docker push gcr.io/my-project/my-image:tag1
   

   gcr.io 레지스트리 호스트가 프로젝트에 없으면 Container Registry가 이미지를 업로드하기 전 호스트를 추가합니다.

6. 레지스트리에서 이미지를 가져오거나 Google Cloud 런타임에 배포합니다. 예를 들면 다음과 같습니다.

   docker pull gcr.io/my-project/my-image:tag1
   

이 워크플로에는 다음 바로가기가 사용됩니다.

• 이미지를 내보내는 계정에 스토리지 관리자 역할 또는 소유자와 같은 동일한 권한이 있는 역할이 있습니다. 이 역할의 광범위한 권한은 Container Registry에서 사용되지 않는 버킷을 포함하여 프로젝트의 모든 스토리지 버킷에 대해 읽기 및 쓰기 액세스를 허용합니다.
• 일부 Google Cloud API를 사용 설정하면 Container Registry API가 자동으로 사용 설정됩니다. 즉, 이러한 서비스 사용자에게 동일 프로젝트에 있는 Container Registry에 대한 암시적 액세스 권한이 포함됩니다. 예를 들어 Cloud Build에서 빌드를 실행할 수 있는 사용자는 기본적으로 레지스트리에 이미지를 내보내고 레지스트리 호스트를 추가할 수 있습니다.

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

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

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

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

3. Artifact Registry와 상호작용하는 계정에 권한을 부여합니다.

4. 변경됨: 저장소에 인증을 수행합니다. gcloud CLI에서 사용자 인증 정보 도우미를 사용하는 경우 Docker 클라이언트 구성에 추가할 호스트를 지정해야 합니다. 예를 들어 다음 명령어는 us-central1-docker.pkg.dev 호스트를 추가합니다.

   gcloud auth configure-docker us-central1-docker.pkg.dev
   

5. 변경됨: 이미지를 빌드하고 태그를 지정합니다.

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

   docker build -t us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
   

6. 변경됨: Artifact Registry 경로를 사용하여 이미지를 저장소로 내보냅니다. 예를 들면 다음과 같습니다.

   docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
   

7. 변경됨: Artifact Registry 경로를 사용하여 이미지를 저장소로 가져옵니다. 예를 들면 다음과 같습니다.

   docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
   

API 사용 설정

핵심 사항:

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

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

Container Registry

Container Registry에 Docker 또는 다른 제3자 클라이언트를 사용하기 전에 Container Registry API를 사용 설정해야 합니다.

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

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

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

Artifact Registry

Artifact Registry에 Docker 클라이언트 또는 기타 Google Cloud 서비스를 사용하려면 먼저 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로 이미지 내보내기를 설명하는 문서에서 제외된 경우가 많습니다.

• 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. 이러한 초기 내보내기 이후 다른 사용자에 대해 스토리지 버킷에 권한을 부여할 수 있습니다.

프로젝트 내에서 레지스트리 호스트는 모든 이미지를 동일한 스토리지 버킷에 저장합니다. 다음 예시에서는 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

이미지를 내보내려면 먼저 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가 없습니다.

권한 부여

핵심 사항:

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

다음 비교는 각 서비스의 권한 설정에 대해 설명합니다.

Container Registry

Container Registry는 Cloud Storage 역할을 사용하여 액세스를 제어합니다.

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

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

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

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

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

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

초기 이미지를 레지스트리로 내보낸 후에는 스토리지 버킷에 액세스해야 하는 다른 계정에 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에는 액세스 제어를 위한 자체 역할이 있습니다. 이러한 역할에 따라 관리자 및 저장소 사용자 역할이 명확하게 구분됩니다.

저장소를 관리하는 계정에만 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는 Container Registry와 동일한 인증 방식을 지원합니다.
• Docker 사용자 인증 정보 도우미의 경우 Docker 클라이언트 구성에 추가할 호스트를 지정해야 합니다.
• docker login을 사용하는 인증의 경우 Container Registry 호스트 대신 Artifact Registry 호스트를 사용합니다.

사용자 인증 정보 도우미 사용

gcloud auth configure-docker 명령어 및 독립형 사용자 인증 정보 도우미는 기본적으로 *.gcr.io 호스트 이름에 대해서만 Docker를 구성합니다. Artifact Registry의 경우에는 Docker 클라이언트 구성에 추가하려는 Artifact Registry 호스트 목록을 지정해야 합니다.

예를 들어 us-central1 리전에서 Docker 저장소에 대해 인증을 설정하려면 다음 명령어를 실행합니다.

gcloud auth configure-docker us-central1-docker.pkg.dev

나중에 us-east1 및 asia-east1에서 저장소를 추가하려면 명령어를 다시 실행하여 해당 리전별 호스트 이름을 Docker 구성에 추가해야 합니다.

gcloud auth configure-docker us-east-docker.pkg.dev,asia-east1-docker.pkg.dev

자세한 Artifact Registry 인증 방법은 Docker에 대한 인증 설정을 참조하세요.

비밀번호 인증 사용

Docker에 로그인할 때 *.gcr.io 호스트 이름 대신 Artifact Registry 호스트 이름을 사용합니다. 다음 예시에서는 base64 인코딩 서비스 계정 키를 사용하는 us-central1-docker.pkg.dev 호스트 인증을 보여줍니다.

cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-central1-docker.pkg.dev

이미지 빌드 및 태그 지정

핵심 사항: - Artifact Registry는 저장소에 대해 다른 호스트 이름을 사용합니다.

이미지에 태그를 지정할 때는 Container Registry 경로 대신 Artifact Registry 경로를 사용합니다. 예를 들면 다음과 같습니다.

docker tag my-image us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

레지스트리에 이미지 내보내기

핵심 사항: - Artifact Registry에서는 이미지를 내보내기 전에 대상 저장소를 종료해야 합니다. - Artifact Registry는 저장소에 대해 다른 호스트 이름을 사용합니다.

이미지를 내보낼 때 Container Registry 경로 대신 Artifact Registry 경로를 사용합니다. 예를 들면 다음과 같습니다.

docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

레지스트리에서 이미지 가져오기

핵심 사항:

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

이미지를 가져올 지정할 때 Container Registry 경로 대신 Artifact Registry 경로를 사용합니다. 예를 들면 다음과 같습니다.

docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Cloud Run 및 GKE와 같은 Google Cloud 런타임에 이미지를 배포하는 예시는 이미지 배포를 참조하세요.