Using Harbor Replication for Multi‑Site Image Sync

The problem: image drift across sites

When the same container workload runs in two data centers, the image stored in each registry can diverge. A push to the primary site may not appear immediately at the secondary, leaving developers with stale images or missing vulnerability scan data. This drift complicates disaster‑recovery drills and makes it hard to guarantee that a pod scheduled in either location runs exactly the same bits.

How Harbor replication works

Harbor includes a built‑in replication engine that copies an image together with its tags, Notary v2 signatures and the latest vulnerability‑scan overview from a source registry to one or more target registries. An administrator defines a replication policy that selects a source project (or specific repository), chooses a destination endpoint, and sets a trigger mode—manual, automatic on each push, or on a schedule. When the trigger fires, Harbor transfers the manifest and all layers, preserving the original digest so the target image is byte‑for‑byte identical to the source.

Worked example: creating an automatic replication policy

1. Log in to the Harbor UI of the primary instance with an account that has System Administrator rights.
2. Navigate to Administration → Replication Policies → New Policy.
3. Enter a name, for example primary‑to‑dr.
4. Under Source, select the project that holds your images (e.g., library) and optionally limit to a specific repository.
5. Under Destination, add the endpoint of the secondary Harbor (e.g., https://harbor-dr.example.com) and provide credentials that have push permission on the target project.
6. Choose Trigger → Automatic so the policy runs after every push to the source.
7. Enable Include Tags and Include Scan Overrides to copy tags and the latest vulnerability‑scan results.
8. Save the policy.
9. Push a new image to the source project, for example:

   docker push harbor-primary.example.com/library/nginx:1.27

10. After the push finishes, open the replication log for the policy (UI: Monitoring → Replication Log) or call the API:

    GET /api/replication/policies/{policy_id}/logs

    Look for an entry with status success and a manifest digest that matches the one you just pushed.
11. To verify that trust and scan data arrived, retrieve the manifest on the target:

    curl -k -H 'Authorization: Bearer ' https://harbor-dr.example.com/v2/library/nginx/manifests/1.27

    Compare the signatures array and the scan_overview field with those returned from the source; identical values indicate faithful replication.

Trade‑offs and limitations

• Replication consumes additional outbound bandwidth equal to the size of the transferred layers. On a congested link this can increase latency for other traffic.
• The first replication of a large image may temporarily spike storage usage on the target node while layers are being written; once the manifest is committed the usage stabilizes.
• If the same image is pushed concurrently to both source and target, Harbor may detect a conflict and require manual resolution or a conflict‑resolution policy.
• Deleted images are not automatically removed from the target unless the target’s garbage collection is disabled; otherwise they linger until the target GC runs.
• Firewall rules must allow TCP 443 (HTTPS) between the Harbor nodes; blocked ports cause silent failures that appear only in the replication log.

Verification and monitoring

After establishing a policy, make it a habit to check the replication lag. The UI shows the time of the last successful sync per policy. Via the API you can query:

GET /api/replication/policies/{policy_id}/status

which returns fields such as last_sync_time and status. A steady increase in the lag value or a series of failed entries signals a network or authentication problem that should be investigated.

For capacity planning, monitor the outbound traffic on the source Harbor node (e.g., with iftop or your network‑monitoring tool) during a known image push and compare it to the baseline. Adjust the replication schedule or enable bandwidth throttling in the policy if the sustained utilization approaches your link’s limit.

Actionable closing

Start with a non‑critical project and a manual trigger to observe the behavior without affecting developers. Once you confirm that images, tags and scan reports appear identical on the secondary, switch the trigger to Automatic or a suitable schedule. Keep an eye on the replication log and API status endpoints, and adjust the policy or network resources as your image traffic grows. This approach gives you a predictable, low‑ops way to keep multi‑site container images in sync while preserving the full metadata Harbor provides.