Harbor Production Architecture

Harbor is an open-source container registry that stores, signs, and scans container images. It is a CNCF Graduated project (since June 2020), which puts it in the same maturity tier as Kubernetes, Prometheus, and Envoy. The latest stable release is v2.14.x (as of early 2026), with v2.15 in release candidate. Harbor is fully OCI-compliant, meaning it works with any OCI-compatible client — Docker, Podman, Buildah, Helm, and OCI artifact tooling.

The core value proposition of Harbor is control. When you self-host a registry, you control where images live, who can access them, what security policies are enforced, and how images are distributed across environments. This matters enormously for air-gapped environments, regulated industries, multi-datacenter architectures, and organizations that need to reduce their dependency on external services.

Why self-host a registry?

• Air-gapped environments — Government, defense, financial, and healthcare systems that cannot reach the public internet need a local registry
• Compliance — Regulations like FedRAMP, HIPAA, PCI-DSS may require that container images are scanned, signed, and stored within your boundary
• Bandwidth and latency — Pulling from Docker Hub or cloud registries over the internet is slow, rate-limited, and unreliable at scale. A local registry eliminates external dependency
• Supply chain security — Vulnerability scanning, image signing (Cosign), and immutable tags give you provable guarantees about what runs in production
• Cost — Cloud registry egress charges add up fast at scale. Self-hosted is free beyond infrastructure

Registry comparison

Harbor is a multi-component system. Understanding the component layout is critical for troubleshooting, capacity planning, and designing HA deployments.

Core components

Request flow

When a client runs docker push registry.example.com/myproject/myapp:v1.2:

1. Nginx receives the request, terminates TLS, and routes it
2. Core Service handles authentication (checks credentials against the local DB, LDAP, or OIDC provider)
3. Core Service checks RBAC — does this user/robot account have push access to the myproject project?
4. If authorized, the request is proxied to the Registry (Distribution) component
5. Registry stores image layers (blobs) in the configured storage backend (S3, filesystem, etc.)
6. If scan-on-push is enabled, Core creates a scan job in Redis, which Job Service picks up and sends to Trivy
7. Trivy downloads the image layers, scans for vulnerabilities, and reports results back to Core via the database

Harbor provides an official installer that generates Docker Compose or Helm configurations. The deployment model you choose depends on your infrastructure, scale, and HA requirements.

Docker Compose installation

# Download the installer
wget https://github.com/goharbor/harbor/releases/download/v2.14.3/harbor-offline-installer-v2.14.3.tgz
tar xzf harbor-offline-installer-v2.14.3.tgz
cd harbor

# Copy and edit the config
cp harbor.yml.tmpl harbor.yml
# Edit harbor.yml: hostname, TLS certs, admin password, storage backend

# Run the installer
./install.sh --with-trivy

# The installer generates docker-compose.yml and starts all services
# Verify:
docker compose ps

Key harbor.yml settings

# harbor.yml (critical settings)
hostname: registry.example.com

https:
  port: 443
  certificate: /data/cert/server.crt
  private_key: /data/cert/server.key

harbor_admin_password: ChangeMeImmediately

database:
  password: db-password-here
  max_idle_conns: 100
  max_open_conns: 900

data_volume: /data    # local storage path

storage_service:
  s3:
    accesskey: AKIAIOSFODNN7EXAMPLE
    secretkey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
    region: us-east-1
    bucket: harbor-registry
    rootdirectory: /registry

trivy:
  ignore_unfixed: false
  skip_update: false       # set true for air-gapped
  insecure: false

Helm chart deployment

# Add the Harbor Helm repo
helm repo add harbor https://helm.goharbor.io
helm repo update

