Mirror, Mirror: Using Harbor’s Image Replication to Reduce Pull Latency Across Regions

Why Replicate Images? The Concrete Problem

When a Kubernetes cluster in a remote region pulls a container image, the request has to travel over the public internet to the registry that hosts the image. If that registry is in a different geographic location, latency spikes and bandwidth costs rise. For high‑availability or multi‑region deployments, this can become a bottleneck.

Harbor’s image replication feature solves this by automatically mirroring images from a source registry to a target registry. The target registry can be in the same data center, a different region, or even a cloud provider’s dedicated registry. Once replicated, any cluster that points to the target registry can pull the image locally, cutting latency and eliminating cross‑regional traffic.

Thesis: Replication Is a One‑Way, Low‑Touch Setup with Clear Trade‑Offs

In Harbor 2.5 and later, replication can be configured either via the web UI or the REST API. The UI is ideal for ad‑hoc setups, while the API is useful for automation or when the UI is unavailable. Replication is one‑way by default, which keeps conflict risk low. Two‑way replication is available but requires careful tag management.

Setting Up a One‑Way Replication

Prerequisites

• Harbor source instance (admin access) – https://source.example.com
• Harbor target instance (admin access) – https://target.example.com
• Harbor API tokens with admin scope on both instances
• Docker CLI installed on the machine that will push the test image
• curl and jq for API calls

Step 1 – Push a Test Image to the Source

docker login https://source.example.com -u admin -p <SOURCE_PASSWORD>
# Build a tiny image for demonstration
printf 'FROM alpine\nCMD ["echo", "Hello World"]' > Dockerfile

docker build -t source.example.com/testapp:1.0 .

docker push source.example.com/testapp:1.0

After the push, the image appears in the testapp project on the source Harbor.

Step 2 – Create a Replication Task via the API

Using the source Harbor’s API, create a replication rule that points to the target instance. The following JSON payload configures a one‑way replication for all tags in the testapp project.

cat > replication.json <<EOF
{
  "source": {
    "type": "harbor",
    "url": "https://source.example.com",
    "project": "testapp",
    "type": "harbor"
  },
  "targets": [
    {
      "type": "harbor",
      "url": "https://target.example.com",
      "project": "testapp",
      "type": "harbor"
    }
  ],
  "filters": {
    "type": "all"
  },
  "schedule": {
    "type": "manual"
  }
}
EOF

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SOURCE_API_TOKEN>" \
  -d @replication.json \
  https://source.example.com/api/v2.0/replications

Replace <SOURCE_API_TOKEN> with a real token. The API returns a replication ID; note it for later checks.

Step 3 – Verify Replication Status

Replication runs asynchronously. Query the status until it reports Succeeded:

curl -H "Authorization: Bearer <SOURCE_API_TOKEN>" \
  https://source.example.com/api/v2.0/replications
  | jq ".[] | select(.id==<REPLICATION_ID>) | .status"

When the status is Succeeded, the image should now exist in the target Harbor.

Step 4 – Pull the Image from the Target

docker login https://target.example.com -u admin -p <TARGET_PASSWORD>

docker pull target.example.com/testapp:1.0

Running a pod in a remote cluster that pulls target.example.com/testapp:1.0 will now use the local copy and avoid cross‑regional traffic.

Trade‑Offs and Limitations

Bandwidth and Storage Costs

Each replication copies the full image layers. If you replicate many large images or use frequent updates, network bandwidth and storage consumption can add up quickly. Plan capacity and consider throttling replication schedules.

Conflict Risk in Two‑Way Replication

Two‑way replication synchronizes tags in both directions. If a tag is updated on both sides before the next sync, a conflict arises and the replication engine resolves it by keeping the most recent version. For critical workloads, one‑way replication is safer.

Older Harbor Versions

Harbor releases before 2.5 lack the UI wizard for replication. In those cases you must use the API, as illustrated above. Also, the API endpoints may differ slightly; consult the version’s documentation.

Actionable Checklist

1. Confirm Harbor ≥2.5 on both source and target.
2. Generate admin‑level API tokens on both instances.
3. Push a test image to the source and note its project/tag.
4. Create a replication rule via UI or API.
5. Monitor the replication status until Succeeded.
6. Verify the image exists in the target Harbor.
7. Test a pull from a remote cluster to ensure local delivery.
8. Schedule regular replication or adjust filters to control bandwidth.
9. Document the replication ID for future audit and troubleshooting.

Following these steps gives you a reliable, low‑touch way to keep images available close to your workloads, while keeping an eye on the cost and conflict implications.