Upgrade Harbor to MSR

Overview

Mirantis Secure Registry (MSR) is a Mirantis-maintained distribution of Harbor. MSR 4.13 and Harbor 2.13 use the same underlying database schema. As a result, the upgrade is a Helm chart replacement and does not require data migration or extended downtime.

Prerequisites

• Current version: Harbor 2.13.x installed with Helm.
• Target version: MSR 4.13.x.
• Database: internal or external PostgreSQL.
• Cache: internal or external Redis or Valkey.

Before you begin

Back up the Harbor database

1. Determine the PostgreSQL leader pod:

   kubectl get pods -l application=spilo,spilo-role=master
   

2. Back up the database for your deployment type:

   Zalando Postgres Operator (MSR 4)Internal database (MSR 4)External PostgreSQL

   kubectl exec -it <PostgreSQL leader pod> -- pg_dump -U msr \
     registry > harbor-backup-$(date +%Y%m%d).sql
   

   kubectl exec -it <PostgreSQL leader pod> -- pg_dump -U postgres \
     registry > harbor-backup-$(date +%Y%m%d).sql
   

   kubectl exec -it <PostgreSQL leader pod> -- pg_dump \
     -U <PostgreSQL user> <PostgreSQL DB name> > \
     harbor-backup-$(date +%Y%m%d).sql
   

Back up Harbor

See the Harbor documentation on backup and restore with Velero for information about backing up Harbor components other than the database.

Procedure

1. Pull the default values file from the MSR Helm chart. The file lists the full set of configuration keys available for MSR, which differ slightly from the upstream Harbor chart.

   helm show values oci://registry.mirantis.com/harbor/helm/msr \
     --version 4.13.x > MSR4.13.x-values.yml
   

2. Configure the MSR4.13.x-values.yml file to match your current Harbor configuration. Compare your existing Harbor values against the MSR defaults, and carry over all site-specific settings manually.

   Verify the following fields:

   Setting	Location	What to verify
   externalURL	Top level	Matches the current Harbor external URL exactly
   expose.type	expose	Matches the current expose type (nodePort, ingress, clusterIP, or loadBalancer)
   expose.tls	expose.tls	TLS enabled or disabled state, certSource, and secret names match
   Persistent volume access modes	persistence.persistentVolumeClaim.*	Uses the same accessMode as the existing PVCs (for example, ReadWriteMany)
   Database connection	database	Type (internal or external), host, port, username, password or secret, and SSL mode
   Redis connection	redis	Type (internal or external), address, sentinel settings, and password or secret
   harborAdminPassword	Top level	Matches the existing admin password or existing secret reference
   secretKey	Top level	Identical to the existing 16-character key
   Image repositories	Each component's image.repository	Uses the registry.mirantis.com/harbor/ prefix instead of goharbor/

   Important

   Do not change secretKey. Harbor uses this key to encrypt sensitive data in the database. If the key changes, Harbor cannot decrypt stored credentials and secrets.

3. Delete the existing Trivy StatefulSet before you run the Helm upgrade. The MSR chart changes the volumeClaimTemplates labels on the Trivy StatefulSet, and Kubernetes does not allow patching immutable fields on an existing StatefulSet.

   If you skip this step, the upgrade fails with the following error:

   Error: UPGRADE FAILED: cannot patch "harbor-trivy" with kind
   StatefulSet: StatefulSet.apps "harbor-trivy" is invalid: spec:
   Forbidden: updates to statefulset spec for fields other than
   'replicas', 'ordinals', 'template', 'updateStrategy',
   'revisionHistoryLimit', 'persistentVolumeClaimRetentionPolicy' and
   'minReadySeconds' are forbidden
   

   Delete the StatefulSet with the --cascade=orphan flag. This flag removes the StatefulSet object from Kubernetes but leaves the Trivy pods running, which minimizes scanner downtime during the upgrade.

   kubectl delete statefulset harbor-trivy --cascade=orphan
   

4. Run the Helm upgrade with your configured values file. Do not use --reuse-values. Instead, pass your values explicitly with -f to avoid carrying over stale Harbor values that are incompatible with the MSR chart structure.

   helm upgrade harbor oci://registry.mirantis.com/harbor/helm/msr \
     --version 4.13.x -f MSR4.13.x-values.yml
   

   Helm pulls the MSR chart, applies your values, and rolls out updated pods for all Harbor components.