Docker용 Artifact Registry에 대한 인증 구성

이 페이지에서는 Artifact Registry Docker 저장소에 인증하도록 Docker를 구성하는 방법을 설명합니다.

Cloud Build 또는 Google Kubernetes Engine 및 Cloud Run과 같은 Google Cloud 런타임 환경에 대한 인증을 구성할 필요는 없지만 필요한 권한이 구성되어 있는지 확인해야 합니다.

시작하기 전에

Google Cloud CLI를 설치한 후 다음 명령어를 실행하여 초기화합니다.
```
gcloud init
```
(선택사항) cloud CLI 명령어의 기본값을 구성합니다.
인증에 사용 중인 계정에 Artifact 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 데몬 보안을 참조하세요.

인증 방법 선택

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

gcloud CLI 사용자 인증 정보 도우미: gcloud CLI에서 직접 Docker에서 사용할 수 있도록 Artifact Registry 사용자 인증 정보를 구성합니다. 가장 간단한 인증 방법이지만 독립형 사용자 인증 정보 도우미보다 속도가 느릴 수 있습니다.
독립형 Docker 사용자 인증 정보 도우미: 이 옵션은 기본적으로 Google Cloud CLI가 없는 경우 Docker에서 사용할 수 있도록 사용자 인증 정보를 구성합니다. gcloud CLI 사용자 인증 정보 도우미보다 상당히 빠르고 애플리케이션 기본 사용자 인증 정보(ADC)를 사용하여 해당 환경의 사용자 인증 정보를 자동으로 찾을 수 있습니다.
액세스 토큰: 서비스 계정에 대해 단기 액세스 토큰을 생성한 후 암호 인증을 위해 토큰을 사용할 수 있습니다. 토큰이 60분 동안만 유효하기 때문에 서비스 계정 키보다 안전한 옵션입니다.
서비스 계정 키: 서비스 계정의 사용자 인증 정보로 사용할 수 있는 사용자 관리형 키-쌍입니다. 사용자 인증 정보는 장기적이므로 사용 가능한 모든 인증 방법 중 보안 수준이 가장 낮은 옵션입니다.

가능하면 액세스 토큰 또는 사용자 인증 정보 도우미를 사용해서 컨테이너 이미지에 대한 승인되지 않은 액세스 위험을 줄이세요. 서비스 계정 키를 사용해야 하는 경우 사용자 인증 정보 관리 권장사항을 따라야 합니다.

Docker 구성 파일의 인증 설정

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

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

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

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

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

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

gcloud CLI 사용자 인증 정보 도우미는 프로젝트 리소스에 대한 안전한 단기 액세스를 제공합니다. Google Cloud CLI가 설치된 모든 환경에서 Artifact Registry 호스트에 인증하도록 Docker를 구성합니다. Cloud Shell에는 Google Cloud CLI 및 Docker 최신 버전이 포함됩니다.

gcloud CLI 사용자 인증 정보 도우미는 가장 간단하게 설정할 수 있는 인증 방법입니다. gcloud CLI 세션에서 활성 사용자 또는 서비스 계정의 사용자 인증 정보로 Docker를 구성합니다. 이 사용자 인증 정보 도우미에는 gcloud CLI가 사용되기 때문에 독립형 사용자 인증 정보 도우미보다 현저히 느릴 수 있습니다. 제3자 도구가 포함된 자동화된 빌드 또는 대규모 구성된 레지스트리 호스트가 포함된 Docker 클라이언트의 경우 대신 독립형 사용자 인증 정보 도우미를 사용합니다.

Artifact Registry에 인증하려면 다음 안내를 따르세요.

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

예를 들어 us-central1 및 asia-northeast1 리전을 추가하려면 다음 명령어를 실행합니다.
```
gcloud auth configure-docker us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
```
지정된 호스트 이름이 사용자 인증 정보 도우미 구성에 추가됩니다. 나중에 이 명령어를 다시 실행하여 구성에 다른 호스트 이름을 추가할 수 있습니다.

지원되는 저장소 위치 목록을 보려면 다음 명령어를 실행합니다.
```
gcloud artifacts locations list
```
이 명령어는 현재 Docker 구성의 credHelpers 섹션과 지정된 호스트 이름을 추가한 후 업데이트된 구성을 보여줍니다.

구성 변경사항을 수락하려면 y를 입력합니다.

사용자 인증 정보는 사용자 홈 디렉터리에 저장됩니다.
- Linux: $HOME/.docker/config.json
- Windows: %USERPROFILE%/.docker/config.json
Docker를 사용하려면 사용자 인증 정보 도우미가 PATH 시스템에 있어야 합니다. gcloud 명령어가 PATH 시스템에 있는지 확인합니다.

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

