Merge branch 'master' into deps/5a89a91-3b3d888

config/software/patroni.rb

@@ -31,5 +31,9 @@ build do
   patch source: "add-license-file.patch"
+  # Version 1.0 of PrettyTable does not work with Patroni 1.6.4
+  # https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5701
+  command "#{install_dir}/embedded/bin/pip3 install prettytable==0.7.2", env: env
+
   command "#{install_dir}/embedded/bin/pip3 install patroni[consul]==#{version}", env: env
 end

config/software/registry.rb

@@ -22,6 +22,7 @@ name 'registry'
 version = Gitlab::Version.new('registry', 'v2.10.1-gitlab')
 default_version version.print(false)
+display_version version.print(false).delete_suffix('-gitlab')
 license 'Apache-2.0'
 license_file 'LICENSE'

config/templates/gitlab-cookbooks/patroni-config.json.erb

+{
+  "run_list": [
+      "recipe[<%= master_cookbook %>::config]",
+      "recipe[postgresql::enable]",
+      "recipe[patroni::enable]"
+  ]
+}
+

doc/.vale/gitlab/Acronyms.yml

@@ -76,6 +76,7 @@ exceptions:
   - SCSS
   - SDK
   - SHA
+  - SLA
   - SMTP
   - SQL
   - SSH

doc/.vale/gitlab/AlertBoxStyle.yml

@@ -3,6 +3,12 @@
 #
 # Makes sure alert boxes follow standard formatting.
 #
+# Checks for 4 known issues:
+# - Alert boxes with no colon, or colon outside the bold text
+# - Known incorrect capitalization of the most commonly used alert box text
+# - Alert boxes with the note text on the same line
+# - Alert boxes using blockquote formatting, like "> **Note:**"
+#
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence
 message: 'Alert box "%s" must use the formatting in the style guide.'

doc/.vale/gitlab/British.yml

@@ -67,7 +67,6 @@ swap:
   matt: matte
   meagre: meager
   metre: meter
-  mitre: miter
   modelling: modeling
   moustache: mustache
   neighbour: neighbor

doc/.vale/gitlab/InclusionAbleism.yml

+---
+# Suggestion: gitlab.InclusionAbleism
+#
+# Suggests alternatives for words that foster ableism.
+#
+# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+extends: substitution
+message: 'Use inclusive language. Consider "%s" instead of "%s".'
+link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#inclusive-language
+level: suggestion
+ignorecase: true
+swap:
+  sanity (?:check|test): check for completeness
+  dummy: placeholder, sample, fake

doc/.vale/gitlab/InclusionCultural.yml

+---
+# Warning: gitlab.InclusionCultural
+#
+# Suggests alternatives for words that are culturally inappropriate.
+#
+# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+extends: substitution
+message: 'Use inclusive language. Consider "%s" instead of "%s".'
+link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#inclusive-language
+level: warning
+ignorecase: true
+swap:
+  blacklist(?:ed|ing|s)?: denylist
+  whitelist(?:ed|ing|s)?: allowlist
+  master: primary, main
+  slave: secondary

doc/.vale/gitlab/InclusionGender.yml

+---
+# Suggestion: gitlab.InclusionGender
+#
+# Suggests alternatives for words that are gender-specific.
+#
+# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+extends: substitution
+message: 'Use inclusive language. Consider "%s" instead of "%s".'
+link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#inclusive-language
+level: suggestion
+ignorecase: true
+swap:
+  mankind: humanity, people
+  manpower: GitLab team members
+  he: they
+  his: their
+  she: they
+  hers: their

doc/.vale/gitlab/SubstitutionWarning.yml

@@ -12,7 +12,6 @@ level: warning
 ignorecase: true
 swap:
   admin: administrator
-  blacklist(ed|ing)?: denylist
   code base: codebase
   config: configuration
   distro: distribution
@@ -20,4 +19,3 @@ swap:
   filesystem: file system
   info: information
   repo: repository
-  whitelist(ed|ing)?: allowlist

doc/.vale/gitlab/spelling-exceptions.txt

