Objective

An OVHcloud Managed Private Registry (MPR) is hosted in a single region. In a 3-AZ region, the service is distributed across several Availability Zones, but your data never leaves that region.

If you need a copy of your artifacts in another region, you can use Harbor's built-in replication feature between two MPRs. Common use cases include:

• keeping a secondary registry ready in another region as part of a disaster recovery plan.
• pulling images from a registry located close to your Managed Kubernetes clusters in each region.
• promoting artifacts from one environment to another (for example, from a staging registry to a production registry).

Replication copies container images, OCI artifacts (including Helm charts stored as OCI artifacts) and the artifacts attached to them, such as signatures, SBOMs and attestations (see Signatures, SBOMs and other attached artifacts). Configuring and operating it is your responsibility (see the responsibility model).

This guide explains how to set up a replication rule between two OVHcloud Managed Private Registries located in different regions.

Requirements

• Two OVHcloud Managed Private Registries located in two different regions. In this guide, they are called the source registry and the destination registry.
• An account with system administrator privileges on the Harbor user interface of both registries.

Instructions

This guide uses push-based replication: the replication rule is created on the source registry, which pushes artifacts to the destination registry. Push-based replication is the only mode that supports the Event Based trigger, which replicates each new artifact as soon as it is pushed.

If you prefer to create the rule on the destination registry, for example to move your artifacts to a new registry in another region, see Using pull-based replication.

Step 1: Preparing the destination registry

1. Log in to the Harbor user interface of the destination registry.
2. Create the project that will receive the replicated artifacts. See Managing users and projects for details.
3. Create a robot account that the source registry will use to push artifacts:
   • Open the project, go to the Robot Accounts tab and click + New Robot Account.
   • Enter a name and an expiration time.
   • Grant at least the Push and Pull permissions on Repository.
   • Click Finish, then copy the robot account name (for example robot$my-project+replication) and its secret.

Step 2: Creating a replication endpoint on the source registry