독립형 Docker 사용자 인증 정보 도우미는 gcloud CLI를 사용할 수 없는 시스템에서 Artifact Registry에 인증하도록 Docker를 구성합니다. gcloud CLI 사용자 인증 정보 도우미보다 상당히 빠르고 애플리케이션 기본 사용자 인증 정보(ADC)를 사용하여 해당 환경의 사용자 인증 정보를 자동으로 찾을 수 있습니다. 이미지 태그 지정 또는 나열과 같이 이미지 내보내기 및 가져오기와 다른 작업을 수행합니다. 제3자 도구를 사용하는 자동화된 빌드 또는 대량의 구성된 레지스트리 호스트를 사용하는 Docker 클라이언트의 경우에 이 인증 방법을 사용하는 것이 좋습니다.

독립형 Docker 사용자 인증 정보 도우미는 Artifact Registry 사용자 인증 정보를 가져와 Docker 구성 파일에 기록합니다. 이렇게 하면 Docker 명령줄 도구 docker를 사용하여 Artifact Registry와 직접 상호작용할 수 있습니다.

Docker 사용자 인증 정보 도우미 사용 방법:

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

GitHub에서 독립형 Docker 사용자 인증 정보 도우미를 다운로드합니다.

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

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

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/

Artifact Registry와 상호 작용할 때 Artifact Registry 사용자 인증 정보를 사용하도록 Docker를 구성합니다(이 작업은 한 번만 하면 됩니다).
```
docker-credential-gcr configure-docker --registries=HOSTNAME-LIST
```
여기서 HOSTNAME-LIST는 사용자 인증 정보 도우미 구성에 추가할 저장소 호스트 이름의 쉼표로 구분된 목록입니다.

예를 들어 us-central1 및 asia-northeast1 리전을 추가하려면 다음 명령어를 실행합니다.
```
docker-credential-gcr configure-docker --registries=us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
```
지정된 호스트 이름이 사용자 인증 정보 도우미 구성에 추가됩니다. 나중에 이 명령어를 다시 실행하여 구성에 다른 호스트 이름을 추가할 수 있습니다.

지원되는 저장소 위치 목록을 보려면 다음 명령어를 실행합니다.
```
gcloud artifacts locations list
```
자세한 내용은 GitHub의 독립형 Docker 사용자 인증 정보 도우미 문서를 참조하세요.

참고: 일반적으로 sudo를 사용하여 Linux에서 Docker 명령을 실행하는 경우, Docker는 $HOME/.docker/config.json 대신 /root/.docker/config.json에서 Artifact Registry 사용자 인증 정보를 찾습니다. Docker 보안 그룹을 사용하는 대신 docker 명령어에 sudo를 사용하려면 대신 sudo docker-credential-gcr configure-docker로 사용자 인증 정보를 구성합니다.

사용자 인증 정보는 사용자 홈 디렉터리에 저장됩니다.
- Linux: $HOME/.docker/config.json
- Windows: %USERPROFILE%/.docker/config.json
Docker를 사용하려면 사용자 인증 정보 도우미가 PATH 시스템에 있어야 합니다. docker-credential-gcr 명령어가 PATH 시스템에 있는지 확인합니다.
사용자 인증 정보 도우미가 사용자 인증 정보를 성공적으로 검색할 수 있는지 확인하려면 다음 명령어를 실행합니다.
```
echo "https://HOSTNAME" | docker-credential-gcr get
```
HOSTNAME을 구성에 추가한 호스트 이름으로 바꿉니다. 예를 들면 다음과 같습니다.
```
echo "https://us-central1-docker.pkg.dev" | docker-credential-gcr get
```
명령어가 성공하면 반환된 JSON 출력에 Secret 필드의 토큰이 포함됩니다. 예를 들면 다음과 같습니다.
```
{"ServerURL":"https://us-central1-docker.pkg.dev","Username":"_dcgcr_2_0_0_token","Secret":"ya29..."}
```

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

액세스 토큰

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

서비스 계정 사용자 인증 정보에 액세스 토큰을 사용하려면 다음 안내를 따르세요.

애플리케이션 대신 작동하도록 서비스 계정을 만들거나 자동화에 사용할 기존 서비스 계정을 선택합니다.
저장소 액세스 권한을 부여하기 위해 서비스 계정에 적절한 Artifact Registry 역할을 부여합니다.
서비스 계정에 대한 액세스 토큰을 생성하고 인증합니다.
- 서비스 계정을 가장하고 서비스 계정에 대한 토큰을 가져온 후 서비스 계정으로 인증할 수 있는 서비스 계정 토큰 생성자 역할(roles/iam.serviceAccountTokenCreator)의 권한이 있어야 합니다.
  
  다음 명령어를 실행하고, ACCOUNT는 서비스 계정 이메일 주소로 바꾸고 LOCATION은 저장소의 리전 또는 멀티 리전 위치로 바꿉니다.
  Linux
