Harbor Registry: The Production-Grade Docker Registry You Should Be Using

You're running 50 microservices on Kubernetes, each deployed multiple times a day. Your images live in Docker Hub or a basic registry. Security asks: 'Are all our images scanned for vulnerabilities?' Compliance asks: 'Can we prove who built each image and when?' Your team asks: 'Why is the registry so slow during deployments?' The answer to all three is Harbor — an enterprise-grade registry that's been the CNCF standard since 2020 and serves as the backbone for production container workflows at thousands of organizations.

Harbor is not just a place to store images. It's an image security platform. It integrates Trivy for automatic vulnerability scanning on push, supports Cosign and Notation for image signing and attestation, manages OCI artifacts beyond containers (Helm charts, OPA policies, SBOMs, signatures), replicates images across clouds and regions for DR, enforces retention policies with tag immutability and garbage collection, and provides a full audit trail of every push, pull, and delete.

By 2026, Harbor has become the default self-hosted registry for production Kubernetes. This guide covers deployment on Kubernetes with Helm, high-availability database configuration (Patroni, CloudNativePG, Redis Sentinel/Cluster), integration with Trivy for scanning, Cosign/Notation for content trust, OCI artifact management, replication strategies, garbage collection, and the production incident patterns that burn teams new to Harbor.

This guide is for platform engineers, DevOps teams, and SREs who need to deploy and operate Harbor in production. By the end, you'll have a production-grade Harbor deployment with HA database, automated scanning, content trust enforcement, and zero-downtime upgrades.

Deploying Harbor on Kubernetes with Helm: HA Configuration

Harbor's Helm chart is the recommended deployment method. It deploys 6+ components: core (API + UI), jobservice (GC, replication, scanning), registry (blob storage, based on Docker Distribution), trivy (vulnerability scanner), portal (web UI), and optional components like Notary, Clair, and ChartMuseum. For HA, you need high-availability for PostgreSQL and Redis — Harbor's stateful dependencies.

The Helm chart supports --set database.type=external to use an external PostgreSQL. For HA, use Patroni (PostgreSQL HA manager), CloudNativePG (Kubernetes-native operator), or a managed cloud database (RDS, Cloud SQL). CloudNativePG is the recommended choice for Kubernetes-native deployments: it manages failover, backups, and replica configuration automatically.

Redis: Harbor uses Redis for session storage (core), job queue (jobservice), and registry cache. For HA, use Redis Sentinel (for smaller deployments) or Redis Cluster (for larger ones). The Helm chart supports --set redis.type=external. Deploy Redis via the bitnami/redis Helm chart with sentinel mode: helm install redis bitnami/redis --set sentinel.enabled=true --set architecture=replication.

Storage: Harbor supports filesystem (PVC), S3, GCS, Azure Blob, and Swift backends. For production, use S3-compatible storage (MinIO, AWS S3, GCS). This decouples blob storage from Kubernetes nodes, enables multi-region replication, and provides durability. The Helm chart configures persistence.imageChartStorage.type: s3.

Ingress: Use a proper ingress controller (nginx-ingress, Traefik, or cloud LB). Harbor needs the ingress to support HTTP/2 for the registry API (it uses the Docker Registry protocol over HTTP/2). Configure TLS termination at the ingress. Set expose.type: ingress and expose.tls.secretName.

Minimal HA configuration: 3x core pods, 3x registry pods, 2x jobservice pods, external PostgreSQL (CloudNativePG cluster with 3 replicas), external Redis (sentinel with 1 primary + 2 replicas), S3 blob storage.

// io.thecodeforge — DevOps tutorial

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

# Create namespace
kubectl create namespace harbor

# Deploy CloudNativePG PostgreSQL
docker pull ghcr.io/cloudnative-pg/postgresql:16

echo """
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: harbor-db
  namespace: harbor
spec:
  instances: 3
  imageName: ghcr.io/cloudnative-pg/postgresql:16
  storage:
    size: 50Gi
  walStorage:
    size: 10Gi
""" | kubectl apply -f -

