Harbor vs Distribution registry: which to choose

Harbor vs Distribution registry: when each one fits

Choose Harbor when several teams share one registry and you need project-level access control, vulnerability scanning and replication on top of storage. Choose the bare CNCF Distribution registry when one team or a small set of automated pipelines pushes and pulls images, the access model is a shared htpasswd file or a token service you already run, and scanning happens elsewhere in the pipeline. Harbor extends Distribution rather than replacing it, so the choice is about how much control plane you want to operate, not about image format or protocol.

Four drivers settle most decisions. First, count the teams and projects that will share the registry: Harbor's projects with role-based access control separate them without separate registries, while Distribution gives you one namespace with one credential store. Second, identify the identity system that must sign users in. Harbor supports LDAP/AD and OIDC single sign-on, whereas Distribution's basic authentication uses bcrypt htpasswd credentials and its token authentication requires your own or a third-party authentication service. Third, decide whether scanning is a policy requirement. Harbor bundles Trivy when installed with the --with-trivy option, and Distribution has no built-in scanner. Fourth, name the operator after launch. Harbor adds a database, a cache, audit logs and upgrades that need backups first, so confirm who owns those tasks.

Before you commit, check two things in your own environment. Confirm the storage backend you need: Distribution defaults to the local filesystem and offers drivers such as Amazon S3, and Harbor's storage and database requirements are in its installation prerequisites. Also confirm that any registry, however simple, sits behind TLS before external hosts reach it. If your answer to the four drivers points toward more than one team, an audit trail, or a scanning gate, Harbor is the likelier fit, and a written scope with a partner can test that assumption against your identity and storage setup.

Which registry fits which team setup

This table matches common team setups to the registry that fits better and explains the reason in terms of supplied capabilities. Read each row as a starting point: the answer changes when the conditions in the last column change, so use it to decide which requirements to confirm first.

Team setup	Better fit	Reason and what would change the answer
One team pushing internal images to one cluster	Distribution registry	A single team with a small set of images needs little beyond push, pull and TLS. Distribution uses htpasswd or delegated token auth and stores data on the local filesystem by default. Choose Harbor if the team later expects project-level permissions or a scanning step.
Several teams needing isolated projects	Harbor	Harbor projects carry role-based access control and LDAP, AD or OIDC single sign-on, so access follows your identity provider. Distribution has no project concept, so isolation would depend on separate registries or external token services you build and operate yourself.
Regulated environment expecting scanning and audit logs	Harbor	Harbor includes Trivy vulnerability scanning (enabled with the --with-trivy install option), audit logs and garbage collection. Distribution provides none of these natively. Either choice can work if an external scanner and log pipeline already meet your evidence requirements, so confirm what your assessor expects before deciding.
Site that must pull from upstream registries during outages	Harbor	Harbor proxy cache projects serve a cached copy when the upstream is unreachable and support Docker Hub, ECR, ACR, GCR, Quay, GitHub Container Registry and JFrog Artifactory. Distribution can be configured as a pull-through mirror, but the caching controls, retention and replication rules are Harbor features, so confirm the exact behavior you need in your test environment.
Multi-site or multi-registry sync	Harbor	Harbor replication runs push or pull rules filtered by name, tag, label and type, on manual, cron or push and retag triggers, with an optional bandwidth limit. Distribution has no built-in replication, so you would script copies and manage their failures yourself.
Air-gapped or edge site with few operators	Distribution registry	Distribution is a single service with a small footprint and few moving parts, which suits a site with limited staff. Harbor brings a database, cache and several components, and its 2.15 line upgrades the bundled PostgreSQL from version 15 to 18 on startup, so it needs a backup plan and operator time. Choose Harbor if the site needs its RBAC, scanning or replication, and confirm the sizing with your own environment.
Team relying on token-based auth from an existing identity system	Either, depending on build effort	Distribution supports delegated token authentication, but you must provide or integrate the authentication system yourself. Harbor already integrates LDAP, AD and OIDC, so it usually needs less custom code. Pick Distribution if your team already runs a token service that meets your standards.
Stack that stores images and Helm charts as OCI artifacts	Harbor	Harbor stores container images and Helm charts as OCI artifacts and removed ChartMuseum from v2.8.0, so chart management sits in the same registry. Distribution implements the OCI Distribution Specification, but chart governance, labels and retention would be handled outside it.

