5. Docker Registry란? Docker Hub와 이미지 저장소 이해하기

 

📚 Docker & Kubernetes 시리즈

이전 글에서는 Spring Boot 소스를 수정한 뒤 변경 사항을 Docker Container에 반영하는 과정을 알아봤다.

소스가 변경되면 새로운 JAR 파일을 생성하고, 이를 기반으로 새로운 Docker Image를 만들어야 한다.

그렇다면 이렇게 생성한 Docker Image는 어디에 저장하고 관리할까?

개발자 개인의 PC에서는 로컬에 이미지를 저장할 수 있지만, 여러 개발자가 함께 사용하거나 개발·스테이지·운영 환경에 배포하려면 이미지를 공유할 수 있는 저장소가 필요하다.

이때 사용하는 것이 Docker Registry이다.

이번 글에서는 Docker Registry의 개념과 Docker Hub를 이용해 이미지를 저장하고 내려받는 방법을 알아보자.

 

 

---

Docker Image는 기본적으로 로컬에 저장된다

먼저 Docker Image를 생성해 보자.

docker build -t my-spring-app .

 

 

빌드가 완료된 후 다음 명령어를 실행하면 현재 로컬 환경에 저장된 이미지를 확인할 수 있다.

docker images

 

 

실행 결과는 다음과 비슷하다.

REPOSITORY      TAG       IMAGE ID       CREATED          SIZE
my-spring-app   latest    9f18c12ab123   10 seconds ago   280MB

 

 

이 상태에서 my-spring-app 이미지는 현재 Docker를 실행한 PC에만 존재한다.

다른 개발자의 PC나 운영 서버에서는 이 이미지를 바로 사용할 수 없다.

이미지를 다른 환경에서도 사용하려면 공용 또는 사설 이미지 저장소에 업로드해야 한다.

 

 

---

Docker Registry란?

Docker Registry는 Docker Image를 저장하고 배포하는 저장소이다.

소스 코드를 GitHub나 GitLab과 같은 Git 저장소에 저장하는 것처럼, Docker Image는 Docker Registry에 저장한다.

역할을 비교하면 다음과 같다.

Git Repository
→ 소스 코드 저장 및 공유

Docker Registry
→ Docker Image 저장 및 공유

 

 

Docker Registry를 사용하면 개발자가 만든 이미지를 서버나 다른 개발자가 내려받아 동일한 환경에서 실행할 수 있다.

전체 흐름은 다음과 같다.

Spring Boot 소스
        │
        ▼
Gradle Build
        │
        ▼
JAR 생성
        │
        ▼
Docker Build
        │
        ▼
Docker Image 생성
        │
        ▼
Docker Registry에 Push
        │
        ▼
배포 서버에서 Pull
        │
        ▼
Container 실행

 

 

---

Repository와 Registry의 차이

Docker를 처음 접하면 Registry와 Repository를 혼동하기 쉽다.

Registry는 여러 Docker Image를 저장하는 전체 서비스이고, Repository는 Registry 안에서 특정 애플리케이션의 이미지를 관리하는 공간이다.

 

예를 들어 다음과 같은 이미지 이름이 있다고 하자.

username/my-spring-app:1.0.0

 

 

각 부분의 의미는 다음과 같다.

username
→ Registry 내 사용자 또는 조직 이름

my-spring-app
→ Repository 이름

1.0.0
→ Image Tag

 

 

하나의 Repository에는 여러 버전의 이미지를 저장할 수 있다.

username/my-spring-app:1.0.0
username/my-spring-app:1.1.0
username/my-spring-app:latest

 

즉, 같은 애플리케이션이라도 Tag를 이용해 여러 버전의 이미지를 관리할 수 있다.

 

 

---

Image Tag란?

Docker Image의 Tag는 이미지의 버전을 구분하기 위해 사용한다.

이미지 이름 뒤에 :을 붙여 지정한다.

my-spring-app:1.0.0
my-spring-app:1.1.0
my-spring-app:dev
my-spring-app:stg
my-spring-app:latest

 

 

Tag를 생략하면 기본값으로 latest가 사용된다.

docker build -t my-spring-app .

 

위 명령어는 다음과 같은 의미이다.

my-spring-app:latest

 

 

하지만 운영 환경에서는 latest만 사용하는 것보다 배포 버전을 식별할 수 있는 Tag를 지정하는 것이 좋다.

예를 들어 다음과 같이 사용할 수 있다.

my-spring-app:1.0.0
my-spring-app:20260723
my-spring-app:build-152
my-spring-app:a1b2c3d

 

