TL;DR — 반입한 이미지가 적재는 성공하는데 이름으로는 쓸 수 없었다. 아카이브에 기록되는 참조를 저장소명만으로 적었는데, 컨테이너 런타임은 조회할 때 레지스트리 호스트를 붙여 정규화한다. 기록된 이름과 조회하는 이름이 영영 어긋난다.

배경

• 프로젝트/기능: DeployHub — 컨테이너 이미지를 버전 단위로 모아 반입용 아카이브로 만들어 전달하는 백엔드
• 환경: Java 17, Spring Boot 3.5, skopeo, OCI 아카이브
• 왜 중요했나: 고객사는 폐쇄망이라 문제가 생겨도 원격으로 고칠 수 없다. 반입물은 한 번에 써야 한다

문제 (증상)

고객사 환경에 아카이브를 적재했는데:

• 적재 자체는 성공한다
• 그런데 이름으로 실행하면 외부 레지스트리에서 받으려 하며 실패한다(pull access denied)
• inspect·tag·rmi도 전부 No such image
• docker images에 같은 항목이 두 번 뜼는다(디스크 사용량은 1배)

원인 분석

• 아카이브의 index.json에 기록되는 org.opencontainers.image.ref.name을 저장소명만으로 적었다
• 컨테이너 런타임은 이미지를 조회할 때 레지스트리 호스트를 붙여 정규화한다
• 즉 저장 시점의 이름과 조회 시점의 이름이 달라진다. 적재는 이름과 무관하게 되므로 성공하고, 이름을 쓰는 모든 동작은 실패한다
• 목록에 두 번 뜼는 것도 같은 이유다 — 기록된 이름과 정규화된 이름이 각각 한 행씩 차지한다

해결

• 목적지 참조를 호스트까지 붙인 완전 수식 참조로 고정했다
• 네임스페이스가 없는 저장소는 정규형이 한 단계 더 들어간다는 것을 따로 처리했다
• 이 둘이 같은 증상을 내서 원인이 겹쳐 보였는데, 7MB 테스트 이미지로 변수를 하나씩만 바꿔가며 인덱스 여부가 아니라 네임스페이스 유무가 원인임을 분리해 확인했다