Upgrade Guide

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.

note
Zero-downtime upgrades are not available with the GitLab charts. Ongoing work to support this feature can be tracked via the GitLab Operator issue.
caution
If you are upgrading from the 5.x version of the chart to the latest 6.0 release, you need to first update to the latest 5.10.x patch release in order for the upgrade to work. The 6.0 release notes describe the supported upgrade path.
caution
If you are upgrading from the 4.x version of the chart to the latest 5.0 release, you need to first update to the latest 4.12.x patch release in order for the upgrade to work. The 5.0 release notes describe the supported upgrade path.

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

Mappings between chart versioning and GitLab versioning can be found here.

Steps

note
If you’re upgrading to the 5.0 version of the chart, follow the manual upgrade steps for 5.0. If you’re upgrading to the 4.0 version of the chart, follow the manual upgrade steps for 4.0. If you’re upgrading to an older version of the chart, follow the upgrade steps for older versions.

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 ...
  6. If you installed the product documentation, see how to upgrade it.

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

note
If you aren’t using the bundled PostgreSQL chart (postgresql.install is false), you do not need to perform this step.

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 the bundled PostgreSQL to version 12

As part of the 5.0.0 release of this chart, we upgraded the bundled PostgreSQL version from 11.9.0 to 12.7.0. This is not a drop in replacement. Manual steps need to be performed to upgrade the database. The steps have been documented in the 5.0 upgrade steps.

Upgrade the bundled PostgreSQL to version 11

As part of the 4.0.0 release of this chart, we upgraded the bundled PostgreSQL chart from 7.7.0 to 8.9.4. This is not a drop in replacement. Manual steps need to be performed to upgrade the database. The steps have been documented in the 4.0 upgrade steps.

Upgrade steps for the 6.0 release

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.

Upgrade steps for 5.9 release

Sidekiq pod never becomes ready

Upgrading to 5.9.x may lead to a situation where the Sidekiq pod does not become ready. The pod starts and appears to work properly but never listens on the 3807, the default metrics endpoint port (metrics.port). As a result, the Sidekiq pod is not considered to be ready.

This can be resolved from the Admin Area:

  1. On the top bar, select Menu > Admin.
  2. On the left sidebar, select Settings > Metrics and profiling.
  3. Expand Metrics - Prometheus.
  4. Ensure that Enable health and performance metrics endpoint is enabled.
  5. Restart the affected pods.

There is additional conversation about this scenario in a closed issue.

Upgrade steps for 5.5 release

The task-runner chart was renamed to toolbox and removed in 5.5.0. As a result, any mention of task-runner in your configuration should be renamed to toolbox. In version 5.5 and newer, use the toolbox chart, and in version 5.4 and older, use the task-runner chart.

Missing object storage secret error

Upgrading to 5.5 or newer might cause an error similar to the following:

Error: UPGRADE FAILED: execution error at (gitlab/charts/gitlab/charts/toolbox/templates/deployment.yaml:227:23): A valid backups.objectStorage.config.secret is needed!

If the secret mentioned in the error already exists and is correct, then this error is likely because there is an object storage configuration value that still references task-runner instead of the new toolbox. Rename task-runner to toolbox in your configuration to fix this.

There is an open issue about clarifying the error message.

Upgrade steps for 5.0 release

The 5.0.0 release requires manual steps in order to perform the upgrade. If you’re using the bundled PostgreSQL, the best way to perform this upgrade is to back up your old database, and restore into a new database instance.

caution
Remember to make a backup before proceeding with the upgrade. Failure to perform these steps as documented may result in the loss of your database. Ensure you have a separate backup.

If you are using an external PostgreSQL database, you should first upgrade the database to version 12 or greater. Then follow the normal upgrade steps.

If you are using the bundled PostgreSQL database, you should follow the bundled database upgrade steps.

Troubleshooting 5.0 release upgrade process

  • If you see any failure during the upgrade, it may be useful to check the description of gitlab-upgrade-check pod for details:

    kubectl get pods -lrelease=RELEASE,app=gitlab
kubectl describe pod <gitlab-upgrade-check-pod-full-name>

Upgrade steps for 4.0 release

The 4.0.0 release requires manual steps in order to perform the upgrade. If you’re using the bundled PostgreSQL, the best way to perform this upgrade is to back up your old database, and restore into a new database instance.

caution
Remember to make a backup before proceeding with the upgrade. Failure to perform these steps as documented may result in the loss of your database. Ensure you have a separate backup.

If you are using an external PostgreSQL database, you should first upgrade the database to version 11 or greater. Then follow the normal upgrade steps.

If you are using the bundled PostgreSQL database, you should follow the bundled database upgrade steps.

Troubleshooting 4.0 release upgrade process

  • If you see any failure during the upgrade, it may be useful to check the description of gitlab-upgrade-check pod for details:

    kubectl get pods -lrelease=RELEASE,app=gitlab
kubectl describe pod <gitlab-upgrade-check-pod-full-name>

4.8: Repository data appears to be lost upgrading Praefect

The Praefect chart is not yet considered suitable for production use.

If you have enabled Praefect before upgrading to version 4.8 of the chart (GitLab 13.8), note that the StatefulSet name for Gitaly will now include the virtual storage name.

In version 4.8 of the Praefect chart, the ability to specify multiple virtual storages was added, making it necessary to change the StatefulSet name.

Any existing Praefect-managed Gitaly StatefulSet names (and, therefore, their associated PersistentVolumeClaims) will change as well, leading to repository data appearing to be lost.

Prior to upgrading, ensure that:

  • All your repositories are in sync across the Gitaly Cluster, and GitLab is not in use during the upgrade. To check whether the repositories are in sync, run the following command in one of your Praefect pods:

    /usr/local/bin/praefect -config /etc/gitaly/config.toml dataloss

  • You have a complete and tested backup.

Repository data can be restored by following the managing persistent volumes documentation, which provides guidance on reconnecting existing PersistentVolumeClaims to previous PersistentVolumes.

A key step of the process is setting the old persistent volumes’ persistentVolumeReclaimPolicy to Retain. If this step is missed, actual data loss will likely occur.

After reviewing the documentation, there is a scripted summary of the procedure in a comment on one of a related issues.

Having reconnected the PersistentVolumes, it is likely that all your repositories will be set read-only by Praefect, as shown by running the following in a Praefect container:

praefect -config /etc/gitaly/config.toml dataloss

If all your Git repositories are in sync across the old persistent volumes, use the accept-dataloss procedure for each repository to fix the Gitaly Cluster in Praefect.

We have an issue open to verify that this is the best approach to fixing Praefect.