```
gcloud auth print-access-token \
    --impersonate-service-account ACCOUNT | docker login \
    -u oauth2accesstoken \
    --password-stdin https://LOCATION-docker.pkg.dev
```
  Windows
```
gcloud auth print-access-token --impersonate-service-account ACCOUNT |
    docker login -u oauth2accesstoken --password-stdin https://LOCATION-docker.pkg.dev
```

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

서비스 계정 키

서비스 계정의 유효한 비공개 키에 액세스할 수 있는 사용자는 누구나 서비스 계정을 통해 리소스에 액세스할 수 있습니다. 서비스 계정에 대한 키의 액세스 수명주기(즉, 서비스 계정이 액세스한 데이터)는 키를 다운로드한 사용자의 수명주기와 관계가 없습니다.

다음 가이드라인을 사용하여 저장소에 대한 액세스를 제한합니다.

저장소와 상호작용하는 데만 사용되는 전용 서비스 계정을 만듭니다.
서비스 계정에 필요한 액세스 권한에 대한 특정 Artifact Registry 역할을 부여합니다. 예를 들어 아티팩트를 다운로드만 하는 서비스 계정에는 Artifact Registry 리더 역할만 필요합니다.
프로젝트 수준 대신 각 저장소의 전용 서비스 계정에 대한 권한을 구성합니다. 그러면 저장소 컨텍스트를 기준으로 액세스를 지정할 수 있습니다. 예를 들어 개발 빌드에 사용되는 서비스 계정에는 프로덕션 저장소에 대한 Artifact Registry 리더 역할이 있고 스테이징 저장소에 대한 Artifact Registry 작성자 역할이 있을 수 있습니다.
사용자 인증 정보 관리 권장사항을 따릅니다.

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

애플리케이션 대신 작동하도록 서비스 계정을 만들거나 자동화에 사용할 기존 서비스 계정을 선택합니다.

Artifact Registry로 인증을 설정하려면 서비스 계정 키 파일의 위치가 필요합니다. 기존 계정의 경우 서비스 계정 페이지에서 키를 보고 새 키를 만들 수 있습니다.

서비스 계정 페이지로 이동

참고: 서비스 계정 키를 올바르게 관리하지 않으면 보안 위험을 초래할 수 있습니다. 가능한 한 서비스 계정 키보다 안전한 대안을 선택해야 합니다. 서비스 계정 키로 인증해야 하는 경우 비공개 키와 서비스 계정 키 관리 권장사항에 설명된 기타 작업을 보호해야 합니다. 서비스 계정 키를 만들 수 없는 경우 서비스 계정 키 생성이 조직에 중지될 수 있습니다. 자세한 내용은 보안 기반 조직 리소스 관리를 참조하세요.
원하는 경우 키 파일의 모든 콘텐츠를 base64로 인코딩할 수 있습니다.
Linux
```
base64 FILE-NAME > NEW-FILE-NAME
```
macOS
```
base64 -i FILE-NAME -o NEW-FILE-NAME
```
Windows
```
Base64.exe -e FILE-NAME > NEW-FILE-NAME
```
여기서 FILE-NAME은 원래 키 파일 이름이고 NEW-FILE-NAME은 base64로 인코딩된 키 파일입니다.
서비스 계정에 대해 권한이 올바르게 구성되었는지 확인합니다. Compute Engine 서비스 계정을 사용하는 경우 권한과 액세스 범위를 모두 올바르게 구성해야 합니다.
서비스 계정 키를 사용하여 Docker와 통합을 구성합니다.

다음 명령어를 실행합니다.
Linux/Mac OS
```
cat KEY-FILE | docker login -u KEY-TYPE --password-stdin \
https://LOCATION-docker.pkg.dev
```
Windows
```
Get-Content KEY-FILE |
docker login -u KEY-TYPE --password-stdin https://LOCATION-docker.pkg.dev
```
다음을 바꿉니다.
- KEY-TYPE은 다음 중 하나입니다.
  - _json_key - 파일을 만들 때 제공된 JSON 형식의 서비스 계정 키를 사용하는 경우
  - _json_key_base64 - 파일의 모든 콘텐츠를 base64로 인코딩한 경우
- KEY-FILE은 JSON 형식의 서비스 계정 키 파일 이름입니다.
- LOCATION은 이미지가 저장된 저장소의 리전 또는 멀티 리전 위치입니다.

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

Docker용 Artifact Registry에 대한 인증 구성

시작하기 전에

Linux

Windows

인증 방법 선택

Docker 구성 파일의 인증 설정

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

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

액세스 토큰

Linux

Windows

서비스 계정 키

Linux

macOS

Windows

Linux/Mac OS

Windows