diff --git a/doc/administration/license.md b/doc/administration/license.md index 7fcf3ee5c126e9084b1b57cd030687ce05bddc82..2dcfb9fd26e62e27b9968abde69611b7a9d3f733 100644 --- a/doc/administration/license.md +++ b/doc/administration/license.md @@ -82,7 +82,7 @@ To verify the edition, sign in to GitLab and select at the top of the page. If you are running GitLab Community Edition (CE), you can upgrade your installation to GitLab -EE. For more information, see [upgrading between editions](../update/upgrade.md#upgrading-between-editions). +EE. For more information, see [other upgrade paths](../update/convert_to_ee/_index.md). If you have questions or need assistance, [contact GitLab Support](https://about.gitlab.com/support/#contact-support). diff --git a/doc/update/convert_to_ee/_index.md b/doc/update/convert_to_ee/_index.md index 42cc642433d6831ba5758ebe0a9efc7b449321b5..423deb1ff731846df052b046d901bb16bbc545ec 100644 --- a/doc/update/convert_to_ee/_index.md +++ b/doc/update/convert_to_ee/_index.md @@ -6,23 +6,20 @@ title: Other upgrade paths description: Move between different editions or installation methods. --- -Not all upgrades are from one version of GitLab to another. -Other paths are available. +Not all upgrades are from one version of GitLab to another. Other paths are available. ## Convert to Enterprise Edition You can convert your GitLab Community Edition (CE) instance to a GitLab Enterprise Edition (EE) instance: -- [Convert the Linux package to EE](package.md) -- [Convert self-compiled to EE](self_compiled.md) -- [Convert Helm chart to EE](https://docs.gitlab.com/charts/installation/deployment.html#convert-community-edition-to-enterprise-edition) +- [Convert a Linux package instance to EE](package.md) +- [Convert a Docker instance to EE](docker.md) +- [Convert a self-compiled instance to EE](self_compiled.md) +- [Convert a GitLab Helm chart instance to EE](https://docs.gitlab.com/charts/installation/deployment.html#convert-community-edition-to-enterprise-edition) -If you need to return to Community Edition from Enterprise Edition: - -- [Revert from EE to CE](revert.md) +If required, you can [revert from Enterprise Edition to Community Edition](revert.md). ## Convert a self-compiled instance to a Linux package -If you have a self-compiled GitLab instance and want to convert it to a Linux package: - -- [Convert self-compiled to Linux](https://docs.gitlab.com/omnibus/update/convert_to_omnibus/) +If you have a self-compiled GitLab instance, you can +[convert a self-compiled GitLab instance to Linux package](https://docs.gitlab.com/omnibus/update/convert_to_omnibus/). diff --git a/doc/update/docker/_index.md b/doc/update/docker/_index.md index d97dbb4eb1039b15db79591fd632de31125e3822..57bc64a1976d0216709fb33911eca1644550cbcb 100644 --- a/doc/update/docker/_index.md +++ b/doc/update/docker/_index.md @@ -3,7 +3,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 Docker instances -description: Upgrade a Docker-based instance. +description: Upgrade a single-node Docker-based instance. --- {{< details >}} @@ -15,9 +15,28 @@ description: Upgrade a Docker-based instance. Upgrade a Docker-based instance to a later version of GitLab. -Before you upgrade, consult [information you need before you upgrade](../plan_your_upgrade.md). +## Prerequisites -## Upgrade GitLab by using Docker Engine +Before you upgrade a Docker instance, you must follow [information you need before you upgrade](../plan_your_upgrade.md). + +## Upgrade GitLab + +To upgrade GitLab: + +1. Consider [turning on maintenance mode](../../administration/maintenance_mode/_index.md) during the upgrade. +1. Pause [running CI/CD pipelines and jobs](../plan_your_upgrade.md#pause-cicd-pipelines-and-jobs). +1. [Upgrade GitLab Runner](https://docs.gitlab.com/runner/install/) to the same version as your target GitLab version. +1. Upgrade GitLab itself by either: + - [Using Docker Engine](#upgrade-gitlab-by-using-docker-engine). + - [Using Docker Compose](#upgrade-gitlab-by-using-docker-compose). + +After you upgrade: + +1. Unpause [running CI/CD pipelines and jobs](../plan_your_upgrade.md#pause-cicd-pipelines-and-jobs). +1. If enabled, [turn off maintenance mode](../../administration/maintenance_mode/_index.md#disable-maintenance-mode). +1. Run [upgrade health checks](../plan_your_upgrade.md#run-upgrade-health-checks). + +### Upgrade GitLab by using Docker Engine To upgrade a GitLab instance that was [installed by using Docker Engine](../../install/docker/installation.md#install-gitlab-by-using-docker-engine): @@ -83,7 +102,7 @@ To upgrade a GitLab instance that was On the first run, GitLab reconfigures and upgrades itself. -## Upgrade GitLab by using Docker Compose +### Upgrade GitLab by using Docker Compose To upgrade a GitLab instance that was [installed by using Docker Compose](../../install/docker/installation.md#install-gitlab-by-using-docker-compose): diff --git a/doc/update/package/_index.md b/doc/update/package/_index.md index c1b387ee6779a311bc1f7c6353589df46df38a72..a6b11d6e8c7fd79bd688def7a919d15f7bc70d9f 100644 --- a/doc/update/package/_index.md +++ b/doc/update/package/_index.md @@ -3,7 +3,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 Linux package instances -description: Upgrade a Linux package-based instance. +description: Upgrade a single-node Linux package-based instance. --- {{< details >}} @@ -14,21 +14,23 @@ description: Upgrade a Linux package-based instance. {{< /details >}} The instructions for upgrading a Linux package instance depend on whether you have a single-node or multi-node -GitLab instance. To upgrade a multi-node instance, see: +GitLab instance. To upgrade a multi-node Linux package GitLab instance, see: - [Upgrade a multi-node instance with downtime](../with_downtime.md). - [Upgrade a multi-node instance with zero downtime](../zero_downtime.md). -To upgrade a single-node GitLab instance: +To upgrade a single-node Linux package GitLab instance, follow the information on this page. -1. [Complete the initial steps](../upgrade.md#upgrade-gitlab) in the main GitLab upgrade documentation. -1. Continue the upgrade by following the next sections. -1. After upgrading, if you host the product documentation, you can - [upgrade to a later version](../../administration/docs_self_host.md#upgrade-the-product-documentation-to-a-later-version). +{{< alert type="note" >}} + +If you host the product documentation, you can also +[upgrade it to a later version](../../administration/docs_self_host.md#upgrade-the-product-documentation-to-a-later-version). + +{{< /alert >}} ## Prerequisites -Before you upgrade a Linux package instance: +Before you upgrade a single-node Linux package GitLab instance: - Consult [information you need before you upgrade](../plan_your_upgrade.md). - If required, upgrade to a [supported operating system](../../install/package/_index.md). @@ -45,7 +47,24 @@ sudo touch /etc/gitlab/skip-auto-backup Nevertheless, you should maintain a full up-to-date [backup](../../administration/backup_restore/_index.md) on your own. -## Upgrade by using the official repositories (recommended) +## Upgrade GitLab + +To upgrade a single-node Linux package GitLab instance: + +1. Consider [turning on maintenance mode](../../administration/maintenance_mode/_index.md) during the upgrade. +1. Pause [running CI/CD pipelines and jobs](../plan_your_upgrade.md#pause-cicd-pipelines-and-jobs). +1. [Upgrade GitLab Runner](https://docs.gitlab.com/runner/install/) to the same version as your target GitLab version. +1. Upgrade GitLab itself by either: + - [Using the official repositories](#upgrade-by-using-the-official-repositories-recommended). + - [Using a downloaded package](#upgrade-by-using-a-downloaded-package). + +After you upgrade: + +1. Unpause [running CI/CD pipelines and jobs](../plan_your_upgrade.md#pause-cicd-pipelines-and-jobs). +1. If enabled, [turn off maintenance mode](../../administration/maintenance_mode/_index.md#disable-maintenance-mode). +1. Run [upgrade health checks](../plan_your_upgrade.md#run-upgrade-health-checks). + +### Upgrade by using the official repositories (recommended) All GitLab packages are posted to the GitLab [package server](https://packages.gitlab.com/gitlab/). @@ -181,7 +200,7 @@ sudo zypper install gitlab-ce {{< /tabs >}} -## Upgrade by using a downloaded package +### Upgrade by using a downloaded package If you don't want to use the official repositories, you can download the package and install it manually. This method can be used to either diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md index bfa064136137f31d6649637e024ad2e8c107671d..397943d232ee063e1782467e1bd5cdc00c3dae62 100644 --- a/doc/update/patch_versions.md +++ b/doc/update/patch_versions.md @@ -2,7 +2,8 @@ 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: Update self-compiled installations with patch versions +title: Update self-compiled instances with patch versions +description: Upgrade a single-node self-compiled instance with a patch version. --- {{< details >}} @@ -12,13 +13,31 @@ title: Update self-compiled installations with patch versions {{< /details >}} -Update self-compiled installations with patch versions. +Update self-compiled instances with patch versions. -Prerequisites: +## Prerequisites -- A [back up](../administration/backup_restore/_index.md) of your self-compiled installation. +Before you upgrade: -## Stop GitLab server +1. Consult [information you need before you upgrade](plan_your_upgrade.md). +1. [Back up](../administration/backup_restore/_index.md) your self-compiled instance. + +## Upgrade GitLab + +To upgrade GitLab: + +1. Consider [turning on maintenance mode](../administration/maintenance_mode/_index.md) during the upgrade. +1. Pause [running CI/CD pipelines and jobs](plan_your_upgrade.md#pause-cicd-pipelines-and-jobs). +1. [Upgrade GitLab Runner](https://docs.gitlab.com/runner/install/) to the same version as your target GitLab version. +1. Upgrade GitLab by following the instructions on this page. + +After you upgrade: + +1. Unpause [running CI/CD pipelines and jobs](plan_your_upgrade.md#pause-cicd-pipelines-and-jobs). +1. If enabled, [turn off maintenance mode](../administration/maintenance_mode/_index.md#disable-maintenance-mode). +1. Run [upgrade health checks](plan_your_upgrade.md#run-upgrade-health-checks). + +### Stop GitLab server To stop the GitLab server: @@ -30,7 +49,7 @@ sudo systemctl stop gitlab.target sudo service gitlab stop ``` -## Get latest code for the stable branch +### Get latest code for the stable branch In the following commands, replace `LATEST_TAG` with the GitLab tag to update to. For example, `v8.0.3`. @@ -57,7 +76,7 @@ In the following commands, replace `LATEST_TAG` with the GitLab tag to update to sudo -u git -H git checkout LATEST_TAG -b LATEST_TAG ``` -## Install libraries and run migrations +### Install libraries and run migrations To install libraries and run migrations, run the following commands: @@ -81,7 +100,7 @@ sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile cache:clear RAILS_ENV=production NODE_ENV=production NODE_OPTIONS="--max_old_space_size=4096" ``` -## Update GitLab Workhorse to the new patch version +### Update GitLab Workhorse to the new patch version To update GitLab Workhorse to the new patch version: @@ -91,7 +110,7 @@ cd /home/git/gitlab sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production ``` -## Update Gitaly to the new patch version +### Update Gitaly to the new patch version To update Gitaly to the new patch version: @@ -101,7 +120,7 @@ cd /home/git/gitlab sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly,/home/git/repositories]" RAILS_ENV=production ``` -## Update GitLab Shell to the new patch version +### Update GitLab Shell to the new patch version To update GitLab Shell to the new patch version: @@ -113,7 +132,7 @@ sudo -u git -H git checkout v$(}} @@ -137,7 +156,7 @@ sudo -u git -H make To install or update `gitlab-elasticsearch-indexer`, follow the [installation instruction](../integration/advanced_search/elasticsearch.md#install-an-elasticsearch-or-aws-opensearch-cluster). -## Start GitLab +### Start GitLab To start GitLab, run the following commands: @@ -151,7 +170,7 @@ sudo service gitlab start sudo service nginx restart ``` -## Check GitLab and its environment +### Check GitLab and its environment To check if GitLab and its environment are configured correctly, run: @@ -169,6 +188,6 @@ sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production If all items are green, then congratulations upgrade complete! -## Make sure background migrations are finished +### Make sure background migrations are finished [Check the status of background migrations](background_migrations.md) and make sure they are finished. diff --git a/doc/update/plan_your_upgrade.md b/doc/update/plan_your_upgrade.md index af8b7f35b3445441fb060f1bcb7e80f4498d0c68..3e547e3d115d05a91624c1e4e750ea83ca017b28 100644 --- a/doc/update/plan_your_upgrade.md +++ b/doc/update/plan_your_upgrade.md @@ -13,14 +13,14 @@ description: Steps to take before you upgrade. {{< /details >}} -Before you upgrade, you should: +Before you upgrade a GitLab instance, you must: -1. Gather pre-upgrade information. -1. Perform pre-upgrade steps. +1. Gather pre-upgrade information to prepare yourself for the upgrade. +1. Perform pre-upgrade steps before you upgrade GitLab itself. ## Gather pre-upgrade information -When planning the upgrade, you should: +When planning the upgrade: 1. Review the [GitLab release and maintenance policy](../policy/maintenance.md). 1. Consult the [GitLab upgrade notes](versions/_index.md) for different versions of GitLab to ensure compatibility. @@ -33,17 +33,52 @@ When planning the upgrade, you should: 1. Determine the appropriate [upgrade path](upgrade_paths.md) for your instance, including any required upgrade stops. Upgrade stops might require you to perform multiple upgrades. 1. Create an upgrade plan that documents: - - The steps to take to upgrade your instance including, if possible and required, a [zero-downtime upgrade](zero_downtime.md). - - The steps to take if the upgrade doesn't go smoothly including how to [roll back GitLab](#rollback-plan) if - necessary. + - The steps to take if the upgrade doesn't go smoothly including how to + [roll back GitLab if necessary](#create-a-rollback-plan-and-backup). With all pre-upgrade information gathered, you can move on to performing pre-upgrade steps. +### Create a rollback plan and backup + +Something might go wrong during an upgrade, so it's critical that you have a rollback plan. A proper rollback plan +creates a clear path to bring a GitLab instance back to its last working state and comprises: + +- The process to back up the instance. +- The process to restore the instance. + +You should test the rollback plan before you need it. For an overview of the steps required for rolling back, see +[roll back to earlier GitLab versions](package/downgrade.md). + +#### Create a GitLab backup + +To make it possible to roll back GitLab if there's a problem with the upgrade, either: + +- Create a [GitLab backup](../administration/backup_restore/_index.md). You must follow the instructions based on your + installation method and make sure to back up the + [secrets and configuration files](../administration/backup_restore/backup_gitlab.md#storing-configuration-files). +- Create a snapshot of your instance. If you instance is multi-node installation, you must snapshot every node. + **This process is out of scope for GitLab Support**. + +#### Roll back GitLab + +If you have a test environment that mimics production, test the restoration to ensure that everything works as you expect. + +To restore your GitLab backup: + +1. Refer to [restore prerequisites](../administration/backup_restore/restore_gitlab.md#restore-prerequisites). Most + importantly, the versions of the backed up and the new GitLab instance must be the same. +1. [Restore GitLab](../administration/backup_restore/_index.md#restore-gitlab) by following the instructions based on + your installation method. +1. Confirm that the [secrets and configuration files](../administration/backup_restore/backup_gitlab.md#storing-configuration-files) + are also restored. + +If restoring from a snapshot, you must already know how to do this. **This process is out of scope for GitLab Support**. + ## Perform pre-upgrade steps -Soon before you perform the upgrade, you should: +Shortly before you perform the upgrade: 1. Test your upgrade in a test environment first to reduce the risk of unplanned outages and extended downtime. 1. Run [upgrade health checks](#run-upgrade-health-checks). @@ -88,7 +123,7 @@ working: 1. If using Elasticsearch, verify that searches are successful. -If something goes wrong, [get support](upgrade.md#getting-support). +If something goes wrong, [get support](#get-support). ### Upgrades for optional features @@ -107,6 +142,38 @@ upgrading GitLab: [Elasticsearch if the new version breaks compatibility](../integration/advanced_search/elasticsearch.md#version-requirements). Updating Elasticsearch is **out of scope for GitLab Support**. +## Pause CI/CD pipelines and jobs + +During upgrades for most types of GitLab instances, you should pause CI/CD pipelines and jobs. + +If you upgrade your GitLab instance while GitLab Runner is processing jobs, the trace updates fail. When GitLab is +back online, the trace updates should self-heal. However, depending on the error, GitLab Runner either retries, or +eventually terminates, job handling. + +GitLab Runner attempts to upload job artifacts three times, after which the job eventually fails. + +To pause CI/CD pipelines and jobs: + +1. Pause the runners. +1. Block new jobs from starting by adding the following to your `/etc/gitlab/gitlab.rb` file: + + ```ruby + nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n deny all;\n return 503;\n}\n" + ``` + +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Wait until all jobs are finished. + +When you've completed your GitLab upgrade: + +1. Unpause your runners. +1. Unblock new jobs from starting by reverting the previous `/etc/gitlab/gitlab.rb` change. + ## Working with Support If you are [working with Support](https://about.gitlab.com/support/scheduling-upgrade-assistance/) to review your @@ -118,43 +185,23 @@ upgrade plan, document and share it with the answers to the following questions: - Is it a single-node or a multi-node setup? If multi-node, document and share any architectural details about each node. Which external components are used? For example, Gitaly, PostgreSQL, or Redis? - Are you using [Geo](../administration/geo/_index.md)? If so, document and share any architectural details about - each secondary node. + each secondary site. - What else might be unique or interesting in your setup that might be important? - Are you running into any known issues with your current version of GitLab? -## Rollback plan - -It's possible that something may go wrong during an upgrade, so it's critical -that a rollback plan be present for that scenario. A proper rollback plan -creates a clear path to bring the instance back to its last working state. It is -comprised of a way to back up the instance and a way to restore it. You should -test the rollback plan before you need it. For an overview of the steps required -for rolling back, see [roll back to earlier GitLab versions](package/downgrade.md). +## Get support -### Back up GitLab +If something goes wrong during your upgrade: -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: - -- Create a [GitLab backup](../administration/backup_restore/_index.md). - Make sure to follow the instructions based on your installation method. - Don't forget to back up the [secrets and configuration files](../administration/backup_restore/backup_gitlab.md#storing-configuration-files). -- Alternatively, create a snapshot of your instance. If this is a multi-node - installation, you must snapshot every node. - **This process is out of scope for GitLab Support**. +1. Copy any errors and gather any logs to later analyze. Use the following tools to help you gather data: + - [`gitlabsos`](https://gitlab.com/gitlab-com/support/toolbox/gitlabsos) if you installed GitLab by using the Linux + package or Docker. + - [`kubesos`](https://gitlab.com/gitlab-com/support/toolbox/kubesos/) if you installed GitLab using the Helm Charts. +1. Roll back to the last working version. -### Restore GitLab +For support: -If you have a test environment that mimics your production one, you should test the restoration to ensure that everything works as you expect. - -To restore your GitLab backup: - -- Before restoring, make sure to read about the - [prerequisites](../administration/backup_restore/_index.md#restore-gitlab), most importantly, - the versions of the backed up and the new GitLab instance must be the same. -- [Restore GitLab](../administration/backup_restore/_index.md#restore-gitlab). - Make sure to follow the instructions based on your installation method. - Confirm that the [secrets and configuration files](../administration/backup_restore/backup_gitlab.md#storing-configuration-files) are also restored. -- If restoring from a snapshot, know the steps to do this. - **This process is out of scope for GitLab Support**. +- [Contact GitLab Support](https://support.gitlab.com/hc/en-us) and your Customer Success Manager, if you have one. +- If [the situation qualifies](https://about.gitlab.com/support/#definitions-of-support-impact) and + [your plan includes emergency support](https://about.gitlab.com/support/#priority-support), + create an emergency ticket. diff --git a/doc/update/upgrade.md b/doc/update/upgrade.md index 1fbe238528f57767d096d4d396cfca9ac69e8142..c34783af1ede489f6538ed9545fd19db86214342 100644 --- a/doc/update/upgrade.md +++ b/doc/update/upgrade.md @@ -13,138 +13,17 @@ description: Upgrade steps for all installation methods. {{< /details >}} -Upgrade a GitLab instance to take advantage of new features and bug fixes. +Upgrade a single-node GitLab instance to take advantage of new features and bug fixes. You can also upgrade multi-node +GitLab instances with or without downtime. -Before you upgrade, consult [information you need before you upgrade](plan_your_upgrade.md). +{{< cards >}} -## Upgrade GitLab +- [Single-node Linux package instances](package/_index.md) +- [Single-node Docker instances](docker/_index.md) +- [Single-node self-compiled instances](upgrading_from_source.md) +- [GitLab Helm chart instances](https://docs.gitlab.com/charts/installation/upgrade/ "Upgrade GitLab Helm chart instance.") +- [GitLab Operator instances](https://docs.gitlab.com/operator/gitlab_upgrades/ "Upgrade GitLab instance with GitLab Operator.") +- [Multi-node GitLab instance with downtime](with_downtime.md) +- [Multi-node GitLab instance with zero downtime](zero_downtime.md) -To upgrade GitLab: - -1. If available in your starting version, consider [turning on maintenance mode](../administration/maintenance_mode/_index.md) - during the upgrade. -1. Pause [running CI/CD pipelines and jobs](#cicd-pipelines-and-jobs-during-upgrades). -1. Follow the [upgrade steps based on your installation method](#upgrade-based-on-installation-method). -1. If your GitLab instance has any runners associated with it, upgrade them to match the current GitLab version. - This step ensures [compatibility with GitLab versions](https://docs.gitlab.com/runner/#gitlab-runner-versions). -1. [Disable maintenance mode](../administration/maintenance_mode/_index.md#disable-maintenance-mode) if you had enabled - it. -1. Unpause [running CI/CD pipelines and jobs](#cicd-pipelines-and-jobs-during-upgrades). -1. Run [upgrade health checks](plan_your_upgrade.md#run-upgrade-health-checks). - -## Upgrade based on installation method - -Depending on the installation method and your GitLab version, there are multiple -official ways to upgrade GitLab: - -{{< tabs >}} - -{{< tab title="Linux packages (Omnibus)" >}} - -As part of a GitLab upgrade, the [Linux package upgrade guide](package/_index.md) contains the specific steps to follow -to upgrade a Linux package instance. - -{{< /tab >}} - -{{< tab title="Helm chart (Kubernetes)" >}} - -GitLab can be deployed into a Kubernetes cluster using Helm. For production deployments, -the setup follows the [Cloud Native Hybrid](../administration/reference_architectures/_index.md#cloud-native-hybrid) -guidance where stateless components of cloud-native GitLab run in Kubernetes with -the GitLab Helm chart, and stateful components are deployed in compute VMs with the -Linux package. - -Use the [version mapping](https://docs.gitlab.com/charts/installation/version_mappings.html) -from the chart version to GitLab version to determine the [upgrade path](upgrade_paths.md). - -Follow [Multi-node upgrades with downtime](with_downtime.md) to perform the upgrade in a Cloud Native Hybrid setup. - -A full cloud-native deployment is [not supported](../administration/reference_architectures/_index.md#stateful-components-in-kubernetes) -for production. However, instructions on how to upgrade such an environment are in -[a separate document](https://docs.gitlab.com/charts/installation/upgrade.html). - -{{< /tab >}} - -{{< tab title="Docker" >}} - -GitLab provides official Docker images for both Community and Enterprise -editions, and they are based on the Linux package. See how to -[install GitLab using Docker](../install/docker/_index.md). - -{{< /tab >}} - -{{< tab title="Self-compiled (source)" >}} - -- [Upgrading Community Edition and Enterprise Edition from source](upgrading_from_source.md): - The guidelines for upgrading Community Edition and Enterprise Edition from source. -- [Patch versions](patch_versions.md) guide includes the steps needed for a - patch version, such as 15.2.0 to 15.2.1, and apply to both Community and Enterprise - Editions. - -In the past we used separate documents for the upgrading instructions, but we -have switched to using a single document. The old upgrading guidelines -can still be found in the Git repository: - -- [Old upgrading guidelines for Community Edition](https://gitlab.com/gitlab-org/gitlab-foss/tree/11-8-stable/doc/update) -- [Old upgrading guidelines for Enterprise Edition](https://gitlab.com/gitlab-org/gitlab/-/tree/11-8-stable-ee/doc/update) - -{{< /tab >}} - -{{< /tabs >}} - -## CI/CD pipelines and jobs during upgrades - -If you upgrade your GitLab instance while the GitLab Runner is processing jobs, the trace updates fail. When GitLab is back online, the trace updates should self-heal. However, depending on the error, the GitLab Runner either retries, or eventually terminates, job handling. - -As for the artifacts, the GitLab Runner attempts to upload them three times, after which the job eventually fails. - -To address the two previous scenarios, it is advised to do the following prior to upgrading: - -1. Plan your maintenance. -1. Pause your runners, or block new jobs from starting by adding the following to your `/etc/gitlab/gitlab.rb`: - - ```ruby - nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n deny all;\n return 503;\n}\n" - ``` - - And reconfigure GitLab with: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -1. Wait until all jobs are finished. -1. Upgrade GitLab. -1. [Upgrade GitLab Runner](https://docs.gitlab.com/runner/install/) to the same version - as your GitLab version. Both versions [should be the same](https://docs.gitlab.com/runner/#gitlab-runner-versions). -1. Unpause your runners and unblock new jobs from starting by reverting the previous `/etc/gitlab/gitlab.rb` change. - -## Upgrading between editions - -GitLab comes in two flavors: [Community Edition](https://about.gitlab.com/features/#community) which is MIT licensed, -and [Enterprise Edition](https://about.gitlab.com/features/#enterprise) which builds on top of the Community Edition and -includes extra features mainly aimed at organizations with more than 100 users. - -In the following section you can find some guides to help you change GitLab editions. - -## Getting support - -If something goes wrong: - -- Copy any errors and gather any logs to later analyze, and then [roll back to the last working version](plan_your_upgrade.md#rollback-plan). - You can use the following tools to help you gather data: - - [`gitlabsos`](https://gitlab.com/gitlab-com/support/toolbox/gitlabsos) if - you installed GitLab using the Linux package or Docker. - - [`kubesos`](https://gitlab.com/gitlab-com/support/toolbox/kubesos/) if - you installed GitLab using the Helm Charts. - -For support: - -- [Contact GitLab Support](https://support.gitlab.com/hc/en-us) and, if you have one, your Customer Success Manager. -- If [the situation qualifies](https://about.gitlab.com/support/#definitions-of-support-impact) and - [your plan includes emergency support](https://about.gitlab.com/support/#priority-support), - create an emergency ticket. - -## Related topics - -- [Managing PostgreSQL extensions](../install/postgresql_extensions.md) +{{< /cards >}} diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md index 2066b578fb30614023c91fffae86a87075ba0be3..cad15398c513619214364b7e6fb3c8482d11725c 100644 --- a/doc/update/upgrading_from_source.md +++ b/doc/update/upgrading_from_source.md @@ -3,7 +3,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 self-compiled instances -description: Upgrade a self-compiled instance. +description: Upgrade a single-node self-compiled instance. --- {{< details >}} @@ -15,33 +15,30 @@ description: Upgrade a self-compiled instance. Upgrade a self-compiled installation to a later version of GitLab. -To upgrade a self-compiled GitLab instance: - -1. [Create a backup](#create-a-backup). -1. [Stop GitLab](#stop-gitlab). -1. [Update Ruby](#update-ruby). -1. [Update Node.js](#update-nodejs). -1. [Update Go](#update-go). -1. [Update Git](#update-git). -1. [Update PostgreSQL](#update-postgresql). -1. [Update the GitLab codebase](#update-the-gitlab-codebase). -1. [Update configuration files](#update-configuration-files). -1. [Install libraries and run migrations](#install-libraries-and-run-migrations). -1. [Update GitLab Shell](#update-gitlab-shell). -1. [Update GitLab Workhorse](#update-gitlab-workhorse). -1. [Update Gitaly](#update-gitaly). -1. [Update GitLab Pages](#update-gitlab-pages). -1. [Perform post-upgrade steps](#post-upgrade-steps). - ## Prerequisites Before you upgrade: -- Consult [information you need before you upgrade](plan_your_upgrade.md). -- Review the [software requirements](../install/self_compiled/_index.md#software-requirements) for Ruby, Node.js, Go, - and PostgreSQL. +1. Consult [information you need before you upgrade](plan_your_upgrade.md). +1. Review the [software requirements](../install/self_compiled/_index.md#software-requirements) for Ruby, Node.js, Go, + and PostgreSQL. + +## Upgrade GitLab + +To upgrade GitLab: + +1. Consider [turning on maintenance mode](../administration/maintenance_mode/_index.md) during the upgrade. +1. Pause [running CI/CD pipelines and jobs](plan_your_upgrade.md#pause-cicd-pipelines-and-jobs). +1. [Upgrade GitLab Runner](https://docs.gitlab.com/runner/install/) to the same version as your target GitLab version. +1. Upgrade GitLab by following the instructions on this page. + +After you upgrade: + +1. Unpause [running CI/CD pipelines and jobs](plan_your_upgrade.md#pause-cicd-pipelines-and-jobs). +1. If enabled, [turn off maintenance mode](../administration/maintenance_mode/_index.md#disable-maintenance-mode). +1. Run [upgrade health checks](plan_your_upgrade.md#run-upgrade-health-checks). -## Create a backup +### Create a backup Prerequisites: @@ -55,7 +52,7 @@ cd /home/git/gitlab sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production ``` -## Stop GitLab +### Stop GitLab To stop GitLab: @@ -67,7 +64,7 @@ sudo systemctl stop gitlab.target sudo service gitlab stop ``` -## Update Ruby +### Update Ruby If a newer version of Ruby is required, you must update Ruby: @@ -80,7 +77,7 @@ If a newer version of Ruby is required, you must update Ruby: 1. For instructions on updating to newer versions of Ruby, see [Ruby installation instructions](https://www.ruby-lang.org/en/documentation/installation/). -## Update Node.js +### Update Node.js If a newer version of Node.js is required, you must update Node.js: @@ -96,7 +93,7 @@ If a newer version of Node.js is required, you must update Node.js: GitLab also requires Yarn `>= v1.10.0` to manage JavaScript dependencies. For more information, see the [Yarn website](https://classic.yarnpkg.com/en/docs/install). -## Update Go +### Update Go If a newer version of Go is required, you must update Go: @@ -109,12 +106,12 @@ If a newer version of Go is required, you must update Go: 1. For instructions on updating to newer versions of Go, see [Go installation instructions](https://go.dev/doc/install). -## Update Git +### Update Git You should use the Git version provided by Gitaly. For more information, see [GitLab installation instructions for Git](../install/self_compiled/_index.md#git). -## Update PostgreSQL +### Update PostgreSQL If a newer version of PostgreSQL is required, you must update PostgreSQL: @@ -128,7 +125,7 @@ If a newer version of PostgreSQL is required, you must update PostgreSQL: [PostgreSQL upgrading documentation](https://www.postgresql.org/docs/16/upgrading.html). 1. Make sure you have the required [PostgreSQL extensions](../install/requirements.md#postgresql). -## Update the GitLab codebase +### Update the GitLab codebase To update your clone of the GitLab codebase: @@ -167,7 +164,7 @@ To update your clone of the GitLab codebase: {{< /tabs >}} -## Update configuration files +### Update configuration files GitLab upgrades might require updates to the following configuration: @@ -180,7 +177,7 @@ GitLab upgrades might require updates to the following configuration: The following sections document how to determine if configuration updates are required. -### New configuration for `gitlab.yml` +#### New configuration for `gitlab.yml` There might be new configuration options available for [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example). @@ -194,7 +191,7 @@ There might be new configuration options available for 1. Apply new configuration manually to your current `gitlab.yml`. -### New configuration for `database.yml` +#### New configuration for `database.yml` {{< history >}} @@ -214,7 +211,7 @@ There might be new configuration options available for 1. Apply new configuration manually to your current `database.yml`. -### New configuration for NGINX or Apache +#### New configuration for NGINX or Apache Ensure you're still up-to-date with the latest NGINX configuration changes: @@ -235,7 +232,7 @@ If you are using Apache instead of NGINX, see the updated [Apache templates](htt Because Apache does not support upstreams behind Unix sockets, you must let GitLab Workhorse listen on a TCP port by using [`/etc/default/gitlab`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/support/init.d/gitlab.default.example#L38). -### SMTP configuration +#### SMTP configuration If you use SMTP to deliver mail, you must add the following line to `config/initializers/smtp_settings.rb`: @@ -246,7 +243,7 @@ ActionMailer::Base.delivery_method = :smtp See [`smtp_settings.rb.sample`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/initializers/smtp_settings.rb.sample#L13) for an example. -### Configure systemd units +#### Configure systemd units 1. Check if the systemd units have been updated: @@ -264,7 +261,7 @@ for an example. sudo systemctl daemon-reload ``` -### Configure SysV init script +#### Configure SysV init script There might be new configuration options available for [`gitlab.default.example`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/support/init.d/gitlab.default.example). @@ -293,7 +290,7 @@ If you are using the init script on a system running systemd as init, because yo sudo systemctl daemon-reload ``` -## Install libraries and run migrations +### Install libraries and run migrations To install libraries and run migrations: @@ -326,7 +323,7 @@ To install libraries and run migrations: sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production ``` -## Update GitLab Shell +### Update GitLab Shell To update GitLab Shell, run these commands: @@ -338,7 +335,7 @@ sudo -u git -H git checkout v$(}} @@ -65,7 +66,7 @@ kubectl scale deploy -n -l release= -l 'app in (p Follow instructions for [upgrading the Consul nodes](../administration/consul.md#upgrade-the-consul-nodes). In summary: 1. Check the Consul nodes are all healthy. -1. [Upgrade GitLab](package/_index.md) on all Consul servers. +1. Upgrade all Consul servers by following the [single-node Linux package upgrade instructions](package/_index.md#upgrade-gitlab). 1. Restart all GitLab services **one node at a time**: ```shell @@ -80,8 +81,8 @@ Patroni. In this case, when upgrading those servers: ## Upgrade Gitaly and Gitaly Cluster (Praefect) -For Gitaly servers that are not part of Gitaly Cluster (Praefect), -[upgrade GitLab](package/_index.md). If you have multiple Gitaly shards, you can upgrade +For Gitaly servers that are not part of Gitaly Cluster (Praefect), upgrade the server +by following the [single-node Linux package upgrade instructions](package/_index.md#upgrade-gitlab). If you have multiple Gitaly shards, you can upgrade the Gitaly servers in any order. If you're running Gitaly Cluster (Praefect), follow the @@ -110,7 +111,7 @@ To upgrade Gitaly Cluster (Praefect) nodes by using an AMI redeployment process: For non-clustered PostgreSQL servers: -1. [Upgrade GitLab](package/_index.md). +1. Upgrade the server by following the [single-node Linux package upgrade instructions](package/_index.md#upgrade-gitlab). 1. Because the upgrade process does not restart PostgreSQL when the binaries are upgraded, restart to load the new version: ```shell @@ -138,7 +139,7 @@ To upgrade Patroni nodes: sudo gitlab-ctl patroni members ``` -1. [Upgrade GitLab](package/_index.md) on one of the replica nodes. +1. Upgrade one of the replica nodes by following the [single-node Linux package upgrade instructions](package/_index.md#upgrade-gitlab). 1. Restart to load the new version: ```shell @@ -159,13 +160,13 @@ To upgrade Patroni nodes: ## Upgrade the PgBouncer nodes If you run PgBouncer on your GitLab application (Rails) nodes, then PgBouncer is upgraded as part of the -application server upgrade. Otherwise, [upgrade GitLab](package/_index.md) on the -PgBouncer nodes. +application server upgrade. Otherwise, upgrade the PgBouncer nodes by following the +[single-node Linux package upgrade instructions](package/_index.md#upgrade-gitlab). ## Upgrade the Redis node -Upgrade a standalone Redis server by [upgrading GitLab](package/_index.md) on the Redis -node. +To upgrade a standalone Redis server, follow the +[single-node Linux package upgrade instructions](package/_index.md#upgrade-gitlab). ### Upgrade Redis HA (using Sentinel) @@ -229,7 +230,7 @@ deploy node: sudo gitlab-ctl reconfigure ``` -1. [Upgrade GitLab](package/_index.md). +1. Upgrade GitLab by following the [single-node Linux package upgrade instructions](package/_index.md#upgrade-gitlab). 1. If you modified `gitlab.rb` on the deploy node to bypass PgBouncer: 1. Update `gitlab.rb` on the deploy node. Change `gitlab_rails['db_host']` and `gitlab_rails['db_port']` back to your PgBouncer settings. @@ -251,7 +252,7 @@ set to anything in `gitlab.rb` on these nodes. They can be upgraded in parallel: -1. [Upgrade GitLab](package/_index.md). +1. Upgrade GitLab by following the [single-node Linux package upgrade instructions](package/_index.md#upgrade-gitlab). 1. Ensure all services are restarted: ```shell @@ -283,4 +284,4 @@ kubectl scale deploy -lapp=prometheus,release= -n You might have configured Prometheus to act as a standalone monitoring node. For example, as part of [configuring a 60 RPS or 3,000 users reference architecture](../administration/reference_architectures/3k_users.md#configure-prometheus). -To upgrade the monitor node, [upgrade GitLab](package/_index.md) on the node. +To upgrade the monitor node, follow the [single-node Linux package upgrade instructions](package/_index.md#upgrade-gitlab). diff --git a/doc/update/zero_downtime.md b/doc/update/zero_downtime.md index 682691025b5351587eeac3b2a08d22c1068da720..344e206d62a16ca8492148de4d124484317ae1d1 100644 --- a/doc/update/zero_downtime.md +++ b/doc/update/zero_downtime.md @@ -3,6 +3,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 a multi-node instance with zero downtime +description: Upgrade a multi-node Linux package-based with zero downtime. --- {{< details >}} @@ -120,7 +121,7 @@ On each component's node to perform the upgrade: sudo touch /etc/gitlab/skip-auto-reconfigure ``` -1. [Upgrade the GitLab package](package/_index.md). +1. Upgrade the node by following the [single-node Linux package upgrade instructions](package/_index.md#upgrade-gitlab). 1. Reconfigure and restart to get the latest code in place: ```shell @@ -154,15 +155,7 @@ On each component's node to perform the upgrade: [Gitaly](../administration/gitaly/_index.md) follows the same core process when it comes to upgrading but with a key difference that the Gitaly process itself is not restarted as it has a built-in process to gracefully reload -at the earliest opportunity. Other components will still need to be restarted. - -{{< alert type="note" >}} - -The upgrade process attempts to do a graceful handover to a new Gitaly process. -Existing long-running Git requests that were started before the upgrade may eventually be dropped as this handover occurs. -In the future this functionality may be changed, [refer to this Epic](https://gitlab.com/groups/gitlab-org/-/epics/10328) for more information. - -{{< /alert >}} +at the earliest opportunity. Other components must still be restarted. This process applies to both Gitaly Sharded and Cluster setups. Run through the following steps sequentially on each Gitaly node to perform the upgrade: @@ -172,14 +165,14 @@ This process applies to both Gitaly Sharded and Cluster setups. Run through the sudo touch /etc/gitlab/skip-auto-reconfigure ``` -1. [Upgrade the GitLab package](package/_index.md). +1. Upgrade the node by following the [single-node Linux package upgrade instructions](package/_index.md#upgrade-gitlab). 1. Run the `reconfigure` command to get the latest code in place and to instruct Gitaly to gracefully reload at the next opportunity: ```shell sudo gitlab-ctl reconfigure ``` -1. Finally, while Gitaly will gracefully reload any other components that have been deployed, we will still need a restart: +1. Finally, while Gitaly gracefully reloads any other components that have been deployed, we still need a restart: ```shell # Get a list of what other components have been deployed beside Gitaly @@ -208,9 +201,7 @@ This section focuses exclusively on the Praefect component, not its [required Po {{< /alert >}} Praefect must also perform database migrations to upgrade any existing data. To avoid clashes, -migrations should run on only one Praefect node. To do this, designate a specific node as a -deploy node that runs the migrations. This is referred to as -the **Praefect deploy node** in the following steps: +migrations should run on only one Praefect node. To do this, designate a **Praefect deploy node** that runs the migrations: 1. On the **Praefect deploy node**: @@ -221,10 +212,8 @@ the **Praefect deploy node** in the following steps: sudo touch /etc/gitlab/skip-auto-reconfigure ``` - 1. [Upgrade the GitLab package](package/_index.md). - + 1. Upgrade the node by following the [single-node Linux package upgrade instructions](package/_index.md#upgrade-gitlab). 1. Ensure that `praefect['auto_migrate'] = true` is set in `/etc/gitlab/gitlab.rb` so that database migrations run. - 1. Run the `reconfigure` command to get the latest code in place, apply the Praefect database migrations and restart gracefully: ```shell @@ -240,18 +229,16 @@ the **Praefect deploy node** in the following steps: sudo touch /etc/gitlab/skip-auto-reconfigure ``` - 1. [Upgrade the GitLab package](package/_index.md). - + 1. Upgrade the node by following the [single-node Linux package upgrade instructions](package/_index.md#upgrade-gitlab). 1. Ensure that `praefect['auto_migrate'] = false` is set in `/etc/gitlab/gitlab.rb` to prevent `reconfigure` from automatically running database migrations. - - 1. Run the `reconfigure` command to get the latest code in place as well as restart gracefully: + 1. Run the `reconfigure` command to get the latest code in place and restart gracefully: ```shell sudo gitlab-ctl reconfigure ``` -1. Finally, while Praefect will gracefully reload, any other components that have been deployed will still need a restart. +1. Finally, while Praefect gracefully reloads, any other components that have been deployed still need a restart. On all **Praefect nodes**: ```shell @@ -297,11 +284,10 @@ In addition to the previous, Rails is where the main database migrations need to sudo touch /etc/gitlab/skip-auto-reconfigure ``` - 1. [Upgrade the GitLab package](package/_index.md). - + 1. Upgrade GitLab by following the [single-node Linux package upgrade instructions](package/_index.md#upgrade-gitlab). 1. Configure regular migrations to run by setting `gitlab_rails['auto_migrate'] = true` in the `/etc/gitlab/gitlab.rb` configuration file. - - If the deploy node is currently going through PgBouncer to reach the database then + - If the deploy node is going through PgBouncer to reach the database then you must [bypass it](../administration/postgresql/pgbouncer.md#procedure-for-bypassing-pgbouncer) and connect directly to the database leader before running migrations. - To find the database leader you can run the following command on any database node - `sudo gitlab-ctl patroni members`. @@ -312,8 +298,7 @@ In addition to the previous, Rails is where the main database migrations need to sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-ctl reconfigure ``` - 1. Leave this node as-is for now as you'll come back to run post-deployment migrations - later. + 1. Leave this node as-is for now as you come back to run post-deployment migrations later. 1. On every **other Rails node** sequentially: @@ -339,12 +324,10 @@ In addition to the previous, Rails is where the main database migrations need to sudo touch /etc/gitlab/skip-auto-reconfigure ``` - 1. [Upgrade the GitLab package](package/_index.md). - + 1. Upgrade GitLab by following the [single-node Linux package upgrade instructions](package/_index.md#upgrade-gitlab). 1. Ensure that `gitlab_rails['auto_migrate'] = false` is set in `/etc/gitlab/gitlab.rb` to prevent `reconfigure` from automatically running database migrations. - - 1. Run the `reconfigure` command to get the latest code in place as well as restart: + 1. Run the `reconfigure` command to get the latest code in place and restart: ```shell sudo gitlab-ctl reconfigure @@ -354,7 +337,7 @@ In addition to the previous, Rails is where the main database migrations need to 1. On the **Rails deploy node** run the post-deployment migrations: 1. Ensure the deploy node is still pointing at the database leader directly. If the node - is currently going through PgBouncer to reach the database then you must + is going through PgBouncer to reach the database then you must [bypass it](../administration/postgresql/pgbouncer.md#procedure-for-bypassing-pgbouncer) and connect directly to the database leader before running migrations. - To find the database leader you can run the following command on any database node - `sudo gitlab-ctl patroni members`. @@ -367,11 +350,11 @@ In addition to the previous, Rails is where the main database migrations need to This task also runs ClickHouse migrations and configures the database based on its state by loading the schema. - 1. Return the config back to normal by setting `gitlab_rails['auto_migrate'] = false` in the + 1. Return the configuration back to normal by setting `gitlab_rails['auto_migrate'] = false` in the `/etc/gitlab/gitlab.rb` configuration file. - - If PgBouncer is being used make sure to set the database config to once again point towards it + - If PgBouncer is being used make sure to set the database configuration to once again point towards it - 1. Run through reconfigure once again to reapply the normal config as well as restart: + 1. Run through reconfigure once again to reapply the normal configuration and restart: ```shell sudo gitlab-ctl reconfigure @@ -390,9 +373,8 @@ Run through the following steps sequentially on each component node to perform t sudo touch /etc/gitlab/skip-auto-reconfigure ``` -1. [Upgrade the GitLab package](package/_index.md). - -1. Run the `reconfigure` command to get the latest code in place as well as restart: +1. Upgrade the node by following the [single-node Linux package upgrade instructions](package/_index.md#upgrade-gitlab). +1. Run the `reconfigure` command to get the latest code in place and restart: ```shell sudo gitlab-ctl reconfigure @@ -468,14 +450,11 @@ The upgrade process is the same for both primary and secondary sites. However, y sudo touch /etc/gitlab/skip-auto-reconfigure ``` - 1. [Upgrade the GitLab package](package/_index.md). - + 1. Upgrade GitLab by following the [single-node Linux package upgrade instructions](package/_index.md#upgrade-gitlab). 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the primary site Rails node to the secondary site Rails node if they're different. The file must be the same on all of a site's nodes. - 1. Ensure no migrations are configured to be run automatically by setting `gitlab_rails['auto_migrate'] = false` and `geo_secondary['auto_migrate'] = false` in the `/etc/gitlab/gitlab.rb` configuration file. - - 1. Run the `reconfigure` command to get the latest code in place as well as restart: + 1. Run the `reconfigure` command to get the latest code in place and restart: ```shell sudo gitlab-ctl reconfigure @@ -518,12 +497,10 @@ The upgrade process is the same for both primary and secondary sites. However, y sudo touch /etc/gitlab/skip-auto-reconfigure ``` - 1. [Upgrade the GitLab package](package/_index.md). - + 1. Upgrade GitLab by following the [single-node Linux package upgrade instructions](package/_index.md#upgrade-gitlab). 1. Ensure no migrations are configured to be run automatically by setting `gitlab_rails['auto_migrate'] = false` and `geo_secondary['auto_migrate'] = false` in the `/etc/gitlab/gitlab.rb` configuration file. - - 1. Run the `reconfigure` command to get the latest code in place as well as restart: + 1. Run the `reconfigure` command to get the latest code in place and restart: ```shell sudo gitlab-ctl reconfigure @@ -543,7 +520,7 @@ Finally, head back to the primary site and finish the upgrade by running the pos 1. On the Primary site's **Rails deploy node** run the post-deployment migrations: 1. Ensure the deploy node is still pointing at the database leader directly. If the node - is currently going through PgBouncer to reach the database then you must + is going through PgBouncer to reach the database then you must [bypass it](../administration/postgresql/pgbouncer.md#procedure-for-bypassing-pgbouncer) and connect directly to the database leader before running migrations. - To find the database leader you can run the following command on any database node - `sudo gitlab-ctl patroni members`. @@ -560,11 +537,11 @@ Finally, head back to the primary site and finish the upgrade by running the pos sudo gitlab-rake gitlab:geo:check ``` - 1. Return the config back to normal by setting `gitlab_rails['auto_migrate'] = false` in the + 1. Return the configuration back to normal by setting `gitlab_rails['auto_migrate'] = false` in the `/etc/gitlab/gitlab.rb` configuration file. - - If PgBouncer is being used make sure to set the database config to once again point towards it + - If PgBouncer is being used make sure to set the database configuration to once again point towards it - 1. Run through reconfigure once again to reapply the normal config as well as restart: + 1. Run through reconfigure once again to reapply the normal configuration and restart: ```shell sudo gitlab-ctl reconfigure