OpenSearch Index State Management Policies, States, Transitions, Actions, Templates, and Simulation

Learning outcomes

AtlasMart now implements the same lifecycle intent in OpenSearch. The objective is not to “translate ILM JSON.” It is to model explicit ISM states, ordered actions, transition conditions, policy attachment/templates, simulation and managed-index diagnostics.

1. ISM is a user-defined state machine

An ISM policy has a default_state, one or more named states, ordered actions inside each state, and transitions evaluated after the state’s actions complete. A managed index is in one state at a time. ISM runs as a background job rather than continuously; upstream documentation states a default job interval of five minutes, and ISM does not run jobs while cluster state is red.

Because transitions are polled, a threshold is not an exact timer. An index can exceed a size/age condition between checks. Capacity planning must include this overshoot rather than assuming the action fires at the exact byte or second.

2. Create the AtlasMart ISM policy

PUT _plugins/_ism/policies/atlasmart-life-os-v1
{
  "policy": {
    "description": "AtlasMart disposable lifecycle lab",
    "default_state": "hot",
    "states": [
      {
        "name": "hot",
        "actions": [
          {"rollover": {"min_doc_count": 3}}
        ],
        "transitions": [
          {"state_name": "warm", "conditions": {"min_rollover_age": "0ms"}}
        ]
      },
      {
        "name": "warm",
        "actions": [
          {"read_only": {}},
          {"force_merge": {"max_num_segments": 1}}
        ],
        "transitions": [
          {"state_name": "delete", "conditions": {"min_index_age": "30d"}}
        ]
      },
      {
        "name": "delete",
        "actions": [{"delete": {}}],
        "transitions": []
      }
    ],
    "ism_template": {
      "index_patterns": ["atlasmart-life-os-*"],
      "priority": 100
    }
  }
}

3. Rollover still needs an index template and write alias

PUT _index_template/atlasmart-life-os-template-v1
{
  "index_patterns": ["atlasmart-life-os-*"],
  "template": {
    "settings": {
      "number_of_shards": 1,
      "number_of_replicas": 0,
      "plugins.index_state_management.rollover_alias": "atlasmart-life-os"
    },
    "mappings": {
      "properties": {
        "@timestamp": {"type":"date"},
        "service.name": {"type":"keyword"},
        "log.level": {"type":"keyword"},
        "message": {"type":"text"}
      }
    }
  }
}

PUT atlasmart-life-os-000001
{
  "aliases": {
    "atlasmart-life-os": {"is_write_index": true}
  }
}

ISM rollover expects a numeric generation suffix such as -000001, a rollover alias setting, and an alias for which the managed index is the write index. The ISM template decides which future indices receive the policy; the index template defines settings/mappings/rollover alias. These are separate artifacts.

4. Simulate before mutation

OpenSearch 3.7 introduced the ISM simulation API. In 3.8 it can evaluate a stored or inline policy against specified indices without changing them. The response can report current state, next action and transition-condition evaluation. This is particularly useful for policy reviews and troubleshooting timing.

POST _plugins/_ism/simulate
{
  "policy_id": "atlasmart-life-os-v1",
  "indices": ["atlasmart-life-os-000001"]
}

Simulation proves how the policy would evaluate the current metadata. It does not prove the future action will have enough disk, eligible allocation targets, privileges, or acceptable merge/recovery latency.

5. Observe managed state, policy version and action validation

GET _plugins/_ism/explain/atlasmart-life-os-000001?show_policy=true
GET _plugins/_ism/explain/atlasmart-life-os-000001?validate_action=true
GET _plugins/_ism/policies/atlasmart-life-os-v1

show_policy=true helps reveal which policy definition is attached to the managed index. The policy document itself exposes version/OCC metadata. Error prevention can validate an upcoming action and surface why rollover, force merge or another operation would fail before execution.

POST atlasmart-life-os/_doc
{"@timestamp":"2026-09-11T12:00:00Z","service.name":"checkout","log.level":"INFO","message":"order accepted"}
POST atlasmart-life-os/_doc
{"@timestamp":"2026-09-11T12:00:01Z","service.name":"checkout","log.level":"WARN","message":"inventory retry"}
POST atlasmart-life-os/_doc
{"@timestamp":"2026-09-11T12:00:02Z","service.name":"checkout","log.level":"INFO","message":"order confirmed"}

GET _plugins/_ism/explain/atlasmart-life-os-*?show_policy=true
GET _cat/aliases/atlasmart-life-os?v
GET _cat/indices/atlasmart-life-os-*?v

The expected invariant is eventual creation of a new write generation after a background ISM check, not immediate rollover in the indexing response.

6. Allocation is not Elastic data tiers

ISM supports an allocation action and other OpenSearch-specific capabilities, but these do not turn upstream OpenSearch into Elastic’s data-tier model. If AtlasMart labels nodes with attributes such as temp=warm, an ISM allocation action can require/include/exclude those attributes. That is an explicit topology contract owned by AtlasMart.

The next lesson focuses on policy versioning, safe testing and stuck-state intervention on both products.

Summary

OpenSearch ISM is an explicit state machine with ordered actions, transition polling, templates, simulation and managed-index diagnostics. The business intent can resemble ILM, but the policy artifact and operational behavior are different.

Authoritative references

• Elastic index lifecycle management — ILM scope, availability, and lifecycle concepts for indices and data streams.
• Elastic ILM phases and actions — Hot/warm/cold/frozen/delete phases, cached phase execution, and transition rules.
• Elastic Explain lifecycle API — Current phase/action/step, failures, and phase execution evidence.
• Elastic data tiers — Content/hot/warm/cold/frozen roles and lifecycle placement concepts.
• Elastic policy updates — Policy versions and cached phase-definition behavior.
• Elastic ILM troubleshooting — ERROR steps, retry behavior, and safe diagnosis.
• OpenSearch Index State Management — ISM model, job cadence, policy attachment, and managed-index workflow.
• OpenSearch ISM policies — States, actions, transitions, rollover, force merge, allocation, and templates.
• OpenSearch ISM API — Policy OCC, explain, retry, change-policy, and simulation APIs.
• OpenSearch ISM error prevention — Pre-action validation and explain diagnostics.
• OpenSearch artifacts by version — Current OpenSearch release baseline.
• Elasticsearch downloads — Current Elasticsearch release baseline.