@@ -76,6 +76,7 @@ Citus
 clonable
 Cloudwatch
 Cobertura
+Codepen
 Cognito
 colocated
 colocating
@@ -283,6 +284,7 @@ namespaces
 namespacing
 namespacings
 Nanoc
+Netlify
 NGINX
 Nokogiri
 npm
@@ -296,6 +298,7 @@ OmniAuth
 onboarding
 OpenID
 OpenShift
+Opsgenie
 Packagist
 parallelization
 parallelizations
@@ -380,6 +383,7 @@ reusability
 reverified
 reverifies
 reverify
+RHEL
 rollout
 rollouts
 rsync
@@ -402,6 +406,7 @@ sanitization
 sbt
 scatterplot
 scatterplots
+Schemastore
 Sendmail
 Sentry
 serializer

doc/README.md

@@ -25,7 +25,7 @@ For installation details, see [Installing Omnibus GitLab](installation/index.md)
 ## Running on a low-resource device (like a Raspberry Pi)
-You can run GitLab on supported low-resource computers like the Raspberry Pi 3, but you will need to tune the settings
+You can run GitLab on supported low-resource computers like the Raspberry Pi 3, but you must tune the settings
 to work best with the available resources. Check out the [documentation](settings/rpi.md) for suggestions on what to adjust.
 ## Maintenance