# Deploy Redis with Sentinel
helm install redis bitnami/redis -n harbor \
  --set architecture=replication \
  --set sentinel.enabled=true \
  --set auth.enabled=true \
  --set auth.password=redis-password

# Deploy Harbor with HA config
helm install harbor harbor/harbor -n harbor \
  --set expose.type=ingress \
  --set expose.ingress.hosts.core=harbor.example.com \
  --set expose.tls.auto.commonName=harbor.example.com \
  --set database.type=external \
  --set database.external.host=harbor-db-rw \
  --set database.external.port=5432 \
  --set database.external.username=harbor \
  --set database.external.password=harbor-db-password \
  --set database.external.sslmode=require \
  --set redis.type=external \
  --set redis.external.addr=redis-node-0.redis-headless:6379 \
  --set redis.external.sentinelAddrs=redis-node-0.redis-headless:26379 \
  --set redis.external.password=redis-password \
  --set persistence.enabled=true \
  --set persistence.persistentVolumeClaim.registry.size=200Gi \
  --set persistence.imageChartStorage.type=s3 \
  --set persistence.imageChartStorage.s3.region=us-east-1 \
  --set persistence.imageChartStorage.s3.bucket=harbor-blobs \
  --set persistence.imageChartStorage.s3.accesskey=AKIA... \
  --set persistence.imageChartStorage.s3.secretkey=... \
  --set trivy.enabled=true \
  --set trivy.severity=CRITICAL,HIGH \
  --set core.replicas=3 \
  --set registry.replicas=3 \
  --set jobservice.replicas=2

Trivy Integration: Automatic Vulnerability Scanning at the Registry Level

Harbor integrates Trivy as its default vulnerability scanner. When configured with --set trivy.enabled=true, Harbor deploys a Trivy scanner pod that automatically scans every image pushed to the registry. Scan results appear in the Harbor UI and are exposed via API. Harbor can enforce policies based on scan results: block pull of images with critical vulnerabilities, block push of images that fail scan, or quarantine images to a separate project.

Trivy in Harbor runs as a separate deployment. It downloads the vulnerability database on startup and updates it periodically. For air-gapped environments, pre-download the Trivy DB and mount it as a volume. The scanner pod needs internet access to update the CVE database, or use a local mirror.

Configuration: trivy.severity sets the severity threshold for blocking (default: CRITICAL). trivy.ignoreUnfixed (default: true) only fails scans on vulnerabilities with a known fix. trivy.gitHubToken sets a GitHub token for API rate limiting when downloading the DB.

Scan-on-push is the default. Schedule scans for existing images with the Harbor jobservice. For large registries, prioritize scanning production-tagged images first. Harbor's scanner supports parallel scanning across multiple scanner pods for throughput.

Policy enforcement: In project configuration, enable 'Prevent vulnerable images from being pulled' and set severity to Critical. Images with any critical CVE will return 403 on pull. This prevents vulnerable images from reaching Kubernetes even if CI/CD scanning missed them.

# io.thecodeforge — DevOps tutorial

# Harbor project policy: block pull of critical-vulnerability images
# Configured via Harbor API or UI
# This prevents vulnerable images from being deployed

apiVersion: goharbor.io/v1alpha1
kind: HarborProject
metadata:
  name: production
spec:
  vulnerabilityScanPolicy:
    analyzer: trivy
    parameters:
      severity: critical,high
      fixable: true
  enforcement:
    pull:
      enabled: true
      severity: critical
    push:
      enabled: false  # Allow push, block pull
  scanOnPush: true
  retentionPolicy:
    numberOfDays: 90
    immutableTags: true

# API equivalent:
# curl -X PUT "https://harbor.example.com/api/v2.0/projects/production" \
#   -H "Content-Type: application/json" \
#   -d '{"vulnerability_scan_policy": {"analyzer": "trivy", "parameters": {"severity": "critical"}}}'

Cosign and Notation Content Trust: Signing Images in Harbor

Harbor supports image signing and verification through two mechanisms: Cosign (Sigstore) and Notation (Notary v2). Both integrate with Harbor's content trust features to ensure that only signed images can be pulled from specific projects.

