Add api spec for tiering of indices from hot to warm

.cspell

@@ -34,6 +34,7 @@ determinized
 distilbert
 DNFOF
 docvalue
+Dopensearch
 Downsample
 downsampling
 Downsampling

.github/workflows/test-spec.yml

@@ -31,9 +31,14 @@ jobs:
           - version: 2.16.0
             hub: opensearchstaging
             ref: '@sha256:bcd7f5d5d30231f24f266064248cc8d3306574948190f7bf93016dff29acf17e'
+          - version: 2.17.0
+            hub: opensearchstaging
+            ref: '@sha256:950075aa5a1fc9b46dcb84fee2ba12258a7f9d01b88d565b9b2634a84f03a212'
+            opts: -Dopensearch.experimental.feature.tiered_remote_index.enabled=true
           - version: 3.0.0
             hub: opensearchstaging
             ref: '@sha256:db1918b2b8f7ef6c22dd6ff54a0640877c3d395a392a53864745024933981e3b'
+            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

@@ -65,7 +65,8 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added metadata additionalProperties to `ErrorCause` ([#462](https://github.com/opensearch-project/opensearch-api-specification/pull/462))
 - Added `creation_date` field to `DanglingIndex` ([#462](https://github.com/opensearch-project/opensearch-api-specification/pull/462))
 - Added doc on `cluster create-index blocked` workaround ([#465](https://github.com/opensearch-project/opensearch-api-specification/pull/465))
-
+- Added `/{index}/_tier` api spec for tiering of indices ([#368](https://github.com/opensearch-project/opensearch-api-specification/pull/368))
+
 ### Changed
 
 - Replaced Smithy with a native OpenAPI spec ([#189](https://github.com/opensearch-project/opensearch-api-specification/issues/189))

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
@@ -2697,6 +2713,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:
       content:
         application/json:
@@ -5077,6 +5111,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,23 @@
+$schema: ../../../json_schemas/test_story.schema.yaml
+
+version: '>= 2.17'
+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