Migration to MSR 4

This guide provides detailed instructions for migrating artifacts from Mirantis Secure Registry (MSR) versions 2 and 3 to MSR4. The transition process ensures a seamless migration of stored artifacts while maintaining data integrity and minimizing downtime.

With the transition to MSR4, the underlying code base has changed. Review What’s New to understand any changes in Mirantis Secure Registry behavior.

If you are using custom repository permissions, custom image signing, or Swarm review Removed features and What to expect when transitioning to MSR4 carefully. If you have any questions, contact support for further guidance.

Environment Prerequisites

  • Ensure you have administrative access to both the source (MSR2 and MSR3) and target (MSR 4) environments.

  • Confirm adequate storage capacity on the target system to accommodate migrated artifacts.

  • Verify network connectivity between source and target systems.

  • Backup existing data on MSR 2/3 to prevent data loss.

How to Migrate to an MSR4 environment

To migrate images, repos, tags, and labels from a MSR2 or MSR3 environment to an MSR4 environment:

  1. In harbor you will need to do two things. First add a registry, then add a replicator. To add a registry go to Administration → Registries → then select “New Endpoint”

    _images/add-registry.png

  2. Under Provider select DTR. Give it a name. Then for the end point URL use the root of the registry. Later this will allow us to crawl the entire host. Do not use a user or repos namespace. Then add the username and password with admin access under Access ID and Access Secret.

    _images/add-username-password.png

  3. Now we need to setup a replication rule under Administration → Replications. Select “Pull Based”. Under Source registry you should see the MSR2 and MSR3 host which was added in the previous steps.

    1. Under Source Resource Filter ensure its ** and leave everything else blank. Also ensure the flattening is at flattening 1 level.

    2. There are other flattening options for customers who might be using the orgs name space option in MSR2 and MSR3.

      _images/edit-replication-rule.png

    Note

    There is the ability to flatten or NOT flatten any type of org/namespace. If you look at the flattening option this will flatten everything into a single namespace. For customers who use a more flexible namespace or org please review the following for the flattening options.

    _images/customize-name-space.png

    Different options on how you can customize the name space.

  4. You should now have a replica which we can replicate. Select the rule then the replicate button. You should see below under the Executions panel the job running When pulling down an entire host it will be a time consuming process.

    _images/replications.png

  5. If you want to check the status of the process. Click on the job ID and you will have a job browser window come up which you can review the status of the job.

    _images/check-status.png

Configuration and Environment Migration Considerations

Configuration Migration

When upgrading to MSR4, customers must manually update some of their settings. Below are key aspects to consider:

Repository and Access Control

  • Project Permissions: Harbor organizes repositories within projects. Customers must ensure that project-level permissions are properly recreated.

  • For more information please refer to Managing Project Permissions.

Replication Rules

  • Registry Replication: If MSR was using replication or mirroring between registries, these rules and schedules need to be re-established in Harbor.

  • For more information please refer to Configuring Replication.

Retention Policies

  • Image Tag Retention: Any existing retention policies for images must be manually configured in Harbor to ensure appropriate lifecycle management.

Security and Compliance

  • Scanning Settings: Harbor includes built-in security scanning via Trivy. Customers must configure or re-enable their image vulnerability scanning policies.

  • For more information refer to Vulnerability Scanning.

  • Audit Logs: If customers rely on audit logs or monitoring, they need to set up appropriate logging mechanisms in Harbor for compliance.

Webhooks and CI/CD Integrations

  • Webhooks: Customers who use webhooks for CI/CD integrations must recreate and configure them to point to Harbor.

  • CI/CD Pipelines: Custom CI/CD pipelines will need updates to reference the new Harbor environment.

Notary and Image Signing

  • Signed Images Customers who use image signing will need to configure cosign.

  • For more information please refer to Signing Artifacts with Cosign

Garbage Collection

  • Garbage Collection Settings: Any previously defined garbage collection policies must be manually reconfigured in Harbor.

  • For more information please refer to Managing Garbage Collection

Custom Certificates

  • Certificate Management: If custom certificates were in use, customers must re-establish these configurations in Harbor.

API Integrations

  • API Updates: If automated systems interact with MSR via API, customers must update API endpoints and account for any changes in Harbor’s API.

Environment Configuration

In addition to configuration migration, customers must manually update their infrastructure settings.

  • CICD Pipelines - Customers using custom CICD pipelines will need to update their jobs to leverage the new environments.

  • DNS - Customers using cnames for dns will need to update to the new hosts when completed with the migration.

By following these steps, customers can ensure a seamless migration from MSR to Harbor while maintaining operational consistency and security.