Merge branch 'docs-aqualls-create-issues2' into 'master'

Word and line edits for Configure docs, part 2

See merge request gitlab-org/gitlab!52732

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

@@ -411,6 +411,7 @@ reauthenticate
 reauthenticated
 reauthenticates
 reauthenticating
+rebalancing
 rebar
 rebase
 rebased
@@ -482,6 +483,7 @@ serializer
 serializers
 serializing
 serverless
+sharded
 sharding
 shfmt
 Shibboleth

doc/administration/git_protocol.md

@@ -29,11 +29,11 @@ server to accept the `GIT_PROTOCOL` environment.
 
 In installations using [GitLab Helm Charts](https://docs.gitlab.com/charts/)
 and [All-in-one Docker image](https://docs.gitlab.com/omnibus/docker/), the SSH
-service is already configured to accept the `GIT_PROTOCOL` environment and users
+service is already configured to accept the `GIT_PROTOCOL` environment. Users
 need not do anything more.
 
-For Omnibus GitLab and installations from source, you have to manually update
-the SSH configuration of your server by adding the line below to the `/etc/ssh/sshd_config` file:
+For Omnibus GitLab and installations from source, update
+the SSH configuration of your server manually by adding this line to the `/etc/ssh/sshd_config` file:
 
 ```plaintext
 AcceptEnv GIT_PROTOCOL

doc/administration/gitaly/index.md

@@ -40,7 +40,7 @@ The following is a high-level architecture overview of how Gitaly is used.
 
 ## Configure Gitaly
 
-The Gitaly service itself is configured via a [TOML configuration file](reference.md).
+The Gitaly service itself is configured by using a [TOML configuration file](reference.md).
 
 To change Gitaly settings:
 
@@ -121,7 +121,7 @@ The following list depicts the network architecture of Gitaly:
   - GitLab Shell.
   - Elasticsearch indexer.
   - Gitaly itself.
-- A Gitaly server must be able to make RPC calls **to itself** via its own
+- A Gitaly server must be able to make RPC calls **to itself** by uing its own
   `(Gitaly address, Gitaly token)` pair as specified in `/config/gitlab.yml`.
 - Authentication is done through a static token which is shared among the Gitaly and GitLab Rails
   nodes.
@@ -502,8 +502,8 @@ If it's excluded, default Git storage directory is used for that storage shard.
 
 ### Disable Gitaly where not required (optional)
 
-If you are running Gitaly [as a remote service](#run-gitaly-on-its-own-server), you may want to
-disable the local Gitaly service that runs on your GitLab server by default and have it only running
+If you run Gitaly [as a remote service](#run-gitaly-on-its-own-server), consider
+disabling the local Gitaly service that runs on your GitLab server by default, and only run it
 where required.
 
 Disabling Gitaly on the GitLab instance only makes sense when you run GitLab in a custom cluster configuration, where
@@ -538,7 +538,7 @@ To disable Gitaly on a GitLab server:
 > - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/3160) in GitLab 13.6, outgoing TLS connections to GitLab provide client certificates if configured.
 
 Gitaly supports TLS encryption. To communicate with a Gitaly instance that listens for secure
-connections, you must use `tls://` URL scheme in the `gitaly_address` of the corresponding
+connections, use the `tls://` URL scheme in the `gitaly_address` of the corresponding
 storage entry in the GitLab configuration.
 
 Gitaly provides the same server certificates as client certificates in TLS
@@ -935,12 +935,13 @@ Note that `enforced="true"` means that authentication is being enforced.
 
 ## Direct Git access bypassing Gitaly
 
-While it is possible to access Gitaly repositories stored on disk directly with a Git client,
-it is not advisable because Gitaly is being continuously improved and changed. Theses improvements may invalidate assumptions, resulting in performance degradation, instability, and even data loss.
+GitLab doesn't advise directly accessing Gitaly repositories stored on disk with
+a Git client, because Gitaly is being continuously improved and changed. These
+improvements may invalidate assumptions, resulting in performance degradation, instability, and even data loss.
 
 Gitaly has optimizations, such as the
 [`info/refs` advertisement cache](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/design_diskcache.md),
-that rely on Gitaly controlling and monitoring access to repositories via the
+that rely on Gitaly controlling and monitoring access to repositories by using the
 official gRPC interface. Likewise, Praefect has optimizations, such as fault
 tolerance and distributed reads, that depend on the gRPC interface and
 database to determine repository state.
@@ -979,11 +980,11 @@ lookup. Even when Gitaly is able to re-use an already-running `git` process (for
 a commit), you still have:
 
 - The cost of a network roundtrip to Gitaly.
-- Within Gitaly, a write/read roundtrip on the Unix pipes that connect Gitaly to the `git` process.
+- Inside Gitaly, a write/read roundtrip on the Unix pipes that connect Gitaly to the `git` process.
 
 Using GitLab.com to measure, we reduced the number of Gitaly calls per request until the loss of
 Rugged's efficiency was no longer felt. It also helped that we run Gitaly itself directly on the Git
-file severs, rather than via NFS mounts. This gave us a speed boost that counteracted the negative
+file severs, rather than by using NFS mounts. This gave us a speed boost that counteracted the negative
 effect of not using Rugged anymore.
 
 Unfortunately, other deployments of GitLab could not remove NFS like we did on GitLab.com, and they
@@ -1018,7 +1019,7 @@ The result of these checks is cached.
 To see if GitLab can access the repository file system directly, we use the following heuristic:
 
 - Gitaly ensures that the file system has a metadata file in its root with a UUID in it.
-- Gitaly reports this UUID to GitLab via the `ServerInfo` RPC.
+- Gitaly reports this UUID to GitLab by using the `ServerInfo` RPC.
 - GitLab Rails tries to read the metadata file directly. If it exists, and if the UUID's match,
   assume we have direct access.
 
@@ -1085,7 +1086,7 @@ app nodes).
 ### Client side gRPC logs
 
 Gitaly uses the [gRPC](https://grpc.io/) RPC framework. The Ruby gRPC
-client has its own log file which may contain useful information when
+client has its own log file which may contain debugging information when
 you are seeing Gitaly errors. You can control the log level of the
 gRPC client with the `GRPC_LOG_LEVEL` environment variable. The
 default level is `WARN`.
@@ -1100,7 +1101,7 @@ sudo GRPC_TRACE=all GRPC_VERBOSITY=DEBUG gitlab-rake gitlab:gitaly:check
 
 Sometimes you need to find out which Gitaly RPC created a particular Git process.
 
-One method for doing this is via `DEBUG` logging. However, this needs to be enabled
+One method for doing this is by using `DEBUG` logging. However, this needs to be enabled
 ahead of time and the logs produced are quite verbose.
 
 A lightweight method for doing this correlation is by inspecting the environment
@@ -1137,16 +1138,19 @@ sum(rate(grpc_client_handled_total[5m])) by (grpc_method) > 0
 
 ### Repository changes fail with a `401 Unauthorized` error
 
-If you're running Gitaly on its own server and notice that users can
-successfully clone and fetch repositories (via both SSH and HTTPS), but can't
-push to them or make changes to the repository in the web UI without getting a
-`401 Unauthorized` message, then it's possible Gitaly is failing to authenticate
-with the Gitaly client due to having the [wrong secrets file](#configure-gitaly-servers).
+If you run Gitaly on its own server and notice these conditions:
+
+- Users can successfully clone and fetch repositories by using both SSH and HTTPS.
+- Users can't push to repositories, or receive a `401 Unauthorized` message when attempting to
+  make changes to them in the web UI.
+
+Gitaly may be failing to authenticate with the Gitaly client because it has the
+[wrong secrets file](#configure-gitaly-servers).
 
 Confirm the following are all true:
 
 - When any user performs a `git push` to any repository on this Gitaly server, it
-  fails with the following error (note the `401 Unauthorized`):
+  fails with a `401 Unauthorized` error:
 
   ```shell
   remote: GitLab: 401 Unauthorized
@@ -1158,7 +1162,7 @@ Confirm the following are all true:
 - When any user adds or modifies a file from the repository using the GitLab
   UI, it immediately fails with a red `401 Unauthorized` banner.
 - Creating a new project and [initializing it with a README](../../gitlab-basics/create-project.md#blank-projects)
-  successfully creates the project but doesn't create the README.
+  successfully creates the project, but doesn't create the README.
 - When [tailing the logs](https://docs.gitlab.com/omnibus/settings/logs.html#tail-logs-in-a-console-on-the-server)
   on a Gitaly client and reproducing the error, you get `401` errors
   when reaching the `/api/v4/internal/allowed` endpoint:
@@ -1229,11 +1233,11 @@ update the secrets file on the Gitaly server to match the Gitaly client, then
 
 ### Command line tools cannot connect to Gitaly
 
-If you are having trouble connecting to a Gitaly server with command line (CLI) tools,
+If you can't connect to a Gitaly server with command line (CLI) tools,
 and certain actions result in a `14: Connect Failed` error message,
-it means that gRPC cannot reach your Gitaly server.
+gRPC cannot reach your Gitaly server.
 
-Verify that you can reach Gitaly via TCP:
+Verify you can reach Gitaly by using TCP:
 
 ```shell
 sudo gitlab-rake gitlab:tcp_check[GITALY_SERVER_IP,GITALY_LISTEN_PORT]

doc/administration/gitaly/praefect.md

@@ -105,7 +105,7 @@ sharding is:
   replicas.
 - Simpler management, because all Gitaly nodes are identical.
 
-Under some workloads, CPU and memory requirements may require a large fleet of Gitaly nodes and it
+Under some workloads, CPU and memory requirements may require a large fleet of Gitaly nodes. It
 can be uneconomical to have one to one replication factor.
 
 A hybrid approach can be used in these instances, where each shard is configured as a smaller
@@ -168,7 +168,7 @@ If you are using Google Cloud Platform, SoftLayer, or any other vendor that prov
 
 The communication between components is secured with different secrets, which
 are described below. Before you begin, generate a unique secret for each, and
-make note of it. This makes it easy to replace these placeholder tokens
+make note of it. This enables you to replace these placeholder tokens
 with secure tokens as you complete the setup process.
 
 1. `GITLAB_SHELL_SECRET_TOKEN`: this is used by Git hooks to make callback HTTP
@@ -260,13 +260,12 @@ this, set the corresponding IP or host address of the PgBouncer instance in
 - `praefect['database_port']`, for the port.
 
 Because PgBouncer manages resources more efficiently, Praefect still requires a
-direct connection to the PostgreSQL database because it uses
+direct connection to the PostgreSQL database. It uses the
 [LISTEN](https://www.postgresql.org/docs/11/sql-listen.html)
-functionality that is [not supported](https://www.pgbouncer.org/features.html) by
+feature that is [not supported](https://www.pgbouncer.org/features.html) by
 PgBouncer with `pool_mode = transaction`.
-
-Therefore, `praefect['database_host_no_proxy']` and `praefect['database_port_no_proxy']`
-should be set to a direct connection and not a PgBouncer connection.
+Set `praefect['database_host_no_proxy']` and `praefect['database_port_no_proxy']`
+to a direct connection, and not a PgBouncer connection.
 
 Save the changes to `/etc/gitlab/gitlab.rb` and
 [reconfigure Praefect](../restart_gitlab.md#omnibus-gitlab-reconfigure).
@@ -960,14 +959,14 @@ To get started quickly:
    gitlab-ctl reconfigure
    ```
 
-1. Set the Grafana admin password. This command prompts you to enter a new
+1. Set the Grafana administrator password. This command prompts you to enter a new
    password:
 
    ```shell
    gitlab-ctl set-grafana-password
    ```
 
-1. In your web browser, open `/-/grafana` (e.g.
+1. In your web browser, open `/-/grafana` (such as
    `https://gitlab.example.com/-/grafana`) on your GitLab server.
 
    Login using the password you set, and the username `admin`.
@@ -1085,7 +1084,7 @@ specific storage nodes to host a repository.
 support configuring a default replication factor for a virtual storage. The default replication factor
 is applied to every newly-created repository.
 
-Prafect does not store the actual replication factor, but assigns enough storages to host the repository
+Praefect does not store the actual replication factor, but assigns enough storages to host the repository
 so the desired replication factor is met. If a storage node is later removed from the virtual storage,
 the replication factor of repositories assigned to the storage is decreased accordingly.
 
@@ -1164,8 +1163,8 @@ To enable writes again, an administrator can:
 
 ### Check for data loss
 
-The Praefect `dataloss` sub-command identifies replicas that are likely to be outdated. This is
-useful for identifying potential data loss after a failover. The following parameters are
+The Praefect `dataloss` sub-command identifies replicas that are likely to be outdated. This can help
+identify potential data loss after a failover. The following parameters are
 available:
 
 - `-virtual-storage` that specifies which virtual storage to check. The default behavior is to
@@ -1189,7 +1188,7 @@ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.t
 ```
 
 Repositories which have assigned storage nodes that contain an outdated copy of the repository are listed
-in the output. A number of useful information is printed for each repository:
+in the output. This information is printed for each repository:
 
 - A repository's relative path to the storage directory identifies each repository and groups the related
   information.
@@ -1206,7 +1205,7 @@ in the output. A number of useful information is printed for each repository:
 
 Whether a replica is assigned to host the repository is listed with each replica's status. `assigned host` is printed
 next to replicas which are assigned to store the repository. The text is omitted if the replica contains a copy of
-the repository but is not assigned to store the repository. Such replicas won't be kept in-sync by Praefect but may
+the repository but is not assigned to store the repository. Such replicas aren't kept in-sync by Praefect, but may
 act as replication sources to bring assigned replicas up to date.
 
 Example output:
@@ -1275,7 +1274,7 @@ To check a project's repository checksums across on all Gitaly nodes, run the
 
 ### Enable writes or accept data loss
 
-Praefect provides the following subcommands to re-enable writes:
+Praefect provides the following sub-commands to re-enable writes:
 
 - In GitLab 13.2 and earlier, `enable-writes` to re-enable virtual storage for writes after data
   recovery attempts.
@@ -1317,7 +1316,7 @@ These tools reconcile the outdated repositories to bring them fully up to date a
 
 Praefect automatically reconciles repositories that are not up to date. By default, this is done every
 five minutes. For each outdated repository on a healthy Gitaly node, the Praefect picks a
-random, fully up to date replica of the repository on another healthy Gitaly node to replicate from. A
+random, fully up-to-date replica of the repository on another healthy Gitaly node to replicate from. A
 replication job is scheduled only if there are no other replication jobs pending for the target
 repository.
 
@@ -1376,7 +1375,7 @@ To move repositories to Gitaly Cluster:
    - The moves are in progress. Re-query the repository move until it completes successfully.
    - The moves have failed. Most failures are temporary and are solved by rescheduling the move.
 
-1. Once the moves are complete, [query projects](../../api/projects.md#list-all-projects)
+1. After the moves are complete, [query projects](../../api/projects.md#list-all-projects)
    using the API to confirm that all projects have moved. No projects should be returned
    with `repository_storage` field set to the old storage.
 

doc/administration/gitaly/reference.md

@@ -95,13 +95,13 @@ key_path = '/home/git/key.pem'
 
 ### Storage
 
-GitLab repositories are grouped into directories known as "storages"
-(e.g., `/home/git/repositories`) containing bare repositories managed
-by GitLab with names (e.g., `default`).
+GitLab repositories are grouped into directories known as storages, such as
+`/home/git/repositories`. They contain bare repositories managed
+by GitLab with names, such as `default`.
 
 These names and paths are also defined in the `gitlab.yml` configuration file of
-GitLab. When you run Gitaly on the same machine as GitLab, which is the default
-and recommended configuration, storage paths defined in Gitaly's `config.toml`
+GitLab. When you run Gitaly on the same machine as GitLab (the default
+and recommended configuration) storage paths defined in Gitaly's `config.toml`
 must match those in `gitlab.yml`.
 
 | Name | Type | Required | Description |
@@ -232,9 +232,9 @@ The following values configure logging in Gitaly under the `[logging]` section.
 | ---- | ---- | -------- | ----------- |
 | `format` | string | no | Log format: `text` or `json`. Default: `text`. |
 | `level`  | string | no | Log level: `debug`, `info`, `warn`, `error`, `fatal`, or `panic`. Default: `info`. |
-| `sentry_dsn` | string | no | Sentry DSN for exception monitoring. |
+| `sentry_dsn` | string | no | Sentry DSN (Data Source Name) for exception monitoring. |
 | `sentry_environment` | string | no | [Sentry Environment](https://docs.sentry.io/product/sentry-basics/environments/) for exception monitoring. |
-| `ruby_sentry_dsn` | string | no | Sentry DSN for `gitaly-ruby` exception monitoring. |
+| `ruby_sentry_dsn` | string | no | Sentry DSN (Data Source Name) for `gitaly-ruby` exception monitoring. |
 
 While the main Gitaly application logs go to `stdout`, there are some extra log
 files that go to a configured directory, like the GitLab Shell logs.

doc/administration/invalidate_markdown_cache.md

@@ -8,10 +8,10 @@ type: reference
 # Invalidate Markdown Cache
 
 For performance reasons, GitLab caches the HTML version of Markdown text
-(e.g. issue and merge request descriptions, comments). It's possible
-that these cached versions become outdated, for example
-when the `external_url` configuration option is changed - causing links
-in the cached text to refer to the old URL.
+in fields like comments, issue descriptions, and merge request descriptions. These
+cached versions can become outdated, such as
+when the `external_url` configuration option is changed. Links
+in the cached text would still refer to the old URL.
 
 To avoid this problem, the administrator can invalidate the existing cache by
 increasing the `local_markdown_version` setting in application settings. This can

doc/administration/repository_storage_paths.md

@@ -40,9 +40,9 @@ storage2:
 
 ## Configure GitLab
 
-In order for [backups](../raketasks/backup_restore.md) to work correctly, the storage path must **not** be a
-mount point and the GitLab user should have correct permissions for the parent
-directory of the path. In Omnibus GitLab this is taken care of automatically,
+For [backups](../raketasks/backup_restore.md) to work correctly, the storage path cannot be a
+mount point, and the GitLab user must have correct permissions for the parent
+directory of the path. Omnibus GitLab takes care of these issues for you,
 but for source installations you should be extra careful.
 
 The thing is that for compatibility reasons `gitlab.yml` has a different
@@ -52,22 +52,26 @@ indicate `git_data_dirs`, which for the example above would be `/home/git`.
 Then, Omnibus creates a `repositories` directory under that path to use with
 `gitlab.yml`.
 
-This little detail matters because while restoring a backup, the current
-contents of `/home/git/repositories` [are moved to](https://gitlab.com/gitlab-org/gitlab/blob/033e5423a2594e08a7ebcd2379bd2331f4c39032/lib/backup/repository.rb#L54-56) `/home/git/repositories.old`,
-so if `/home/git/repositories` is the mount point, then `mv` would be moving
+WARNING:
+This detail matters because while restoring a backup, the current
+contents of `/home/git/repositories`
+[are moved to](https://gitlab.com/gitlab-org/gitlab/blob/033e5423a2594e08a7ebcd2379bd2331f4c39032/lib/backup/repository.rb#L54-56)
+`/home/git/repositories.old`.
+If `/home/git/repositories` is the mount point, then `mv` would be moving
 things between mount points, and bad things could happen. Ideally,
-`/home/git` would be the mount point, so then things would be moving within the
-same mount point. This is guaranteed with Omnibus installations (because they
-don't specify the full repository path but the parent path), but not for source
-installations.
+`/home/git` would be the mount point, so things would remain inside the
+same mount point. Omnibus installations guarantee this, because they
+don't specify the full repository path but instead the parent path, but source
+installations do not.
 
-Now that you've read that big fat warning above, let's edit the configuration
-files and add the full paths of the alternative repository storage paths. In
+Next, edit the configuration
+files, and add the full paths of the alternative repository storage paths. In
 the example below, we add two more mount points that are named `nfs_1` and `nfs_2`
 respectively.
 
 NOTE:
-This example uses NFS. We do not recommend using EFS for storage as it may impact GitLab performance. See the [relevant documentation](nfs.md#avoid-using-awss-elastic-file-system-efs) for more details.
+This example uses NFS. We do not recommend using EFS for storage as it may impact GitLab performance. Read
+the [relevant documentation](nfs.md#avoid-using-awss-elastic-file-system-efs) for more details.
 
 **For installations from source**
 
@@ -112,7 +116,7 @@ working, you can remove the `repos_path` line.
 
 ## Choose where new repositories are stored
 
-Once you set the multiple storage paths, you can choose where new repositories
+After you set the multiple storage paths, you can choose where new repositories
 are stored in the Admin Area under **Settings > Repository > Repository storage > Storage nodes for new repositories**.
 
 Each storage can be assigned a weight from 0-100. When a new project is created, these

doc/administration/snippets/index.md

@@ -18,7 +18,7 @@ abuse of the feature. The default value is **52428800 Bytes** (50 MB).
 
 ### How does it work?
 
-The content size limit will be applied when a snippet is created or updated.
+The content size limit is applied when a snippet is created or updated.
 
 This limit doesn't affect existing snippets until they're updated and their
 content changes.
@@ -60,8 +60,8 @@ To retrieve the current value, start the Rails console and run:
 
 #### Through the API
 
-The process to set the snippets size limit through the Application Settings API is
-exactly the same as you would do to [update any other setting](../../api/settings.md#change-application-settings).
+To set the snippets size limit through the Application Settings API (similar to
+[updating any other setting](../../api/settings.md#change-application-settings)), use this command:
 
 ```shell
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/settings?snippet_size_limit=52428800"