• Steps
• Upgrade the bundled PostgreSQL chart
  • Upgrade the bundled PostgreSQL to version 13
• Upgrade to version 7.0
  • Update the bundled Redis sub-chart
  • Use of global.redis.password
  • useNewIngressForCerts on Ingresses
• Upgrade to version 6.0
• Older upgrade instructions

Upgrade the GitLab chart

Before upgrading your GitLab installation, you need to check the changelog corresponding to the specific release you want to upgrade to and look for any release notes that might pertain to the new GitLab chart version.

Upgrades have to follow a supported upgrade path. Because the GitLab chart versions don’t follow the same numbering as GitLab versions, see the version mappings between them.

We also recommend that you take a backup first. Also note that you must provide all values using helm upgrade --set key=value syntax or -f values.yaml instead of using --reuse-values, because some of the current values might be deprecated.

You can retrieve your previous --set arguments cleanly, with helm get values <release name>. If you direct this into a file (helm get values <release name> > gitlab.yaml), you can safely pass this file via -f. Thus helm upgrade gitlab gitlab/gitlab -f gitlab.yaml. This safely replaces the behavior of --reuse-values

Steps

Before you upgrade, reflect on your set values and if you’ve possibly “over-configured” your settings. We expect you to maintain a small list of modified values, and leverage most of the chart defaults. If you’ve explicitly set a large number of settings by:

• Copying computed settings
• Copying all settings and explicitly defining values that are actually the same as the default values

This will almost certainly cause issues during the upgrade as the configuration structure could have changed across versions, and that will cause problems applying the settings. We cover how to check this in the following steps.

The following are the steps to upgrade GitLab to a newer version:

1. Check the change log for the specific version you would like to upgrade to.
2. Go through the deployment documentation step by step.

3. Extract your previously provided values:

   helm get values gitlab > gitlab.yaml
   

4. Decide on all the values you need to carry through as you upgrade. GitLab has reasonable default values, and while upgrading, you can attempt to pass in all values from the above command, but it could create a scenario where a configuration has changed across chart versions and it might not map cleanly. We advise keeping a minimal set of values that you want to explicitly set, and passing those during the upgrade process.

5. Perform the upgrade, with values extracted in the previous step:

   helm upgrade gitlab gitlab/gitlab \
     --version <new version> \
     -f gitlab.yaml \
     --set gitlab.migrations.enabled=true \
     --set ...
   

During a major database upgrade, we ask you to set gitlab.migrations.enabled set to false. Ensure that you explicitly set it back to true for future updates.

Upgrade the bundled PostgreSQL chart

Upgrade the bundled PostgreSQL to version 13

PostgreSQL 13 is supported by GitLab 14.1 and later. PostgreSQL 13 brings significant performance improvements.

To upgrade the bundled PostgreSQL to version 13, the following steps are required:

1. Prepare the existing database.
2. Delete existing PostgreSQL data.
3. Update the postgresql.image.tag value to 13.6.0 and reinstall the chart to create a new PostgreSQL 13 database.
4. Restore the database.

Upgrade to version 7.0

The 7.0.x release may require manual steps in order to perform the upgrade.

• If using the bundled bitnami/Redis sub-chart to provide an in-cluster Redis service - you’ll need to manually delete the StatefulSet for Redis prior to upgrading to version 7.0 of the GitLab chart. Follow the setups in Upgrade the bundled Redis sub-chart below.

Update the bundled Redis sub-chart

Release 7.0 of the GitLab chart updates the bundled bitnami/Redis sub-chart to version 16.13.2 from the previously installed 11.3.4. Due to changes in matchLabels applied to the redis-master StatefulSet in the sub-chart, upgrading without manually deleting the StatefulSet will result in the following error:

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

To delete the StatefulSet for RELEASE-redis-master:

1. Scale down the replicas to 0 for the webservice, sidekiq, kas, and gitlab-exporter deployments:

   kubectl scale deployment --replicas 0 --selector 'app in (webservice, sidekiq, kas, gitlab-exporter)' --namespace <namespace>
   

2. Delete the RELEASE-redis-master StatefulSet:

   kubectl delete statefulset RELEASE-redis-master --namespace <namespace>
   

   • <namespace> should be replaced with the namespace where you installed the GitLab chart.

Then follow the standard upgrade steps. Due to how Helm merges changes, you may need to scale up the deployments you scaled down in step one manually.

Use of global.redis.password

In order to mitigate a configuration type conflict with the use of global.redis.password we’ve deprecated the use of global.redis.password in favor of global.redis.auth.

In addition to displaying a deprecation notice - if you see the following warning message from helm upgrade:

coalesce.go:199: warning: destination for password is a table. Ignoring non-table value

This is an indication that you are setting global.redis.password in your values file.

useNewIngressForCerts on Ingresses

If you are upgrading an existing chart from 7.x to a later version, and are changing global.ingress.useNewIngressForCerts to true, you must also update any existing cert-manager Certificate objects to delete the acme.cert-manager.io/http01-override-ingress-name annotation.

You must make this change because with this attribute set to false (default), this annotation is added by default to the Certificates, and cert-manager uses it to identify which Ingress method to use for that certificate. The annotation is not automatically removed by only changing this attribute to false. A manual action is needed otherwise cert-manager keeps using the old behavior for pre-existing Ingresses.

Upgrade to version 6.0

To upgrade to the 6.0 release you must first be on the latest 5.10.x patch release. There isn’t any additional manual changes required in 6.0 so you can follow the regular release upgrade steps.

Older upgrade instructions

If you’re upgrading from versions of GitLab chart older than 5.x, see the GitLab Docs archives to access older versions of the documentation.