Cosign integration: Harbor stores Cosign signatures as OCI artifacts alongside the image. When you cosign sign <harbor-url>/project/image:tag, the signature is stored in Harbor as a separate OCI artifact referenced from the image manifest. Harbor does not verify signatures during push/pull by default — verification happens at the admission controller level (Kyverno) or via cosign verify. However, Harbor can enforce 'immutable tags' to prevent signature overwrite.

Notation (Notary v2) integration: Harbor has built-in support for Notation since version 2.8.0. Signature verification is enforced at the registry level: a project can be configured to require valid Notation signatures before allowing pull. This is the most mature content trust enforcement in Harbor. Set --set notary.enabled=true in the Helm chart to deploy the Notary signer.

Robot accounts: Harbor supports robot accounts for CI/CD automation. Create a robot account with push permissions, and use its credentials in CI pipelines. Robot accounts can be scoped to specific projects and expiration dates.

Best practice: use Cosign for keyless signing (via OIDC) in CI/CD pipelines, and use Notation for enterprise PKI-based signing (if you have an existing certificate authority). Harbor supports both simultaneously.

// io.thecodeforge — DevOps tutorial

# 1. Push an image to Harbor
docker pull alpine:latest
docker tag alpine:latest harbor.example.com/library/alpine:1.0
docker push harbor.example.com/library/alpine:1.0

# 2. Sign with Cosign (keyless)
cosign sign harbor.example.com/library/alpine:1.0
# Uses OIDC token from environment (GitHub Actions, etc.)
# Signature stored as OCI artifact in Harbor

# 3. Sign with Cosign (key-based)
cosign generate-key-pair
cosign sign --key cosign.key harbor.example.com/library/alpine:1.0

# 4. List signatures
cosign verify harbor.example.com/library/alpine:1.0 --key cosign.pub

# 5. Sign with Notation (requires Notation installed)
notation cert generate-test --default "harbor.example.com"
notation sign --key "harbor.example.com" harbor.example.com/library/alpine:1.0
notation verify harbor.example.com/library/alpine:1.0

# 6. Enable content trust enforcement in Harbor project
# Harbor UI → Project → Configuration → Enable Content Trust
# Then only signed images can be pulled from this project.

OCI Artifact Management: Beyond Container Images

Harbor supports OCI artifacts — any OCI-compliant content stored and managed like container images. This includes Helm charts, OPA policies, CNAB bundles, WASM modules, SBOMs, vulnerability reports, and custom artifacts. Harbor provides a unified UI and API for all artifact types.

Helm charts: Store and manage Helm charts directly in Harbor. Harbor's ChartMuseum component (deprecated in favor of OCI-native Helm charts) now supports pushing charts as OCI artifacts: helm push chart.tar.gz oci://harbor.example.com/project. Charts are versioned, searchable, and scanable for vulnerabilities in their dependencies.

OPA bundles: OPA/Gatekeeper policies can be stored as OCI artifacts in Harbor. This enables versioned, signed policy distribution. opa build -t oci . -o policy.tar.gz && oras push harbor.example.com/policies/kubernetes:1.0 policy.tar.gz.

SBOMs: Harbor can store CycloneDX and SPDX SBOMs as OCI artifacts. Attach SBOMs to image artifacts for supply chain transparency. Tools like Syft can generate and push SBOMs directly to Harbor: syft myapp:latest -o cyclonedx-json | oras push harbor.example.com/library/myapp:sbom-latest -.

Cosign signatures and attestations: Harbor stores Cosign signatures (.sig) and attestations (.att) as OCI artifacts referenced by the image manifest. cosign sign pushes to <image>.sig as a referrer. Harbor handles the referrers API automatically (OCI 1.1 spec).

OCI artifact management is configured per-project. Each artifact type can have its own retention policy, access control, and immutability settings.

// io.thecodeforge — DevOps tutorial

# 1. Push a Helm chart as OCI artifact
helm package my-chart/
helm push my-chart-1.0.0.tgz oci://harbor.example.com/helm-charts

