Migrate from Docker Hub to Harbor: what the move involves
A platform team that wants its images and Helm charts under its own control can move most of that content into Harbor without rebuilding anything. The migration is mostly replication, pull-path changes and a parallel run. Harbor can register Docker Hub as a replication endpoint and pull artifacts into a Harbor project, so the data movement is handled by configuration rather than by custom scripts. The work is usually done by platform or DevOps engineers, with a security reviewer checking access control, scanning settings and the pull secrets that move into the cluster and CI configuration.
The effort is mainly in inventory and cutover rather than in copying bytes. Start by listing which repositories and tags your build and deployment pipelines actually pull. For official images, the replication filter must include the library namespace, for example library/hello-world, or the rule will silently match nothing. Replication rules can run pull-based, filter by name, tag, label and resource type, and carry an optional bandwidth limit. Manual and scheduled rules do not replicate deletions, so plan how retired tags will be handled. For public base images you pull often, a proxy cache project is usually a better fit than a full copy, because it fetches on first request and serves the cached copy if Docker Hub is unreachable.
Cutover is where risk concentrates. Repoint CI jobs, imagePullSecrets and Helm oci:// references in a small set of pipelines first, and keep Docker Hub as a fallback until both registries have served the same digests for a full release cycle. Confirm the current Harbor release notes before you upgrade, since recent minor lines have changed the bundled database and cache and introduced breaking webhook and content trust behavior. Back up Harbor before every upgrade, and ask your DeployOpen or internal team to write down the rollback step for each pull path before the old one is switched off.
Which Docker Hub capabilities map cleanly to Harbor
This table compares the main Docker Hub capabilities with their Harbor equivalents and marks each as clean, needs rework or gap. Read it as a checklist: items marked clean can move with configuration, items needing rework require a policy or process change, and gaps need a decision before cutover. Confirm any Docker Hub feature not listed here against your own plan before you assume a match.
| Capability | Harbor equivalent | Status |
|---|---|---|
| Private repositories | Private Harbor projects hold images and Helm charts behind access control, with visibility set per project | Clean |
| Pull and push access | Role-based project membership controls pull and push; Harbor projects are read-only for pushes when used as proxy cache | Clean |
| Tags and multi-architecture images | Harbor stores tags and multi-architecture manifests as OCI content; confirm that every build pipeline publishes the same manifest lists | Needs rework |
| Helm charts | Charts are stored as OCI artifacts and pulled with oci:// references, since Harbor removed ChartMuseum in v2.8.0 | Needs rework |
| Team access and SSO | Harbor offers LDAP/AD and OIDC single sign-on and project roles, which replace Docker's plan-based SSO; map groups before cutover | Needs rework |
| Vulnerability scanning | Harbor scans images with the open-source Trivy scanner, enabled at install with --with-trivy; Docker Scout findings and policies do not carry over | Needs rework |
| Webhooks and automation | Harbor supports webhooks, but v2.15.3 blocks webhooks to internal network addresses by default, so confirm targets before cutover | Needs rework |
| Replication from Docker Hub | Pull-based replication rules copy images from Docker Hub into Harbor, but deletions are not replicated by manual or scheduled rules | Clean |
| Docker Hub features not covered by the supplied facts | Confirm with Docker and your own environment before assuming an equivalent exists in Harbor | Gap |
Migration sequence from inventory to decommission
This sequence moves images from Docker Hub into a self-hosted Harbor registry in controlled stages, so each team proves its pulls, pushes and cluster access before the old path is turned off. Each step ends with a named artifact that the next step depends on.
Inventory repositories, tags and pull consumers
Your platform team lists every Docker Hub namespace, repository and tag the organization depends on, including official images under the library namespace, and maps each one to the CI pipelines, Kubernetes namespaces and build hosts that pull it. Use the Docker Hub API with access tokens or a Skopeo listing to export the list, and count how many pulls each consumer makes so you know which pipelines are sensitive to rate limits. The output is a repository inventory with owners, tags to keep and consumers, which becomes the scope for every later step.
Stand up a Harbor pilot with one project
Install Harbor in your own infrastructure, following the installation prerequisites for your environment, and create a single project for one low-risk team. Connect the project to your identity provider through OIDC or LDAP/AD, set role-based access, and enable Trivy scanning if you chose the install-time option. The pilot is complete when a test user can push and pull an image through the project over TLS and the audit log records both actions.
Build and test a pull-based replication rule
Register Docker Hub as a replication endpoint, then create a pull-based rule that copies the pilot repositories into the Harbor project. Filters must include the library namespace for official images, for example library/hello-world, or those images will not match. Run the rule manually first, check digests against the source, and confirm that tag filters select only the tags you listed. Keep the bandwidth limit set during testing. Replication does not copy deletions, so record that behavior in the runbook. The output is a tested rule with a documented filter set and a digest comparison report.
Configure proxy cache projects for public base images
Create proxy cache projects for Docker Hub so builds and cluster nodes pull base images through Harbor instead of directly from Docker Hub. Harbor checks cached images with HEAD requests that do not count against the Docker Hub pull limit, and it keeps serving cached copies when Docker Hub is unreachable. Review the default 7-day retention policy and decide whether base images need a different setting. The check is that a clean build node pulls a base image through the cache and the Docker Hub pull counter does not move for the HEAD checks.
Run Harbor and Docker Hub in parallel
Expand replication rules to all inventoried repositories and keep existing pull paths working. Teams push new builds to Harbor while Docker Hub remains the fallback source. Compare digests on a schedule, track failed replication tasks, and confirm that scanner results and access rules match what each team expects. Harbor upgrades in this period need a backup first, because the v2.15.2 release notes recommend one before upgrading. The output is a parallel-run report showing zero unexplained digest mismatches for the agreed period.
Cut over CI and Kubernetes pull secrets
Change image references in pipelines and manifests to the Harbor host, then rotate imagePullSecrets in each Kubernetes namespace so nodes authenticate to Harbor. Update CI registry credentials with robot or service accounts scoped to the required projects. Cut over one team at a time, starting with the pilot, and keep the old Docker Hub references in a rollback branch. The step is complete when deployments in each namespace pull from Harbor and the old secrets are removed from the cluster.
Decommission Docker Hub dependencies
After every consumer has been cut over and the rollback window has closed, remove Docker Hub credentials from CI systems, delete unused replication rules and proxy cache references that point to superseded tags, and archive the inventory and parallel-run reports as the change record. Keep the Docker Hub account only as long as your contracts or audit obligations require, and confirm the retention decision with your compliance lead. The output is a signed decommission record listing each retired credential and rule.
Which data moves and which integrations must be rebuilt
Replication moves artifacts, not the workflow around them. In Harbor, the Docker Hub account is registered once as a replication endpoint, then a pull-based replication rule copies matching repositories and tags into a Harbor project. Manual and scheduled rules do not replicate deletions, so an image removed from Docker Hub stays in Harbor until someone removes it there. Confirm that retention is the behavior you want, and remember that official images need the library namespace in the filter, for example library/hello-world. For a one-time bulk export of every tag and architecture, Skopeo is a documented copy path that runs without privileges and can write to a local directory or another registry, which suits transfer hosts and isolated networks.
Image references are the integration most likely to break silently. Every CI pipeline, Dockerfile FROM line and Kubernetes manifest that names docker.io or a bare image name must be rewritten to the Harbor hostname and project path, and the pull secrets must change with them. Each namespace that pulls from Harbor needs an imagePullSecrets entry referencing a Docker-config secret for a Harbor robot or service account with pull rights, and the old Docker Hub credentials can be removed once no workload references them. Helm charts that pointed at a chart repository must switch to oci:// references, because Harbor no longer bundles ChartMuseum from v2.8.0. Check each helm command in pipelines, since a classic repository URL will not resolve against Harbor.
Webhooks and identity need separate decisions. Harbor v2.15.3 blocks webhooks to internal network addresses by default, so any notification that posts to an internal chat, ticketing or deployment endpoint will stop until an administrator explicitly allows it, and that change should be tested before cutover. On the access side, map Docker Hub organizations and teams to Harbor projects with role-based access control, and decide which groups come from your identity provider over OIDC or LDAP/AD. Confirm how group claims or directory groups will map to project roles before go-live, and record which accounts were personal Docker Hub logins that must be replaced with service accounts.
How the migration differs by estate size and starting point
A small team with a handful of repositories usually has the simplest path. The work is mostly copying a known set of images, pointing a few pipelines at the new registry and retiring the old references. Pull-based replication into a single Harbor project is often enough, because the team can list its repositories by hand and confirm each tag. The effort concentrates on access design and backups rather than throughput.
- Inventory first: List every repository and tag the team actually deploys, and drop tags that nothing references.
- Pull replication with explicit filters: Create one pull-based rule per namespace, and remember that official images need the
librarynamespace in the filter. - Manual or scheduled runs: A manual run before cutover plus one scheduled run is usually enough to keep the copies current.
- Project and role design: Map each team to a Harbor project with role-based access control instead of sharing one administrator account.
- Backups before upgrades: Take a backup before any Harbor upgrade, since upgrade notes recommend this.
Illustrative example: a team with a dozen services can often finish the copy in one session and verify each deployment against a test cluster. Confirm with your own tag list how many images and tags the copy covers before you schedule the cutover.
A large CI fleet that pulls public base images at high volume is limited by Docker Hub's pull quotas, not by storage. Here the proxy cache project matters more than replication. Harbor checks cached images with HEAD requests, which do not count against the Docker Hub rate limiter, so the fleet can pull through Harbor while only first pulls reach Docker Hub. Replication still helps for private images built by your own pipelines.
- Proxy cache for public images: Create a proxy cache project for Docker Hub so runners pull through Harbor on every job.
- Replication for internal images: Keep private build outputs in ordinary Harbor projects and replicate only what other sites need.
- Retention and cache size: Review the default 7-day retention policy for cached images against how often your pipelines use each base image.
- Runner configuration: Repoint runner registry mirrors and image references in batches, watching pull errors for each batch.
- Upstream outage behavior: Harbor serves the cached copy when Docker Hub is unreachable, which you should test by simulating an outage.
Confirm with your own CI logs how many pulls per hour reach Docker Hub today, and how much of that traffic a proxy cache would serve, before you size the storage and bandwidth plan.
A Kubernetes estate with many imagePullSecrets has a configuration problem more than a data problem. Every namespace, service account and Helm release may hold a pull secret that names docker.io or a Docker Hub credential. Replication moves the images, but the workloads only move when their image references and secrets change. The cutover sequence should therefore treat secrets and manifests as the main work item, with replication and proxy cache as the supporting pieces.
- Secret inventory: Find every
imagePullSecretsentry, everydockerconfigjsonsecret and every Helm value that sets an image registry. - Robot accounts per cluster: Create a Harbor robot account per cluster or environment with read-only access to the relevant projects.
- Staged rollout by namespace: Change one namespace at a time, starting with non-production, and keep the old reference available until each rollout is healthy.
- Helm charts as OCI: Harbor serves Helm charts as OCI artifacts from v2.8.0, so chart references should move to
oci://URLs in the same change window. - Node-level mirrors: If nodes resolve docker.io through a mirror, confirm the mirror and the Harbor endpoint do not conflict.
Confirm with your platform team which Kubernetes distribution and admission controls enforce image sources, because a policy that allows only one registry can block the rollout.
An air-gapped network cannot reach Docker Hub at all, so the migration becomes a transfer problem. The sequence starts outside the isolated network, where images are copied from Docker Hub into a staging area, then moves across a controlled transfer path into a Harbor registry installed from the offline installer. Skopeo fits this role because it copies images without privileges and can sync an external repository to a local directory. Proxy cache does not apply, since the isolated network has no upstream to cache from.
- Offline installer: Install Harbor from the offline package, not the online installer, which needs network access.
- Skopeo sync to a directory: Export the needed repositories and tags to a local directory on the transfer host, then import them into Harbor.
- Verification of transferred content: Compare digests on both sides of the transfer and record them as evidence.
- Scheduled refresh windows: Decide how often new image versions cross the boundary and who approves each transfer.
- Scanner data: Plan how Trivy vulnerability databases reach the isolated network, since scanning depends on updates.
Confirm with your security team which transfer media and approval steps your accreditation requires, because those rules set the cadence more than the tooling does.
What drives cost and duration in a Harbor migration
This table breaks a Docker Hub to Harbor move into cost components, showing who is paid, what is one-time and what recurs, and which inputs push effort up. Use it to shape a written scope, since most of the cost depends on how many images, tags and pull paths your estate has, not on the software itself.
| Component | One-time or recurring | What drives it | What to ask for in the written scope |
|---|---|---|---|
| Harbor, PostgreSQL and cache infrastructure | Recurring | Replica count, storage class and whether PostgreSQL and the cache run inside the bundled install or on managed services. Harbor v2.15.2 moved the bundled database to PostgreSQL 18 and Redis to Valkey. | Target topology, hosting location, HA design and who operates the database and backups |
| Storage growth | Recurring | Total size of mirrored images across tags and architectures, plus the retention and garbage collection schedule you set | Current image inventory by size and tag count, retention policy, and storage growth assumptions for the next 12 months |
| Pilot and replication tuning | One-time | Number of replication rules, name and tag filters, and bandwidth limits per task. Default concurrency is 10 per job-service pod, so large pulls may need more pods or staged batches. | Pilot scope, list of replication rules, bandwidth caps and the acceptance test for each rule |
| Official image namespace handling | One-time | Official Docker Hub images need the library namespace in the replication filter, such as library/hello-world, so each base image is a deliberate rule | List of base images used by builds and a check that each one is covered by a filter |
| Pull path and build changes | One-time | Number of CI pipelines, Kubernetes manifests, Helm values and pull secrets that reference docker.io. Each one needs a changed image path and a test pull. | Inventory of pull paths and Docker Hub-based builds, plus who edits and who approves each change |
| Cutover and dual running | One-time, with a period of running both registries | Length of the overlap period, the number of clusters switched in waves, and how far Docker Hub stays in use during rollback | Cutover plan, rollback steps, and the exit criteria that end dual running |
| Proxy cache projects for public images | Recurring | Number of cache projects and the retention policy (7-day default), which affects how often images are re-fetched and how much storage they hold | Which public images need caching and the retention setting per project |
| Upgrade effort across 2.13 to 2.15 lines | Recurring | Current installed version, the v2.15.2 database and cache change, the v2.15.3 breaking changes for webhooks and content trust, and the backup and reindexing steps | Upgrade runbook, backup evidence before each step, and a test environment that mirrors production |
| Vulnerability scanning setup | One-time setup, recurring tuning | Whether Trivy runs inside Harbor or as an external instance, scan policy on pushes, and how findings are triaged | Scanner placement, scan policy, and how findings flow to your ticketing or review process |
What usually goes wrong and how to prevent it
Most failed Docker Hub to Harbor migrations are not caused by Harbor itself. They come from filters that miss official images, replication rules that assume deletes travel, pull secrets nobody updated, upgrades run without a backup, and caches that behave differently when Docker Hub is slow or unreachable. Each card below names one of these risks and the check that catches it before cutover.
Official images missing from replication
Official Docker Hub images live under the library namespace, so a filter that only names your own repositories will silently skip base images such as hello-world. Your builds may then pull a base image that never reached Harbor and fail only in the cluster. Before the first run, list the exact repository paths you expect, including library/ entries, and confirm each one appears in the destination project. Run a pull-based rule against a small test set first and check the tag list, not just the job status.
Deletions that never propagate
Manual and scheduled replication rules do not replicate deletions. If a tag is removed or rebuilt at the source, Harbor keeps the old copy, so stale tags can remain available to deployments that still reference them. Decide early which side is the system of record, and write a cleanup routine for the destination that runs on a schedule. During cutover, compare tag inventories between the two registries rather than assuming a clean mirror.
Pull secrets still pointing at Docker Hub
Kubernetes clusters, CI runners and build agents often hold image pull secrets or registry credentials for Docker Hub, and image references in manifests still name docker.io. Moving the images does not move these references. Inventory every namespace, service account, Helm values file and pipeline variable that names Docker Hub, then repoint them to Harbor in a staged order. Keep the old credentials valid until the inventory shows no remaining pulls from Docker Hub.
Upgrades that migrate the database
Harbor v2.15.2 upgrades the bundled internal database from PostgreSQL 15 to PostgreSQL 18 on container startup and replaces Redis with Valkey as the cache backend. Starting the new version without a verified backup leaves no clean rollback path if the migration fails. Take a database and configuration backup, record the current version, and test the upgrade on a copy of the environment. Keep the release notes open, since they recommend running reindexdb if index problems appear.
Breaking changes in v2.15.3
Harbor v2.15.3 blocks webhooks to internal network addresses by default and makes signing of unsigned images fail in projects that enforce content trust. Teams that rely on internal notification endpoints or on signing workflows can see jobs stop after an otherwise routine upgrade. Read the release notes before choosing a version, review each project's content trust setting, and test webhook targets in a staging instance. Plan explicit allow-list or policy changes instead of relaxing controls under deadline pressure.
Proxy cache retention and upstream outages
A Harbor proxy cache project keeps serving cached images when Docker Hub is unreachable, but cached copies follow a default 7-day retention policy and can expire. Builds that depend on a cached image may fail once it ages out, or behave differently across environments that cached different versions. Set retention rules that match your release cadence, pin critical base images by tag or digest in your own projects, and alert on failed upstream checks so outages are visible before a deployment window.
Questions buyers ask before moving off Docker Hub
How much does it cost to move from Docker Hub to Harbor?
The cost is mostly people and infrastructure rather than licence fees, because Harbor is Apache-2.0 licensed. The recurring items are the servers or cloud capacity for Harbor, storage for images, PostgreSQL and Redis or their replacements, backups, scanning capacity, and the engineer time to upgrade and operate it. The one-time items are planning, replication setup, CI and Kubernetes changes, and testing. Your Docker subscription does not disappear automatically, so decide whether any paid Docker plan stays during cutover. Ask any implementation partner for a fixed-scope quote built from your image count, registry size, number of clusters and CI pipelines.
How long does a Docker Hub to Harbor migration take?
The timeline depends on how many repositories, tags and architectures you hold, how much bandwidth sits between Docker Hub and your Harbor host, and how many CI pipelines and clusters reference image names. Replication rules can be capped with a bandwidth limit in KB/s, which lengthens the copy but protects other traffic. Each pipeline and cluster also needs its pull secrets and image references updated and tested. Ask for a written schedule with these milestones and a named owner for each, and confirm the current Harbor release line with the vendor before you begin.
What does our internal team need to provide?
Your team needs to supply an inventory of images used by CI and clusters, a decision on the Harbor hostname, TLS certificates, storage and backup targets, and identity integration through LDAP, AD or OIDC. You also need named owners for image promotion, vulnerability triage and access approvals, plus a change window for CI and Kubernetes updates. Someone must hold credentials for a Docker Hub account with enough access to read the repositories you replicate. Confirm these items in the scope document so that nothing is discovered during cutover.
Can our own engineers run this migration without outside help?
Yes, a capable platform team can do it, since Harbor is documented and its replication and proxy cache features are configured in the web interface or API. The harder parts are sizing and hardening the installation, handling upgrades, and keeping backups and scanning working over time. Harbor v2.15.2 changed its bundled database and cache, and v2.15.3 introduced breaking changes to webhooks and content trust, so upgrades need reading and testing. Decide which of these your team will own after go-live and which, if any, you want a fixed-scope partner to cover.
Does a Harbor proxy cache alone fix Docker Hub rate limits?
A proxy cache project reduces pulls against Docker Hub, but it does not remove the limit on the first pull of each image. Docker Hub caps unauthenticated pulls at 100 per 6 hours per IPv4 address or IPv6 /64 subnet and Docker Personal accounts at 200 per 6 hours. Harbor re-checks cached images with HEAD requests that do not trigger that limiter, so steady-state CI traffic largely stops counting. Pulls of new tags still reach Docker Hub, so you should also authenticate the proxy's upstream credentials and confirm the behavior with Docker for your plan.
Does replication copy deletions from Docker Hub into Harbor?
No. Manual and scheduled Harbor replication rules do not replicate deletions, so an image removed from Docker Hub stays in Harbor until you remove it there. This matters for compliance because deleted content can remain available internally. Plan a retention and garbage collection policy in Harbor, record which copies are authoritative, and confirm the behavior of event-triggered rules in the release you deploy. Also remember that to replicate official Docker Hub images, the filter must include the library namespace, for example library/hello-world.
What happens to running clusters during cutover?
Running workloads keep the images they already have on their nodes, so a pod restart is the moment a cluster needs a new image reference. Run both registries during cutover: keep Docker Hub references working while you point CI and Kubernetes pull secrets and image names at Harbor in stages, then verify pulls from each cluster before removing the old path. Keep a rollback plan that restores the previous image reference. Ask the vendor or partner to document which namespaces, deployments and pipelines change at each step, and to test pulls from an isolated cluster first.
How the pilot and parallel run protect production pulls
Run Docker Hub and Harbor side by side for the whole cutover, and move one Harbor project and one pipeline first so that a failed pull affects a small, known set of builds. Create the Harbor project for that single workload, add a pull-based replication rule for only the images it uses, and point that one CI job at Harbor. Keep every other pipeline and Kubernetes namespace on Docker Hub until the pilot has produced clean pulls. Confirm that the replication filter includes the library namespace for any official images, because a filter that omits it will silently skip them.
Keep Docker Hub as the fallback until every pull secret and build reference is verified. In each pilot namespace, check that the imagePullSecrets entry points to a Harbor robot account with read-only access to the pilot project, and that Deployments reference the Harbor hostname in their image fields. Also check base image lines in Dockerfiles that the pilot pipeline uses. Do not delete Docker Hub pull secrets or tags during this period, since replication rules do not propagate deletions and a rollback should need only a manifest change.
Write rollback criteria before the first pilot pull, and agree them with the platform owner and the team that runs the affected services. Reasonable triggers include failed pulls from the Harbor hostname, image digests that differ from the Docker Hub source after replication, and any pull path that still needs Docker Hub credentials. Also decide how long the parallel run lasts and who signs off each step. Watch replication bandwidth limits and job concurrency, since a slow sync can leave the pilot project behind its source. Ask your Harbor administrator to confirm the current defaults for your installed version before you set those limits.
How DeployOpen scopes and runs a Harbor migration
DeployOpen is a Chainscore Labs company that plans, implements, hardens, documents and supports self-hosted open-source platforms inside the client's own cloud accounts, data centers or air-gapped networks. For a Docker Hub to Harbor migration, we start from a written scope that names the image inventory, replication rules, proxy cache projects and cutover plan before any work begins.
How we scope
- Inventory the repositories, tags and architectures your CI and clusters pull from Docker Hub today
- Agree in writing which images are replicated, which are cached through proxy projects and which are retired
- Define the Harbor projects, role-based access and OIDC or LDAP single sign-on your teams will use
- Confirm the cutover window, rollback path and the registry each cluster and pipeline will switch to
How we build
- Install Harbor in your environment, with PostgreSQL and Valkey settings sized to your own capacity
- Register Docker Hub as a replication endpoint and build pull-based rules with name and tag filters
- Configure proxy cache projects for public base images and test HEAD-based revalidation under load
- Enable Trivy scanning and audit logs, then verify behavior against the agreed test plan
How we hand over
- Document the replication rules, filters, retention settings and proxy cache policies as delivered
- Provide updated pull secrets and manifests for CI pipelines and Kubernetes namespaces
- Run a joint cutover rehearsal and record results, including what still pulls from Docker Hub
- Deliver backup and upgrade runbooks, including the backup step recommended before Harbor upgrades
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover
- Retainers can cover Harbor patch releases, including security fixes and breaking-change reviews
- Ask any quote to separate one-time migration work from recurring operations and support
- Confirm with DeployOpen how the retainer scope and response expectations are written into the contract
