Replicating Harbor Images Across Regions: A Practical Guide

Why Replication Matters

In a multi‑region deployment, keeping container images close to your workloads reduces latency, avoids cross‑border data transfer, and strengthens disaster‑resiliency. Manually pushing the same image to every Harbor instance is error‑prone and hard to audit. Harbor’s built‑in image replication solves this by automatically mirroring repositories from one Harbor instance to another.

What Harbor Replication Does

Replication is a pull‑based sync: a source Harbor pushes a copy of an image to a target Harbor whenever a new image is pushed or when a policy is triggered. The process is managed by Harbor’s internal registry API, so you don’t need to run extra services. Replication policies can filter by tag, digest, or custom rules, and can run on a schedule or on demand.

Setting Up a One‑to‑One Replication Policy

Below is a step‑by‑step example that mirrors the my‑app repository from harbor‑us.example.com to harbor‑eu.example.com. The example uses the Harbor UI; the same steps can be performed via the REST API.

1. Prepare the target registry
   • Ensure harbor‑eu.example.com is reachable from the source (port 5000 or 443 if TLS is enabled).
   • Generate a Harbor user with the Replication role and note the username/password.
2. In the source Harbor UI
   1. Navigate to Administration → Replication.
   2. Click Create Policy.
      • Policy name: US‑to‑EU‑my‑app
      • Source registry: harbor‑us.example.com (auto‑selected)
      • Target registry: harbor‑eu.example.com
      • Repository: my‑app
      • Replication type: One‑to‑one
      • Trigger: On push (or set a cron schedule)
      • Tag filter: .* (replicate all tags)
   3. Click Save.
3. Trigger the policy manually (optional)
   • In the policy list, click Run Now next to the new policy.
   • Check the status column; it should transition from Idle to Running to Success.
4. Verify on the target
   • Log into harbor‑eu.example.com and navigate to the my‑app repository.
   • Pull the image locally: docker pull harbor-eu.example.com/my-app:latest
   • Inspect the digest: docker image inspect harbor-eu.example.com/my-app:latest | grep Digest and compare with the source.

REST API Alternative

For automation, the following cURL snippet creates the same policy:

curl -k -u admin:Harbor123! \
  -H "Content-Type: application/json" \
  -X POST https://harbor-us.example.com/api/v2.0/replications \
  -d '{
  "name": "US-to-EU-my-app",
  "source": {"registry": "harbor-us.example.com"},
  "targets": [{"registry": "harbor-eu.example.com"}],
  "repository": "my-app",
  "replication_type": "one_to_one",
  "trigger": {"type": "on_push"},
  "tag_filter": ".*"
}'

Replace admin:Harbor123! with a user that has the Replication role on both registries.

Trade‑Offs and Limitations

• Bandwidth and Cost: Replication copies the entire image each time a new tag is pushed. Large images or frequent pushes can consume significant bandwidth, especially across wide‑area networks. Plan for network capacity or use a tag_filter to limit replication.
• Lag: Replication is asynchronous. A push to the source may take seconds to minutes before the target shows the new image, depending on network latency and image size.
• Credentials Management: Each target registry requires a separate credential set. Store these securely (e.g., in a secrets manager) and rotate them periodically.
• Metadata Not Replicated: Replication syncs only image layers and tags. Harbor project settings, vulnerability reports, and user permissions are not mirrored. Use a separate backup strategy for full cluster state.
• Policy Scope: New projects are not automatically covered. Either enable Replicate all projects in the policy or create per‑project policies.

Next Steps

1. Plan a replication matrix: list all source and target Harbor instances and decide on one‑to‑one or one‑to‑many relationships.
2. Define tag filters that match your release strategy (e.g., ^v[0-9]+\.[0-9]+\.[0-9]+$ for semantic versions).
3. Automate policy creation with the REST API in your CI/CD pipeline.
4. Set up monitoring: use Harbor’s Replication tab or query /api/v2.0/replications/{id}/logs to alert on failures.
5. Complement replication with a full backup of Harbor’s database and configuration for disaster recovery.

By configuring replication once, you gain a reliable, auditable path for distributing container images across regions without manual intervention. Start with a small test repository, validate the flow, and then scale to your production workloads.