도커 이미지 다운로드 | 경로, 위치, 파일, 제한, 에러, policy, secret

이번 포스팅은 도커 이미지 다운로드 관련 자주 질문하는 6가지 핵심 내용을 정리합니다. 도커 이미지 로컬 다운로드 명령어부터 로컬 다운로드 경로 위치, 파일 다운로드 방법, 다운로드 제한, 에러 해결과 쿠버네티스 관련 내용도 조금 다루겠습니다.

1. 도커 이미지 로컬 다운로드 명령어

도커 이미지는 직접 빌드할 수도 있지만, 여러 곳의 도커 컨테이너 레지스트리에서 다운로드 받을 수도 있습니다. 가장 대표적인 레지스트리는 Docker Hub이며, 이외에도 Google의 GCR, Amazon의 ECR, MS의 ACR 등이 있습니다. 이들 레지스트리에서 도커 이미지를 로컬에 다운로드 받는 명령어는 다음과 같습니다.

$ docker image pull [OPTIONS] NAME[:TAG|@DIGEST]

여기서 NAME은 이미지 이름을 의미하며, TAG 혹은 DIGEST 는 같은 이름을 가진 여러 버전의 이미지 중 특정한 이미지를 선택하는 구분자 역할을 합니다. 만약 아무 태그나 다이제스트 값을 입력하지 않으면 :latest 태그에 해당하는 이미지를 다운로드합니다.

이미지에 부여한 태그는 시시때때로 수정할 수 있어서, 시간이 지나 같은 태그의 이미지를 다운받아도 동일하지 않은 이미지일 가능성이 있습니다. 이럴 때, 다이제스트 값을 사용하면, 정확하게 동일한 이미지를 다운로드할 수 있습니다. 아래처럼 이 값은 inspect 명령어 출력 결과 중 RepoDigests 항목에서 확인할 수 있습니다.

docker image inspect 명령어에 대한 더 자세한 내용은 이미지 확인 포스트를 참고하세요

$ docker image inspect --format '{ {.RepoDigests} }' nginx:latest
[nginx@sha256:af296b188c7b7df99ba960ca614439c99cb7cf252ed7bbc23e90cfda59092305]
Copy

태그, 다이제스트 둘 중 어떤 값을 사용해도 다음과 같이 같은 이미지를 다운로드합니다.

$ docker image pull nginx@sha256:af296b...092305
docker.io/library/nginx@sha256:af296b188c7b7df99ba960ca614439c99cb7cf252ed7bbc23e90cfda59092305: Pulling from library/nginx
Digest: sha256:af296b188c7b7df99ba960ca614439c99cb7cf252ed7bbc23e90cfda59092305
Status: Image is up to date for nginx@sha256:af296b188c7b7df99ba960ca614439c99cb7cf252ed7bbc23e90cfda59092305
docker.io/library/nginx@sha256:af296b188c7b7df99ba960ca614439c99cb7cf252ed7bbc23e90cfda59092305
 
$ docker image pull nginx:latest
latest: Pulling from library/nginx
Digest: sha256:af296b188c7b7df99ba960ca614439c99cb7cf252ed7bbc23e90cfda59092305
Status: Image is up to date for nginx:latest
docker.io/library/nginx:latest

2. 이미지 로컬 다운로드 경로 위치

섹션 1의 pull 명령어로 도커 이미지를 다운받으면, 해당 이미지 데이터는 도커가 알아서 관리하는 경로에 위치하게 됩니다.

일반적인 이미지 로컬 다운로드 경로 위치는 다음과 같습니다.

Linux: /var/lib/docker/
MacOS: ~/Library/Containers/com.docker.docker/Data/vms/0/
윈도우: C:\ProgramData\Docker\

하지만, 일반적으로 이 디력토리에 직접 접근하는 방법은 적절하지 않습니다. 도커는 별도의 데이터 구조와 알고리즘으로 이미지와 컨테이너를 관리하고 있기 때문입니다. 이미지를 파일로 저장하고 로드하길 원한다면 다음 섹션 3을 참고하세요.

3. 이미지 파일 다운로드 명령어

네트워크 이외의 방법으로 이미지를 전송, 배포하거나, 백업 및 복원 등을 위해 특정 이미지를 파일로 저장해야 할 경우도 있습니다. 로컬에 다운로드 받아 저장한 이미지를 파일로 저장하려면 다음 명령어 형식을 사용합니다.

docker image save -o IMAGE_NAME IMAGE

IMAGE_NAME 부분에 파일이 저장되길 원하는 경로와 파일 이름을 .tar 확장자를 붙여 입력해줍니다. 파일 이름만 지정하면 자동으로 현재 디렉토리에 해당 파일명으로 저장됩니다.

$ mkdir docker-images
 
$ docker image save -o  ~/docker-images/nginx-image nginx:latest
 
