Added schema and tests for cluster routing awareness and decommission.

.github/workflows/test-spec.yml

@@ -32,6 +32,8 @@ jobs:
             tests: plugins/index_state_management
           - version: 2.16.0
             tests: plugins/ml
+          - version: 2.16.0
+            tests: routing
           - version: 2.16.0
             tests: snapshot
           - version: 2.17.0
@@ -67,11 +69,6 @@ jobs:
         working-directory: tests/${{ matrix.entry.tests || 'default' }}
         run: docker compose up -d
 
-      - name: Get Container ID
-        id: container
-        run: |
-          echo "CONTAINER_ID=$(docker ps -aqf "ancestor=opensearchproject/opensearch:${{ matrix.entry.version }}")" >> $GITHUB_OUTPUT
-
       - name: Run Tests
         run: |
           npm run test:spec -- \
@@ -81,10 +78,12 @@ jobs:
             --tests=tests/${{ matrix.entry.tests || 'default' }}
 
       - name: Get Container Logs
-        if: failure() && steps.container.outputs.CONTAINER_ID
+        if: failure()
         run: |
-          echo Dumping logs from ${{ steps.container.outputs.CONTAINER_ID }} ...
-          docker logs ${{ steps.container.outputs.CONTAINER_ID }}
+          for container_id in $(docker ps -aqf "ancestor=opensearchproject/opensearch:${{ matrix.entry.version }}"); do \
+            echo Dumping logs from $container_id ... && \
+            docker logs $container_id \
+          ; done
 
       - name: Upload Test Coverage Results
         uses: actions/upload-artifact@v4

CHANGELOG.md

