Blog

🚨 도입부

Docker를 사용하다 보면 “Image not found or pull access denied”라는 에러 메시지를 만나는 순간, 여러분도 한 번쯤은 짜증이 났던 경험이 있을 것입니다. 이 에러는 특히 프로젝트의 중요한 시점에 발생하여 개발자의 시간을 허비하게 만들곤 하죠. 예를 들어, 새로운 CI/CD 파이프라인을 설정하던 중에, 또는 팀원이 공유한 Dockerfile을 실행하던 중에, 아니면 단순히 새로운 이미지를 당겨오려 시도할 때 발생할 수 있습니다. 이 글에서는 이러한 상황에서 겪는 어려움을 이해하고, 구체적인 해결책을 제공합니다. 예를 들어, 이미지 레포지터리 접근 권한 문제를 해결하거나, 이미지 태그 오타를 수정하는 방법 등을 알아보게 됩니다. 일반적으로 이 문제를 해결하는 데는 5분에서 30분 정도가 소요될 수 있으며, 난이도는 초중급 수준입니다.

🔍 에러 메시지 상세 분석

“Image not found or pull access denied”는 Docker에서 이미지를 당겨오려 할 때 발생하는 에러입니다. 이 에러는 “Error response from daemon: repository does not exist or may require ‘docker login'” 또는 “manifest for : not found”와 같은 변형으로 나타날 수 있습니다. 이러한 메시지는 주로 이미지가 존재하지 않거나, 레포지터리에 대한 접근 권한이 부족할 때 발생합니다. 특히 이미지의 이름이나 태그가 잘못되었거나, 이미지가 비공개로 설정된 경우에 자주 발생합니다. 초보자는 이 에러 메시지를 읽을 때 각 부분의 의미를 해석하기 어려울 수 있습니다. 예를 들어, “repository does not exist”는 이미지 이름이나 태그가 잘못되었음을 의미하며, “require ‘docker login'”은 레포지터리 접근 권한이 없음을 나타냅니다. 이 에러와 혼동하기 쉬운 비슷한 에러로는 “unauthorized: authentication required”가 있습니다. 이 또한 인증 문제가 원인일 수 있습니다.

🧐 발생 원인 분석

이 에러의 주요 원인으로는 다음과 같은 것들이 있습니다:

• 이미지 이름이나 태그가 잘못되었습니다. 예를 들어, “nginx:latest” 대신 “nginx:lates”와 같이 오타가 있는 경우입니다. 이미지 이름과 태그는 대소문자를 구분하므로 주의해야 합니다.
• 이미지가 비공개 레포지터리에 저장되어 있어, 접근 권한이 없는 경우입니다. 이 경우, 해당 레포지터리에 로그인해야 합니다. 개발 환경에 따라 이 문제가 발생할 수 있으며, 예를 들어, 사내 레포지터리를 사용하는 경우에는 더욱 주의가 필요합니다.
• 레포지터리 URL이 잘못되었거나, 레포지터리 서버가 다운되어 있는 경우입니다. 특히 사내에서 운영하는 레포지터리 서버가 유지보수 중인 경우, 이러한 문제가 발생할 수 있습니다.
• Docker Hub 또는 다른 퍼블릭 레포지터리의 네트워크 장애로 인해 접근이 불가능한 경우입니다. 이 경우에는 네트워크 상태를 확인해야 합니다.
• Docker가 설치된 환경의 버전이 오래되어, 최신 레포지터리 프로토콜을 지원하지 않는 경우입니다. 이 경우, Docker의 버전을 최신으로 업그레이드해야 합니다.

각 원인별 간단한 확인 방법으로, 이미지 이름과 태그를 다시 확인하거나, 레포지터리에 로그인하여 접근 권한을 확인하는 것이 있습니다. 또한, 네트워크 상태를 점검하거나, Docker 버전을 확인하는 것도 유용합니다.

✅ 해결 방법

다양한 상황에 맞는 해결 방법을 제공합니다:

즉시 해결

