Skip to content

Migration Guide#

This guide describes the migration from MSR 2.9, MSR 2.10, and MSR 3.1 to MSR 4 for registry administrators. In both supported migration paths, you install MSR 4 as a new deployment and copy data to it from your existing registry, which remains active until you cut over.

Before You Begin#

MSR 4 is based on CNCF Harbor and differs from MSR 2 and MSR 3 in its architecture, authentication methods, and feature set. Certain differences, including the removal of SAML support and the transition to OCI-based Helm charts, can require changes to your environment before you migrate. Therefore, review MSR 4 Changes before you choose a migration path.

Choose a Migration Path#

The two migration paths differ in the scope of data that they transfer and in the setup that they require.

Manual migration

  • Transfers repository data only, including repositories, images, and tags.
  • Requires no additional tooling, which keeps the setup simple.
  • Requires you to recreate permissions and mirroring policies in MSR 4.
  • Can be time-consuming and error-prone in large deployments because you recreate access controls manually.

Tool-based migration

  • Transfers repositories, permissions, and push and poll mirroring policies using the Mirantis migration tool.
  • Automates the migration, which reduces manual effort.
  • Transfers metadata through offline copies.
  • Improves consistency in large or complex environments.
  • Requires the installation and configuration of the tool on a host that has network access to both registries.

For small environments or migrations of limited scope, perform the manual migration. For large environments, or for deployments that must preserve permissions and mirroring policies, perform the tool-based migration.

  • Manual Migration

    Transfers repository data without additional tooling. Recommended for small environments or migrations of limited scope.

    Manual Migration

  • Tool-Based Migration

    Transfers repositories, permissions, and mirroring policies using the migration tool. Recommended for large or complex environments.

    Tool Migration