Add api spec for tiering of indices from hot to warm

Signed-off-by: Neetika Singhal <neetiks@amazon.com>

Author: neetikasinghal

.github/workflows/test-spec.yml

@@ -29,7 +29,7 @@ jobs:
           - version: 2.16.0
             hub: opensearchstaging
             ref: '@sha256:50fbfe3b95c41e92a113ada3e80513ba4524dfc8a25dc6aaeff2bbe1e1145d5f'
-
+          - opts: -Dopensearch.experimental.feature.tiered_remote_index.enabled=true
     name: test-opensearch-spec (version=${{ matrix.entry.version }}, hub=${{ matrix.entry.hub || 'opensearchproject' }})
     runs-on: ubuntu-latest
 

CHANGELOG.md

@@ -57,6 +57,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added `--opensearch-version` to `merger` that excludes schema elements per semver ([#428](https://github.com/opensearch-project/opensearch-api-specification/pull/428))
 - Added `retry` to `tester` to support asynchronous tasks ([453](https://github.com/opensearch-project/opensearch-api-specification/pull/453))
 - Added passing OPENSEARCH_JAVA_OPTS into the docker container used for tests ([#454](https://github.com/opensearch-project/opensearch-api-specification/pull/454))
+- Added `/{index}/_tier` api spec for tiering of indices ([#368](https://github.com/opensearch-project/opensearch-api-specification/pull/368))
 
 ### Changed
 

spec/namespaces/indices.yaml

@@ -1793,6 +1793,22 @@ paths:
       responses:
         '200':
           $ref: '#/components/responses/indices.stats@200'
+  /{index}/_tier/warm:
+    post:
+      operationId: indices.tier_warm.0
+      x-operation-group: indices.tier_warm
+      x-version-added: 2.16.0
+      description: Tier the index to warm in the cluster.
+      parameters:
+        - $ref: '#/components/parameters/indices.tier_warm::path.index'
+        - $ref: '#/components/parameters/indices.tier_warm::query.allow_no_indices'
+        - $ref: '#/components/parameters/indices.tier_warm::query.cluster_manager_timeout'
+        - $ref: '#/components/parameters/indices.tier_warm::query.ignore_unavailable'
+        - $ref: '#/components/parameters/indices.tier_warm::query.timeout'
+        - $ref: '#/components/parameters/indices.tier_warm::query.wait_for_completion'
+      responses:
+        '200':
+          $ref: '#/components/responses/indices.tier_warm@200'
   /{index}/_upgrade:
     get:
       operationId: indices.get_upgrade.1
@@ -2743,6 +2759,24 @@ components:
             required:
               - _all
               - _shards
+    indices.tier_warm@200:
+      description: tiering response for indices target to warm tier
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              acknowledged:
+                description: Whether the request has been acknowledged
+                type: boolean
+              failed_indices:
+                description: List of failed indices
+                type: array
+                items:
+                  $ref: '../schemas/tier.warm.yaml#/components/schemas/FailedIndex'
+            required:
+              - acknowledged
+              - failed_indices
     indices.update_aliases@200:
       description: ''
       content:
@@ -5126,6 +5160,59 @@ components:
       schema:
         $ref: '../schemas/_common.yaml#/components/schemas/Level'
       style: form
+    indices.tier_warm::path.index:
+      in: path
+      name: index
+      description: |-
+        Comma-separated list of data streams, indices, and aliases to tier.
+        Supports wildcards (`*`).
+        To search all data streams or indices, omit this parameter or use `*` or `_all`.
+      required: true
+      schema:
+        $ref: '../schemas/_common.yaml#/components/schemas/Indices'
+      style: simple
+    indices.tier_warm::query.allow_no_indices:
+      in: query
+      name: allow_no_indices
+      description: |-
+        If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices.
+        This behavior applies even if the request targets other open indices.
+      schema:
+        type: boolean
+        default: false
+      style: form
+    indices.tier_warm::query.cluster_manager_timeout:
+      name: cluster_manager_timeout
+      in: query
+      description: Operation timeout for connection to cluster-manager node.
+      schema:
+        $ref: '../schemas/_common.yaml#/components/schemas/Duration'
+      x-version-added: 2.0.0
+    indices.tier_warm::query.ignore_unavailable:
+      in: query
+      name: ignore_unavailable
+      description: If `false`, the request returns an error if it targets a missing or closed index.
+      schema:
+        type: boolean
+        default: false
+      style: form
+    indices.tier_warm::query.timeout:
+      in: query
+      name: timeout
+      description: |-
+        Period to wait for a response.
+        If no response is received before the timeout expires, the request fails and returns an error.
+      schema:
+        $ref: '../schemas/_common.yaml#/components/schemas/Duration'
+      style: form
+    indices.tier_warm::query.wait_for_completion:
+      name: wait_for_completion
+      in: query
+      description: Wait until the operation has completed before returning.
+      schema:
+        type: boolean
+        default: true
+        description: Wait until the operation has completed before returning.
     indices.update_aliases::query.cluster_manager_timeout:
       name: cluster_manager_timeout
       in: query

spec/schemas/tier.warm.yaml

@@ -0,0 +1,17 @@
+openapi: 3.1.0
+info:
+  title: Schemas of tier_warm category
+  description: Schemas of tier_warm category
+  version: 1.0.0
+paths: {}
+components:
+  schemas:
+    FailedIndex:
+      type: object
+      properties:
+        index:
+          description: Index name.
+          $ref: '_common.yaml#/components/schemas/IndexName'
+        error:
+          description: Error message.
+          type: string

tests/indices/tier/warm.yaml

@@ -0,0 +1,26 @@
+$schema: ../../../json_schemas/test_story.schema.yaml
+
+version: '>= 2.16'
+description: Test endpoints relevant to tiering of index to warm.
+prologues:
+  - path: /{index}
+    method: PUT
+    parameters:
+      index: books
+  - path: /{index}
+    method: PUT
+    parameters:
+      index: games
+epilogues:
+  - path: /books,movies
+    method: DELETE
+    status: [200, 404]
+chapters:
+  - synopsis: Tier the `books` and `games` indices from hot to warm.
+    path: /{index}/_tier/warm
+    method: POST
+    parameters:
+      index: books,games
+    response:
+      status: 200
+