How Harbor is built on top of Distribution

Harbor keeps the open-source Distribution registry at its core and adds the layers that a team usually has to build around a bare registry: projects, identity, scanning, audit and an API. Each layer below is a separate thing to size, secure and upgrade, so the day-two questions attach to each one.

The registry core

Distribution implements the OCI Distribution Specification and handles pushes, pulls and blob storage. Harbor builds on this core rather than replacing it, so image transport behaves the same way at the protocol level. Check that your clients, mirrors and CI tooling are tested against the Harbor endpoint, not only against Distribution, because the surrounding authentication and project rules sit in Harbor.

Management and metadata layer

Harbor adds projects with role-based access control, audit logs, garbage collection and a REST API with an embedded Swagger UI. This layer stores who owns which repositories and what policy applies to them. Plan for it as stateful configuration: it needs backup and restore procedures, and changes to projects and roles should be reviewed like any other access change.

Identity integration

LDAP/AD and OIDC single sign-on sit in Harbor, not in the bare registry, which relies on htpasswd or delegated token authentication. Confirm which identity source your directory or OIDC provider exposes, how group membership maps to Harbor roles, and what happens to access when a user is removed from the source system.

Bundled database and cache

Harbor ships an internal PostgreSQL database and a cache. In v2.15.2 the bundled database moves from PostgreSQL 15 to PostgreSQL 18 on container startup, and Redis is replaced by Valkey as the cache backend. The release notes recommend a backup before upgrading and a reindexdb run if index problems appear. Decide whether you will run the bundled database or an external one, because that choice decides who patches and backs it up.

Vulnerability scanner

Harbor's static analysis uses the open-source Trivy scanner, enabled at install time with the --with-trivy option, and can connect to an external Trivy instance or other scanners. Scanning is a separate component with its own vulnerability database updates and resource use. Confirm how your environment supplies scanner database updates, especially in networks with restricted egress.

Storage backends and day-two operations

The bare Distribution registry stores data on the local filesystem by default and supports drivers such as Amazon S3. Harbor sits on the same storage model, so capacity planning, garbage collection timing and backup scope follow from the storage you choose. Ask your team which component owns each backup, how upgrades are sequenced across the database, cache and registry, and who signs off on each Harbor release.

Side-by-side feature support for registry security and operations

This table compares the security, identity, storage and operations features of Harbor and the bare CNCF Distribution registry. Read each row as a question about your own requirements: where Harbor's built-in features are required, Distribution can still be enough if you are prepared to build the surrounding controls yourself. The main takeaway is that Distribution provides the registry protocol, while Harbor adds the access model, scanning and replication around it.

Capability	Harbor	Distribution registry
License	Apache-2.0, CNCF graduated project	Apache-2.0, CNCF project
Projects with role-based access control	Yes	No
LDAP/AD and OIDC single sign-on	Built in, configured in Harbor. Confirm the directory attributes and group mapping against your identity provider.	Not built in. Delegated token auth needs your own or a third-party authentication system.
Basic authentication	Local accounts and project-level roles managed in Harbor	Bcrypt htpasswd credentials, the simplest restriction in the deployment guide
Vulnerability scanning	Trivy enabled at install with --with-trivy, or an external Trivy or other scanner. Confirm the scanner version your release bundles.	Not included. Scanning must be added through a separate tool in your pipeline.
Garbage collection and audit logs	Both provided in the platform. Confirm retention and log forwarding for your audit needs.	Garbage collection available through the registry tooling. Audit logging must be built or sourced separately.
Replication	Push or pull, filtered by name, tag, label and resource type, run manually, on cron or on push and retag, with optional bandwidth limits	Not included. Mirroring must be scripted or handled by external tooling.
Proxy cache	Supported for several upstream registries. Cached copies are read-only for pushes, and the default retention policy is 7 days.	Pull-through caching is not a Harbor-style managed project. Confirm the upstream configuration you need.
Default storage	Stores artifacts in the platform's configured backend. Confirm the storage setup for your environment.	Local filesystem by default, with drivers such as Amazon S3 available
OCI Helm charts	Served as OCI artifacts from v2.8.0, ChartMuseum no longer included	Stores OCI artifacts through the OCI Distribution Specification. Confirm chart tooling and workflows.

