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 및 Docker 관련 문제 해결 방법을 설명합니다.

도메인 범위 프로젝트

invalid reference format 오류가 표시되는 경우 도메인 범위 프로젝트가 존재하는 것이 문제일 수 있습니다.

프로젝트의 범위가 도메인으로 지정되면 프로젝트 ID에 도메인과 콜론이 포함됩니다(예: example.com:my-project). 도메인을 포함하는 프로젝트 ID를 사용하는 방법은 도메인 범위 프로젝트를 참조하세요.

오류: 상태 405: `v1 Registry API is disabled.`

이미지를 가져오거나 내보낼 때 "v1 Registry API가 사용 중지되었습니다." 같은 오류가 계속 발생한다면, 호스트 이름과 프로젝트 ID, 이미지 이름, 태그나 다이제스트의 철자가 올바른지 확인하세요.

이미지의 태그와 다이제스트를 보려면 다음 명령어를 실행합니다.

gcloud container images list-tags [HOSTNAME]/[PROJECT-ID]/[IMAGE]

예를 들면 다음과 같습니다.

gcloud container images list-tags gcr.io/my-project/my-image

이미지 태그 및 다이제스트 나열에 대한 자세한 내용은 이미지 관리를 참조하세요.

권한 문제

다음 섹션에서는 특정 권한 문제에 대한 해결책을 설명합니다. 항상 내보내기 또는 가져오기에 필요한 권한이 있는지 확인하세요. 권한 및 역할을 참조하세요.

균일한 버킷 수준 액세스와 관련된 권한 문제

Container Registry에서 사용하는 스토리지 버킷에 균일한 버킷 수준 액세스를 사용 설정한 경우 Container Registry로 내보낼 때 또는 가져올 때 액세스 문제가 발생할 수 있습니다.

액세스 문제를 해결하려면 내보내기 또는 가져오기에 필요한 권한이 있는지 확인하세요. 이러한 권한은 권한 및 역할에 나열되어 있습니다.

로컬 머신에서의 Docker 설정 관련 권한 문제

다음 예시와 같은 permission denied 오류가 발생하는 경우:

FATA[0000] Post http://var/run/docker.sock/v1.17/images/gcr.io/container-engine-docs/example/push?tag=: dial unix /var/run/docker.sock: permission denied
ERROR: (gcloud.docker) A Docker command did not run successfully.
Tried to run: 'docker push gcr.io/container-engine-docs/example'
Exit code: 1

본인을 docker 사용자 그룹에 추가해야 할 수도 있습니다.

셸 또는 터미널 창에서 다음 명령어를 실행합니다.

  sudo usermod -a -G docker ${USER}

본인을 docker 사용자 그룹에 추가한 후에 시스템을 다시 시작합니다.

Container Registry와 통신할 때의 권한 문제

다음과 같은 권한 오류가 발생한다면,

Permission denied: Unable to create the repository, please check that you have access to do so

프로젝트에 결제가 사용 설정되었는지 확인합니다.
액세스 권한을 확인합니다.
1. 다음 명령어를 실행하여 gcloud에 대한 인증을 받았는지 확인합니다.
```
gcloud init
```
2. 다음 명령어를 사용하여 Docker가 gcloud를 Container Registry 사용자 인증 정보 도우미로 사용하도록 구성되었는지 확인합니다.
```
gcloud auth configure-docker
```
3. docker-credential-gcloud를 실행할 수 있는지 확인합니다.
```
docker-credential-gcloud list
```
  JSON 객체와 그 키인 대상 레지스트리가 표시됩니다. 예를 들면 다음과 같습니다.
