본문으로 건너뛰기

Container Registry 서비스 문제 해결

본 문서는 Container Registry 서비스 관련 문제를 해결하기 위한 방법을 설명합니다.

도커 로그인 실패 오류​

발급받은 액세스 키 ID와 보안 액세스 키로 Docker 로그인을 시도할 때, Login Succeeded 대신 아래와 같은 오류가 발생할 수 있습니다.

Get "RepositoryURI": unauthorized: login failed​

오류 메시지
Error response from daemon: Get "${repository_uri}": unauthorized: login failed

이 오류는 발급받은 액세스 키 ID와 보안 액세스 키가 잘못 입력되었거나, 만료되었을 경우 나타나는 오류입니다.

▶️ 해결 방법: 액세스 키 ID와 보안 액세스 키의 입력이 잘못되었는지 확인하거나, 액세스 키가 만료된 경우 새로운 액세스 키를 발급받아 다시 로그인해 주십시오. 기술문서의 액세스 키 발급 가이드를 참고할 수 있습니다.

Get "RepositoryURI": net/http: request canceled while waiting for connection​

오류 메시지
Error response from daemon: Get "${repository_uri}": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

이 오류는 요청하는 환경에서 도메인 쿼리가 정상적으로 이루어지지 않을 때 발생할 수 있습니다.

▶️ 해결 방법: ${repository_uri} 쿼리가 정상적으로 실행되면 문제가 해결됩니다. 아래의 해결 방법을 참고하세요.

  1. 오류 메시지에서 확인한 ${repository_uri}에서 도메인(호스트네임) 부분만을 대상으로 DNS 문제 여부를 확인합니다. 예를 들어, ${repository_uri}가 https://myproject.kr-central-2.kcr.dev/myrepo/이라면 myproject.kr-central-2.kcr.dev만을 사용하여 쿼리합니다.

    # 입력
    nslookup `${repository_uri_domain}`

    # 출력
    ;; communications error to ${dns_server_ip}#53: timed out

  2. 이 오류는 쿼리에 사용되는 DNS 서버 문제로 인해 발생할 수 있습니다. 직접 구성한 DNS 서버라면 조치가 필요하며, 조치가 어려운 경우 외부 DNS 서버 사용을 고려해야 합니다. (단, 외부 DNS 서버 사용할 경우, 다른 구성상의 문제는 없는지 확인이 필요합니다.)

이미지 Pull 오류​

failed to resolve reference "ImageURI": failed to do request: Head Image"​

Kubernetes Engine 클러스터 환경에서 이미지 Pull 작업 시, 다음과 같은 오류가 발생할 수 있습니다.

오류 메시지
failed to resolve reference "${image_uri}": failed to do request: Head "${image_manifest_uri}": dial tcp 61.109.235.253:443: connect: network is unreachable

현재 Container Registry 서비스는 인터넷 연결이 가능한 환경에서만 사용이 지원됩니다. 따라서 위와 같은 오류 메시지는 이미지 다운로드 환경에서 외부(Container Registry)와의 네트워크 연결이 차단된 경우 발생할 수 있습니다.

▶️ 해결 방법: Private 환경에서 Container Registry 이미지를 반드시 Pull 해야 한다면, NAT 인스턴스를 통해 외부 통신을 설정할 수 있습니다.

이미지 Push 오류​

denied: requested access to the resource is denied​

리포지토리에 이미지를 Push할 때, 다음과 같은 오류가 발생할 수 있습니다.

오류 메시지
denied: requested access to the resource is denied

이 오류는 여러 원인으로 발생할 수 있으며, 각 원인에 대한 해결 방안은 다음과 같습니다.

1. 이미지 Push 요청 계정이 리포지토리 뷰어 권한만 보유한 경우​

리포지토리 뷰어 권한은 이미지 Pull 작업만 허용하며, Push 작업은 지원하지 않습니다.

▶️ 해결 방법: 리포지토리를 공개 리포지토리로 변경하거나, 해당 계정을 리포지토리 멤버 권한으로 조정하세요. 자세한 내용은 Container Registry 접근 권한 가이드를 참고하시기 바랍니다.

2. 이미지 Push 요청 계정이 프로젝트 리더 권한을 가진 경우​

프로젝트 리더(reader)는 이미지 Pull만 가능하며, Push 작업 권한을 가질 수 없습니다.

▶️ 해결 방법: 프로젝트 리더 계정에는 리포지토리 멤버 권한을 직접 부여할 수 없으므로, 해당 계정의 IAM 역할 변경을 고려하세요. 다른 프로젝트에는 리포지토리 멤버로 등록할 수 있지만, 프로젝트 리더로 설정되어 있는 현재 프로젝트에서는 권한 설정이 제한됩니다.

3. 리포지토리가 비공개로 설정된 경우​

비공개 리포지토리의 경우 프로젝트에 속하지 않은 사용자나 익명 사용자는 이미지 Push가 불가능합니다.

▶️ 해결 방법: 이미지 Push가 필요한 계정의 권한을 리포지토리 멤버로 변경하여 접근을 허용하세요. 리포지토리 멤버로 추가하는 법에 대해서는 리포지토리 권한 설정 가이드를 참고하실 수 있습니다.

권한 설정 오류: "권한을 변경하는 데 실패했습니다." 메시지 발생​

권한 설정 중 사용자 추가 시 "권한을 변경하는 데 실패했습니다." 오류가 발생할 수 있습니다.

▶️ 해결 방법: 프로젝트 내 사용자를 추가할 경우 해당 오류는 정상 동작입니다.

사용자가 프로젝트 관리자 또는 프로젝트 멤버 역할을 가진 경우, 자동으로 Container Registry 관리자 권한이 부여됩니다. 반면, 프로젝트 리더는 리소스 조회만 가능한 기본 IAM 사용자 역할이 우선 적용되어, 추가 권한 설정이 불가능합니다.