Harbor 구성 요소와 용도

Harbor는 컨테이너 이미지와 OCI 아티팩트를 저장하는 Registry를 중심으로, 인증·권한 관리, 보안 스캔, 비동기 작업, 메타데이터 관리 기능을 결합한 플랫폼이다. 각 구성 요소는 독립적인 컨테이너 또는 Pod로 배포되며, Kubernetes 환경에서는 Helm Chart로 설치하는 방식이 일반적이다.

전체 구성도

Harbor는 이미지의 실제 바이너리 데이터와 관리 정보를 분리한다. 이미지 레이어, Manifest 같은 대용량 데이터는 Registry와 스토리지 백엔드가 담당하고, 사용자·프로젝트·권한·정책·태그 등의 메타데이터는 PostgreSQL에 보관한다.

핵심 구성 요소

구성 요소	주요 용도	운영 관점의 특징
Nginx	외부 요청을 수신하는 리버스 프록시	TLS 종료, 웹 UI·API·OCI Registry API 요청을 적절한 내부 서비스로 라우팅한다
Portal	Harbor 웹 콘솔 제공	프로젝트, Repository, 태그, 취약점, 사용자, 복제 정책 등을 브라우저에서 관리한다
Core	Harbor의 중앙 API 및 제어 서비스	인증·인가, Project/RBAC, Quota, Retention, Replication, Webhook, 정책 관리 등 핵심 비즈니스 로직을 담당한다
Registry	OCI 이미지와 아티팩트의 저장·전송	Docker Distribution 기반으로 `docker push`, `docker pull`, `helm push` 등 OCI Distribution API 요청을 처리한다
Registryctl	Registry 스토리지 제어	가비지 컬렉션(GC), 스토리지 상태 점검처럼 Registry에 직접 영향을 주는 관리 작업을 수행한다
Jobservice	비동기·장시간 작업 처리	이미지 복제, 취약점 스캔, 보존 정책 실행, 가비지 컬렉션 등의 작업을 백그라운드에서 실행한다
PostgreSQL	Harbor 메타데이터 영구 저장	사용자, 프로젝트, 권한, Repository, 태그, 정책, 복제 설정, 감사 정보 등을 저장한다
Redis	캐시와 작업 상태 관리	세션, 캐시, Jobservice의 작업 큐 및 실행 상태를 관리한다
Storage Backend	이미지 Blob과 Manifest 영구 저장	로컬 파일시스템, NFS, S3 호환 오브젝트 스토리지, MinIO, Ceph RGW, GCS 등을 사용할 수 있다
Trivy Adapter	컨테이너 이미지 취약점 스캔	이미지 패키지와 OS 취약점(CVE)을 분석하고 결과를 Harbor에 등록한다
Exporter	모니터링용 메트릭 노출	Prometheus가 수집할 수 있는 Harbor 상태·작업·스토리지 관련 메트릭을 제공한다
Log Collector	Harbor 서비스 로그 수집	컨테이너별 로그를 중앙 수집 대상으로 전달하거나 표준 출력 로그를 관리한다

Harbor의 Core는 API 게이트웨이이자 제어 평면 역할을 한다. 반면 Registry는 OCI Distribution API를 통해 이미지와 아티팩트를 실제로 저장하고 전달하는 데이터 평면이다. Jobservice는 이미지 복제, 스캔, 삭제 및 GC처럼 요청 처리 시간이 길어질 수 있는 작업을 비동기로 분리한다.

보안·인증 연동 요소

다음 항목은 Harbor 내부 서비스라기보다 Harbor가 연동하는 보안 및 ID 관리 구성 요소다.