@@ -34,7 +34,7 @@ to work best with the available resources. Check out the [documentation](setting
 - [Starting and stopping](maintenance/README.md#starting-and-stopping)
 - [Invoking Rake tasks](maintenance/README.md#invoking-rake-tasks)
 - [Starting a Rails console session](maintenance/README.md#starting-a-rails-console-session)
-- [Starting a PostgreSQL superuser psql session](maintenance/README.md#starting-a-postgresql-superuser-psql-session)
+- [Starting a PostgreSQL superuser `psql` session](maintenance/README.md#starting-a-postgresql-superuser-psql-session)
 - [Container registry garbage collection](maintenance/README.md#container-registry-garbage-collection)
 ## Configuring
@@ -44,7 +44,7 @@ to work best with the available resources. Check out the [documentation](setting
 - [Storing Git data in an alternative directory](settings/configuration.md#storing-git-data-in-an-alternative-directory)
 - [Changing the name of the Git user group](settings/configuration.md#changing-the-name-of-the-git-user--group)
 - [Specify numeric user and group identifiers](settings/configuration.md#specify-numeric-user-and-group-identifiers)
-- [Only start Omnibus GitLab services after a given filesystem is mounted](settings/configuration.md#only-start-omnibus-gitlab-services-after-a-given-filesystem-is-mounted)
+- [Only start Omnibus GitLab services after a given file system is mounted](settings/configuration.md#only-start-omnibus-gitlab-services-after-a-given-file-system-is-mounted)
 - [Disable user and group account management](settings/configuration.md#disable-user-and-group-account-management)
 - [Disable storage directory management](settings/configuration.md#disable-storage-directories-management)
 - [Configuring Rack attack](settings/configuration.md#configuring-rack-attack)

doc/build/team_member_docs.md

@@ -43,6 +43,7 @@ details:
 | GITLAB_SHELL_VERSION                 | GITLAB_SHELL_VERSION                 | Git reference of the [GitLab Shell](https://gitlab.com/gitlab-org/gitlab-shell) repository.|
 | GITLAB_WORKHORSE_VERSION             | GITLAB_WORKHORSE_VERSION             | Git reference of the [GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) repository.|
 | GITLAB_ELASTICSEARCH_INDEXER_VERSION | GITLAB_ELASTICSEARCH_INDEXER_VERSION | Git reference of the [GitLab Elasticsearch Indexer](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer) repository. Used only in EE builds.|
+| GITLAB_KAS_VERSION                   | GITLAB_KAS_VERSION                   | Git reference of the [GitLab Kubernetes Agent Server](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) repository.|
 If you are running `package-and-qa` job from a GitLab MR, `GITLAB_VERSION`
 environment variable will be set to the commit SHA corresponding to the pipeline

doc/common_installation_problems/README.md

@@ -326,7 +326,7 @@ Expected process to exit with [0], but received '255'
 This is unlikely to happen with non virtualized machines but on a VPS with virtualization like openVZ, container might not have the required module enabled
 or container doesn't have access to kernel parameters.
-Try enabling the module on which sysctl errored out, on how to enable the module see example [here](https://serverfault.com/questions/477718/sysctl-p-etc-sysctl-conf-returns-error).
+Try [enabling the module](https://serverfault.com/questions/477718/sysctl-p-etc-sysctl-conf-returns-error) on which sysctl errored out.
 There is a reported workaround described in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/361) which requires editing the GitLab' internal recipe by supplying the switch which will ignore failures. Ignoring errors can have unexpected side effects on performance of your GitLab server so it is not recommended to do so.
@@ -470,7 +470,7 @@ sudo chown -R git:git /var/opt/gitlab/gitlab-rails/tmp/cache
 ## 'Short read or OOM loading DB' error
-Try cleaning the old Redis session by following the [documentation here.](https://docs.gitlab.com/ee/operations/cleaning_up_redis_sessions.html)
+Try [cleaning the old Redis session](https://docs.gitlab.com/ee/operations/cleaning_up_redis_sessions.html).
 ## Apt error 'The requested URL returned error: 403'

doc/development/managing-postgresql-versions.md

@@ -6,7 +6,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 # Managing PostgreSQL versions
-Usually, we are shipping three versions of PostgreSQL. We need to support running on all versions, as well as upgrading from the older versions to the newest.
+The PostgreSQL Global Development Group typically releases [one major version of PostgreSQL each year](https://www.postgresql.org/support/versioning/), usually in the third quarter. Our goal is to add support for the newest PostgreSQL release in the next major release of GitLab, and to support two versions of PostgreSQL at any given time. This means that in each major release of GitLab, we will remove the oldest version of PostgreSQL that we support, bump the minimally required PostgreSQL version up by one major version, and add support for the newest PostgreSQL version.
+
+## Example
+
+1. GitLab 14.0 (May 2021) supports PostgreSQL 12 and 13, with the default version for new installs and upgrades being PostgreSQL 12.
+1. PostgreSQL 14 is released in October 2021.
+1. In GitLab 14.x, the default version for new installs and upgrades is bumped to PostgreSQL 13.
+1. In GitLab 15.0 (May 2022) we remove PostgreSQL 12, minimally require PostgreSQL 13, and add support for PostgreSQL 14.
+
+We need to support running GitLab on both supported versions, as well as upgrading from the older versions to the newest.
+
+NOTE: **Note:**
+GitLab 13.0 to 13.3 will only have support for one version of PostgreSQL (11). This is an exception while the plan above is implemented.
 ## Software definitions
@@ -30,7 +42,15 @@ The [`gitlab-ctl pg-upgrade` command](https://gitlab.com/gitlab-org/omnibus-gitl
 ## Removing an older version
-When it is time to remove an older version, perform the following steps:
+When it is time to remove an older version, create an epic with issues to track the following:
+
+1. Remove the old version from Omnibus.
+1. Remove the old version from the Helm install.
+1. To minimize CI costs, remove the older version from test suites (before doing this, check that .com is not using the old version still).
+1. Remove references to that version of PostgreSQL in the GitLab user documentation.
+1. Start printing deprecation notices in the release post three GitLab versions before a major PostgreSQL version is removed. If the PostgreSQL version is a version that will be removed within three releases, print deprecation notices in the Admin UI and during the GitLab upgrade process, regardless of whether it is an Omnibus-managed PostgreSQL database or an external database.
+
+For removals, perform the following steps:
 1. Run `git rm config/software/postgresql_old.rb`
 1. Run `git mv config/software/postgresql{,_old}.rb`
@@ -40,8 +60,6 @@ When it is time to remove an older version, perform the following steps:
 ## Adding a new version
-We currently support shipping three versions:
-
 1. Run `git cp config/software/postgresql{,_new}.rb`
 1. Edit `config/software/postgresql_new.rb`. Update:
@@ -50,7 +68,40 @@ We currently support shipping three versions:
    1. `version` to have the new version, and the `sha256`
    1. `major_version` if necessary
-Additionally, ensure that:
+1. Add the new PostgreSQL version to the full test suite.
+1. Run a nightly test of the `gitlab-org/gitlab` repo against the new version of PostgreSQL.
+1. Ensure that the package build includes both versions of PostgreSQL.
+1. For Helm installs, update the default PostgreSQL chart version if the default is changing.
+1. Update user documentation.
+
+### Testing
+
+1. GitLab runs on the new version of PostgreSQL.
+1. Test running GitLab on the new PostgreSQL version at the 10k reference architecture scale and check for performance regressions.
+
+Test upgrades and fresh installs for the following environments:
+
+1. Single node.
+1. Install with a separate database node managed by Omnibus.
+1. HA database cluster with 3 or more database nodes in the cluster.
+1. Geo installations with a single node primary and single node secondary (`postgresql` and `geo-postgresql` on the same secondary node).
+1. Geo installations with a HA database cluster on the primary.
+1. Geo installations with a separate database and a separate tracking database on the secondary.
+1. Helm installs.
+1. After testing that upgrades to the newest version work, confirm that `revert-pg-upgrade` successfully downgrades to the previously used version, including on a Geo secondary standalone tracking database.
+1. If the default PostgreSQL version changes, test GitLab upgrades with external PostgreSQL databases.
+1. Back up and restore.
+If the default PostgreSQL version is changing:
+
+1. Auto upgrades on a single node install, separate database node, HA cluster.
+1. Auto upgrades where an external PostgreSQL database is being used.
+1. Geo installs are not auto upgraded.
+
+If the minimally required version is changing:
+
+1. GitLab upgrade errors out if an old version of Omnibus-managed PostgreSQL is still installed.
+
+If the above tests are manual, we risk missing a breaking change that is introduced after the manual tests have been performed. We should automate as many of these tests as possible.
 1. The package build includes both versions of PostgreSQL
 1. Running `gitlab-ctl pg-upgrade` works
@@ -59,3 +110,7 @@ Additionally, ensure that:
 Some modules, including `pyscopg2`, depend on PostgreSQL client library, i.e. `libpq`. It should be always linked to the
 latest bundled version. By using the latest version we rely on backward compatibility of `libpq`.
+
+## Known issues
+
+Geo uses streaming replication, which requires that the entire secondary database be resynced after a major PostgreSQL upgrade. This can cause hours or days of downtime, and as such, we do not recommend auto upgrades for Geo customers. Starting in 12.10, automatic PostgreSQL upgrades are disabled if Geo is detected.

doc/development/new-software-definition.md

@@ -22,9 +22,7 @@ When adding a component that should be fetched from Git the clone address of the
 repositories of the local mirror and upstream should be added to
 `/.custom_sources.yml`.
-The local mirror should be created in the <https://dev.gitlab.org/omnibus-mirror>
-project by a member of the Distribution team. It should have the
-`omnibus-builder deploy key` enabled.
+The local mirror should be created in the [omnibus-mirror project](omnibus-mirror.md) by a member of the Distribution team.
 See other Software services in the directory for examples on how to include your
 software service.

doc/development/omnibus-mirror.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-mirror
+
+In order to minimize the dependency on external resources during our build and release process, we maintain a mirror of various software dependencies within GitLab resources.
+
+The system consists of two groups, one on GitLab.com, and the other on `dev.gitlab.org`
+
+1. [GitLab.com projects](https://gitlab.com/gitlab-org/build/omnibus-mirror)
+
+   1. Pull mirrors of the upstream source, and push mirrors to the corresponding `dev.gitlab.org` project.
+   1. Publically available. Should be available to the `trigger-package` pipeline, as well as community developers for building custom `omnibus-gitlab` packages
+
+1. [`dev.gitlab.org` projects](https://dev.gitlab.org/omnibus-mirror)
+
+   1. Pipelines on `dev.gitlab.org` use these projects to build `omnibus-gitlab` projects. This includes the package releases, as well as builds used by GitLab Team members to build custom `omnibus-gitlab` packages for all supported platforms.
+
+## Adding a project
+
+1. Log into GitLab.com as the `gitlab-omnibus-mirror-bot`. Login details are in the Build vault in 1 Password
+1. Click on **New Project** to create a project
+   1. **Project name**: usually should match the upstream name
+   1. **Project URL**: Select `gitlab-org/build/omnibus-mirror` from the **Groups** sub-group in the drop-down
+   1. **Visibility Level**: Set this to **Public**
+   1. Leave the remaining options as their default, and click on **Create project**
+1. Set up the pull mirror
+   1. Click **Settings -> Repository** in the left hand menu
+   1. Click **Expand** next to the **Mirroring repositories** option
+   1. Set **Git repository URL** to the upstream URL we'll be mirroring
+   1. Change **Mirror direction** to **Pull**
+   1. Select the **Overwrite diverged branches** option
+   1. Click **Mirror repository** to add the pull mirror. Depending on the size of the repository, this can take a few minutes to run
+   1. Leave this page open as you will need it later
+1. Log into `dev.gitlab.org`. This can happen with your personal account
+1. Click on **New Project** to create a project
+   1. **Project name**: usually should match the upstream name
+   1. **Project URL**: Select `omnibus-mirror` from the **Groups** sub-group in the drop-down
+   1. Leave the remaining options as their default and click on **Create project**
+1. Enable the `omnibus-builder` deploy key
+   1. Navigate to **Settings -> Repository**
+   1. Click on **Expand** next to the **Deploy Keys** section
+   1. Click the **Privately accessible deploy keys** tab
+   1. Find the `omnibus-builder deploy key` and click on the **Enable** button next to it
+1. Setup the push mirror
+   1. Return to the **Mirroring repositories** page for the GitLab.com project
+   1. In **Git repository URL** enter the path to the `dev.gitlab.org` with `build_mirror_bot@` inserted between `https://` and `dev.gitlab.org`
+   1. In **Password** enter the `PAT` from the **Build Team Mirror Bot** entry in the **Build** vault in 1 Password
+   1. Leave the remaining options as their default, and click on **Mirror repository**
+   1. Click the **Update Now** button to trigger initial mirroring

doc/docker/README.md

@@ -6,29 +6,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 # GitLab Docker images
-The GitLab Docker images are monolithic images of GitLab running all the necessary
-services in a single container.
-NOTE: **Note:**
-The Docker images do not include a mail transport agent (MTA). The recommended solution is to add an MTA, such as Postfix or Sendmail, running in a separate container. Alternatively, install an MTA directly in the GitLab container, but this adds maintenance overhead as you'll likely need to reinstall the MTA after every upgrade of restart.
-
-NOTE: **Note:**
-To install GitLab on Kubernetes, take a look at
-[GitLab Helm Charts](https://docs.gitlab.com/charts/).
+The GitLab Docker images are monolithic images of GitLab running all the
+necessary services in a single container. If you instead want to install GitLab
+on Kubernetes, see [GitLab Helm Charts](https://docs.gitlab.com/charts/).
+Find GitLab's official Docker image at:
 - [GitLab Docker image in Docker Hub](https://hub.docker.com/r/gitlab/gitlab-ee/)
+The Docker images don't include a mail transport agent (MTA). The recommended
+solution is to add an MTA (such as Postfix or Sendmail) running in a separate
+container. As another option, you can install an MTA directly in the GitLab
+container, but this adds maintenance overhead as you'll likely need to reinstall
+the MTA after every upgrade or restart.
+
 In the following examples, if you want to use the latest RC image, use
 `gitlab/gitlab-ee:rc` instead.
-Docker installation is required, see the [official installation docs](https://docs.docker.com/install/).
-
 CAUTION: **Caution:**
 Docker for Windows is not officially supported. There are known issues with volume
 permissions, and potentially other unknown issues. If you are trying to run on Docker
 for Windows, see the [getting help page](https://about.gitlab.com/get-help/) for links
 to community resources (IRC, forum, etc.) to seek help from other users.
+## Prerequisites
+
+Docker is required. See the [official installation documentation](https://docs.docker.com/install/).
+
 ## Set up the volumes location
 Before setting everything else, configure a new environment variable `$GITLAB_HOME`
@@ -49,11 +53,11 @@ export GITLAB_HOME=$HOME/gitlab
 The GitLab container uses host mounted volumes to store persistent data:
-| Local location | Container location | Usage |
-| -------------- | ------------------ | ----- |
-| `$GITLAB_HOME/data`  | `/var/opt/gitlab` | For storing application data |
-| `$GITLAB_HOME/logs`  | `/var/log/gitlab` | For storing logs |
-| `$GITLAB_HOME/config`| `/etc/gitlab`     | For storing the GitLab configuration files |
+| Local location       | Container location | Usage                                       |
+|----------------------|--------------------|---------------------------------------------|
+| `$GITLAB_HOME/data`  | `/var/opt/gitlab`  | For storing application data.               |
+| `$GITLAB_HOME/logs`  | `/var/log/gitlab`  | For storing logs.                           |
+| `$GITLAB_HOME/config`| `/etc/gitlab`      | For storing the GitLab configuration files. |
 ## Installation
@@ -101,11 +105,9 @@ sudo docker run --detach \
 This will ensure that the Docker process has enough permissions to create the
 config files in the mounted volumes.
-NOTE: **Note:**
-You will also need to publish your Kerberos port (e.g., `--publish 8443:8443`)
-if you are using the [Kerberos
-integration](https://docs.gitlab.com/ee/integration/kerberos.html) **(STARTER ONLY)**.
-Failure to do so will prevent Git operations via Kerberos.
+If you're using the [Kerberos integration](https://docs.gitlab.com/ee/integration/kerberos.html) **(STARTER ONLY)**,
+you must also publish your Kerberos port (for example, `--publish 8443:8443`).
+Failing to do so prevents Git operations with Kerberos.
 The initialization process may take a long time. You can track this
 process with:
@@ -288,24 +290,20 @@ in order to reconfigure GitLab:
 sudo docker restart gitlab
 ```
-NOTE: **Note:**
 GitLab will reconfigure itself whenever the container starts.
-
 For more options about configuring GitLab, check the
 [configuration documentation](../settings/configuration.md).
 ### Pre-configure Docker container
-You can pre-configure the GitLab Docker image by adding the environment
-variable `GITLAB_OMNIBUS_CONFIG` to Docker run command. This variable can
-contain any `gitlab.rb` setting and will be evaluated before loading the
-container's `gitlab.rb` file. That way you can easily configure GitLab's
-external URL, make any database configuration or any other option from the
+You can pre-configure the GitLab Docker image by adding the environment variable
+`GITLAB_OMNIBUS_CONFIG` to Docker run command. This variable can contain any
+`gitlab.rb` setting and is evaluated before the loading of the container's
+`gitlab.rb` file. This behavior allows you to configure GitLab's external URL,
+and make database configuration or any other option from the
 [Omnibus GitLab template](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template).
-
-NOTE: **Note:**
-The settings contained in `GITLAB_OMNIBUS_CONFIG` will not be written to the
-`gitlab.rb` configuration file, they're evaluated on load.
+The settings contained in `GITLAB_OMNIBUS_CONFIG` aren't written to the
+`gitlab.rb` configuration file, and are evaluated on load.
 Here's an example that sets the external URL and enables LFS while starting
 the container:
@@ -343,7 +341,7 @@ the GitLab version you want to run, for example `gitlab/gitlab-ee:12.1.3-ce.0`.
 You can make Docker to use your IP address and forward all traffic to the
 GitLab container by modifying the `--publish` flag.
-To expose GitLab CE on IP `198.51.100.1`:
+To expose GitLab on IP `198.51.100.1`:
 ```shell
 sudo docker run --detach \
@@ -409,7 +407,6 @@ port `2289`:
    external_url "https://gitlab.example.com:8929"
    ```
-   NOTE: **Note:**
    The port specified in this URL must match the port published to the host by Docker.
    Additionally, if the NGINX listen port is not explicitly set in
    `nginx['listen_port']`, it will be pulled from the `external_url`.
@@ -455,7 +452,7 @@ To update GitLab that was [installed using Docker Engine](#install-gitlab-using-
    sudo docker rm gitlab
    ```
-1. Pull the new image. For example, the latest GitLab CE image:
+1. Pull the new image. For example, the latest GitLab image:
    ```shell
    sudo docker pull gitlab/gitlab-ee:latest
@@ -478,7 +475,6 @@ To update GitLab that was [installed using Docker Engine](#install-gitlab-using-
 On the first run, GitLab will reconfigure and update itself.
-NOTE: **Note:**
 Refer to the GitLab [Upgrade recommendations](https://docs.gitlab.com/ee/policy/maintenance.html#upgrade-recommendations)
 when upgrading between major versions.
@@ -494,7 +490,6 @@ To update GitLab that was [installed using Docker Compose](#install-gitlab-using
    docker-compose up -d
    ```
-   NOTE: **Note:**
    If you have used [tags](#use-tagged-versions-of-gitlab) instead, you'll need
    to first edit `docker-compose.yml`.
@@ -512,7 +507,8 @@ Read more on how to [back up and restore GitLab](https://docs.gitlab.com/ee/rake
 [GitLab CE Docker image](https://hub.docker.com/r/gitlab/gitlab-ce/)
-To install the Community Edition, replace `ee` with `ce` in the commands on this page. 
+To install the Community Edition, replace `ee` with `ce` in the commands on this
+page.
 ## Troubleshooting
@@ -602,5 +598,32 @@ If these are not correct, set them with:
 sudo setfacl -mR default:group:docker:rwx $GITLAB_HOME
 ```
-NOTE: **Note:**
-`docker` is the default group, if you've changed this, update your commands accordingly.
+The default group is `docker`. If you changed the group, be sure to update your
+commands.
+
+### /dev/shm mount not having enough space in Docker container
+
+GitLab comes with a Prometheus metrics endpoint at `/-/metrics` to expose a
+variety of statistics on the health and performance of GitLab. The files
+required for this gets written to a temporary file system (like `/run` or
+`/dev/shm`).
+
+By default, Docker allocates 64Mb to the shared memory directory (mounted at
+`/dev/shm`). This is insufficient to hold all the Prometheus metrics related
+files generated, and will generate error logs like the following:
+
+```plaintext
+writing value to /dev/shm/gitlab/sidekiq/gauge_all_sidekiq_0-1.db failed with unmapped file
+writing value to /dev/shm/gitlab/sidekiq/gauge_all_sidekiq_0-1.db failed with unmapped file
+writing value to /dev/shm/gitlab/sidekiq/gauge_all_sidekiq_0-1.db failed with unmapped file
+writing value to /dev/shm/gitlab/sidekiq/histogram_sidekiq_0-0.db failed with unmapped file
+writing value to /dev/shm/gitlab/sidekiq/histogram_sidekiq_0-0.db failed with unmapped file
+writing value to /dev/shm/gitlab/sidekiq/histogram_sidekiq_0-0.db failed with unmapped file
+writing value to /dev/shm/gitlab/sidekiq/histogram_sidekiq_0-0.db failed with unmapped file
+```
+
+Other than disabling the Prometheus Metrics from the Admin page, the recommended
+solution to fix this problem is to increase the size of shm to at least 256Mb.
+If using `docker run`, this can be done by passing the flag `--shm-size 256m`.
+If using a `docker-compose.yml` file, the `shm_size` key can be used for this
+purpose.

doc/gitlab-mattermost/README.md

@@ -276,6 +276,7 @@ Below is a list of Mattermost versions for GitLab 11.10 and later:
 | 13.2 | 5.24 |
 | 13.3 | 5.25 |
 | 13.4 | 5.26 |
+| 13.5 | 5.27 |
 Starting with GitLab 11.0, GitLab Mattermost can be upgraded through the regular Omnibus GitLab update process. When upgrading previous versions of
 GitLab that process can only be used if Mattermost configuration settings have not been changed outside of GitLab (i.e., no changes to Mattermost's `config.json`