Harbor란?

Open Source Software

Harbor란?

Somaz 2024. 10. 8. 20:06

728x90

Overview

Harbor는 컨테이너 이미지의 보안, 관리, 배포를 강화하는 오픈소스 OCI(OCI-Compliance) 레지스트리 솔루션이다. 기본 Docker Registry의 기능을 확장하여, 대규모 Kubernetes 기반의 멀티 테넌트 환경에서도 안정적인 이미지 관리가 가능하다.

Harbor는 RBAC(역할 기반 접근 제어), 취약점 스캐닝(Trivy, Clair), 이미지 복제, Helm 차트 저장소, 정책 기반 이미지 보존, 감사 로그(Auditing), SSO 인증(OIDC, LDAP), Prometheus Exporter를 통한 모니터링 등 다양한 기능을 기본으로 제공한다.

또한, Nginx 기반의 API Gateway, PostgreSQL 데이터베이스, Redis 캐시, Job Service, Exporter, Portal UI 등 다양한 컴포넌트로 구성되어 있어, 설치 전 이해해야 할 아키텍처 구성도 명확하다.

이번 문서에서는 Harbor의 개념부터 아키텍처, Helm 기반 설치 방법, 실무 설정 팁, Docker Hub나 ECR과의 비교, 그리고 설치 후 체크리스트까지 실무 중심의 Harbor 활용법을 정리하였다.

Harbor는 단순한 이미지 저장소를 넘어, 보안과 운영의 안정성을 동시에 고려하는 조직에게 꼭 필요한 솔루션이다.

출처 : https://vra4u.com/2023/01/11/harbor-quick-tip-leverage-oci-registry-with-helm/

2024.05.28 - [IaC/CI CD Tool] - 6. Gitlab CI Build(with GCP Artifact Registry, Harbor)

2024.08.20 - [Open Source Software] - Habor Robot Account(하버 로봇 계정)란?

2025.02.19 - [Open Source Software] - Harbor SSO 구성 가이드(OIDC : Azrue AD, Gitlab)

Harbor란?

Harbor는 컨테이너 이미지를 관리, 보호, 배포하는 데 도움이 되는 오픈 소스 컨테이너 이미지 레지스트리이다. 보안, ID 관리, 취약성 검색, 콘텐츠 서명 및 역할 기반 액세스 제어(RBAC)와 같은 고급 기능을 추가하여 기본 Docker 레지스트리의 기능을 확장한다. Harbor는 컨테이너 이미지의 보안과 관리가 중요한 대규모 멀티 테넌트 Kubernetes 환경에 특히 유용하다.

Harbor 주요특징

Role-Based Access Control (RBAC): 사용자 역할을 기반으로 프로젝트 및 이미지에 대한 액세스를 세밀하게 제어할 수 있다.
Vulnerability Scanning(취약성 검색): 통합 Clair 또는 Trivy 취약성 스캐너를 사용하여 컨테이너 이미지에서 취약성을 검색할 수 있다.
Replication(복제): 여러 Harbor 인스턴스 간의 이미지 복제를 지원한다.
Retention Policies(보존 정책): 오래되었거나 사용되지 않는 컨테이너 이미지를 자동으로 정리하는 규칙을 정의할 수 있다.
Auditing(감사): 규정 준수 및 보안 목적으로 사용자와 관리자가 수행한 작업을 추적한다.
Multi-Tenancy(다중 테넌트): 사용자는 다양한 액세스 수준과 정책을 사용하여 격리된 프로젝트를 만들 수 있다.
Support for Multiple Authentication Methods(다중 인증 방법 지원): LDAP, OAuth 및 내부 데이터베이스 인증 방법이 지원한다.

Harbor 구성요소

Core: 다른 구성 요소와 상호 작용하는 기본 API 서비스이다. 사용자 관리, 프로젝트 관리, 이미지 태그 지정, 저장소 구성과 같은 기능에 대한 액세스를 제공한다.
Database (Harbor DB): Harbor는 PostgreSQL 데이터베이스를 사용하여 사용자, 프로젝트, 로그 및 복제 규칙에 대한 모든 메타데이터를 저장한다.
Registry: 컨테이너 이미지 레지스트리는 Docker 이미지를 저장한다. Harbor는 Docker의 기본 레지스트리(Distribution)와 통합되어 컨테이너 이미지를 저장하고 관리한다.
Job Service: Harbor에는 취약점 검색, 이미지 복제, 가비지 수집과 같은 비동기 작업 실행을 담당하는 작업 서비스가 있다.
Clair/Trivy (Vulnerability Scanning): Harbor는 Clair 또는 Trivy와 통합되어 컨테이너 이미지에 대한 취약성 검색을 제공한다. 이미지가 푸시되면 스캐너는 이를 분석하고 모든 취약점을 보고한다.
- Trivy: Harbor와 잘 통합되어 컨테이너 이미지에 대한 실시간 보안 검사를 제공하는 인기 있는 취약성 스캐너이다. (default)
- Clair: 컨테이너 이미지의 취약점을 탐지하는 또 다른 보안 도구입니다. 이미지의 레이어 분석을 수행한다.
Notary: DCT(Docker Content Trust)를 사용하여 컨테이너 이미지에 서명하는 서비스이다. 이미지의 신뢰성과 무결성을 확인하여 신뢰할 수 있는 이미지만 배포되도록 보장한다. (Deprecated)
- 처음에는 효과적이었지만 Notary에는 다중 아키텍처 이미지 서명에 대한 지원 부족, 확장성 문제 등 몇 가지 제한 사항이 있다.
ChartMuseum: ChartMuseum은 Kubernetes용 패키지 관리자인 Helm 차트의 저장소이다. Harbor는 이를 Kubernetes 애플리케이션을 정의, 설치 및 업그레이드하는 데 사용되는 Helm 차트를 호스팅하기 위한 선택적 구성 요소로 통합한다.
Portal: 사용자가 Harbor의 프로젝트, 사용자, 이미지 및 구성을 관리할 수 있는 웹 기반 그래픽 사용자 인터페이스(GUI)이다. 포털은 관리자와 개발자에게 컨테이너 레지스트리 및 프로젝트를 관리하기 위한 친숙한 인터페이스를 제공한다.
Log Collector: 로그 수집기는 모든 Harbor 구성 요소에서 로그를 수집하여 중앙 집중식 모니터링 또는 문제 해결을 위해 제공한다.
API Gateway (Nginx): Harbor는 Nginx를 역방향 프록시로 사용하여 API 요청을 적절한 서비스로 라우팅하고 보안을 처리하며 다양한 구성 요소 간의 트래픽 균형을 유지한다. Nginx는 보안 통신을 보장하고 핵심 서비스, 레지스트리, 작업 서비스 등과 같은 다양한 구성 요소에 대한 게이트웨이 역할을 한다.
Replication Service: Harbor는 서로 다른 Harbor 인스턴스 또는 다른 컨테이너 레지스트리 간의 이미지 복제를 지원한다. 이는 사용자가 여러 위치에 걸쳐 이미지를 복제해야 하거나 고가용성을 위해 필요한 시나리오에서 유용하다.
Harbor Admin Server: 관리 서버 구성 요소를 사용하면 관리자는 Harbor의 시스템 설정을 구성하고 사용자, 프로젝트 및 로그를 관리할 수 있다. Harbor 인스턴스의 상태를 모니터링하고 관리하는 데 중요하다.
Redis: Harbor는 Redis를 메모리 내 키-값 저장소로 사용한다. 주로 작업 처리, 세션 관리 및 복제와 같은 Harbor 작업 속도를 높이기 위한 캐싱 목적으로 사용된다.
Exporter: 주로 이미지 수, 사용자, 프로젝트, 저장소 등과 같은 Harbor의 다양한 구성 요소에서 측정항목을 수집하는 데 사용된다.

Docker Content Trust(DCT)는 Harbour 버전 2.0 이상에서 더 이상 사용되지 않는다. Harbor 프로젝트는 Notary 및 Docker Content Trust에 의존하는 대신 Cosign 및 OCI 이미지 서명 사양이라는 더욱 안전한 새 프레임워크로 전환했다.

Harbor 설치

Helm을 사용해서 Harbor 설치를 진행해본다. 2024.10.08 기준 최신버전으로 설치하였다.

# git clone
git clone https://github.com/goharbor/harbor-helm

# helm repo 등록
helm repo add harbor https://helm.goharbor.io

# 경로 이동 및 values 파일 복사
cd harbor-helm/
mkdir values
cp values.yaml values/somaz.yaml

# helm 의존성 설치
helm dependency update .

`values/somaz.yaml`

expose:
  type: ingress
  tls:
    enabled: true
    # The source of the tls certificate. Set as "auto", "secret"
    # or "none" and fill the information in the corresponding section
    certSource: none
  ingress:
    hosts:
      core: harbor.somaz.link
    controller: default
    className: "nginx"
    annotations:
      ingress.kubernetes.io/ssl-redirect: "true"
      ingress.kubernetes.io/proxy-body-size: "0"
      nginx.ingress.kubernetes.io/ssl-redirect: "true"
      nginx.ingress.kubernetes.io/proxy-body-size: "0"
      nginx.ingress.kubernetes.io/client-body-buffer-size: "512M" # 클라이언트로부터 받는 요청 본문(body)의 버퍼 크기를 조정한다. 이 크기가 설정된 값보다 큰 요청 본문이 들어오면 Nginx는 임시 파일을 사용하여 요청을 처리
  clusterIP:
    # The name of ClusterIP service
    name: harbor
    ports:
      # The service port Harbor listens on when serving HTTP
      httpPort: 80
      # The service port Harbor listens on when serving HTTPS
      httpsPort: 443

externalURL: https://harbor.somaz.link

persistence:
  enabled: true
  resourcePolicy: "keep"
  persistentVolumeClaim:
    registry:
      storageClass: "default"
      accessMode: ReadWriteOnce
      size: 5Gi
    jobservice:
      jobLog:
        storageClass: "default"
        accessMode: ReadWriteOnce
        size: 1Gi
    database:
      storageClass: "default"
      accessMode: ReadWriteOnce
      size: 1Gi
    redis:
      storageClass: "default"
      accessMode: ReadWriteOnce
      size: 1Gi
    trivy:
      storageClass: "default"
      accessMode: ReadWriteOnce
      size: 5Gi
  imageChartStorage:
    disableredirect: false
    type: filesystem
    filesystem:
      rootdirectory: /storage
      #maxthreads: 100

existingSecretAdminPasswordKey: HARBOR_ADMIN_PASSWORD
harborAdminPassword: "somaz@1234"

# debug, info, warning, error or fatal
logLevel: info

# Run the migration job via helm hook
enableMigrateHelmHook: false

metrics:
  enabled: true
  serviceMonitor:
    enabled: ture

trace:
  enabled: false

cache:
  # default is not enabled.
  enabled: true
  # default keep cache for one day.
  expireHours: 24


# If service exposed via "ingress", the Nginx will not be used
nginx:
  image:
    repository: goharbor/nginx-photon
    tag: v2.11.0
  automountServiceAccountToken: false
  replicas: 1
  revisionHistoryLimit: 10
  resources:
    requests:
      memory: 256Mi
      cpu: 100m
    limits:
      memory: 1Gi
      cpu: 1

portal:
  image:
    repository: goharbor/harbor-portal
    tag: v2.11.0
  replicas: 1
  revisionHistoryLimit: 10
  resources:
    requests:
      memory: 256Mi
      cpu: 100m
    limits:
      memory: 1Gi
      cpu: 1

core:
  image:
    repository: goharbor/harbor-core
    tag: v2.11.0
  replicas: 1
  resources:
    requests:
      memory: 256Mi
      cpu: 100m
    limits:
      memory: 1Gi
      cpu: 1

jobservice:
  image:
    repository: goharbor/harbor-jobservice
    tag: v2.11.0
  replicas: 1
  revisionHistoryLimit: 10
  resources:
    requests:
      memory: 256Mi
      cpu: 100m
    limits:
      memory: 1Gi
      cpu: 1

registry:
  registry:
    image:
      repository: goharbor/registry-photon
      tag: v2.11.0
    resources:
      requests:
        memory: 256Mi
        cpu: 100m
      limits:
        memory: 1Gi
        cpu: 1
  controller:
    image:
      repository: goharbor/harbor-registryctl
      tag: v2.11.0
    resources:
      requests:
        memory: 256Mi
        cpu: 100m
      limits:
        memory: 1Gi
        cpu: 1
  replicas: 1
  revisionHistoryLimit: 10
  upload_purging:
    enabled: true
    age: 168h
    interval: 24h
    dryrun: false

