Container Registry는 지원 중단되었으며 종료될 예정입니다. 2024년 5월 15일 이후에는 이전에 Container Registry를 사용하지 않은 프로젝트의 gcr.io 도메인 이미지를 Artifact Registry에서 호스팅합니다. 2025년 3월 18일 이후에는 Container Registry가 종료됩니다.

Google Cloud에서 컨테이너 관리를 시작하려면 Artifact Registry를 사용하세요. Container Registry를 사용하는 경우 Artifact Registry로 전환하여 Google Cloud에서 컨테이너를 관리하는 방법을 알아보세요.

지원 중단 및 종료에 대한 자세한 내용은 지원 중단 페이지와 출시 노트를 참조하세요.

인증 방식

이 페이지에서는 Container Registry로 인증하도록 타사 클라이언트를 구성하는 방법을 설명합니다.

Container Registry와 통합되는 Google Cloud 서비스는 동일한 프로젝트의 저장소에 액세스할 수 있는 권한으로 사전 구성됩니다. 이러한 서비스에 대한 인증을 구성할 필요는 없지만 권한이 적절하게 구성되었는지 확인해야 합니다.

시작하기 전에

Container Registry API를 사용 설정하고 gcloud CLI를 설치했는지 확인합니다. 자세한 내용은 서비스 사용 설정 및 사용 중지를 참조하세요.
인증에 사용 중인 계정에 Container Registry에 액세스할 수 있는 권한이 있는지 확인합니다. 사용자 계정이 아닌 서비스 계정을 사용하는 것이 좋습니다.
Docker가 아직 설치되어 있지 않으면 설치합니다. Docker는 Cloud Shell에 포함되어 있습니다.
Docker에는 레지스트리와 상호작용하기 위한 액세스 권한이 필요합니다. Linux 또는 Windows에서 Docker 보안 그룹에 Docker 명령어를 실행하는 데 사용할 사용자를 추가합니다. Docker Desktop은 가상 머신에서 루트 사용자로 실행되므로 MacOS에서는 이 단계가 필요하지 않습니다.
Linux
Docker 보안 그룹을 docker라고 합니다. 사용자 이름을 추가하려면 다음 명령어를 실행합니다.
```
sudo usermod -a -G docker ${USER}
```
Windows
Docker 보안 그룹을 docker-users라고 합니다. 관리자 명령어 프롬프트에서 사용자를 추가하려면 다음 명령어를 실행합니다.
```
net localgroup docker-users DOMAIN\USERNAME /add
```
각 항목의 의미는 다음과 같습니다.
- DOMAIN은 Windows 도메인입니다.
- USERNAME은 사용자 이름입니다.
그룹 멤버십 변경사항을 적용하려면 로그아웃했다가 다시 로그인합니다. 가상 머신을 사용하는 경우 멤버십 변경사항을 적용하려면 가상 머신을 다시 시작해야 할 수 있습니다.

참고: Docker 보안 그룹은 루트 또는 관리자 사용자와 동등한 액세스 권한이 있습니다. Docker 액세스가 필요한 신뢰할 수 있는 사용자만 추가하세요. 보안 영향에 대한 자세한 내용은 Docker 데몬 보안을 참조하세요.

인증 방식

Container Registry에 액세스해야 하는 모든 타사 클라이언트를 구성해야 합니다.

다음과 같은 인증 방식을 사용할 수 있습니다.

gcloud 사용자 인증 정보 도우미(권장)

gcloud에서 직접 Docker에서 사용할 수 있도록 Container Registry 사용자 인증 정보를 구성합니다. 프로젝트 리소스에 대한 안전하고 일시적인 액세스가 가능한 경우에 이 방법을 사용합니다. 이 옵션은 Docker 버전 18.03 이상만 지원합니다.

독립형 사용자 인증 정보 도우미

이 옵션은 기본적으로 Google Cloud CLI가 없는 경우 Docker에서 사용할 수 있도록 사용자 인증 정보를 구성합니다. 이 옵션은 Docker 버전 18.03 이상만 지원합니다.

액세스 토큰