How authentication differs between htpasswd, tokens and Harbor SSO

The main difference is where user identity lives. The Distribution registry's simplest access restriction is basic authentication with bcrypt htpasswd credentials, which means the registry itself holds a file of usernames and hashed passwords that someone must create, rotate and remove by hand. Delegated token authentication moves that decision outward: the registry hands authentication to a token service, and the Distribution deployment guide is clear that this requires an authentication system your team already runs or buys. Nothing in the registry supplies that system for you, so the token service becomes a component you must deploy, secure and keep available.

Harbor takes a different position. Its README describes projects with role-based access control and LDAP/AD or OIDC single sign-on as built-in features, so user lifecycle, group-to-role mapping and project membership are managed inside Harbor instead of in a separate file or custom token service. For a team that wants offboarding to work through the directory it already uses, this is the decisive difference. The cost is that Harbor's own administration becomes a system of record you must back up and audit, and project roles must be reviewed as people change teams.

Whichever registry you choose, TLS must be in place before external hosts can reach it, as the Distribution deployment guide requires. Confirm with your identity team exactly how directory groups or OIDC claims map to Harbor roles in your own environment, including who may create projects, who may push to production repositories and what happens to access when a group is renamed. Test a revoked account against both registries before go-live, because an htpasswd entry or a cached token can outlive the person it was issued to.

Licensing and editions for each registry

Harbor is licensed under Apache-2.0 and is a CNCF project that joined the CNCF on July 31, 2018, moved to incubating on November 14, 2018 and reached the Graduated maturity level on June 15, 2020. The latest stable release is v2.15.4, published on October 9, 2026. The 2.14 and 2.13 lines still receive patch releases, with v2.14.5 and v2.13.6 both published on October 6, 2026, so you can choose a line that matches your upgrade cadence.

License: Apache-2.0 covers the project code you install, with no paid edition supplied in the facts for this page.
CNCF maturity: Graduated status since June 15, 2020, which signals a mature governance process.
Current stable line: v2.15.4, published October 9, 2026, with v2.15.0 shipped on March 20, 2026.
Maintained older lines: 2.14 (v2.14.5) and 2.13 (v2.13.6) received patch releases on October 6, 2026.
Commercial support: no paid support edition is supplied, so confirm any vendor support options directly with the maintainers or vendors.

Check the Harbor GitHub releases page before you pin a version in your change plan.

What drives the running cost of each registry

Running either registry costs more than the software itself. The main components are the storage and compute you provision, the people who upgrade and patch, and the work to make the registry secure and reachable by your pipelines. Harbor bundles more of that work, while a bare Distribution registry shifts it onto your team and your integration effort.

Storage and compute footprint

Both registries store image layers in a backend, and that storage grows with every build, tag and retained version. Distribution writes to the local filesystem by default and supports storage drivers such as Amazon S3. Harbor adds its own database, cache and scanner components, so it needs more CPU and memory before any images are stored. Ask the quote to size storage growth against your retention rules, not only today's footprint.

Upgrade and patch effort

Upgrades recur for both registries, and Harbor's upgrades carry more moving parts. Recent Harbor releases changed the bundled database and cache engines and introduced breaking changes in webhooks and content trust, and the release notes recommend a backup before upgrading. Each Harbor patch cycle needs a test run against your pipelines. Distribution has a smaller surface, but you still own every patch to the registry, its TLS setup and its host.

Scanning and database operations

Harbor's Trivy scanning and bundled PostgreSQL database are running services you operate. Trivy needs its vulnerability data kept current, and the database needs backups, restore tests and capacity planning. A bare Distribution registry has neither component, which lowers its ongoing operating load but also removes scanning altogether. Confirm in the quote who maintains the scanner configuration and the database lifecycle after handover.

Building auth, scanning and replication

