summaryrefslogtreecommitdiff
path: root/doc/update
diff options
context:
space:
mode:
Diffstat (limited to 'doc/update')
-rw-r--r--doc/update/deprecations.md125
-rw-r--r--doc/update/index.md171
-rw-r--r--doc/update/package/index.md4
-rw-r--r--doc/update/plan_your_upgrade.md8
-rw-r--r--doc/update/upgrading_from_source.md2
-rw-r--r--doc/update/upgrading_postgresql_using_slony.md6
-rw-r--r--doc/update/zero_downtime.md70
7 files changed, 261 insertions, 125 deletions
diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md
index 42bd41ed74b..8bf14bc2dce 100644
--- a/doc/update/deprecations.md
+++ b/doc/update/deprecations.md
@@ -45,6 +45,7 @@ The Task Runner pod is used to execute periodic housekeeping tasks within the Gi
This will result in the rename of the sub-chart: `gitlab/task-runner` to `gitlab/toolbox`. Resulting pods will be named along the lines of `{{ .Release.Name }}-toolbox`, which will often be `gitlab-toolbox`. They will be locatable with the label `app=toolbox`.
Announced: 2021-08-22
+Planned removal: 2021-11-22
## 14.6
@@ -53,6 +54,7 @@ Announced: 2021-08-22
The [release-cli](https://gitlab.com/gitlab-org/release-cli) will be released as a [generic package](https://gitlab.com/gitlab-org/release-cli/-/packages) starting in GitLab 14.2. We will continue to deploy it as a binary to S3 until GitLab 14.5 and stop distributing it in S3 in GitLab 14.6.
Announced: 2021-08-22
+Planned removal: 2021-12-22
## 14.8
@@ -63,9 +65,19 @@ Distribution support and security updates for openSUSE Leap 15.2 are [ending Dec
Starting in 14.5 we are providing packages for openSUSE Leap 15.3, and will stop providing packages for openSUSE Leap 15.2 in the 14.8 milestone.
Announced: 2021-11-22
+Planned removal: 2022-02-22
## 15.0
+### API: `stale` status returned instead of `offline` or `not_connected`
+
+A breaking change will occur for the Runner [API](https://docs.gitlab.com/ee/api/runners.html#runners-api) endpoints in 15.0.
+
+Instead of the GitLab Runner API endpoints returning `offline` and `not_connected` for runners that have not contacted the GitLab instance in the past three months, the API endpoints will return the `stale` value, which was introduced in 14.6.
+
+Announced: 2021-12-22
+Planned removal: 2022-05-22
+
### Audit events for repository push events
Audit events for [repository events](https://docs.gitlab.com/ee/administration/audit_events.html#repository-push) are now deprecated and will be removed in GitLab 15.0.
@@ -75,6 +87,14 @@ feature flag. Enabling them can cause too many events to be generated which can
dramatically slow down GitLab instances. For this reason, they are being removed.
Announced: 2021-09-22
+Planned removal: 2022-05-22
+
+### CI/CD job name length limit
+
+In GitLab 15.0 we are going to limit the number of characters in CI/CD job names to 255. Any pipeline with job names that exceed the 255 character limit will stop working after the 15.0 release.
+
+Announced: 2021-12-22
+Planned removal: 2022-05-22
### Certificate-based integration with Kubernetes
@@ -89,12 +109,14 @@ For a more robust, secure, forthcoming, and reliable integration with Kubernetes
[Kubernetes Agent](https://docs.gitlab.com/ee/user/clusters/agent/) to connect Kubernetes clusters with GitLab.
Announced: 2021-11-15
+Planned removal: 2022-05-22
### Converting an instance (shared) runner to a project (specific) runner is deprecated
In GitLab 15.0, we will remove the feature that enables you to convert an instance (shared) runner to a project (specific) runner. Users who need to add a runner to only a particular project can register a runner to the project directly.
Announced: 2021-11-22
+Planned removal: 2022-05-22
### Deprecate `Versions` on base `PackageType`
@@ -103,12 +125,51 @@ As part of the work to create a [Package Registry GraphQL API](https://gitlab.co
In milestone 15.0, we will completely remove `Version` from `PackageType`.
Announced: 2021-11-22
+Planned removal: 2022-05-22
+
+### Deprecate `pipelines` fields in the Package GraphQL types
+
+As part of the work to create a [Package Registry GraphQL API](https://gitlab.com/groups/gitlab-org/-/epics/6318), the Package group deprecated the `pipelines` fields in all Package-related GraphQL types. As of GitLab 14.6, the `pipelines` field is deprecated in [`Package`](https://docs.gitlab.com/ee/api/graphql/reference/index.html#package) and [`PackageDetailsType`](https://docs.gitlab.com/ee/api/graphql/reference/index.html#packagedetailstype) due to scalability and performance concerns.
+
+In milestone 15.0, we will completely remove `pipelines` from `Package` and `PackageDetailsType`. You can follow and contribute to work on a replacement in the epic [GitLab-#7214](https://gitlab.com/groups/gitlab-org/-/epics/7214).
+
+Announced: 2021-12-22
+Planned removal: 2022-05-22
+
+### Deprecate legacy approval status names from License Compliance API
+
+We deprecated legacy names for approval status of license policy (blacklisted, approved) in the `managed_licenses` API but they are still used in our API queries and responses. They will be removed in 15.0.
+
+If you are using our License Compliance API you should stop using the `approved` and `blacklisted` query parameters, they are now `allowed` and `denied`. In 15.0 the responses will also stop using `approved` and `blacklisted` so you need to adjust any of your custom tools to use the old and new values so they do not break with the 15.0 release.
+
+Announced: 2021-12-22
+Planned removal: 2022-05-22
### Deprecate support for SLES 12 SP2
Long term service and support (LTSS) for SUSE Linux Enterprise Server (SLES) 12 SP2 [ended on March 31, 2021](https://www.suse.com/lifecycle/). The CA certificates on SP2 include the expired DST root certificate, and it's not getting new CA certificate package updates. We have implemented some [workarounds](https://gitlab.com/gitlab-org/gitlab-omnibus-builder/-/merge_requests/191), but we will not be able to continue to keep the build running properly.
Announced: 2021-11-22
+Planned removal: 2022-05-22
+
+### Deprecation of Runner status `not_connected` API value
+
+The GitLab Runner REST and GraphQL [API](https://docs.gitlab.com/ee/api/runners.html#runners-api) endpoints
+will return `never_contacted` instead of `not_connected` as the status values in 15.0.
+
+Runners that have never contacted the GitLab instance will also return `stale` if created more than 3 months ago.
+
+Announced: 2021-12-22
+Planned removal: 2022-05-22
+
+### Deprecation of bundler-audit Dependency Scanning tool
+
+As of 14.6 bundler-audit is being deprecated from Dependency Scanning. It will continue to be in our CI/CD template while deprecated. We are removing bundler-audit from Dependency Scanning on May 22, 2022 in 15.0. After this removal Ruby scanning functionality will not be affected as it is still being covered by Gemnasium.
+
+If you have explicitly excluded bundler-audit using DS_EXCLUDED_ANALYZERS you will need to clean up (remove the reference) in 15.0. If you have customized your pipeline's Dependency Scanning configuration, for example to edit the `bundler-audit-dependency_scanning` job, you will want to switch to gemnasium-dependency_scanning before removal in 15.0, to prevent your pipeline from failing. If you have not used the DS_EXCLUDED_ANALYZERS to reference bundler-audit, or customized your template specifically for bundler-audit, you will not need to take action.
+
+Announced: 2021-12-22
+Planned removal: 2022-05-22
### GitLab Serverless
@@ -117,6 +178,7 @@ Announced: 2021-11-22
We decided to remove the GitLab Serverless features as they never really resonated with our users. Besides, given the continuous development of Kubernetes and Knative, our current implementations do not even work with recent versions.
Announced: 2021-09-22
+Planned removal: 2022-05-22
### Known host required for GitLab Runner SSH executor
@@ -125,6 +187,7 @@ In [GitLab 14.3](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/30
In GitLab 15.0 and later, the default value for this configuration option will change from `true` to `false`. This means that strict host key checking will be enforced when using the GitLab Runner SSH executor.
Announced: 2021-11-22
+Planned removal: 2022-05-22
### Legacy database configuration
@@ -135,6 +198,16 @@ supported using a single PostgreSQL adapter, whereas the new format is changing
This deprecation mainly impacts users compiling GitLab from source because Omnibus will handle this configuration automatically.
Announced: 2021-09-22
+Planned removal: 2022-05-22
+
+### Must explicitly assign `AuthenticationType` for `[runners.cache.s3]`
+
+In GitLab 15.0 and later, to access the AWS S3 cache, you must specify the `AuthenticationType` for [`[runners.cache.s3]`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscaches3-section). The `AuthenticationType` must be `IAM` or `credentials`.
+
+Prior to 14.5, if you did not define the `AuthenticationType`, GitLab Runner chose a type for you.
+
+Announced: 2021-11-22
+Planned removal: 2022-05-22
### NFS for Git repository storage deprecated
@@ -149,6 +222,7 @@ Gitaly Cluster offers tremendous benefits for our customers such as:
We encourage customers currently using NFS for Git repositories to plan their migration by reviewing our documentation on [migrating to Gitaly Cluster](https://docs.gitlab.com/ee/administration/gitaly/index.html#migrate-to-gitaly-cluster).
Announced: 2021-06-22
+Planned removal: 2022-05-22
### OmniAuth Kerberos gem
@@ -159,6 +233,7 @@ This gem has not been maintained and has very little usage. We therefore plan to
Note that we are not deprecating the Kerberos SPNEGO integration, only the old password-based Kerberos integration.
Announced: 2021-09-22
+Planned removal: 2022-05-22
### Package pipelines in API payload is paginated
@@ -167,31 +242,48 @@ A request to the API for `/api/v4/projects/:id/packages` returns a paginated res
In milestone 15.0, we will remove the `pipelines` attribute from the API response.
Announced: 2021-11-22
+Planned removal: 2022-05-22
### REST API Runner will not contain `paused`
-Runner REST API will not return `paused` as a status in GitLab 15.0.
+The GitLab Runner REST and GraphQL API endpoints will not return `paused` or `active` as a status in GitLab 15.0.
-Paused runners' status will only relate to runner contact status, such as:
-`online`, `offline`, or `not_connected`. Status `paused` will not appear when the runner is
-not active.
+A runner's status will only relate to runner contact status, such as:
+`online`, `offline`, or `not_connected`. Status `paused` or `active` will no longer appear.
When checking if a runner is `paused`, API users are advised to check the boolean attribute
-`active` to be `false` instead.
+`active` to be `false` instead. When checking if a runner is `active`, check if `active` is `true`.
+
+Announced: 2021-11-22
+Planned removal: 2022-05-22
+
+### Removal of `defaultMergeCommitMessageWithDescription` GraphQL API field
+
+The GraphQL API field `defaultMergeCommitMessageWithDescription` has been deprecated and will be removed in GitLab 15.0. For projects with a commit message template set, it will ignore the template.
Announced: 2021-11-22
+Planned removal: 2022-05-22
### Removal of `promote-db` command from `gitlab-ctl`
In GitLab 14.5, we introduced the command `gitlab-ctl promote` to promote any Geo secondary node to a primary during a failover. This command replaces `gitlab-ctl promote-db` which is used to promote database nodes in multi-node Geo secondary sites. `gitlab-ctl promote-db` will continue to function as-is and be available until GitLab 15.0. We recommend that Geo customers begin testing the new `gitlab-ctl promote` command in their staging environments and incorporating the new command in their failover procedures.
Announced: 2021-11-22
+Planned removal: 2022-05-22
### Removal of `promote-to-primary-node` command from `gitlab-ctl`
In GitLab 14.5, we introduced the command `gitlab-ctl promote` to promote any Geo secondary node to a primary during a failover. This command replaces `gitlab-ctl promote-to-primary-node` which was only usable for single-node Geo sites. `gitlab-ctl promote-to-primary-node` will continue to function as-is and be available until GitLab 15.0. We recommend that Geo customers begin testing the new `gitlab-ctl promote` command in their staging environments and incorporating the new command in their failover procedures.
Announced: 2021-11-22
+Planned removal: 2022-05-22
+
+### Remove `type` and `types` keyword in CI/CD configuration
+
+The `type` and `types` CI/CD keywords will be removed in GitLab 15.0. Pipelines that use these keywords will stop working, so you must switch to `stage` and `stages`, which have the same behavior.
+
+Announced: 2021-12-22
+Planned removal: 2022-05-22
### Remove the `:dependency_proxy_for_private_groups` feature flag
@@ -200,6 +292,7 @@ We added a feature flag because [GitLab-#11582](https://gitlab.com/gitlab-org/gi
In milestone 15.0, we will remove the feature flag entirely. Moving forward, you must authenticate when using the Dependency Proxy.
Announced: 2021-11-22
+Planned removal: 2022-05-22
### Remove the `pipelines` field from the `version` field
@@ -211,6 +304,7 @@ In GraphQL, there are two `pipelines` fields that you can use in a [`PackageDeta
To mitigate possible performance problems, we will remove the `versions` field's `pipelines` field in milestone 15.0. Although you will no longer be able to get all pipelines for all versions of a package, you can still get the pipelines of a single version through the remaining `pipelines` field for that version.
Announced: 2021-11-22
+Planned removal: 2022-05-22
### Update to the Container Registry group-level API
@@ -219,25 +313,22 @@ In milestone 15.0, support for the `tags` and `tags_count` parameters will be re
The `GET /groups/:id/registry/repositories` endpoint will remain, but won't return any info about tags. To get the info about tags, you can use the existing `GET /registry/repositories/:id` endpoint, which will continue to support the `tags` and `tag_count` options as it does today. The latter must be called once per image repository.
Announced: 2021-11-22
+Planned removal: 2022-05-22
### Value Stream Analytics filtering calculation change
-We are changing how the date filter works in Value Stream Analytics. Instead of filtering by the time that the issue or merge request was created, the date filter will filter by the end event time of the given stage. This will result in completely different figures after this change has rolled out.
+We are changing how the date filter works in Value Stream Analytics. Instead of filtering by the time that the issue or merge request was created, the date filter will filter by the end event time of the given stage. This will result in completely different figures after this change has rolled out.
If you monitor Value Stream Analytics metrics and rely on the date filter, to avoid losing data, you must save the data prior to this change.
Announced: 2021-11-22
+Planned removal: 2022-05-22
-### `AuthenticationType` for `[runners.cache.s3]` must be explicitly assigned
+### apiFuzzingCiConfigurationCreate GraphQL mutation
-In GitLab 15.0 and later, to access the AWS S3 cache, you must specify the `AuthenticationType` for [`[runners.cache.s3]`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscaches3-section). The `AuthenticationType` must be `IAM` or `credentials`.
-
-Prior to 14.5, if you did not define the `AuthenticationType`, GitLab Runner chose a type for you.
+The API Fuzzing configuration snippet is now being generated client-side and does not require an
+API request anymore. We are therefore deprecating the `apiFuzzingCiConfigurationCreate` mutation
+which isn't being used in GitLab anymore.
-Announced: 2021-11-22
-
-### defaultMergeCommitMessageWithDescription GraphQL API field will be removed in GitLab 15.0
-
-The GraphQL API field `defaultMergeCommitMessageWithDescription` has been deprecated and will be removed in GitLab 15.0. For projects with a commit message template set, it will ignore the template.
-
-Announced: 2021-11-22
+Announced: 2021-12-22
+Planned removal: 2022-05-22
diff --git a/doc/update/index.md b/doc/update/index.md
index bb7fdaa93c0..98dfee04a41 100644
--- a/doc/update/index.md
+++ b/doc/update/index.md
@@ -82,17 +82,23 @@ See the guide to [plan your GitLab upgrade](plan_your_upgrade.md).
## Checking for background migrations before upgrading
Certain releases may require different migrations to be
-finished before you update to the newer version. Additionally check
-[batched migrations](#batched-background-migrations) from GitLab 14.0.
+finished before you update to the newer version.
+
+[Batched migrations](#batched-background-migrations) are a migration type available in GitLab 14.0 and later.
+Background migrations and batched migrations not the same, so you should check that both are
+complete before updating.
Decrease the time required to complete these migrations by increasing the number of
[Sidekiq workers](../administration/operations/extra_sidekiq_processes.md)
that can process jobs in the `background_migration` queue.
+### Background migrations
+
**For Omnibus installations:**
```shell
sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'
+sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.pending'
```
**For installations from source:**
@@ -100,6 +106,7 @@ sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaini
```shell
cd /home/git/gitlab
sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'
+sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::BackgroundMigration.pending'
```
### Batched background migrations
@@ -212,30 +219,9 @@ sudo -u git -H bundle exec rake gitlab:elastic:list_pending_migrations
See [how to retry a halted migration](../integration/elasticsearch.md#retry-a-halted-migration).
-## Upgrade paths
-
-Upgrading across multiple GitLab versions in one go is *only possible by accepting downtime*.
-The following examples assume downtime is acceptable while upgrading.
-If you don't want any downtime, read how to [upgrade with zero downtime](zero_downtime.md).
-
-Find where your version sits in the upgrade path below, and upgrade GitLab
-accordingly, while also consulting the
-[version-specific upgrade instructions](#version-specific-upgrading-instructions):
-
-`8.11.Z` -> `8.12.0` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> [`11.11.8`](#1200) -> `12.0.12` -> [`12.1.17`](#1210) -> `12.10.14` -> `13.0.14` -> [`13.1.11`](#1310) -> [`13.8.8`](#1388) -> [`13.12.15`](https://about.gitlab.com/releases/categories/releases/) -> [latest `14.0.Z`](#1400) -> [latest `14.1.Z`](#1410) -> [latest `14.Y.Z`](https://about.gitlab.com/releases/categories/releases/)
-
-The following table, while not exhaustive, shows some examples of the supported
-upgrade paths.
+## Upgrading without downtime
-| Target version | Your version | Supported upgrade path | Note |
-| -------------- | ------------ | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `14.1.6` | `13.9.2` | `13.9.2` -> `13.12.12` -> `14.0.11` -> `14.1.6` | Two intermediate versions are required: `13.12` and `14.0`, then `14.1`. |
-| `13.12.10` | `12.9.2` | `12.9.2` -> `12.10.14` -> `13.0.14` -> `13.1.11` -> `13.8.8` -> `13.12.10` | Four intermediate versions are required: `12.10`, `13.0`, `13.1` and `13.8.8`, then `13.12.10`. |
-| `13.2.10` | `11.5.0` | `11.5.0` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14` -> `13.0.14` -> `13.1.11` -> `13.2.10` | Six intermediate versions are required: `11.11`, `12.0`, `12.1`, `12.10`, `13.0` and `13.1`, then `13.2.10`. |
-| `12.10.14` | `11.3.4` | `11.3.4` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14` | Three intermediate versions are required: `11.11`, `12.0` and `12.1`, then `12.10.14`. |
-| `12.9.5` | `10.4.5` | `10.4.5` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.9.5` | Four intermediate versions are required: `10.8`, `11.11`, `12.0` and `12.1`, then `12.9.5`. |
-| `12.2.5` | `9.2.6` | `9.2.6` -> `9.5.10` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.2.5` | Five intermediate versions are required: `9.5`, `10.8`, `11.11`, `12.0`, `12.1`, then `12.2.5`. |
-| `11.3.4` | `8.13.4` | `8.13.4` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> `11.3.4` | `8.17.7` is the last version in version 8, `9.5.10` is the last version in version 9, `10.8.7` is the last version in version 10. |
+Read how to [upgrade without downtime](zero_downtime.md).
## Upgrading to a new major version
@@ -247,8 +233,9 @@ cannot guarantee that upgrading between major versions is seamless.
It is required to follow the following upgrade steps to ensure a successful *major* version upgrade:
1. Upgrade to the latest minor version of the preceding major version.
-1. Upgrade to the first minor version (`X.0.Z`) of the target major version.
-1. Proceed with upgrading to a newer release.
+1. Upgrade to the next major version (`X.0.Z`).
+1. Upgrade to its first minor version (`X.1.Z`).
+1. Proceed with upgrading to a newer releases of that major version.
Identify a [supported upgrade path](#upgrade-paths).
@@ -264,11 +251,34 @@ before proceeding with the major version upgrade.
If your GitLab instance has any runners associated with it, it is very
important to upgrade GitLab Runner to match the GitLab minor version that was
-upgraded to. This is to ensure [compatibility with GitLab versions](https://docs.gitlab.com/runner/#compatibility-with-gitlab-versions).
+upgraded to. This is to ensure [compatibility with GitLab versions](https://docs.gitlab.com/runner/#gitlab-runner-versions).
-## Upgrading without downtime
+## Upgrade paths
-Read how to [upgrade without downtime](zero_downtime.md).
+Upgrading across multiple GitLab versions in one go is *only possible by accepting downtime*.
+The following examples assume downtime is acceptable while upgrading.
+If you don't want any downtime, read how to [upgrade with zero downtime](zero_downtime.md).
+
+Find where your version sits in the upgrade path below, and upgrade GitLab
+accordingly, while also consulting the
+[version-specific upgrade instructions](#version-specific-upgrading-instructions):
+
+`8.11.Z` -> `8.12.0` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> [`11.11.8`](#1200) -> `12.0.12` -> [`12.1.17`](#1210) -> `12.10.14` -> `13.0.14` -> [`13.1.11`](#1310) -> [`13.8.8`](#1388) -> [latest `13.12.Z`](https://about.gitlab.com/releases/categories/releases/) -> [latest `14.0.Z`](#1400) -> [latest `14.1.Z`](#1410) -> [latest `14.Y.Z`](https://about.gitlab.com/releases/categories/releases/)
+
+The following table, while not exhaustive, shows some examples of the supported
+upgrade paths.
+Additional steps between the mentioned versions are possible. We list the minimally necessary steps only.
+
+| Target version | Your version | Supported upgrade path | Note |
+| -------------- | ------------ | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `14.2.6` | `13.10.2` | `13.10.2` -> `13.12.12` -> `14.0.11` -> `14.1.8` -> `14.2.6` | Three intermediate versions are required: `13.12`, `14.0`, and `14.1`, then `14.2.6`. |
+| `14.1.8` | `13.9.2` | `13.9.2` -> `13.12.12` -> `14.0.11` -> `14.1.8` | Two intermediate versions are required: `13.12` and `14.0`, then `14.1.8`. |
+| `13.12.10` | `12.9.2` | `12.9.2` -> `12.10.14` -> `13.0.14` -> `13.1.11` -> `13.8.8` -> `13.12.10` | Four intermediate versions are required: `12.10`, `13.0`, `13.1` and `13.8.8`, then `13.12.10`. |
+| `13.2.10` | `11.5.0` | `11.5.0` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14` -> `13.0.14` -> `13.1.11` -> `13.2.10` | Six intermediate versions are required: `11.11`, `12.0`, `12.1`, `12.10`, `13.0` and `13.1`, then `13.2.10`. |
+| `12.10.14` | `11.3.4` | `11.3.4` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14` | Three intermediate versions are required: `11.11`, `12.0` and `12.1`, then `12.10.14`. |
+| `12.9.5` | `10.4.5` | `10.4.5` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.9.5` | Four intermediate versions are required: `10.8`, `11.11`, `12.0` and `12.1`, then `12.9.5`. |
+| `12.2.5` | `9.2.6` | `9.2.6` -> `9.5.10` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.2.5` | Five intermediate versions are required: `9.5`, `10.8`, `11.11`, `12.0`, and `12.1`, then `12.2.5`. |
+| `11.3.4` | `8.13.4` | `8.13.4` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> `11.3.4` | `8.17.7` is the last version in version 8, `9.5.10` is the last version in version 9, `10.8.7` is the last version in version 10. |
## Upgrading between editions
@@ -357,8 +367,14 @@ or [init scripts](upgrading_from_source.md#configure-sysv-init-script) by [follo
### 14.4.0
-Git 2.33.x and later is required. We recommend you use the
-[Git version provided by Gitaly](../install/installation.md#git).
+- Git 2.33.x and later is required. We recommend you use the
+ [Git version provided by Gitaly](../install/installation.md#git).
+- See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144).
+- After enabling database load balancing by default in 14.4.0, we found an issue where
+ [cron jobs would not work if the connection to PostgreSQL was severed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73716),
+ as Sidekiq would continue using a bad connection. Geo and other features that rely on
+ cron jobs running regularly do not work until Sidekiq is restarted. We recommend
+ upgrading to GitLab 14.4.3 and later if this issue affects you.
### 14.3.0
@@ -385,6 +401,8 @@ for how to proceed.
sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production
```
+- See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144).
+
### 14.2.0
- [Instances running 14.0.0 - 14.0.4 should not upgrade directly to GitLab 14.2 or later](#upgrading-to-later-14y-releases).
@@ -411,15 +429,20 @@ for how to proceed.
sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production
```
+- See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144).
+
### 14.1.0
- [Instances running 14.0.0 - 14.0.4 should not upgrade directly to GitLab 14.2 or later](#upgrading-to-later-14y-releases)
but can upgrade to 14.1.Z.
-- It is not required for instances already running 14.0.5 (or higher) to stop at 14.1.Z.
+
+ It is not required for instances already running 14.0.5 (or higher) to stop at 14.1.Z.
14.1 is included on the upgrade path for the broadest compatibility
with self-managed installations, and ensure 14.0.0-14.0.4 installations do not
encounter issues with [batched background migrations](#batched-background-migrations).
+- See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144).
+
### 14.0.0
- Database changes made by the upgrade to GitLab 14.0 can take hours or days to complete on larger GitLab instances.
@@ -449,6 +472,8 @@ for how to proceed.
You should instead follow a [supported upgrade path](#upgrade-paths).
- The support of PostgreSQL 11 [has been dropped](../install/requirements.md#database). Make sure to [update your database](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server) to version 12 before updating to GitLab 14.0.
+- See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144).
+
#### Upgrading to later 14.Y releases
- Instances running 14.0.0 - 14.0.4 should not upgrade directly to GitLab 14.2 or later,
@@ -459,48 +484,60 @@ for how to proceed.
1. [Batched background migrations need to finish](#batched-background-migrations)
before you update to a later version [and may take longer than usual](#1400).
+### 13.12.0
+
+See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144).
+
### 13.11.0
-Git 2.31.x and later is required. We recommend you use the
-[Git version provided by Gitaly](../install/installation.md#git).
+- Git 2.31.x and later is required. We recommend you use the
+ [Git version provided by Gitaly](../install/installation.md#git).
+
+- See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144).
+
+### 13.10.0
+
+See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144).
### 13.9.0
-We've detected an issue [with a column rename](https://gitlab.com/gitlab-org/gitlab/-/issues/324160)
-that prevents upgrades to GitLab 13.9.0, 13.9.1, 13.9.2, and 13.9.3 when following the zero-downtime steps. It is necessary
-to perform the following additional steps for the zero-downtime upgrade:
+- We've detected an issue [with a column rename](https://gitlab.com/gitlab-org/gitlab/-/issues/324160)
+ that prevents upgrades to GitLab 13.9.0, 13.9.1, 13.9.2, and 13.9.3 when following the zero-downtime steps. It is necessary
+ to perform the following additional steps for the zero-downtime upgrade:
-1. Before running the final `sudo gitlab-rake db:migrate` command on the deploy node,
- execute the following queries using the PostgreSQL console (or `sudo gitlab-psql`)
- to drop the problematic triggers:
+ 1. Before running the final `sudo gitlab-rake db:migrate` command on the deploy node,
+ execute the following queries using the PostgreSQL console (or `sudo gitlab-psql`)
+ to drop the problematic triggers:
- ```sql
- drop trigger trigger_e40a6f1858e6 on application_settings;
- drop trigger trigger_0d588df444c8 on application_settings;
- drop trigger trigger_1572cbc9a15f on application_settings;
- drop trigger trigger_22a39c5c25f3 on application_settings;
- ```
+ ```sql
+ drop trigger trigger_e40a6f1858e6 on application_settings;
+ drop trigger trigger_0d588df444c8 on application_settings;
+ drop trigger trigger_1572cbc9a15f on application_settings;
+ drop trigger trigger_22a39c5c25f3 on application_settings;
+ ```
-1. Run the final migrations:
+ 1. Run the final migrations:
- ```shell
- sudo gitlab-rake db:migrate
- ```
+ ```shell
+ sudo gitlab-rake db:migrate
+ ```
-If you have already run the final `sudo gitlab-rake db:migrate` command on the deploy node and have
-encountered the [column rename issue](https://gitlab.com/gitlab-org/gitlab/-/issues/324160), you
-see the following error:
+ If you have already run the final `sudo gitlab-rake db:migrate` command on the deploy node and have
+ encountered the [column rename issue](https://gitlab.com/gitlab-org/gitlab/-/issues/324160), you
+ see the following error:
-```shell
--- remove_column(:application_settings, :asset_proxy_whitelist)
-rake aborted!
-StandardError: An error has occurred, all later migrations canceled:
-PG::DependentObjectsStillExist: ERROR: cannot drop column asset_proxy_whitelist of table application_settings because other objects depend on it
-DETAIL: trigger trigger_0d588df444c8 on table application_settings depends on column asset_proxy_whitelist of table application_settings
-```
+ ```shell
+ -- remove_column(:application_settings, :asset_proxy_whitelist)
+ rake aborted!
+ StandardError: An error has occurred, all later migrations canceled:
+ PG::DependentObjectsStillExist: ERROR: cannot drop column asset_proxy_whitelist of table application_settings because other objects depend on it
+ DETAIL: trigger trigger_0d588df444c8 on table application_settings depends on column asset_proxy_whitelist of table application_settings
+ ```
+
+ To work around this bug, follow the previous steps to complete the update.
+ More details are available [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/324160).
-To work around this bug, follow the previous steps to complete the update.
-More details are available [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/324160).
+- See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144).
### 13.8.8
@@ -610,6 +647,14 @@ After upgraded to 11.11.8 you can safely upgrade to 12.0.Z.
See our [documentation on upgrade paths](../policy/maintenance.md#upgrade-recommendations)
for more information.
+### Maintenance mode issue in GitLab 13.9 to 14.4
+
+When [Maintenance mode](../administration/maintenance_mode/index.md) is enabled, users cannot sign in with SSO, SAML, or LDAP.
+
+Users who were signed in before Maintenance mode was enabled will continue to be signed in. If the admin who enabled Maintenance mode loses their session, then they will not be able to disable Maintenance mode via the UI. In that case, you can [disable Maintenance mode via the API or Rails console](../administration/maintenance_mode/#disable-maintenance-mode).
+
+[This bug](https://gitlab.com/gitlab-org/gitlab/-/issues/329261) was fixed in GitLab 14.5.0, and is expected to be backported to GitLab 14.3 and 14.4.
+
## Miscellaneous
- [MySQL to PostgreSQL](mysql_to_postgresql.md) guides you through migrating
diff --git a/doc/update/package/index.md b/doc/update/package/index.md
index 27845caed76..d7c18f15e44 100644
--- a/doc/update/package/index.md
+++ b/doc/update/package/index.md
@@ -159,7 +159,7 @@ install GitLab for the first time or update it.
To download and install GitLab:
1. Visit the [official repository](#upgrade-using-the-official-repositories) of your package.
-1. Filter the list by searching for the version you want to install (for example 14.1.6).
+1. Filter the list by searching for the version you want to install (for example 14.1.8).
Multiple packages may exist for a single version, one for each supported distribution
and architecture. Next to the filename is a label indicating the distribution,
as the filenames may be the same.
@@ -188,7 +188,7 @@ For the GitLab Community Edition, replace `gitlab-ee` with
### GitLab 13.7 and later unavailable on Amazon Linux 2
-Amazon Linux 2 is not an [officially supported operating system](../../administration/package_information/deprecated_os.md#supported-operating-systems).
+Amazon Linux 2 is not an [officially supported operating system](../../administration/package_information/supported_os.md).
However, in past the [official package installation script](https://packages.gitlab.com/gitlab/gitlab-ee/install)
installed the `el/6` package repository if run on Amazon Linux. From GitLab 13.7, we no longer
provide `el/6` packages so administrators must run the [installation script](https://packages.gitlab.com/gitlab/gitlab-ee/install)
diff --git a/doc/update/plan_your_upgrade.md b/doc/update/plan_your_upgrade.md
index 320f900dd21..98549cc136a 100644
--- a/doc/update/plan_your_upgrade.md
+++ b/doc/update/plan_your_upgrade.md
@@ -18,7 +18,7 @@ General notes:
to create your plan, share details of your architecture, including:
- How is GitLab installed?
- What is the operating system of the node?
- (check [OS versions that are no longer supported](../administration/package_information/deprecated_os.md) to confirm that later updates are available).
+ (check [OS versions that are no longer supported](../administration/package_information/supported_os.md#os-versions-that-are-no-longer-supported) to confirm that later updates are available).
- Is it a single-node or a multi-node setup? If multi-node, share any architectural details about each node with us.
- Are you using [GitLab Geo](../administration/geo/index.md)? If so, share any architectural details about each secondary node.
- What else might be unique or interesting in your setup that might be important for us to understand?
@@ -71,7 +71,7 @@ comprised of a way to back up the instance and a way to restore it.
### Back up GitLab
-Create a backup of GitLab and all its data (database, repos, uploads, builds,
+Create a backup of GitLab and all its data (database, repositories, uploads, builds,
artifacts, LFS objects, registry, pages). This is vital for making it possible
to roll back GitLab to a working state if there's a problem with the upgrade:
@@ -112,7 +112,7 @@ to your instance and then upgrade it for any relevant features you're using.
- [Determine what upgrade path](index.md#upgrade-paths) to follow.
- Account for any [version-specific update instructions](index.md#version-specific-upgrading-instructions).
- Account for any [version-specific changes](package/index.md#version-specific-changes).
- - Check the [OS compatibility with the target GitLab version](../administration/package_information/deprecated_os.md).
+ - Check the [OS compatibility with the target GitLab version](../administration/package_information/supported_os.md).
- Due to background migrations, plan to pause any further upgrades after upgrading
to a new major version.
[All migrations must finish running](index.md#checking-for-background-migrations-before-upgrading)
@@ -145,7 +145,7 @@ version prior to upgrading the application server.
If you're using Geo:
-- Review [Geo upgrade documentation](../administration/geo/replication/updating_the_geo_nodes.md).
+- Review [Geo upgrade documentation](../administration/geo/replication/updating_the_geo_sites.md).
- Read about the [Geo version-specific update instructions](../administration/geo/replication/version_specific_updates.md).
- Review Geo-specific steps when [updating the database](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance).
- Create an upgrade and rollback plan for _each_ Geo node (primary and each secondary).
diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md
index 4343b464ba6..22ffcda9138 100644
--- a/doc/update/upgrading_from_source.md
+++ b/doc/update/upgrading_from_source.md
@@ -111,7 +111,7 @@ Download and install Go (for Linux, 64-bit):
# Remove former Go installation folder
sudo rm -rf /usr/local/go
-curl --remote-name --progress-bar "https://golang.org/dl/go1.16.10.linux-amd64.tar.gz"
+curl --remote-name --progress-bar "https://go.dev/dl/go1.16.10.linux-amd64.tar.gz"
echo '414cd18ce1d193769b9e97d2401ad718755ab47816e13b2a1cde203d263b55cf go1.16.10.linux-amd64.tar.gz' | shasum -a256 -c - && \
sudo tar -C /usr/local -xzf go1.16.10.linux-amd64.tar.gz
sudo ln -sf /usr/local/go/bin/{go,gofmt} /usr/local/bin/
diff --git a/doc/update/upgrading_postgresql_using_slony.md b/doc/update/upgrading_postgresql_using_slony.md
index 8ccdf8d0077..f2bbc8d7558 100644
--- a/doc/update/upgrading_postgresql_using_slony.md
+++ b/doc/update/upgrading_postgresql_using_slony.md
@@ -113,7 +113,7 @@ CREATE ROLE slony WITH SUPERUSER LOGIN REPLICATION ENCRYPTED PASSWORD 'password
ALTER ROLE slony SET statement_timeout TO 0;
```
-Make sure you replace "password string here" with the actual password for the
+Make sure you replace "password string here" with an actual password for the
user. A password is required. This user must be created on both the old and
new database server using the same password.
@@ -230,7 +230,7 @@ Now run the following commands:
\i /tmp/migrations.sql
```
-To verify if the structure is in place close the session, start it again, then
+To verify if the structure is in place close the session (`\q`), start it again, then
run `\d`. If all went well you should see output along the lines of the
following:
@@ -459,7 +459,7 @@ main
Upload this script to the _target_ server and execute it as follows:
```shell
-bash path/to/the/script/above.sh
+sudo bash path/to/the/script/above.sh
```
This corrects the ownership of sequences and reset the next value for the
diff --git a/doc/update/zero_downtime.md b/doc/update/zero_downtime.md
index a311731cadd..13658e6071b 100644
--- a/doc/update/zero_downtime.md
+++ b/doc/update/zero_downtime.md
@@ -29,9 +29,9 @@ If you meet all the requirements above, follow these instructions in order. Ther
| [Geo](#geo-deployment) | GitLab EE with Geo enabled |
| [Multi-node / HA with Geo](#multi-node--ha-deployment-with-geo) | GitLab CE/EE on multiple nodes |
-Each type of deployment will require that you hot reload the `puma` and `sidekiq` processes on all nodes running these
+Each type of deployment requires that you hot reload the `puma` and `sidekiq` processes on all nodes running these
services after you've upgraded. The reason for this is that those processes each load the GitLab Rails application which reads and loads
-the database schema into memory when starting up. Each of these processes will need to be reloaded (or restarted in the case of `sidekiq`)
+the database schema into memory when starting up. Each of these processes needs to be reloaded (or restarted in the case of `sidekiq`)
to re-read any database changes that have been made by post-deployment migrations.
Most of the time you can safely upgrade from a patch release to the next minor
@@ -56,7 +56,7 @@ increasing the number of Sidekiq workers that can process jobs in the
`background_migration` queue. To see the size of this queue,
[Check for background migrations before upgrading](index.md#checking-for-background-migrations-before-upgrading).
-As a rule of thumb, any database smaller than 10 GB doesn't take too much time to
+As a guideline, any database smaller than 10 GB doesn't take too much time to
upgrade; perhaps an hour at most per minor release. Larger databases however may
require more time, but this is highly dependent on the size of the database and
the migrations that are being performed.
@@ -111,26 +111,26 @@ Before following these instructions, note the following **important** informatio
1. Update the GitLab package:
- - For GitLab Community Edition:
+ - For GitLab [Enterprise Edition](https://about.gitlab.com/pricing/):
```shell
# Debian/Ubuntu
sudo apt-get update
- sudo apt-get install gitlab-ce
+ sudo apt-get install gitlab-ee
# Centos/RHEL
- sudo yum install gitlab-ce
+ sudo yum install gitlab-ee
```
- - For GitLab [Enterprise Edition](https://about.gitlab.com/pricing/):
+ - For GitLab Community Edition:
```shell
# Debian/Ubuntu
sudo apt-get update
- sudo apt-get install gitlab-ee
+ sudo apt-get install gitlab-ce
# Centos/RHEL
- sudo yum install gitlab-ee
+ sudo yum install gitlab-ce
```
1. To get the regular migrations and latest code in place, run
@@ -176,14 +176,14 @@ Upgrades on web (Puma) nodes must be done in a rolling manner, one after
another, ensuring at least one node is always up to serve traffic. This is
required to ensure zero-downtime.
-Puma will enter a blackout period as part of the upgrade, during which they
-continue to accept connections but will mark their respective health check
+Puma enters a blackout period as part of the upgrade, during which nodes
+continue to accept connections but mark their respective health check
endpoints to be unhealthy. On seeing this, the load balancer should disconnect
them gracefully.
-Puma will restart only after completing all the currently processing requests.
+Puma restarts only after completing all the currently processing requests.
This ensures data and service integrity. Once they have restarted, the health
-check end points will be marked healthy.
+check end points are marked healthy.
The nodes must be updated in the following order to update an HA instance using
load balancer to latest GitLab version.
@@ -201,14 +201,14 @@ load balancer to latest GitLab version.
```shell
# Debian/Ubuntu
- sudo apt-get update && sudo apt-get install gitlab-ce
+ sudo apt-get update && sudo apt-get install gitlab-ee
# Centos/RHEL
- sudo yum install gitlab-ce
+ sudo yum install gitlab-ee
```
- If you are an Enterprise Edition user, replace `gitlab-ce` with
- `gitlab-ee` in the above command.
+ If you are a Community Edition user, replace `gitlab-ee` with
+ `gitlab-ce` in the above command.
1. Get the regular migrations and latest code in place. Before running this step,
the deploy node's `/etc/gitlab/gitlab.rb` configuration file must have
@@ -254,7 +254,7 @@ the application.
Before you update the main application you need to update Praefect.
Out of your Praefect nodes, pick one to be your Praefect deploy node.
-This is where you will install the new Omnibus package first and run
+This is where you install the new Omnibus package first and run
database migrations.
**Praefect deploy node**
@@ -277,13 +277,13 @@ database migrations.
```shell
# Debian/Ubuntu
- sudo apt-get update && sudo apt-get install gitlab-ce
+ sudo apt-get update && sudo apt-get install gitlab-ee
# Centos/RHEL
- sudo yum install gitlab-ce
+ sudo yum install gitlab-ee
```
- If you are an Enterprise Edition user, replace `gitlab-ce` with `gitlab-ee` in the above command.
+ If you are a Community Edition user, replace `gitlab-ee` with `gitlab-ce` in the above command.
- To apply the Praefect database migrations and restart Praefect, run:
@@ -296,10 +296,10 @@ database migrations.
- Update the GitLab package:
```shell
- sudo apt-get update && sudo apt-get install gitlab-ce
+ sudo apt-get update && sudo apt-get install gitlab-ee
```
- If you are an Enterprise Edition user, replace `gitlab-ce` with `gitlab-ee` in the above command.
+ If you are a Community Edition user, replace `gitlab-ee` with `gitlab-ce` in the above command.
- Ensure nodes are running the latest code:
@@ -330,13 +330,13 @@ node throughout the process.
```shell
# Debian/Ubuntu
- sudo apt-get update && sudo apt-get install gitlab-ce
+ sudo apt-get update && sudo apt-get install gitlab-ee
# Centos/RHEL
- sudo yum install gitlab-ce
+ sudo yum install gitlab-ee
```
- If you are an Enterprise Edition user, replace `gitlab-ce` with `gitlab-ee` in the above command.
+ If you are a Community Edition user, replace `gitlab-ee` with `gitlab-ce` in the above command.
- Ensure nodes are running the latest code
@@ -350,17 +350,17 @@ node throughout the process.
```shell
# Debian/Ubuntu
- sudo apt-get update && sudo apt-get install gitlab-ce
+ sudo apt-get update && sudo apt-get install gitlab-ee
# Centos/RHEL
- sudo yum install gitlab-ce
+ sudo yum install gitlab-ee
```
- If you are an Enterprise Edition user, replace `gitlab-ce` with `gitlab-ee` in the above command.
+ If you are a Community Edition user, replace `gitlab-ee` with `gitlab-ce` in the above command.
- If you're using PgBouncer:
- You'll need to bypass PgBouncer and connect directly to the database master
+ You need to bypass PgBouncer and connect directly to the database master
before running migrations.
Rails uses an advisory lock when attempting to run a migration to prevent
@@ -391,10 +391,10 @@ node throughout the process.
- Update the GitLab package
```shell
- sudo apt-get update && sudo apt-get install gitlab-ce
+ sudo apt-get update && sudo apt-get install gitlab-ee
```
- If you are an Enterprise Edition user, replace `gitlab-ce` with `gitlab-ee` in the above command.
+ If you are a Community Edition user, replace `gitlab-ee` with `gitlab-ce` in the above command.
- Ensure nodes are running the latest code
@@ -457,7 +457,7 @@ following command to get address of current Redis primary
```
- If your application node is running a version older than GitLab 12.7.0, you
- will have to run the underlying `redis-cli` command (which `get-redis-master`
+ have to run the underlying `redis-cli` command (which `get-redis-master`
command uses) to fetch information about the primary.
1. Get the address of one of the sentinel nodes specified as
@@ -653,7 +653,7 @@ setting `gitlab_rails['auto_migrate'] = false` in
This section describes the steps required to upgrade a multi-node / HA
deployment with Geo. Some steps must be performed on a particular node. This
-node will be known as the “deploy node” and is noted through the following
+node is known as the “deploy node” and is noted through the following
instructions.
Updates must be performed in the following order:
@@ -737,7 +737,7 @@ sudo touch /etc/gitlab/skip-auto-reconfigure
1. If you're using PgBouncer:
- You'll need to bypass PgBouncer and connect directly to the database master
+ You need to bypass PgBouncer and connect directly to the database master
before running migrations.
Rails uses an advisory lock when attempting to run a migration to prevent
View Lorry Controller Status