1. Docker pull의 일반적인 동작

docker에서 기본적으로 아래와 같은 명령어를 실행해서 docker image를 가지고 온다

# docker pull ubuntu:22.04
# docker pull docker.io/ubuntu:22.04

그러나 내부 동작 방식을 확인해보면 아래와 같이 주소로 image 데이터를 가지고 온다

Sep  6 13:50:48 homemachine dockerd[104079]: time="2024-09-06T13:50:48.344713168+09:00" level=debug msg="Trying to pull registry-1.docker.io/library/ubuntu from https://registry-1.docker.io"
Sep  6 13:50:50 homemachine dockerd[104079]: time="2024-09-06T13:50:50.196001411+09:00" level=debug msg="Fetching manifest from remote" digest="sha256:adbb90115a21969d2fe6fa7f9af4253e16d45f8d4c1e930182610c4731962658" error="<nil>" remote="registry-1.docker.io/library/ubuntu:22.04"

위에 적혀 있는 remote 주소로 이미지를 요청하면 정상작으로 pull이 된다.

# docker pull registry-1.docker.io/library/ubuntu:22.04
22.04: Pulling from library/ubuntu
857cc8cb19c0: Pull complete
Digest: sha256:adbb90115a21969d2fe6fa7f9af4253e16d45f8d4c1e930182610c4731962658
Status: Downloaded newer image for registry-1.docker.io/library/ubuntu:22.04
registry-1.docker.io/library/ubuntu:22.04

그러나 docker pull ubuntu:22.04 명령어를 사용해서 다운받은 이미지와 다르게 인식한다.

1. registry-1.docker.io에서 이미지 다운로드

# docker pull registry-1.docker.io/library/ubuntu:22.04
22.04: Pulling from library/ubuntu
857cc8cb19c0: Pull complete
Digest: sha256:adbb90115a21969d2fe6fa7f9af4253e16d45f8d4c1e930182610c4731962658
Status: Downloaded newer image for registry-1.docker.io/library/ubuntu:22.04
registry-1.docker.io/library/ubuntu:22.04


2. docker.io에서 이미지 다운로드
# docker pull ubuntu:22.04
22.04: Pulling from library/ubuntu
Digest: sha256:adbb90115a21969d2fe6fa7f9af4253e16d45f8d4c1e930182610c4731962658
Status: Downloaded newer image for ubuntu:22.04
docker.io/library/ubuntu:22.04


3. 시스템에 docker images 저장 현황
# docker images -a
REPOSITORY                            TAG       IMAGE ID       CREATED       SIZE
ubuntu                                22.04     53a843653cbc   3 weeks ago   77.9MB
registry-1.docker.io/library/ubuntu   22.04     53a843653cbc   3 weeks ago   77.9MB

결과론적으로는 docker 이미지 저장소의 서비스 구조와 간편성으로 이유로 docker client에서 몇 가지 상황에 대해서는 docker 주소를 오버래핑하는 것으로 확인된다.

2. Docker pull 시 이미지 요청 주소 네이밍 규칙

위의 예제에서 docker의 이미지를 pull할 때 몇 가지 이미지 네이밍 변경 규칙 있는 것으로 확인되었다.

1. 도메인이 없는 경우
  ubuntu:22.04 -> registry-1.docker.io/library/ubuntu:22.04
2. docker.io 도메인이 있는 경우
  docker.io/ubuntu:22.04 -> registry-1.docker.io/library/ubuntu:22.04

위 요청 호출 주소를 기반으로 예상할 때, 도메인 + PATH + 이미지로 확인된다.

위와 같은 경우 주소를 변경하는 방안으로 2가지를 예측해볼 수 있다.

1번 케이스

도메인이 없는 경우 무조건 registry-1.docker.io/library/ 요청 주소 만들기
docker.io 도메인만 매칭되는 경우 무조건 registry-1.docker.io/library/ 요청 주소 만들기

2번 케이스

도메인이 없는 경우 library PATH를 붙이고 registry-1.docker.io 도메인을 붙여 요청 주소를 만들기
docker.io 도메인만 매칭되는 경우 library PATH를 붙이고 docker.io 도메인을 registry-1.docker.io 변경하여 요청 주소 만들기

테스트를 해보면 2번 케이스라고 확인이 가능하다.

http 접근 방향성, 프로그래밍 방안 등을 생각하면 2번 케이스가 유력하다.

이를 확인하기 위해서 docker client가 동작하는 시스템에 registry mirror(reg.encicle.com)를 등록해서 이미지를 요청해서 어떻게 동작하는지 확인하자

docker client 실행 화면 - registry mirrors로 등록 시켜 놓은 reg.encicle.com은 동작하지 않는다. 단지 디버깅을 위해서 설정함

# cat /etc/docker/daemon.json
{
  "registry-mirrors": ["https://reg.encicle.com"]
}

# docker pull ubuntu:22.04
22.04: Pulling from library/ubuntu
Digest: sha256:adbb90115a21969d2fe6fa7f9af4253e16d45f8d4c1e930182610c4731962658
Status: Image is up to date for ubuntu:22.04
docker.io/library/ubuntu:22.04

docker daemon의 로그

