Merge branch 'eread/clean-up-repository-storage-paths-documentation' into 'master'

Clean up repository storage paths documentation

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130010



Merged-by: Marcin Sedlak-Jakubowski <msedlakjakubowski@gitlab.com>
Approved-by: John Cai <jcai@gitlab.com>
Approved-by: Marcin Sedlak-Jakubowski <msedlakjakubowski@gitlab.com>
Reviewed-by: John Cai <jcai@gitlab.com>
Co-authored-by: Evan Read <eread@gitlab.com>

doc/administration/repository_storage_paths.md

@@ -9,142 +9,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 GitLab stores [repositories](../user/project/repository/index.md) on repository storage. Repository
 storage is either:
 
-- A `gitaly_address`, which points to a [Gitaly node](gitaly/index.md).
-- A `path`, which points directly to the directory where the repositories are stored. GitLab
-  directly accessing a directory containing repositories
-  [is deprecated](https://gitlab.com/gitlab-org/gitaly/-/issues/1690).
-  GitLab should be configured to access GitLab repositories through a `gitaly_address`.
-
-GitLab allows you to define multiple repository storages to distribute the storage load between
-several mount points. For example:
-
-- When using Gitaly (Linux package installation-style configuration):
-
-  ```ruby
-   git_data_dirs({
-     'default' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' },
-     'storage2' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075' },
-   })
-   ```
-
-- When using direct repository storage (self-compiled installation-style configuration):
-
-  ```plaintext
-  default:
-    gitaly_address: tcp://gitaly1.example:8075
-  storage2:
-    gitaly_address: tcp://gitaly2.example:8075
-  ```
-
-For more information on:
-
-- Configuring Gitaly, see [Configure Gitaly](gitaly/index.md#configure-gitaly).
-- Configuring direct repository access, see the following section below.
-
-## Configure repository storage paths
+- Physical storage configured with a `gitaly_address` that points to a [Gitaly node](gitaly/index.md).
+- [Virtual storage](gitaly/index.md#virtual-storage) that stores repositories on a Gitaly Cluster.
 
 WARNING:
-The following information is for configuring GitLab to directly access repositories. This
-configuration option is deprecated in favor of using [Gitaly](gitaly/index.md).
-[Issue 403318](https://gitlab.com/gitlab-org/gitlab/-/issues/403318) proposes to remove this configuration option.
-
-To configure repository storage paths:
-
-1. Edit the necessary configuration files:
-   - `/etc/gitlab/gitlab.rb`, for Linux package installations.
-   - `gitlab.yml`, for self-compiled installations.
-1. Add the required repository storage paths.
-
-For repository storage paths:
-
-- You must have at least one storage path called `default`.
-- The paths are defined in key-value pairs. Apart from `default`, the key can be any name you choose
-  to name the file path.
-- The target directories and any of its sub paths must not be a symlink.
-- No target directory may be a sub-directory of another. That is, no nesting. For example, the
-  following configuration is invalid:
-
-  ```plaintext
-  default:
-    path: /mnt/git-storage-1
-  storage2:
-    path: /mnt/git-storage-1/git-storage-2 # <- NOT OK because of nesting
-  ```
-
-### Configure for backups
-
-For [backups](../administration/backup_restore/index.md) to work correctly:
-
-- The repository storage path cannot be a mount point.
-- The GitLab user must have correct permissions for the parent directory of the path.
-
-The Linux package takes care of these issues for you but for self-compiled installations, you should be extra
-careful.
+Repository storage could be configured as a `path` that points directly to the directory where the repositories are
+stored. GitLab directly accessing a directory containing repositories is deprecated. You should configure GitLab to
+access repositories through a physical or virtual storage.
 
-While restoring a backup, the current contents of `/home/git/repositories` are moved to
-`/home/git/repositories.old`. If `/home/git/repositories` is a mount point, then `mv` would be
-moving things between mount points, and problems can occur.
-
-Ideally, `/home/git` is the mount point, so things remain inside the same mount point. Linux package
-installations guarantee this because they don't specify the full repository path but instead
-the parent path, but self-compiled installations do not.
-
-### Example configuration
-
-In the examples below, we add two additional repository storage paths configured to two additional
-mount points.
-
-For compatibility reasons `gitlab.yml` has a different structure than Linux package installation configuration:
-
-- In `gitlab.yml`, you indicate the path for the repositories. For example, `/home/git/repositories`.
-- In Linux package installation configuration, you indicate `git_data_dirs`, which could be `/home/git` for
-  example. The Linux package installation then creates a `repositories` directory under that path to use with
-  `gitlab.yml`.
-
-For self-compiled installations:
-
-1. Edit `gitlab.yml` and add the storage paths:
-
-   ```yaml
-   repositories:
-     # Paths where repositories can be stored. Give the canonicalized absolute pathname.
-     # NOTE: REPOS PATHS MUST NOT CONTAIN ANY SYMLINK!!!
-     storages: # You must have at least a 'default' repository storage path.
-       default:
-         path: /home/git/repositories
-       storage1:
-         path: /mnt/storage1/repositories
-       storage2:
-         path: /mnt/storage2/repositories
-   ```
-
-1. [Restart GitLab](restart_gitlab.md#self-compiled-installations) for the changes to take effect.
-
-1. [Configure where new repositories are stored](#configure-where-new-repositories-are-stored).
-
-For Linux package installations:
-
-1. Edit `/etc/gitlab/gitlab.rb` by appending the rest of the paths to the default one:
-
-   ```ruby
-   git_data_dirs({
-    "default" => { "path" => "/var/opt/gitlab/git-data" },
-    "storage1" => { "path" => "/mnt/storage1/git-data" },
-    "storage2" => { "path" => "/mnt/storage2/git-data" }
-   })
-   ```
-
-1. [Restart GitLab](restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect.
-
-1. [Configure where new repositories are stored](#configure-where-new-repositories-are-stored).
+For more information on:
 
-NOTE:
-Linux package installations store the repositories in a `repositories` subdirectory of the `git-data` directory.
+- Configuring Gitaly, see [Configure Gitaly](gitaly/configure_gitaly.md).
+- Configuring Gitaly Cluster, see [Configure Gitaly Cluster](gitaly/praefect.md).
 
 ## Configure where new repositories are stored
 
-After you [configure](#configure-repository-storage-paths) multiple repository storage paths, you
-can choose where new repositories are stored:
+After you configure multiple repository storages, you can choose where new repositories are stored:
 
 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**).
 1. Select **Admin Area**.
@@ -157,8 +37,7 @@ Each repository storage path can be assigned a weight from 0-100. When a new pro
 these weights are used to determine the storage location the repository is created on.
 
 The higher the weight of a given repository storage path relative to other repository storages
-paths, the more often it is chosen. That is,
-`(storage weight) / (sum of all weights) * 100 = chance %`.
+paths, the more often it is chosen (`(storage weight) / (sum of all weights) * 100 = chance %`).
 
 By default, if repository weights have not been configured earlier: