컨테이너 레지스트리의 작동 원리: 이미지 직접 Push/Pull하기

컨테이너 레지스트리는 겉보기엔 단순하지만, 잘못된 태그, 플랫폼 불일치, 레이어 누락, 실제 삭제 실패 같은 문제를 디버깅하려면 내부 동작 원리를 반드시 이해해야 함

• 레지스트리의 핵심은
  콘텐츠 주소 지정 방식(content-addressable) blob 저장소로, 모든 레이어·설정 파일·아티팩트는 digest를 주소로 삼아 저장됨
• 이미지 push는 blob 업로드 후
  manifest로 묶는 순서로 진행되고, pull은 manifest를 먼저 받아 blob을 순차적으로 내려받는 역순 구조임
  이미지 삭제는 단순 언태그만으로는 완전 제거가 되지 않으며, 다른 manifest에서 공유 중인 레이어를 먼저 확인한 뒤 blob까지 직접 삭제해야 함
  멀티 플랫폼 이미지는 기존 API 엔드포인트를 그대로 유지하면서 image index(manifest list)라는 추가 간접 계층 하나만 도입해 구현됨

Registry API 개요

• 현대 컨테이너 레지스트리 대부분은
  OCI Distribution Specification을 구현하며, 이 스펙은 콘텐츠 배포를 표준화하는 API 프로토콜을 정의함
• Registry API는 실제로 간결하고 이해하기 쉬우며,
  curl

만으로도 충분히 직접 조작 가능

Blob 업로드 및 다운로드

• 레지스트리는 본질적으로
  콘텐츠 주소 지정 blob 저장소로, 파일을 로컬에서 해싱한 뒤 digest를 주소로 사용해 업로드함
• 가장 단순한 업로드 방식은
  Monolithic PUT 방식으로, POST

로 세션을 초기화한 뒤 PUT

으로 blob을 전송하는 2단계 구조

• 대용량 파일에는
  POST + PATCH + PUT

청크 업로드 방식이 더 효율적이나, 소형 blob의 경우 Monolithic PUT으로 충분

• 업로드 성공 시
  HTTP/2 201 Created

응답과 함께 새 blob의 위치를 가리키는 Location

헤더가 반환됨

• 다운로드는 digest만 알면
  GET /v2/<repo>/blobs/<digest>

로 바로 수행 가능

이미지 Push

• 이미지 push 절차: (1) 각
  rootfs 레이어 blob 업로드 → (2) image configuration blob 업로드 → (3) 모든 digest를 하나의 JSON 문서로 묶는 manifest 파일 push
• manifest는
  PUT /v2/<repo>/manifests/<tag>

엔드포인트로 업로드하며, 이 시점에 태그가 생성됨

• 실제 클라이언트(예:
  docker push

)는 blob 업로드를 병렬로 수행하나, 원리 이해를 위해 순차 처리도 가능

• 이미지 디렉터리 구성 예시:
  config.json

, layer-1.tar.gz

, layer-2.tar.gz

, manifest.json

태그 목록 조회

GET /v2/<repo>/tags/list

엔드포인트로 특정 레포지터리의 모든 태그 목록 조회 가능

• 이 기능은
  docker

CLI에서는 노출되지 않으며, curl

또는 crane

, regctl

같은 도구로만 접근 가능
crane

, regctl

은 동일 엔드포인트를 ls

명령으로 래핑한 것

이미지 Pull

• pull 절차는 push의 역순: (1)
  GET /v2/<repo>/manifests/<tag>

로 manifest 조회 → (2) manifest에 명시된 digest로 모든 blob 다운로드

• 현대 manifest는 rootfs 레이어·이미지 설정 외에도
  Helm 차트, SBOM, 출처 증명(provenance attestation), LLM 가중치 등 임의 아티팩트를 blob으로 참조하는 범용 저장소로도 활용됨

이미지 삭제

• 이미지 삭제는 단순하지 않으며,
  태그 제거(언태그)만으로는 manifest 자체가 삭제되지 않음
• 완전 삭제 절차:
• (1)
  DELETE /v2/<repo>/manifests/<tag>

로 태그 제거

• (2) manifest를 digest로 조회해 참조 중인 모든 blob 확인
• (3)
  다른 manifest에서 공유 중이지 않은 blob만 선택적으로 삭제
• (4)
  DELETE /v2/<repo>/blobs/<manifest-digest>

로 manifest blob 삭제

• 레지스트리는 콘텐츠 주소 지정 저장소이므로, 동일한 rootfs 레이어를 여러 이미지가 공유할 수 있으며, 삭제 시 해당 레이어를 참조하는
  모든 이미지에 영향을 줌
• 대안으로 모든 태그를 제거한 뒤 레지스트리의
  가비지 컬렉션(garbage collection) 설정에 의존하는 방법도 있으나, 공용 레지스트리에서는 항상 활성화되어 있지 않음

멀티 플랫폼 이미지

• 멀티 플랫폼 이미지는
  레지스트리 API 구조 변경 없이 구현됨 — 엔드포인트 추가·수정 없이 기존 API를 그대로 활용
• 구성 방식:
• 각 단일 플랫폼 변형(amd64, arm64 등)을 개별 manifest와 함께
  digest 기반으로 먼저 push
• 이후
  image index(manifest list) 라 불리는 상위 manifest를 태그와 함께 push

GET /v2/<repo>/manifests/<tag>

호출 시 단일 플랫폼 manifest 또는 image index 중 하나가 반환되며, 호출자는 반환된 문서의 content type으로 구분해야 함

• 결과적으로 멀티 플랫폼 지원은 기존 구조에
  간접 계층 하나와 index 문서 업로드/다운로드 단계 하나만 추가한 것

레지스트리 API 보호

• OCI Distribution Spec은 인증 방식을 엄격히 정의하지 않으나, 대부분의 실제 레지스트리는
  HTTP Basic 인증을 사용
• 자격증명이 평문으로 전송되는 것을 막기 위해 반드시
  HTTPS 위에서 운영해야 함

댓글과 토론