diff options
Diffstat (limited to 'doc/update')
| -rw-r--r-- | doc/update/deprecations.md | 142 | ||||
| -rw-r--r-- | doc/update/index.md | 61 | ||||
| -rw-r--r-- | doc/update/upgrading_from_source.md | 11 | ||||
| -rw-r--r-- | doc/update/zero_downtime.md | 80 |
4 files changed, 168 insertions, 126 deletions
diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md index 9453482cc67..7e8eaef2b4c 100644 --- a/doc/update/deprecations.md +++ b/doc/update/deprecations.md @@ -36,6 +36,68 @@ For deprecation reviewers (Technical Writers only): https://about.gitlab.com/handbook/marketing/blog/release-posts/#update-the-deprecations-doc --> +View deprecations by the product versions in which they were announced. + +Each deprecation has a **planned removal milestone** and indicates whether it is a breaking change. + +Most of the deprecations are **planned for removal in 15.0**, and many of them are **breaking changes**. + +## 14.10 + +### Manual iteration management + +WARNING: +This feature will be changed or removed in 16.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +Manual iteration management is deprecated and only automatic iteration cadences will be supported in the future. + +Creating and deleting iterations will be fully removed in 16.0. Updating all iteration fields except for +`description` will also be removed. + +On the GraphQL API the following mutations will be removed: + + 1. `iterationCreate` + 1. `iterationDelete` + +The update `updateIteration` mutation will only allow updating the iteration's `description`. The following +arguments will be removed: + + 1. `title` + 1. `dueDate` + 1. `startDate` + +For more information about iteration cadences, you can refer to +[the documentation of the feature](https://docs.gitlab.com/ee/user/group/iterations/#iteration-cadences). + +**Planned removal milestone: 16.0 (2023-04-22)** + +### Outdated indices of Advanced Search migrations + +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +As Advanced Search migrations usually require support multiple code paths for a long period of time, it’s important to clean those up when we safely can. We use GitLab major version upgrades as a safe time to remove backward compatibility for indices that have not been fully migrated. See the [upgrade documentation](https://docs.gitlab.com/ee/update/index.html#upgrading-to-a-new-major-version) for details. + +**Planned removal milestone: 15.0 (2021-05-22)** + +### Toggle notes confidentiality on APIs + +WARNING: +This feature will be changed or removed in 16.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +Toggling notes confidentiality with REST and GraphQL APIs is being deprecated. Updating notes confidential attribute is no longer supported by any means. We are changing this to simplify the experience and prevent private information from being unintentionally exposed. + +**Planned removal milestone: 16.0 (2023-05-22)** + ## 14.9 ### Background upload for object storage @@ -59,7 +121,7 @@ GitLab will publish additional guidance to assist affected customers in migratin ### Deprecate support for Debian 9 -Long term service and support (LTSS) for [Debian 9 Stretch ends in July 2022](https://wiki.debian.org/LTS). Therefore, we will longer support the Debian 9 distribution for the GitLab package. Users can upgrade to Debian 10 or Debian 11. +Long term service and support (LTSS) for [Debian 9 Stretch ends in July 2022](https://wiki.debian.org/LTS). Therefore, we will no longer support the Debian 9 distribution for the GitLab package. Users can upgrade to Debian 10 or Debian 11. **Planned removal milestone: 15.1 (2022-06-22)** @@ -69,17 +131,17 @@ In 15.0, support for daemon mode for GitLab Pages will be removed. **Planned removal milestone: 15.0 (2022-05-22)** -### GitLab self-monitoring +### GitLab self-monitoring project WARNING: -This feature will be changed or removed in 15.0 +This feature will be changed or removed in 16.0 as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). Before updating GitLab, review the details carefully to determine if you need to make any changes to your code, settings, or workflow. -GitLab self-monitoring gives administrators of self-hosted GitLab instances the tools to monitor the health of their instances. This feature is deprecated in GitLab 14.9, and is scheduled for removal in 15.0. +GitLab self-monitoring gives administrators of self-hosted GitLab instances the tools to monitor the health of their instances. This feature is deprecated in GitLab 14.9, and is scheduled for removal in 16.0. -**Planned removal milestone: 15.0 (2022-05-22)** +**Planned removal milestone: 16.0 (2023-05-22)** ### GraphQL permissions change for Package settings @@ -313,12 +375,12 @@ Specifically, the following are deprecated: - Requests that have the `status` field set to `approved`. Beginning in GitLab 15.0, status checks will only be updated to a passing state if the `status` field is both present -and set to `pass`. Requests that: +and set to `passed`. Requests that: - Do not contain the `status` field will be rejected with a `422` error. For more information, see [the relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/338827). -- Contain any value other than `pass` will cause the status check to fail. For more information, see [the relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/339039). +- Contain any value other than `passed` will cause the status check to fail. For more information, see [the relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/339039). -To align with this change, API calls to list external status checks will also return the value of `pass` rather than +To align with this change, API calls to list external status checks will also return the value of `passed` rather than `approved` for status checks that have passed. **Planned removal milestone: 15.0 (2022-05-22)** @@ -528,29 +590,6 @@ existing runners. **Planned removal milestone: 16.0 (2023-04-22)** -### Reminder: support for NFS repository storage - -WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. - -As [announced](https://about.gitlab.com/releases/2021/06/22/gitlab-14-0-released/#nfs-for-git-repository-storage-deprecated) at the -release of GitLab 14.0, technical support for NFS storage for Git repositories is being removed. Please see our official -[Statement of Support](https://about.gitlab.com/support/statement-of-support.html#gitaly-and-nfs) for additional information. - -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/#migrating-to-gitaly-cluster). - -Gitaly Cluster offers tremendous benefits for our customers such as: - -- [Variable replication factors](https://docs.gitlab.com/ee/administration/gitaly/praefect.html#configure-replication-factor) -- [Strong consistency](https://docs.gitlab.com/ee/administration/gitaly/#strong-consistency) -- [Distributed read capabilities](https://docs.gitlab.com/ee/administration/gitaly/#distributed-reads) - -**Planned removal milestone: 15.0 (2022-05-22)** - ### Request profiling WARNING: @@ -812,14 +851,29 @@ The new security approvals feature is similar to vulnerability check. For exampl ### `CI_BUILD_*` predefined variables WARNING: -This feature will be changed or removed in 15.0 +This feature will be changed or removed in 16.0 as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). Before updating GitLab, review the details carefully to determine if you need to make any changes to your code, settings, or workflow. -The predefined CI/CD variables that start with `CI_BUILD_*` were deprecated in GitLab 9.0, and will be removed in GitLab 15.0. If you still use these variables, be sure to change to the current [`CI_JOB_*` predefined variables](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html) which are identical (except for the updated name). +The predefined CI/CD variables that start with `CI_BUILD_*` were deprecated in GitLab 9.0, and will be removed in GitLab 16.0. If you still use these variables, be sure to change to the replacement [predefined variables](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html) which are functionally identical: -**Planned removal milestone: 15.0 (2022-05-22)** +| Removed variable | Replacement variable | +| --------------------- |------------------------ | +| `CI_BUILD_BEFORE_SHA` | `CI_COMMIT_BEFORE_SHA` | +| `CI_BUILD_ID` | `CI_JOB_ID` | +| `CI_BUILD_MANUAL` | `CI_JOB_MANUAL` | +| `CI_BUILD_NAME` | `CI_JOB_NAME` | +| `CI_BUILD_REF` | `CI_COMMIT_SHA` | +| `CI_BUILD_REF_NAME` | `CI_COMMIT_REF_NAME` | +| `CI_BUILD_REF_SLUG` | `CI_COMMIT_REF_SLUG` | +| `CI_BUILD_REPO` | `CI_REPOSITORY_URL` | +| `CI_BUILD_STAGE` | `CI_JOB_STAGE` | +| `CI_BUILD_TAG` | `CI_COMMIT_TAG` | +| `CI_BUILD_TOKEN` | `CI_JOB_TOKEN` | +| `CI_BUILD_TRIGGERED` | `CI_PIPELINE_TRIGGERED` | + +**Planned removal milestone: 16.0 (2023-04-22)** ### `fixup!` commit messages setting draft status of associated Merge Request @@ -973,7 +1027,7 @@ The logging features in GitLab allow users to install the ELK stack (Elasticsear ### Monitor performance metrics through Prometheus WARNING: -This feature will be changed or removed in 15.0 +This feature will be changed or removed in 16.0 as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). Before updating GitLab, review the details carefully to determine if you need to make any changes to your code, settings, or workflow. @@ -981,7 +1035,7 @@ changes to your code, settings, or workflow. By displaying data stored in a Prometheus instance, GitLab allows users to view performance metrics. GitLab also displays visualizations of these metrics in dashboards. The user can connect to a previously-configured external Prometheus instance, or set up Prometheus as a GitLab Managed App. However, since certificate-based integration with Kubernetes clusters is deprecated in GitLab, the metrics functionality in GitLab that relies on Prometheus is also deprecated. This includes the metrics visualizations in dashboards. GitLab is working to develop a single user experience based on [Opstrace](https://about.gitlab.com/press/releases/2021-12-14-gitlab-acquires-opstrace-to-expand-its-devops-platform-with-open-source-observability-solution.html). An [issue exists](https://gitlab.com/groups/gitlab-org/-/epics/6976) for you to follow work on the Opstrace integration. -**Planned removal milestone: 15.0 (2022-05-22)** +**Planned removal milestone: 16.0 (2023-05-22)** ### Pseudonymizer @@ -1294,12 +1348,12 @@ In milestone 15.0, we will remove the `pipelines` attribute from the API respons ### REST and GraphQL API Runner status will not return `paused` WARNING: -This feature will be changed or removed in 15.0 +This feature will be changed or removed in 16.0 as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). Before updating GitLab, review the details carefully to determine if you need to make any changes to your code, settings, or workflow. -The GitLab Runner REST and GraphQL API endpoints will not return `paused` or `active` 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 16.0. 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. @@ -1307,7 +1361,7 @@ A runner's status will only relate to runner contact status, such as: When checking if a runner is `paused`, API users are advised to check the boolean attribute `paused` to be `true` instead. When checking if a runner is `active`, check if `paused` is `false`. -**Planned removal milestone: 15.0 (2022-05-22)** +**Planned removal milestone: 16.0 (2023-04-22)** ### Support for SLES 12 SP2 @@ -1522,13 +1576,7 @@ This will result in the rename of the sub-chart: `gitlab/task-runner` to `gitlab ### NFS for Git repository storage -WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. - -With the general availability of Gitaly Cluster ([introduced in GitLab 13.0](https://about.gitlab.com/releases/2020/05/22/gitlab-13-0-released/)), we have deprecated development (bugfixes, performance improvements, etc) for NFS for Git repository storage in GitLab 14.0. We will continue to provide technical support for NFS for Git repositories throughout 14.x, but we will remove all support for NFS in GitLab 15.0. Please see our official [Statement of Support](https://about.gitlab.com/support/statement-of-support.html#gitaly-and-nfs) for further information. +With the general availability of Gitaly Cluster ([introduced in GitLab 13.0](https://about.gitlab.com/releases/2020/05/22/gitlab-13-0-released/)), we have deprecated development (bugfixes, performance improvements, etc) for NFS for Git repository storage in GitLab 14.0. We will continue to provide technical support for NFS for Git repositories throughout 14.x, but we will remove all support for NFS on November 22, 2022. This was originally planned for May 22, 2022, but in an effort to allow continued maturity of Gitaly Cluster, we have chosen to extend our deprecation of support date. Please see our official [Statement of Support](https://about.gitlab.com/support/statement-of-support.html#gitaly-and-nfs) for further information. Gitaly Cluster offers tremendous benefits for our customers such as: @@ -1538,7 +1586,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). -**Planned removal milestone: 15.0 (2022-05-22)** +**Planned removal milestone: 15.6 (2022-11-22)** ### OAuth implicit grant diff --git a/doc/update/index.md b/doc/update/index.md index 5a00a728535..1e8badf59b4 100644 --- a/doc/update/index.md +++ b/doc/update/index.md @@ -192,6 +192,8 @@ pending_job_classes.each { |job_class| Gitlab::BackgroundMigration.steal(job_cla #### Background migrations stuck in 'pending' state GitLab 13.6 introduced an issue where a background migration named `BackfillJiraTrackerDeploymentType2` can be permanently stuck in a **pending** state across upgrades. To clean up this stuck migration, see the [13.6.0 version-specific instructions](#1360). +GitLab 14.4 introduced an issue where a background migration named `PopulateTopicsTotalProjectsCountCache` can be permanently stuck in a **pending** state across upgrades when the instance lacks records that match the migration's target. To clean up this stuck migration, see the [14.4.0 version-specific instructions](#1440). +GitLab 14.8 introduced an issue where a background migration named `PopulateTopicsNonPrivateProjectsCount` can be permanently stuck in a **pending** state across upgrades. To clean up this stuck migration, see the [14.8.0 version-specific instructions](#1480). For other background migrations stuck in pending, run the following check. If it returns non-zero and the count does not decrease over time, follow the rest of the steps in this section. @@ -398,6 +400,8 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap ### 14.8.0 +- If upgrading from a version earlier than 14.6.5, 14.7.4, or 14.8.2, please review the [Critical Security Release: 14.8.2, 14.7.4, and 14.6.5](https://about.gitlab.com/releases/2022/02/25/critical-security-release-gitlab-14-8-2-released/) blog post. + Updating to 14.8.2 or later will reset runner registration tokens for your groups and projects. - The agent server for Kubernetes [is enabled by default](https://about.gitlab.com/releases/2022/02/22/gitlab-14-8-released/#the-agent-server-for-kubernetes-is-enabled-by-default) on Omnibus installations. If you run GitLab at scale, such as [the reference architectures](../administration/reference_architectures/index.md), @@ -417,15 +421,49 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap 1. Add `gitlab_kas['enable'] = false` to `gitlab.rb`. 1. If the server is already upgraded to 14.8, run `gitlab-ctl reconfigure`. +- GitLab 14.8.0 includes a +[background migration `PopulateTopicsNonPrivateProjectsCount`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79140) +that may remain stuck permanently in a **pending** state. + + To clean up this stuck job, run the following in the [GitLab Rails Console](../administration/operations/rails_console.md): + + ```ruby + Gitlab::Database::BackgroundMigrationJob.pending.where(class_name: "PopulateTopicsNonPrivateProjectsCount").find_each do |job| + puts Gitlab::Database::BackgroundMigrationJob.mark_all_as_succeeded("PopulateTopicsNonPrivateProjectsCountq", job.arguments) + end + ``` + +- If upgrading from a version earlier than 14.3.0, to avoid + [an issue with job retries](https://gitlab.com/gitlab-org/gitlab/-/issues/357822), first upgrade + to GitLab 14.7.x and make sure all batched migrations have finished. +- If upgrading from version 14.3.0 or later, you might notice a failed + [batched migration](../user/admin_area/monitoring/background_migrations.md) named + `BackfillNamespaceIdForNamespaceRoute`. You can [ignore](https://gitlab.com/gitlab-org/gitlab/-/issues/357822) + this. Retry it after you upgrade to version 14.9.x. ### 14.7.0 - See [LFS objects import and mirror issue in GitLab 14.6.0 to 14.7.2](#lfs-objects-import-and-mirror-issue-in-gitlab-1460-to-1472). +- If upgrading from a version earlier than 14.6.5, 14.7.4, or 14.8.2, please review the [Critical Security Release: 14.8.2, 14.7.4, and 14.6.5](https://about.gitlab.com/releases/2022/02/25/critical-security-release-gitlab-14-8-2-released/) blog post. + Updating to 14.7.4 or later will reset runner registration tokens for your groups and projects. +- GitLab 14.7 introduced a change where Gitaly expects persistent files in the `/tmp` directory. + When using the `noatime` mount option on `/tmp` in a node running Gitaly, most Linux distributions + run into [an issue with Git server hooks getting deleted](https://gitlab.com/gitlab-org/gitaly/-/issues/4113). + These conditions are present in the default Amazon Linux configuration. + + If your Linux distribution manages files in `/tmp` with the `tmpfiles.d` service, you + can override the behavior of `tmpfiles.d` for the Gitaly files and avoid this issue: + + ```shell + sudo echo "x /tmp/gitaly-hooks-*" > /etc/tmpfiles.d/gitaly-workaround.conf + ``` ### 14.6.0 - See [LFS objects import and mirror issue in GitLab 14.6.0 to 14.7.2](#lfs-objects-import-and-mirror-issue-in-gitlab-1460-to-1472). - +- If upgrading from a version earlier than 14.6.5, 14.7.4, or 14.8.2, please review the [Critical Security Release: 14.8.2, 14.7.4, and 14.6.5](https://about.gitlab.com/releases/2022/02/25/critical-security-release-gitlab-14-8-2-released/) blog post. + Updating to 14.6.5 or later will reset runner registration tokens for your groups and projects. + ### 14.5.0 - When `make` is run, Gitaly builds are now created in `_build/bin` and no longer in the root directory of the source directory. If you @@ -473,6 +511,17 @@ or [init scripts](upgrading_from_source.md#configure-sysv-init-script) by [follo 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. +- GitLab 14.4.0 includes a +[background migration `PopulateTopicsTotalProjectsCountCache`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71033) +that may remain stuck permanently in a **pending** state when the instance lacks records that match the migration's target. + + To clean up this stuck job, run the following in the [GitLab Rails Console](../administration/operations/rails_console.md): + + ```ruby + Gitlab::Database::BackgroundMigrationJob.pending.where(class_name: "PopulateTopicsTotalProjectsCountCache").find_each do |job| + puts Gitlab::Database::BackgroundMigrationJob.mark_all_as_succeeded("PopulateTopicsTotalProjectsCountCache", job.arguments) + end + ``` ### 14.3.0 @@ -576,6 +625,8 @@ for how to proceed. - 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). +- See [Custom Rack Attack initializers](#custom-rack-attack-initializers) if you persist your own custom Rack Attack + initializers during upgrades. #### Upgrading to later 14.Y releases @@ -754,6 +805,14 @@ all servers must first be upgraded to 13.1.Z before upgrading to 13.2.0 or later 1. Only then, continue to upgrade to later versions of GitLab. +#### Custom Rack Attack initializers + +From GitLab 13.0.1, custom Rack Attack initializers (`config/initializers/rack_attack.rb`) are replaced with initializers +supplied with GitLab during upgrades. We recommend you use these GitLab-supplied initializers. + +If you persist your own Rack Attack initializers between upgrades, you might +[get `500` errors](https://gitlab.com/gitlab-org/gitlab/-/issues/334681) when [upgrading to GitLab 14.0 and later](#1400). + ### 12.2.0 In 12.2.0, we enabled Rails' authenticated cookie encryption. Old sessions are diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md index 22367435ae4..4537faaaead 100644 --- a/doc/update/upgrading_from_source.md +++ b/doc/update/upgrading_from_source.md @@ -199,6 +199,17 @@ cd /home/git/gitlab git diff origin/PREVIOUS_BRANCH:config/gitlab.yml.example origin/BRANCH:config/gitlab.yml.example ``` +#### New configuration options for `database.yml` + +There might be configuration options available for [`database.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/database.yml.postgresql). +View them with the command below and apply them manually to your current `database.yml`: + +```shell +cd /home/git/gitlab + +git diff origin/PREVIOUS_BRANCH:config/database.yml.postgresql origin/BRANCH:config/database.yml.postgresql +``` + #### NGINX configuration Ensure you're still up-to-date with the latest NGINX configuration changes: diff --git a/doc/update/zero_downtime.md b/doc/update/zero_downtime.md index d69d60fe73d..5aa80c12f11 100644 --- a/doc/update/zero_downtime.md +++ b/doc/update/zero_downtime.md @@ -13,16 +13,14 @@ there are the following requirements: - You can only upgrade one minor release at a time. So from 13.1 to 13.2, not to 13.3. If you skip releases, database modifications may be run in the wrong sequence [and leave the database schema in a broken state](https://gitlab.com/gitlab-org/gitlab/-/issues/321542). -- You have to use [post-deployment migrations](../development/post_deployment_migrations.md). +- You have to use [post-deployment migrations](../development/database/post_deployment_migrations.md). - You are using PostgreSQL. Starting from GitLab 12.1, MySQL is not supported. -- Multi-node GitLab instance. Single-node instances may experience brief interruptions - [as services restart (Puma in particular)](#single-node-deployment). +- You have set up a multi-node GitLab instance. Single-node instances do not support zero-downtime upgrades. If you meet all the requirements above, follow these instructions in order. There are three sets of steps, depending on your deployment type: | Deployment type | Description | | --------------------------------------------------------------- | ------------------------------------------------ | -| [Single-node](#single-node-deployment) | GitLab CE/EE on a single node | | [Gitaly Cluster](#gitaly-cluster) | GitLab CE/EE using HA architecture for Gitaly Cluster | | [Multi-node / PostgreSQL HA](#use-postgresql-ha) | GitLab CE/EE using HA architecture for PostgreSQL | | [Multi-node / Redis HA](#use-redis-ha-using-sentinel) | GitLab CE/EE using HA architecture for Redis | @@ -87,80 +85,6 @@ migrations this could potentially lead to hours of downtime, depending on the size of your database. To work around this you must use PostgreSQL and meet the other online upgrade requirements mentioned above. -## Single-node deployment - -WARNING: -You can only upgrade one minor release at a time. - -Before following these instructions, note the following **important** information: - -- You can only upgrade one minor release at a time. So from 13.6 to 13.7, not to 13.8. - If you attempt more than one minor release, the upgrade may fail. -- On single-node Omnibus deployments, updates with no downtime are not possible when - using Puma because Puma always requires a complete restart. This is because the - [phased restart](https://github.com/puma/puma/blob/master/README.md#clustered-mode) - feature of Puma does not work with the way it is configured in GitLab all-in-one - packages (cluster-mode with app preloading). -- While it is possible to minimize downtime on a single-node instance by following - these instructions, **it is not possible to always achieve true zero downtime - updates**. Users may see some connections timeout or be refused for a few minutes, - depending on which services need to restart. -- On Omnibus deployments, the `/etc/gitlab/gitlab.rb` configuration file must **not** have - `gitlab_rails['auto_migrate'] = true`. - -1. Create an empty file at `/etc/gitlab/skip-auto-reconfigure`. This prevents upgrades from running `gitlab-ctl reconfigure`, which by default automatically stops GitLab, runs all database migrations, and restarts GitLab. - - ```shell - sudo touch /etc/gitlab/skip-auto-reconfigure - ``` - -1. Update the GitLab package: - - - For GitLab [Enterprise Edition](https://about.gitlab.com/pricing/): - - ```shell - # Debian/Ubuntu - sudo apt-get update - sudo apt-get install gitlab-ee - - # Centos/RHEL - sudo yum install gitlab-ee - ``` - - - For GitLab Community Edition: - - ```shell - # Debian/Ubuntu - sudo apt-get update - sudo apt-get install gitlab-ce - - # Centos/RHEL - sudo yum install gitlab-ce - ``` - -1. To get the regular migrations and latest code in place, run - - ```shell - sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-ctl reconfigure - ``` - -1. Once the node is updated and `reconfigure` finished successfully, run post-deployment migrations with - - ```shell - sudo gitlab-rake db:migrate - ``` - -1. Hot reload `puma` and `sidekiq` services - - ```shell - sudo gitlab-ctl hup puma - sudo gitlab-ctl restart sidekiq - ``` - -If you do not want to run zero downtime upgrades in the future, make -sure you remove `/etc/gitlab/skip-auto-reconfigure` after -you've completed these steps. - ## Multi-node / HA deployment WARNING: |