# Install with custom values
helm install harbor harbor/harbor \
  --namespace harbor --create-namespace \
  --set expose.type=ingress \
  --set expose.ingress.hosts.core=registry.example.com \
  --set expose.ingress.className=nginx \
  --set externalURL=https://registry.example.com \
  --set persistence.persistentVolumeClaim.registry.storageClass=gp3 \
  --set persistence.persistentVolumeClaim.registry.size=500Gi \
  --set database.type=external \
  --set database.external.host=harbor-pg.rds.amazonaws.com \
  --set database.external.port=5432 \
  --set database.external.username=harbor \
  --set database.external.password=secret \
  --set redis.type=external \
  --set redis.external.addr=harbor-redis.cache.amazonaws.com:6379 \
  --values harbor-values.yaml

Harbor does not have built-in clustering. HA is achieved by scaling stateless components horizontally and using HA-capable external services for stateful components. This is a common source of confusion — there is no "Harbor cluster mode" you can toggle on.

HA architecture

Stateless components (scale horizontally)

• Core Service — Run 2-3 replicas behind a load balancer. Each instance is identical. Session state is in Redis.
• Portal — Static web UI, scales trivially. Typically combined with Core in the same pod (Helm chart default).
• Registry (Distribution) — Multiple replicas all pointing at the same storage backend. S3 or shared filesystem required.
• Job Service — Runs async tasks. Multiple replicas consume from the same Redis queue. Jobs are idempotent.
• Trivy — Stateless scanner. Multiple replicas handle parallel scan requests.

Stateful components (use external HA services)

• PostgreSQL — Use managed databases (RDS, Cloud SQL, Azure DB) or Patroni for on-prem HA. Streaming replication with automatic failover.
• Redis — Use managed Redis (ElastiCache, Memorystore) or Redis Sentinel for on-prem. Redis Cluster mode is not natively supported by Harbor due to underlying library constraints — use Sentinel mode for HA.
• Storage Backend — S3 is strongly recommended for HA. It is the only storage option that is inherently distributed and fault-tolerant. Filesystem storage requires a shared NFS mount, which introduces its own SPOF unless you run an HA NFS service.

Load balancer configuration

# Nginx LB example for Harbor HA
upstream harbor_backend {
    server harbor-node1:443;
    server harbor-node2:443;
    server harbor-node3:443;
}

server {
    listen 443 ssl;
    server_name registry.example.com;

    ssl_certificate     /etc/ssl/certs/registry.crt;
    ssl_certificate_key /etc/ssl/private/registry.key;

    # Large body size for image pushes
    client_max_body_size 0;

    # Chunked transfer encoding for large layers
    chunked_transfer_encoding on;

    location / {
        proxy_pass https://harbor_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_request_buffering off;
    }
}

Harbor's registry component uses the Docker Distribution storage driver system. The storage backend holds image layers (blobs) and manifests. Choosing the right backend is one of the most impactful decisions for a Harbor deployment.

S3 storage configuration

# harbor.yml storage configuration for S3
storage_service:
  s3:
    accesskey: AKIAIOSFODNN7EXAMPLE
    secretkey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
    region: us-east-1
    bucket: harbor-registry
    regionendpoint: https://s3.us-east-1.amazonaws.com  # required for MinIO
    rootdirectory: /v2                                   # prefix in bucket
    encrypt: true                                        # SSE-S3 encryption
    multipartcopychunksize: 33554432                     # 32MB chunk for multipart
    multipartcopymaxconcurrency: 100
    multipartcopythresholdsize: 33554432

Garbage collection

Deleting an image tag in Harbor performs a soft delete — the tag is removed from the metadata database, but the blobs remain in storage. To reclaim disk space, you must run garbage collection (GC).

# Docker Compose: run GC manually
docker compose exec registryctl /home/harbor/harbor_registryctl garbage-collect

# Or trigger via API
curl -X POST "https://registry.example.com/api/v2.0/system/gc/schedule" \
  -H "Content-Type: application/json" \
  -u "admin:password" \
  -d '{"schedule":{"type":"Manual"}}'

# Schedule automatic GC (e.g., weekly at 2 AM Saturday)
curl -X PUT "https://registry.example.com/api/v2.0/system/gc/schedule" \
  -H "Content-Type: application/json" \
  -u "admin:password" \
  -d '{"schedule":{"type":"Weekly","cron":"0 0 2 * * 6"}}'

