Docker 'pull access denied' 오류 해결 방법 - 문제 해결 및 예방

소개

Docker 는 애플리케이션 배포 및 관리를 단순화하는 강력한 컨테이너화 플랫폼입니다. 하지만 사용자는 Docker 이미지를 pull 하려고 할 때 'pull access denied' 오류를 종종 겪을 수 있습니다. 이 포괄적인 튜토리얼은 이 흔한 Docker 문제를 이해하고, 문제 해결 및 해결하는 과정을 안내합니다.

이 랩을 통해 Docker 이미지 레지스트리 (registry) 가 어떻게 작동하는지, 액세스 거부 오류가 발생하는 이유를 배우고, 인증 문제를 해결하는 실질적인 기술을 개발할 것입니다. 이 튜토리얼이 끝나면 컨테이너화 워크플로우에서 Docker 이미지 액세스 문제를 자신 있게 처리할 수 있게 될 것입니다.

Docker 레지스트리 (Registry) 이해 및 기본 이미지 풀링 (Pulling)

"pull access denied" 오류를 살펴보기 전에 Docker 레지스트리와 이미지 풀링이 어떻게 작동하는지 이해해 보겠습니다.

Docker 레지스트리란 무엇인가요?

Docker 레지스트리는 Docker 이미지를 위한 저장 시스템입니다. 컨테이너 이미지를 푸시 (업로드) 하고 풀 (다운로드) 할 수 있습니다. Docker Hub 는 기본 공용 레지스트리이지만, 조직에서 독점 이미지를 저장하는 데 사용하는 개인 레지스트리를 포함하여 다른 많은 레지스트리가 있습니다.

먼저 Docker 가 시스템에 제대로 설치되었는지 확인해 보겠습니다. 터미널을 열고 다음을 실행합니다.

docker --version

다음과 유사한 출력을 볼 수 있습니다.

Docker version 20.10.21, build baeda1f

Docker Hub 에서 공용 이미지 풀링

이제 Docker Hub 에서 간단한 공용 이미지를 풀링해 보겠습니다. 이미지를 풀링하는 기본 구문은 다음과 같습니다.

docker pull [registry/][username/]repository[:tag]

작고 일반적으로 사용되는 공식 Alpine Linux 이미지를 풀링해 보겠습니다.

docker pull alpine:latest

다음과 유사한 출력을 볼 수 있습니다.

latest: Pulling from library/alpine
c158987b0551: Pull complete
Digest: sha256:bc41182d7ef5ffc53a40b044e725193bc10142a1243f395ee852a8d9730fc2ad
Status: Downloaded newer image for alpine:latest
docker.io/library/alpine:latest

이것은 공용 이미지를 성공적으로 풀링할 수 있음을 확인합니다. 다운로드된 이미지를 확인하기 위해 모든 Docker 이미지를 나열해 보겠습니다.

docker images

목록에 alpine 이미지가 표시됩니다.

REPOSITORY   TAG       IMAGE ID       CREATED        SIZE
alpine       latest    9c6f07244728   2 weeks ago    5.54MB

Docker 이미지 명명 규칙

액세스 문제를 해결하려면 Docker 이미지 명명 규칙을 이해하는 것이 중요합니다.

Registry: 레지스트리가 있는 호스트 이름 (기본값은 Docker Hub)
Username/Organization: 레포지토리 (repository) 를 소유한 계정
Repository: 이미지의 이름
Tag: 이미지의 특정 버전 (기본값은 "latest")

예를 들어, docker.io/nginx:1.21에서 레지스트리는 docker.io이고, 레포지토리는 nginx이며, 태그는 1.21입니다.

레지스트리를 지정하지 않으면 Docker 는 Docker Hub 를 사용한다고 가정합니다. 사용자 이름 또는 조직을 지정하지 않으면 Docker 는 공식 이미지가 포함된 "library" 네임스페이스를 검색합니다.

"Pull Access Denied" 오류 발생