Git Commit Hash나 Jenkins Build Number를 Tag로 사용하면 어떤 소스를 기반으로 생성된 이미지인지 추적하기 쉽다.

 

 

---

Docker Hub란?

Docker Hub는 Docker에서 제공하는 대표적인 공개 Registry 서비스이다.

 

Docker Hub에는 직접 만든 이미지를 업로드할 수도 있고, 다른 사용자가 만든 이미지를 내려받아 사용할 수도 있다.

Dockerfile에서 자주 사용하는 다음 이미지도 Registry에서 내려받는 이미지이다.

FROM eclipse-temurin:21-jre

 

별도의 Registry 주소를 작성하지 않으면 Docker는 기본적으로 Docker Hub에서 이미지를 찾는다.

따라서 위 코드는 Docker Hub에 저장된 eclipse-temurin:21-jre 이미지를 기반 이미지로 사용한다는 의미이다.

 

 

---

Docker Hub에서 Image를 내려받는 방법

Docker Registry에서 이미지를 내려받을 때는 docker pull 명령어를 사용한다.

docker pull eclipse-temurin:21-jre

 

 

Spring Boot 애플리케이션 이미지를 내려받는다면 다음과 같이 작성할 수 있다.

docker pull username/my-spring-app:1.0.0

 

 

내려받은 이미지는 로컬에 저장된다.

docker images

 

 

이후 해당 이미지를 기반으로 Container를 실행할 수 있다.

docker run -d \
  --name my-spring-app \
  -p 8080:8080 \
  username/my-spring-app:1.0.0

 

 

---

Docker Hub에 Image를 업로드하는 방법

이번에는 직접 만든 Spring Boot 이미지를 Docker Hub에 업로드해 보자.

 

먼저 Docker Hub 계정으로 로그인한다.

docker login

 

 

로그인이 완료되면 로컬 이미지에 Docker Hub Repository 이름을 지정해야 한다.

현재 로컬 이미지가 다음과 같다고 가정해 보자.

my-spring-app:latest

 

 

Docker Hub에 업로드하려면 사용자 이름을 포함한 형태로 Tag를 다시 지정한다.

docker tag my-spring-app:latest username/my-spring-app:1.0.0

 

 

이 명령어는 기존 이미지 파일을 복사하는 것이 아니라 동일한 이미지에 새로운 이름과 Tag를 추가한다.

확인해 보면 동일한 Image ID를 가진 이미지가 표시된다.

docker images

REPOSITORY                     TAG       IMAGE ID
my-spring-app                  latest    9f18c12ab123
username/my-spring-app         1.0.0     9f18c12ab123

 

 

이제 docker push 명령어로 이미지를 업로드한다.

docker push username/my-spring-app:1.0.0

 

 

업로드가 완료되면 다른 PC나 서버에서도 해당 이미지를 내려받아 사용할 수 있다.

docker pull username/my-spring-app:1.0.0

 

 

---

Docker Push와 Pull

Docker Registry에서 자주 사용하는 명령은 push와 pull이다.

docker push
→ 로컬 Image를 Registry에 업로드

docker pull
→ Registry의 Image를 로컬로 다운로드

 

 

흐름으로 표현하면 다음과 같다.

개발자 PC
        │
        │ docker push
        ▼
Docker Registry
        │
        │ docker pull
        ▼
개발·스테이지·운영 서버

 

이를 통해 여러 환경에서 동일한 Docker Image를 사용할 수 있다.

 

 

---

Public Registry와 Private Registry

Docker Registry는 공개 범위에 따라 Public Registry와 Private Registry로 나눌 수 있다.

 

Public Registry

누구나 접근할 수 있는 공개 이미지 저장소이다.

대표적인 예로 Docker Hub의 Public Repository가 있다.

Java, Ubuntu, Nginx, MySQL 등 일반적으로 사용하는 공식 이미지를 공개 Registry에서 내려받아 사용할 수 있다.

docker pull nginx
docker pull mysql
docker pull eclipse-temurin:21-jre

 

Private Registry

인증된 사용자만 접근할 수 있는 사설 이미지 저장소이다.

기업의 애플리케이션에는 내부 소스와 설정 구조가 포함될 수 있으므로 일반적으로 Private Registry를 사용한다.

대표적인 Registry 서비스는 다음과 같다.

Docker Hub Private Repository
Harbor
AWS ECR
Google Artifact Registry
Azure Container Registry
GitLab Container Registry

 

회사 내부에서 Harbor를 구축해 사용하거나 클라우드 환경에서 AWS ECR과 같은 관리형 Registry를 사용할 수 있다.

 

 

