Merge branch 'eread/move-repository-move-documentation' into 'master'

Repository move information moved into a generic section

See merge request gitlab-org/gitlab!68119

doc/administration/gitaly/faq.md

@@ -35,7 +35,7 @@ For more information, see:
 
 ## Are there instructions for migrating to Gitaly Cluster?
 
-Yes! For more information, see [Migrate to Gitaly Cluster](praefect.md#migrate-to-gitaly-cluster).
+Yes! For more information, see [Migrate to Gitaly Cluster](index.md#migrate-to-gitaly-cluster).
 
 ## What are some repository storage recommendations?
 

doc/administration/gitaly/index.md

@@ -306,6 +306,18 @@ For configuration information, see [Configure replication factor](praefect.md#co
 
 For more information on configuring Gitaly Cluster, see [Configure Gitaly Cluster](praefect.md).
 
+### Migrate to Gitaly Cluster
+
+Whether migrating to Gitaly Cluster because of [NFS support deprecation](index.md#nfs-deprecation-notice)
+or to move from single Gitaly nodes, the basic process involves:
+
+1. Create the required storage. Refer to
+   [repository storage recommendations](faq.md#what-are-some-repository-storage-recommendations).
+1. Create and configure [Gitaly Cluster](praefect.md).
+1. [Move the repositories](../operations/moving_repositories.md#move-repositories). To migrate to
+   Gitaly Cluster, existing repositories stored outside Gitaly Cluster must be moved. There is no
+   automatic migration but the moves can be scheduled with the GitLab API.
+
 ## Monitor Gitaly and Gitaly Cluster
 
 You can use the available logs and [Prometheus metrics](../monitoring/prometheus/index.md) to
@@ -389,7 +401,7 @@ The following are useful queries for monitoring Gitaly:
   {enforced="true",status="ok"}  4424.985419441742
   ```
 
-  There may also be other numbers with rate 0, but you only need to take note of the non-zero numbers.
+  There may also be other numbers with rate 0, but you only have to take note of the non-zero numbers.
 
   The only non-zero number should have `enforced="true",status="ok"`. If you have other non-zero
   numbers, something is wrong in your configuration.
@@ -560,7 +572,7 @@ Additional information:
 GitLab recommends:
 
 - Creating a [Gitaly Cluster](#gitaly-cluster) as soon as possible.
-- [Moving your repositories](praefect.md#migrate-to-gitaly-cluster) from NFS-based storage to Gitaly
+- [Moving your repositories](#migrate-to-gitaly-cluster) from NFS-based storage to Gitaly
   Cluster.
 
 We welcome your feedback on this process. You can:

doc/administration/gitaly/praefect.md

@@ -432,7 +432,7 @@ On the **Praefect** node:
    WARNING:
    If you have data on an already existing storage called
    `default`, you should configure the virtual storage with another name and
-   [migrate the data to the Gitaly Cluster storage](#migrate-to-gitaly-cluster)
+   [migrate the data to the Gitaly Cluster storage](index.md#migrate-to-gitaly-cluster)
    afterwards.
 
    Replace `PRAEFECT_INTERNAL_TOKEN` with a strong secret, which is used by
@@ -896,7 +896,7 @@ Particular attention should be shown to:
 
    WARNING:
    If you have existing data stored on the default Gitaly storage,
-   you should [migrate the data your Gitaly Cluster storage](#migrate-to-gitaly-cluster)
+   you should [migrate the data your Gitaly Cluster storage](index.md#migrate-to-gitaly-cluster)
    first.
 
    ```ruby
@@ -1574,132 +1574,3 @@ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.t
 - Replace the placeholder `<virtual-storage>` with the virtual storage containing the Gitaly node storage to be checked.
 - Replace the placeholder `<up-to-date-storage>` with the Gitaly storage name containing up to date repositories.
 - Replace the placeholder `<outdated-storage>` with the Gitaly storage name containing outdated repositories.
-
-## Migrate to Gitaly Cluster
-
-Whether migrating to Gitaly Cluster because of [NFS support deprecation](index.md#nfs-deprecation-notice)
-or to move from single Gitaly nodes, the basic process involves:
-
-1. Create the required storage.
-1. Create and configure Gitaly Cluster.
-1. [Move the repositories](#move-repositories).
-
-When creating the storage, see some
-[repository storage recommendations](faq.md#what-are-some-repository-storage-recommendations).
-
-### Move Repositories
-
-WARNING:
-To move repositories into a Gitaly Cluster in GitLab versions 13.12 to 14.1, you must
-[enable the `gitaly_replicate_repository_direct_fetch` feature flag](../feature_flags.md).
-
-To migrate to Gitaly Cluster, existing repositories stored outside Gitaly Cluster must be
-moved. There is no automatic migration but the moves can be scheduled with the GitLab API.
-
-GitLab repositories can be associated with projects, groups, and snippets. Each of these types
-have a separate API to schedule the respective repositories to move. To move all repositories
-on a GitLab instance, each of these types must be scheduled to move for each storage.
-
-Each repository is made read-only for the duration of the move. The repository is not writable
-until the move has completed.
-
-After creating and configuring Gitaly Cluster:
-
-1. Ensure all storages are accessible to the GitLab instance. In this example, these are
-   `<original_storage_name>` and `<cluster_storage_name>`.
-1. [Configure repository storage weights](../repository_storage_paths.md#configure-where-new-repositories-are-stored)
-   so that the Gitaly Cluster receives all new projects. This stops new projects from being created
-   on existing Gitaly nodes while the migration is in progress.
-1. Schedule repository moves for:
-   - [Projects](#bulk-schedule-project-moves).
-   - [Snippets](#bulk-schedule-snippet-moves).
-   - [Groups](#bulk-schedule-group-moves). **(PREMIUM SELF)**
-
-#### Bulk schedule project moves
-
-1. [Schedule repository storage moves for all projects on a storage shard](../../api/project_repository_storage_moves.md#schedule-repository-storage-moves-for-all-projects-on-a-storage-shard) using the API. For example:
-
-   ```shell
-   curl --request POST --header "Private-Token: <your_access_token>" \
-        --header "Content-Type: application/json" \
-        --data '{"source_storage_name":"<original_storage_name>","destination_storage_name":"<cluster_storage_name>"}' \
-        "https://gitlab.example.com/api/v4/project_repository_storage_moves"
-   ```
-
-1. [Query the most recent repository moves](../../api/project_repository_storage_moves.md#retrieve-all-project-repository-storage-moves)
-   using the API. The query indicates either:
-   - The moves have completed successfully. The `state` field is `finished`.
-   - 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. 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.
-
-   ```shell
-   curl --header "Private-Token: <your_access_token>" --header "Content-Type: application/json" \
-   "https://gitlab.example.com/api/v4/projects?repository_storage=<original_storage_name>"
-   ```
-
-   Alternatively use [the rails console](../operations/rails_console.md) to
-   confirm that all projects have moved. Run the following in the rails console:
-
-   ```ruby
-   ProjectRepository.for_repository_storage('<original_storage_name>')
-   ```
-
-1. Repeat for each storage as required.
-
-#### Bulk schedule snippet moves
-
-1. [Schedule repository storage moves for all snippets on a storage shard](../../api/snippet_repository_storage_moves.md#schedule-repository-storage-moves-for-all-snippets-on-a-storage-shard) using the API. For example:
-
-   ```shell
-   curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
-        --header "Content-Type: application/json" \
-        --data '{"source_storage_name":"<original_storage_name>","destination_storage_name":"<cluster_storage_name>"}' \
-        "https://gitlab.example.com/api/v4/snippet_repository_storage_moves"
-   ```
-
-1. [Query the most recent repository moves](../../api/snippet_repository_storage_moves.md#retrieve-all-snippet-repository-storage-moves)
-   using the API. The query indicates either:
-   - The moves have completed successfully. The `state` field is `finished`.
-   - 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. After the moves are complete, use [the rails console](../operations/rails_console.md) to
-   confirm that all snippets have moved. No snippets should be returned for the original
-   storage. Run the following in the rails console:
-
-   ```ruby
-   SnippetRepository.for_repository_storage('<original_storage_name>')
-   ```
-
-1. Repeat for each storage as required.
-
-#### Bulk schedule group moves **(PREMIUM SELF)**
-
-1. [Schedule repository storage moves for all groups on a storage shard](../../api/group_repository_storage_moves.md#schedule-repository-storage-moves-for-all-groups-on-a-storage-shard) using the API.
-
-    ```shell
-    curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
-         --header "Content-Type: application/json" \
-         --data '{"source_storage_name":"<original_storage_name>","destination_storage_name":"<cluster_storage_name>"}' \
-         "https://gitlab.example.com/api/v4/group_repository_storage_moves"
-    ```
-
-1. [Query the most recent repository moves](../../api/group_repository_storage_moves.md#retrieve-all-group-repository-storage-moves)
-   using the API. The query indicates either:
-   - The moves have completed successfully. The `state` field is `finished`.
-   - 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. After the moves are complete, use [the rails console](../operations/rails_console.md) to
-   confirm that all groups have moved. No groups should be returned for the original
-   storage. Run the following in the rails console:
-
-   ```ruby
-   GroupWikiRepository.for_repository_storage('<original_storage_name>')
-   ```
-
-1. Repeat for each storage as required.

doc/administration/operations/moving_repositories.md

@@ -7,8 +7,7 @@ type: reference
 
 # Moving repositories managed by GitLab **(FREE SELF)**
 
-Sometimes you need to move all repositories managed by GitLab to
-another file system or another server.
+You can move all repositories managed by GitLab to another file system or another server.
 
 ## Moving data within a GitLab instance
 
@@ -28,7 +27,128 @@ For more information, see:
   querying and scheduling snippet repository moves.
 - [The API documentation](../../api/group_repository_storage_moves.md) details the endpoints for
   querying and scheduling group repository moves **(PREMIUM SELF)**.
-- [Migrate to Gitaly Cluster](../gitaly/praefect.md#migrate-to-gitaly-cluster).
+- [Migrate to Gitaly Cluster](../gitaly/index.md#migrate-to-gitaly-cluster).
+
+### Move Repositories
+
+GitLab repositories can be associated with projects, groups, and snippets. Each of these types
+have a separate API to schedule the respective repositories to move. To move all repositories
+on a GitLab instance, each of these types must be scheduled to move for each storage.
+
+WARNING:
+To move repositories into a [Gitaly Cluster](../gitaly/index.md#gitaly-cluster) in GitLab versions
+13.12 to 14.1, you must [enable the `gitaly_replicate_repository_direct_fetch` feature flag](../feature_flags.md).
+
+Each repository is made read-only for the duration of the move. The repository is not writable
+until the move has completed.
+
+To move repositories:
+
+1. Ensure all storages are accessible to the GitLab instance. In this example, these are
+   `<original_storage_name>` and `<cluster_storage_name>`.
+1. [Configure repository storage weights](../repository_storage_paths.md#configure-where-new-repositories-are-stored)
+   so that the new storages receives all new projects. This stops new projects from being created
+   on existing storages while the migration is in progress.
+1. Schedule repository moves for:
+   - [Projects](#bulk-schedule-project-moves).
+   - [Snippets](#bulk-schedule-snippet-moves).
+   - [Groups](#bulk-schedule-group-moves). **(PREMIUM SELF)**
+
+### Bulk schedule project moves
+
+Use the API to schedule project moves:
+
+1. [Schedule repository storage moves for all projects on a storage shard](../../api/project_repository_storage_moves.md#schedule-repository-storage-moves-for-all-projects-on-a-storage-shard)
+   using the API. For example:
+
+   ```shell
+   curl --request POST --header "Private-Token: <your_access_token>" \
+        --header "Content-Type: application/json" \
+        --data '{"source_storage_name":"<original_storage_name>","destination_storage_name":"<cluster_storage_name>"}' \
+        "https://gitlab.example.com/api/v4/project_repository_storage_moves"
+   ```
+
+1. [Query the most recent repository moves](../../api/project_repository_storage_moves.md#retrieve-all-project-repository-storage-moves)
+   using the API. The response indicates either:
+   - The moves have completed successfully. The `state` field is `finished`.
+   - 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. After the moves are complete, use the API to [query projects](../../api/projects.md#list-all-projects) and confirm that all projects have moved. None of the projects should be returned with the
+   `repository_storage` field set to the old storage. For example:
+
+   ```shell
+   curl --header "Private-Token: <your_access_token>" --header "Content-Type: application/json" \
+   "https://gitlab.example.com/api/v4/projects?repository_storage=<original_storage_name>"
+   ```
+
+   Alternatively use [the rails console](../operations/rails_console.md) to confirm that all
+   projects have moved. Run the following in the rails console:
+
+   ```ruby
+   ProjectRepository.for_repository_storage('<original_storage_name>')
+   ```
+
+1. Repeat for each storage as required.
+
+### Bulk schedule snippet moves
+
+Use the API to schedule snippet moves:
+
+1. [Schedule repository storage moves for all snippets on a storage shard](../../api/snippet_repository_storage_moves.md#schedule-repository-storage-moves-for-all-snippets-on-a-storage-shard). For example:
+
+   ```shell
+   curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
+        --header "Content-Type: application/json" \
+        --data '{"source_storage_name":"<original_storage_name>","destination_storage_name":"<cluster_storage_name>"}' \
+        "https://gitlab.example.com/api/v4/snippet_repository_storage_moves"
+   ```
+
+1. [Query the most recent repository moves](../../api/snippet_repository_storage_moves.md#retrieve-all-snippet-repository-storage-moves)
+The response indicates either:
+   - The moves have completed successfully. The `state` field is `finished`.
+   - 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. After the moves are complete, use [the rails console](../operations/rails_console.md) to confirm
+   that all snippets have moved. No snippets should be returned for the original storage. Run the
+   following in the rails console:
+
+   ```ruby
+   SnippetRepository.for_repository_storage('<original_storage_name>')
+   ```
+
+1. Repeat for each storage as required.
+
+### Bulk schedule group moves **(PREMIUM SELF)**
+
+Use the API to schedule group moves:
+
+1. [Schedule repository storage moves for all groups on a storage shard](../../api/group_repository_storage_moves.md#schedule-repository-storage-moves-for-all-groups-on-a-storage-shard)
+. For example:
+
+    ```shell
+    curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
+         --header "Content-Type: application/json" \
+         --data '{"source_storage_name":"<original_storage_name>","destination_storage_name":"<cluster_storage_name>"}' \
+         "https://gitlab.example.com/api/v4/group_repository_storage_moves"
+    ```
+
+1. [Query the most recent repository moves](../../api/group_repository_storage_moves.md#retrieve-all-group-repository-storage-moves)
+. The response indicates either:
+   - The moves have completed successfully. The `state` field is `finished`.
+   - 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. After the moves are complete, use [the rails console](../operations/rails_console.md) to confirm
+   that all groups have moved. No groups should be returned for the original storage. Run the
+   following in the rails console:
+
+   ```ruby
+   GroupWikiRepository.for_repository_storage('<original_storage_name>')
+   ```
+
+1. Repeat for each storage as required.
 
 ## Migrating to another GitLab instance
 

doc/administration/repository_storage_paths.md

@@ -156,4 +156,4 @@ paths, the more often it is chosen. That is,
 ## Move repositories
 
 To move a repository to a different repository storage (for example, from `default` to `storage2`), use the
-same process as [migrating to Gitaly Cluster](gitaly/praefect.md#migrate-to-gitaly-cluster).
+same process as [migrating to Gitaly Cluster](gitaly/index.md#migrate-to-gitaly-cluster).

doc/api/group_repository_storage_moves.md

@@ -10,7 +10,7 @@ type: reference
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53016) in GitLab 13.9.
 
 Group repositories can be moved between storages. This API can help you when
-[migrating to Gitaly Cluster](../administration/gitaly/praefect.md#migrate-to-gitaly-cluster), for
+[migrating to Gitaly Cluster](../administration/gitaly/index.md#migrate-to-gitaly-cluster), for
 example, or to migrate a [group wiki](../user/project/wiki/index.md#group-wikis).
 
 As group repository storage moves are processed, they transition through different states. Values

doc/api/project_repository_storage_moves.md

@@ -10,7 +10,7 @@ type: reference
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31285) in GitLab 13.0.
 
 Project repositories including wiki and design repositories can be moved between storages. This can be useful when
-[migrating to Gitaly Cluster](../administration/gitaly/praefect.md#migrate-to-gitaly-cluster),
+[migrating to Gitaly Cluster](../administration/gitaly/index.md#migrate-to-gitaly-cluster),
 for example.
 
 As project repository storage moves are processed, they transition through different states. Values

doc/api/snippet_repository_storage_moves.md

@@ -10,7 +10,7 @@ type: reference
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49228) in GitLab 13.8.
 
 Snippet repositories can be moved between storages. This can be useful when
-[migrating to Gitaly Cluster](../administration/gitaly/praefect.md#migrate-to-gitaly-cluster), for
+[migrating to Gitaly Cluster](../administration/gitaly/index.md#migrate-to-gitaly-cluster), for
 example.
 
 As snippet repository storage moves are processed, they transition through different states. Values