[DOC] Adding documentation for simulate API for ISM

[Tarun-kishore]

What do you want to do?

• Request a change to existing documentation
• Add new documentation
• Report a technical problem with the documentation
• Other

Tell us about your request.

Add documentation for the new ISM Policy Simulate API (POST /_plugins/_ism/simulate).

The API allows users to simulate an ISM policy against one or more indices without actually applying it. This helps users:

• Preview which state and action an index would currently be in under a given policy
• Evaluate transition conditions (e.g., min_index_age, min_doc_count, min_size) and see current vs. required values
• Test an inline policy definition without saving it to the ISM config index
• Identify the next state an index would transition to

Request body parameters:

Field	Type	Required	Description
policy_id	String	Conditional	ID of a stored ISM policy to simulate. Required if policy is not provided.
policy	Object	Conditional	Inline policy definition to simulate. Required if policy_id is not provided.
indices	Array of strings	Yes	List of index names or wildcard patterns to simulate against.

Example request (stored policy):

POST /_plugins/_ism/simulate
{
  "policy_id": "my-policy",
  "indices": ["my-index-*"]
}

Example request (inline policy):

  POST /_plugins/_ism/simulate
  {
    "policy": {
      "description": "test",
      "states": [
        {
          "name": "hot",
          "actions": [],
          "transitions": [
            { "state_name": "warm", "conditions": { "min_index_age": "30d" } }
          ] 
        },
        { "name": "warm", "actions": [], "transitions": [] }
      ] 
    },
    "indices": ["my-index"]
  }

Example response:

{
  "simulate_results": [
    {
      "index_name": "my-index",
      "index_uuid": "abc123",
      "policy_id": "my-policy",
      "is_managed": false,
      "current_state": "hot",
      "current_action": "transition",
      "transition_evaluation": [
        {
          "condition_met": false,
          "condition_type": "min_index_age",
          "current_value": "5d 3h",
          "required_value": "30d"
        } 
      ],
      "next_state": null
    } 
  ] 
} 

Version: later than 3.6

What other resources are available?

• Implementation PR: opensearch-project/index-management (pending merge)

[kolchfa-aws]

Thank you for filing this issue with such a detailed description. Since you have the subject matter expertise, would you be willing to submit a pull request with the documentation? We'd be happy to review it. You can use our API template as a starting point.

[Tarun-kishore]

Hi @kolchfa-aws, I'd be happy to create a PR for this change. I'm just waiting for the PR in index-management repo to be merged so that I can update the documentation with final approved changes.