Add latest changes from gitlab-org/gitlab@master

5 files changed, 103 insertions, 77 deletions

diff --git a/doc/administration/high_availability/README.md b/doc/administration/high_availability/README.md
index 88f1079dec5..2bc2f28e4c5 100644
--- a/doc/administration/high_availability/README.md
+++ b/doc/administration/high_availability/README.md
@@ -4,62 +4,80 @@ type: reference, concepts
 
 # Scaling and High Availability
 
-GitLab supports a number of options for larger self-managed instances to
-ensure that they are scalable and highly available. While these needs can be tackled
-individually, they typically go hand in hand: a performant scalable environment
-will have availability by default, as its components are separated and pooled.
+GitLab supports a number of scaling options to ensure that your self-managed
+instance is able to scale out to meet your organization's needs when scaling up
+is no longer practical or feasible.
 
-On this page, we present a maturity model for a progression from simple to complex
-GitLab installations as your GitLab usage evolves. For larger setups we give several recommended
-architectures based on experience with GitLab.com and internal scale
-testing that aim to achieve the right balance between both scalability
-and availability.
+GitLab also offers high availability options for organizations that require
+the fault tolerance and redundancy necessary to maintain high-uptime operations.
+
+Scaling and high availability can be tackled separately as GitLab comprises
+modular components which can be individually scaled or made highly available
+depending on your organization's needs and resources.
+
+On this page, we present examples of self-managed instances which demonstrate
+how GitLab can be scaled out and made highly available. These examples progress
+from simple to complex as scaling or highly-available components are added.
+
+For larger setups serving 2,000 or more users, we provide
+[reference architectures](#reference-architectures) based on GitLab's
+experience with GitLab.com and internal scale testing that aim to achieve the
+right balance of scalability and availability.
 
 For detailed insight into how GitLab scales and configures GitLab.com, you can
 watch [this 1 hour Q&A](https://www.youtube.com/watch?v=uCU8jdYzpac)
 with [John Northrup](https://gitlab.com/northrup), and live questions coming
 in from some of our customers.
 
-## Maturity levels
+## Scaling examples
 
-### Level 1: Single-node Omnibus installation
+### Single-node Omnibus installation
 
 This solution is appropriate for many teams that have a single server at their disposal. With automatic backup of the GitLab repositories, configuration, and the database, this can be an optimal solution if you don't have strict availability requirements.
 
-This configuration is supported in [GitLab Starter, Premium and Ultimate](https://about.gitlab.com/pricing/).
+You can also optionally configure GitLab to use an [external PostgreSQL service](../external_database.md)
+or an [external object storage service](object_storage.md) for added
+performance and reliability at a relatively low complexity cost.
 
 References:
 
 - [Installation Docs](../../install/README.md)
 - [Backup/Restore Docs](https://docs.gitlab.com/omnibus/settings/backups.html#backup-and-restore-omnibus-gitlab-configuration)
 
-### Level 2: Multiple application servers
+### Omnibus installation with multiple application servers
 
-By separating components you can see a number of advantages compared to a single-node setup. Namely, you can:
+This solution is appropriate for teams that are starting to scale out when
+scaling up is no longer meeting their needs. In this configuration, additional application nodes will handle frontend traffic, with a load balancer in front to distribute traffic across those nodes. Meanwhile, each application node connects to a shared file server and PostgreSQL and Redis services on the back end.
 
-- Increase the number of users
-- Enable zero-downtime upgrades
-- Increase availability
-
-Additional application nodes will handle frontend traffic, with a load balancer in front to distribute traffic across those nodes. Meanwhile, each application node connects to a shared file server and database systems on the back end. This way, if one of the application servers fails, the workflow is not interrupted.
-
-This configuration is supported in [GitLab Starter, Premium and Ultimate](https://about.gitlab.com/pricing/).
+The additional application servers adds limited fault tolerance to your GitLab
+instance. As long as one application node is online and capable of handling the
+instance's usage load, your team's productivity will not be interrupted. Having
+multiple application nodes also enables [zero-downtime updates](https://docs.gitlab.com/omnibus/update/#zero-downtime-updates).
 
 References:
 
-- [High Availability Reference Architectures](#reference-architectures), without HA components
+- [Configure your load balancer for GitLab](load_balancer.md)
+- [Configure your NFS server to work with GitLab](nfs.md)
+- [Configure packaged PostgreSQL server to listen on TCP/IP](https://docs.gitlab.com/omnibus/settings/database.html#configure-packaged-postgresql-server-to-listen-on-tcpip)
+- [Setting up a Redis-only server](https://docs.gitlab.com/omnibus/settings/redis.html#setting-up-a-redis-only-server)
 
-### Level 3: Highly Available
+## High-availability examples
 
-By adding automatic failover for database systems, we can enable higher uptime with an additional layer of complexity.
+### Omnibus installation with automatic database failover
 
-This configuration is supported in [GitLab Premium and Ultimate](https://about.gitlab.com/pricing/).
+By adding automatic failover for database systems, we can enable higher uptime with an additional layer of complexity.
 
-References:
+- For PostgreSQL, we provide repmgr for server cluster management and failover
+  and a combination of [PgBouncer](pgbouncer.md) and [Consul](consul.md) for
+  database client cutover.
+- For Redis, we use [Redis Sentinel](redis.md) for server failover and client cutover.
 
-- [High Availability Reference Architectures](#reference-architectures)
+You can also optionally run [additional Sidekiq processes on dedicated hardware](sidekiq.md)
+and configure individual Sidekiq processes to
+[process specific background job queues](../operations/extra_sidekiq_processes.md)
+if you need to scale out background job processing.
 
-### Level 4: GitLab Geo
+### GitLab Geo
 
 GitLab Geo allows you to replicate your GitLab instance to other geographical locations as a read-only fully operational instance that can also be promoted in case of disaster.
 
@@ -70,12 +88,6 @@ References:
 - [Geo Documentation](../geo/replication/index.md)
 - [GitLab Geo with a highly available configuration](../geo/replication/high_availability.md)
 
-## Recommended setups based on number of users
-
-- 1 - 1000 Users: A single-node [Omnibus](https://docs.gitlab.com/omnibus/) setup with frequent backups. Refer to the [requirements page](../../install/requirements.md) for further details of the specs you will require.
-- 1000 - 10000 Users: A scaled environment based on one of our [Reference Architectures](#reference-architectures), without the HA components applied. This can be a reasonable step towards a fully HA environment.
-- 2000 - 50000+ Users: A scaled HA environment based on one of our [Reference Architectures](#reference-architectures) below.
-
 ## GitLab components and configuration instructions
 
 The GitLab application depends on the following [components](../../development/architecture.md#component-diagram).
@@ -116,6 +128,12 @@ them.
 
 In some cases, components can be combined on the same nodes to reduce complexity as well.
 
+## Recommended setups based on number of users
+
+- 1 - 1000 Users: A single-node [Omnibus](https://docs.gitlab.com/omnibus/) setup with frequent backups. Refer to the [requirements page](../../install/requirements.md) for further details of the specs you will require.
+- 1000 - 10000 Users: A scaled environment based on one of our [Reference Architectures](#reference-architectures), without the HA components applied. This can be a reasonable step towards a fully HA environment.
+- 2000 - 50000+ Users: A scaled HA environment based on one of our [Reference Architectures](#reference-architectures) below.
+
 ## Reference architectures
 
 In this section we'll detail the Reference Architectures that can support large numbers
diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md
index 04af406a295..c1ab7730903 100644
--- a/doc/administration/instance_limits.md
+++ b/doc/administration/instance_limits.md
@@ -35,6 +35,14 @@ Read more in the [CI documentation](../ci/yaml/README.md#processing-git-pushes).
 
 Activity history for projects and individuals' profiles was limited to one year until [GitLab 11.4](https://gitlab.com/gitlab-org/gitlab-foss/issues/52246) when it was extended to two years, and in [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/33840) to three years.
 
+## Number of embedded metrics
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14939) in GitLab 12.7.
+
+There is a limit when embedding metrics in GFM for performance reasons.
+
+- **Max limit:** 100 embeds
+
 ## Number of webhooks
 
 On GitLab.com, the [maximum number of webhooks](../user/gitlab_com/index.md#maximum-number-of-webhooks) per project, and per group, is limited.
diff --git a/doc/api/deployments.md b/doc/api/deployments.md
index f34c8026ac4..250c63a8520 100644
--- a/doc/api/deployments.md
+++ b/doc/api/deployments.md
@@ -37,6 +37,7 @@ Example of response
   {
     "created_at": "2016-08-11T07:36:40.222Z",
     "updated_at": "2016-08-11T07:38:12.414Z",
+    "status": "created",
     "deployable": {
       "commit": {
         "author_email": "admin@example.com",
@@ -106,6 +107,7 @@ Example of response
   {
     "created_at": "2016-08-11T11:32:35.444Z",
     "updated_at": "2016-08-11T11:34:01.123Z",
+    "status": "created",
     "deployable": {
       "commit": {
         "author_email": "admin@example.com",
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index 705f9e41b39..41a87412ef9 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -100,12 +100,15 @@ The [documentation website](https://docs.gitlab.com) uses GitLab Kramdown as its
 
 The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown)
 Ruby gem will support all [GFM markup](../../user/markdown.md) in the future. That is,
-all markup that is supported for display in the GitLab application itself. For now,
+all markup supported for display in the GitLab application itself. For now,
 use regular Markdown markup, following the rules in the linked style guide.
 
 Note that Kramdown-specific markup (for example, `{:.class}`) will not render properly on GitLab instances under [`/help`](index.md#gitlab-help).
 
-Hard-coded HTML is valid, although it's discouraged to be used while we have `/help`. HTML is permitted as long as:
+### HTML in Markdown
+
+Hard-coded HTML is valid, although it's discouraged from being used while we have `/help`.
+HTML is permitted as long as:
 
 - There's no equivalent markup in Markdown.
 - Advanced tables are necessary.
@@ -130,7 +133,7 @@ to verify that proper capitalization and backticks are used. Words in backticks
 be ignored by markdownlint.
 
 In general, product names should follow the exact capitalization of the official names
-of the products, protocols, etc.
+of the products, protocols, and so on.
 
 Some examples that will fail if incorrect capitalization is used:
 
@@ -138,7 +141,7 @@ Some examples that will fail if incorrect capitalization is used:
 - NGINX (needs all capitals)
 - runit (needs lowercase `r`)
 
-Additionally, commands, parameters, values, filenames, etc. must be included in backticks.
+Additionally, commands, parameters, values, filenames, and so on must be included in backticks.
 For example:
 
 - "Change the `needs` keyword in your `.gitlab.yml`..."
@@ -198,7 +201,7 @@ The table below shows what kind of documentation goes where.
    1. `doc/user/group/` should contain all group related documentation.
    1. `doc/user/profile/` should contain all profile related documentation.
       Every page you would navigate under `/profile` should have its own document,
-      i.e. `account.md`, `applications.md`, `emails.md`, etc.
+      for example, `account.md`, `applications.md`, or `emails.md`.
    1. `doc/user/dashboard/` should contain all dashboard related documentation.
    1. `doc/user/admin_area/` should contain all admin related documentation
       describing what can be achieved by accessing GitLab's admin interface
@@ -235,7 +238,7 @@ Do not include the same information in multiple places. [Link to a SSOT instead.
 ### Structure within documents
 
 - Include any and all applicable subsections as described on the [structure and template](structure.md) page.
-- Structure content in alphabetical order in tables, lists, etc., unless there is
+- Structure content in alphabetical order in tables, lists, and so on, unless there is
   a logical reason not to (for example, when mirroring the UI or an otherwise ordered sequence).
 
 ## Language
@@ -271,9 +274,9 @@ Do not include the same information in multiple places. [Link to a SSOT instead.
   - Use "may" to indicate giving permission for someone to do something, or consider using "can" instead. "You may select either option on this screen." Or, "you can select either option on this screen."
 - We discourage use of Latin abbreviations, such as "e.g.," "i.e.," or "etc.,"
 as even native users of English might misunderstand them.
-  - Instead of "i.e.", use "that is."
-  - Instead of "e.g.", use "for example," "such as," "for instance," or "like."
-  - Instead of "etc.", either use "and so on" or consider editing it out, since it can be vague.
+  - Instead of "i.e.," use "that is."
+  - Instead of "e.g.," use "for example," "such as," "for instance," or "like."
+  - Instead of "etc.," either use "and so on" or consider editing it out, since it can be vague.
 
 ### Contractions
 
@@ -332,8 +335,9 @@ as even native users of English might misunderstand them.
 - [Write in Markdown](#markdown).
 - Splitting long lines (preferably up to 100 characters) can make it easier to provide feedback on small chunks of text.
 - Insert an empty line for new paragraphs.
+- Add a new line by ending a line with two spaces. [Using a backslash](../../user/markdown.md#newlines) doesn't work in the docs site.
 - Use sentence case for titles, headings, labels, menu items, and buttons.
-- Insert an empty line between different markups (e.g., after every paragraph, header, list, etc). Example:
+- Insert an empty line between different markups (for example, after every paragraph, header, list, and so on). Example:
 
   ```md
   ## Header
@@ -637,7 +641,7 @@ We include guidance for links in the following categories:
   It's easier to read, review, and maintain. **Do not** use `[Text][identifier]`.
 
 - Use [meaningful anchor texts](https://www.futurehosting.com/blog/links-should-have-meaningful-anchor-text-heres-why/).
-  E.g., instead of writing something like `Read more about GitLab Issue Boards [here](LINK)`,
+  For example, instead of writing something like `Read more about GitLab Issue Boards [here](LINK)`,
   write `Read more about [GitLab Issue Boards](LINK)`.
 
 ### Links to internal documentation
@@ -675,7 +679,8 @@ To link to internal documentation:
   - `../../issues/tags.md`
   - `../../issues/tags.md#stages`
 
-- Use the Markdown extension for the [`/help`](index.md#gitlab-help) section of GitLab.
+NOTE: **Note**:
+Using the Markdown extension is necessary for the [`/help`](index.md#gitlab-help) section of GitLab.
 
 ### Links requiring permissions
 
@@ -721,9 +726,9 @@ To indicate the steps of navigation through the UI:
 
 - Use the exact word as shown in the UI, including any capital letters as-is.
 - Use bold text for navigation items and the char "greater than" (`>`) as separator
-  (e.g., `Navigate to your project's **Settings > CI/CD**` ).
+  (for example, `Navigate to your project's **Settings > CI/CD**` ).
 - If there are any expandable menus, make sure to mention that the user
-  needs to expand the tab to find the settings you're referring to (e.g., `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`).
+  needs to expand the tab to find the settings you're referring to (for example, `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`).
 
 ## Images
 
@@ -852,7 +857,7 @@ nicely on different mobile devices.
 ## Code blocks
 
 - Always wrap code added to a sentence in inline code blocks (`` ` ``).
-  E.g., `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, `only: [master]`.
+  For example, `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, or `only: [master]`.
   File names, commands, entries, and anything that refers to code should be added to code blocks.
   To make things easier for the user, always add a full code block for things that can be
   useful to copy and paste, as they can easily do it with the button on code blocks.
@@ -1197,11 +1202,11 @@ belongs to, says the GitLab version that it became available in, and links to
 the pricing page in case the user wants to upgrade to a paid tier
 to use that feature.
 
-For example, if I'm a regular user and I'm looking at the docs for a feature I haven't used before,
-I can immediately see if that feature is available to me or not. Alternatively,
-if I have been using a certain feature for a long time and it changed in some way,
+For example, if you're a regular user and you're looking at the docs for a feature you haven't used before,
+you can immediately see if that feature is available to you or not. Alternatively,
+if you've been using a certain feature for a long time and it changed in some way,
 it's important
-to me to spot when it changed and what's new in that feature.
+to be able to spot when it changed and what's new in that feature.
 
 This is even more important as we don't have a perfect process for shipping docs.
 Unfortunately, we still see features without docs and docs without
@@ -1265,12 +1270,12 @@ badges and tooltips (`<span class="badge-trigger starter">`). When the keyword
 
 Certain styles should be applied to specific sections. Styles for specific sections are outlined below.
 
-### GitLab Restart
+### GitLab restart
 
 There are many cases that a restart/reconfigure of GitLab is required. To
 avoid duplication, link to the special document that can be found in
-[`doc/administration/restart_gitlab.md`][doc-restart]. Usually the text will
-read like:
+[`doc/administration/restart_gitlab.md`](../../administration/restart_gitlab.md).
+Usually the text will read like:
 
 ```md
 Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md)
@@ -1563,8 +1568,3 @@ restrict the sign-up e-mail domains of a GitLab instance to `*.example.com` and
 ```shell
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "domain_whitelist[]=*.example.com" --data "domain_whitelist[]=example.net" https://gitlab.example.com/api/v4/application/settings
 ```
-
-[single spaces]: http://www.slate.com/articles/technology/technology/2011/01/space_invaders.html
-[gfm]: ../../user/markdown.md#newlines "GitLab flavored markdown documentation"
-[ce-1242]: https://gitlab.com/gitlab-org/gitlab-foss/issues/1242
-[doc-restart]: ../../administration/restart_gitlab.md "GitLab restart documentation"
diff --git a/doc/user/markdown.md b/doc/user/markdown.md
index 666b0ce3500..866293302cf 100644
--- a/doc/user/markdown.md
+++ b/doc/user/markdown.md
@@ -821,32 +821,30 @@ Footnotes add a link to a note that will be rendered at the end of a Markdown fi
 To make a footnote, you need both a reference tag and a separate line (anywhere in the file) with
 the note content.
 
-Regardless of the tag names, the relative order of the reference tags determines the rendered numbering.
+Regardless of the tag names, the relative order of the reference tags determines the rendered
+numbering.
 
-```markdown
-A footnote reference tag looks like this:[^1]
-
-[^1]: This is the contents of a footnote.
+Reference tags can use letters and other characters. Avoid using lowercase `w` or an underscore
+(`_`) in footnote tag names until [this bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is
+resolved.
 
-Reference tags can use letters and other characters.[^footnote-note]
-
-Avoid using lowercase `w` or an underscore (`_`) in footnote tag names until
-[this bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved. [^this-name-has-w] [^this-name-has_]
+```markdown
+A footnote reference tag looks like this: [^1]
 
-[^this-name-has-w]: This won't be rendered, because the name contains "w".
+This reference tag is a mix of letters and numbers. [^footnote-42]
 
-[^this-name-has_]: This won be rendered, because the name contains an underscore.
+[^1]: This is the text inside a footnote.
 
+[^footnote-42]: This is another footnote.
 ```
 
-Reference tags can use letters and other characters.[^footnote-note]
+A footnote reference tag looks like this:[^1]
 
-Avoid using lowercase `w` or an underscore (`_`) in footnote tag names until
-[this bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved. [^this-name-has-w] [^this-name-has_]
+This reference tag is a mix of letters and numbers.[^footnote-42]
 
-[^this-name-has-w]: This won't be rendered, because the name contains "w".
+[^1]: This is the text inside a footnote.
 
-[^this-name-has_]: This won't be rendered, because the name contains an underscore.
+[^footnote-42]: This is another footnote.
 
 ### Headers