Merge branch 'doc-218997-fj-add-doc-for-snippet-api-repository-moves' into 'master'

Add documentation for new Snippet repository storage move API

See merge request gitlab-org/gitlab!50151

changelogs/unreleased/doc-218997-fj-add-doc-for-snippet-api-repository-moves.yml

+---
+title: Add documentation for new Snippet repository storage move API
+merge_request: 50151
+author:
+type: other

doc/administration/gitaly/praefect.md

@@ -1363,7 +1363,7 @@ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.t
 If your GitLab instance already has repositories on single Gitaly nodes, these aren't migrated to
 Gitaly Cluster automatically.
 
-Repositories may be moved from one storage location using the [Project repository storage moves API](../../api/project_repository_storage_moves.md):
+Project repositories may be moved from one storage location using the [Project repository storage moves API](../../api/project_repository_storage_moves.md):
 
 NOTE:
 The Project repository storage moves API [cannot move all repository types](../../api/project_repository_storage_moves.md#limitations).
@@ -1387,6 +1387,8 @@ To move repositories to Gitaly Cluster:
    using the API to confirm that all projects have moved. No projects should be returned
    with `repository_storage` field set to the old storage.
 
+In a similar way, you can move Snippet repositories using the [Snippet repository storage moves API](../../api/snippet_repository_storage_moves.md):
+
 ## Debugging Praefect
 
 If you receive an error, check `/var/log/gitlab/gitlab-rails/production.log`.

doc/administration/operations/moving_repositories.md

@@ -23,12 +23,14 @@ For more information, see:
 - [Configuring additional storage for Gitaly](../gitaly/index.md#network-architecture). Within this
   example, additional storage called `storage1` and `storage2` is configured.
 - [The API documentation](../../api/project_repository_storage_moves.md) details the endpoints for
-  querying and scheduling repository moves.
+  querying and scheduling project repository moves.
+- [The API documentation](../../api/snippet_repository_storage_moves.md) details the endpoints for
+  querying and scheduling snippet repository moves.
 - [Migrate existing repositories to Gitaly Cluster](../gitaly/praefect.md#migrate-existing-repositories-to-gitaly-cluster).
 
 ### Limitations
 
-Read more in the [API documentation](../../api/project_repository_storage_moves.md#limitations).
+Read more in the [API documentation for projects](../../api/project_repository_storage_moves.md#limitations) and the [API documentation for snippets](../../api/snippet_repository_storage_moves.md#limitations).
 
 ## Migrating to another GitLab instance
 

doc/api/api_resources.md

@@ -158,6 +158,7 @@ The following API resources are available outside of project and group contexts
 | [Runners](runners.md)                              | `/runners` (also available for projects)                                |
 | [Search](search.md)                                | `/search` (also available for groups and projects)                      |
 | [Settings](settings.md) **(CORE ONLY)**            | `/application/settings`                                                 |
+| [Snippet repository storage moves](snippet_repository_storage_moves.md) **(CORE ONLY)** | `/snippet_repository_storage_moves` |
 | [Statistics](statistics.md)                        | `/application/statistics`                                               |
 | [Sidekiq metrics](sidekiq_metrics.md) **(CORE ONLY)** | `/sidekiq`                                                           |
 | [Suggestions](suggestions.md)                      | `/suggestions`                                                          |

doc/api/project_repository_storage_moves.md

@@ -30,9 +30,10 @@ read-only. Please try again later.` message if they try to push new commits.
 
 This API requires you to [authenticate yourself](README.md#authentication) as an administrator.
 
+Snippet repositories can be moved using the [Snippet repository storage moves API](snippet_repository_storage_moves.md).
+
 ## Limitations
 
-- The repositories associated with snippets [can't be moved with the API](https://gitlab.com/groups/gitlab-org/-/epics/3393).
 - Group-level wikis [can't be moved with the API](https://gitlab.com/gitlab-org/gitlab/-/issues/219003).
 
 ## Retrieve all project repository storage moves

doc/api/snippet_repository_storage_moves.md

+---
+stage: Create
+group: Editor
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+type: reference
+---
+
+# Snippet repository storage moves API **(CORE ONLY)**
+
+> [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-existing-repositories-to-gitaly-cluster),
+for example.
+
+As snippet repository storage moves are processed, they transition through different states. Values
+of `state` are:
+
+- `initial`
+- `scheduled`
+- `started`
+- `finished`
+- `failed`
+- `replicated`
+- `cleanup failed`
+
+To ensure data integrity, snippets are put in a temporary read-only state for the
+duration of the move. During this time, users receive a `The repository is temporarily
+read-only. Please try again later.` message if they try to push new commits.
+
+This API requires you to [authenticate yourself](README.md#authentication) as an administrator.
+
+Project repositories can be moved using the [Project repository storage moves API](project_repository_storage_moves.md).
+
+## Limitations
+
+- Group-level wikis [can't be moved with the API](https://gitlab.com/gitlab-org/gitlab/-/issues/219003).
+
+## Retrieve all snippet repository storage moves
+
+```plaintext
+GET /snippet_repository_storage_moves
+```
+
+By default, `GET` requests return 20 results at a time because the API results
+are [paginated](README.md#pagination).
+
+Example request:
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/snippet_repository_storage_moves"
+```
+
+Example response:
+
+```json
+[
+  {
+    "id": 1,
+    "created_at": "2020-05-07T04:27:17.234Z",
+    "state": "scheduled",
+    "source_storage_name": "default",
+    "destination_storage_name": "storage2",
+    "snippet": {
+      "id": 65,
+      "title": "Test Snippet",
+      "description": null,
+      "visibility": "internal",
+      "updated_at": "2020-12-01T11:15:50.385Z",
+      "created_at": "2020-12-01T11:15:50.385Z",
+      "project_id": null,
+      "web_url": "https://gitlab.example.com/-/snippets/65",
+      "raw_url": "https://gitlab.example.com/-/snippets/65/raw",
+      "ssh_url_to_repo": "ssh://user@gitlab.example.com/snippets/65.git",
+      "http_url_to_repo": "https://gitlab.example.com/snippets/65.git"
+    }
+  }
+]
+```
+
+## Retrieve all repository storage moves for a snippet
+
+```plaintext
+GET /snippets/:snippet_id/repository_storage_moves
+```
+
+By default, `GET` requests return 20 results at a time because the API results
+are [paginated](README.md#pagination).
+
+Supported attributes:
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `snippet_id` | integer | yes | ID of the snippet. |
+
+Example request:
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/snippets/1/repository_storage_moves"
+```
+
+Example response:
+
+```json
+[
+  {
+    "id": 1,
+    "created_at": "2020-05-07T04:27:17.234Z",
+    "state": "scheduled",
+    "source_storage_name": "default",
+    "destination_storage_name": "storage2",
+    "snippet": {
+      "id": 65,
+      "title": "Test Snippet",
+      "description": null,
+      "visibility": "internal",
+      "updated_at": "2020-12-01T11:15:50.385Z",
+      "created_at": "2020-12-01T11:15:50.385Z",
+      "project_id": null,
+      "web_url": "https://gitlab.example.com/-/snippets/65",
+      "raw_url": "https://gitlab.example.com/-/snippets/65/raw",
+      "ssh_url_to_repo": "ssh://user@gitlab.example.com/snippets/65.git",
+      "http_url_to_repo": "https://gitlab.example.com/snippets/65.git"
+    }
+  }
+]
+```
+
+## Get a single snippet repository storage move
+
+```plaintext
+GET /snippet_repository_storage_moves/:repository_storage_id
+```
+
+Supported attributes:
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `repository_storage_id` | integer | yes | ID of the snippet repository storage move. |
+
+Example request:
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/snippet_repository_storage_moves/1"
+```
+
+Example response:
+
+```json
+{
+  "id": 1,
+  "created_at": "2020-05-07T04:27:17.234Z",
+  "state": "scheduled",
+  "source_storage_name": "default",
+  "destination_storage_name": "storage2",
+  "snippet": {
+    "id": 65,
+    "title": "Test Snippet",
+    "description": null,
+    "visibility": "internal",
+    "updated_at": "2020-12-01T11:15:50.385Z",
+    "created_at": "2020-12-01T11:15:50.385Z",
+    "project_id": null,
+    "web_url": "https://gitlab.example.com/-/snippets/65",
+    "raw_url": "https://gitlab.example.com/-/snippets/65/raw",
+    "ssh_url_to_repo": "ssh://user@gitlab.example.com/snippets/65.git",
+    "http_url_to_repo": "https://gitlab.example.com/snippets/65.git"
+  }
+}
+```
+
+## Get a single repository storage move for a snippet
+
+```plaintext
+GET /snippets/:snippet_id/repository_storage_moves/:repository_storage_id
+```
+
+Supported attributes:
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `snippet_id` | integer | yes | ID of the snippet. |
+| `repository_storage_id` | integer | yes | ID of the snippet repository storage move. |
+
+Example request:
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/snippets/1/repository_storage_moves/1"
+```
+
+Example response:
+
+```json
+{
+  "id": 1,
+  "created_at": "2020-05-07T04:27:17.234Z",
+  "state": "scheduled",
+  "source_storage_name": "default",
+  "destination_storage_name": "storage2",
+  "snippet": {
+    "id": 65,
+    "title": "Test Snippet",
+    "description": null,
+    "visibility": "internal",
+    "updated_at": "2020-12-01T11:15:50.385Z",
+    "created_at": "2020-12-01T11:15:50.385Z",
+    "project_id": null,
+    "web_url": "https://gitlab.example.com/-/snippets/65",
+    "raw_url": "https://gitlab.example.com/-/snippets/65/raw",
+    "ssh_url_to_repo": "ssh://user@gitlab.example.com/snippets/65.git",
+    "http_url_to_repo": "https://gitlab.example.com/snippets/65.git"
+  }
+}
+```
+
+## Schedule a repository storage move for a snippet
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49228) in GitLab 13.8.
+
+```plaintext
+POST /snippets/:snippet_id/repository_storage_moves
+```
+
+Supported attributes:
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `snippet_id` | integer | yes | ID of the snippet. |
+| `destination_storage_name` | string | no | Name of the destination storage shard. In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitaly/-/issues/3209), the storage is selected automatically if not provided. |
+
+Example request:
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \
+--data '{"destination_storage_name":"storage2"}' "https://gitlab.example.com/api/v4/snippets/1/repository_storage_moves"
+```
+
+Example response:
+
+```json
+{
+  "id": 1,
+  "created_at": "2020-05-07T04:27:17.234Z",
+  "state": "scheduled",
+  "source_storage_name": "default",
+  "destination_storage_name": "storage2",
+  "snippet": {
+    "id": 65,
+    "title": "Test Snippet",
+    "description": null,
+    "visibility": "internal",
+    "updated_at": "2020-12-01T11:15:50.385Z",
+    "created_at": "2020-12-01T11:15:50.385Z",
+    "project_id": null,
+    "web_url": "https://gitlab.example.com/-/snippets/65",
+    "raw_url": "https://gitlab.example.com/-/snippets/65/raw",
+    "ssh_url_to_repo": "ssh://user@gitlab.example.com/snippets/65.git",
+    "http_url_to_repo": "https://gitlab.example.com/snippets/65.git"
+  }
+}
+```
+
+## Schedule repository storage moves for all snippets on a storage shard
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49228) in GitLab 13.8.
+
+Schedules repository storage moves for each snippet repository stored on the source storage shard.
+
+```plaintext
+POST /snippet_repository_storage_moves
+```
+
+Supported attributes:
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `source_storage_name` | string | yes | Name of the source storage shard. |
+| `destination_storage_name` | string | no | Name of the destination storage shard. The storage is selected automatically if not provided. |
+
+Example request:
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \
+--data '{"source_storage_name":"default"}' "https://gitlab.example.com/api/v4/snippet_repository_storage_moves"
+```
+
+Example response:
+
+```json
+{
+  "message": "202 Accepted"
+}
+```