Docker 이미지 풀링의 기본 사항을 이해했으므로 "pull access denied" 오류를 살펴보겠습니다. 이 오류는 일반적으로 액세스 권한이 없는 이미지를 풀려고 할 때 발생합니다.

오류 발생 시나리오 만들기

"pull access denied" 오류를 의도적으로 트리거하기 위해 존재하지 않거나 개인 이미지를 풀링해 보겠습니다. 가상의 개인 이미지를 풀링하려고 시도합니다.

docker pull labex/private-repo:latest

다음과 유사한 오류 메시지가 표시됩니다.

Error response from daemon: pull access denied for labex/private-repo, repository does not exist or may require 'docker login': denied: requested access to the resource is denied

이 오류는 다음 중 하나로 인해 발생합니다.

레포지토리 (repository) 가 존재하지 않음
레포지토리가 존재하지만 비공개이며 인증되지 않음
인증되었지만 이 레포지토리에 액세스할 권한이 없음

Docker 레지스트리 (Registry) 에 대한 인증 이해

Docker 는 개인 레지스트리에 대해 간단한 인증 시스템을 사용합니다. 개인 이미지를 풀링하기 전에 docker login 명령을 사용하여 인증해야 합니다.

docker login [registry-url]

레지스트리 URL 이 제공되지 않으면 Docker 는 Docker Hub 에 로그인한다고 가정합니다.

Docker Hub 에 로그인해 보겠습니다 (Docker Hub 계정이 있는 경우 해당 계정을 사용하거나, 프롬프트를 확인한 다음 Ctrl+C 를 눌러 취소할 수 있습니다).

docker login

사용자 이름과 비밀번호를 묻는 메시지가 표시됩니다.

Login with your Docker ID to push and pull images from Docker Hub. If you don't have a Docker ID, head over to https://hub.docker.com to create one.
Username:

이 연습을 위해 실제로 로그인할 필요가 없으므로 Ctrl+C 를 눌러 로그인 프로세스를 취소할 수 있습니다.

"Pull Access Denied" 오류의 일반적인 원인

"pull access denied" 오류는 여러 가지 이유로 발생할 수 있습니다.

잘못된 레포지토리 이름: 레포지토리 이름을 잘못 입력했을 수 있습니다.
레포지토리가 존재하지 않음: 액세스하려는 레포지토리가 존재하지 않습니다.
인증 필요: 레포지토리가 비공개이며 로그인이 필요합니다.
권한 부족: 인증되었지만 액세스 권한이 없습니다.
Rate limiting (속도 제한): Docker Hub 는 인증되지 않은 사용자에 대한 풀링을 제한합니다.

Docker 데몬 로그 확인

액세스 문제를 해결할 때 Docker 데몬 로그를 확인하는 것이 도움이 되는 경우가 많습니다.

sudo journalctl -u docker | tail -n 20

이것은 Docker 의 시스템 로그의 마지막 20 줄을 표시하며, 액세스 거부 오류에 대한 추가 정보를 포함할 수 있습니다.

"Pull Access Denied" 오류 해결

"pull access denied" 오류의 원인을 이해했으므로, 이를 해결하는 방법을 알아보겠습니다. 가장 일반적인 원인에 따라 몇 가지 해결 방법을 살펴보겠습니다.

해결 방법 1: 레포지토리 (Repository) 이름 및 태그 확인

액세스 오류의 가장 일반적인 원인 중 하나는 잘못된 레포지토리 이름이나 태그를 사용하는 것입니다. 이미지 이름에 오타가 없는지 항상 다시 확인하십시오.

특정 태그가 있는 유효한 이미지를 풀링해 보겠습니다.

docker pull nginx:1.21.0

출력은 성공적인 풀을 보여야 합니다.

1.21.0: Pulling from library/nginx
a330b6cecb98: Pull complete
b847ebd0aed4: Pull complete
543e2db69aaf: Pull complete
... (more lines)
Digest: sha256:2f1cd90e00fe2a0aa8969938c6a4135443ac6c7e50d255a54b57ba1a21086ce3
Status: Downloaded newer image for nginx:1.21.0
docker.io/library/nginx:1.21.0