```
{
  "https://asia.gcr.io": "oauth2accesstoken",
  "https://eu.gcr.io": "oauth2accesstoken",
  "https://gcr.io": "oauth2accesstoken",
  "https://us.gcr.io": "oauth2accesstoken"
}
```
4. 이제 내보내는 프로젝트의 Cloud Storage에 대한 쓰기 권한이 있는지 확인해야 합니다. 권한이 없다면 사용자에게 액세스 권한을 부여하도록 관리자에게 요청한 후 다시 시도하세요.
5. 권한 수정 후에도 문제가 지속된다면, 다음 범위 밖에서 액세스 토큰을 얻었을지도 모릅니다.
  - https://www.googleapis.com/auth/devstorage.read_write
  - https://www.googleapis.com/auth/devstorage.full_control
  이를 확인하려면 먼저 액세스 토큰을 직접 받아야 합니다. 방법은 애플리케이션마다 다릅니다. 예를 들어 Compute Engine 기본 서비스 계정에서 얻은 액세스 토큰을 사용한다면, 여기에 있는 지침을 따라야 합니다.
  
  액세스 계정을 직접 얻었다면, 이 명령어를 이용해 액세스 토큰을 얻는데 사용한 범위를 확인할 수 있습니다:
```
curl -H "Authorization: Bearer <your access token>" https://www.googleapis.com/oauth2/v1/tokeninfo
```
  언급된 범위가 포함되지 않았다면, 문제를 해결해 코드에서 액세스 토큰을 얻을 때 해당 범위가 포함되게 해야 합니다. 예를 들어 Compute Engine 가상 머신의 기본 서비스 계정에 대해 특별히 생성된 토큰이라면 해당 가상 머신의 범위 설정을 수정하고 다시 만들어야 합니다.

이미지를 내보낼 때 또는 가져올 때의 권한 문제

이미지를 내보내거나 가져오는 VM 인스턴스는 Container Registry 스토리지 버킷에 액세스하는 데 필요한 IAM 권한과 액세스 범위로 올바르게 구성되어야 합니다. 필수 설정에 대한 자세한 내용은 Google Cloud에서 Container Registry 사용을 참조하세요.

Google Kubernetes Engine의 ImagePullBackoff 오류

GKE는 레지스트리에서 이미지를 가져올 수 없을 때 ImagePullBackoff 오류를 반환합니다. 이 오류는 이미지를 찾을 수 없거나 레지스트리에서 가져올 권한이 노드에 없기 때문일 수 있습니다. 기본적으로 레지스트리가 노드와 동일한 Google Cloud 프로젝트에 있는 경우 Container Registry에서 이미지를 가져올 권한이 GKE 노드에 있습니다.

GKE 문서에는 근본 원인을 식별하고 문제를 해결하기 위한 단계가 포함되어 있습니다.

조직 정책 적용

조직 정책 제약조건은 고객 관리 암호화 키(CMEK) 사용이 필요한 제약조건을 포함하여 Container Registry에 사용되는 서비스에 적용될 때 Container Registry 사용에 영향을 줄 수 있습니다.

이미지를 푸시할 때 잘못된 요청 오류 발생

Cloud Storage API가 constraints/gcp.restrictNonCmekServices 제약 조건에 대한 Deny 정책 목록에 있으면 기본 스토리지 버킷이 CMEK로 암호화되지 않은 경우에 Container Registry에 이미지를 푸시할 수 있습니다. 다음 메시지가 반환됩니다.

unknown: Bad Request

constraints/gcp.restrictCmekCryptoKeyProjects가 구성된 경우에는 허용되는 프로젝트, 폴더, 조직에서 CryptoKey를 사용하여 스토리지 버킷이 암호화되어 있어야 합니다. 호환되지 않는 기존 버킷은 기본적으로 필요한 키를 사용하도록 구성해야 합니다.

스토리지 버킷을 암호화하려면 Cloud Storage 안내를 참조하세요. 레지스트리 호스트의 버킷 이름에는 다음 형식 중 하나가 포함됩니다.