---

Harbor란?

Harbor는 오픈소스 기반의 Private Container Registry이다.

기업 내부에서 Docker Image를 저장하고 관리할 때 자주 사용된다.

단순히 이미지를 저장하는 것뿐만 아니라 다음과 같은 기능을 제공한다.

사용자 및 프로젝트 권한 관리
Private Repository 관리
Image 취약점 검사
Image 복제
접근 이력 관리
Image 보존 정책 관리

 

Docker Hub가 외부에서 제공되는 Registry 서비스라면, Harbor는 회사 내부 환경에 직접 구축해 사용할 수 있는 Registry라고 이해할 수 있다.

 

 

---

AWS ECR이란?

AWS ECR은 Amazon Web Services에서 제공하는 Container Registry이다.

ECR은 Elastic Container Registry의 약자이다.

AWS 환경에서 애플리케이션을 운영한다면 Docker Image를 ECR에 저장하고, Amazon EKS나 ECS에서 이미지를 내려받아 실행할 수 있다.

 

전체 흐름은 다음과 같다.

Jenkins
        │
        ▼
Docker Image Build
        │
        ▼
AWS ECR Push
        │
        ▼
Amazon EKS 또는 ECS
        │
        ▼
Container 실행

 

직접 Registry 서버를 설치하고 관리하지 않아도 된다는 장점이 있다.

 

 

---

실무에서는 어떻게 사용할까?

실무에서는 개발자가 직접 이미지를 빌드하고 Registry에 업로드하는 과정을 CI 도구가 자동으로 처리하는 경우가 많다.

예를 들어 Jenkins를 사용하는 환경에서는 다음과 같은 흐름으로 동작할 수 있다.

개발자가 Git Push
        │
        ▼
Jenkins Pipeline 실행
        │
        ▼
Gradle Build
        │
        ▼
JAR 생성
        │
        ▼
Docker Image Build
        │
        ▼
Image Tag 지정
        │
        ▼
Private Registry에 Push

 

 

Jenkins는 빌드 번호나 Git Commit Hash를 이용해 이미지 Tag를 생성할 수 있다.

my-spring-app:build-152
my-spring-app:a1b2c3d

 

 

Registry에 이미지가 업로드되면 Kubernetes가 해당 이미지를 내려받아 새로운 Pod를 실행한다.

Private Registry
        │
        │ Image Pull
        ▼
Kubernetes
        │
        ▼
새로운 Pod 생성
        │
        ▼
Health Check
        │
        ▼
정상 Pod를 서비스에 연결

 

Argo CD를 사용하는 환경에서는 Kubernetes 배포 설정이 저장된 Git Repository의 변경 사항을 기준으로 배포 상태를 동기화할 수 있다.

예를 들어 배포 설정의 Image Tag가 다음과 같이 변경될 수 있다.

containers:
  - name: my-spring-app
    image: registry.example.com/my-spring-app:build-152

 

Argo CD가 해당 변경 사항을 Kubernetes에 반영하면 Kubernetes는 Registry에서 이미지를 내려받아 새로운 Pod를 생성한다.

새로운 Pod의 Health Check가 정상적으로 완료되면 트래픽이 새 Pod로 연결되고, 기존 Pod는 순차적으로 종료된다.

 

 

---

Registry가 필요한 이유

Docker Registry를 사용하는 이유는 단순히 이미지를 보관하기 위해서만은 아니다.

 

동일한 실행 환경 유지

개발, 스테이지, 운영 환경이 동일한 이미지를 사용하므로 환경 차이로 인한 문제를 줄일 수 있다.

개발 환경
→ my-spring-app:1.0.0

스테이지 환경
→ my-spring-app:1.0.0

운영 환경
→ my-spring-app:1.0.0

 

환경마다 애플리케이션을 다시 빌드하는 것이 아니라, 한 번 생성한 이미지를 각 환경에서 동일하게 사용한다.

 

버전 관리

Tag를 이용해 애플리케이션 버전을 관리할 수 있다.

my-spring-app:1.0.0
my-spring-app:1.1.0
my-spring-app:1.2.0

 

배포 이력 추적

어떤 이미지가 언제 배포되었는지 확인할 수 있다.

Git Commit Hash나 Jenkins Build Number를 Tag에 포함하면 소스 코드와 Docker Image를 연결해 추적하기 쉬워진다.

 

이전 버전으로 복구

신규 버전에 문제가 발생하면 기존 이미지로 다시 배포할 수 있다.