trivy:
  enabled: true
  image:
    # repository the repository for Trivy adapter image
    repository: goharbor/trivy-adapter-photon
    # tag the tag for Trivy adapter image
    tag: v2.11.0
  replicas: 1
  resources:
    requests:
      memory: 256Mi
      cpu: 100m
    limits:
      memory: 1Gi
      cpu: 1

database:
  type: internal
  internal:
    image:
      repository: goharbor/harbor-db
      tag: v2.11.0
    password: "somaz@1234"
    # shmSizeLimit: 512Mi
    shmSizeLimit: 2048Mi

redis:
  type: internal
  internal:
    image:
      repository: goharbor/redis-photon
      tag: v2.11.0

exporter:
  image:
    repository: goharbor/harbor-exporter
    tag: v2.11.0
  replicas: 1
  revisionHistoryLimit: 10
  resources:
    requests:
      memory: 256Mi
      cpu: 100m
    limits:
      memory: 1Gi
      cpu: 1

metrics:
  enabled: true
  serviceMonitor:
    enabled: true

설치방법은 아래와 같다.

# lint 확인
helm lint --values ./values/somaz.yaml  

# 설치전 확인
helm install harbor . -n harbor -f ./values/somaz.yaml --create-namespace --dry-run >> output.yaml

# 설치
helm install harbor . -n harbor -f ./values/somaz.yaml --create-namespace

# 업그레이드 방법
helm upgrade harbor . -n harbor -f ./values/somaz.yaml

삭제방법은 아래와같다.

# harbor 삭제
helm delete -n harbor harbor

# pvc 전부 삭제
kubectl delete pvc --all -n harbor

# pv 삭제
kubectl get pv | grep Released
kubectl delete pv $(kubectl get pv | grep Released | awk '{print $1}')

Harbor 아키텍처 다이어그램

+-------------------+
|   API Gateway     |  (Nginx) 요청 라우팅
+-------------------+
           |
+-------------------+
|       Core        |  (Harbor 핵심 API 서비스)
+-------------------+
|                   |
| DB(PostgreSQL)    |  (유저, 프로젝트 메타데이터 저장)
+-------------------+
|                   |
| Registry          |  (이미지 저장소)
+-------------------+
|                   |
| Job Service       |  (비동기 작업 처리 - 복제, 취약점 스캔 등)
+-------------------+
|                   |
| Trivy             |  (취약점 스캐너)
+-------------------+
|                   |
| Portal            |  (웹 UI)
+-------------------+
|                   |
| Log Collector     |  (로그 수집)
+-------------------+
|                   |
| Redis             |  (캐시, 큐 관리)
+-------------------+

실무 팁 - 설치 시 주의사항

1. 스토리지 용량 충분히 확보

특히 `persistence.imageChartStorage` 는 실제 이미지 저장소이므로 충분한 용량을 설정해야 함
Trivy 취약점 데이터베이스도 초기 다운로드 시 수백 MB 수준이므로 주의

2. 인증서 설정

`expose.tls.certSource` 를 auto로 하면 cert-manager와 연동 가능
내부 환경에서는 secret 방식으로 사전 발급한 인증서 활용 권장

3. 취약점 스캔 주기 설정

기본적으로 이미지 푸시 시 자동 스캔되지만, 주기적 전체 재스캔 설정 필요 (보안 강화)

Harbor와 Docker Hub, ECR, Nexus 비교

항목	Harbor	Docker Hub	AWS ECR	Nexus
오픈소스 여부	✅	❌	❌	✅
비용	무료	용량 제한 이후 유료	유료	무료(기본기능)
RBAC 지원	✅	일부	✅	✅
취약점 스캔	✅	일부(유료)	✅	플러그인 필요
OCI 호환성	✅	✅	✅	✅
Helm Chart 저장	✅	❌	❌	플러그인 필요
복제 기능	✅	❌	✅	일부 지원

설치 후 주요 점검 포인트

