diff options
Diffstat (limited to 'doc/update')
| -rw-r--r-- | doc/update/deprecations.md | 173 | ||||
| -rw-r--r-- | doc/update/index.md | 69 | ||||
| -rw-r--r-- | doc/update/package/index.md | 7 | ||||
| -rw-r--r-- | doc/update/plan_your_upgrade.md | 5 | ||||
| -rw-r--r-- | doc/update/removals.md | 47 | ||||
| -rw-r--r-- | doc/update/upgrading_from_source.md | 2 | ||||
| -rw-r--r-- | doc/update/zero_downtime.md | 43 |
7 files changed, 270 insertions, 76 deletions
diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md index b69f8de2947..44a7137f698 100644 --- a/doc/update/deprecations.md +++ b/doc/update/deprecations.md @@ -45,24 +45,91 @@ sole discretion of GitLab Inc. <div class="announcement-milestone"> -## Announced in 15.8 +## Announced in 15.4 <div class="deprecation removal-160 breaking-change"> -### Security report schemas version 14.x.x +### Container Scanning variables that reference Docker + +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +All Container Scanning variables that are prefixed by `DOCKER_` in variable name are deprecated. This includes the `DOCKER_IMAGE`, `DOCKER_PASSWORD`, `DOCKER_USER`, and `DOCKERFILE_PATH` variables. Support for these variables will be removed in the GitLab 16.0 release. Use the [new variable names](https://docs.gitlab.com/ee/user/application_security/container_scanning/#available-cicd-variables) `CS_IMAGE`, `CS_REGISTRY_PASSWORD`, `CS_REGISTRY_USER`, and `CS_DOCKERFILE_PATH` in place of the deprecated names. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Non-expiring access tokens + +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +Access tokens that have no expiration date are valid indefinitely, which presents a security risk if the access token +is divulged. Because access tokens that have an exipiration date are better, from GitLab 15.3 we +[populate a default expiration date](https://gitlab.com/gitlab-org/gitlab/-/issues/348660). + +In GitLab 16.0, any [personal](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html), +[project](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html), or +[group](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html) access token that does not have an +expiration date will automatically have an expiration date set at one year. + +We recommend giving your access tokens an expiration date in line with your company's security policies before the +default is applied: + +- On GitLab.com during the 16.0 milestone. +- On GitLab self-managed instances when they are upgraded to 16.0. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Starboard directive in the config for the GitLab Agent for Kubernetes -End of Support: GitLab <span class="removal-milestone">15.8</span> (2023-01-22) Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). Review the details carefully before upgrading. -All [security report schema](https://gitlab.com/gitlab-org/security-products/security-report-schemas) versions before 15.0.0 are considered deprecated in GitLab %15.8. Specifically, all [schemas](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/lib/ee/gitlab/ci/parsers/security/validators/schemas) that match 14.*.* will be deprecated. +GitLab's operational container scanning capabilities no longer require starboard to be installed. Consequently, use of the `starboard:` directive in the configuration file for the GitLab Agent for Kubernetes is now deprecated and is scheduled for removal in GitLab 16.0. Update your configuration file to use the `container_scanning:` directive. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Toggle behavior of `/draft` quick action in merge requests + +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2022-05-22) -Please note that any [security report scanner integration](https://docs.gitlab.com/ee/development/integrations/secure.html) with GitLab using a deprecated schema version will result in a deprecation warning as a result of [report validation](https://docs.gitlab.com/ee/development/integrations/secure.html#report-validation). +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. -See [Security report validation](https://docs.gitlab.com/ee/user/application_security/#security-report-validation) for more information. +In order to make the behavior of toggling the draft status of a merge request more clear via a quick action, we're deprecating and removing the toggle behavior of the `/draft` quick action. Beginning with the 16.0 release of GitLab, `/draft` will only set a merge request to Draft and a new `/ready` quick action will be used to remove the draft status. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Vulnerability confidence field + +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +In GitLab 15.3, [security report schemas below version 15 were deprecated](https://docs.gitlab.com/ee/update/deprecations.html#security-report-schemas-version-14xx). +The `confidence` attribute on vulnerability findings exists only in schema versions before `15-0-0`, and therefore is effectively deprecated since GitLab 15.4 supports schema version `15-0-0`. To maintain consistency +between the reports and our public APIs, the `confidence` attribute on any vulnerability-related components of our GraphQL API is now deprecated and will be +removed in 16.0. </div> </div> @@ -88,6 +155,20 @@ next major release, GitLab 16.0. This gem sees very little use and its </div> +<div class="deprecation removal-154"> + +### Bundled Grafana deprecated + +Planned removal: GitLab <span class="removal-milestone">15.4</span> (2022-09-22) + +In GitLab 15.4, we will be swapping the bundled Grafana to a fork of Grafana maintained by GitLab. + +There was an [identified CVE for Grafana](https://nvd.nist.gov/vuln/detail/CVE-2022-31107), and to mitigate this security vulnerability, we must swap to our own fork because the older version of Grafana we were bundling is no longer receiving long-term support. + +This is not expected to cause any incompatibilities with the previous version of Grafana. Neither when using our bundled version, nor when using an external instance of Grafana. + +</div> + <div class="deprecation removal-160 breaking-change"> ### CAS OmniAuth provider @@ -121,7 +202,7 @@ The [**Maximum number of active pipelines per project** limit](https://docs.gitl ### Redis 5 deprecated -End of Support: GitLab <span class="removal-milestone">15.6</span> (2022-11-22) +End of Support: GitLab <span class="removal-milestone">15.6</span> (2022-11-22)<br /> Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) WARNING: @@ -133,6 +214,40 @@ Redis 5 has reached the end of life in April 2022 and will no longer be supporte If you are using your own Redis 5.0 instance, you should upgrade it to Redis 6.0 or higher before upgrading to GitLab 16.0 or higher. </div> + +<div class="deprecation removal-160 breaking-change"> + +### Security report schemas version 14.x.x + +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +Version 14.x.x [security report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas) are deprecated. + +In GitLab 15.8 and later, [security report scanner integrations](https://docs.gitlab.com/ee/development/integrations/secure.html) that use schema version 14.x.x will display a deprecation warning in the pipeline's **Security** tab. + +In GitLab 16.0 and later, the feature will be removed. Security reports that use schema version 14.x.x will cause an error in the pipeline's **Security** tab. + +For more information, refer to [security report validation](https://docs.gitlab.com/ee/user/application_security/#security-report-validation). + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### Use of `id` field in vulnerabilityFindingDismiss mutation + +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +You can use the vulnerabilityFindingDismiss GraphQL mutation to set the status of a vulnerability finding to `Dismissed`. Previously, this mutation used the `id` field to identify findings uniquely. However, this did not work for dismissing findings from the pipeline security tab. Therefore, using the `id` field as an identifier has been dropped in favor of the `uuid` field. Using the 'uuid' field as an identifier allows you to dismiss the finding from the pipeline security tab. + +</div> </div> <div class="announcement-milestone"> @@ -337,38 +452,6 @@ In GitLab 15.0, for Dependency Scanning, the default version of Java that the sc </div> -<div class="deprecation removal-160 breaking-change"> - -### Manual iteration management - -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-04-22) - -WARNING: -This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). -Review the details carefully before upgrading. - -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). - -</div> - <div class="deprecation removal-150 breaking-change"> ### Outdated indices of Advanced Search migrations @@ -1757,17 +1840,17 @@ When checking if a runner is `paused`, API users are advised to check the boolea </div> -<div class="deprecation removal-156 breaking-change"> +<div class="deprecation removal-159 breaking-change"> ### SaaS certificate-based integration with Kubernetes -Planned removal: GitLab <span class="removal-milestone">15.6</span> (2022-11-22) +Planned removal: GitLab <span class="removal-milestone">15.9</span> (2023-02-22) WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). Review the details carefully before upgrading. -The certificate-based integration with Kubernetes will be [deprecated and removed](https://about.gitlab.com/blog/2021/11/15/deprecating-the-cert-based-kubernetes-integration/). As a GitLab SaaS customer, on new namespaces, you will no longer be able to integrate GitLab and your cluster using the certificate-based approach as of GitLab 15.0. The integration for current users will be enabled per namespace. The integrations are expected to be switched off completely on GitLab SaaS around 2022 November 22. +The certificate-based integration with Kubernetes will be [deprecated and removed](https://about.gitlab.com/blog/2021/11/15/deprecating-the-cert-based-kubernetes-integration/). As a GitLab SaaS customer, on new namespaces, you will no longer be able to integrate GitLab and your cluster using the certificate-based approach as of GitLab 15.0. The integration for current users will be enabled per namespace. For a more robust, secure, forthcoming, and reliable integration with Kubernetes, we recommend you use the [agent for Kubernetes](https://docs.gitlab.com/ee/user/clusters/agent/) to connect Kubernetes clusters with GitLab. [How do I migrate?](https://docs.gitlab.com/ee/user/infrastructure/clusters/migrate_to_gitlab_agent.html) @@ -1778,11 +1861,11 @@ GitLab self-managed customers can still use the feature [with a feature flag](ht </div> -<div class="deprecation removal-160 breaking-change"> +<div class="deprecation removal-170 breaking-change"> ### Self-managed certificate-based integration with Kubernetes -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">17.0</span> (2024-05-22) WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). @@ -1792,7 +1875,7 @@ The certificate-based integration with Kubernetes [will be deprecated and remove As a self-managed customer, we are introducing the [feature flag](../administration/feature_flags.md#enable-or-disable-the-feature) `certificate_based_clusters` in GitLab 15.0 so you can keep your certificate-based integration enabled. However, the feature flag will be disabled by default, so this change is a **breaking change**. -In GitLab 16.0 we will remove both the feature and its related code. Until the final removal in 16.0, features built on this integration will continue to work, if you enable the feature flag. Until the feature is removed, GitLab will continue to fix security and critical issues as they arise. +In GitLab 17.0 we will remove both the feature and its related code. Until the final removal in 17.0, features built on this integration will continue to work, if you enable the feature flag. Until the feature is removed, GitLab will continue to fix security and critical issues as they arise. For a more robust, secure, forthcoming, and reliable integration with Kubernetes, we recommend you use the [agent for Kubernetes](https://docs.gitlab.com/ee/user/clusters/agent/) to connect Kubernetes clusters with GitLab. [How do I migrate?](https://docs.gitlab.com/ee/user/infrastructure/clusters/migrate_to_gitlab_agent.html) diff --git a/doc/update/index.md b/doc/update/index.md index d4412d85355..bffecf58304 100644 --- a/doc/update/index.md +++ b/doc/update/index.md @@ -41,7 +41,7 @@ There are also instructions when you want to ### Installation from source -- [Upgrading Community Edition and Enterprise Edition from source](upgrading_from_source.md) - +- [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 13.2.0 to 13.2.1, and apply to both Community and Enterprise @@ -147,7 +147,7 @@ Some installations [may need to run GitLab 14.0 for at least a day](#1400) to co To check the status of batched background migrations: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Migrations**.  @@ -328,7 +328,7 @@ sudo -u git -H bundle exec rake gitlab:elastic:list_pending_migrations ### What do you do if your Advanced Search migrations are stuck? In GitLab 15.0, an Advanced Search migration named `DeleteOrphanedCommit` can be permanently stuck -in a pending state across upgrades. This issue +in a pending state across upgrades. This issue [is corrected in GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89539). If you are a self-managed customer who uses GitLab 15.0 with Advanced Search, you will experience performance degradation. @@ -380,7 +380,7 @@ 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`](#12100) -> `13.0.14` -> [`13.1.11`](#1310) -> [`13.8.8`](#1388) -> [`13.12.15`](#13120) -> [`14.0.12`](#1400) -> [`14.3.6`](#1430) -> [`14.9.5`](#1490) -> [`14.10.Z`](#14100) -> [`15.0.Z`](#1500) -> [latest `15.Y.Z`](https://gitlab.com/gitlab-org/gitlab/-/releases) +`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`](#12100) -> `13.0.14` -> [`13.1.11`](#1310) -> [`13.8.8`](#1388) -> [`13.12.15`](#13120) -> [`14.0.12`](#1400) -> [`14.3.6`](#1430) -> [`14.9.5`](#1490) -> [`14.10.Z`](#14100) -> [`15.0.Z`](#1500) -> [`15.4.0`](#1540) -> [latest `15.Y.Z`](https://gitlab.com/gitlab-org/gitlab/-/releases) NOTE: When not explicitly specified, upgrade GitLab to the latest available patch @@ -465,6 +465,21 @@ NOTE: Specific information that follow related to Ruby and Git versions do not apply to [Omnibus installations](https://docs.gitlab.com/omnibus/) and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with appropriate Ruby and Git versions and are not using system binaries for Ruby and Git. There is no need to install Ruby or Git when utilizing these two approaches. +### 15.4.0 + +- GitLab 15.4.0 includes a [batched background migration](#batched-background-migrations) to [remove incorrect values from `expire_at` in `ci_job_artifacts` table](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89318). + This migration might take hours or days to complete on larger GitLab instances. + +### 15.3.3 + +- In GitLab 15.3.3, [SAML Group Links](../api/groups.md#saml-group-links) API `access_level` attribute type changed to `integer`. See +[valid access levels](../api/members.md#valid-access-levels) documentation. + +### 15.3.0 + +- [Incorrect deletion of object storage files on Geo secondary sites]((https://gitlab.com/gitlab-org/gitlab/-/issues/371397)) can occur in certain situations. See [Geo: Incorrect object storage LFS file deletion on secondary site issue in GitLab 15.0.0 to 15.3.2](#geo-incorrect-object-storage-lfs-file-deletion-on-secondary-sites-in-gitlab-1500-to-1532). +- LFS transfers can [redirect to the primary from secondary site mid-session](https://gitlab.com/gitlab-org/gitlab/-/issues/371571) causing failed pull and clone requests when [Geo proxying](../administration/geo/secondary_proxy/index.md) is enabled. Geo proxying is enabled by default in GitLab 15.1 and later. See [Geo: LFS transfer redirect to primary from secondary site mid-session issue in GitLab 15.1.0 to 15.3.2](#geo-lfs-transfers-redirect-to-primary-from-secondary-site-mid-session-in-gitlab-1510-to-1532) for more details. + ### 15.2.0 - GitLab installations that have multiple web nodes should be @@ -472,6 +487,19 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap configuration change in Rails that can result in inconsistent ETag key generation. - Some Sidekiq workers were renamed in this release. To avoid any disruption, [run the Rake tasks to migrate any pending jobs](../administration/sidekiq/sidekiq_job_migration.md#future-jobs) before starting the upgrade to GitLab 15.2.0. +- Gitaly now executes its binaries in a [runtime location](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/4670). By default on Omnibus GitLab, + this path is `/var/opt/gitlab/gitaly/run/`. If this location is mounted with `noexec`, merge requests generate the following error: + + ```plaintext + fork/exec /var/opt/gitlab/gitaly/run/gitaly-<nnnn>/gitaly-git2go-v15: permission denied + ``` + + To resolve this, remove the `noexec` option from the filesystem mount. An alternative is to change the Gitaly runtime directory: + + 1. Add `gitaly['runtime_dir'] = '<PATH_WITH_EXEC_PERM>'` to `/etc/gitlab/gitlab.rb` and specify a location without `noexec` set. + 1. Run `sudo gitlab-ctl reconfigure`. +- [Incorrect deletion of object storage files on Geo secondary sites]((https://gitlab.com/gitlab-org/gitlab/-/issues/371397)) can occur in certain situations. See [Geo: Incorrect object storage LFS file deletion on secondary site issue in GitLab 15.0.0 to 15.3.2](#geo-incorrect-object-storage-lfs-file-deletion-on-secondary-sites-in-gitlab-1500-to-1532). +- LFS transfers can [redirect to the primary from secondary site mid-session](https://gitlab.com/gitlab-org/gitlab/-/issues/371571) causing failed pull and clone requests when [Geo proxying](../administration/geo/secondary_proxy/index.md) is enabled. Geo proxying is enabled by default in GitLab 15.1 and later. See [Geo: LFS transfer redirect to primary from secondary site mid-session issue in GitLab 15.1.0 to 15.3.2](#geo-lfs-transfers-redirect-to-primary-from-secondary-site-mid-session-in-gitlab-1510-to-1532) for more details. ### 15.1.0 @@ -490,6 +518,8 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap - Unauthenticated requests to the [`ciConfig` GraphQL field](../api/graphql/reference/index.md#queryciconfig) are no longer supported. Before you upgrade to GitLab 15.1, add an [access token](../api/index.md#authentication) to your requests. The user creating the token must have [permission](../user/permissions.md) to create pipelines in the project. +- [Incorrect deletion of object storage files on Geo secondary sites]((https://gitlab.com/gitlab-org/gitlab/-/issues/371397)) can occur in certain situations. See [Geo: Incorrect object storage LFS file deletion on secondary site issue in GitLab 15.0.0 to 15.3.2](#geo-incorrect-object-storage-lfs-file-deletion-on-secondary-sites-in-gitlab-1500-to-1532). +- LFS transfers can [redirect to the primary from secondary site mid-session](https://gitlab.com/gitlab-org/gitlab/-/issues/371571) causing failed pull and clone requests when [Geo proxying](../administration/geo/secondary_proxy/index.md) is enabled. Geo proxying is enabled by default in GitLab 15.1 and later. See [Geo: LFS transfer redirect to primary from secondary site mid-session issue in GitLab 15.1.0 to 15.3.2](#geo-lfs-transfers-redirect-to-primary-from-secondary-site-mid-session-in-gitlab-1510-to-1532) for more details. ### 15.0.0 @@ -500,6 +530,12 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap - The use of encrypted S3 buckets with storage-specific configuration is no longer supported after [removing support for using `background_upload`](removals.md#background-upload-for-object-storage). - The [certificate-based Kubernetes integration (DEPRECATED)](../user/infrastructure/clusters/index.md#certificate-based-kubernetes-integration-deprecated) is disabled by default, but you can be re-enable it through the [`certificate_based_clusters` feature flag](../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags) until GitLab 16.0. - When you use the GitLab Helm Chart project with a custom `serviceAccount`, ensure it has `get` and `list` permissions for the `serviceAccount` and `secret` resources. +- The [`custom_hooks_dir`](../administration/server_hooks.md#create-global-server-hooks-for-all-repositories) setting for configuring global server hooks is now configured in + Gitaly. The previous implementation in GitLab Shell was removed in GitLab 15.0. With this change, global server hooks are stored only inside a subdirectory named after the + hook type. Global server hooks can no longer be a single hook file in the root of the custom hooks directory. For example, you must use `<custom_hooks_dir>/<hook_name>.d/*` rather + than `<custom_hooks_dir>/<hook_name>`. +- [Incorrect deletion of object storage files on Geo secondary sites]((https://gitlab.com/gitlab-org/gitlab/-/issues/371397)) can occur in certain situations. See [Geo: Incorrect object storage LFS file deletion on secondary site issue in GitLab 15.0.0 to 15.3.2](#geo-incorrect-object-storage-lfs-file-deletion-on-secondary-sites-in-gitlab-1500-to-1532). +- The `FF_GITLAB_REGISTRY_HELPER_IMAGE` [feature flag](../administration/feature_flags.md#enable-or-disable-the-feature) is removed and helper images are always pulled from GitLab Registry. ### 14.10.0 @@ -1040,7 +1076,7 @@ In 13.1.0, you must upgrade to either: 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 +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 @@ -1121,7 +1157,7 @@ for more information. 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, continue to be signed in. If the administrator who enabled Maintenance mode loses their session, then they can't 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). +Users who were signed in before Maintenance mode was enabled, continue to be signed in. If the administrator who enabled Maintenance mode loses their session, then they can't disable Maintenance mode via the UI. In that case, you can [disable Maintenance mode via the API or Rails console](../administration/maintenance_mode/index.md#disable-maintenance-mode). [This bug](https://gitlab.com/gitlab-org/gitlab/-/issues/329261) was fixed in GitLab 14.5.0 and backported into 14.4.3 and 14.3.5. @@ -1145,6 +1181,27 @@ by a database engine bug that causes a segmentation fault. Read more [in the issue](https://gitlab.com/gitlab-org/gitlab/-/issues/364763). +### Geo: Incorrect object storage LFS file deletion on secondary sites in GitLab 15.0.0 to 15.3.2 + +[Incorrect deletion of object storage files on Geo secondary sites]((https://gitlab.com/gitlab-org/gitlab/-/issues/371397)) +can occur in GitLab 15.0.0 to 15.3.2 in the following situations: + +- GitLab-managed object storage replication is disabled, and LFS objects are created while importing a project with object storage enabled. +- GitLab-managed replication to sync object storage is enabled and subsequently disabled. + +This issue is resolved in 15.3.3. Customers who have both LFS enabled and LFS objects being replicated across Geo sites +should upgrade directly to 15.3.3 to reduce the risk of data loss on secondary sites. + +### Geo: LFS transfers redirect to primary from secondary site mid-session in GitLab 15.1.0 to 15.3.2 + +LFS transfers can [redirect to the primary from secondary site mid-session](https://gitlab.com/gitlab-org/gitlab/-/issues/371571) causing failed pull and clone requests in GitLab 15.1.0 to 15.3.2 when [Geo proxying](../administration/geo/secondary_proxy/index.md) is enabled. Geo proxying is enabled by default in GitLab 15.1 and later. + +This issue is resolved in GitLab 15.3.3, so customers with the following configuration should upgrade to 15.3.3 or later: + +- LFS is enabled. +- LFS objects are being replicated across Geo sites. +- Repositories are being pulled by using a Geo secondary site. + ## 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 12a8b6f3190..06a56f49cc1 100644 --- a/doc/update/package/index.md +++ b/doc/update/package/index.md @@ -330,3 +330,10 @@ To fix this error: ```shell sudo gitlab-ctl reconfigure ``` + +1. Hot reload `puma` and `sidekiq` services: + + ```shell + sudo gitlab-ctl hup puma + sudo gitlab-ctl restart sidekiq + ``` diff --git a/doc/update/plan_your_upgrade.md b/doc/update/plan_your_upgrade.md index 0947bab855f..03bdf161756 100644 --- a/doc/update/plan_your_upgrade.md +++ b/doc/update/plan_your_upgrade.md @@ -132,7 +132,7 @@ to your instance and then upgrade it for any relevant features you're using. [turning on maintenance mode](../administration/maintenance_mode/index.md) during the upgrade. - About PostgreSQL: - - On the top bar, select **Menu > Admin**, and look for the version of + - On the top bar, select **Main menu > Admin**, and look for the version of PostgreSQL you are using. If [a PostgreSQL upgrade is needed](../administration/package_information/postgresql_versions.md), account for the relevant @@ -172,6 +172,9 @@ If you have Kubernetes clusters connected with GitLab, [upgrade your GitLab agen #### Elasticsearch +Before updating GitLab, confirm Advanced Search migrations are complete by +[checking for pending advanced search migrations](index.md#checking-for-pending-advanced-search-migrations). + After updating GitLab, you may have to upgrade [Elasticsearch if the new version breaks compatibility](../integration/advanced_search/elasticsearch.md#version-requirements). Updating Elasticsearch is **out of scope for GitLab Support**. diff --git a/doc/update/removals.md b/doc/update/removals.md index cdb35b5faa0..9b5596d67f2 100644 --- a/doc/update/removals.md +++ b/doc/update/removals.md @@ -31,6 +31,49 @@ For removal reviewers (Technical Writers only): https://about.gitlab.com/handbook/marketing/blog/release-posts/#update-the-removals-doc --> +## Removed in 15.4 + +### SAST analyzer consolidation and CI/CD template changes + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +We have replaced the GitLab SAST [analyzers](https://docs.gitlab.com/ee/user/application_security/sast/analyzers/) for certain languages in GitLab 15.4 as part of our long-term strategy to deliver a more consistent user experience, faster scan times, and reduced CI minute usage. + +Starting from GitLab 15.4, the [GitLab-managed SAST CI/CD template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) uses [Semgrep-based scanning](https://docs.gitlab.com/ee/user/application_security/sast/analyzers.html#transition-to-semgrep-based-scanning) instead of the following analyzers: + +- [ESLint](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) for JavaScript, TypeScript, React +- [Gosec](https://gitlab.com/gitlab-org/security-products/analyzers/gosec) for Go +- [Bandit](https://gitlab.com/gitlab-org/security-products/analyzers/bandit) for Python +- [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) for Java + +We will no longer make any updates to the ESLint-, Gosec-, and Bandit-based analyzers. +The SpotBugs-based analyzer will continue to be used for Groovy, Kotlin, and Scala scanning. + +We won't delete container images previously published for these analyzers, so older versions of the CI/CD template will continue to work. + +If you changed the default GitLab SAST configuration, you may need to update your configuration as detailed in the [deprecation issue for this change](https://gitlab.com/gitlab-org/gitlab/-/issues/352554#actions-required). + +## Removed in 15.3 + +### Support for Debian 9 + +Long term service and support (LTSS) for [Debian 9 Stretch ended 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. + +### Vulnerability Report sort by State + +The ability to sort the Vulnerability Report by the `State` column was disabled and put behind a feature flag in GitLab 14.10 due to a refactor +of the underlying data model. The feature flag has remained off by default as further refactoring will be required to ensure sorting +by this value remains performant. Due to very low usage of the `State` column for sorting, the feature flag is instead removed in 15.3 to simplify the codebase and prevent any unwanted performance degradation. + +### Vulnerability Report sort by Tool + +The ability to sort the Vulnerability Report by the `Tool` column (scan type) was disabled and put behind a feature flag in GitLab 14.10 due to a refactor +of the underlying data model. The feature flag has remained off by default as further refactoring will be required to ensure sorting +by this value remains performant. Due to very low usage of the `Tool` column for sorting, the feature flag is instead removed in +GitLab 15.3 to simplify the codebase and prevent any unwanted performance degradation. + ## Removed in 15.2 ### Support for older browsers @@ -121,8 +164,8 @@ If you have set a prefix, you can use a workaround to revert to background uploa gitlab_rails['env'] = { 'GITLAB_LEGACY_BACKGROUND_UPLOADS' => 'artifacts,external_diffs,lfs,uploads,packages,dependency_proxy,terraform_state,pages' } ``` -Prefixes will be supported officially in [GitLab 15.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91307). -This workaround will be dropped, so we encourage migrating to consolidated object storage. +Support for prefixes was restored in GitLab 15.2 via [this MR](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91307). +Support for setting `GITLAB_LEGACY_BACKGROUND_UPLOADS` will be removed in GitLab 15.4. ### Container Network and Host Security diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md index 2df11e8f741..4f54e69d8c9 100644 --- a/doc/update/upgrading_from_source.md +++ b/doc/update/upgrading_from_source.md @@ -119,7 +119,7 @@ rm go1.17.10.linux-amd64.tar.gz To check you are running the minimum required Git version, see [Git versions](../install/installation.md#software-requirements). -From GitLab 13.6, we recommend you use the +From GitLab 13.6, we recommend you use the [Git version provided by Gitaly](https://gitlab.com/gitlab-org/gitaly/-/issues/2729) that: diff --git a/doc/update/zero_downtime.md b/doc/update/zero_downtime.md index 0abdd769a6b..29bb1c4bcb4 100644 --- a/doc/update/zero_downtime.md +++ b/doc/update/zero_downtime.md @@ -53,7 +53,7 @@ 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 processes any remaining jobs before continuing the upgrading procedure. While this doesn't require downtime -(if the above conditions are met) we require that you +(if the above conditions are met) we require that you [wait for background migrations to complete](index.md#checking-for-background-migrations-before-upgrading) between each major/minor release upgrade. The time necessary to complete these migrations can be reduced by @@ -492,9 +492,11 @@ You can only upgrade one minor release at a time. The order of steps is important. While following these steps, make sure you follow them in the right order, on the correct node. +### Update the Geo primary site + Log in to your **primary** node, executing the following: -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. +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 @@ -512,7 +514,7 @@ Log in to your **primary** node, executing the following: sudo gitlab-ctl reconfigure ``` -1. Update the GitLab package +1. Update the GitLab package: ```shell # Debian/Ubuntu @@ -522,18 +524,13 @@ Log in to your **primary** node, executing the following: sudo yum install gitlab-ee ``` -1. To get the database migrations and latest code in place, run +1. To get the database migrations and latest code in place, run: ```shell sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-ctl reconfigure ``` -1. Hot reload `puma` and `sidekiq` services - - ```shell - sudo gitlab-ctl hup puma - sudo gitlab-ctl restart sidekiq - ``` +### Update the Geo secondary site On each **secondary** node, executing the following: @@ -555,7 +552,7 @@ On each **secondary** node, executing the following: sudo gitlab-ctl reconfigure ``` -1. Update the GitLab package +1. Update the GitLab package: ```shell # Debian/Ubuntu @@ -565,26 +562,20 @@ On each **secondary** node, executing the following: sudo yum install gitlab-ee ``` -1. To get the database migrations and latest code in place, run +1. To get the database migrations and latest code in place, run: ```shell sudo SKIP_POST_DEPLOYMENT_MIGRATIONS=true gitlab-ctl reconfigure ``` -1. Hot reload `puma`, `sidekiq` and restart `geo-logcursor` services - - ```shell - sudo gitlab-ctl hup puma - sudo gitlab-ctl restart sidekiq - sudo gitlab-ctl restart geo-logcursor - ``` - -1. Run post-deployment database migrations, specific to the Geo database +1. Run post-deployment database migrations, specific to the Geo database: ```shell sudo gitlab-rake db:migrate:geo ``` +### Finalize the update + After all **secondary** nodes are updated, finalize the update on the **primary** node: @@ -594,6 +585,16 @@ the update on the **primary** node: sudo gitlab-rake db:migrate ``` +- After the update is finalized on the primary node, hot reload `puma` and +restart `sidekiq` and `geo-logcursor` services on **all primary and secondary** +nodes: + + ```shell + sudo gitlab-ctl hup puma + sudo gitlab-ctl restart sidekiq + sudo gitlab-ctl restart geo-logcursor + ``` + After updating all nodes (both **primary** and all **secondaries**), check their status: - Verify Geo configuration and dependencies |