애플리케이션 기본 사용자 인증 정보는 서비스 계정에서 Google Cloud 리소스에 액세스하는 데 사용하는 일시적인 액세스 토큰을 제공합니다. 사용자 인증 정보 도우미로 gcloud을 사용하는 것이 가장 안전합니다.

JSON 키 파일

서비스 계정의 사용자 인증 정보로 사용할 수 있는 사용자 관리형 키-쌍입니다. 사용자 인증 정보는 장기적이므로 사용 가능한 모든 인증 방법 중 보안 수준이 가장 낮은 옵션입니다.

가능하면 액세스 토큰 또는 사용 가능한 다른 인증 방법을 사용하여 아티팩트에 대한 무단 액세스의 위험을 줄이세요. 서비스 계정 키를 올바르게 관리하지 않으면 보안 위험을 초래할 수 있습니다. 가능한 한 서비스 계정 키보다 안전한 대안을 선택해야 합니다. 서비스 계정 키로 인증해야 하는 경우 비공개 키와 서비스 계정 키 관리 권장사항에 설명된 기타 작업을 보호해야 합니다. 서비스 계정 키를 만들 수 없는 경우 서비스 계정 키 생성이 조직에 중지될 수 있습니다. 자세한 내용은 기본 보안별 조직 리소스 관리를 참조하세요.

일부 도구 또는 워크플로에서는 gcloud를 사용자 인증 정보 도우미로 사용할 수 없습니다. 대체 옵션 중 하나를 사용할 경우 보안상의 영향을 파악해야 합니다.

Docker 구성 파일의 인증 설정

Docker는 구성 파일 config.json에 인증 설정을 저장합니다.

Linux: ~/.docker/config.json
Windows: %USERPROFILE%\.docker\config.json

파일에는 여러 인증 방법에 대한 개별 섹션이 있습니다.

credHelpers: 인증을 위해 Docker 사용자 인증 정보 도우미를 사용하는 경우 Container Registry가 사용자 인증 정보 도우미 설정을 파일의 credHelpers 섹션에 저장합니다.
auths: Docker를 사용해서 토큰 또는 서비스 계정 키를 비밀번호로 사용해서 로그인하는 경우 Docker가 사용자 인증 정보를 파일의 auths 섹션에 저장합니다.
credStore: 사용자 인증 정보 관리를 위해 사용자 인증 정보 저장소를 구성한 경우 사용자 인증 정보 저장소의 설정이 파일의 credStore 섹션에 있습니다.

Docker가 레지스트리에 연결하면 먼저 호스트와 연관된 사용자 인증 정보 도우미를 확인합니다. 따라서 config.json에서 credHelpers 및 auths 섹션 모두에 Container Registry 설정이 포함되어 있으면 auths 섹션의 정보가 무시됩니다.

gcloud 사용자 인증 정보 도우미

가능하다면 되도록 이 방법을 사용하세요. 프로젝트 리소스에 대한 안전한 단기 액세스를 제공합니다.

gcloud CLI를 사용하여 Cloud Shell에서 또는 Google Cloud CLI가 설치된 환경에서 인증을 구성합니다. Cloud Shell에는 Docker의 현재 버전이 포함되어 있습니다.

인증을 구성하려면 다음 안내를 따르세요.