체크리스트	설명
인증서 정상적용 여부	웹 UI 접속 시 HTTPS 적용 확인
프로젝트 권한 설정	RBAC 테스트 (읽기/쓰기/관리 권한 나눔)
취약점 스캔 자동화	이미지 푸시 후 자동 스캔되는지 확인
외부 연동 테스트	ArgoCD, Jenkins 등과 이미지 pull 정상작동 확인
모니터링 연결	Prometheus & Grafana 연결 및 메트릭 수집 확인

실무에서 자주 묻는 질문(FAQ)

Q1. Harbor 설치 위치는 어디가 적당한가요?

클러스터 내부에 설치하는 것이 일반적이지만, 외부에서 접근해야 한다면 DMZ 구간에 설치하는 것도 가능
외부 Registry로 설정 시, 보안 강화 필요

Q2. Harbor 성능 튜닝 포인트는?

영역	방법
Storage	SSD 기반 스토리지 권장
Concurrency	JobService 동시작업 수 조절 (concurrency)
Cache	Redis 캐시 사이즈 충분히 확보
Ingress	Nginx 프록시 버퍼사이즈 조정 (대용량 이미지 대응)

Q3. 이미지 삭제 시 주의사항은?

Retention Policy를 설정해 자동 정리 권장
삭제 후 실제 디스크 정리를 위해 Garbage Collection 주기적 실행 필수

harbor-core:
  jobservice:
    gc:
      schedule: "0 0 * * *"

결론 (Conclusion)

Harbor는 단순 이미지 저장소를 넘어, 보안·관리·확장성까지 모두 갖춘 엔터프라이즈급 레지스트리 솔루션이다.
다양한 보안 정책, RBAC, Helm Chart 관리, 취약점 스캔, 복제 기능 등은 클라우드 네이티브 환경에서 필수 요소가 되었다.
특히 내부 프라이빗 클러스터에서 안전하게 이미지 저장·관리할 수 있는 강력한 도구로 자리 잡았다.
제대로 활용하려면 초기 구성 시 스토리지, 보안, 모니터링까지 종합적으로 설계해야 하며, 꾸준한 모니터링과 정기 점검도 필수다.

Reference

Harbor Install
- https://github.com/goharbor/harbor-helm

https://vra4u.com/2023/01/11/harbor-quick-tip-leverage-oci-registry-with-helm/

728x90

'Open Source Software' 카테고리의 다른 글

Google Chrome Extension 만들어보기 (0)	2025.01.14
Vaultwarden(Bitwarden)이란? (2)	2024.11.08
Minio란? (Object Storage) (2)	2024.08.26
Habor Robot Account(하버 로봇 계정)란? (0)	2024.08.21
Cephadm-ansible이란? (3)	2024.02.29

현재글Harbor란?

Somaz의 IT 공부 일지

Harbor란?

Overview

📅 관련 글

Harbor란?

Harbor 주요특징

Harbor 구성요소

Harbor 설치

Harbor 아키텍처 다이어그램

실무 팁 - 설치 시 주의사항

1. 스토리지 용량 충분히 확보

2. 인증서 설정

3. 취약점 스캔 주기 설정

Harbor와 Docker Hub, ECR, Nexus 비교

설치 후 주요 점검 포인트

실무에서 자주 묻는 질문(FAQ)

Q1. Harbor 설치 위치는 어디가 적당한가요?

Q2. Harbor 성능 튜닝 포인트는?

Q3. 이미지 삭제 시 주의사항은?

결론 (Conclusion)

Reference

'Open Source Software' 카테고리의 다른 글

'Open Source Software'의 다른글

티스토리툴바

Harbor란?

Overview

📅 관련 글

Harbor란?

Harbor 주요특징

Harbor 구성요소

Harbor 설치

Harbor 아키텍처 다이어그램

실무 팁 - 설치 시 주의사항

1. 스토리지 용량 충분히 확보

2. 인증서 설정

3. 취약점 스캔 주기 설정

Harbor와 Docker Hub, ECR, Nexus 비교

설치 후 주요 점검 포인트

실무에서 자주 묻는 질문(FAQ)

Q1. Harbor 설치 위치는 어디가 적당한가요?

Q2. Harbor 성능 튜닝 포인트는?

Q3. 이미지 삭제 시 주의사항은?

결론 (Conclusion)

Reference

'Open Source Software' 카테고리의 다른 글

'Open Source Software'의 다른글

관련글

티스토리툴바