Skip to content

Differences Between MSR versions#

MSR 4 is based on CNCF Harbor, which brings increased stability, an expanded feature set, and a broader ecosystem of integrations. However, some functional changes may require you to adjust authentication, promotion workflows, and backup strategies. Review the changes on this section before you plan your migration.

API#

API and webhook behavior have been updated to reflect Harbor’s implementation. These changes support better compatibility with ecosystem tools and simplify DevOps automation.

Architecture#

MSR 4 introduces a Harbor-based architecture that is more scalable and easier to operate than the MSR 2 and MSR 3 design. Legacy components such as RethinkDB and embedded services have been removed or refactored, improving performance and simplifying upgrades.

Artifact Management and CI/CD Pipelines#

Helm Support

Helm chart support in MSR 4 is now OCI-compliant. Charts are stored and managed as OCI artifacts rather than through a dedicated Helm repository. To manage them, use OCI commands:

helm push <CHART>.tgz oci://<MSR-HOST>/<PROJECT>
helm pull oci://<MSR-HOST>/<PROJECT>/<CHART> --version <VERSION>

Note

The helm search repo command is no longer supported. Instead, use the MSR web console to browse charts.

This change improves compatibility with OCI tooling but may require minor adjustments to traditional Helm workflows.

Promotion Policies

If you use promotion policies, reproduce the same workflows in your CI/CD pipelines.

Authentication and Access Control#

OpenID Connect (OIDC) Authentication

MSR 4 replaces legacy SAML support with OpenID Connect (OIDC). OIDC is more suitable for modern applications due to its lightweight protocol, better mobile and microservices compatibility, and broader support across enterprise Identity Providers (IdPs) such as Microsoft Entra ID, Okta, Google Identity Platform, Amazon Cognito, Ping Identity, IBM Security Verify, OneLogin, and VMware Workspace ONE.

Organizations that use SAML must configure an IdP that supports SAML-to-OIDC bridging, for example, Okta, Keycloak, or Azure AD.

Role-Based Access Control (RBAC)

MSR 4 removes the legacy Teams and Enzi components. You must now add users manually to projects to configure access. Group-based access is supported only through AD Groups, which requires integration with LDAP/AD and OIDC.

For configuration, refer to Authentication Configuration.

Database#

MSR 4 replaces the legacy RethinkDB backend with PostgreSQL, an industry-standard relational database known for stability and scalability. This transition improves data consistency, query performance, and operational resilience in high-demand environments. PostgreSQL also simplifies administrative tasks and aligns MSR 4 with enterprise database best practices.

Deployment and Infrastructure Support#

Backup and Disaster Recovery

MSR 2 and MSR 3 included built-in backup capabilities. MSR 4 requires external backup management using Velero, an open-source tool widely used in enterprise Kubernetes environments. Velero supports backup and restore, but it requires a Kubernetes-based deployment. For more information, refer to Backup Guide.

Swarm Support and HA

MSR 4 does not support Swarm. You can deploy MSR 4 as a single-node instance using Docker Compose. High availability (HA) requires Kubernetes.

Image Signing#

MSR 4 replaces Docker Content Trust (DCT) and Notary v1 with Cosign and Notation (Notary v2).

Job Runner for Background Task Execution#

The MSR 4 job runner, inherited from Harbor’s job service, provides a modernized mechanism for executing background tasks such as garbage collection, replication, scanning, and retention.

Compared to MSR 2, the new job runner supports distributed execution, automatic retry policies, improved error reporting, and detailed job history. These features improve observability and reliability for registry operations.

Migration#

MSR supports a mirroring-based migration from MSR 2 and MSR 3.

The migration tool copies permissions, roles, Helm charts, and push and poll mirroring policies. After that initial migration, with those policies in place, images and tags continue to replicate without further use of the tool. MSR 2 or MSR 3 can remain active alongside MSR 4 until you cut over.

Manual migration copies repositories, images, and tags only. Recreate permissions and mirroring policies in MSR 4.

See What to Expect During the Migration and Choose a Migration Path.

Quota Management#

MSR 4 introduces project-level quotas.

Replication Targets#

MSR 4 extends support for replicating images and artifacts to and from OCI-compatible registries.

Repository Naming#

MSR 4 supports repository path lengths up to 256 characters. This support enables deeper project namespaces and more descriptive naming, which are common in enterprise CI/CD pipelines.