Harbor is an open-source registry that stores and distributes container images and other OCI artifacts such as Helm charts. It builds on the open-source Docker Distribution and adds what a plain registry lacks: projects with role-based access control, user and group integration, vulnerability scanning, image signing, replication between registries, retention and immutability policies, and audit logs. It addresses the problems of relying on public registries, which bring rate limits, outside control of sensitive images and limited governance, by giving organisations a registry they own, in their own network or cloud. Harbor began in 2014 as an internal VMware project for developers using containers and was open sourced in 2016. It was donated to the CNCF in summer 2018, accepted as an incubating project in November 2018, and graduated in June 2020, announced on June 23, 2020, as the eleventh CNCF project to do so. Release 2.15 followed in March 2026.
CNCF daily · Sprint 1, day 5 · Container Registry
At a glance
| Category | Container Registry |
| CNCF status | Graduated. Incubating since November 2018; graduated June 2020 |
| Written in | Go |
| License | Apache 2.0 |
| Artifacts | Container images and OCI artifacts, including Helm charts and SBOMs |
| Security features | RBAC, project quotas, vulnerability scanning with Trivy, image signing, immutable tags and robot accounts |
| Replication | Push and pull replication between Harbor instances and other registries, plus proxy-cache projects |
| Identity | Local users, LDAP or Active Directory and OIDC |
| Release status | 2.15 (March 2026), with 2.14 and 2.13 also supported |
Architecture
flowchart TB
DEV[Docker, containerd, Helm, CI] -->|push and pull over HTTPS| PROXY[Ingress or load balancer]
PROXY --> CORE
subgraph H[Harbor components]
CORE[Core service<br/>API, auth, projects, policy] --> REG[Registry<br/>Distribution storage API]
CORE --> JOB[Job service<br/>replication, GC, scans]
CORE --> PORTAL[Portal<br/>web UI]
CORE --> TRIVY[Scanner adapter<br/>Trivy]
end
CORE --> DB[(PostgreSQL<br/>metadata and policy)]
CORE --> REDIS[(Redis<br/>cache and job queue)]
REG --> STORE[Object storage<br/>S3, GCS, Azure Blob]
JOB -->|replicate| OTHER[Other registries<br/>Harbor, ECR, Docker Hub]
CORE --> IDP[LDAP, AD or OIDC<br/>identity provider]
CORE --> OBS[Metrics and audit logs<br/>Prometheus]
| Component | Responsibility |
|---|---|
| Core service | Serves the API, authenticates users, enforces project policy and coordinates the other components. |
| Registry | The Docker Distribution engine that stores and serves image layers and manifests. |
| Job service | Runs asynchronous work such as replication, garbage collection, retention and scanning. |
| Portal | The web interface for projects, users, policies and scan results. |
| Scanner adapter | Connects Harbor to vulnerability scanners. Trivy is the default optional scanner. |
| PostgreSQL and Redis | PostgreSQL holds metadata, users and policies, and Redis provides caching and the job queue. |
| Storage backend | Local disk or object storage such as S3, GCS and Azure Blob holds the image content. |
Design principle. Harbor keeps the image storage engine, Docker Distribution, and layers governance around it. Access control, scanning, signing, replication and retention are policy attached to projects, so a team gets a private, audited registry without modifying client tooling, since Docker, containerd, Helm and CI systems all use the standard registry API.
Production reference design
A common pattern on EKS, GKE, AKS and on-premises Kubernetes, and on virtual machines in private data centres where public registries are not acceptable:
- Plan the dependencies. For high availability use an external PostgreSQL service, external Redis, and object storage for image data, rather than the chart’s bundled single-instance defaults. Reserve a DNS name and a TLS certificate, for example issued by cert-manager.
- Install with the Helm chart and a values file, pinning a current supported release:
helm repo add harbor https://helm.goharbor.io helm install harbor harbor/harbor --version <version> \ -n harbor --create-namespace -f values.yaml# values.yaml (check keys against the chart version you install) externalURL: https://registry.example.com expose: type: ingress tls: certSource: secret secret: { secretName: harbor-tls } ingress: className: nginx hosts: { core: registry.example.com } persistence: imageChartStorage: type: s3 s3: { region: ap-south-1, bucket: example-harbor-registry } trivy: { enabled: true } metrics: { enabled: true } - Model projects and access. Create a project per team or application, connect identity through LDAP or OIDC, and give pipelines robot accounts limited to push or pull on specific projects, never personal credentials.
- Turn on guardrails. Enable scan on push, block deployment of images above a chosen severity, use immutable tag rules for release tags, set tag retention and storage quotas, and require signatures where your pipeline signs images with Cosign.
- Use proxy cache and replication. Create a proxy-cache project for Docker Hub or another upstream to avoid rate limits and speed up pulls, and replicate critical projects to a second Harbor in another region for disaster recovery.
- Use it from CI and clusters. Push with a robot account, and point cluster nodes or containerd mirror settings at Harbor:
docker login registry.example.com -u 'robot$ci-orders' --password-stdin < token.txt docker push registry.example.com/orders/api:2.8.1 - Operate it. Run scheduled garbage collection, back up PostgreSQL, watch storage growth and scan results, and scrape Harbor’s metrics with Prometheus.
Typical production uses include a private registry for internal applications, a pull-through cache for public images, a promotion path across environments, a disaster-recovery mirror, and a store for Helm charts and other OCI artifacts.
Operational considerations
- Treat it as production infrastructure. If Harbor is down, deployments and node scaling can stall on image pulls. Run it highly available with external PostgreSQL, Redis and object storage, and test restores.
- Run garbage collection deliberately. Deleting a tag does not free storage until garbage collection runs. Schedule it, use retention rules and monitor storage growth, particularly with proxy-cache projects.
- Stay within the support window. The three latest minor releases receive fixes, and upgrades are supported only from two minor releases back, so upgrade regularly rather than in large jumps.
- Lock down access. Restrict project creation, use robot accounts with narrow scopes and expiry, enforce TLS, and review audit logs. Public projects expose their images to anyone who can reach the registry.
- Scan results need a process. Scanning on push finds known vulnerabilities but does not fix them. Decide who owns triage, which severities block deployment and how exceptions are recorded.
Adoption
- The CNCF graduation announcement named production users including CaiCloud, China Mobile, Hyland Software, JD.com, MuleSoft, Samsung SDS, Trend Micro and VMware.
- JD.com reported saving about 60 percent of maintenance time on its private image repository, and China Mobile said it adopted Harbor in 2017 and relies on it in its enterprise container cloud platform.
- At graduation, 83 organisations had contributed to the project, including Anchore, Aqua Security, DigitalOcean, OVHcloud and Tencent.
Alternatives
| Solution | Model | Best suited to |
|---|---|---|
| Cloud registries (ECR, Artifact Registry, ACR) | Managed registries inside a cloud account | Teams that want no registry to operate and are tied to one cloud |
| Docker Distribution | The minimal open-source registry | Small or air-gapped setups that need storage without policy features |
| Quay | Registry with scanning and access control | Red Hat OpenShift environments |
| GitLab or GitHub registries | Registry bundled with source hosting | Teams that want images next to their code and pipelines |
| JFrog Artifactory and Sonatype Nexus | Universal artifact repositories | Organisations that store many package formats beyond containers |
Strengths and limitations
| Strengths | Limitations |
|---|---|
| Rich governance: RBAC, quotas, immutability, retention and audit logs | You operate it, including database, cache, storage and upgrades |
| Built-in vulnerability scanning and signing support | Scanning surfaces issues but does not remediate them |
| Replication and proxy cache for disaster recovery and public rate limits | Garbage collection and storage growth need active management |
| Standard registry API works with Docker, containerd, Helm and CI | Several components make high availability more involved than a plain registry |
| Mature, graduated project with an active release cadence | Support window is short, with upgrades limited to two minor versions back |
Recommendation
Adopt Harbor when you need a private registry with governance, a pull-through cache or cross-region replication, especially on-premises, in private cloud or across several clouds. Deploy it highly available with external PostgreSQL, Redis and object storage, use robot accounts and scan-on-push policies, and plan regular upgrades. If you run on a single cloud and want no registry to operate, the provider’s managed registry is the simpler choice.
References: CNCF project page · CNCF: Harbor graduation announcement · CNCF blog: Harbor for modern private cloud · Harbor documentation · Harbor release lines on endoflife.date · Harbor on GitHub