$ ls docker-images
nginx-image

이렇게 파일로 저장한 이미지는 load 명령어로 다시 불러올 수 있습니다. -i 옵션 뒤에 이미지 파일의 경로와 이름을 입력해주세요.

$ docker image load -i docker-images/nginx-image.tar
Loaded image: nginx:latest

4. Docker Hub 다운로드 제한

Docker Hub 는 보다 나은 서비스를 위해서, 사용자 플랜에 따라 하루 다운로드 횟수에 차등제한을 두고 있습니다. 하루 최대 다운로드 가능 횟수는 다음과 같습니다.

로그인하지 않은 사용자: 100회/6시간
무료 플랜 사용자: 200회/6시간
유료 플랜 사용자: 5000회/1일

만약 최대 가능 횟수를 초과하여 다운로드 요청을 한 경우, 다음과 같은 로그 메시지를 받습니다.

You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits

5. no basic auth credentials 에러 해결 방법

이 에러 메시지는 사용자의 Docker CLI가 Docker Hub를 비롯한 도커 레지스트리에 인증하는 데 필요한 자격 증명을 찾을 수 없을 때 발생합니다. 일반적으로는, 로그인이 필요한데 로그인 상태가 아니거나, 로그인 정보가 잘못되었을 경우 자주 발생할 수 있습니다.

이러한 경우에는 docker login 명령을 이용해 로그인 시도를 하거나, docker logout 명령어로 로그아웃한 이후, 다시 로그인을 시도해볼 수 있습니다. 정상적인 로그인에 성공하면 인증 정보는 ~/.docker/config.json 파일에 저장됩니다.

로그인 시도가 정상적이지 않으면 confing.json 파일을 다른 디렉토리로 백업한 후, 재시도하는 방법도 시도할 수 있습니다.

6. 쿠버네티스와 사용하는 도커: Image pull policy, Docker pull secret

쿠버네티스와 같은 컨테이너 오케스트레이션 도구는 docker pull policy 와 secret 을 설정합니다.

6.1. Image pull policy

Image pull policy란 쿠버네티스에서 도커 이미지를 사용해 컨테이너를 실행할 때, 언제 이미지를 다운로드할 지 설정해두는 규칙을 의미합니다. 쿠버네티스에는 다음의 3가지 정책이 있습니다.

Always: 이 정책은 쿠버네티스가 항상 이미지를 레지스트리에서 다운로드하도록 합니다. 이미 같은 태그의 이미지가 로컬에 있더라도 무시하고 레지스트리에서 새로운 이미지를 가져옵니다. 이는 이미지 태그가 :latest인 경우 기본 정책입니다.
IfNotPresent: 이 정책은 쿠버네티스가 이미지가 로컬에 없는 경우에만 레지스트리에서 이미지를 다운로드하도록 합니다. 이미 같은 태그의 이미지가 로컬에 있으면, 그 이미지를 사용합니다. 이는 이미지 태그가 :latest가 아닌 경우 기본 정책입니다.
Never: 이 정책은 쿠버네티스가 이미지를 레지스트리에서 다운로드하지 않도록 합니다. 쿠버네티스는 항상 로컬에 있는 이미지를 사용하려고 시도하며, 이미지가 없는 경우 에러를 반환합니다.

이러한 정책들은 쿠버네티스의 Pod 사양에서 설정할 수 있습니다.

6.2. Docker pull secret

Docker pull secret은 쿠버네티스와 같은 컨테이너 오케스트레이션 도구에서, 특정 도커 레지스트리에 대한 접근 권한 인증 정보를 저장하는 데 사용합니다. 이 시크릿을 사용해서 도커 이미지를 다운로드할 수 있습니다.

시크릿은 일반적으로 JSON 파일 형식이며, 쿠버네티스 CLI에서는 아래와 같은 시크릿 생성 명령어를 제공합니다.

$ kubectl create secret docker-registry my-secret --docker-server=DOCKER_REGISTRY_SERVER --docker-username=DOCKER_USER --docker-password=DOCKER_PASSWORD --docker-email=DOCKER_EMAIL

위 명령어는 my-secret 이라는 시크릿 파일을 생성하며, 쿠버네티스 Pod 사양에서 imagePullSecrets 항목으로 이 파일을 참조할 수 있습니다.

7. 마치며

지금까지 도커 이미지 다운로드 관련 자주 질문하는 6가지 핵심 내용을 정리해보았습니다. 도커 이미지 로컬 다운로드 명령어부터 로컬 다운로드 경로 위치, 파일 다운로드 방법, 다운로드 제한, 에러 해결과 쿠버네티스 관련 내용도 조금 다뤄보았습니다. 이미지를 다운로드하고 저장하는 과정에 도움이 되길 바랍니다.

삭제 확인