Docker 명령어를 실행할 사용자로 gcloud에 로그인합니다.
- 사용자 인증 정보로 인증을 구성하려면 다음 명령어를 실행합니다.
```
gcloud auth login
```
- 서비스 계정 사용자 인증 정보로 인증을 구성하려면 다음 명령어를 실행합니다.
```
gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
```
  각 항목의 의미는 다음과 같습니다.
  - ACCOUNT는 [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com 형식의 서비스 계정 이름입니다. Google Cloud 콘솔의 서비스 계정 페이지 또는 gcloud iam service-accounts list 명령어를 사용하여 기존 서비스 계정을 볼 수 있습니다.
  - KEY-FILE은 서비스 계정 키 파일입니다. 키 만들기에 대한 자세한 내용은 Identity and Access Management(IAM) 문서를 참조하세요.
참고: 서비스 계정 키를 올바르게 관리하지 않으면 보안 위험을 초래할 수 있습니다. 가능한 한 서비스 계정 키보다 안전한 대안을 선택해야 합니다. 서비스 계정 키로 인증해야 하는 경우 비공개 키와 서비스 계정 키 관리 권장사항에 설명된 기타 작업을 보호해야 합니다. 서비스 계정 키를 만들 수 없는 경우 서비스 계정 키 생성이 조직에 중지될 수 있습니다. 자세한 내용은 보안 기반 조직 리소스 관리를 참조하세요.
다음 명령어로 Docker를 구성합니다.
```
gcloud auth configure-docker
```
사용자 인증 정보는 사용자 홈 디렉터리에 저장됩니다.
- Linux: $HOME/.docker/config.json
- Windows: %USERPROFILE%/.docker/config.json

독립형 사용자 인증 정보 도우미

독립형 Docker 사용자 인증 정보 도우미는 gcloud CLI를 사용할 수 없는 시스템에서 Container Registry에 인증하도록 Docker를 구성합니다.

사용자 인증 정보 도우미는 Container Registry 사용자 인증 정보를 자동으로, 또는 --token-source 플래그로 지정한 위치에서 가져온 다음 Docker의 구성 파일에 기록합니다. 이렇게 하면 Docker의 명령줄 도구 docker를 사용하여 Container Registry와 직접 상호 작용할 수 있습니다.

인증을 구성하려면 다음 안내를 따르세요.

Docker 명령어를 실행할 사용자로 머신에 로그인합니다.

GitHub 출시 버전에서 docker-credential-gcr을 다운로드합니다.

원하는 경우 curl 명령줄 유틸리티를 사용할 수 있습니다. 예를 들면 다음과 같습니다.

VERSION=2.1.22
OS=linux  # or "darwin" for OSX, "windows" for Windows.
ARCH=amd64  # or "386" for 32-bit OSs, "arm64" for ARM 64.

curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \
| tar xz docker-credential-gcr \
&& chmod +x docker-credential-gcr && sudo mv docker-credential-gcr /usr/bin/

다음 명령어로 Docker를 구성합니다.
```
docker-credential-gcr configure-docker
```
사용자 인증 정보는 사용자 홈 디렉터리에 저장됩니다.
- Linux: $HOME/.docker/config.json
- Windows: %USERPROFILE%/.docker/config.json

자세한 내용은 GitHub의 독립형 Docker 사용자 인증 정보 도우미 문서를 참조하세요.

이제 Docker가 Container Registry로 인증하도록 구성되었습니다. 이미지를 내보내고 가져오려면 권한이 올바르게 구성되어 있는지 확인합니다.

액세스 토큰

Container Registry에 인증을 수행하기 위해 단기 OAuth 액세스 토큰을 생성할 수 있습니다. 토큰은 60분 동안 유효하므로 Container Registry와 연결하는 데 사용하기 한 시간 전에 요청해야 합니다.

Container Registry와 상호작용할 새 서비스 계정을 만듭니다.
Console
1. Google Cloud 콘솔에서 서비스 계정 만들기 페이지로 이동합니다.
  
  서비스 계정 만들기 페이지로 이동
2. 사용할 프로젝트를 선택합니다.
3. 서비스 계정 이름 필드에 이름을 입력합니다.
4. 선택사항: 서비스 계정 설명 필드에 설명을 입력합니다.
5. 만들기를 클릭합니다.
6. 역할 선택 필드를 클릭합니다. 모든 역할에서 서비스 계정에 부여하려는 권한에 따라 적절한 Cloud Storage 역할을 선택합니다.
7. 완료를 클릭합니다.
gcloud
로컬 머신이나 Cloud Shell에서 Google Cloud CLI를 사용하여 다음 명령어를 실행할 수 있습니다.
1. 서비스 계정을 만듭니다. NAME을 서비스 계정 이름으로 바꿉니다.
```
gcloud iam service-accounts create NAME
```
2. 서비스 계정에 역할을 부여합니다. PROJECT_ID를 프로젝트 ID로 바꾸고, ROLE을 서비스 계정에 적절한 Cloud Storage 역할로 바꿉니다. 이 역할은 프로젝트의 저장소에 적용됩니다. 나중에 역할을 변경할 수 있고 특정 저장소의 서비스 계정에 다른 역할을 부여할 수도 있습니다.
```
gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
```
Container Registry와 상호작용할 서비스 계정의 키를 가져옵니다.

참고: 서비스 계정 키를 올바르게 관리하지 않으면 보안 위험을 초래할 수 있습니다. 가능한 한 서비스 계정 키보다 안전한 대안을 선택해야 합니다. 서비스 계정 키로 인증해야 하는 경우 비공개 키와 서비스 계정 키 관리 권장사항에 설명된 기타 작업을 보호해야 합니다. 서비스 계정 키를 만들 수 없는 경우 서비스 계정 키 생성이 조직에 중지될 수 있습니다. 자세한 내용은 보안 기반 조직 리소스 관리를 참조하세요.
콘솔
1. Google Cloud 콘솔에서 서비스 계정 페이지로 이동합니다.
  
  서비스 계정 페이지로 이동
2. 사용할 서비스 계정의 이메일 주소를 클릭합니다.
3. 키를 클릭합니다.
4. 키 추가를 클릭한 후 새 키 만들기를 클릭합니다.
5. 만들기를 클릭합니다. 키가 포함된 JSON 파일이 컴퓨터에 다운로드됩니다.
  
  이 페이지의 안내는 이 키 파일에 keyfile.json 파일 이름을 사용합니다.
6. 닫기를 클릭합니다.
gcloud
로컬 머신이나 Cloud Shell에서 Google Cloud CLI를 사용하여 다음 명령어를 실행할 수 있습니다.

이 페이지의 안내는 이 키 파일에 keyfile.json 파일 이름을 사용합니다.
```
gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com
```
다음 명령어를 실행하여 Google Cloud CLI에 서비스 계정으로 로그인합니다.
```
gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
```
각 항목의 의미는 다음과 같습니다.
- ACCOUNT는 [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com 형식의 서비스 계정 이름입니다.
- KEY-FILE은 서비스 계정 키 파일입니다. 키를 만드는 방법은 IAM 문서를 참조하세요.
서비스 계정에 대해 권한이 올바르게 구성되었는지 확인합니다. Compute Engine 서비스 계정을 사용하는 경우 권한과 액세스 범위를 모두 올바르게 구성해야 합니다.
서비스 계정의 액세스 토큰을 가져옵니다. 토큰은 일시적으로 Container Registry와 연결하는 데 사용하기 한 시간 전에 요청합니다.

다음 명령어를 실행합니다.
Linux
```
gcloud auth print-access-token | docker login -u oauth2accesstoken \
    --password-stdin https://HOSTNAME
```
Windows
```
gcloud auth print-access-token |
    docker login -u oauth2accesstoken --password-stdin https://HOSTNAME
```
여기서 HOSTNAME은 gcr.io, us.gcr.io, eu.gcr.io 또는 asia.gcr.io입니다.

참고: gcr.io 하위 도메인에서 이미지를 제공하는 Google Cloud 서비스는 인증이 필요할 수 있습니다. 예를 들어 Google Cloud Marketplace에서 이미지를 가져오려면 marketplace.gcr.io에 인증해야 합니다.

이제 Docker가 Container Registry로 인증됩니다.

JSON 키 파일

서비스 계정 키는 서비스 계정의 사용자 인증 정보로 사용할 수 있는 수명이 긴 키-쌍입니다. OAuth 액세스 토큰과 달리 서비스 계정 키는 만료되지 않습니다.

서비스 계정의 유효한 비공개 키에 액세스할 수 있는 사용자는 누구나 서비스 계정을 통해 리소스에 액세스할 수 있습니다. 예를 들어 Container Registry 서비스 계정과 같이 Google Cloud에서 자동으로 만든 일부 서비스 계정에는 상위 프로젝트에 대한 읽기-쓰기 Editor 역할이 부여됩니다. Compute Engine 기본 서비스 계정은 동일한 프로젝트 내의 스토리지에 대한 읽기 전용 액세스 권한으로 구성됩니다.

또한 서비스 계정에 대한 키의 액세스 수명 주기(즉, 서비스 계정이 액세스한 데이터)는 키를 다운로드한 사용자의 수명 주기와는 관계가 없습니다.

컨테이너 이미지에 대한 액세스를 제한하려면 다음 가이드라인을 따릅니다.

Container Registry와 상호작용하는 데에만 사용되는 전용 서비스 계정을 만듭니다.
서비스 계정에 필요한 액세스 권한이 가장 낮은 특정 역할을 부여합니다.
사용자 인증 정보 관리 권장사항을 따릅니다.

Container Registry 저장소에서만 사용할 수 있도록 새 서비스 계정과 서비스 계정 키를 만들려면 다음 안내를 따르세요.

Container Registry와 상호작용할 새 서비스 계정을 만듭니다.
Console
1. Google Cloud 콘솔에서 서비스 계정 만들기 페이지로 이동합니다.
  
  서비스 계정 만들기 페이지로 이동
2. 사용할 프로젝트를 선택합니다.
3. 서비스 계정 이름 필드에 이름을 입력합니다.
4. 선택사항: 서비스 계정 설명 필드에 설명을 입력합니다.
5. 만들기를 클릭합니다.
6. 역할 선택 필드를 클릭합니다. 모든 역할에서 서비스 계정에 적합한 Cloud Storage 역할을 선택합니다.
7. 완료를 클릭합니다.
gcloud
로컬 머신이나 Cloud Shell에서 Google Cloud CLI를 사용하여 다음 명령어를 실행할 수 있습니다.
1. 서비스 계정을 만듭니다. NAME을 서비스 계정 이름으로 바꿉니다.
```
gcloud iam service-accounts create NAME
```
2. 서비스 계정에 역할을 부여합니다. PROJECT_ID를 프로젝트 ID로 바꾸고, ROLE을 서비스 계정에 적절한 Cloud Storage 역할로 바꿉니다.
```
gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
```
Container Registry와 상호작용할 서비스 계정의 키를 가져옵니다.
콘솔
1. Google Cloud 콘솔에서 서비스 계정 페이지로 이동합니다.
  
  서비스 계정 페이지로 이동
2. 사용할 서비스 계정의 이메일 주소를 클릭합니다.
3. 키를 클릭합니다.
4. 키 추가를 클릭한 후 새 키 만들기를 클릭합니다.
5. 만들기를 클릭합니다. 키가 포함된 JSON 파일이 컴퓨터에 다운로드됩니다.
  
  이 페이지의 안내는 이 키 파일에 keyfile.json 파일 이름을 사용합니다.
6. 닫기를 클릭합니다.
gcloud
로컬 머신이나 Cloud Shell에서 Google Cloud CLI를 사용하여 다음 명령어를 실행할 수 있습니다.

이 페이지의 안내는 이 키 파일에 keyfile.json 파일 이름을 사용합니다.
```
gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com
```
서비스 계정에 대해 권한이 올바르게 구성되었는지 확인합니다. Compute Engine 서비스 계정을 사용하는 경우 권한과 액세스 범위를 모두 올바르게 구성해야 합니다.
서비스 계정 키를 비밀번호로 사용하여 Docker로 인증합니다.
Linux/Mac OS
```
cat KEY-FILE | docker login -u _json_key --password-stdin \
https://HOSTNAME
```
Windows
```
Get-Content KEY-FILE |
docker login -u _json_key --password-stdin https://HOSTNAME
```
다음을 바꿉니다.
- KEY-FILE은 JSON 형식의 서비스 계정 키 파일 이름입니다.
- HOSTNAME은 gcr.io, us.gcr.io, eu.gcr.io 또는 asia.gcr.io입니다.
참고: gcr.io 하위 도메인에서 이미지를 제공하는 Google Cloud 서비스는 인증이 필요할 수 있습니다. 예를 들어 Google Cloud Marketplace에서 이미지를 가져오려면 marketplace.gcr.io에 인증해야 합니다.

이제 Docker가 Container Registry로 인증됩니다.

인증 방식

시작하기 전에

Linux

Windows

인증 방식

Docker 구성 파일의 인증 설정

gcloud 사용자 인증 정보 도우미

독립형 사용자 인증 정보 도우미

액세스 토큰

Console

gcloud

콘솔

gcloud

Linux

Windows

JSON 키 파일

Console

gcloud

콘솔

gcloud

Linux/Mac OS

Windows