문제 해결

이 섹션에서는 일반적인 Container Registry 및 Docker 관련 문제 해결 방법을 설명합니다.

도메인 범위 프로젝트

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

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

오류: Status 405: "v1 Registry API가 사용 중지되었습니다."

이미지를 가져오거나 내보낼 때 "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로 내보낼 때 또는 가져올 때 액세스 문제가 발생할 수 있습니다.

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

다음 예시와 같은 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. 프로젝트에 결제가 사용 설정되었는지 확인합니다.

  2. 액세스 권한을 확인합니다.

    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://staging-k8s.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를 사용하는 데 필요한 요구사항을 참조하세요.

할당량 한도

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

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 최신 버전을 실행 중인지 확인합니다.