1. Log in to the Harbor user interface of the source registry.
2. Go to Administration, then Registries.
3. Click + New Endpoint and fill in the details:
   • Provider: Harbor
   • Name: a name for the endpoint (for example mpr-destination)
   • Description: optional
   • Endpoint URL: the URL of the destination registry (for example https://xxxxxxxx.c1.de1.container-registry.ovh.net)
   • Access ID: the full name of the robot account created in step 1 (for example robot$my-project+replication)
   • Access Secret: the secret of the robot account
   • Verify Remote Cert: leave it ticked
4. Click Test Connection. Once the test succeeds, click OK.

Step 3: Creating a replication rule

1. On the source registry, go to Administration, then Replications.
2. Click + New Replication Rule and fill in the details:
   • Name and Description: a name for the rule and an optional description.
   • Replication mode: Push-based.
   • Source resource filter: the artifacts to replicate. Leave the fields empty to replicate everything.
     • Name: a repository name or pattern (for example my-project/**).
     • Tag: a tag or pattern, which you can set to match or exclude (for example v* to replicate only release tags).
     • Label: one or more existing labels, which you can set to match or exclude.
     • Resource: images only, artifacts only, or all.
   • Destination registry: the endpoint created in step 2.
   • Destination namespace: the destination project (for example my-project). If you leave it empty, artifacts are replicated into a project with the same name as on the source registry.
   • Destination Flattening: how many levels of the repository path are removed. The default value, Flatten 1 Level, turns a/b/c/img into namespace/b/c/img. Select No Flatting to keep the full source path under the destination namespace (a/b/c/img becomes namespace/a/b/c/img).
   • Trigger Mode:
     • Manual: the rule only runs when you start it.
     • Scheduled: the rule runs periodically, based on a cron expression.
     • Event Based: the rule runs each time an artifact is pushed or retagged on the source registry. Tick Delete remote resources when locally deleted to also replicate deletions (the robot account then also needs the Delete permission on Repository).
   • Bandwidth: the maximum bandwidth per replication task, in KB/s. -1 means unlimited.
   • Override: tick it to overwrite artifacts that already exist with the same name on the destination registry.
   • Copy by chunk: tick it to copy layers in chunks of 10 MB, which can help with large images.
   • Single active replication: tick it to skip a new run while a previous run of the same rule is still in progress.
3. Click Save.

The Name and Tag filters support the following patterns:

For example, library/* matches library/nginx but not library/tools/nginx, while library/** matches both.

Step 4: Running and monitoring the replication

1. On the source registry, go to Administration, then Replications.
2. Select the rule and click Replicate to start an initial replication. This is recommended even with the Event Based trigger, which only applies to artifacts pushed after the rule is created.
3. Click the rule to display its executions, then click an execution ID to see its tasks. Each replicated artifact is a separate task.
4. Click the log icon of a task to see its details. You can also click STOP to stop an execution.

Failed tasks are automatically retried several times. You cannot edit or delete a rule while one of its executions is in progress.

Step 5: Checking the result on the destination registry

1. Log in to the Harbor user interface of the destination registry and open the destination project. The replicated repositories and tags are listed there.

2. Pull an image from the destination registry to check that it can be used:

   docker login <destination-registry-url>
   docker pull <destination-registry-url>/<project>/<image>:<tag>

To use the destination registry from a Managed Kubernetes cluster, see Using Private Registry with OVHcloud Managed Kubernetes.

Using pull-based replication

With pull-based replication, the rule is created on the destination registry, which pulls artifacts from the source registry. The source registry only needs a robot account with read access.

This mode is well suited to moving your artifacts to a new registry in another region: you configure everything on the new registry and change nothing on the registry you are leaving, apart from the robot account.

Pull-based replication does not support the Event Based trigger: use Manual or Scheduled instead.

Step 1: Creating a read-only robot account on the source registry

1. Log in to the Harbor user interface of the source registry.
2. Create a robot account with the Read permission on Project, the List and Read permissions on Artifact and the List and Pull permissions on Repository:
   • for a single project: open the project, go to the Robot Accounts tab and click + New Robot Account.
   • for several projects: go to Administration, then Robot Accounts, click + New Robot Account and select the projects to cover, or tick Cover all projects.
3. Click Finish, then copy the robot account name and its secret.

Step 2: Creating a replication endpoint on the destination registry

1. Log in to the Harbor user interface of the destination registry.
2. Go to Administration, then Registries, and click + New Endpoint.
3. Fill in the details as described in step 2 above, with the URL of the source registry in Endpoint URL and the robot account created in step 1 in Access ID and Access Secret.
4. Click Test Connection. Once the test succeeds, click OK.

Step 3: Creating the replication rule on the destination registry

1. On the destination registry, go to Administration, then Replications, and click + New Replication Rule.
2. Fill in the details:
   • Replication mode: Pull-based.
   • Source registry: the endpoint created in step 2.
   • Source resource filter: the artifacts to replicate, with the same filters and patterns as for push-based replication. Leave the fields empty to replicate all the artifacts the robot account can read.
   • Destination namespace: leave it empty to replicate each project into a project with the same name, which is created automatically if needed.
   • Destination Flattening: select No Flatting to keep the same repository paths as on the source registry.
   • Trigger Mode: Manual or Scheduled.
   • The other options (Bandwidth, Override, Copy by chunk, Single active replication) work as described in step 3 above.
3. Click Save.

Step 4: Running the replication and checking the result

Run and monitor the rule from the destination registry, as described in step 4, then check the result as described in step 5.

Signatures, SBOMs and other attached artifacts

Harbor replicates each artifact together with the artifacts attached to it, called accessories. They are replicated whenever their parent artifact is, even if they have no tag of their own:

• Cosign signatures, in both formats: the tag-based format of Cosign v2 (sha256-<digest>.sig) and the OCI 1.1 format used by default by Cosign v3.
• Notation signatures.
• any artifact attached with the OCI 1.1 subject field, such as SBOMs, provenance attestations or VEX documents (for example, pushed with oras attach or cosign attest).
• SBOMs generated by Harbor.

Attestations added by BuildKit (docker buildx build --sbom --provenance) are stored inside the image index: they are copied with the image.

Vulnerability scan results

Scan results are stored in the database of each registry and are not replicated. To get them on the destination registry, which needs an M or L plan to include a vulnerability scanner, enable Automatically scan images on push in the Configuration tab of the destination project before running the replication: replicated artifacts are then scanned as soon as they arrive. You can also start a scan manually afterwards. See Scanning Docker images for vulnerabilities.

Projects created automatically by the replication use the default settings, in which automatic scanning is disabled: create the destination projects beforehand to configure it.

What is not replicated

Replication only copies artifacts, their signatures and the other artifacts attached to them. The following elements are specific to each registry and must be configured separately on the destination registry:

• project members and their roles.
• vulnerability scan results (see Vulnerability scan results).
• users, robot accounts and their secrets.
• authentication settings (OVHcloud IAM or OIDC provider) and IP restrictions.
• project settings, such as quotas, retention and immutability rules, vulnerability scanning policies and webhooks.

Replicated artifacts use storage on both registries: check that the plan of the destination registry offers enough capacity.

Go further

Harbor documentation: Configuring Replication

Sign OCI artifacts with Cosign

Configuring Proxy Cache on an OVHcloud Managed Private Registry

Join our community of users.