• 오타 확인: 이미지 이름과 태그를 다시 확인하고, 오타가 있는지 점검합니다. 예를 들어, “nginx:lates” 대신 “nginx:latest”로 수정합니다.
• 로그인: 비공개 레포지터리 경우, 다음 명령어로 로그인합니다:

  docker login -u  -p 

  이 명령어는 Docker 레지스트리에 로그인하여 접근 권한을 부여합니다.

• 네트워크 확인: 네트워크 상태를 점검하고, 문제가 있는 경우 해결합니다. 이를 위해 ping 명령어를 사용하여 레포지터리 서버에 대한 연결을 확인합니다.

  ping registry-1.docker.io

표준 해결

• 정확한 이미지 정보 확인: 공식 문서나 팀 내 공유 문서를 통해 이미지 이름과 태그의 정확성을 검증합니다.
• Docker 버전 업데이트: 오래된 Docker 버전으로 인해 발생할 수 있는 문제를 방지하기 위해, Docker를 최신 버전으로 업데이트합니다.

  sudo apt-get update && sudo apt-get install docker-ce docker-ce-cli containerd.io

• 레포지터리 서버 상태 확인: 사내 레포지터리 서버의 상태를 점검하고, 필요 시 IT 팀에 문의하여 문제를 해결합니다.
• 캐시 정리: Docker의 캐시를 정리하여, 오래된 이미지 정보를 제거합니다.

  docker system prune --volumes

• 대체 이미지 사용: 동일한 기능을 제공하는 다른 이미지를 사용하는 것도 하나의 방법입니다.

고급 해결

• 사내 레포지터리 설정 문제 해결: 사내 레포지터리의 설정 문제로 인해 발생할 수 있는 접근 문제를 해결합니다. 특히, 사내 레포지터리가 프록시 서버 뒤에 있는 경우, 프록시 설정을 확인합니다.
• 보안 정책 검토: 조직의 보안 정책에 따라 레포지터리 접근 권한이 제한될 수 있으므로, 정책을 검토하고 필요 시 보안 팀과 협력하여 접근 권한을 수정합니다.
• 레포지터리 미러 설정: Docker Hub의 네트워크 문제를 방지하기 위해, 미러 레포지터리를 설정하여 사용합니다.

  {
    "registry-mirrors": ["https://.com"]
  }

  이 설정은 Docker 설정 파일에 추가하여 적용할 수 있습니다.

각 방법의 장단점은 사용 환경에 따라 다르며, 해결 후에는 Docker 로그를 확인하여 문제가 해결되었는지 점검합니다. 예를 들어, “docker images” 명령어로 이미지 목록을 확인합니다.

🛡️ 예방법 및 베스트 프랙티스

이 에러가 재발하지 않도록 하기 위한 방법으로는 다음과 같은 것들이 있습니다:

• 정확한 문서화: 이미지 이름과 태그, 레포지터리 정보를 정확히 문서화하여 팀 내에서 공유합니다.
• 정기적인 업데이트: Docker와 레포지터리 서버를 정기적으로 업데이트하여 최신 상태를 유지합니다.
• 보안 정책 준수: 조직의 보안 정책을 준수하고, 접근 권한 관리를 철저히 합니다.
• CI/CD 파이프라인 설정: 자동화된 CI/CD 파이프라인을 설정하여, 이미지 빌드 및 배포 과정을 자동화합니다.
• 모니터링 도구 사용: 네트워크 상태 및 레포지터리 서버 상태를 모니터링할 수 있는 도구를 사용합니다.

🎯 마무리 및 추가 팁

이번 글에서는 “Image not found or pull access denied” 에러의 원인과 해결 방법을 살펴보았습니다. 중요한 내용은 다음과 같습니다: 이미지 이름과 태그의 정확성 확인, 레포지터리 접근 권한 문제 해결, Docker 및 레포지터리 서버 업데이트 유지. 비슷한 에러로는 “unauthorized: authentication required”가 있으며, 이는 인증 문제일 수 있습니다. 추가 학습을 원하시는 분들은 Docker 공식 문서와 관련 포럼을 참고하시면 좋습니다. 여러분의 개발 여정에 도움이 되길 바라며, 에러 해결에 있어 자신감을 가지시길 응원합니다!