Harbor: Private Container Registry

By Khimananda Oli | Last reviewed: August 2026

Deploying a Harbor: Private Container Registry solves the critical supply chain risks inherent in relying solely on public hubs like Docker Hub. For teams managing sensitive data, operating in air-gapped environments, or requiring strict compliance controls, a self-hosted registry provides the necessary isolation, vulnerability scanning, and role-based access control that public services cannot guarantee. This guide covers the practical architecture, secure installation, and operational workflows required to run Harbor reliably in production.

What is Harbor: Private Container Registry and why use it?

Harbor is more than just a storage backend for Docker images; it is a comprehensive cloud-native registry project designed specifically for enterprise security and governance. While you can store images in AWS ECR or Azure ACR, those are managed services tied to specific cloud vendors. Harbor provides vendor neutrality and can be deployed anywhere: on-premises, at the edge, or across multiple clouds. This portability is essential for organizations in Nepal and globally that need to avoid vendor lock-in or maintain data sovereignty.

In my experience helping teams achieve SOC 2 and ISO 27001 compliance, Harbor fills a specific gap: automated policy enforcement at the artifact level. Public registries let you pull anything. Harbor lets you define policies that block deployment if an image has critical CVEs, lacks a valid signature, or hasn't been scanned in the last 24 hours. This shifts security left effectively because the gatekeeper sits directly in the image distribution path.

Before diving into installation, understand that Harbor supports the OCI (Open Container Initiative) specification fully. This means it stores not just Docker images but also Helm charts, Singularity images, OPA bundles, and SBOMs. If you are building a platform engineering strategy, Harbor acts as the central artifact hub that feeds your internal developer platform securely.

How do you install Harbor: Private Container Registry on Kubernetes?

While Harbor offers a Docker Compose installer for single-node setups, production environments should always use the Helm chart on Kubernetes. This ensures high availability, easier upgrades, and integration with your existing cluster monitoring. I recommend dedicating a namespace specifically for registry infrastructure to isolate it from application workloads.

Prerequisites and storage planning

Harbor requires persistent storage for the database (PostgreSQL), cache (Redis), and object storage (for image blobs). In production, never use local-path provisioners unless you have a robust backup strategy. Use S3-compatible object storage (MinIO, Ceph, or cloud S3) for the blob layer to decouple compute from storage. This makes scaling and disaster recovery significantly simpler.