Cost optimization for large registries

• Tag retention policies — Automatically delete old tags. Keep the last N tags, or tags newer than N days. Combined with GC, this keeps storage manageable.
• S3 Intelligent-Tiering — Image layers that haven't been pulled in months move to cheaper storage automatically.
• Deduplication — Docker Distribution already deduplicates blobs (layers shared across images are stored once). This is automatic and significant — base images shared across hundreds of apps are stored once.
• Monitor storage growth — Track the harbor_project_quota_usage_bytes metric. Set alerts when total storage exceeds thresholds.

Harbor supports replicating images between Harbor instances and between Harbor and other registries (Docker Hub, GCR, ECR, ACR, Quay, GitLab, etc.). Replication is a key feature for multi-datacenter deployments, disaster recovery, and hybrid cloud architectures.

Replication modes

Replication policies

Policies define what gets replicated, with fine-grained filters:

• By project — Replicate all images in specific projects
• By repository — Filter by repository name pattern (e.g., myproject/api-*)
• By tag — Filter by tag pattern (e.g., v* for release tags only, exclude latest)
• By label — Replicate only images with specific labels (e.g., approved-for-production)
• By resource type — Images, Helm charts, or both

# Create a replication policy via API
curl -X POST "https://registry.example.com/api/v2.0/replication/policies" \
  -H "Content-Type: application/json" \
  -u "admin:password" \
  -d '{
    "name": "prod-sync",
    "src_registry": {"id": 1},
    "dest_namespace": "production",
    "trigger": {
      "type": "event_based"
    },
    "filters": [
      {"type": "name", "value": "myproject/**"},
      {"type": "tag", "value": "v*"}
    ],
    "enabled": true,
    "override": true
  }'

Cross-datacenter DR pattern

A common production pattern for disaster recovery:

1. Primary site (DC1) — Harbor with S3 storage, receives all pushes from CI/CD
2. DR site (DC2) — Harbor with its own S3 storage, receives push-based replication from DC1
3. Replication policy: event-driven, replicate all projects, all tags
4. DNS failover: if DC1 is down, switch registry.example.com to DC2
5. RTO depends on DNS TTL and replication lag (typically minutes for event-driven replication)

Security is Harbor's strongest differentiator over a bare Docker Distribution registry. The combination of vulnerability scanning, image signing, RBAC, and policy enforcement makes Harbor a supply chain security tool, not just a registry.

Scan-on-push configuration

# Enable scan-on-push for a project via API
curl -X PUT "https://registry.example.com/api/v2.0/projects/myproject" \
  -H "Content-Type: application/json" \
  -u "admin:password" \
  -d '{"metadata": {"auto_scan": "true"}}'

# Set a vulnerability prevention policy (block critical CVEs)
curl -X PUT "https://registry.example.com/api/v2.0/projects/myproject" \
  -H "Content-Type: application/json" \
  -u "admin:password" \
  -d '{"metadata": {"prevent_vul": "true", "severity": "critical"}}'

Robot accounts for CI/CD

# Create a robot account scoped to a project
curl -X POST "https://registry.example.com/api/v2.0/robots" \
  -H "Content-Type: application/json" \
  -u "admin:password" \
  -d '{
    "name": "ci-pipeline",
    "duration": -1,
    "level": "project",
    "permissions": [
      {
        "namespace": "myproject",
        "kind": "project",
        "access": [
          {"resource": "repository", "action": "push"},
          {"resource": "repository", "action": "pull"},
          {"resource": "tag", "action": "create"}
        ]
      }
    ]
  }'
# Response includes the robot token -- store it securely!

Image signing with Cosign

# Sign an image with Cosign (keyless, via Sigstore)
cosign sign --yes registry.example.com/myproject/myapp:v1.2

# Sign with a private key
cosign sign --key cosign.key registry.example.com/myproject/myapp:v1.2

# Verify a signature
cosign verify --key cosign.pub registry.example.com/myproject/myapp:v1.2

