diff options
Diffstat (limited to 'doc/update/index.md')
| -rw-r--r-- | doc/update/index.md | 77 |
1 files changed, 62 insertions, 15 deletions
diff --git a/doc/update/index.md b/doc/update/index.md index 71d1bd06ff0..4c4dfe79d03 100644 --- a/doc/update/index.md +++ b/doc/update/index.md @@ -107,6 +107,10 @@ Sidekiq::Queue.new("background_migration").size Sidekiq::ScheduledSet.new.select { |r| r.klass == 'BackgroundMigrationWorker' }.size ``` +### Batched background migrations + +See the documentation on [batched background migrations](../user/admin_area/monitoring/background_migrations.md). + ### What do I do if my background migrations are stuck? WARNING: @@ -138,6 +142,19 @@ pending_job_classes = scheduled_queue.select { |job| job["class"] == "Background pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_class) } ``` +## Dealing with running CI/CD pipelines and jobs + +If you upgrade your GitLab instance while the GitLab Runner is processing jobs, the trace updates will fail. Once GitLab is back online, then the trace updates should self-heal. However, depending on the error, the GitLab Runner will either retry or eventually terminate job handling. + +As for the artifacts, the GitLab Runner will attempt to upload them three times, after which the job will eventually fail. + +To address the above two scenario's, it is advised to do the following prior to upgrading: + +1. Plan your maintenance. +1. Pause your runners. +1. Wait until all jobs are finished. +1. Upgrade GitLab. + ## Checking for pending Advanced Search migrations This section is only applicable if you have enabled the [Elasticsearch @@ -185,7 +202,7 @@ upgrade paths. | Target version | Your version | Supported upgrade path | Note | | --------------------- | ------------ | ------------------------ | ---- | | `13.5.4` | `12.9.2` | `12.9.2` -> `12.10.14` -> `13.0.14` -> `13.1.11` -> `13.5.4` | Three intermediate versions are required: the final `12.10` release, plus `13.0` and `13.1`. | -| `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.2.10` | Five intermediate versions are required: the final `11.11`, `12.0`, `12.1` and `12.10` releases, plus `13.0`. | +| `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: the final `11.11`, `12.0`, `12.1`, `12.10`, `13.0` releases, plus `13.1`. | | `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: the final `11.11` and `12.0` releases, plus `12.1` | | `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`. | @@ -198,7 +215,7 @@ Backward-incompatible changes and migrations are reserved for major versions. We cannot guarantee that upgrading between major versions will be seamless. It is suggested to upgrade to the latest available *minor* version within your major version before proceeding to the next major version. -Doing this will address any backward-incompatible changes or deprecations +Doing this addresses any backward-incompatible changes or deprecations to help ensure a successful upgrade to the next major release. Identify a [supported upgrade path](#upgrade-paths). @@ -212,7 +229,7 @@ before upgrading to a new major version. To see the current size of the `backgro [Check for background migrations before upgrading](#checking-for-background-migrations-before-upgrading). If you have enabled the [Elasticsearch -integration](../integration/elasticsearch.md), then you will also need to ensure +integration](../integration/elasticsearch.md), then ensure all Advanced Search migrations are completed in the last minor version within your current version. Be sure to [check for pending Advanced Search migrations](#checking-for-pending-advanced-search-migrations) before proceeding @@ -250,8 +267,8 @@ migrations are performed in the background by Sidekiq and are often used for migrating data. Background migrations are only added in the monthly releases. Certain major/minor releases may require a set of background migrations to be -finished. To guarantee this such a release will process any remaining jobs -before continuing the upgrading procedure. While this won't require downtime +finished. To guarantee this, such a release processes any remaining jobs +before continuing the upgrading procedure. While this doesn't require downtime (if the above conditions are met) we recommend users to keep at least 1 week between upgrading major/minor releases, allowing the background migrations to finish. The time necessary to complete these migrations can be reduced by @@ -259,7 +276,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](#checking-for-background-migrations-before-upgrading). -As a rule of thumb, any database smaller than 10 GB won't take too much time to +As a rule of thumb, 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. @@ -277,17 +294,17 @@ _have_ to first upgrade to a 9.5.Z release. **Example 2:** You are running a large GitLab installation using version 9.4.2, which is the latest patch release of 9.4. GitLab 9.5 includes some background -migrations, and 10.0 will require these to be completed (processing any +migrations, and 10.0 requires these to be completed (processing any remaining jobs for you). Skipping 9.5 is not possible without downtime, and due to the background migrations would require potentially hours of downtime depending on how long it takes for the background migrations to complete. To -work around this you will have to upgrade to 9.5.Z first, then wait at least a +work around this you have to upgrade to 9.5.Z first, then wait at least a week before upgrading to 10.0. **Example 3:** You use MySQL as the database for GitLab. Any upgrade to a new -major/minor release will require downtime. If a release includes any background +major/minor release requires downtime. If a release includes any background migrations this could potentially lead to hours of downtime, depending on the -size of your database. To work around this you will have to use PostgreSQL and +size of your database. To work around this you must use PostgreSQL and meet the other online upgrade requirements mentioned above. ### Steps @@ -334,7 +351,7 @@ At the end of those release posts, there are three sections to look for: - Removals - Important notes on upgrading -These will include: +These include: - Steps you need to perform as part of an upgrade. For example [8.12](https://about.gitlab.com/releases/2016/09/22/gitlab-8-12-released/#upgrade-barometer) @@ -357,9 +374,39 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap Git 2.31.x and later is required. We recommend you use the [Git version provided by Gitaly](../install/installation.md#git). +### 13.9.0 + +We've detected an issue [with a column rename](https://gitlab.com/gitlab-org/gitlab/-/issues/324160) +that may prevent upgrades to GitLab 13.9.0, 13.9.1, 13.9.2 and 13.9.3. +We are working on a patch, but until a fixed version is released, you can manually complete +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: + + ```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: + + ```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 can still +follow the previous steps to complete the update. + +More details are available [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/324160). + ### 13.6.0 -Ruby 2.7.2 is required. GitLab will not start with Ruby 2.6.6 or older versions. +Ruby 2.7.2 is required. GitLab does not start with Ruby 2.6.6 or older versions. The required Git version is Git v2.29 or higher. @@ -374,7 +421,7 @@ v2.24 remains the same. ### 13.2.0 -GitLab installations that have multiple web nodes will need to be +GitLab installations that have multiple web nodes must be [upgraded to 13.1](#1310) before upgrading to 13.2 (and later) due to a breaking change in Rails that can result in authorization issues. @@ -396,14 +443,14 @@ In 13.1.0, you must upgrade to either: - At least Git v2.24 (previously, the minimum required version was Git v2.22). - The recommended Git v2.26. -Failure to do so will result in internal errors in the Gitaly service in some RPCs due +Failure to do so results in internal errors in the Gitaly service in some RPCs due to the use of the new `--end-of-options` Git flag. Additionally, in GitLab 13.1.0, the version of [Rails was upgraded from 6.0.3 to 6.0.3.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33454). The Rails upgrade included a change to CSRF token generation which is not backwards-compatible - GitLab servers with the new Rails version -will generate CSRF tokens that are not recognizable by GitLab servers +generate CSRF tokens that are not recognizable by GitLab servers with the older Rails version - which could cause non-GET requests to fail for [multi-node GitLab installations](https://docs.gitlab.com/omnibus/update/#multi-node--ha-deployment). |