해결 방법 2: 레지스트리 (Registry) 로 인증

비공개 레포지토리에 액세스하려는 경우 먼저 인증해야 합니다.

docker login [registry-url]

인증에 성공하면 Docker 는 자격 증명을 ~/.docker/config.json의 구성 파일에 저장합니다. 이 파일이 있는지 확인해 보겠습니다.

ls -la ~/.docker/

이전에 로그인한 적이 있다면 config.json 파일이 나열되어야 합니다.

해결 방법 3: 레지스트리 (Registry) 속도 제한 확인

Docker Hub 는 풀링에 속도 제한을 적용합니다.

익명 사용자: IP 주소당 6 시간마다 100 회 풀링
인증된 사용자: 계정당 6 시간마다 200 회 풀링

속도 제한에 도달한 경우, 제한을 늘리기 위해 인증합니다.

docker login

해결 방법 4: 명시적 레지스트리 (Registry) URL 사용

경우에 따라 전체 레지스트리 URL 을 지정하면 액세스 문제를 해결하는 데 도움이 될 수 있습니다.

docker pull docker.io/library/ubuntu:20.04

이 명시적 형식은 Docker 가 연결할 레지스트리를 올바르게 식별하는 데 도움이 됩니다.

다른 공용 이미지 풀링을 통해 액세스 테스트

다른 이미지를 풀링하여 여전히 공용 이미지를 풀링할 수 있는지 확인해 보겠습니다.

docker pull hello-world

성공적인 풀을 확인하는 출력이 표시되어야 합니다.

Using default tag: latest
latest: Pulling from library/hello-world
2db29710123e: Pull complete
Digest: sha256:6e8b6f026e0b9c419ea0fd02d3905dd0952ad1feea67543f525c73a0a790fefb
Status: Downloaded newer image for hello-world:latest
docker.io/library/hello-world:latest

이제 모든 것이 제대로 작동하는지 확인하기 위해 hello-world 컨테이너를 실행합니다.

docker run hello-world

Docker 의 환영 메시지가 표시되어야 합니다.

Hello from Docker!
This message shows that your installation appears to be working correctly.
...

문제 해결 체크리스트

"pull access denied" 오류가 발생하면 다음 체크리스트를 따르십시오.

이미지 이름과 태그가 올바른지 확인합니다.
레포지토리가 존재하는지 확인합니다 (Docker Hub 에서 검색).
레포지토리가 비공개인 경우 인증합니다.
속도 제한 문제를 확인합니다.
자세한 오류 메시지를 위해 Docker 데몬 로그를 검사합니다.
레지스트리에 대한 네트워크 연결을 확인합니다.

개인 레지스트리 (Registry) 작업

많은 실제 시나리오에서 개인 Docker 레지스트리로 작업해야 합니다. 이러한 레지스트리는 인증과 신중한 자격 증명 관리가 필요합니다. 이를 효과적으로 사용하는 방법을 알아보겠습니다.

개인 레지스트리 (Registry) 유형

사용 가능한 몇 가지 개인 레지스트리 옵션이 있습니다.

Docker Hub 개인 레포지토리 (Repository): Docker Hub 의 개인 레포지토리
Docker Registry: Docker 의 오픈 소스 레지스트리 구현
Docker Trusted Registry (DTR): Docker Enterprise 의 일부
타사 레지스트리: AWS ECR, Google Container Registry, GitHub Container Registry 등

테스트를 위한 간단한 로컬 레지스트리 (Registry) 설정

학습 목적으로 로컬 Docker 레지스트리를 설정해 보겠습니다. 이를 통해 개인 레지스트리가 어떻게 작동하는지 이해하는 데 도움이 됩니다.

docker run -d -p 5000:5000 --name registry registry:2

이 명령은 포트 5000 에서 개인 레지스트리 컨테이너를 시작합니다. 성공하면 컨테이너 ID 출력이 표시됩니다.

