Add spec for new rename_alias_pattern and rename_alias_replacement pa…

…rameters to snapshot restore (#615)
opensearch-project · Nov 23, 2024 · 8cb29a4 · 8cb29a4
1 parent 22bdd5c
commit 8cb29a4
Show file tree

Hide file tree

Showing 3 changed files with 100 additions and 6 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -16,6 +16,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added `PhoneAnalyzer` from `analysis-phonenumber` plugin ([#609](https://github.com/opensearch-project/opensearch-api-specification/pull/609))
 - Added `/_list/indices` & `/_list/shards` api specs ([#613](https://github.com/opensearch-project/opensearch-api-specification/pull/613))
 - Added `GET` and `HEAD /{index}/_source/{id}` returning `404` ([#673](https://github.com/opensearch-project/opensearch-api-specification/pull/673))
+- Added `rename_alias_pattern` and `rename_alias_replacment` to `/_snapshot/{repository}/{snapshot}/_restore` body parameters ([#615](https://github.com/opensearch-project/opensearch-api-specification/pull/615))
 
 ### Removed
 - Removed unsupported `_common.mapping:SourceField`'s `mode` field and associated `_common.mapping:SourceFieldMode` enum ([#652](https://github.com/opensearch-project/opensearch-api-specification/pull/652))

diff --git a/spec/namespaces/snapshot.yaml b/spec/namespaces/snapshot.yaml
@@ -294,7 +294,7 @@ components:
             type: object
             properties:
               ignore_unavailable:
-                description: If `true`, the request ignores data streams and indexes in `indices` that are missing or closed. If `false`, the request returns an error for any data stream or index that is missing or closed.
+                description: If `true`, the request ignores data streams and indexes in `indexes` that are missing or closed. If `false`, the request returns an error for any data stream or index that is missing or closed.
                 type: boolean
               include_global_state:
                 description: If `true`, the current cluster state is included in the snapshot. The cluster state includes persistent cluster settings, composable index templates, legacy index templates, ingest pipelines, and ILM policies. It also includes data stored in system indexes, such as Watches and task records (configurable with `feature_states`).
@@ -335,30 +335,67 @@ components:
           schema:
             type: object
             properties:
-              feature_states:
-                type: array
-                items:
-                  type: string
               ignore_index_settings:
+                description: A comma-delimited list of index settings that you don't want to restore from a snapshot.
                 type: array
                 items:
                   type: string
               ignore_unavailable:
                 type: boolean
+                description: How to handle data streams or indexes that are missing or closed. If `false`, the request returns an error for any data stream or index that is missing or closed. If `true`, the request ignores data streams and indexes in indexes that are missing or closed. Defaults to `false`.
               include_aliases:
                 type: boolean
+                description: How to handle index aliases from the original snapshot. If `true`, index aliases from the original snapshot are restored. If `false`, aliases along with associated indexes are not restored. Defaults to `true`.
               include_global_state:
                 type: boolean
+                description: Whether to restore the current cluster state. If `false`, the cluster state is not restored. If true, the current cluster state is restored. Defaults to `false`.
               index_settings:
+                description: A comma-delimited list of settings to add or change in all restored indexes. Use this parameter to override index settings during snapshot restoration. For data streams, these index settings are applied to the restored backing indexes.
                 $ref: '../schemas/indices._common.yaml#/components/schemas/IndexSettings'
               indices:
+                description: A comma-delimited list of data streams and indexes to restore from the snapshot. Multi-index syntax is supported. By default, a restore operation includes all data streams and indexes in the snapshot. If this argument is provided, the restore operation only includes the data streams and indexes that you specify.
                 $ref: '../schemas/_common.yaml#/components/schemas/Indices'
               partial:
                 type: boolean
+                description: |-
+                  How the restore operation will behave if indexes in the snapshot do not have all primary shards available.
+                  If `false`, the entire restore operation fails if any indexes in the snapshot do not have all primary shards available.
+                  If `true`, allows the restoration of a partial snapshot of indexes with unavailable shards. Only shards that were successfully included in the snapshot are restored. All missing shards are recreated as empty. By default, the entire restore operation fails if one or more indexes included in the snapshot do not have all primary shards available. To change this behavior, set `partial` to `true`.
+                  Defaults to `false`.
               rename_pattern:
                 type: string
+                description: |-
+                  The pattern to apply to the restored data streams and indexes. Data streams and indexes matching the rename pattern will be renamed according to the `rename_replacement` setting.
+                  The rename pattern is applied as defined by the regular expression that supports referencing the original text.
+                  The request fails if two or more data streams or indexes are renamed into the same name.
+                  If you rename a restored data stream, its backing indexes are also renamed. For example, if you rename the logs data stream to `recovered-logs`, the backing index `.ds-logs-1` is renamed to `.ds-recovered-logs-1`.
+                  If you rename a restored stream, ensure an index template matches the new stream name. If there are no matching index template names, the stream cannot roll over and new backing indexes are not created.
               rename_replacement:
                 type: string
+                description: The rename replacement string.
+              rename_alias_pattern:
+                x-version-added: '2.18'
+                type: string
+                description: |-
+                  The pattern to apply to the restored aliases. Aliases matching the rename pattern will be renamed according to the `rename_alias_replacement` setting.
+                  The rename pattern is applied as defined by the regular expression that supports referencing the original text.
+                  If two or more aliases are renamed into the same name, these aliases will be merged into one.
+              rename_alias_replacement:
+                x-version-added: '2.18'
+                type: string
+                description: The rename replacement string for aliases.
+              source_remote_store_repository:
+                x-version-added: '2.10'
+                type: string
+                description: The name of the remote store repository of the source index being restored. If not provided, the Snapshot Restore API will use the repository that was registered when the snapshot was created.
+              storage_type:
+                x-version-added: '2.7'
+                type: string
+                description: |-
+                  Where will be the authoritative store of the restored indexes' data.
+                  A value of `local` indicates that all snapshot metadata and index data will be downloaded to local storage.
+                  A value of `remote_snapshot` indicates that snapshot metadata will be downloaded to the cluster, but the remote repository will remain the authoritative store of the index data. Data will be downloaded and cached as necessary to service queries. At least one node in the cluster must be configured with the search role in order to restore a snapshot using the type `remote_snapshot`.
+                  Defaults to `local`.
             description: Details of what to restore
   responses:
     snapshot.cleanup_repository@200:

diff --git a/tests/snapshot/snapshot/restore.yaml b/tests/snapshot/snapshot/restore.yaml
@@ -19,6 +19,12 @@ epilogues:
   - path: /books
     method: DELETE
     status: [200, 404]
+  - path: /stories
+    method: DELETE
+    status: [200, 404]
+  - path: /stories_restored
+    method: DELETE
+    status: [200, 404]
 prologues:
   - path: /_snapshot/{repository}
     method: PUT
@@ -33,6 +39,16 @@ prologues:
     method: PUT
   - path: /books
     method: PUT
+  - path: /stories
+    method: PUT
+  - path: /_aliases
+    method: POST
+    request:
+      payload:
+        actions:
+          - add:
+              index: stories
+              alias: stories_alias
   - path: /_snapshot/{repository}/{snapshot}
     method: PUT
     parameters:
@@ -44,6 +60,7 @@ prologues:
         indices:
           - books
           - movies
+          - stories
         ignore_unavailable: true
         include_global_state: false
         partial: true
@@ -53,6 +70,9 @@ prologues:
   - path: /books
     method: DELETE
     status: [200, 404]
+  - path: /stories
+    method: DELETE
+    status: [200, 404]
 chapters:
   - synopsis: Restore snapshot with `wait_for_completion` true.
     path: /_snapshot/{repository}/{snapshot}/_restore
@@ -98,4 +118,40 @@ chapters:
             - stage: DONE
               type: SNAPSHOT
     retry:
-      count: 3
+      count: 3
+  - synopsis: Restore snapshot with rename_pattern and rename_replacement.
+    path: /_snapshot/{repository}/{snapshot}/_restore
+    method: POST
+    parameters:
+      repository: my-fs-repository
+      snapshot: my-test-snapshot
+      wait_for_completion: true
+    request:
+      payload:
+        indices: stories
+        rename_pattern: '^(.*)$'
+        rename_replacement: $1_restored
+    response:
+      status: 200
+      payload:
+        snapshot:
+          snapshot: my-test-snapshot
+  - synopsis: Restore snapshot with rename_alias_pattern and rename_alias_replacement.
+    version: '>= 2.18'
+    path: /_snapshot/{repository}/{snapshot}/_restore
+    method: POST
+    parameters:
+      repository: my-fs-repository
+      snapshot: my-test-snapshot
+      wait_for_completion: true
+    request:
+      payload:
+        indices: stories
+        include_aliases: true
+        rename_alias_pattern: '^(.*)$'
+        rename_alias_replacement: $1_restored
+    response:
+      status: 200
+      payload:
+        snapshot:
+          snapshot: my-test-snapshot