• Kubernetes: v1.28+ recommended for full OCI support.
• Ingress Controller: Nginx or Traefik with TLS termination.
• Certificates: Valid TLS cert (Let's Encrypt or internal CA) — never run HTTP in production.
• Storage: Min 50GB for DB/Redis, scalable S3 bucket for blobs.

Helm installation commands

Add the official Harbor Helm repository and create a values file tailored to your environment. The example below configures external S3 storage and enables Trivy scanning by default, which is critical for any DevSecOps workflow.

<!-- Add Harbor repo -->
helm repo add harbor https://helm.goharbor.io
helm repo update

<!-- Create namespace -->
kubectl create namespace harbor-system

<!-- Install with custom values -->
helm install harbor harbor/harbor \
  --namespace harbor-system \
  --set expose.type=ingress \
  --set expose.ingress.hosts.core=registry.example.com \
  --set externalURL=https://registry.example.com \
  --set persistence.enabled=true \
  --set persistence.imageChartStorage.type=s3 \
  --set persistence.imageChartStorage.s3.region=us-east-1 \
  --set persistence.imageChartStorage.s3.bucket=harbor-artifacts \
  --set trivy.enabled=true \
  --set trivy.ignoreUnfixed=true \
  --version 1.15.0

After installation, verify all pods are running. Harbor consists of multiple microservices: core, portal, registry, chartmuseum, trivy-adapter, jobservice, database, and redis. If the jobservice pod is restarting, check Redis connectivity first — this is the most common failure mode during initial setup.

How does vulnerability scanning and policy enforcement work in Harbor?

Security is the primary reason teams adopt Harbor: Private Container Registry over vanilla Docker registries. Harbor integrates Trivy natively as its default scanner. When an image is pushed, Harbor can automatically trigger a scan based on project-level policies. The results are stored as metadata attached to the artifact, making them queryable via API or UI without re-scanning.

Configuring prevention policies

Scanning alone is insufficient; you must enforce results. Harbor allows you to configure "Deployment Security" policies per project. Navigate to your project configuration and enable Prevent vulnerable images from running. Set the severity threshold to "High" or "Critical". This prevents Kubernetes from pulling images that fail the check if you integrate Harbor with admission controllers like Kyverno or OPA Gatekeeper.

For teams managing Kubernetes secrets and configurations, ensure your base images are also scanned. A common mistake is scanning only application layers while ignoring outdated OS packages in the base layer. Configure Harbor to scan base images nightly and alert when new CVEs are published against them.

Content trust and signing

Enable Content Trust (Cosign/Notary) to cryptographically sign images. This guarantees that the image pulled in production is exactly what was built and scanned in CI. In your CI pipeline, after a successful scan, sign the image digest:

# Sign image after successful push and scan
cosign sign --key cosign.key registry.example.com/myproject/app@sha256:abc123...

# Verify signature before deployment
cosign verify --key cosign.pub registry.example.com/myproject/app@sha256:abc123...

Harbor displays signed status in the UI and API. Unsigned images can be blocked via policy, ensuring supply chain integrity even if credentials are compromised.

How does Harbor compare to ECR, GCR, and Docker Hub?

Choosing between Harbor: Private Container Registry and managed alternatives depends on your compliance requirements, budget, and operational capacity. Managed services reduce toil but increase vendor dependency and cost at scale. Harbor increases operational responsibility but offers unmatched flexibility and zero egress fees for on-prem deployments.

For Nepali organizations or those serving local government/fintech sectors, Harbor is often the only viable option due to data residency requirements. Cloud providers may not have local regions, and routing sensitive financial data through Singapore or Mumbai might violate regulatory guidelines. Hosting Harbor locally ensures compliance while maintaining modern DevOps practices.

How do you configure replication and garbage collection in Harbor?

Production registries accumulate orphaned blobs and untagged manifests rapidly. Without active management, storage costs balloon and backup windows extend. Harbor provides two critical mechanisms: replication for HA/DR and garbage collection for hygiene.

Setting up cross-site replication

Replication in Harbor is rule-based, not just mirror-based. You can replicate specific projects, tags matching regex patterns, or only signed artifacts. This is useful for promoting images from dev → staging → production registries, or syncing to a disaster recovery site.

1. Navigate to Administration → Replications.
2. Create a new endpoint pointing to your target Harbor instance.
3. Define a replication rule with filters (e.g., tag v*.*.*, exclude *-dev).
4. Set trigger mode: Manual, Scheduled, or Event-based (on push).
5. Enable "Override destination" if you want to flatten namespaces or rename projects.

Test replication thoroughly before relying on it for DR. Bandwidth between sites (especially in Nepal where inter-datacenter links can be constrained) is often the bottleneck. Use scheduled replication during off-peak hours rather than event-based triggers for large artifacts.

Garbage collection best practices

Harbor's garbage collector runs as a job and marks unreferenced blobs for deletion. Schedule GC weekly during maintenance windows. Never run GC during peak push/pull activity — it can cause temporary latency spikes. Enable "Delete untagged artifacts" but set a retention period (e.g., 7 days) to allow rollbacks. Monitor GC job logs; failures here silently consume disk until you run out.

Conclusion

Implementing Harbor: Private Container Registry transforms your container workflow from a convenience into a governed, secure supply chain component. The initial operational investment pays dividends in compliance audit readiness, reduced egress costs, and protection against upstream supply chain attacks. Start with a minimal Helm deployment, enable Trivy scanning immediately, and gradually layer in signing and replication as your maturity grows.

If your team needs assistance designing a compliant registry architecture or integrating Harbor with existing monitoring stacks, reach out to discuss your infrastructure requirements. Secure artifact management is foundational — get it right early, and everything downstream becomes safer and faster.