연동 요소	용도	활용 예시
LDAP / Active Directory	조직 계정 인증 및 그룹 동기화	AD 그룹별로 `developer`, `maintainer`, `projectadmin` 권한을 자동 부여
OIDC Provider	SSO 인증	Keycloak, Okta, Azure AD, Dex와 연동하여 Harbor 로그인 통합
Robot Account	자동화 전용 계정	GitLab CI, Jenkins, Argo CD에 프로젝트별 최소 권한의 Pull/Push 토큰 발급
Trivy	취약점 분석	CI에서 Push된 이미지 자동 스캔 후 Critical 취약점 존재 여부 확인
Cosign / Notation	이미지 서명과 검증	CI가 이미지 빌드 후 서명하고, 운영 환경에서는 서명된 이미지만 배포
Webhook	이벤트 외부 전달	이미지 Push 완료, 취약점 스캔 완료 이벤트를 Jenkins·Slack·보안 시스템으로 전송

Harbor는 취약점 스캐너, OIDC 인증, 레지스트리 복제 어댑터 같은 외부 컴포넌트를 플러그인 방식으로 연동할 수 있다. 이미지 서명과 검증에는 Cosign 및 Notation 통합을 지원한다.

이미지 Push 처리 흐름

다음은 개발자가 CI/CD 파이프라인에서 Harbor로 이미지를 Push할 때의 일반적인 처리 흐름이다.

GitLab CI 또는 Jenkins가 이미지를 빌드한다.
파이프라인은 Robot Account 또는 사용자 계정으로 Harbor에 로그인한다.
클라이언트의 docker push harbor.example.com/platform/api:v1.0.0 요청이 Nginx에 도착한다.
Nginx는 인증 및 권한 확인이 필요한 요청을 Core로 전달한다.
Core는 PostgreSQL의 프로젝트 설정과 RBAC 정보를 확인한다.
Registry는 이미지 레이어와 Manifest를 Storage Backend에 저장한다.
Core는 Repository, Tag, Artifact 등의 메타데이터를 PostgreSQL에 기록한다.
필요하면 Jobservice가 Trivy 취약점 스캔 또는 다른 Harbor·ECR·Docker Hub 대상 복제 작업을 수행한다.
Portal 또는 API에서 Push 결과, 이미지 정보, 취약점 결과를 조회한다.

GitLab CI / Jenkins
        |
        | docker push
        v
      Nginx
        |
        +--> Core ---> PostgreSQL
        |
        +--> Registry ---> Object Storage / NFS / MinIO
                        |
                        +--> Jobservice ---> Trivy Scan / Replication
                                      |
                                      +--> Redis

운영 시 중요 포인트

PostgreSQL과 Registry Storage를 우선 보호한다.
Harbor 애플리케이션 Pod는 비교적 쉽게 재배포할 수 있지만, PostgreSQL 메타데이터와 이미지가 저장된 스토리지를 잃으면 Repository·태그·이미지 데이터를 복구하기 어렵다.

이미지 데이터와 메타데이터 백업을 함께 설계한다.
Storage Backend만 백업하면 Harbor DB의 프로젝트·권한·태그·정책 정보가 빠질 수 있다. 반대로 PostgreSQL만 백업하면 실제 이미지 Blob을 복구할 수 없다.

Redis는 영구 데이터 저장소가 아니다.
Redis는 캐시와 비동기 작업 상태에 사용되므로 HA 구성에서는 가용성을 고려해야 하지만, PostgreSQL과 이미지 스토리지보다 우선순위가 높지는 않다.

Jobservice의 처리량을 관찰한다.
대규모 이미지 복제, 일괄 스캔, 보존 정책, GC가 겹치면 작업 큐가 밀리고 Registry 부하가 커질 수 있다.

스토리지 선택이 성능과 가용성을 좌우한다.
단일 노드 파일시스템은 간단하지만 HA에 부적합하다. Kubernetes 기반 운영에서는 S3 호환 오브젝트 스토리지나 고가용성 공유 스토리지를 주로 검토한다.

취약점 스캔 결과만으로 배포 차단이 완성되지는 않는다.
CI 파이프라인, Argo CD 정책, Kyverno 또는 OPA Gatekeeper 같은 Kubernetes 정책 도구와 연계해 실제 운영 배포 단계에서 정책을 강제하는 구성이 필요하다.

작성일: 2026년 8월 11일 , 마지막 업데이트: 2026년 8월 11일