# Verify keyless signature (checks Fulcio cert + Rekor transparency log)
cosign verify \
  --certificate-identity=ci@example.com \
  --certificate-oidc-issuer=https://accounts.google.com \
  registry.example.com/myproject/myapp:v1.2

TLS configuration

Harbor must run with TLS in production. Docker and Podman refuse to push/pull from non-HTTPS registries unless explicitly configured as insecure (which you should never do in production).

# Generate a certificate (Let's Encrypt recommended for public-facing)
# For internal registries, use your organization's CA
openssl req -x509 -nodes -days 365 \
  -newkey rsa:4096 \
  -keyout /data/cert/server.key \
  -out /data/cert/server.crt \
  -subj "/CN=registry.example.com" \
  -addext "subjectAltName=DNS:registry.example.com"

# Distribute the CA cert to all Docker/Podman clients
# Docker:
mkdir -p /etc/docker/certs.d/registry.example.com/
cp ca.crt /etc/docker/certs.d/registry.example.com/ca.crt

# Podman:
cp ca.crt /etc/containers/certs.d/registry.example.com/ca.crt

Harbor organizes images into projects, which are the fundamental unit of access control and policy enforcement. Understanding the hierarchy and management features is essential for keeping a registry healthy at scale.

Project hierarchy

• Project — Top-level container (e.g., myproject). Maps to the first path segment in the image name: registry.example.com/myproject/myapp:v1
• Repository — An image name within a project (e.g., myproject/myapp). Contains multiple tags.
• Tag — A specific version of an image (e.g., v1.2.3, latest, sha-abc123)
• Label — User-defined metadata attached to images for filtering, replication, and organization

Tag retention policies

Without retention policies, registries grow unbounded. Every CI/CD pipeline push adds a new tag. Retention policies automatically clean up old tags.

# Create a tag retention policy via API
# Keep the 10 most recent tags matching "v*" and always keep "latest"
curl -X POST "https://registry.example.com/api/v2.0/retentions" \
  -H "Content-Type: application/json" \
  -u "admin:password" \
  -d '{
    "algorithm": "or",
    "rules": [
      {
        "action": "retain",
        "template": "latestPushedK",
        "params": {"latestPushedK": 10},
        "tag_selectors": [{"kind": "doublestar", "decoration": "matches", "pattern": "v*"}],
        "scope_selectors": {"repository": [{"kind": "doublestar", "decoration": "repoMatches", "pattern": "**"}]}
      },
      {
        "action": "retain",
        "template": "always",
        "tag_selectors": [{"kind": "doublestar", "decoration": "matches", "pattern": "latest"}],
        "scope_selectors": {"repository": [{"kind": "doublestar", "decoration": "repoMatches", "pattern": "**"}]}
      }
    ],
    "trigger": {"kind": "Schedule", "settings": {"cron": "0 0 3 * * *"}}
  }'

Proxy cache (pull-through cache)

Harbor can act as a pull-through cache for remote registries. When a client pulls registry.example.com/dockerhub-cache/library/nginx:latest, Harbor checks its local cache first. If the image is not cached or is stale, Harbor pulls it from Docker Hub, caches it locally, and serves it to the client.

• Reduces Docker Hub rate limiting — Unauthenticated pulls are limited to 100 per 6 hours, Docker Personal accounts to 200 per 6 hours (paid subscribers get unlimited pulls). A proxy cache means only the first pull hits Docker Hub.
• Bandwidth savings — Images are pulled once from the internet, then served locally at LAN speed.
• Resilience — If Docker Hub is down, cached images are still available.
• Supports: Docker Hub, GCR, Quay, GitHub Container Registry, ECR, and any OCI-compliant registry.

# Create a proxy cache project for Docker Hub
# In the Harbor UI: Projects > New Project > Proxy Cache
# Or via API:
curl -X POST "https://registry.example.com/api/v2.0/projects" \
  -H "Content-Type: application/json" \
  -u "admin:password" \
  -d '{
    "project_name": "dockerhub-cache",
    "registry_id": 1,
    "metadata": {"public": "true"}
  }'

