How to Efficiently Migrate Docker Registry Images to Harbor: 4 Proven Strategies

Registry

Docker Distribution is the first tool that implements packaging, publishing, storage and distribution of images, acting as a Docker registry. It has been donated to CNCF and its spec became the OCI distribution‑spec.

Harbor

Harbor also uses Docker Distribution as its backend storage. Before Harbor 2.0 most image functions were handled by Docker Distribution; since 2.0 Harbor maintains its own OCI artifact metadata in its database, turning Harbor into a cloud‑native artifact repository that supports Helm charts, CNAB, OPA bundles, and more.

Migration Goal

Given an internal network with a Docker registry at registry.k8s.li containing 5,000 images and a newly deployed Harbor at harbor.k8s.li, the article presents four practical migration approaches.

Step 1 – List All Images in the Registry

Before migration obtain a list of all tagged images by traversing the registry storage directory’s current/index files. This method only captures images that have tags.

Step 2 – Create Corresponding Projects in Harbor

Harbor starts with a default library project; you must manually create projects that match the directories under the registry’s repositories path.

Migration Schemes

Scheme 1: Docker retag

Pull each image from the source registry, retag it, and push it to Harbor. Simple but inefficient because Docker decompresses layers during pull‑tag‑push.

Scheme 2: skopeo

Use skopeo copy to transfer images directly between registries without layer decompression, offering better performance. skopeo sync can synchronize whole projects.

Use skopeo copy Use

skopeo sync

Scheme 3: Direct Storage Directory Migration

Because Harbor’s backend also uses Docker Distribution, you can copy the entire storage directory from the source registry to Harbor’s storage directory, then restart Harbor so it rescans the blobs and rebuilds metadata. This works for Harbor 1.x but not for 2.x.

Scheme 4: Adapted Directory Migration for Harbor 2.x

For Harbor 2.x the metadata must be written to Harbor’s database, so the storage‑directory copy alone is insufficient. The recommended approach is to convert the registry’s blobs into a skopeo dir format and then push them with skopeo copy or skopeo sync. The article details how to extract manifests, config and layer files from the registry storage, reconstruct a dir image, and optionally use hard links to reduce I/O.

Comparison

Scheme 1: Low entry cost, suitable for few images, but poor performance.

Scheme 2: Ideal for synchronizing two registries, e.g., copying public images from Docker Hub to an internal registry.

Scheme 3: Best performance for registry‑to‑registry migration, not compatible with Harbor 2.x.

Scheme 4: Compromise for Harbor 2.x, requires re‑pushing images, thus slower than Scheme 3.

References

Harbor Authoritative Guide

Exploring Container Image Life Cycle

Skopeo First Experience

Harbor 2.0 OCI support announcement