How teams migrate Docker repositories from Nexus to Harbor
Moving a Nexus Docker estate to Harbor is a copy, a rebuild and a planned reference change. Images in Nexus hosted Docker repositories are pulled and pushed into Harbor projects through a replication rule, Nexus proxy repositories are recreated as Harbor proxy cache projects, and every cluster, pipeline and build file that names the old registry host is switched over on a date the platform team controls. Teams usually start this work when a Nexus licensing limit, a data residency requirement or a wish to reduce lock-in makes the current registry hard to keep, and they usually run it themselves with an implementation partner for the replication, access model and cutover. The work is owned by platform or DevOps engineers, with security and identity staff involved for roles and LDAP or OIDC groups. The effort is moderate and driven by the number of repositories, the number of tags that must survive, the number of consumers and how many clusters pull from the registry. Before the first replication, inventory each Docker hosted and proxy repository, record which tags are still in use, and confirm with the Harbor documentation how replication handles the image formats you hold. Plan for a parallel period in which old and new registry hosts both serve pulls.
Map Nexus privileges to Harbor projects and roles first, because replication and proxy cache projects inherit their access rules from Harbor, not from Nexus. Connect Harbor to your LDAP or AD groups or OIDC provider before creating the replication endpoints, and test that a pull from a non-admin account in each cluster succeeds. Proxy repositories need separate handling: a Harbor proxy cache project reads from the upstream on demand and keeps a cached copy, so confirm its retention policy and how a pull behaves during an upstream outage in your own environment. Maven, npm and other formats are a separate track covered by the sibling Nexus pages on Pulp, so do not plan them into this cutover.
Which Nexus Docker features map to Harbor and which need rework
This table maps each Nexus Repository Docker feature to its closest Harbor equivalent and marks it as clean, needs rework or gap. Use it to scope the migration before you touch production clusters, and confirm the Nexus-specific details in your own instance because Nexus behavior varies by edition and version.
| Nexus feature | Harbor equivalent | Status | Where to confirm |
|---|---|---|---|
| Hosted Docker repositories | Harbor projects holding pushed images and Helm charts as OCI artifacts | Clean | Push a sample image and tag set to a test project and compare manifests and digests |
| Proxy repositories for Docker Hub and other registries | Proxy cache projects, which are read-only for pushes and serve cached copies if upstream is unreachable | Needs rework | Re-create each proxy as a proxy cache project and confirm the default 7-day retention policy fits your needs |
| Group repositories that merge several Docker sources | No direct equivalent; use separate proxy cache projects and update client image references per source | Gap | Inventory every group member and confirm with your platform team which clients pull through the group URL |
| Role-based access to repositories | Project roles with RBAC for members and project administrators | Needs rework | Map each Nexus privilege to a Harbor role and test write and pull access per project |
| LDAP realms and group mapping | LDAP/AD authentication and group-based project membership | Needs rework | Confirm group search base, filters and attribute names against your directory before cutover |
| Cleanup policies for old tags and components | Tag retention rules and scheduled garbage collection of unreferenced blobs | Needs rework | Review Nexus cleanup behavior in your version and set equivalent Harbor retention per project |
| Repository and component REST API | Harbor REST API with embedded Swagger UI | Needs rework | Rewrite CI scripts and automation calls against Harbor endpoints and test them in staging |
| Replication from Nexus to another registry | Replication rules, push or pull, with filters by name, tag and label | Clean | Confirm whether a Docker registry endpoint on your Nexus version supports the pull mode you need |
| Audit logging of repository events | Harbor audit logs for project and repository actions | Needs rework | Compare retained fields and retention period with your compliance evidence requirements |
What data and integrations move, and what you rebuild
Harbor replication moves image layers and tags, but it does not carry over everything a Nexus instance does. Roles, identity mappings, CI credentials, scanners and webhooks each need a deliberate decision before cutover. The cards below separate what copies from what you configure again.
Image layers and tags via replication
Harbor replication rules can run push-based or pull-based, so you can pull from a Docker registry endpoint that points at Nexus or push from a staging Harbor. Filters by repository name, tag, label and resource type control what moves, and a per-task bandwidth limit protects the Nexus network path during the copy. Check that tag names and digests match on both sides before you retire the source. For illustrative planning, run a small hosted repository first and compare manifest digests. Confirm the replication behavior against the Harbor replication rules documentation.
Helm charts as OCI artifacts
Helm charts stored in Nexus as a classic chart repository do not move as a Harbor project by default, because Harbor removed its bundled ChartMuseum server in v2.8.0. Charts must be pushed to Harbor as OCI artifacts and referenced with oci:// URLs in Helm commands and CI pipelines. Check every helm repo add line and chart dependency in your build files. Plan the cutover so chart consumers switch to the OCI path in the same change window.
Users and groups from LDAP, AD or OIDC
Harbor maps identity through LDAP/AD or OIDC single sign-on, but the group-to-role assignments are yours to recreate. Nexus privileges and roles do not translate automatically into Harbor project roles. Export your Nexus role inventory, map each directory group to a Harbor project role, and test with a non-production account. Ask your identity team whether service accounts for CI will live in the directory or in Harbor's local store.
CI push credentials and robot accounts
Pipelines that push images to Nexus hold credentials that must be replaced with Harbor credentials scoped to specific projects. Create dedicated robot accounts with push or pull rights only where needed, and store them in your secrets manager rather than in pipeline variables copied by hand. Update every pipeline and cluster pull secret in the same window, or builds will fail at push time. Confirm the robot account model with your Harbor version's documentation.
Vulnerability scanners and Trivy
Nexus scanning and any policy tied to it do not carry over. Harbor provides static analysis through Trivy when installed with the --with-trivy option, or it can connect to an external Trivy instance or other scanners. Harbor v2.15.4 bundles Trivy 0.75.0. Decide which scanner gates deployments, set severity thresholds, and test that scan results appear for migrated images.
Webhooks and internal network targets
Harbor v2.15.3 blocks webhooks to internal network addresses by default, which affects notifications to internal chat tools, CI servers or SIEM collectors on private ranges. Review every webhook you rebuild and decide whether to allow specific internal targets. Also check that signing unsigned images fails in projects that enforce content trust, which can break workflows that signed images late. Test both behaviors on a staging Harbor before production cutover.
Migration sequence from inventory to Nexus decommission
This sequence moves Docker hosted, proxy and group repositories from Nexus to Harbor without a single high-risk cutover. Each phase ends with a checkable output, so the team knows when it can move to the next one and when Nexus can be retired.
Inventory Docker repositories and their consumers
Platform engineering lists every Docker hosted, proxy and group repository in Nexus, including its upstream, retention settings, tags in use and the role and LDAP group that can read or write it. In parallel, the team maps which clusters, CI pipelines and build jobs pull or push each repository, using image references in manifests and pipeline definitions as the source. The output is a signed-off inventory with one row per repository and one owner per consumer, which becomes the work list for every later step.
Install and harden Harbor
The platform team deploys Harbor in the client's own infrastructure using the installer or the Helm chart, following the prerequisites in the Harbor documentation. Add the --with-trivy option at install time if image vulnerability scanning is wanted, and confirm the chosen database and cache versions against the release notes for the Harbor version being installed. Configure TLS, LDAP or OIDC sign-in, and backups before any data moves. The output is a reachable Harbor instance with a tested backup and restore, and a documented admin runbook.
Pilot one project with replication and a proxy cache
Choose one low-risk application team and create a Harbor project for it. Add a replication endpoint that points at the Nexus Docker registry, then create a pull-based replication rule filtered to the pilot repositories, and run it manually first. Create one proxy cache project for a public upstream that the pilot team uses, and confirm that Harbor serves the cached copy. Check that tags, digests and the pilot team's role mappings behave as expected. The output is a written pilot report listing what copied, what failed and what needed a manual fix.
Run Nexus and Harbor in parallel
Both registries serve pulls while the teams move their CI pipelines to push to Harbor. Replication rules keep the Harbor copies current for repositories still written through Nexus, and the team reviews replication failures on a fixed schedule. Each consuming team moves its pipelines to Harbor project paths in its own change, with a rollback to the previous push target documented. Tell consumers in advance which image paths change and which remain available. The output is a tracked list of pipelines and clusters, each marked as pushing to Harbor, pulling from Harbor or still pending.
Cut over image references in clusters
Owners update image references in Deployments, Helm values, GitOps repositories and build templates to the Harbor host and project paths, one application group at a time. Verify that each workload pulls its image from Harbor after rollout, and confirm that pull secrets, image pull policies and the Helm chart location point at Harbor. Helm charts stored in Nexus need to be pushed to Harbor as OCI artifacts before their references change. The output is a cluster-wide check showing no running workload still references the Nexus Docker endpoint.
Hold a rollback window and decommission Nexus
After the last cutover, Nexus stays read-only for a rollback window agreed in the migration plan, and its Docker repositories remain available for emergency pulls. The team confirms that no new traffic reaches the Nexus Docker endpoint, takes a final backup of the Nexus data, and archives the inventory and audit logs. Only then does the team remove the Docker repositories and retire the Nexus instance. The output is a decommission record that names the backup location, the date of retirement and the owner who signed it off.
How replication and proxy cache projects replace Nexus proxy repositories
In Harbor, the counterpart to a Nexus Docker proxy repository is a proxy cache project. You create one per upstream registry, such as Docker Hub, and point cluster image references at the Harbor project path instead of the public registry. Harbor's documentation lists Docker Hub, Harbor, generic Docker registries, AWS ECR, Azure ACR, Google GCR, Quay, GitHub Container Registry and JFrog Artifactory as cacheable upstreams, so confirm your specific upstream appears on that list before you plan the cutover. Each project is read-only for pushes, so teams that pushed internal images into a Nexus proxy path must move those images into a separate hosted project. Cached copies are retained under a default 7-day retention policy, which you should review against how often your clusters pull each image, since an image that ages out is fetched again from upstream.
Two behaviors matter for both resilience and rate limits. If the upstream is unreachable, Harbor serves the cached copy, which keeps node restarts working during an upstream outage, provided the image was already cached. Harbor's documentation also states that its cache checks use HEAD requests, which do not count against the Docker Hub pull rate limits described in Docker's pull usage documentation. Verify this against your Docker Hub account type and your Harbor version, and test a pull after the cache is warm to confirm the count stays flat.
Images you build or receive from another registry are moved with replication rules rather than proxy projects. A rule can be push-based 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, with an optional bandwidth limit. Before you build a rule, create a replication endpoint for each source and confirm in the Harbor endpoint documentation that your registry type is supported as a source or destination, because the supported list differs from the proxy cache list. Record the rule names and schedules in your migration runbook so the cutover team knows which images are copied and when.
What drives migration cost and duration
This table lists the factors that set the effort of moving Nexus Docker repositories to Harbor and the costs that continue after cutover. Use it to build the questions you put to any implementation partner, and note that no duration or price is implied here.
| Driver or cost | Why it matters | One-time or recurring |
|---|---|---|
| Repository and tag count | Each hosted and proxy repository needs a Harbor project or proxy cache project, and each tag needs an explicit replication decision, so inventory size sets the work. | One-time |
| Total image size and bandwidth | Large image sets take longer to replicate, and any per-task bandwidth limit on replication rules extends the copy window. Ask how the plan throttles transfers during business hours. | One-time |
| Replication rule design | Rules can filter by name, tag, label and resource type and run on push, pull, cron or manual triggers. More filters and more trigger types mean more rules to write and test. | One-time |
| Clusters and CI pipelines with hard-coded references | Every manifest, Helm values file and pipeline that names the old Nexus host needs an updated image reference, and each cluster rollout needs its own verification. | One-time |
| LDAP group complexity | Nested or overlapping Nexus privileges must map onto Harbor project roles and LDAP or OIDC groups, and the mapping needs review with each identity owner. | One-time, then ongoing when groups change |
| Harbor high availability design | Choosing between the harbor-helm chart and the installer, plus external PostgreSQL, Valkey and shared storage, drives both build effort and run cost. Confirm the target topology in writing. | One-time build, recurring operation |
| Validation and testing | Pull tests from every cluster, scan results, signature checks, rollback drills and audit log review each take effort before Nexus is retired. | One-time |
| Harbor upgrades and scanner updates | Harbor patch and minor releases, bundled database changes and Trivy database updates need a planned window and a tested backup each time. | Recurring |
| Storage and backup | Registry blob storage grows with retained tags and garbage collection schedules. Backup of the registry and its database is a continuing cost. | Recurring |
| Support and retainer | Ongoing support, upgrades and continuous testing can be bought as a retainer, which is priced separately from the fixed-scope migration. Ask which parts are covered. | Recurring |
What usually goes wrong when moving Nexus Docker repositories
Most Nexus-to-Harbor problems come from the cutover itself rather than from Harbor. Clients keep pointing at old endpoints, copies drift from their sources, and access rules do not map cleanly, so each risk below needs a named check before the move.
Missed consumers still pulling from Nexus
Build agents, cluster manifests, Helm values and nightly jobs often hold Nexus hostnames that nobody lists in the migration plan. When Nexus is switched off or its repositories are cleaned up, those consumers fail at the worst time. Before cutover, search Git repositories, cluster manifests and CI variables for the Nexus registry hostname, and run a period where both registries answer so each consumer can be found in access logs.
Tag drift between source and copies
A replicated or re-pushed image is only identical to its source if the tag was not moved afterward. Mutable tags such as latest or stable can point at different digests in Nexus and Harbor, and a rebuild during the migration window makes the difference invisible. Compare digests rather than tag names for critical images, and pin workloads to digests once the copy is verified.
Rate limits hit during proxy warm-up
A new Harbor proxy cache project starts empty, so the first pulls of every base image go upstream. If Harbor is configured against Docker Hub without authentication, a busy cluster can exhaust the anonymous pull limit quickly. Harbor's proxy cache checks cached images with HEAD requests that do not count against that limit, so the risk sits in the first pull of each image. Warm the most-used images in advance and confirm which upstream credentials the proxy project uses.
Role and LDAP mismatches locking out pipelines
Nexus privileges, repository roles and LDAP groups rarely map one to one onto Harbor projects and roles. A CI service account that could push to a Nexus hosted repository may hold only a pull role in Harbor, and the pipeline fails with an authorization error that looks like a network fault. Export the current Nexus role grants, list each service account, and test a push and a pull with every account against a non-production Harbor project before cutover.
Harbor v2.15.3 breaking changes
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. Either change can break a pipeline that worked on an earlier Harbor release, and the failure may appear only after the upgrade. Read the release notes for each version you target, and test webhook receivers and signing steps in a staging instance that matches production settings.
Skipping the backup before the PostgreSQL 18 upgrade
Harbor v2.15.2 upgrades the bundled internal database from PostgreSQL 15 to PostgreSQL 18 on container startup and replaces Redis with Valkey. The release notes recommend a backup before upgrading and a reindexdb run if index problems appear. Teams that upgrade a running instance without a verified database dump and a copy of the storage backend have no clean rollback path, so take and test both backups before any Harbor upgrade.
How the migration changes by estate size and starting point
A small team with one Kubernetes cluster usually has a short list of images, a handful of hosted repositories and one or two proxy repositories. The work is mostly sequential: install Harbor, create projects, move the images that the cluster actually pulls, and then switch the cluster's image references. Because there is one consumer, the cutover can be planned around a single deployment window.
- Inventory first: List the images the cluster pulls, grouped by Nexus repository, and drop anything that is no longer deployed.
- Build the projects: Create one Harbor project per team or application group, with RBAC roles that match the existing Nexus privileges.
- Replicate or push: Pull hosted images through a replication rule or push them directly, then confirm tags and digests match.
- Switch references: Update the image fields in manifests or Helm values and roll the deployments once per release.
- Retire Nexus later: Keep the Nexus Docker repositories read-only for a rollback window before decommissioning them.
Before cutover, confirm with your platform team that the nodes can resolve the Harbor hostname and trust its certificate, since a missing trust chain is the most common cause of failed pulls on a fresh registry.
An estate with several clusters, or workloads in more than one cloud, has more consumers and more Docker Hub dependency. Pulls from Docker Hub often run through the Nexus proxy, so the migration has to rebuild that path as a Harbor proxy cache project before any cluster is switched. The sequence changes from a single cutover to a staged rollout, one environment at a time, with the old and new paths running in parallel.
- Map upstreams first: Record which Nexus proxy repositories point at Docker Hub and which point at other registries, because each one becomes a separate proxy cache project.
- Stage the caches: Create proxy cache projects in Harbor for each upstream and watch the cache hit pattern before moving production workloads.
- Plan replication for hosted content: Use push or pull replication rules, filtered by repository name or tag, to sync images that must exist in more than one location.
- Roll environment by environment: Move a non-production cluster, then a production cluster, and keep the Nexus path available until each one is verified.
- Coordinate with pipelines: Update build and deploy pipelines so new images push to Harbor while older tags stay available until no deployment references them.
Confirm which clusters and CI runners share credentials with Nexus, because each shared account must be re-issued in Harbor and any rate limits on the upstream side should be understood before large pulls start.
In an air-gapped network, images cannot be pulled from Docker Hub or Nexus over the internet at migration time. Skopeo is the usual tool for moving images across the boundary: it copies images between registries without requiring privileges and can export them to a local directory, which is then transported in and pushed into an internal Harbor instance. The sequence is therefore driven by transfer media and approval steps rather than by cluster changes.
- Export on the connected side: Use Skopeo to copy the required images from Nexus or the upstream registry to a local directory, keeping a manifest of each image and tag.
- Verify before transfer: Record digests for every exported image so the receiving side can confirm nothing changed in transit.
- Import into Harbor: Push the images from the local directory into Harbor projects inside the isolated network, then check that tags and digests match the manifest.
- Mirror Helm charts: Charts stored as OCI artifacts move the same way, so include them in the export list rather than treating them as a separate process.
- Set up updates: Agree on how new images cross the boundary in future, because a one-time import leaves the environment unable to receive security fixes.
Confirm with your security and change-control owners how transfer media is approved and logged, and check the Harbor version supported in your environment against the installation prerequisites before the first import.
Questions teams ask before moving Docker images from Nexus to Harbor
What drives the cost of moving Docker images from Nexus to Harbor?
The cost comes from people and infrastructure, not from a license fee for Harbor, which is Apache-2.0 licensed. The main components are the planning and inventory work, the Harbor installation and configuration, the replication and proxy cache setup, the client and cluster changes, testing, and the ongoing operation of the registry. Harbor's own infrastructure includes compute, PostgreSQL, Redis-compatible caching and storage for image layers, and these recur every month. Costs rise with the number of repositories, the volume of image data, the number of clusters pulling images, and the number of role and LDAP group mappings to rebuild. Ask any provider for a fixed-scope quote that lists each of these components separately, and confirm which parts are one-time and which are recurring.
How long does a Nexus to Harbor Docker migration take?
The timeline depends on how many Docker hosted and proxy repositories exist, how much image data must move, and how many clusters and pipelines reference them. No duration is set by this page, so ask for the timeline in the written scope rather than relying on a general figure. The biggest variables are the inventory of tags that must be kept, the time to replicate large repositories over the network or through a bandwidth-limited task, and the number of image references that must change in manifests, Helm values and CI configuration. Teams often run both registries in parallel while clusters switch over, which extends the calendar but reduces risk.
What does the migration need from our own engineering team?
Your team needs to provide access and decisions that only your organization can make. Expect to supply the Nexus inventory and access, the identity source for LDAP or OIDC, the list of projects and the people who should own each one, the clusters and CI systems that pull images, and a change window for updating image references. Platform engineers should review how Harbor is installed, including whether Trivy scanning is enabled at install time with the --with-trivy option. Security teams should confirm the role model and scanning policy before cutover. The more of these inputs are ready at kickoff, the less time the engagement spends waiting.
Can our team migrate Nexus Docker repositories to Harbor without outside help?
Yes, a team with container registry and Kubernetes experience can do this internally, because Harbor is open source and its documentation covers replication endpoints, replication rules and proxy cache projects. The work that most often causes trouble is less about the tooling and more about the details: matching roles and LDAP groups, re-creating proxy repositories with the right upstreams, confirming that clients can authenticate, and finding every place an image reference is hard-coded. DeployOpen plans, implements, integrates and documents self-hosted platforms in your own infrastructure, and most engagements are fixed-scope with the scope agreed in writing before work starts. Whichever path you choose, confirm who owns upgrades and backups after go-live.
Do Maven and npm packages have to move at the same time as Docker images?
No, Docker images and Helm charts can move on their own schedule. Harbor is a registry for container images and Helm charts, and it does not serve Maven or npm packages, so those repositories need a separate home. Pulp is the option this group points to for multi-format packages such as Maven, npm, Python, RPM and Debian. Keeping the two moves separate lets each team cut over at its own pace, but you should confirm that the Nexus repositories for other formats remain available until their own migration is complete, and that any shared credentials or LDAP mappings still work during the transition.
How does rollback work if the Harbor cutover fails?
The safest rollback keeps Nexus running and unchanged until Harbor has served production pulls successfully. Because replication copies images rather than moving them, the original Nexus repositories stay in place during the transition, and clusters can be pointed back by reverting the image references in manifests, Helm values or pipeline variables. Take a backup of the Harbor database before any upgrade, since release notes for recent Harbor versions recommend this. Before cutover, write a rollback runbook that names the reference change to revert, the owner who approves it and the test that confirms the old path works again.
Can Harbor fully replace Nexus Docker repositories?
Harbor covers the Docker and OCI side of Nexus well: hosted repositories become Harbor projects, Docker Hub and other upstreams become proxy cache projects, and the Harbor REST API and replication handle movement between registries. Confirm these gaps before deciding: Harbor's proxy cache does not cover every upstream type that Nexus proxies, the mapping of Nexus privileges to Harbor roles needs review, and any Nexus-specific scripts, webhooks or cleanup tasks must be rewritten. Also confirm the list of Harbor's supported upstream endpoints against your current proxy list, since Nexus may proxy formats that Harbor does not handle.
How do we update image references in our clusters after the move?
Image references must change from the Nexus host to the Harbor host, usually in Kubernetes manifests, Helm values, Kustomize overlays and CI pipeline definitions. Start by searching your Git repositories and cluster configuration for the Nexus hostname, then group the changes by application so each team can test its own workloads. Where a proxy cache project is used, the internal reference can stay stable while the upstream changes behind it, which reduces the number of edits. Confirm with your platform team whether image pull secrets, certificates and network policies also need updates, and roll changes out namespace by namespace.
How DeployOpen scopes and runs a Nexus to Harbor migration
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including Harbor. For a Nexus Docker migration, we start with a written scope that maps each hosted and proxy repository to a Harbor project or proxy cache project, then build and test the target in your environment before any client changes.
How we scope
- Inventory every Nexus Docker hosted and proxy repository, with its tags, consumers and upstream sources
- Agree in writing which images replicate, which become proxy cache projects and which are retired
- Map Nexus roles and LDAP groups to Harbor project roles and confirm the identity source with your directory team
- Engagements are fixed-scope, with deliverables and timelines agreed before work starts
How we build
- Install Harbor in your cloud account, data center or air-gapped network and configure storage, TLS and backups
- Configure replication endpoints and rules, filtering by repository name, tag and resource type, with a bandwidth limit if needed
- Test pulls, pushes and scans against representative images, including Trivy scanning and a rehearsed rollback
- Update Kubernetes manifests, Helm values and CI pipelines to new image references in controlled batches
How we hand over
- Document the Harbor architecture, project and role model, replication rules and proxy cache retention settings
- Provide runbooks for upgrades, garbage collection, backup restores and reindexing after database upgrades
- Deliver a cutover checklist listing every changed image reference and the owner who verified it
- Walk your platform and security teams through operations and record open items for your own follow-up
How we support
- Ongoing support, upgrades and continuous security testing are available as retainers after handover
- Patch and upgrade planning follows Harbor's release notes, including breaking changes in each release line
- Security testing of the registry, its APIs and its integrations can be scoped separately
- Confirm support terms, response expectations and included services in the written scope before signing