# Pull through the cache (from any Docker client):
docker pull registry.example.com/dockerhub-cache/library/nginx:1.25

Quota management

Projects can have storage quotas to prevent any single team or project from consuming all available storage:

# Set a 50 GB quota on a project
curl -X PUT "https://registry.example.com/api/v2.0/projects/myproject" \
  -H "Content-Type: application/json" \
  -u "admin:password" \
  -d '{"storage_limit": 53687091200}'  # 50 GB in bytes

Multi-architecture images

Harbor fully supports OCI image indexes (multi-arch manifests). Push multi-platform images with docker buildx or crane, and Harbor stores and serves the correct architecture automatically:

# Build and push a multi-arch image
docker buildx create --use
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag registry.example.com/myproject/myapp:v1.2 \
  --push .

Harbor upgrades involve database migrations and container image updates. The upgrade process differs between Docker Compose and Helm deployments, but both require careful planning.

Pre-upgrade checklist

1. Read the release notes — Check for breaking changes, deprecated features, and migration notes at github.com/goharbor/harbor/releases
2. Back up the database — pg_dump the entire Harbor database. This is non-negotiable.
3. Back up the configuration — harbor.yml, TLS certificates, custom configs
4. Test in staging first — Restore the database backup to a staging instance and upgrade there
5. Check the upgrade path — Harbor supports upgrading from N-2 to N (two previous minor versions). Skipping more than two minor versions (e.g., 2.10 to 2.14) requires stepping through intermediate versions.

Docker Compose upgrade

# 1. Back up the database
docker compose exec harbor-db pg_dump -U postgres registry > harbor-backup-$(date +%Y%m%d).sql

# 2. Back up the config
cp harbor.yml harbor.yml.bak
cp -r /data/secret /data/secret.bak

# 3. Stop Harbor
docker compose down

# 4. Download the new version
wget https://github.com/goharbor/harbor/releases/download/v2.14.3/harbor-offline-installer-v2.14.3.tgz
tar xzf harbor-offline-installer-v2.14.3.tgz -C /opt/harbor-new

# 5. Copy your existing harbor.yml to the new directory
cp harbor.yml /opt/harbor-new/harbor/harbor.yml

# 6. Run the migration tool (if required by release notes)
docker run -it --rm \
  -v /data/database:/var/lib/postgresql/data \
  goharbor/harbor-db-migrator:v2.14.3 up

# 7. Run the installer
cd /opt/harbor-new/harbor
./install.sh --with-trivy

# 8. Verify
docker compose ps
curl -s https://registry.example.com/api/v2.0/systeminfo | jq .harbor_version

Helm chart upgrade

# 1. Back up the external database
pg_dump -h harbor-pg.rds.amazonaws.com -U harbor -d registry > harbor-backup.sql

# 2. Update the Helm repo
helm repo update harbor

# 3. Check what will change
helm diff upgrade harbor harbor/harbor \
  --namespace harbor \
  --values harbor-values.yaml

# 4. Perform the upgrade
helm upgrade harbor harbor/harbor \
  --namespace harbor \
  --values harbor-values.yaml \
  --timeout 10m

# 5. Watch the rollout
kubectl -n harbor rollout status deployment/harbor-core
kubectl -n harbor get pods

Upgrade path rules

Harbor exposes Prometheus-compatible metrics and health check endpoints. Production deployments need proactive monitoring to catch storage issues, scan backlogs, and authentication failures before they become incidents.

Key metrics

Prometheus metrics endpoint

# Enable metrics in harbor.yml
metric:
  enabled: true
  type: prometheus
  port: 9090
  path: /metrics

# Prometheus scrape config
- job_name: 'harbor'
  scrape_interval: 30s
  metrics_path: /metrics
  static_configs:
    - targets:
      - harbor-core:9090
      - harbor-registry:9090
      - harbor-jobservice:9090
      - harbor-exporter:9090

Health check endpoints

