컨테이너 레지스트리를 API로 이해해야 하는 이유

컨테이너 레지스트리를 API로 이해해야 하는 이유

AI 뉴스 썸네일

컨테이너 레지스트리는 보통 `docker push`와 `docker pull` 뒤에 숨어 있어요. 그런데 태그가 엉뚱한 이미지를 가리키거나, arm64 서버에서 다른 플랫폼 이미지가 내려오거나, 삭제한 줄 알았던 레이어가 남아 있으면 이야기가 달라져요. iximiuz Labs의 새 튜토리얼은 레지스트리를 직접 API로 다루며 이런 문제를 어디서 봐야 하는지 보여줘요.

핵심 요약

구분	핵심	왜 볼 만한가요
레지스트리 구조	이미지는 digest 기반 blob과 manifest 조합으로 저장돼요	태그만 보면 놓치는 실제 저장 단위를 이해할 수 있어요
Push와 Pull	push는 blob을 올린 뒤 manifest로 묶고, pull은 manifest를 먼저 받아요	이미지 배포 실패를 어느 단계에서 확인할지 감이 잡혀요
삭제와 멀티 플랫폼	언태그, blob 삭제, image index가 서로 다른 층이에요	저장 공간 정리와 플랫폼 불일치 문제를 더 안전하게 다룰 수 있어요

1. 레지스트리는 태그 저장소가 아니라 digest 저장소예요

많은 개발자는 레지스트리를 “이미지 이름과 태그를 보관하는 곳” 정도로 생각해요. 실제로는 콘텐츠 주소 지정 방식의 blob 저장소에 가까워요. 레이어, 이미지 설정 파일, 기타 아티팩트가 로컬에서 계산한 digest를 주소로 삼아 저장돼요. 태그는 그 위에 붙는 사람이 읽기 쉬운 별칭에 가까워요. 그래서 같은 레이어를 여러 이미지가 공유할 수 있고, 태그를 바꿔도 실제 blob은 그대로 남을 수 있어요. iximiuz Labs 원문

이 관점은 디버깅할 때 바로 도움이 돼요. “latest를 pull했는데 왜 예전 이미지가 내려왔지?” 같은 문제는 태그 이름만 보면 답이 안 나와요. 어떤 manifest가 태그에 연결됐는지, 그 manifest가 어떤 config와 layer digest를 참조하는지 봐야 해요. GeekNews 요약도 이 글의 핵심을 digest 기반 blob 저장소와 manifest 구조로 잡고 있어요. GeekNews 글

2. Push는 blob을 올리고 manifest로 묶는 순서예요

이미지를 push할 때 클라이언트는 레이어 blob부터 올려요. 그다음 이미지 설정 파일을 올리고, 마지막에 이 모든 digest를 JSON 문서인 manifest로 묶어 특정 태그에 연결해요. 튜토리얼은 이 흐름을 Docker CLI 없이 `curl`로 직접 따라가요. 업로드 세션을 만들고, digest를 붙여 blob을 보내고, manifest를 `PUT /v2//manifests/`로 올리는 식이에요. iximiuz Labs 원문

pull은 반대 방향이에요. 먼저 태그로 manifest를 받고, 그 안에 적힌 digest를 따라 config와 layer blob을 내려받아요. 이 순서를 알면 장애 위치를 좁히기 쉬워져요. manifest는 있는데 특정 layer 다운로드가 실패하는지, 클라이언트가 잘못된 플랫폼 manifest를 고른 건지, 애초에 태그가 다른 manifest를 가리키는지 나눠 볼 수 있어요. 레지스트리 문제를 “Docker가 이상해요”로 뭉개지 않고 API 응답 단위로 볼 수 있게 돼요.

3. 삭제와 멀티 플랫폼은 한 단계 더 조심해야 해요

이미지 삭제는 태그 삭제와 같지 않아요. 태그를 지워도 manifest와 blob이 바로 사라지지 않을 수 있어요. 레이어는 여러 이미지가 공유할 수 있어서, 아무 blob이나 지우면 다른 이미지 pull까지 깨질 수 있어요. 튜토리얼은 manifest를 digest로 확인하고, 어떤 blob이 다른 manifest에서도 쓰이는지 따져 본 뒤 삭제해야 한다고 설명해요. 공용 레지스트리에서는 가비지 컬렉션 정책도 제각각이라 “삭제 버튼을 눌렀다”만으로 저장 공간이 정리됐다고 보기 어려워요. iximiuz Labs 원문

멀티 플랫폼 이미지도 비슷해요. amd64와 arm64 이미지를 각각 manifest로 올린 뒤, 그 위에 image index 또는 manifest list라는 상위 문서를 하나 더 올려요. 같은 태그로 요청해도 응답이 단일 manifest인지 image index인지 content type으로 구분해야 해요. Kubernetes 노드 아키텍처가 섞인 환경이나 Apple Silicon 개발 환경에서 “내 머신에서는 되는데 서버에서는 안 돼요”가 나오면 이 층을 의심해 볼 수 있어요.

왜 중요한가요

컨테이너 레지스트리는 배포 파이프라인의 통로처럼 보이지만, 실제로는 운영 문제의 원인이 자주 숨어 있는 곳이에요. CI에서 이미지를 성공적으로 push했는데 운영 클러스터가 다른 digest를 받거나, 취약점이 있는 이미지를 삭제했는데 저장소에 blob이 남아 있거나, 멀티 아키텍처 태그가 잘못 묶이면 배포 안정성이 바로 흔들려요. 이때 레지스트리 API와 manifest 구조를 알면 추측 대신 확인으로 접근할 수 있어요. iximiuz Labs 원문

AI 서비스와도 이어져요. 최근에는 컨테이너 이미지뿐 아니라 SBOM, provenance attestation, Helm 차트, 모델 가중치 같은 아티팩트도 OCI 레지스트리 형식으로 다루는 흐름이 커졌어요. 레지스트리를 단순 이미지 창고로만 보면 이런 확장을 이해하기 어려워요. 플랫폼 팀이나 백엔드 팀이라면 한 번쯤 직접 API를 호출해 보는 편이 좋아요. 나중에 배포가 꼬였을 때 어디부터 열어 볼지 훨씬 분명해져요. GeekNews 글

참고 자료

1. 컨테이너 레지스트리의 작동 원리: 이미지 직접 Push/Pull하기 — GeekNews
2. How Container Registries Work: Pushing and Pulling Images By Hand — iximiuz Labs