@@ -86,6 +86,8 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added `cluster_manager` to `ClusterNodeCount` ([#534](https://github.com/opensearch-project/opensearch-api-specification/pull/534))
 - Added support for `query` with `terms` in `_search` ([#546](https://github.com/opensearch-project/opensearch-api-specification/pull/546))
 - Added `h`, `bytes`, `time` parameters to cat API tests ([#551](https://github.com/opensearch-project/opensearch-api-specification/pull/551))
+- Added request and response schemas for `/_cluster/routing/awareness/{attribute}/weights` ([#524](https://github.com/opensearch-project/opensearch-api-specification/pull/524))
+- Added request and response schemas for `/_cluster/decommission/awareness` ([#524](https://github.com/opensearch-project/opensearch-api-specification/pull/524))
 
 ### Changed
 

TESTING_GUIDE.md

@@ -213,7 +213,15 @@ Consider the following chapters in [ml/model_groups](tests/plugins/ml/ml/model_g
 ```
 As you can see, the `output` field in the first chapter saves the `model_group_id` from the response body. This value is then used in the subsequent chapters to query and delete the model group.
 
-You can also reuse output in payload expectations. See [tests/plugins/index_state_management/nodes/plugins/index_state_management.yaml](tests/plugins/index_state_management/nodes/plugins/index_state_management.yaml) for an example.
+You can also supply defaults for output values, e.g. for `payload._version` used in [cluster/routing/awareness/weights.yaml](tests/routing/cluster/routing/awareness/weights.yaml).
+
+```
+version:
+  path: payload._version
+  default: -1
+```
+
+You can reuse output in payload expectations. See [tests/plugins/index_state_management/nodes/plugins/index_state_management.yaml](tests/plugins/index_state_management/nodes/plugins/index_state_management.yaml) for an example.
 
 ### Managing Versions
 

json_schemas/test_story.schema.yaml

@@ -105,8 +105,22 @@ definitions:
       - `headers.<header-name>` for the headers.
     type: object
     additionalProperties:
-      type: string
+      anyOf:
+        - type: string
+        - $ref: '#/definitions/DetailedOutput'
 
+  DetailedOutput:
+    properties:
+      path:
+        type: string
+      default:
+        type:
+          - boolean
+          - number
+          - string
+    required:
+      - path
+
   Version:
     description: |
       The semver range to execute the story or chapter against.

spec/namespaces/cluster.yaml

@@ -170,6 +170,8 @@ paths:
       description: Delete weighted shard routing weights.
       externalDocs:
         url: https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-awareness/#example-deleting-weights
+      requestBody:
+        $ref: '#/components/requestBodies/cluster.delete_weighted_routing'
       responses:
         '200':
           $ref: '#/components/responses/cluster.delete_weighted_routing@200'
@@ -195,6 +197,8 @@ paths:
         url: https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-awareness/#example-weighted-round-robin-search
       parameters:
         - $ref: '#/components/parameters/cluster.put_weighted_routing::path.attribute'
+      requestBody:
+        $ref: '#/components/requestBodies/cluster.put_weighted_routing'
       responses:
         '200':
           $ref: '#/components/responses/cluster.put_weighted_routing@200'
@@ -465,6 +469,16 @@ paths:
           $ref: '#/components/responses/cluster.remote_info@200'
 components:
   requestBodies:
+    cluster.put_weighted_routing:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/cluster.weighted_routing.yaml#/components/schemas/Weights'
+    cluster.delete_weighted_routing:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/cluster.weighted_routing.yaml#/components/schemas/WeightsBase'
     cluster.allocation_explain:
       content:
         application/json:
@@ -605,11 +619,19 @@ components:
         application/json:
           schema:
             $ref: '../schemas/_common.yaml#/components/schemas/AcknowledgedResponseBase'
-    cluster.delete_decommission_awareness@200: {}
+    cluster.delete_decommission_awareness@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/_common.yaml#/components/schemas/AcknowledgedResponseBase'
     cluster.delete_voting_config_exclusions@200:
       content:
         application/json: {}
-    cluster.delete_weighted_routing@200: {}
+    cluster.delete_weighted_routing@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/_common.yaml#/components/schemas/AcknowledgedResponseBase'
     cluster.exists_component_template@200:
       content:
         application/json: {}
@@ -625,7 +647,11 @@ components:
                   $ref: '../schemas/cluster._common.yaml#/components/schemas/ComponentTemplate'
             required:
               - component_templates
-    cluster.get_decommission_awareness@200: {}
+    cluster.get_decommission_awareness@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/cluster.decommission_awareness.yaml#/components/schemas/DecommissionStatusResponse'
     cluster.get_settings@200:
       content:
         application/json:
@@ -644,7 +670,11 @@ components:
             required:
               - persistent
               - transient
-    cluster.get_weighted_routing@200: {}
+    cluster.get_weighted_routing@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/cluster.weighted_routing.yaml#/components/schemas/WeightsResponse'
     cluster.health@200:
       content:
         application/json:
@@ -670,7 +700,11 @@ components:
         application/json:
           schema:
             $ref: '../schemas/_common.yaml#/components/schemas/AcknowledgedResponseBase'
-    cluster.put_decommission_awareness@200: {}
+    cluster.put_decommission_awareness@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/_common.yaml#/components/schemas/AcknowledgedResponseBase'
     cluster.put_settings@200:
       content:
         application/json:
@@ -689,7 +723,11 @@ components:
               - acknowledged
               - persistent
               - transient
-    cluster.put_weighted_routing@200: {}
+    cluster.put_weighted_routing@200:
+      content:
+        application/json:
+          schema:
+            type: object
     cluster.remote_info@200:
       content:
         application/json:

spec/schemas/cluster.decommission_awareness.yaml

@@ -0,0 +1,21 @@
+openapi: 3.1.0
+info:
+  title: Schemas of Decommission Awareness.
+  description: Schemas of decommission awareness category.
+  version: 1.0.0
+paths: {}
+components:
+  schemas:
+    DecommissionStatusResponse:
+      oneOf:
+        - $ref: '#/components/schemas/ZoneDecommissionStatusResponse'
+    ZoneDecommissionStatusResponse:
+      type: object
+      additionalProperties:
+        type: string
+        enum:
+          - DRAINING
+          - FAILED
+          - INIT
+          - IN_PROGRESS
+          - SUCCESSFUL

spec/schemas/cluster.weighted_routing.yaml

@@ -0,0 +1,27 @@
+openapi: 3.1.0
+info:
+  title: Schemas of Weighted Routing Category
+  description: Schemas of weighted routing category.
+  version: 1.0.0
+paths: {}
+components:
+  schemas:
+    WeightsBase:
+      type: object
+      properties:
+        _version:
+          $ref: '_common.yaml#/components/schemas/VersionNumber'
+    Weights:
+      allOf:
+        - $ref: '#/components/schemas/WeightsBase'
+        - type: object
+          properties:
+            weights:
+              type: object
+    WeightsResponse:
+      allOf:
+        - $ref: '#/components/schemas/Weights'
+        - type: object
+          properties:
+            discovered_cluster_manager:
+              type: boolean

tests/default/cluster/pending_tasks.yaml

@@ -35,6 +35,3 @@ chapters:
     method: GET
     response:
       status: 200
-      payload:
-        tasks:
-          - executing: true

tests/routing/cluster/decommission/awareness.yaml

@@ -0,0 +1,49 @@
+$schema: ../../../../json_schemas/test_story.schema.yaml
+
+description: Test cluster routing settings.
+version: '>= 2.16'
+prologues:
+  - id: weights
+    path: /_cluster/routing/awareness/zone/weights
+    method: GET
+    output:
+      version: 
+        path: payload._version
+        default: -1
+  - path: /_cluster/routing/awareness/zone/weights
+    method: PUT
+    request:
+      payload:
+        weights:
+          zoneA: '1'
+          zoneB: '0'
+        _version: ${weights.version}
+epilogues:    
+  - path: /_cluster/decommission/awareness
+    method: DELETE
+  - id: epilogue_weights
+    path: /_cluster/routing/awareness/zone/weights
+    method: GET
+    output:
+      version:
+        path: payload._version
+        default: -1
+  - path: /_cluster/routing/awareness/weights
+    method: DELETE
+    request:
+      payload:
+        _version: ${epilogue_weights.version}
+chapters:
+  - synopsis: Decommission zoneB.
+    path: /_cluster/decommission/awareness/{awareness_attribute_name}/{awareness_attribute_value}
+    method: PUT
+    parameters:
+      awareness_attribute_name: zone
+      awareness_attribute_value: zoneB
+    response:
+      status: 200
+  - synopsis: Recommission the decommissioned zoneB.
+    path: /_cluster/decommission/awareness
+    method: DELETE
+    response:
+      status: 200

tests/routing/cluster/decommission/status.yaml

@@ -0,0 +1,45 @@
+$schema: ../../../../json_schemas/test_story.schema.yaml
+
+description: Test cluster routing settings.
+version: '>= 2.16'
+prologues:
+  - id: weights
+    path: /_cluster/routing/awareness/zone/weights
+    method: GET
+    output:
+      version:
+        path: payload._version
+        default: -1
+  - path: /_cluster/routing/awareness/zone/weights
+    method: PUT
+    request:
+      payload:
+        weights:
+          zoneA: '1'
+          zoneB: '0'
+        _version: ${weights.version}
+  - path: /_cluster/decommission/awareness/zone/zoneB
+    method: PUT
+epilogues:    
+  - path: /_cluster/decommission/awareness
+    method: DELETE
+  - id: epilogue_weights
+    path: /_cluster/routing/awareness/zone/weights
+    method: GET
+    output:
+      version:
+        path: payload._version
+        default: -1
+  - path: /_cluster/routing/awareness/weights
+    method: DELETE
+    request:
+      payload:
+        _version: ${epilogue_weights.version}
+chapters:
+  - synopsis: Get the decommissioned zoneB status.
+    path: /_cluster/decommission/awareness/{awareness_attribute_name}/_status
+    method: GET
+    parameters:
+      awareness_attribute_name: zone
+    response:
+      status: 200