Merge branch 'update-gitaly-ref-arch' into 'master'

Update the Gitaly section to be the same on all pages See merge request gitlab-org/gitlab!44474

Merge branch 'update-gitaly-ref-arch' into 'master'
Update the Gitaly section to be the same on all pages See merge request gitlab-org/gitlab!44474
4bd6e136 · Craig Norris · 8036f796 · c7b93ae7 · 4bd6e136 · 4bd6e136
Commit 4bd6e136 authored Oct 07, 2020 by Craig Norris
5 changed files
--- a/doc/administration/reference_architectures/10k_users.md
+++ b/doc/administration/reference_architectures/10k_users.md
@@ -1364,52 +1364,48 @@ To configure the Sentinel Queues server:
 ## Configure Gitaly
-Deploying Gitaly in its own server can benefit GitLab installations that are
+[Gitaly](../gitaly/index.md) server node requirements are dependent on data,
-larger than a single machine.
+specifically the number of projects and those projects' sizes. It's recommended
+that a Gitaly server node stores no more than 5 TB of data. Although this
-The Gitaly node requirements are dependent on customer data, specifically the number of
+reference architecture includes a recommendation for the number of Gitaly server
-projects and their repository sizes. Two nodes are recommended as an absolute minimum.
+nodes to use, depending on your storage requirements, you may require additional
-Each Gitaly node should store no more than 5TB of data and have the number of
+Gitaly server nodes.
-[`gitaly-ruby` workers](../gitaly/index.md#gitaly-ruby) set to 20% of available CPUs.
-Additional nodes should be considered in conjunction with a review of expected
+Due to Gitaly having notable input and output requirements, we strongly
-data size and spread based on the recommendations above.
+recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should
+have a throughput of at least 8,000 input/output operations per second (IOPS)
-It is also strongly recommended that all Gitaly nodes be set up with SSD disks with
+for read operations and 2,000 IOPS for write operations. These IOPS values are
-a throughput of at least 8,000 IOPS for read operations and 2,000 IOPS for write,
+initial recommendations, and may be adjusted to greater or lesser values
-as Gitaly has heavy I/O. These IOPS values are recommended only as a starter as with
+depending on the scale of your environment's workload. If you're running the
-time they may be adjusted higher or lower depending on the scale of your environment's workload.
+environment on a Cloud provider, refer to their documentation about how to
-If you're running the environment on a Cloud provider, you may need to refer to
+configure IOPS correctly.
-their documentation on how to configure IOPS correctly.
+Be sure to note the following items:
-Some things to note:
+- The GitLab Rails application shards repositories into
- The GitLab Rails application shards repositories into [repository storages](../repository_storage_paths.md).
+  [repository storage paths](../repository_storage_paths.md).
- A Gitaly server can host one or more storages.
+- A Gitaly server can host one or more storage paths.
- A GitLab server can use one or more Gitaly servers.
+- A GitLab server can use one or more Gitaly server nodes.
- Gitaly addresses must be specified in such a way that they resolve
+- Gitaly addresses must be specified to be correctly resolvable for _all_
-  correctly for ALL Gitaly clients.
+  Gitaly clients.
 - Gitaly servers must not be exposed to the public internet, as Gitaly's network
  traffic is unencrypted by default. The use of a firewall is highly recommended
  to restrict access to the Gitaly server. Another option is to
  [use TLS](#gitaly-tls-support).
-TIP: **Tip:**
+NOTE: **Note:**
-For more information about Gitaly's history and network architecture see the
+The token referred to throughout the Gitaly documentation is an arbitrary
-[standalone Gitaly documentation](../gitaly/index.md).
+password selected by the administrator. This token is unrelated to tokens
+created for the GitLab API or other similar web API tokens.
-Note: **Note:**
-The token referred to throughout the Gitaly documentation is
-just an arbitrary password selected by the administrator. It is unrelated to
-tokens created for the GitLab API or other similar web API tokens.
-Below we describe how to configure two Gitaly servers, with IPs and
+This section describes how to configure two Gitaly servers, with the following
-domain names:
+IPs and domain names:
 - `10.6.0.91`: Gitaly 1 (`gitaly1.internal`)
 - `10.6.0.92`: Gitaly 2 (`gitaly2.internal`)
-The secret token is assumed to be `gitalysecret` and that
+Assumptions about your servers include having the secret token be `gitalysecret`,
-your GitLab installation has three repository storages:
+and that your GitLab installation has three repository storages:
 - `default` on Gitaly 1
 - `storage1` on Gitaly 1
@@ -1417,11 +1413,11 @@ your GitLab installation has three repository storages:
 On each node:
-1. [Download/Install](https://about.gitlab.com/install/) the Omnibus GitLab
+1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab
-   package you want using **steps 1 and 2** from the GitLab downloads page but
+   package you want (based on _steps 1 and 2_ on the GitLab downloads page), but
-   **without** providing the `EXTERNAL_URL` value.
+   _without_ providing the `EXTERNAL_URL` value.
-1. Edit `/etc/gitlab/gitlab.rb` to configure storage paths, enable
+1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable
-   the network listener and configure the token:
+   the network listener, and configure the token:
   <!--
   updates to following example must also be made at
@@ -1469,39 +1465,39 @@ On each node:
   ```
 1. Append the following to `/etc/gitlab/gitlab.rb` for each respective server:
-   1. On `gitaly1.internal`:
+   - On `gitaly1.internal`:
-      ```ruby
+     ```ruby
-      git_data_dirs({
+     git_data_dirs({
-        'default' => {
+       'default' => {
-          'path' => '/var/opt/gitlab/git-data'
+         'path' => '/var/opt/gitlab/git-data'
-        },
+       },
-        'storage1' => {
+       'storage1' => {
-          'path' => '/mnt/gitlab/git-data'
+         'path' => '/mnt/gitlab/git-data'
-        },
+       },
-      })
+     })
-      ```
+     ```
-   1. On `gitaly2.internal`:
+   - On `gitaly2.internal`:
-      ```ruby
+     ```ruby
-      git_data_dirs({
+     git_data_dirs({
-        'storage2' => {
+       'storage2' => {
-          'path' => '/mnt/gitlab/git-data'
+         'path' => '/mnt/gitlab/git-data'
-        },
+       },
-      })
+     })
-      ```
+     ```
   <!--
   updates to following example must also be made at
   https://gitlab.com/gitlab-org/charts/gitlab/blob/master/doc/advanced/external-gitaly/external-omnibus-gitaly.md#configure-omnibus-gitlab
   -->
-1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and replace
+1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and
-   the file of the same name on this server. If that file is not on this server,
+   then replace the file of the same name on this server. If that file isn't on
-   add the file from your Consul server to this server.
+   this server, add the file from your Consul server to this server.
-1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
+1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
 ### Gitaly TLS support

--- a/doc/administration/reference_architectures/25k_users.md
+++ b/doc/administration/reference_architectures/25k_users.md
@@ -1364,52 +1364,48 @@ To configure the Sentinel Queues server:
 ## Configure Gitaly
-Deploying Gitaly in its own server can benefit GitLab installations that are
+[Gitaly](../gitaly/index.md) server node requirements are dependent on data,
-larger than a single machine.
+specifically the number of projects and those projects' sizes. It's recommended
+that a Gitaly server node stores no more than 5 TB of data. Although this
-The Gitaly node requirements are dependent on customer data, specifically the number of
+reference architecture includes a recommendation for the number of Gitaly server
-projects and their repository sizes. Two nodes are recommended as an absolute minimum.
+nodes to use, depending on your storage requirements, you may require additional
-Each Gitaly node should store no more than 5TB of data and have the number of
+Gitaly server nodes.
-[`gitaly-ruby` workers](../gitaly/index.md#gitaly-ruby) set to 20% of available CPUs.
-Additional nodes should be considered in conjunction with a review of expected
+Due to Gitaly having notable input and output requirements, we strongly
-data size and spread based on the recommendations above.
+recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should
+have a throughput of at least 8,000 input/output operations per second (IOPS)
-It is also strongly recommended that all Gitaly nodes be set up with SSD disks with
+for read operations and 2,000 IOPS for write operations. These IOPS values are
-a throughput of at least 8,000 IOPS for read operations and 2,000 IOPS for write,
+initial recommendations, and may be adjusted to greater or lesser values
-as Gitaly has heavy I/O. These IOPS values are recommended only as a starter as with
+depending on the scale of your environment's workload. If you're running the
-time they may be adjusted higher or lower depending on the scale of your environment's workload.
+environment on a Cloud provider, refer to their documentation about how to
-If you're running the environment on a Cloud provider, you may need to refer to
+configure IOPS correctly.
-their documentation on how to configure IOPS correctly.
+Be sure to note the following items:
-Some things to note:
+- The GitLab Rails application shards repositories into
- The GitLab Rails application shards repositories into [repository storages](../repository_storage_paths.md).
+  [repository storage paths](../repository_storage_paths.md).
- A Gitaly server can host one or more storages.
+- A Gitaly server can host one or more storage paths.
- A GitLab server can use one or more Gitaly servers.
+- A GitLab server can use one or more Gitaly server nodes.
- Gitaly addresses must be specified in such a way that they resolve
+- Gitaly addresses must be specified to be correctly resolvable for _all_
-  correctly for ALL Gitaly clients.
+  Gitaly clients.
 - Gitaly servers must not be exposed to the public internet, as Gitaly's network
  traffic is unencrypted by default. The use of a firewall is highly recommended
  to restrict access to the Gitaly server. Another option is to
  [use TLS](#gitaly-tls-support).
-TIP: **Tip:**
+NOTE: **Note:**
-For more information about Gitaly's history and network architecture see the
+The token referred to throughout the Gitaly documentation is an arbitrary
-[standalone Gitaly documentation](../gitaly/index.md).
+password selected by the administrator. This token is unrelated to tokens
+created for the GitLab API or other similar web API tokens.
-Note: **Note:**
-The token referred to throughout the Gitaly documentation is
-just an arbitrary password selected by the administrator. It is unrelated to
-tokens created for the GitLab API or other similar web API tokens.
-Below we describe how to configure two Gitaly servers, with IPs and
+This section describes how to configure two Gitaly servers, with the following
-domain names:
+IPs and domain names:
 - `10.6.0.91`: Gitaly 1 (`gitaly1.internal`)
 - `10.6.0.92`: Gitaly 2 (`gitaly2.internal`)
-The secret token is assumed to be `gitalysecret` and that
+Assumptions about your servers include having the secret token be `gitalysecret`,
-your GitLab installation has three repository storages:
+and that your GitLab installation has three repository storages:
 - `default` on Gitaly 1
 - `storage1` on Gitaly 1
@@ -1417,11 +1413,11 @@ your GitLab installation has three repository storages:
 On each node:
-1. [Download/Install](https://about.gitlab.com/install/) the Omnibus GitLab
+1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab
-   package you want using **steps 1 and 2** from the GitLab downloads page but
+   package you want (based on _steps 1 and 2_ on the GitLab downloads page), but
-   **without** providing the `EXTERNAL_URL` value.
+   _without_ providing the `EXTERNAL_URL` value.
-1. Edit `/etc/gitlab/gitlab.rb` to configure storage paths, enable
+1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable
-   the network listener and configure the token:
+   the network listener, and configure the token:
   <!--
   updates to following example must also be made at
@@ -1469,39 +1465,39 @@ On each node:
   ```
 1. Append the following to `/etc/gitlab/gitlab.rb` for each respective server:
-   1. On `gitaly1.internal`:
+   - On `gitaly1.internal`:
-      ```ruby
+     ```ruby
-      git_data_dirs({
+     git_data_dirs({
-        'default' => {
+       'default' => {
-          'path' => '/var/opt/gitlab/git-data'
+         'path' => '/var/opt/gitlab/git-data'
-        },
+       },
-        'storage1' => {
+       'storage1' => {
-          'path' => '/mnt/gitlab/git-data'
+         'path' => '/mnt/gitlab/git-data'
-        },
+       },
-      })
+     })
-      ```
+     ```
-   1. On `gitaly2.internal`:
+   - On `gitaly2.internal`:
-      ```ruby
+     ```ruby
-      git_data_dirs({
+     git_data_dirs({
-        'storage2' => {
+       'storage2' => {
-          'path' => '/mnt/gitlab/git-data'
+         'path' => '/mnt/gitlab/git-data'
-        },
+       },
-      })
+     })
-      ```
+     ```
   <!--
   updates to following example must also be made at
   https://gitlab.com/gitlab-org/charts/gitlab/blob/master/doc/advanced/external-gitaly/external-omnibus-gitaly.md#configure-omnibus-gitlab
   -->
-1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and replace
+1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and
-   the file of the same name on this server. If that file is not on this server,
+   then replace the file of the same name on this server. If that file isn't on
-   add the file from your Consul server to this server.
+   this server, add the file from your Consul server to this server.
-1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
+1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
 ### Gitaly TLS support

--- a/doc/administration/reference_architectures/3k_users.md
+++ b/doc/administration/reference_architectures/3k_users.md
@@ -1071,51 +1071,48 @@ Refer to your preferred Load Balancer's documentation for further guidance.
 ## Configure Gitaly
-Deploying Gitaly in its own server can benefit GitLab installations that are
+[Gitaly](../gitaly/index.md) server node requirements are dependent on data,
-larger than a single machine.
+specifically the number of projects and those projects' sizes. It's recommended
+that a Gitaly server node stores no more than 5 TB of data. Although this
-The Gitaly node requirements are dependent on customer data, specifically the number of
+reference architecture includes a recommendation for the number of Gitaly server
-projects and their repository sizes. Two nodes are recommended as an absolute minimum.
+nodes to use, depending on your storage requirements, you may require additional
-Each Gitaly node should store no more than 5TB of data and have the number of
+Gitaly server nodes.
-[`gitaly-ruby` workers](../gitaly/index.md#gitaly-ruby) set to 20% of available CPUs.
-Additional nodes should be considered in conjunction with a review of expected
+Due to Gitaly having notable input and output requirements, we strongly
-data size and spread based on the recommendations above.
+recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should
+have a throughput of at least 8,000 input/output operations per second (IOPS)
-It is also strongly recommended that all Gitaly nodes be set up with SSD disks with
+for read operations and 2,000 IOPS for write operations. These IOPS values are
-a throughput of at least 8,000 IOPS for read operations and 2,000 IOPS for write,
+initial recommendations, and may be adjusted to greater or lesser values
-as Gitaly has heavy I/O. These IOPS values are recommended only as a starter as with
+depending on the scale of your environment's workload. If you're running the
-time they may be adjusted higher or lower depending on the scale of your environment's workload.
+environment on a Cloud provider, refer to their documentation about how to
-If you're running the environment on a Cloud provider, you may need to refer to
+configure IOPS correctly.
-their documentation on how to configure IOPS correctly.
+Be sure to note the following items:
-Some things to note:
+- The GitLab Rails application shards repositories into
- The GitLab Rails application shards repositories into [repository storages](../repository_storage_paths.md).
+  [repository storage paths](../repository_storage_paths.md).
- A Gitaly server can host one or more storages.
+- A Gitaly server can host one or more storage paths.
- A GitLab server can use one or more Gitaly servers.
+- A GitLab server can use one or more Gitaly server nodes.
- Gitaly addresses must be specified in such a way that they resolve
+- Gitaly addresses must be specified to be correctly resolvable for _all_
-  correctly for ALL Gitaly clients.
+  Gitaly clients.
 - Gitaly servers must not be exposed to the public internet, as Gitaly's network
  traffic is unencrypted by default. The use of a firewall is highly recommended
  to restrict access to the Gitaly server. Another option is to
  [use TLS](#gitaly-tls-support).
-TIP: **Tip:**
+NOTE: **Note:**
-For more information about Gitaly's history and network architecture see the
+The token referred to throughout the Gitaly documentation is an arbitrary
-[standalone Gitaly documentation](../gitaly/index.md).
+password selected by the administrator. This token is unrelated to tokens
+created for the GitLab API or other similar web API tokens.
-Note: **Note:** The token referred to throughout the Gitaly documentation is
-just an arbitrary password selected by the administrator. It is unrelated to
-tokens created for the GitLab API or other similar web API tokens.
-Below we describe how to configure two Gitaly servers, with IPs and
+This section describes how to configure two Gitaly servers, with the following
-domain names:
+IPs and domain names:
 - `10.6.0.51`: Gitaly 1 (`gitaly1.internal`)
 - `10.6.0.52`: Gitaly 2 (`gitaly2.internal`)
-The secret token is assumed to be `gitalysecret` and that
+Assumptions about your servers include having the secret token be `gitalysecret`,
-your GitLab installation has three repository storages:
+and that your GitLab installation has three repository storages:
 - `default` on Gitaly 1
 - `storage1` on Gitaly 1
@@ -1123,11 +1120,11 @@ your GitLab installation has three repository storages:
 On each node:
-1. [Download/Install](https://about.gitlab.com/install/) the Omnibus GitLab
+1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab
-   package you want using **steps 1 and 2** from the GitLab downloads page but
+   package you want (based on _steps 1 and 2_ on the GitLab downloads page), but
-   **without** providing the `EXTERNAL_URL` value.
+   _without_ providing the `EXTERNAL_URL` value.
-1. Edit `/etc/gitlab/gitlab.rb` to configure storage paths, enable
+1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable
-   the network listener and configure the token:
+   the network listener, and configure the token:
   <!--
   updates to following example must also be made at
@@ -1191,35 +1188,35 @@ On each node:
   ```
 1. Append the following to `/etc/gitlab/gitlab.rb` for each respective server:
-   1. On `gitaly1.internal`:
+   - On `gitaly1.internal`:
-      ```ruby
+     ```ruby
-      git_data_dirs({
+     git_data_dirs({
-        'default' => {
+       'default' => {
-          'path' => '/var/opt/gitlab/git-data'
+         'path' => '/var/opt/gitlab/git-data'
-        },
+       },
-        'storage1' => {
+       'storage1' => {
-          'path' => '/mnt/gitlab/git-data'
+         'path' => '/mnt/gitlab/git-data'
-        },
+       },
-      })
+     })
-      ```
+     ```
-   1. On `gitaly2.internal`:
+   - On `gitaly2.internal`:
-      ```ruby
+     ```ruby
-      git_data_dirs({
+     git_data_dirs({
-        'storage2' => {
+       'storage2' => {
-          'path' => '/mnt/gitlab/git-data'
+         'path' => '/mnt/gitlab/git-data'
-        },
+       },
-      })
+     })
-      ```
+     ```
   <!--
   updates to following example must also be made at
   https://gitlab.com/gitlab-org/charts/gitlab/blob/master/doc/advanced/external-gitaly/external-omnibus-gitaly.md#configure-omnibus-gitlab
   -->
-1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
+1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
 1. Confirm that Gitaly can perform callbacks to the internal API:
   ```shell

--- a/doc/administration/reference_architectures/50k_users.md
+++ b/doc/administration/reference_architectures/50k_users.md
@@ -1364,52 +1364,48 @@ To configure the Sentinel Queues server:
 ## Configure Gitaly
-Deploying Gitaly in its own server can benefit GitLab installations that are
+[Gitaly](../gitaly/index.md) server node requirements are dependent on data,
-larger than a single machine.
+specifically the number of projects and those projects' sizes. It's recommended
+that a Gitaly server node stores no more than 5 TB of data. Although this
-The Gitaly node requirements are dependent on customer data, specifically the number of
+reference architecture includes a recommendation for the number of Gitaly server
-projects and their repository sizes. Two nodes are recommended as an absolute minimum.
+nodes to use, depending on your storage requirements, you may require additional
-Each Gitaly node should store no more than 5TB of data and have the number of
+Gitaly server nodes.
-[`gitaly-ruby` workers](../gitaly/index.md#gitaly-ruby) set to 20% of available CPUs.
-Additional nodes should be considered in conjunction with a review of expected
+Due to Gitaly having notable input and output requirements, we strongly
-data size and spread based on the recommendations above.
+recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should
+have a throughput of at least 8,000 input/output operations per second (IOPS)
-It is also strongly recommended that all Gitaly nodes be set up with SSD disks with
+for read operations and 2,000 IOPS for write operations. These IOPS values are
-a throughput of at least 8,000 IOPS for read operations and 2,000 IOPS for write,
+initial recommendations, and may be adjusted to greater or lesser values
-as Gitaly has heavy I/O. These IOPS values are recommended only as a starter as with
+depending on the scale of your environment's workload. If you're running the
-time they may be adjusted higher or lower depending on the scale of your environment's workload.
+environment on a Cloud provider, refer to their documentation about how to
-If you're running the environment on a Cloud provider, you may need to refer to
+configure IOPS correctly.
-their documentation on how to configure IOPS correctly.
+Be sure to note the following items:
-Some things to note:
+- The GitLab Rails application shards repositories into
- The GitLab Rails application shards repositories into [repository storages](../repository_storage_paths.md).
+  [repository storage paths](../repository_storage_paths.md).
- A Gitaly server can host one or more storages.
+- A Gitaly server can host one or more storage paths.
- A GitLab server can use one or more Gitaly servers.
+- A GitLab server can use one or more Gitaly server nodes.
- Gitaly addresses must be specified in such a way that they resolve
+- Gitaly addresses must be specified to be correctly resolvable for _all_
-  correctly for ALL Gitaly clients.
+  Gitaly clients.
 - Gitaly servers must not be exposed to the public internet, as Gitaly's network
  traffic is unencrypted by default. The use of a firewall is highly recommended
  to restrict access to the Gitaly server. Another option is to
  [use TLS](#gitaly-tls-support).
-TIP: **Tip:**
+NOTE: **Note:**
-For more information about Gitaly's history and network architecture see the
+The token referred to throughout the Gitaly documentation is an arbitrary
-[standalone Gitaly documentation](../gitaly/index.md).
+password selected by the administrator. This token is unrelated to tokens
+created for the GitLab API or other similar web API tokens.
-Note: **Note:**
-The token referred to throughout the Gitaly documentation is
-just an arbitrary password selected by the administrator. It is unrelated to
-tokens created for the GitLab API or other similar web API tokens.
-Below we describe how to configure two Gitaly servers, with IPs and
+This section describes how to configure two Gitaly servers, with the following
-domain names:
+IPs and domain names:
 - `10.6.0.91`: Gitaly 1 (`gitaly1.internal`)
 - `10.6.0.92`: Gitaly 2 (`gitaly2.internal`)
-The secret token is assumed to be `gitalysecret` and that
+Assumptions about your servers include having the secret token be `gitalysecret`,
-your GitLab installation has three repository storages:
+and that your GitLab installation has three repository storages:
 - `default` on Gitaly 1
 - `storage1` on Gitaly 1
@@ -1417,11 +1413,11 @@ your GitLab installation has three repository storages:
 On each node:
-1. [Download/Install](https://about.gitlab.com/install/) the Omnibus GitLab
+1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab
-   package you want using **steps 1 and 2** from the GitLab downloads page but
+   package you want (based on _steps 1 and 2_ on the GitLab downloads page), but
-   **without** providing the `EXTERNAL_URL` value.
+   _without_ providing the `EXTERNAL_URL` value.
-1. Edit `/etc/gitlab/gitlab.rb` to configure storage paths, enable
+1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable
-   the network listener and configure the token:
+   the network listener, and configure the token:
   <!--
   updates to following example must also be made at
@@ -1469,39 +1465,39 @@ On each node:
   ```
 1. Append the following to `/etc/gitlab/gitlab.rb` for each respective server:
-   1. On `gitaly1.internal`:
+   - On `gitaly1.internal`:
-      ```ruby
+     ```ruby
-      git_data_dirs({
+     git_data_dirs({
-        'default' => {
+       'default' => {
-          'path' => '/var/opt/gitlab/git-data'
+         'path' => '/var/opt/gitlab/git-data'
-        },
+       },
-        'storage1' => {
+       'storage1' => {
-          'path' => '/mnt/gitlab/git-data'
+         'path' => '/mnt/gitlab/git-data'
-        },
+       },
-      })
+     })
-      ```
+     ```
-   1. On `gitaly2.internal`:
+   - On `gitaly2.internal`:
-      ```ruby
+     ```ruby
-      git_data_dirs({
+     git_data_dirs({
-        'storage2' => {
+       'storage2' => {
-          'path' => '/mnt/gitlab/git-data'
+         'path' => '/mnt/gitlab/git-data'
-        },
+       },
-      })
+     })
-      ```
+     ```
   <!--
   updates to following example must also be made at
   https://gitlab.com/gitlab-org/charts/gitlab/blob/master/doc/advanced/external-gitaly/external-omnibus-gitaly.md#configure-omnibus-gitlab
   -->
-1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and replace
+1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and
-   the file of the same name on this server. If that file is not on this server,
+   then replace the file of the same name on this server. If that file isn't on
-   add the file from your Consul server to this server.
+   this server, add the file from your Consul server to this server.
-1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
+1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
 ### Gitaly TLS support

--- a/doc/administration/reference_architectures/5k_users.md
+++ b/doc/administration/reference_architectures/5k_users.md
@@ -1070,51 +1070,48 @@ Refer to your preferred Load Balancer's documentation for further guidance.
 ## Configure Gitaly
-Deploying Gitaly in its own server can benefit GitLab installations that are
+[Gitaly](../gitaly/index.md) server node requirements are dependent on data,
-larger than a single machine.
+specifically the number of projects and those projects' sizes. It's recommended
+that a Gitaly server node stores no more than 5 TB of data. Although this
-The Gitaly node requirements are dependent on customer data, specifically the number of
+reference architecture includes a recommendation for the number of Gitaly server
-projects and their repository sizes. Two nodes are recommended as an absolute minimum.
+nodes to use, depending on your storage requirements, you may require additional
-Each Gitaly node should store no more than 5TB of data and have the number of
+Gitaly server nodes.
-[`gitaly-ruby` workers](../gitaly/index.md#gitaly-ruby) set to 20% of available CPUs.
-Additional nodes should be considered in conjunction with a review of expected
+Due to Gitaly having notable input and output requirements, we strongly
-data size and spread based on the recommendations above.
+recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should
+have a throughput of at least 8,000 input/output operations per second (IOPS)
-It is also strongly recommended that all Gitaly nodes be set up with SSD disks with
+for read operations and 2,000 IOPS for write operations. These IOPS values are
-a throughput of at least 8,000 IOPS for read operations and 2,000 IOPS for write,
+initial recommendations, and may be adjusted to greater or lesser values
-as Gitaly has heavy I/O. These IOPS values are recommended only as a starter as with
+depending on the scale of your environment's workload. If you're running the
-time they may be adjusted higher or lower depending on the scale of your environment's workload.
+environment on a Cloud provider, refer to their documentation about how to
-If you're running the environment on a Cloud provider, you may need to refer to
+configure IOPS correctly.
-their documentation on how to configure IOPS correctly.
+Be sure to note the following items:
-Some things to note:
+- The GitLab Rails application shards repositories into
- The GitLab Rails application shards repositories into [repository storages](../repository_storage_paths.md).
+  [repository storage paths](../repository_storage_paths.md).
- A Gitaly server can host one or more storages.
+- A Gitaly server can host one or more storage paths.
- A GitLab server can use one or more Gitaly servers.
+- A GitLab server can use one or more Gitaly server nodes.
- Gitaly addresses must be specified in such a way that they resolve
+- Gitaly addresses must be specified to be correctly resolvable for _all_
-  correctly for ALL Gitaly clients.
+  Gitaly clients.
 - Gitaly servers must not be exposed to the public internet, as Gitaly's network
  traffic is unencrypted by default. The use of a firewall is highly recommended
  to restrict access to the Gitaly server. Another option is to
  [use TLS](#gitaly-tls-support).
-TIP: **Tip:**
+NOTE: **Note:**
-For more information about Gitaly's history and network architecture see the
+The token referred to throughout the Gitaly documentation is an arbitrary
-[standalone Gitaly documentation](../gitaly/index.md).
+password selected by the administrator. This token is unrelated to tokens
+created for the GitLab API or other similar web API tokens.
-Note: **Note:** The token referred to throughout the Gitaly documentation is
-just an arbitrary password selected by the administrator. It is unrelated to
-tokens created for the GitLab API or other similar web API tokens.
-Below we describe how to configure two Gitaly servers, with IPs and
+This section describes how to configure two Gitaly servers, with the following
-domain names:
+IPs and domain names:
 - `10.6.0.51`: Gitaly 1 (`gitaly1.internal`)
 - `10.6.0.52`: Gitaly 2 (`gitaly2.internal`)
-The secret token is assumed to be `gitalysecret` and that
+Assumptions about your servers include having the secret token be `gitalysecret`,
-your GitLab installation has three repository storages:
+and that your GitLab installation has three repository storages:
 - `default` on Gitaly 1
 - `storage1` on Gitaly 1
@@ -1122,11 +1119,11 @@ your GitLab installation has three repository storages:
 On each node:
-1. [Download/Install](https://about.gitlab.com/install/) the Omnibus GitLab
+1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab
-   package you want using **steps 1 and 2** from the GitLab downloads page but
+   package you want (based on _steps 1 and 2_ on the GitLab downloads page), but
-   **without** providing the `EXTERNAL_URL` value.
+   _without_ providing the `EXTERNAL_URL` value.
-1. Edit `/etc/gitlab/gitlab.rb` to configure storage paths, enable
+1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable
-   the network listener and configure the token:
+   the network listener, and configure the token:
   <!--
   updates to following example must also be made at
@@ -1190,35 +1187,35 @@ On each node:
   ```
 1. Append the following to `/etc/gitlab/gitlab.rb` for each respective server:
-   1. On `gitaly1.internal`:
+   - On `gitaly1.internal`:
-      ```ruby
+     ```ruby
-      git_data_dirs({
+     git_data_dirs({
-        'default' => {
+       'default' => {
-          'path' => '/var/opt/gitlab/git-data'
+         'path' => '/var/opt/gitlab/git-data'
-        },
+       },
-        'storage1' => {
+       'storage1' => {
-          'path' => '/mnt/gitlab/git-data'
+         'path' => '/mnt/gitlab/git-data'
-        },
+       },
-      })
+     })
-      ```
+     ```
-   1. On `gitaly2.internal`:
+   - On `gitaly2.internal`:
-      ```ruby
+     ```ruby
-      git_data_dirs({
+     git_data_dirs({
-        'storage2' => {
+       'storage2' => {
-          'path' => '/mnt/gitlab/git-data'
+         'path' => '/mnt/gitlab/git-data'
-        },
+       },
-      })
+     })
-      ```
+     ```
   <!--
   updates to following example must also be made at
   https://gitlab.com/gitlab-org/charts/gitlab/blob/master/doc/advanced/external-gitaly/external-omnibus-gitaly.md#configure-omnibus-gitlab
   -->
-1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
+1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
 1. Confirm that Gitaly can perform callbacks to the internal API:
   ```shell