# 2. Push an OPA bundle as OCI artifact
docker run --rm -v $(pwd)/policies:/policies openpolicyagent/opa:latest \
  build -t oci -o bundle.tar.gz /policies
oras push harbor.example.com/opa-bundles/k8s:1.0 bundle.tar.gz

# 3. Push an SBOM as OCI artifact
syft harbor.example.com/library/myapp:1.0 -o cyclonedx-json | \
  oras push harbor.example.com/library/myapp:sbom-1.0 -

# 4. List artifacts in a project
curl -u admin:harbor \
  -X GET "https://harbor.example.com/api/v2.0/projects/library/repositories"

# 5. List artifacts of a specific type
curl -u admin:harbor \
  -X GET "https://harbor.example.com/api/v2.0/projects/library/repositories/myapp/artifacts?with_tag=true"

# 6. Download an OCI artifact
oras pull harbor.example.com/opa-bundles/k8s:1.0 -o /tmp/policies

Garbage Collection, Replication, and Retention Policies

Harbor's garbage collection (GC) reclaims storage from blobs that are no longer referenced by any image tag. GC is critical for production registries that see frequent image pushes and deletions. Without GC, deleted images leave orphaned blobs that consume storage indefinitely.

GC configuration: Harbor's jobservice runs GC as a cron job. Default: daily at midnight. Configure via jobservice.gcCron in Helm values. Always run GC with --dry-run first to see what would be deleted. Review the GC report in Harbor UI. Enable --delete-untagged only after validating the dry-run.

Key GC risk: GC can delete blobs that are still referenced by an image tag if the reference count is temporarily inconsistent (e.g., during replication). Solution: schedule GC and replication at different times. Use S3 versioning or blob soft-delete to recover from accidental deletion.

Replication: Harbor replicates images between registries. Use cases: DR (replicate to a secondary Harbor in another region), migration (from Docker Hub to Harbor), multi-cloud (replicate to AWS ECR or GCR for cloud-native deployments), and edge distribution (replicate to edge registries).

Replication modes: push-based (Harbor pushes to remote) and pull-based (remote pulls from Harbor). Filter by repository name, tag pattern, or resource type. Replication respects Harbor's scan and content trust policies — only scan-passing images are replicated.

Retention policies: Harbor can automatically delete images based on rules: number of days since push, number of most recent tags to retain, or tag patterns to exclude. Combine with immutability to protect critical tags (latest, production) from deletion.

// io.thecodeforge — DevOps tutorial

# 1. Run GC in dry-run mode
# Create a manual job in Harbor UI or via API:
curl -u admin:harbor -X POST \
  https://harbor.example.com/api/v2.0/system/gc/schedule \
  -H "Content-Type: application/json" \
  -d '{"schedule": {"type": "Manual"}, "parameters": {"dry_run": true}}'

# 2. Check GC results
curl -u admin:harbor \
  https://harbor.example.com/api/v2.0/system/gc/1234

# 3. Run GC for real (only after dry-run review)
curl -u admin:harbor -X POST \
  https://harbor.example.com/api/v2.0/system/gc/schedule \
  -H "Content-Type: application/json" \
  -d '{"schedule": {"type": "Manual"}, "parameters": {"dry_run": false}}'

# 4. Create a replication rule (push to AWS ECR)
# Harbor UI → Administration → Replications → New Replication Rule
# Name: replicate-to-ecr
# Source: harbor.example.com/production/*
# Destination: aws_account_id.dkr.ecr.us-east-1.amazonaws.com/production/*
# Trigger: On Push
# Mode: Push-based

# 5. Create retention policy (keep last 30 tags, delete older)
curl -u admin:harbor -X POST \
  https://harbor.example.com/api/v2.0/projects/production/retentions \
  -H "Content-Type: application/json" \
  -d '{
        "algorithm": "or",
        "rules": [{
          "disabled": false,
          "template": "days_since_last_push",
          "params": {"num": 90},
          "tag_selectors": [{"kind": "doublestar", "pattern": "**", "decoration": "matches"}],
          "scope_selectors": {"repository": [{"kind": "doublestar", "pattern": "**", "decoration": "repoMatches"}]}
        }]
      }'