문제해결

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

도메인 범위 프로젝트

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

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

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

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

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

다음 예시와 같은 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 목록

      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 https://www.googleapis.com/oauth2/v1/tokeninfo?access_token=<your access token>
          

      언급된 범위가 포함되지 않았으면 문제를 해결해 코드에서 액세스 토큰을 가져올 때 해당 범위가 포함되게 해야 합니다. 예를 들어 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 최신 버전을 실행 중인지 확인합니다.