Sep  6 14:20:30 homemachine dockerd[104079]: time="2024-09-06T14:20:30.095844132+09:00" level=debug msg="Calling HEAD /_ping"
Sep  6 14:20:30 homemachine dockerd[104079]: time="2024-09-06T14:20:30.096191648+09:00" level=debug msg="Calling POST /v1.43/images/create?fromImage=ubuntu&tag=22.04"
Sep  6 14:20:30 homemachine dockerd[104079]: time="2024-09-06T14:20:30.108688053+09:00" level=debug msg="hostDir: /etc/docker/certs.d/reg.encicle.com"
Sep  6 14:20:30 homemachine dockerd[104079]: time="2024-09-06T14:20:30.108708163+09:00" level=debug msg="Trying to pull ubuntu from https://reg.encicle.com/"
Sep  6 14:20:30 homemachine dockerd[104079]: time="2024-09-06T14:20:30.141310274+09:00" level=info msg="Attempting next endpoint for pull after error: unknown: repository library/ubuntu not found"
Sep  6 14:20:30 homemachine dockerd[104079]: time="2024-09-06T14:20:30.141337380+09:00" level=debug msg="Trying to pull ubuntu from https://registry-1.docker.io"
Sep  6 14:20:32 homemachine dockerd[104079]: time="2024-09-06T14:20:32.001917839+09:00" level=debug msg="Pulling ref from V2 registry: ubuntu:22.04"
Sep  6 14:20:32 homemachine dockerd[104079]: time="2024-09-06T14:20:32.001944256+09:00" level=debug msg="docker.io/library/ubuntu:22.04 resolved to a manifestList object with 6 entries; looking for a unknown match"
Sep  6 14:20:32 homemachine dockerd[104079]: time="2024-09-06T14:20:32.001960916+09:00" level=debug msg="found match for linux/amd64/v3 with media type application/vnd.oci.image.manifest.v1+json, digest sha256:075680e983398fda61b1ac59ad733ad81d18df4bc46411666bb8a03fb9ea0195"
Sep  6 14:20:32 homemachine dockerd[104079]: time="2024-09-06T14:20:32.027444340+09:00" level=debug msg="Adding content digest to lease" digest="sha256:adbb90115a21969d2fe6fa7f9af4253e16d45f8d4c1e930182610c4731962658" lease="moby-image-sha256:53a843653cbcd9e10be207e951d907dc2481d9c222de57d24cfcac32e5165188" remote="docker.io/library/ubuntu:22.04"
Sep  6 14:20:32 homemachine dockerd[104079]: time="2024-09-06T14:20:32.033295991+09:00" level=debug msg="Adding content digest to lease" digest="sha256:075680e983398fda61b1ac59ad733ad81d18df4bc46411666bb8a03fb9ea0195" lease="moby-image-sha256:53a843653cbcd9e10be207e951d907dc2481d9c222de57d24cfcac32e5165188" remote="docker.io/library/ubuntu:22.04"

위 로그로 봤을 때, 2번 케이스로 동작하는 것을 확인할 수 있다.

3. Docker pull 시 registry-mirrors가 설정되어 있는 경우 이미지 요청 주소 네이밍 규칙

registry-mirror 설정

# cat /etc/docker/daemon.json
{
  "registry-mirrors": ["https://reg.encicle.com"]
}

1. 도메인이 없는 경우

# docker pull ubuntu:22.04
  -> /library/ubuntu:22.04 PATH 추가로 요청 PATH 생성
  -> 미러 도메인으로 연결 "https://reg.encicle.com"
  -> 연결 정상일 경우 "/library/ubuntu:22.04" 이미지 요청
  -> 이미지 저장
  -> 저장된 이미지 명을 docker.io/registry/ubuntu:22.04로 저장

2. docker.io 도메인으로 요청하는 경우

# docker pull docker.io/ubuntu:22.04
  -> /library/ubuntu:22.04 PATH 추가로 요청 PATH 생성
  -> 미러 도메인으로 연결 "https://reg.encicle.com"
  -> 연결 정상일 경우 "/library/ubuntu:22.04" 이미지 요청
  -> 저장된 이미지 명을 docker.io/registry/ubuntu:22.04로 저장

3. registry-mirrors 사이트가 장애이거나 이미지가 없는 경우

# docker pull ubuntu:22.04
or
# docker pull docker.io/ubuntu:22.04

 -> registy-mirror 장애 or not found image
 -> 이미지 요청 : https://registry-1.docker.io

위를 기반으로 한다면 ubuntu:22.04 / docker.io/ubuntu:22.04 요청에 대해서 registry-mirrors를 구성해서 Cache Proxy 시스템 구성도 가능하다.

docker pull 동작 방식 이해를 통한 registry-mirrors(harbor) 구성 - 01

ubuntu 22.04 - Harbor를 이용한 registry-mirrors 구성 - 02

Search

docker pull 동작 방식 이해를 통한 registry-mirrors(harbor) 구성 - 01

1. Docker pull의 일반적인 동작

2. Docker pull 시 이미지 요청 주소 네이밍 규칙

3. Docker pull 시 registry-mirrors가 설정되어 있는 경우 이미지 요청 주소 네이밍 규칙