호스트 gcr.io에 저장된 이미지의 경우 artifacts.PROJECT-ID.appspot.com
asia.gcr.io, eu.gcr.io, us.gcr.io에 저장된 이미지의 경우 STORAGE-REGION.artifacts.PROJECT-ID.appspot.com

gcr Pub/Sub 주제가 자동으로 생성되지 않음

Google Cloud 프로젝트에서 Container Registry API를 활성화하면 Container Registry는 Google 관리 암호화 키를 사용하여 주제 ID gcr로 Pub/Sub 주제를 자동으로 만들려고 합니다.

Pub/Sub API가 constraints/gcp.restrictNonCmekServices 제약조건에 대한 Deny 정책 목록에 있으면 주제가 CMEK로 암호화되어야 합니다. CMEK 암호화 없이 주제를 만들려는 요청은 실패합니다.

CMEK 암호화로 gcr 주제를 만들려면 Pub/Sub 주제 암호화 안내를 참조하세요.

할당량 한도

Container Registry의 할당량 한도를 초과하면 다음과 같은 오류 메시지가 표시될 수 있습니다.

Error: Status 429 trying to pull repository [...] "Quota Exceeded."

정해진 할당량 한도를 초과하지 않으려면 다음 방법을 사용하세요.

Container Registry와 통신하는 IP 주소의 수를 늘립니다. 할당량은 IP 주소별로 지정됩니다.
지연을 초래하는 재시도를 추가합니다. 예를 들어 지수 백오프를 사용할 수도 있습니다.

boot2docker가 있는 잘못된 레지스트리 엔드포인트

boot2docker 환경에서 Container Registry에 접근하는 데 문제가 있다면,

docker push gcr.io/example/sample

Error response from daemon: invalid registry endpoint https://gcr.io/v0/:
  unable to ping registry endpoint https://gcr.io/v0/
v2 ping attempt failed with error: Get https://gcr.io/v2/:
  x509: certificate has expired or is not yet valid
v1 ping attempt failed with error: Get https://gcr.io/v1/_ping:
  x509: certificate has expired or is not yet valid.
If this private registry supports only HTTP or HTTPS with an unknown CA
certificate, please add `--insecure-registry gcr.io` to the daemon's
arguments. In the case of HTTPS, if you have access to the registry's CA
certificate, no need for the flag; simply place the CA certificate at
/etc/docker/certs.d/gcr.io/ca.crt

boot2docker를 다시 시작해보세요.

boot2docker stop
boot2docker start

루트 수준 이미지 푸시 오류

컨테이너 이미지를 푸시하려고 하면 다음을 포함하는 메시지와 함께 푸시가 실패합니다.

Pushing to root-level images is disabled

이 메시지는 호스트 이름과 이미지를 이미지에 태그했지만 프로젝트 ID가 포함되지 않았음을 나타냅니다.

올바른 이미지 경로 형식을 사용하여 이미지에 태그를 지정합니다.

HOSTNAME/PROJECT-ID/IMAGE:TAG

예를 들면 gcr.io/web-project/web-app:1.0입니다.

Mac용 Docker

Mac용 Docker에서 문제가 발생한다면, 해결 방법을 시도해봐야 합니다. 대표적인 오류에는 응답하지 않는 Docker 내보내기/가져오기 작업 및 다음과 비슷한 네트워크 오류 등이 있습니다.

Post https://us.gcr.io/v2/[repo name]/blobs/uploads/: dial tcp xx.xxx.xx.xx:xxx: i/o timeout

이러한 오류가 발생하면 다음 단계를 시도해보세요.

Mac 단말기에서 docker-machine restart default 명령어를 실행하여 Docker 데몬을 다시 시작합니다.
Docker의 환경설정 메뉴에서 "Securely store docker logins in macOS keychain"(Docker 로그인 정보를 macOS 키체인에 안전하게 저장)이 사용 설정되지 않은 상태인지 확인합니다.
Docker 최신 버전을 실행 중인지 확인합니다.