This is the largest cost for a bare Distribution registry. Its simplest access control is htpasswd basic authentication, and token authentication requires your own or a third-party authentication system. Scanning, replication, proxy cache, audit logs and project-level access are not included, so your team or a partner must build and test each one. Engineering time for this work is usually one-time, but every integration you build becomes a maintenance item.

Support contracts and vendor terms

Harbor is Apache-2.0 and community supported, so a support contract is optional. Any paid support or managed service recurs annually or per term and should be priced separately from the implementation. Distribution has no vendor support tier to compare. Ask for the response scope, the supported versions and whether patches for older Harbor lines are included, since the project has continued patch releases on several lines.

Quote scope and handover documentation

Setup work is largely one-time: identity integration with your directory, scanning policy design, replication rules and backup design. Ask each quote to state the scope of identity integration, the scanning configuration and policies, backup and upgrade testing in a staging environment, and the handover documentation for runbooks and certificate renewal. Clear scope in writing lets you compare the two options on the same basis.

Moving from Distribution to Harbor without losing images

This sequence takes a team from a bare Distribution registry to Harbor with projects, identities, copied artifacts and scanning in place, and ends with a retired old registry only after clients have been verified against Harbor. It works best when each step closes with a written check the platform owner can point to.

Inventory repositories, tags and access rules
The platform owner lists every repository, tag and image digest in the existing registry, along with which users, service accounts and CI jobs push or pull each one. The Distribution registry keeps access rules in its own configuration, such as the htpasswd file or the token authentication service, so export those lists and note which entries are human users and which are machines. The step is done when the inventory is a reviewed document that another engineer can use to rebuild access without asking the original author. Confirm with your security team whether any repositories contain content that must be retained under a records policy before anything is copied.
Stand up Harbor with a tested backup plan
The platform team installs Harbor in its own environment, choosing the installer or Helm-based deployment that matches the team's Kubernetes or VM footprint and enabling Trivy at install time with the --with-trivy option if scanning is in scope. Before loading any data, the team takes a backup of the Harbor database and storage and restores it into a scratch environment to prove the procedure works. Harbor v2.15.2 upgrades its bundled database from PostgreSQL 15 to PostgreSQL 18 on container startup and recommends a backup before upgrading, so use the same discipline for the first install. The step is done when a restore has been tested and recorded. Confirm the supported prerequisites in the installation documentation before sizing hosts.
Create projects and map identities
Create Harbor projects that mirror the grouping in the old inventory, such as one project per team or per environment, and decide which projects are private. Connect Harbor to your identity source through LDAP, Active Directory or OIDC single sign-on, then assign project roles to groups rather than individual users where the identity provider supports it. Users, role assignments and access rules do not transfer automatically from Distribution, so every mapping is rebuilt here from the inventory. The step is done when a test account from each group can log in and sees only the projects its role allows. Robot accounts for CI should be created separately and documented with their intended permissions.
Copy images and Helm charts into projects
Copy each image from the old registry into the matching Harbor project, preserving tags and verifying digests after each batch, using a tool your team already trusts such as a registry copy utility or a replication rule. Harbor stores Helm charts as OCI artifacts from v2.8.0 onward and no longer serves ChartMuseum, so migrate charts as OCI artifacts into their projects and update any chart references that assumed the older chart repository format. Replication rules in Harbor can pull from or push to other registries, but for a one-time move a deliberate copy with digest checks is easier to audit. The step is done when a sample of digests in Harbor matches the source inventory and every chart installs from its new location.
Repoint clients and CI pipelines
Update image references in manifests, Helm values, build pipelines and node or runtime configuration to the Harbor hostname and project paths, and recreate the credentials CI uses as Harbor robot accounts. Recreate any webhooks that notify other systems, and note that in Harbor v2.15.3 webhooks to internal network addresses are blocked by default, so an allowlist or a reviewed configuration change may be required before they work. Test a pull and push from each environment before removing the old endpoint from configuration. The step is done when a canary deployment in each environment runs from Harbor and the build pipelines complete a push without manual intervention.
Enable scanning, retention and content trust policy
Configure vulnerability scanning on each project, define retention and garbage collection schedules, and decide whether content trust is enforced. Retention and scanning policies are rebuilt in Harbor, not carried over from Distribution. Be aware that in Harbor v2.15.3 signing unsigned images fails in projects that enforce content trust, so confirm that every signing workflow in CI works against the new endpoint before enforcement is turned on. The step is done when a test push is scanned, a policy violation blocks a deliberately unsigned test image in an enforcing project, and the results are documented in the platform runbook.
Retire the old registry
Keep the Distribution registry in read-only mode for a period agreed by the platform owner and the security team, then decommission it after logs show no remaining pulls from old endpoints. Preserve the final inventory, backups and configuration files as evidence of the migration. Confirm with your compliance lead what retention applies to those records. The step is done when access logs for the agreed period show no legacy traffic, the old storage is archived or deleted according to policy, and the change record is closed.