# Overall health check
curl -s https://registry.example.com/api/v2.0/health | jq
# Returns component status for each service:
# {
#   "status": "healthy",
#   "components": [
#     {"name": "core", "status": "healthy"},
#     {"name": "database", "status": "healthy"},
#     {"name": "redis", "status": "healthy"},
#     {"name": "registry", "status": "healthy"},
#     {"name": "registryctl", "status": "healthy"},
#     {"name": "trivy", "status": "healthy"}
#   ]
# }

# Use in Kubernetes liveness/readiness probes
# The Helm chart configures these automatically

Grafana dashboard

Community Grafana dashboards are available for Harbor. Key panels to include:

• Push/pull rate over time (operations per minute)
• Storage usage per project (trend line with forecast)
• Scan results distribution (pie chart: critical, high, medium, low)
• Replication status (success/failure counts, lag time)
• API response latency (p50, p95, p99)
• Active robot accounts and their last-used timestamps

Log aggregation

# Docker Compose: logs go to /var/log/harbor/ by default
# Configure log rotation in harbor.yml:
log:
  level: info       # debug, info, warning, error, fatal
  local:
    rotate_count: 50
    rotate_size: 200M
    location: /var/log/harbor

# For K8s: use a log aggregator (Loki, ELK, Fluentd)
# Harbor pods write to stdout/stderr (standard K8s logging)

Harbor is licensed under Apache 2.0 and is a CNCF Graduated project. There is no enterprise edition, no feature gating, no paid tier. Every feature is available in the open-source release. This is a significant differentiator in the registry space, where most competitors have commercial editions with gated features.

CNCF Graduated status

CNCF Graduation means Harbor has met the foundation's highest maturity bar:

• Adopted by a diverse set of production users
• Passed an independent security audit
• Has a healthy contributor ecosystem (not single-vendor dominated)
• Follows CNCF governance practices

Commercial support

While Harbor itself is free, commercial support is available:

• VMware/Broadcom — Harbor was originally created by VMware. VMware Tanzu products include Harbor as a supported component. Following the Broadcom acquisition, the support landscape is evolving.
• Community support — GitHub issues, CNCF Slack (#harbor channel), community mailing list. Response times vary.
• Third-party consultants — Several CNCF-ecosystem consultancies offer Harbor deployment and support.

Registry comparison (licensing & cost)

Before deploying Harbor for a client, work through these questions:

1. Deployment platform? — Kubernetes (Helm) or Docker Compose on VMs? K8s is strongly preferred for production.
2. Storage backend? — S3/MinIO for HA and scalability. Filesystem only for single-node dev setups. Estimate initial storage: how many images, how large, how fast will it grow?
3. Database? — External PostgreSQL with HA (RDS, Patroni). Never use the built-in database for production.
4. HA requirements? — Multiple Harbor replicas + external DB/Redis + S3 storage + load balancer. Or is single-node acceptable?
5. Authentication? — OIDC (Keycloak, Azure AD, Okta) or LDAP? How will CI/CD authenticate (robot accounts)?
6. Security scanning? — Scan-on-push enabled? Vulnerability prevention policy (block critical CVEs)? Air-gapped Trivy DB?
7. Image signing? — Cosign (recommended; Notary v1 was removed in Harbor v2.9). Keyless (Sigstore) or key-based? Verification policies in the deployment pipeline (Kyverno, OPA Gatekeeper)?
8. Replication? — Multi-site deployment? DR requirements? Push or pull mode? Bandwidth between sites?
9. Proxy cache? — Cache Docker Hub pulls to avoid rate limiting? Cache other upstream registries?
10. Retention and GC? — Tag retention policies per project. GC schedule. Maintenance window for GC.
11. TLS certificates? — Let's Encrypt, internal CA, or manual? Certificate distribution to all Docker/K8s clients.
12. Monitoring? — Prometheus metrics, health checks, storage alerts, scan backlog alerts. Grafana dashboard.
13. Backup strategy? — Database backups (pg_dump + WAL archiving). Config backups. S3 bucket versioning for registry blobs.
14. Upgrade plan? — Who owns upgrades? What's the upgrade cadence? Staging environment for testing upgrades?