현재 배포 버전
→ my-spring-app:1.2.0

문제 발생 후 이전 버전으로 복구
→ my-spring-app:1.1.0

 

다만 실제 운영 환경의 복구 가능 여부는 애플리케이션뿐만 아니라 데이터베이스 변경 사항과 외부 시스템 호환성도 함께 고려해야 한다.

 

 

---

latest Tag 사용 시 주의할 점

latest는 가장 최신 이미지를 자동으로 의미하는 특별한 버전 관리 기능이 아니다.

Tag를 생략했을 때 사용되는 기본 이름에 가깝다.

 

docker build -t my-spring-app .

 

위 명령어는 다음과 동일하다.

docker build -t my-spring-app:latest .

 

latest Tag에 새로운 이미지를 계속 덮어쓰면 현재 배포된 이미지가 어떤 소스를 기반으로 만들어졌는지 파악하기 어려울 수 있다.

또한 같은 Tag를 사용하더라도 실행 환경에 이전 이미지가 남아 있으면 예상한 이미지와 다른 버전이 사용되는 문제가 발생할 수 있다.

 

따라서 실무에서는 고유한 Tag를 사용하는 것이 좋다.

my-spring-app:1.0.0
my-spring-app:build-152
my-spring-app:20260723-1530
my-spring-app:a1b2c3d

 

운영 배포에서는 변경되지 않는 고유 Tag를 사용하고, 필요한 경우 별도로 latest, dev, stg와 같은 별칭 Tag를 함께 관리할 수 있다.

 

---

자주 사용하는 Docker Registry 명령어

Docker Hub 로그인

docker login

 

Image에 새로운 Tag 지정

docker tag my-spring-app:latest username/my-spring-app:1.0.0

 

Registry에 Image 업로드

docker push username/my-spring-app:1.0.0

 

Registry에서 Image 다운로드

docker pull username/my-spring-app:1.0.0

 

로컬 Image 확인

docker images

 

로컬 Image 삭제

docker rmi username/my-spring-app:1.0.0

 

 

---

전체 흐름 정리

Spring Boot 애플리케이션이 Docker Registry를 거쳐 배포되는 전체 흐름은 다음과 같다.

Spring Boot 소스 수정
        │
        ▼
Gradle Build
        │
        ▼
JAR 생성
        │
        ▼
Docker Image Build
        │
        ▼
Image Tag 지정
        │
        ▼
Docker Registry에 Push
        │
        ▼
배포 환경에서 Image Pull
        │
        ▼
새로운 Container 또는 Pod 실행
        │
        ▼
Health Check
        │
        ▼
서비스 반영

 

Docker Registry는 개발자가 만든 Docker Image를 저장하고, 여러 실행 환경에 동일한 이미지를 전달하는 역할을 한다.

 

 

---

정리

Docker Image는 이미지를 생성한 로컬 환경에만 저장된다.

다른 개발자나 서버에서 동일한 이미지를 사용하려면 Docker Registry에 이미지를 업로드해야 한다.

 

Docker Registry와 관련된 핵심 개념은 다음과 같다.

Registry
→ Docker Image를 저장하고 배포하는 전체 서비스

Repository
→ 특정 애플리케이션의 이미지를 관리하는 공간

Tag
→ Image의 버전 또는 빌드를 구분하는 값

Push
→ 로컬 Image를 Registry에 업로드

Pull
→ Registry의 Image를 로컬로 다운로드

 

Docker Hub는 대표적인 Public Registry이며, 기업 환경에서는 Harbor, AWS ECR, GitLab Container Registry 등의 Private Registry를 사용할 수 있다.

실무에서는 Jenkins가 Docker Image를 빌드해 Registry에 업로드하고, Kubernetes가 해당 이미지를 내려받아 새로운 Pod를 실행하는 방식으로 배포가 이루어진다.

결국 Docker Registry는 Docker Image를 개발 환경에서 스테이지와 운영 환경까지 전달하는 중간 저장소라고 할 수 있다.

 

 

---

다음 글

지금까지 Docker Image를 생성하고 Registry에 저장하는 과정을 알아봤다.

그렇다면 개발자가 소스를 Git에 Push한 이후, 애플리케이션 빌드와 Docker Image 업로드는 누가 수행할까?

 

“Jenkins와 Argo CD는 각각 어떤 역할을 할까?”

 

 

다음 글에서는 Jenkins와 Argo CD로 이해하는 CI/CD를 주제로, 소스 코드가 Docker Image로 만들어지고 Kubernetes에 배포되는 전체 흐름을 알아보겠다.