Where Harbor and Distribution projects usually run long

Distribution is quick to stand up for one team, but the work grows once authentication has to match corporate identity. Running the Distribution registry means TLS in front of the registry, a storage driver (local filesystem by default, with drivers such as Amazon S3), an auth approach and client configuration on every build host. Basic auth with bcrypt htpasswd credentials is the simplest option the deployment guide describes. Delegated token authentication requires your own or a third-party authentication system, so that system becomes a project in its own right. Confirm early whether your identity provider can issue tokens the registry can validate, because that decision sets the rest of the timeline.

Harbor front-loads the design work, and most of the long projects stall in four places. Installation depends on the prerequisites for your platform, so confirm them against the Harbor installation prerequisites documentation before you size hosts. Plan for the database and cache changes in v2.15.2, which upgrade the bundled database from PostgreSQL 15 to PostgreSQL 18 on container startup and replace Redis with Valkey, and take the backup the release notes recommend first. Plan also for the v2.15.3 change that blocks webhooks to internal network addresses by default, and for the failure of signing unsigned images in projects that enforce content trust. Both can break a pipeline that worked on the previous release.

Identity mapping, CI client changes, storage sizing and policy design are the four areas where teams usually lose time. Map LDAP, AD or OIDC groups to Harbor project roles before onboarding users, because a mapping error surfaces as access failures across many projects. Every CI job that pushes or pulls needs its credentials and endpoint updated, and that change is easy to underestimate when many pipelines share one registry. Storage sizing depends on image churn, retention and garbage collection schedules, which you should model from your own pipeline history rather than assume. Finally, decide on scanning gates, replication direction and proxy cache retention as policy before go-live, since changing them later affects every project that inherited the defaults.

What buyers ask before choosing a registry

Is the simple Distribution registry enough for a small team?

It can be, if the team needs to push and pull images, has one or a few users, and can accept basic authentication with bcrypt htpasswd credentials or build its own token authentication. The Distribution deployment guide says the simplest access restriction is htpasswd, that delegated token auth requires an authentication system you run or source elsewhere, and that TLS is required before external hosts can reach it. The questions to settle are who needs access, whether you need per-project permissions, whether you need image vulnerability scanning and whether you need replication or proxy caching. If the answer to the last three is yes, plan for Harbor from the start, because adding those controls later means building them around the registry.

What drives the effort to run Harbor?

Effort depends on how many projects, users and identity sources you connect, the storage backend, whether you use the bundled internal database or an external one, and how often you upgrade. Harbor's installer enables Trivy only if you pass the --with-trivy option at install time, so scanning is a deliberate setup choice. Upgrades carry real work: v2.15.2 moved the bundled database from PostgreSQL 15 to PostgreSQL 18 on container startup and replaced Redis with Valkey, and its release notes recommend a backup first. Confirm the Harbor version, the deployment method (installer, Helm or operator) and the backup and restore process you will own before estimating ongoing load.

Can we run Harbor ourselves or do we need outside help?

Many teams run Harbor in-house, provided they have people comfortable with Kubernetes or Docker hosts, certificates, PostgreSQL backups, LDAP or OIDC integration and upgrade testing. Teams without that depth often bring in outside help for the initial design, hardening and runbooks, then operate it themselves. DeployOpen plans, implements, hardens, backs up, upgrades, documents and supports self-hosted platforms inside your own infrastructure, and most engagements are fixed-scope with scope, deliverables and timelines agreed in writing before work starts. Ongoing support and upgrades are available as retainers. Ask any provider to show which tasks they will perform and which stay with your team.