이미지를 로컬 레지스트리 (Registry) 로 푸시

기존 이미지를 수정하고 로컬 레지스트리로 푸시해 보겠습니다.

먼저, 기존 이미지에 로컬 레지스트리 주소로 태그를 지정합니다.

docker tag nginx:1.21.0 localhost:5000/my-nginx:v1

이미지를 로컬 레지스트리로 푸시합니다.

docker push localhost:5000/my-nginx:v1

푸시 진행 상황을 보여주는 출력이 표시되어야 합니다.

The push refers to repository [localhost:5000/my-nginx]
72a69066d2fe: Pushed
1e7cb45d18ab: Pushed
c8db6be2bb1a: Pushed
... (more layers)
v1: digest: sha256:... size: 1570

이제 로컬 이미지를 제거하고 레지스트리에서 풀링해 보겠습니다.

docker image rm localhost:5000/my-nginx:v1
docker pull localhost:5000/my-nginx:v1

로컬 레지스트리에서 이미지가 성공적으로 풀링되는 것을 볼 수 있습니다.

레지스트리 (Registry) 인증 작업

프로덕션 개인 레지스트리의 경우 인증을 적절하게 처리해야 합니다. 개인 레지스트리에 로그인하면 Docker 는 자격 증명을 구성 파일에 저장합니다.

개인 레지스트리로 인증하려면 다음을 수행합니다.

docker login [registry-url]

인증 후에는 일반적으로 이미지를 풀링할 수 있습니다.

docker pull [registry-url]/[repository]:[tag]

보안상의 이유로 완료되면 로그아웃해야 합니다.

docker logout [registry-url]

레지스트리 (Registry) 자격 증명 안전하게 저장

자동화된 시스템의 경우 자격 증명을 안전하게 저장하는 것이 중요합니다. 다음을 사용할 수 있습니다.

Docker 자격 증명 도우미 (credential helpers)
docker login 을 사용한 환경 변수
Docker secrets (swarm 모드에서)

현재 자격 증명 저장소를 확인해 보겠습니다.

cat ~/.docker/config.json | grep -v auth

Docker 설정에 대한 구성 세부 정보를 볼 수 있습니다.

정리

테스트 레지스트리를 중지하고 제거해 보겠습니다.

docker stop registry
docker rm registry

이렇게 하면 테스트를 위해 생성한 로컬 레지스트리 컨테이너가 제거됩니다.

액세스 문제 방지를 위한 모범 사례

"pull access denied" 오류를 해결하는 방법을 배웠으니, 이제 향후 이러한 문제를 방지하기 위한 모범 사례를 살펴보겠습니다.

완전한 정규 이미지 이름 사용

모호성을 피하기 위해 항상 완전한 정규 이미지 이름을 사용하십시오.

docker pull docker.io/library/ubuntu:20.04

이를 통해 액세스하려는 레지스트리, 리포지토리 및 태그를 명확하게 알 수 있습니다.

자격 증명 도우미 설정

Docker 자격 증명 도우미는 레지스트리 자격 증명을 안전하게 저장합니다. 운영 체제에 적합한 도우미를 설치하십시오.

Ubuntu 의 경우 pass 기반 자격 증명 도우미를 사용할 수 있습니다.

sudo apt-get update
sudo apt-get install -y pass

그런 다음 GPG 키를 생성합니다 (데모 목적으로 Enter 키를 눌러 기본값을 수락할 수 있습니다).

gpg --generate-key

이전 출력에서 가져온 실제 키 ID 로 GPG 키 ID 를 사용하여 pass 를 초기화합니다.

pass init "Your GPG Key ID"

Docker 자격 증명 도우미를 설치합니다.

sudo apt-get install -y docker-credential-pass

기본 레지스트리 설정 구성

Docker 데몬 구성 파일에서 기본 레지스트리 설정을 구성할 수 있습니다. 간단한 구성을 만들어 보겠습니다.

