From dca81d8bf66212f977650ccf41b14b67b2acccf0 Mon Sep 17 00:00:00 2001 From: Evan Read Date: Wed, 27 Aug 2025 14:29:24 +1000 Subject: [PATCH 1/2] Refactor Helm chart upgrade documentation --- doc/charts/globals.md | 3 +- doc/installation/database_upgrade.md | 2 +- doc/installation/upgrade.md | 177 +++++---------------------- doc/installation/version_mappings.md | 26 +--- doc/releases/6_0.md | 87 ++----------- doc/releases/7_0.md | 102 ++------------- doc/releases/_index.md | 16 +++ doc/troubleshooting/_index.md | 38 ------ 8 files changed, 69 insertions(+), 382 deletions(-) create mode 100644 doc/releases/_index.md diff --git a/doc/charts/globals.md b/doc/charts/globals.md index cd62cdc6d8..3af0f532d5 100644 --- a/doc/charts/globals.md +++ b/doc/charts/globals.md @@ -194,8 +194,7 @@ The default logic (when `global.ingress.useNewIngressForCerts` is `false`) reuse validation. This default is not suitable in some situations. Setting the flag to `true` will mean that a new Ingress object is created for each validation. -`global.ingress.useNewIngressForCerts` cannot be set to `true` when used with GKE Ingress Controllers. For full details -on enabling this, see [release notes](../releases/7_0.md#bundled-certmanager). +`global.ingress.useNewIngressForCerts` cannot be set to `true` when used with GKE Ingress Controllers. ## GitLab Version diff --git a/doc/installation/database_upgrade.md b/doc/installation/database_upgrade.md index af3aeb16e5..0954c68219 100644 --- a/doc/installation/database_upgrade.md +++ b/doc/installation/database_upgrade.md @@ -93,7 +93,7 @@ kubectl delete pvc data-RELEASE_NAME-postgresql-0 ### Upgrade GitLab -Upgrade GitLab following our [standard procedure](upgrade.md#steps), with the following additions of: +Upgrade GitLab following our [standard procedure](upgrade.md), with the following additions of: Disable migrations using the following flag on your upgrade command: diff --git a/doc/installation/upgrade.md b/doc/installation/upgrade.md index 1ef2fe4159..ba6695ecae 100644 --- a/doc/installation/upgrade.md +++ b/doc/installation/upgrade.md @@ -2,7 +2,7 @@ stage: GitLab Delivery group: Operate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments -title: Upgrade Helm chart installations +title: Upgrade cloud-native GitLab instances --- {{< details >}} @@ -12,63 +12,46 @@ title: Upgrade Helm chart installations {{< /details >}} -Upgrade a Helm chart installation to a later version of GitLab. +Upgrade a cloud-native GitLab instance to a later version of GitLab. -Before upgrading your GitLab installation, you need to check the -[changelog](https://gitlab.com/gitlab-org/charts/gitlab/blob/master/CHANGELOG.md) -corresponding to the specific release you want to upgrade to and look for any -[release notes](version_mappings.md#upgrade-notes-for-each-supported-version) that might pertain to the new GitLab chart -version. - -Upgrades have to follow a supported [upgrade path](https://docs.gitlab.com/update/#upgrade-paths). -Because the GitLab chart versions don't follow the same numbering as GitLab versions, -see the [version mappings](version_mappings.md) between them. +Upgrades must follow a supported [upgrade path](https://docs.gitlab.com/update/upgrade_paths/). Because GitLab Helm +chart versions don't follow the same numbering as GitLab versions, see the [version mappings](version_mappings.md) +between them. {{< alert type="note" >}} -**Zero-downtime upgrades** are not available with the GitLab charts but can be achieved by using [GitLab Operator](https://docs.gitlab.com/operator/gitlab_upgrades/). +**Zero-downtime upgrades** are only available for cloud-native GitLab instances by using +[GitLab Operator](https://docs.gitlab.com/operator/gitlab_upgrades/). {{< /alert >}} -We also recommend that you take a [backup](../backup-restore/_index.md) 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 `. If you direct this into a file -(`helm get values > 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` +## Prerequistes -## Steps - -{{< alert type="note" >}} - -If you're upgrading to the `7.0` version of the chart, follow the [manual upgrade steps for 7.0](#upgrade-to-version-70). -If you're upgrading to the `6.0` version of the chart, follow the [manual upgrade steps for 6.0](#upgrade-to-version-60). -If you're upgrading to an older version of the chart, follow the [upgrade steps for older versions](#older-upgrade-instructions). - -{{< /alert >}} +Before upgrading a cloud-native GitLab instance: -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: +- Check the [CHANGELOG](https://gitlab.com/gitlab-org/charts/gitlab/blob/master/CHANGELOG.md) corresponding to the + specific release you want to upgrade to. +- Look for any [upgrade notes](https://docs.gitlab.com/update/versions/) for the GitLab Helm chart version you're + upgrading to. +- If you're upgrading from versions of the GitLab Helm chart version earlier than 8.x, see the + [GitLab documentation archives](https://docs.gitlab.com/archives/) to access older versions of the documentation. +- Take a [backup](../backup-restore/_index.md). -- Copying computed settings -- Copying all settings and explicitly defining values that are actually the same as the default values +## Upgrade a cloud-native GitLab instance -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. +To upgrade a cloud-native GitLab instance: -The following are the steps to upgrade GitLab to a newer version: - -1. Check the [change log](https://gitlab.com/gitlab-org/charts/gitlab/blob/master/CHANGELOG.md) for the specific version you would like to upgrade to. -1. Go through the [deployment documentation](deployment.md) step by step. +1. Follow the [deployment documentation](deployment.md) step by step. 1. Extract your previously provided values: ```shell helm get values gitlab > gitlab.yaml ``` -1. 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. -1. Perform the upgrade, with values extracted in the previous step: +1. Decide on all the values you need to carry through as you upgrade. You should only keep a minimal set of values that + you want to explicitly set and pass those during the upgrade process. You should otherwise rely on GitLab default + values. +1. Perform the upgrade, with values extracted and reviewed in previous steps: ```shell helm upgrade gitlab gitlab/gitlab \ @@ -78,116 +61,18 @@ The following are the steps to upgrade GitLab to a newer version: --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 - -{{< alert type="note" >}} - -If you aren't using the bundled PostgreSQL chart (`postgresql.install` is false), you do not need to -perform this step. - -{{< /alert >}} + During a major database upgrade, you should set `gitlab.migrations.enabled` to `false`. + Ensure that you explicitly set it back to `true` for future updates. -### Upgrade the bundled PostgreSQL to version 13 +## Upgrade the bundled PostgreSQL -PostgreSQL 13 is supported by GitLab 14.1 and later. [PostgreSQL 13 brings significant performance improvements](https://www.postgresql.org/about/news/postgresql-13-released-2077/). +Only perform these steps if you are using the bundled PostgreSQL chart (`postgresql.install` is `true`). -To upgrade the bundled PostgreSQL to version 13, the following steps are required: +To upgrade the bundled PostgreSQL: +1. Decide [which version of PostgreSQL](https://docs.gitlab.com/install/requirements/#postgresql) to upgrade to. 1. [Prepare the existing database](database_upgrade.md#prepare-the-existing-database). 1. [Delete existing PostgreSQL data](database_upgrade.md#delete-existing-postgresql-data). -1. Update the `postgresql.image.tag` value to `13.6.0` and [reinstall the chart](database_upgrade.md#upgrade-gitlab) to create a new PostgreSQL 13 database. +1. Update the `postgresql.image.tag` value to the required version of PostgreSQL and + [reinstall the chart](database_upgrade.md#upgrade-gitlab) to create a new PostgreSQL database. 1. [Restore the database](database_upgrade.md#restore-the-database). - -## Upgrade to version 7.0 - -{{< alert type="warning" >}} - -If you are upgrading from the `6.x` version of the chart to the latest `7.0` release, you need -to first update to the latest `6.11.x` patch release in order for the upgrade to work. -The [7.0 release notes](../releases/7_0.md) describe the supported upgrade path. - -{{< /alert >}} - -The `7.0.x` release may require manual steps in order to perform the upgrade. - -- If using the bundled [`bitnami/Redis`](https://artifacthub.io/packages/helm/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](#update-the-bundled-redis-sub-chart) below. - -### Update the bundled Redis sub-chart - -Release 7.0 of the GitLab chart updates the bundled [`bitnami/Redis`](https://artifacthub.io/packages/helm/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: - -```shell -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: - - ```shell - kubectl scale deployment --replicas 0 --selector 'app in (webservice, sidekiq, kas, gitlab-exporter)' --namespace - ``` - -1. Delete the `RELEASE-redis-master` StatefulSet: - - ```shell - kubectl delete statefulset RELEASE-redis-master --namespace - ``` - - - `` should be replaced with the namespace where you installed the GitLab chart. - -Then follow the [standard upgrade steps](#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`: - -```plaintext -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 - -{{< alert type="warning" >}} - -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](../releases/6_0.md) describe the supported upgrade path. - -{{< /alert >}} - -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](#steps). - -## Older upgrade instructions - -If you're upgrading from versions of GitLab chart older than 5.x, see the -[GitLab Docs archives](https://docs.gitlab.com/archives/) to access older versions of the documentation. diff --git a/doc/installation/version_mappings.md b/doc/installation/version_mappings.md index c053fe7bab..b540c8aca4 100644 --- a/doc/installation/version_mappings.md +++ b/doc/installation/version_mappings.md @@ -15,28 +15,17 @@ title: GitLab Helm chart versions The GitLab Helm chart doesn't have the same version number as GitLab itself. This means that breaking changes can be introduced to the chart independent of GitLab. -To quickly see the full list of the `gitlab` chart versions and the GitLab version -they map to, run the following command with [Helm](tools.md): +To see the full list of the `gitlab` chart versions and the GitLab version they map to, run the following +command with [Helm](tools.md): ```shell helm repo add gitlab https://charts.gitlab.io/ helm search repo -l gitlab/gitlab ``` -## Upgrade notes for each supported version +## GitLab chart version mappings -Upgrade notes for each supported version of the GitLab Helm chart are available: - -- [9.0](../releases/9_0.md) -- [8.0](../releases/8_0.md) -- [7.0](../releases/7_0.md) -- [6.0](../releases/6_0.md) - -See also the project's [CHANGELOG](https://gitlab.com/gitlab-org/charts/gitlab/blob/master/CHANGELOG.md). - -## Previous chart versions - -The table below maps some of the key previous supported chart versions and supported GitLab versions. +The table below maps supported GitLab Helm chart versions to supported GitLab versions. | Chart version | GitLab version | |---------------|----------------| @@ -393,10 +382,3 @@ The table below maps some of the key previous supported chart versions and suppo | 6.0.2 | 15.0.2 | | 6.0.1 | 15.0.1 | | 6.0.0 | 15.0.0 | - -To see the full list, you can issue the following command with Helm: - -```shell -helm repo add gitlab https://charts.gitlab.io/ -helm search repo -l gitlab/gitlab -``` diff --git a/doc/releases/6_0.md b/doc/releases/6_0.md index f9f5e2620c..b42904b522 100644 --- a/doc/releases/6_0.md +++ b/doc/releases/6_0.md @@ -1,84 +1,13 @@ --- -stage: GitLab Delivery -group: Operate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments -title: GitLab Helm chart 6.0 upgrade notes +redirect_to: '_index.md' +remove_date: '2025-12-29' --- -With the `15.0` release of GitLab, we have released version `6.0` of the GitLab Helm chart. + -## Summary of major changes +This document was moved to [another location](_index.md). -- The recommended PostgreSQL database is [upgraded to 13](#postgresql). -- The default list of allowed ciphers for NGINX Ingress has been changed to - [remove weak ciphers](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/2578). - This might break some AWS deployments. See [issue #3317](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/3317) - for more information. - -## Upgrade path from 5.x - -In order to upgrade to the `6.0` version of the chart, you first need to upgrade to the latest `5.10.x` -release of the chart. Check the [version mapping details](../installation/version_mappings.md) for the latest patch. - -If you don't first upgrade to the latest `5.10.x` patch, you will see the following error from `helm upgrade`: - -```shell -Error: UPGRADE FAILED: Job failed: BackoffLimitExceeded -``` - -You can then confirm you are in this situation by looking for pods in error with the text `gitlab-upgrade-check` in the name. - -If you check the logs for those pods will see the version upgrade error message: - -```plaintext -It seems you are upgrading the GitLab Helm chart from X (GitLab X) to 6.0.0 (GitLab 15.0.0). -It is required to upgrade to the latest 5.10.x version first before proceeding. -Please follow the upgrade documentation at https://docs.gitlab.com/charts/releases/6_0.html -and upgrade to GitLab Helm chart version 5.10.x before upgrading to 6.0.0. -``` - -## Upgrade from 5.10.x - -Please follow the [normal upgrade steps](../installation/upgrade.md). - -## Major Changes - -### PostgreSQL - -PostgreSQL 13 is the recommended version, but PostgreSQL 12.x is still -supported. - -{{< alert type="note" >}} - -Although it is not required for this major release, you should -start planning for an upgrade to PostgreSQL 13. - -{{< /alert >}} - -## Release cadence - -We will be releasing a new version of the chart with each new GitLab patch. - -More information on how we are versioning the chart can be found in the [release documentation](../development/release.md). - -Along with the issues and merge requests in this repository, a [changelog](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/CHANGELOG.md) is available to more easily follow along with updates. - -## Kubernetes deployment support - -GitLab is tested against: - -- [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine) -- [Amazon EKS](https://aws.amazon.com/eks/) - -Other Kubernetes deployments should also work. In the event of a specific non-GKE deployment issue, please raise an issue. - -This release has automated CI testing for Kubernetes version `1.21.10-gke.2000` and `v1.19.16-eks-25803e`. - -## Technical support - -Before opening an issue, please [search existing issues](https://gitlab.com/gitlab-org/charts/gitlab/-/issues) to see if a similar issue already exists. - -We greatly appreciate the wider testing of the community, and encourage creating new issues so we can address them. - -We welcome any improvements contributed in the form of [Merge Requests](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests). -Get started with our [contributor documentation](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/CONTRIBUTING.md). + + + + diff --git a/doc/releases/7_0.md b/doc/releases/7_0.md index fd9577b4ad..b42904b522 100644 --- a/doc/releases/7_0.md +++ b/doc/releases/7_0.md @@ -1,99 +1,13 @@ --- -stage: GitLab Delivery -group: Operate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#designated-technical-writers -title: GitLab Helm chart 7.0 upgrade notes +redirect_to: '_index.md' +remove_date: '2025-12-29' --- -With the `16.0` release of GitLab, we have released version `7.0` of the GitLab Helm chart. + -## Summary of major changes +This document was moved to [another location](_index.md). -- The recommended PostgreSQL database is [upgraded to 14.8](#postgresql). -- The bundled certmanager chart is [upgraded from 1.5.4 to 1.11.1](#bundled-certmanager). - -## Upgrade path from 6.x - -In order to upgrade to the `7.0` version of the chart, you first need to upgrade to the latest `6.11.x` -release of the chart. Check the [version mapping details](../installation/version_mappings.md) for the latest patch. - -GitLab now defaults to using two database connections. Prior to upgrading, you can check that PostgreSQL `max_connections` is -high enough (using more than 50% of the available max connections). -You can verify this by running the following Rake task using [the Toolbox container](../charts/gitlab/toolbox/_index.md#toolbox-included-tools): - -```shell -gitlab-rake gitlab:db:decomposition:connection_status -``` - -If the task indicates that `max_connections` is high enough, then you can -proceed with the upgrade. If not, or you wish to remain on single -connection, you can set the `ci.enabled` key to `false` prior to the upgrade. - -## Upgrade from 6.11.x - -Please follow the [upgrade steps for 7.0 release](../installation/upgrade.md#upgrade-to-version-70). - -## Major Changes - -### PostgreSQL - -As part of the `7.0.0` release of this chart, we upgraded the default PostgreSQL version from `12.7` to `14.8`. This -is done by upgrading [PostgreSQL chart](https://github.com/bitnami/charts/tree/main/bitnami/postgresql) version from -`8.9.4` to `12.5.2`. - -This is not a drop in replacement. Manual steps need to be performed to upgrade the database. The steps have been -documented in the [upgrade steps](../installation/database_upgrade.md#steps-for-upgrading-the-bundled-postgresql). - -{{< alert type="note" >}} - -Note that PostgreSQL 13 is the minimum required PostgreSQL version in GitLab 16.0. PostgreSQL 12 is no longer -supported by GitLab 16.0 and later. - -{{< /alert >}} - -### Bundled certmanager - -The bundled certmanager chart is upgraded from 1.5.4 to 1.11.1. Depending on your cluster and tooling this -may require manual interaction before upgrading. - -Make sure your cluster version is supported by certmanager 1.11. The release supports Kubernetes 1.21 to -1.26 and OpenShift 4.8 to 4.13. See [certmanager supported releases](https://cert-manager.io/docs/releases/) -for more information. - -The default certmanager configuration now uses the `acme.cert-manager.io/http01-edit-in-place` annotation. -As a result, certmanager will use the existing Ingresses to complete ACME challenges instead of creating -new ones. This change ensures compatibility with Ingress controllers that need the `ingressClassName` to be set. - -OpenShift users may have to modify the Security Context Constraints to deploy certmanager 1.10+. -See [certmanager 1.10 release notes](https://cert-manager.io/docs/releases/release-notes/release-notes-1.10/#on-openshift-the-cert-manager-pods-may-fail-until-you-modify-security-context-constraints) -for more information. - -In case you deploy any certmanager custom resources not managed by the GitLab chart, or use additional -scripts or tooling related to cert-manager, please read through the potentially breaking changes of -[certmanager 1.6 to 1.11](https://cert-manager.io/docs/releases/) before upgrading. - -#### Disable in-place Ingress modification - -Sometimes the logic of reusing existing Ingresses for validation is not suitable. For example, if you -have IP allowlists or other restrictions on your Ingresses that makes them inaccessible to the public -Internet. - -To perform the ACME challenge validation with an Ingress created dynamically each time, from `7.7.0` you can -set the `global.issuer.useNewIngressForCerts` value to `true` (defaults to `false`). - -Setting `useNewIngressForCerts` to `true` requires the `ingressClassName` field to be supported by the -Ingress controller. This field has been available from Kubernetes 1.18, but is not supported on all controllers, -for example it is not yet available when using -[GKE Ingress](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress#deprecated_annotation). - -In case you need to enable this field during an upgrade on an existing cluster running GitLab charts `7.0-7.6`, -please follow the [upgrade instructions](../installation/upgrade.md#usenewingressforcerts-on-ingresses) - -### Redis - -The included [`bitnami/Redis`](https://artifacthub.io/packages/helm/bitnami/redis) -sub-chart has been updated to version `16.13.2` from the previously installed -`11.3.4`. This also upgrades Redis from `6.0.9` to `6.2.7`. - -Manual steps are required prior to upgrading if using the bundled Redis. -See [Upgrade the bundled Redis sub-chart](../installation/upgrade.md#update-the-bundled-redis-sub-chart) + + + + diff --git a/doc/releases/_index.md b/doc/releases/_index.md new file mode 100644 index 0000000000..9c9b439c35 --- /dev/null +++ b/doc/releases/_index.md @@ -0,0 +1,16 @@ +--- +stage: GitLab Delivery +group: Operate +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#designated-technical-writers +title: GitLab Helm chart upgrade notes +--- + +Upgrade notes for recent GitLab Helm chart versions. For upgrade notes for older versions, see the +[GitLab documentation archives](https://archives.docs.gitlab.com). + +{{< cards >}} + +- [GitLab Helm chart 9.0 upgrade notes](9_0.md) +- [GitLab Helm chart 8.0 upgrade notes](8_0.md) + +{{< /cards >}} diff --git a/doc/troubleshooting/_index.md b/doc/troubleshooting/_index.md index b53e37b5fa..2d3a617f57 100644 --- a/doc/troubleshooting/_index.md +++ b/doc/troubleshooting/_index.md @@ -5,44 +5,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w title: Troubleshooting the GitLab chart --- -## UPGRADE FAILED: Job failed: BackoffLimitExceeded - -If you received this error when [upgrading to the 6.0 version of the chart](../releases/6_0.md#upgrade-path-from-5x), -then it's probably because you didn't follow the right upgrade path, as you first need to upgrade to the latest 5.10.x version: - -1. List all your releases to identify your GitLab Helm release name (you will need to include `-n ` if your release was not deployed to the `default` K8s namespace): - - ```shell - helm ls - ``` - -1. Assuming that your GitLab Helm release is called `gitlab` you then need to look at the release history and identify the last successful revision (you can see the status of a revision under `DESCRIPTION`): - - ```shell - helm history gitlab - ``` - -1. Assuming your most recent successful revision is `1` use this command to roll back: - - ```shell - helm rollback gitlab 1 - ``` - -1. Re-run the upgrade command by replacing `` with the appropriate chart version: - - ```shell - helm upgrade --version=5.10. - ``` - -1. At this point you can use the `--version` option to pass a specific 6.x.x chart version or remove the option for upgrading to the latest version of GitLab: - - ```shell - helm upgrade --install gitlab gitlab/gitlab - ``` - -More information about command line arguments can be found in our [Deploy using Helm](../installation/deployment.md#deploy-using-helm) section. -For mappings between chart versions and GitLab versions, read [GitLab version mappings](../installation/version_mappings.md). - ## UPGRADE FAILED: "$name" has no deployed releases This error occurs on your second install/upgrade if your initial install failed. -- GitLab From 532ac9bf0a7bf8c00670e53b0b8a26f50f40afe3 Mon Sep 17 00:00:00 2001 From: Evan Read Date: Mon, 29 Sep 2025 16:24:20 +1000 Subject: [PATCH 2/2] Call out Helm chart as the installation method To disambiguate from cloud-native instances that were installed with GitLab Operator. --- doc/installation/upgrade.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/installation/upgrade.md b/doc/installation/upgrade.md index ba6695ecae..d17bace8bf 100644 --- a/doc/installation/upgrade.md +++ b/doc/installation/upgrade.md @@ -2,7 +2,7 @@ stage: GitLab Delivery group: Operate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments -title: Upgrade cloud-native GitLab instances +title: Upgrade GitLab Helm chart instances --- {{< details >}} @@ -12,7 +12,7 @@ title: Upgrade cloud-native GitLab instances {{< /details >}} -Upgrade a cloud-native GitLab instance to a later version of GitLab. +Upgrade a GitLab Helm chart instance to a later version of GitLab. Upgrades must follow a supported [upgrade path](https://docs.gitlab.com/update/upgrade_paths/). Because GitLab Helm chart versions don't follow the same numbering as GitLab versions, see the [version mappings](version_mappings.md) @@ -25,9 +25,9 @@ between them. {{< /alert >}} -## Prerequistes +## Prerequisites -Before upgrading a cloud-native GitLab instance: +Before upgrading a GitLab Helm chart instance: - Check the [CHANGELOG](https://gitlab.com/gitlab-org/charts/gitlab/blob/master/CHANGELOG.md) corresponding to the specific release you want to upgrade to. @@ -37,9 +37,9 @@ Before upgrading a cloud-native GitLab instance: [GitLab documentation archives](https://docs.gitlab.com/archives/) to access older versions of the documentation. - Take a [backup](../backup-restore/_index.md). -## Upgrade a cloud-native GitLab instance +## Upgrade a GitLab Helm chart instance -To upgrade a cloud-native GitLab instance: +To upgrade a GitLab Helm chart instance: 1. Follow the [deployment documentation](deployment.md) step by step. 1. Extract your previously provided values: -- GitLab