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

Update Gitaly section for refinement

See merge request gitlab-org/gitlab!40875

doc/administration/reference_architectures/2k_users.md

@@ -348,50 +348,51 @@ are supported and can be added if needed.
 
 ## Configure Gitaly
 
-Deploying Gitaly in its own server can benefit GitLab installations that are
-larger than a single machine. Gitaly node requirements are dependent on data,
-specifically the number of projects and their sizes. It's recommended that each
-Gitaly node store no more than 5TB of data. Your 2K setup may require one or more
-nodes depending on your repository storage requirements.
-
-We strongly recommend that all Gitaly nodes should be set up with SSD disks with a throughput of at least
-8,000 IOPS for read operations and 2,000 IOPS for write, as Gitaly has heavy I/O.
-These IOPS values are recommended only as a starter as with time they may be
-adjusted higher or lower depending on the scale of your environment's workload.
-If you're running the environment on a Cloud provider
-you may need to refer to their documentation on how configure IOPS correctly.
-
-Some things to note:
-
-- The GitLab Rails application shards repositories into [repository storages](../repository_storage_paths.md).
-- A Gitaly server can host one or more storages.
-- A GitLab server can use one or more Gitaly servers.
-- Gitaly addresses must be specified in such a way that they resolve
-  correctly for ALL Gitaly clients.
+[Gitaly](../gitaly/index.md) server node requirements are dependent on data,
+specifically the number of projects and those projects' sizes. It's recommended
+that a Gitaly server node stores no more than 5TB of data. Although this
+reference architecture includes a single Gitaly server node, you may require
+additional nodes depending on your repository storage requirements.
+
+Due to Gitaly having notable input and output requirements, we strongly
+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) for read operations and 2,000 IOPS
+for write operations. These IOPS values are initial recommendations, and may be
+adjusted to greater or lesser values depending on the scale of your
+environment's workload. If you're running the environment on a Cloud provider,
+refer to their documentation about how to configure IOPS correctly.
+
+Be sure to note the following items:
+
+- The GitLab Rails application shards repositories into
+  [repository storage paths](../repository_storage_paths.md).
+- A Gitaly server can host one or more storage paths.
+- A GitLab server can use one or more Gitaly server nodes.
+- Gitaly addresses must be specified to be correctly resolvable for *all*
+  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:**
-For more information about Gitaly's history and network architecture see the
-[standalone Gitaly documentation](../gitaly/index.md).
-
-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.
+NOTE: **Note:**
+The token referred to throughout the Gitaly documentation is an arbitrary
+password selected by the administrator. This token is unrelated to tokens
+created for the GitLab API or other similar web API tokens.
 
-Below we describe how to configure one Gitaly server `gitaly1.internal` with
-secret token `gitalysecret`. We assume your GitLab installation has two
-repository storages: `default` and `storage1`.
+The following procedure describes how to configure a single Gitaly server named
+`gitaly1.internal` with the secret token `gitalysecret`. We assume your GitLab
+installation has two repository storages: `default` and `storage1`.
 
 To configure the Gitaly server:
 
-1. [Download/Install](https://about.gitlab.com/install/) the Omnibus GitLab
-   package you want using **steps 1 and 2** from the GitLab downloads page but
-   **without** providing the `EXTERNAL_URL` value.
-1. Edit `/etc/gitlab/gitlab.rb` to configure storage paths, enable
-   the network listener and configure the token:
+1. On the server node you want to use for Gitaly,
+   [download and install](https://about.gitlab.com/install/) your selected
+   Omnibus GitLab package using *steps 1 and 2* from the GitLab downloads page,
+   but *without* providing the `EXTERNAL_URL` value.
+1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure
+   storage paths, enable the network listener, and to configure the token:
 
    <!--
    updates to following example must also be made at
@@ -440,11 +441,7 @@ To configure the Gitaly server:
 
    # Set the network addresses that the exporters used for monitoring will listen on
    node_exporter['listen_address'] = '0.0.0.0:9100'
-   ```
 
-1. Append the following to `/etc/gitlab/gitlab.rb` on `gitaly1.internal`:
-
-   ```ruby
    git_data_dirs({
      'default' => {
        'path' => '/var/opt/gitlab/git-data'
@@ -455,12 +452,7 @@ To configure the Gitaly server:
    })
    ```
 
-   <!--
-   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