sudo mkdir -p /etc/docker
echo '{
  "registry-mirrors": ["https://registry-mirror.example.com"]
}' | sudo tee /etc/docker/daemon.json

참고: 이것은 예시일 뿐입니다. 필요한 경우 미러 URL 을 실제 URL 로 바꿔야 합니다.

일관된 배포를 위한 Docker Compose 사용

Docker Compose 는 환경 전반에 걸쳐 일관된 이미지 참조를 보장하는 데 도움이 됩니다. 간단한 docker-compose.yml 파일을 만들어 보겠습니다.

mkdir -p ~/project/compose-demo
cd ~/project/compose-demo

이제 docker-compose.yml 파일을 만듭니다.

cat > docker-compose.yml << 'EOF'
version: '3'
services:
  web:
    image: nginx:1.21.0
    ports:
      - "8080:80"
  redis:
    image: redis:6.2
EOF

먼저 시스템에 Docker Compose 가 설치되어 있는지 확인합니다.

docker compose version

Docker Compose 가 설치되어 있지 않으면 설치해야 할 수 있습니다. Ubuntu 에서는 다음을 사용하여 설치할 수 있습니다.

sudo apt-get update
sudo apt-get install -y docker-compose-plugin

이 파일을 사용하면 단일 명령으로 두 서비스를 시작할 수 있습니다.

docker compose up -d

컨테이너가 생성되는 것을 보여주는 출력이 표시됩니다.

Creating network "compose-demo_default" with the default driver
Creating compose-demo_web_1   ... done
Creating compose-demo_redis_1 ... done

서비스가 실행 중인지 확인합니다.

docker compose ps

"Up" 상태의 두 서비스를 볼 수 있습니다.

Docker 환경 정리

컨테이너를 중지하고 제거하여 환경을 정리해 보겠습니다.

docker compose down
cd ~/project

이것은 Docker Compose 로 생성한 컨테이너를 중지하고 제거합니다.

모범 사례 요약

항상 완전한 정규 이미지 이름을 사용하십시오.
비공개 이미지를 가져오기 전에 인증하십시오.
안전한 자격 증명 저장소를 설정하십시오.
일관된 배포를 위해 Docker Compose 를 사용하십시오.
Docker 구성을 정기적으로 감사하십시오.
불변 참조를 위해 이미지 다이제스트를 사용하십시오.
레지스트리 액세스를 위한 적절한 네트워크 구성을 구현하십시오.

이러한 모범 사례를 따르면 "pull access denied" 오류를 최소화하고 보다 안정적인 컨테이너화된 환경을 만들 수 있습니다.

요약

이 랩에서는 Docker 에서 "pull access denied" 오류를 이해하고, 문제 해결하고, 해결하는 방법을 배웠습니다. 이제 다음 사항에 대한 실질적인 경험을 갖게 되었습니다.

Docker 레지스트리 (registry) 및 이미지 풀링 (image pulling) 기본 사항 이해
"pull access denied" 오류의 일반적인 원인 식별
적절한 인증 및 문제 해결을 통한 액세스 문제 해결
로컬 테스트 레지스트리 설정을 포함한 개인 레지스트리 작업
향후 액세스 문제를 방지하기 위한 모범 사례 구현

이러한 기술은 Docker 환경에서 원활한 컨테이너 배포 및 관리에 필수적입니다. Docker 를 계속 사용하면서 적절한 액세스 관리가 컨테이너 작업의 기본 측면이며, 특히 개인 레지스트리가 있는 엔터프라이즈 환경에서 중요하다는 것을 알게 될 것입니다.

액세스 문제를 해결하기 위한 주요 단계를 기억하십시오.

이미지 이름 및 태그 확인
인증 요구 사항 확인
Docker 데몬 로그 검토
적절한 네트워크 연결 보장
자격 증명 관리에 대한 모범 사례 적용

이제 컨테이너화 워크플로우에서 Docker 이미지 액세스 문제를 자신 있게 처리할 수 있는 지식을 갖추게 되었습니다.