How long does a migration from Distribution to Harbor take?

No duration can be stated here, because it depends on the number of repositories and tags, the storage size, how many clients point at the old registry hostname, and how much CI and Kubernetes configuration must change. Migration usually includes deciding project structure, recreating access rules, copying artifacts (for example with replication from the old registry, if your setup allows it), testing pulls from every cluster and cutting over DNS or client settings. Request a written scope that lists the inventory of repositories, the cutover plan, the rollback method and the acceptance tests before you accept any timeline.

What does Harbor need from our identity and platform teams?

Harbor supports LDAP or Active Directory and OIDC single sign-on, so your identity team must provide a directory or OIDC client, group mappings to Harbor roles and a process for removing access when people leave. Platform teams must provide TLS certificates, DNS, storage (a persistent volume or object storage backend), network paths from build and cluster nodes, and a place to run the database and Redis or Valkey components. Confirm with both teams who owns certificate renewal, service accounts for robot access in CI and the audit log retention you need. Gaps in these areas usually cause more delay than the Harbor installation itself.

Can Harbor replicate or proxy from our existing registries?

Yes, according to the Harbor documentation. Replication endpoints include another Harbor, Docker Hub, a Docker registry, AWS ECR, Azure Container Registry, Google Artifact Registry, GitHub Container Registry, JFrog Artifactory and several regional clouds. Replication rules can be push or pull based, filter by repository name, tag, label and resource type, and run manually, on a cron schedule or on push and retag events. Proxy cache projects can cache Docker Hub, another Harbor, Docker registry, AWS ECR, Azure ACR, Google GCR, Quay, GitHub Container Registry and JFrog Artifactory, and serve the cached copy if upstream is unreachable. Check that your specific registry type appears in the replication endpoint documentation and confirm credentials, network reachability and bandwidth limits before you plan cutover.

Is a commercial support contract available for Harbor?

Harbor is Apache-2.0 licensed and a CNCF graduated project, and its maintainers publish stable releases and patch lines on GitHub. Those releases do not come with a vendor support contract. For a commercial agreement, confirm with the vendor or service provider you choose what response commitments, upgrade assistance and hours are included in writing. DeployOpen offers implementation, hardening, upgrades, documentation and support as fixed-scope work or retainers, and does not publish a price list, so a quote follows from the written scope. Ask any provider for a named support process and the exact patch and security response terms.

How DeployOpen helps choose and implement a registry

DeployOpen helps teams decide whether Harbor's projects, RBAC, scanning and replication justify its extra components, or whether a Distribution registry with token authentication fits the workload. Where Harbor is chosen, we plan and deploy it inside your own infrastructure and hand it over with documented controls.

How we scope

We confirm which registry features your teams need, such as per-project RBAC, scanning, replication or pull-through caching.
We document the identity source, TLS certificate approach and storage backend in the written scope before work starts.
Engagements are fixed-scope, with deliverables and timelines agreed in writing, and ongoing support available as a retainer.

How we build

We deploy Harbor or Distribution in your cloud accounts, data centers or air-gapped network, with the storage backend you select.
We configure OIDC or LDAP single sign-on, project roles, Trivy scanning and garbage collection schedules to match your policy.
We test push, pull, replication and upstream outage behavior, and we review upgrade paths such as the Harbor v2.15.x database changes.

How we hand over

We document the installation, configuration, backup and restore steps so your platform team can operate the registry.
We provide runbooks for user onboarding, access reviews, certificate rotation and handling breaking changes between Harbor releases.
We deliver evidence of configured controls that your internal or external assessors can review, without issuing any audit report.

How we support

Retainers cover upgrades, patching of Harbor components and periodic review of configuration as your registry usage grows.
We can run continuous security testing of the registry and its surrounding APIs under a separate written scope.
Support boundaries, response expectations and upgrade responsibilities are set out in the retainer agreement before it starts.

Harbor vs Distribution registry