Merge branch 'docs-aqualls-omnibus-pkgdocs-move' into 'master'

Move package information index page into this repo

See merge request gitlab-org/gitlab!70537

doc/administration/consul.md

@@ -21,7 +21,7 @@ Before configuring Consul:
 
 1. Review the [reference architecture](reference_architectures/index.md#available-reference-architectures)
    documentation to determine the number of Consul server nodes you should have.
-1. If necessary, ensure the [appropriate ports are open](https://docs.gitlab.com/omnibus/package-information/defaults.html#ports) in your firewall.
+1. If necessary, ensure the [appropriate ports are open](package-information/defaults.md#ports) in your firewall.
 
 ## Configure the Consul nodes
 

doc/administration/geo/index.md

@@ -138,7 +138,7 @@ The following table lists basic ports that must be open between the **primary**
 | 22               | 22                 | TCP          |
 | 5432             |                    | PostgreSQL   |
 
-See the full list of ports used by GitLab in [Package defaults](https://docs.gitlab.com/omnibus/package-information/defaults.html)
+See the full list of ports used by GitLab in [Package defaults](../package-information/defaults.md)
 
 NOTE:
 [Web terminal](../../ci/environments/index.md#web-terminals) support requires your load balancer to correctly handle WebSocket connections.

doc/administration/package-information/defaults.md

+---
+stage: Enablement
+group: Distribution
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+---
+
+# Package defaults
+
+Unless configuration is specified in the `/etc/gitlab/gitlab.rb` file,
+the package will assume the defaults as noted below.
+
+## Ports
+
+See the table below for the list of ports that the Omnibus GitLab assigns
+by default:
+
+| Component                                              | On by default  | Communicates via | Alternative | Connection port                            |
+| :----------------------------------------------------: | :------------: | :--------------: | :---------: | :------------------------------------:     |
+| <a name="gitlab-rails"></a>        GitLab Rails        | Yes            | Port             | X           | 80 or 443                                  |
+| <a name="gitlab-shell"></a>        GitLab Shell        | Yes            | Port             | X           | 22                                         |
+| <a name="postgresql"></a>          PostgreSQL          | Yes            | Socket           | Port (5432) | X                                          |
+| <a name="redis"></a>               Redis               | Yes            | Socket           | Port (6379) | X                                          |
+| <a name="puma"></a>                Puma                | Yes            | Socket           | Port (8080) | X                                          |
+| <a name="gitlab-workhorse"></a>    GitLab Workhorse    | Yes            | Socket           | Port (8181) | X                                          |
+| <a name="nginx-status"></a>        NGINX status        | Yes            | Port             | X           | 8060                                       |
+| <a name="prometheus"></a>          Prometheus          | Yes            | Port             | X           | 9090                                       |
+| <a name="node-exporter"></a>       Node exporter       | Yes            | Port             | X           | 9100                                       |
+| <a name="redis-exporter"></a>      Redis exporter      | Yes            | Port             | X           | 9121                                       |
+| <a name="postgres-exporter"></a>   PostgreSQL exporter | Yes            | Port             | X           | 9187                                       |
+| <a name="pgbouncer-exporter"></a>  PgBouncer exporter  | No             | Port             | X           | 9188                                       |
+| <a name="gitlab-exporter"></a>     GitLab Exporter     | Yes            | Port             | X           | 9168                                       |
+| <a name="sidekiq-exporter"></a>    Sidekiq exporter    | Yes            | Port             | X           | 8082                                       |
+| <a name="puma-exporter"></a>       Puma exporter       | No             | Port             | X           | 8083                                       |
+| <a name="geo-postgresql"></a>      Geo PostgreSQL      | No             | Socket           | Port (5431) | X                                          |
+| <a name="redis-sentinel"></a>      Redis Sentinel      | No             | Port             | X           | 26379                                      |
+| <a name="incoming-email"></a>      Incoming email      | No             | Port             | X           | 143                                        |
+| <a name="elasticsearch"></a>       Elastic search      | No             | Port             | X           | 9200                                       |
+| <a name="gitlab-pages"></a>        GitLab Pages        | No             | Port             | X           | 80 or 443                                  |
+| <a name="gitlab-registry-web"></a> GitLab Registry     | No*            | Port             | X           | 80, 443 or 5050                            |
+| <a name="gitlab-registry"></a>     GitLab Registry     | No             | Port             | X           | 5000                                       |
+| <a name="ldap"></a>                LDAP                | No             | Port             | X           | Depends on the component configuration     |
+| <a name="kerberos"></a>            Kerberos            | No             | Port             | X           | 8443 or 8088                               |
+| <a name="omniauth"></a>            OmniAuth            | Yes            | Port             | X           | Depends on the component configuration     |
+| <a name="smtp"></a>                SMTP                | No             | Port             | X           | 465                                        |
+| <a name="remote-syslog"></a>       Remote syslog       | No             | Port             | X           | 514                                        |
+| <a name="mattermost"></a>          Mattermost          | No             | Port             | X           | 8065                                       |
+| <a name="mattermost-web"></a>      Mattermost          | No             | Port             | X           | 80 or 443                                  |
+| <a name="pgbouncer"></a>           PgBouncer           | No             | Port             | X           | 6432                                       |
+| <a name="consul"></a>              Consul              | No             | Port             | X           | 8300, 8301(UDP), 8500, 8600[^Consul-notes] |
+| <a name="patroni"></a>             Patroni             | No             | Port             | X           | 8008                                       |
+| <a name="gitlab-kas"></a>          GitLab KAS          | No             | Port             | X           | 8150                                       |
+| <a name="gitaly"></a>              Gitaly              | No             | Port             | X           | 8075                                       |
+
+Legend:
+
+- `Component` - Name of the component.
+- `On by default` - Is the component running by default.
+- `Communicates via` - How the component talks with the other components.
+- `Alternative` - If it is possible to configure the component to use different type of communication. The type is listed with default port used in that case.
+- `Connection port` - Port on which the component communicates.
+
+GitLab also expects a filesystem to be ready for the storage of Git repositories
+and various other files.
+
+Note that if you are using NFS (Network File System), files will be carried
+over a network which will require, based on implementation, ports `111` and
+`2049` to be open.
+
+NOTE:
+In some cases, the GitLab Registry will be automatically enabled by default. Please see [our documentation](../packages/container_registry.md) for more details
+
+ [^Consul-notes]: If using additional Consul functionality, more ports may need to be opened. See the [official documentation](https://www.consul.io/docs/install/ports#ports-table) for the list.

doc/administration/package-information/deprecation_policy.md

+---
+stage: Enablement
+group: Distribution
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+---
+
+# Deprecation policy
+
+The Omnibus GitLab packages come with number of different libraries and services which offers users plethora of configuration options.
+
+As libraries and services get updated, their configuration options change
+and become obsolete. To increase maintainability and preserve a working
+setup, various configuration requires removal.
+
+## Configuration deprecation
+
+### Policy
+
+The Omnibus GitLab package will retain configuration for at least **one major**
+version. We cannot guarantee that deprecated configuration
+will be available in the next major release. See [example](#example) for more details.
+
+### Notice
+
+If the configuration becomes obsolete, we will announce the deprecation:
+
+- via release blog post on `https://about.gitlab.com/blog/`. The blog post item
+  will contain the deprecation notice together with the target removal date.
+- via installation/reconfigure output (if applicable).
+- via official documentation on `https://docs.gitlab.com/`. The documentation update will contain the corrected syntax (if applicable) or a date of configuration removal.
+
+### Procedure
+
+This section lists steps necessary for deprecating and removing configuration.
+
+We can differentiate two different types of configuration:
+
+- Sensitive: Configuration that can cause major service outage ( Data integrity,
+  installation integrity, preventing users from reaching the installation, etc.)
+- Regular: Configuration that can make a feature unavailable but still makes the installation useable ( Change in default project/group settings, miscommunication with other components and similar )
+
+We also need to differentiate deprecation and removal procedure.
+
+#### Deprecating configuration
+
+Deprecation procedure is similar for both `sensitive` and `regular` configuration. The only difference is in the removal target date.
+
+Common steps:
+
+1. Create an issue at the [Omnibus GitLab issue tracker](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues) with details on deprecation type and other necessary information. Apply the label `deprecation`.
+1. Decide on the removal target for the deprecated configuration
+1. Formulate deprecation notice for each item as noted in [Notice section](#notice)
+
+Removal target:
+
+For regular configuration, removal target should always be the date of the **next major** release. If the date is not known, you can reference the next major version.
+
+For sensitive configuration things are a bit more complicated.
+We should aim to not remove sensitive configuration in the *next major* release if the next major release is 2 minor releases away (This number is chosen to match our security backport release policy).
+
+See the table below for some examples:
+
+| Config. type | Deprecation announced | Final minor release | Remove |
+| -------- | -------- | -------- | -------- |
+| Sensitive | 10.1.0   | 10.9.0   | 11.0.0 |
+| Sensitive | 10.7.0   | 10.9.0   | 12.0.0 |
+| Regular | 10.1.0 | 10.9.0 | 11.0.0 |
+| Regular | 10.8.0 | 10.9.0 | 11.0.0 |
+
+#### Removing configuration
+
+When deprecation is announced and removal target set, the milestone for the issue
+should be changed to match the removal target version.
+
+The final comment in the issue **has to have**:
+
+1. Text snippet for the release blog post section
+1. Documentation MR ( or snippet ) for introducing the change
+1. Draft MR removing the configuration OR details on what needs to be done. See [Adding deprecation messages](https://docs.gitlab.com/omnibus/development/adding-deprecation-messages.html) for more on this
+
+## Example
+
+User configuration available in `/etc/gitlab/gitlab.rb` was introduced in GitLab version 10.0, `gitlab_rails['configuration'] = true`. In GitLab version 10.4.0, a new change was introduced that requires rename of this configuration option. New configuration option is `gitlab_rails['better_configuration'] = true`. Development team will translate the old configuration into new one
+and trigger a deprecation procedure.
+
+This means that these two configuration
+options will both be valid through GitLab version 10. In other words,
+if you still have `gitlab_rails['configuration'] = true` set in GitLab 10.8.0
+the feature will continue working the same way as if you had `gitlab_rails['better_configuration'] = true` set.
+However, setting the old version of configuration will print out a deprecation
+notice at the end of installation/upgrade/reconfigure run.
+
+With GitLab 11, `gitlab_rails['configuration'] = true` will no longer work and you will have to manually change the configuration in `/etc/gitlab/gitlab.rb` to the new valid config.
+**Note** If this configuration option is sensitive and can put integrity of the installation or
+data in danger, installation/upgrade will be aborted.

doc/administration/package-information/index.md

+---
+stage: Enablement
+group: Distribution
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+---
+
+# Package information
+
+The Omnibus GitLab package is bundled with all dependencies required for GitLab
+to function correctly. More details can be found
+at [bundling dependencies document](omnibus_packages.md).
+
+## Package Version
+
+The released package versions are in the format `MAJOR.MINOR.PATCH-EDITION.OMNIBUS_RELEASE`
+
+| Component         | Meaning | Example |
+| ---------         | ------- | ------- |
+| MAJOR.MINOR.PATCH | The GitLab version this corresponds to | 13.3.0 |
+| EDITION           | The edition of GitLab this corresponds to | ee |
+| OMNIBUS_RELEASE   | The omnibus release. Usually, this will be 0. This will be incremented if we need to build a new package without changing the GitLab version. | 0 |
+
+## Licenses
+
+See [licensing](licensing.md)
+
+## Defaults
+
+The Omnibus GitLab package requires various configuration to get the
+components in working order.
+If the configuration is not provided, the package will use the default
+values assumed in the package.
+
+These defaults are noted in the package [defaults document](defaults.md).
+
+## Checking the versions of bundled software
+
+Once the Omnibus GitLab package is installed, all versions of the bundled
+libraries are located in `/opt/gitlab/version-manifest.txt`.
+
+If you don't have the package installed, you can always check the Omnibus GitLab
+[source repository](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master), specifically the
+[config directory](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/config).
+
+For example, if you take a look at the `8-6-stable` branch, you can conclude that
+8.6 packages were running [Ruby 2.1.8](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/8-6-stable/config/projects/gitlab.rb#L48).
+Or, that 8.5 packages were bundled with [NGINX 1.9.0](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/8-5-stable/config/software/nginx.rb#L20).
+
+## Signatures of GitLab, Inc. provided packages
+
+Documentation on package signatures can be found at [Signed Packages](signed_packages.md)
+
+## Checking for newer configuration options on upgrade
+
+Configuration file in `/etc/gitlab/gitlab.rb` is created on initial installation
+of the Omnibus GitLab package. On subsequent package upgrades, the configuration
+file is not updated with new configuration. This is done in order to avoid
+accidental overwrite of user configuration provided in `/etc/gitlab/gitlab.rb`.
+
+New configuration options are noted in the
+[`gitlab.rb.template` file](https://gitlab.com/gitlab-org/omnibus-gitlab/raw/master/files/gitlab-config-template/gitlab.rb.template).
+
+The Omnibus GitLab package also provides convenience command which will
+compare the existing user configuration with the latest version of the
+template contained in the package.
+
+To view a diff between your configuration file and the latest version, run:
+
+```shell
+sudo gitlab-ctl diff-config
+```
+
+_**Note:** This command is available from GitLab 8.17_
+
+**Important:** If you are copy-pasting the output of this command into your
+`/etc/gitlab/gitlab.rb` configuration file, make sure to omit leading `+` and `-`
+on each line.
+
+## Init system detection
+
+Omnibus GitLab will attempt to query the underlaying system in order to
+check which init system it uses.
+This manifests itself as a `WARNING` during the `sudo gitlab-ctl reconfigure`
+run.
+
+Depending on the init system, this `WARNING` can be one of:
+
+```plaintext
+/sbin/init: unrecognized option '--version'
+```
+
+when the underlying init system *IS NOT* upstart.
+
+```plaintext
+  -.mount loaded active mounted   /
+```
+
+when the underlying init system *IS* systemd.
+
+These warnings _can be safely ignored_. They are not suppressed because this
+allows everyone to debug possible detection issues faster.

doc/administration/package-information/licensing.md

+---
+stage: Enablement
+group: Distribution
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+---
+
+# Package Licensing
+
+## License
+
+While GitLab itself is MIT, the Omnibus GitLab sources are licensed under the Apache-2.0.
+
+## License file location
+
+Starting with version 8.11, the Omnibus GitLab package contains license
+information of all software that is bundled within the package.
+
+After installing the package, licenses for each individual bundled library
+can be found in `/opt/gitlab/LICENSES` directory.
+
+There is also one `LICENSE` file which contains all licenses compiled together.
+This compiled license can be found in `/opt/gitlab/LICENSE` file.
+
+Starting with version 9.2, the Omnibus GitLab package ships a
+`dependency_licenses.json` file containing version and license information of
+all bundled software, including software libraries, Ruby gems that the rails
+application uses, and JavaScript libraries that is required for the frontend
+components. This file, being in JSON format, is easily machine parseable and
+can be used for automated checks or validations. The file may be found at
+`/opt/gitlab/dependency_licenses.json`.
+
+Starting with version 11.3, we have also made the license information available
+online, at: <https://gitlab-org.gitlab.io/omnibus-gitlab/licenses.html>
+
+## Checking licenses
+
+The Omnibus GitLab package is made up of many pieces of software, comprising code
+that is covered by many different licenses. Those licenses are provided and
+compiled as stated above.
+
+Starting with version 8.13, GitLab has placed an additional step into
+Omnibus GitLab. The `license_check` step calls
+`lib/gitlab/tasks/license_check.rake`, which checks the compiled `LICENSE` file
+against the current list of approved and questionable licenses as denoted in the
+arrays at the top of the script. This script will output one of `Good`,
+`Unknown` or `Check` for each piece of software that is a part of the
+Omnibus GitLab package.
+
+- `Good`: denotes a license that is approved for all usage types, within GitLab and
+  Omnibus GitLab.
+- `Unknown`: denotes a license that is not recognized in the list of 'good' or 'bad',
+  which should be immediately reviewed for implications of use.
+- `Check`: denotes a license that has the potential be incompatible with GitLab itself,
+  and thus should be checked for how it is used as a part of the Omnibus GitLab package
+  to ensure compliance.
+
+This list is currently sourced from the [GitLab development documentation on licensing](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/doc/development/licensing.md).
+However, due to the nature of the Omnibus GitLab package the licenses may not apply
+in the same way. Such as with `git` and `rsync`. See the [GNU License FAQ](https://www.gnu.org/licenses/gpl-faq.en.html#MereAggregation)
+
+## License acknowledgements
+
+### libjpeg-turbo - BSD 3-clause license
+
+This software is based in part on the work of the Independent JPEG Group.
+
+## Trademark Usage
+
+Within the GitLab documentation, reference to third party technology(ies) and/or trademarks of third party entities, may be made. The inclusion of reference to third party technology and/or entities is solely for the purposes of example(s) of how GitLab software may interact with, or be used in conjunction with, such third party technology.
+All trademarks, materials, documentation, and other intellectual property remain the property of any/all such third party.
+
+### Trademark Requirements
+
+Use of GitLab Trademarks must be in compliance with the standards set forth in [our guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/trademark-guidelines/) (as updated from time to time).
+CHEF® and all Chef marks are owned by Progress Software Corporation and must be used in accordance with the [Progress Software Trademark Usage Policy](https://www.progress.com/legal/trademarks).
+
+When using a GitLab or 3rd party trademark in documentation, include the (R) symbol in the first instance, for example, "Chef(R) is used for configuring...." You may omit the symbol in subsequent instances.
+
+If a trademark owner requires a particular notice or trademark requirement, such notice or requirement should be stated above.

doc/administration/package-information/omnibus_packages.md

+---
+stage: Enablement
+group: Distribution
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+---
+
+# Omnibus based packages and images
+
+Below you can find some basic information on why GitLab provides packages and
+a Docker image that come with bundled dependencies.
+
+These methods are great for physical and virtual machine installations, and simple Docker installations.
+
+## Goals
+
+We have a few core goals with these packages:
+
+1. Extremely easy to install, upgrade, maintain.
+1. Support for a wide variety of operating systems
+1. Wide support of cloud service providers
+
+## Omnibus GitLab Architecture
+
+GitLab in its core is a Ruby on Rails project. However, GitLab as a whole
+application is more complex and has multiple components. If these components are
+not present or are incorrectly configured, GitLab will not work or it will work
+unpredictably.
+
+The [GitLab Architecture Overview](../../development/architecture.md#gitlab-architecture-overview) shows some of these components and how they
+interact. Each of these components needs to be configured and kept up to date.
+
+Most of the components also have external dependencies. For example, the Rails
+application depends on a number of [Ruby gems](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/Gemfile.lock). Some of these dependencies also
+have their own external dependencies which need to be present on the Operating
+System in order for them to function correctly.
+
+Furthermore, GitLab has a monthly release cycle requiring frequent maintenance
+to stay up to date.
+
+All the things listed above present a challenge for the user maintaining the GitLab
+installation.
+
+## External Software Dependencies
+
+For applications such as GitLab, external dependencies usually bring the following
+challenges:
+
+- Keeping versions in sync between direct and indirect dependencies
+- Availability of a version on a specific Operating System
+- Version changes can introduce or remove previously used configuration
+- Security implications when library is marked as vulnerable but does not have
+  a new version released yet
+
+Keep in mind that if a dependency exists on your Operating System, it does not
+necessarily exist on other supported OSs.
+
+## Benefits
+
+A few benefits of a package with bundled dependencies:
+
+1. Minimal effort required to install GitLab.
+1. Minimum configuration required to get GitLab up and running.
+1. Minimum effort required to upgrade between GitLab versions.
+1. Multiple platforms supported.
+1. Maintenance on older platforms is greatly simplified.
+1. Less effort to support potential issues.
+
+## Drawbacks
+
+Some drawbacks of a package with bundled dependencies:
+
+1. Duplication with possibly existing software.
+1. Less flexibility in configuration.
+
+## Why would I install an omnibus package when I can use a system package?
+
+The answer can be simplified to: less maintenance required. Instead of handling
+multiple packages that *can* break existing functionality if the versions are
+not compatible, only handle one.
+
+Multiple packages require correct configuration in multiple locations.
+Keeping configuration in sync can be error prone.
+
+If you have the skill set to maintain all current dependencies and enough time
+to handle any future dependencies that might get introduced, the above listed
+reasons might not be good enough for you to not use the omnibus package.
+
+There are two things to keep in mind before going down this route:
+
+1. Getting support for any problems
+   you encounter might be more difficult due to the number of possibilities that exist
+   when using a library version that is not tested by majority of users.
+1. Omnibus package also allows shutting off of any services that you do not need,
+   if you need to run a component independently. For example, you can use a
+   [non-bundled PostgreSQL database](https://docs.gitlab.com/omnibus/settings/database.html#using-a-non-packaged-postgresql-database-management-server) with the omnibus package.
+
+Keep in mind that a non-standard solution like the omnibus package
+might be a better fit when the application has a number of moving parts.
+
+## Docker image with multiple services
+
+[GitLab Docker image](../../install/docker.md#gitlab-docker-images) is based on the omnibus package.
+
+Considering that container spawned from this image contains multiple processes,
+these types of containers are also referred to as 'fat containers'.
+
+There are reasons for and against an image like this, but they are similar to
+what was noted above:
+
+1. Very simple to get started.
+1. Upgrading to the latest version is extremely simple.
+1. Running separate services in multiple containers and keeping them running
+   can be more complex and might not be required for a given install.
+
+This method is useful for organizations just getting started with containers and schedulers, and may not be ready for a more complex installation. This method is a great introduction, and will work well for smaller organizations.

doc/administration/package-information/postgresql_versions.md

+---
+stage: Enablement
+group: Distribution
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+---
+
+# PostgreSQL versions shipped with Omnibus GitLab
+
+NOTE:
+This table lists only GitLab versions where a significant change happened in the
+package regarding PostgreSQL versions, not all.
+
+Usually, PostgreSQL versions change with major or minor GitLab releases. However, patch versions
+of Omnibus GitLab sometimes update the patch level of PostgreSQL.
+
+For example:
+
+- Omnibus 12.7.6 shipped with PostgreSQL 9.6.14 and 10.9.
+- Omnibus 12.7.7 shipped with PostgreSQL 9.6.17 and 10.12.
+
+[Find out which versions of PostgreSQL (and other components) ship with
+each Omnibus GitLab release](https://gitlab-org.gitlab.io/omnibus-gitlab/licenses.html).
+
+Read more about update policies and warnings in the PostgreSQL
+[upgrade docs](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server).
+
+| GitLab version | PostgreSQL versions | Default version for fresh installs | Default version for upgrades | Notes |
+| -------------- | --------------------- | ---------------------------------- | ---------------------------- | ----- |
+| 14.1 | 12.6, 13.3 | 12.6 | 12.6 | PostgreSQL 13 available for fresh installations if not using Geo or High Availability. |
+| 14.0 | 12.6       | 12.6 | 12.6 | HA installations with repmgr are no longer supported and will be prevented from upgrading to Omnibus GitLab 14.0 |
+| 13.8 | 11.9, 12.4 | 12.4 | 12.4 | Package upgrades automatically performed PostgreSQL upgrade for nodes that are not part of a Geo or HA cluster.). |
+| 13.7 | 11.9, 12.4 | 12.4 | 11.9 | For upgrades users can manually upgrade to 12.4 following the [upgrade docs](https://docs.gitlab.com/omnibus/settings/database.html#gitlab-133-and-later). |
+| 13.4 | 11.9, 12.4 | 11.9 | 11.9 | Package upgrades aborted if users not running PostgreSQL 11 already |
+| 13.3 | 11.7, 12.3 | 11.7 | 11.7 | Package upgrades aborted if users not running PostgreSQL 11 already |
+| 13.0 | 11.7 | 11.7 | 11.7 | Package upgrades aborted if users not running PostgreSQL 11 already |
+| 12.10 | 9.6.17, 10.12, and 11.7 | 11.7 | 11.7 | Package upgrades automatically performed PostgreSQL upgrade for nodes that are not part of a Geo or repmgr cluster. |
+| 12.8 | 9.6.17, 10.12, and 11.7 | 10.12 | 10.12 | Users can manually upgrade to 11.7 following the upgrade docs. |
+| 12.0 | 9.6.11 and 10.7 | 10.7 | 10.7 | Package upgrades automatically performed PostgreSQL upgrade. |
+| 11.11 | 9.6.11 and 10.7 | 9.6.11 | 9.6.11 | Users can manually upgrade to 10.7 following the upgrade docs. |
+| 10.0 | 9.6.3 | 9.6.3 | 9.6.3 | Package upgrades aborted if users still on 9.2. |
+| 9.0 | 9.2.18 and 9.6.1 | 9.6.1 | 9.6.1 | Package upgrades automatically performed PostgreSQL upgrade. |
+| 8.14 | 9.2.18 and 9.6.1 | 9.2.18 | 9.2.18 | Users can manually upgrade to 9.6 following the upgrade docs. |

doc/administration/package-information/signed_packages.md

+---
+stage: Enablement
+group: Distribution
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+---
+
+# Package Signatures
+
+As of the release of GitLab 9.5 on August 22, 2017, GitLab provides signed Omnibus GitLab packages for RPM and DEB based distributions. This means that all packages provided on <https://packages.gitlab.com> are signed, starting with `9.5.0`, and all future versions of supported branches (e.g. `9.3.x` and `9.4.x` after August 22, 2017). Any package version prior to August 22, 2017, will not be signed. Please pass the appropriate argument to your package manager. (Example: `yum --nogpgcheck`)
+
+Omnibus GitLab packages produced by GitLab are created via the [Omnibus](https://github.com/chef/omnibus) tool, for which GitLab has added DEB signing via `debsigs` in [our own fork](https://gitlab.com/gitlab-org/omnibus). This addition, combined with the existing functionality of RPM signing, allows GitLab to provide signed packages for all supported distributions using DEB or RPM.
+
+These packages are produced by the GitLab CI process, as found in the  [Omnibus GitLab project](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/.gitlab-ci.yml), prior to their delivery to <https://packages.gitlab.com> to ensure provide assurance that the packages are not altered prior to delivery to our community.
+
+## GnuPG Public Keys
+
+All packages are signed with [GnuPG](https://www.gnupg.org/), in a method appropriate for their format. The key used to sign these packages can be found on [pgp.mit.edu](https://pgp.mit.edu) at [0x3cfcf9baf27eab47](https://pgp.mit.edu/pks/lookup?op=vindex&search=0x3CFCF9BAF27EAB47)
+
+## Verifying Signatures
+
+Information on how to verify GitLab package signatures can be found in [Package Signatures](https://docs.gitlab.com/omnibus/update/package_signatures.html).
+
+## GPG Signature Management
+
+Information on how GitLab manages GPG keys for package signing can be found in [the runbooks](https://gitlab.com/gitlab-com/runbooks/-/blob/master/docs/packaging/manage-package-signing-keys.md).

doc/administration/pages/index.md

@@ -1278,7 +1278,7 @@ in all of your GitLab Pages instances.
 
 ### 500 error with `securecookie: failed to generate random iv` and `Failed to save the session`
 
-This problem most likely results from an [out-dated operating system](https://docs.gitlab.com/omnibus/package-information/deprecated_os.html).
+This problem most likely results from an [out-dated operating system](../package-information/deprecated_os.md).
 The [Pages daemon uses the `securecookie` library](https://gitlab.com/search?group_id=9970&project_id=734943&repository_ref=master&scope=blobs&search=securecookie&snippets=false) to get random strings via [`crypto/rand` in Go](https://golang.org/pkg/crypto/rand/#pkg-variables).
 This requires the `getrandom` system call or `/dev/urandom` to be available on the host OS.
 Upgrading to an [officially supported operating system](https://about.gitlab.com/install/) is recommended.

doc/administration/postgresql/replication_and_failover.md

@@ -72,13 +72,13 @@ the PgBouncer service.
 
 ### Connection flow
 
-Each service in the package comes with a set of [default ports](https://docs.gitlab.com/omnibus/package-information/defaults.html#ports). You may need to make specific firewall rules for the connections listed below:
+Each service in the package comes with a set of [default ports](../package-information/defaults.md#ports). You may need to make specific firewall rules for the connections listed below:
 
-- Application servers connect to either PgBouncer directly via its [default port](https://docs.gitlab.com/omnibus/package-information/defaults.html#pgbouncer) or via a configured Internal Load Balancer (TCP) that serves multiple PgBouncers.
-- PgBouncer connects to the primary database servers [PostgreSQL default port](https://docs.gitlab.com/omnibus/package-information/defaults.html#postgresql)
+- Application servers connect to either PgBouncer directly via its [default port](../package-information/defaults.md) or via a configured Internal Load Balancer (TCP) that serves multiple PgBouncers.
+- PgBouncer connects to the primary database servers [PostgreSQL default port](../package-information/defaults.md)
 - Patroni actively manages the running PostgreSQL processes and configuration.
-- PostgreSQL secondaries connect to the primary database servers [PostgreSQL default port](https://docs.gitlab.com/omnibus/package-information/defaults.html#postgresql)
-- Consul servers and agents connect to each others [Consul default ports](https://docs.gitlab.com/omnibus/package-information/defaults.html#consul)
+- PostgreSQL secondaries connect to the primary database servers [PostgreSQL default port](../package-information/defaults.md)
+- Consul servers and agents connect to each others [Consul default ports](../package-information/defaults.md)
 
 ## Setting it up
 
@@ -306,7 +306,7 @@ If you enable Monitoring, it must be enabled on **all** database servers.
 #### Enable TLS support for the Patroni API
 
 By default, Patroni's [REST API](https://patroni.readthedocs.io/en/latest/rest_api.html#rest-api) is served over HTTP.
-You have the option to enable TLS and use HTTPS over the same [port](https://docs.gitlab.com/omnibus/package-information/defaults.html#patroni).
+You have the option to enable TLS and use HTTPS over the same [port](../package-information/defaults.md).
 
 To enable TLS, you need PEM-formatted certificate and private key files. Both files must be readable by the PostgreSQL user (`gitlab-psql` by default, or the one set by `postgresql['username']`):
 
@@ -789,7 +789,7 @@ You do not need any special consideration for Patroni while provisioning your da
 
 Patroni monitors the cluster and handles any failover. When the primary node fails it works with Consul to notify PgBouncer. On failure, Patroni handles the transitioning of the old primary to a replica and rejoins it to the cluster automatically.
 
-With Patroni, the connection flow is slightly different. Patroni on each node connects to Consul agent to join the cluster. Only after this point it decides if the node is the primary or a replica. Based on this decision, it configures and starts PostgreSQL which it communicates with directly over a Unix socket. This means that if the Consul cluster is not functional or does not have a leader, Patroni and by extension PostgreSQL does not start. Patroni also exposes a REST API which can be accessed via its [default port](https://docs.gitlab.com/omnibus/package-information/defaults.html#patroni)
+With Patroni, the connection flow is slightly different. Patroni on each node connects to Consul agent to join the cluster. Only after this point it decides if the node is the primary or a replica. Based on this decision, it configures and starts PostgreSQL which it communicates with directly over a Unix socket. This means that if the Consul cluster is not functional or does not have a leader, Patroni and by extension PostgreSQL does not start. Patroni also exposes a REST API which can be accessed via its [default port](../package-information/defaults.md)
 on each node.
 
 ### Check replication status

doc/development/deprecation_guidelines/index.md

@@ -32,6 +32,6 @@ It also should be [deprecated in advance](https://about.gitlab.com/handbook/mark
 
 For API removals, see the [GraphQL](../../api/graphql/index.md#deprecation-and-removal-process) and [GitLab API](../../api/index.md#compatibility-guidelines) guidelines.
 
-For configuration removals, see the [Omnibus deprecation policy](https://docs.gitlab.com/omnibus/package-information/deprecation_policy.html).
+For configuration removals, see the [Omnibus deprecation policy](../../administration/package-information/deprecation_policy.md).
 
 For versioning and upgrade details, see our [Release and Maintenance policy](../../policy/maintenance.md).

doc/development/pipelines.md

@@ -450,7 +450,7 @@ In addition, there are a few circumstances where we would always run the full Je
 ### PostgreSQL versions testing
 
 Our test suite runs against PG12 as GitLab.com runs on PG12 and
-[Omnibus defaults to PG12 for new installs and upgrades](https://docs.gitlab.com/omnibus/package-information/postgresql_versions.html),
+[Omnibus defaults to PG12 for new installs and upgrades](../administration/package-information/postgresql_versions.md),
 Our test suite is currently running against PG11, since GitLab.com still runs on PG11.
 
 We do run our test suite against PG11 on nightly scheduled pipelines as well as upon specific
@@ -467,7 +467,7 @@ database library changes in MRs and `main` pipelines (with the `rspec db-library
 
 #### Long-term plan
 
-We follow the [PostgreSQL versions shipped with Omnibus GitLab](https://docs.gitlab.com/omnibus/package-information/postgresql_versions.html):
+We follow the [PostgreSQL versions shipped with Omnibus GitLab](../administration/package-information/postgresql_versions.md):
 
 | PostgreSQL version | 13.11 (April 2021)     | 13.12 (May 2021)       | 14.0 (June 2021?)      |
 | -------------------| ---------------------- | ---------------------- | ---------------------- |

doc/install/docker.md

@@ -368,7 +368,7 @@ You can then access your GitLab instance at `http://198.51.100.1/` and `https://
 
 ### Expose GitLab on different ports
 
-GitLab will occupy [some ports](https://docs.gitlab.com/omnibus/package-information/defaults.html)
+GitLab will occupy [some ports](../administration/package-information/defaults.md)
 inside the container.
 
 If you want to use a different host port than `80` (HTTP) or `443` (HTTPS),

doc/install/requirements.md

@@ -36,7 +36,7 @@ For the installation options, see [the main installation page](index.md).
 Installation of GitLab on these operating systems is possible, but not supported.
 Please see the [installation from source guide](installation.md) and the [installation guides](https://about.gitlab.com/install/) for more information.
 
-Please see [OS versions that are no longer supported](https://docs.gitlab.com/omnibus/package-information/deprecated_os.html) for Omnibus installs page
+Please see [OS versions that are no longer supported](../administration/package-information/deprecated_os.md) for Omnibus installs page
 for a list of supported and unsupported OS versions as well as the last support GitLab version for that OS.
 
 ### Microsoft Windows

doc/update/package/index.md

@@ -183,7 +183,7 @@ To download and install GitLab:
 
 ### GitLab 13.7 and later unavailable on Amazon Linux 2
 
-Amazon Linux 2 is not an [officially supported operating system](https://docs.gitlab.com/omnibus/package-information/deprecated_os.html#supported-operating-systems).
+Amazon Linux 2 is not an [officially supported operating system](../../administration/package-information/deprecated_os.md#supported-operating-systems).
 However, in past the [official package installation script](https://packages.gitlab.com/gitlab/gitlab-ee/install)
 installed the `el/6` package repository if run on Amazon Linux. From GitLab 13.7, we no longer
 provide `el/6` packages so administrators must run the [installation script](https://packages.gitlab.com/gitlab/gitlab-ee/install)

doc/update/plan_your_upgrade.md

@@ -18,7 +18,7 @@ General notes:
   to create your plan, share details of your architecture, including:
   - How is GitLab installed?
   - What is the operating system of the node?
-    (check [OS versions that are no longer supported](https://docs.gitlab.com/omnibus/package-information/deprecated_os.html) to confirm that later updates are available).
+    (check [OS versions that are no longer supported](../administration/package-information/deprecated_os.md) to confirm that later updates are available).
   - Is it a single-node or a multi-node setup? If multi-node, share any architectural details about each node with us.
   - Are you using [GitLab Geo](../administration/geo/index.md)? If so, share any architectural details about each secondary node.
   - What else might be unique or interesting in your setup that might be important for us to understand?
@@ -112,7 +112,7 @@ to your instance and then upgrade it for any relevant features you're using.
   - [Determine what upgrade path](index.md#upgrade-paths) to follow.
   - Account for any [version-specific update instructions](index.md#version-specific-upgrading-instructions).
   - Account for any [version-specific changes](package/index.md#version-specific-changes).
-  - Check the [OS compatibility with the target GitLab version](https://docs.gitlab.com/omnibus/package-information/deprecated_os.html).
+  - Check the [OS compatibility with the target GitLab version](../administration/package-information/deprecated_os.md).
 - Due to background migrations, plan to pause any further upgrades after upgrading
   to a new major version.
   [All migrations must finish running](index.md#checking-for-background-migrations-before-upgrading)
@@ -123,7 +123,7 @@ to your instance and then upgrade it for any relevant features you're using.
 - About PostgreSQL:
   - On the top bar, select **Menu > Admin**, and look for the version of
     PostgreSQL you are using.
-    If [a PostgreSQL upgrade is needed](https://docs.gitlab.com/omnibus/package-information/postgresql_versions.html),
+    If [a PostgreSQL upgrade is needed](../administration/package-information/postgresql_versions.md),
     account for the relevant
     [packaged](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server)
     or [non-packaged](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-a-non-packaged-postgresql-database) steps.

doc/user/project/import/index.md

@@ -76,7 +76,7 @@ a self-managed instance from an old server to a new server.
 
 The backups produced don't depend on the operating system running GitLab. You can therefore use
 the restore method to switch between different operating system distributions or versions, as long
-as the same GitLab version [is available for installation](https://docs.gitlab.com/omnibus/package-information/deprecated_os.html).
+as the same GitLab version [is available for installation](../../../administration/package-information/deprecated_os.md).
 
 To instead merge two self-managed GitLab instances together, use the instructions in
 [Migrate from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom).