ISM Policy Actions Comparison

OpenSearch Index State Management gives you seven distinct actions — rollover, force_merge, shrink, allocation, snapshot, close/open, and delete — and the single most common policy design mistake is reaching for the wrong one, or firing an expensive one in the wrong tier. A force_merge on an index that is still ingesting burns hot-node I/O for nothing; a shrink on a follower index fails outright; a delete placed one transition too early destroys data an auditor still needs. This page is a decision reference: it compares every ISM action across cost, timing, preconditions, and reversibility, gives you a symptom-to-action decision flow, and shows an opensearch-py helper that reports which actions each managed index has actually run. It sits under OpenSearch ISM Architecture & Fundamentals and assumes you already understand the index lifecycle basics that these actions operate within.

The problem: the same lifecycle, seven levers #

A managed index advances through named states, and each state runs an ordered list of actions before its transition conditions are evaluated. The actions are not interchangeable. Some rewrite the physical Lucene layout (force_merge, shrink), some only move pointers (rollover, allocation), some reach outside the OpenSearch cluster (snapshot), and one is terminal and irreversible (delete). Choosing correctly is a function of three questions: what physical change am I trying to make, what does the index need to look like before the action can run, and how much I/O will it cost on the tier that owns it. The comparison table below answers the first and third; the preconditions column answers the second.

The stakes are concrete. Actions execute on the node that currently holds the primary shards, so an action’s I/O cost lands on that tier’s hardware — the compute-heavy hot tier and the storage-heavy cold tier in the hot-warm-cold tier design have very different tolerances for a segment-rewriting merge. Fire the expensive actions where the hardware and the timing are right, and the lifecycle is cheap; fire them blindly and you get I/O storms, stuck transitions, and read-only indices.

Action-to-tier fit reference #

Before the full comparison, this table aligns each action with the tier where it normally belongs and the hardware profile that tier runs on. It is the physical companion to the node role allocation model — an action is only “cheap” when the tier that runs it has the I/O budget for it.

The rule that falls out of this table: mutate the shape of an index (force_merge, shrink) exactly once, on the warm tier, after writes have stopped and before it settles onto slow cold-tier disks. Everything else is either a pointer move or an out-of-cluster copy.

The full comparison #

This is the core of the page. Every ISM action, compared across what it does, when it should fire, its I/O cost, its hard preconditions, whether it can be undone, and the tier it typically runs in.

Read the reversibility column carefully. allocation, snapshot, and close/open are round-trips — a mistake costs you a relocation or a restore. rollover, force_merge, and shrink are one-way transforms of physical layout, but the data survives. delete is the only action that destroys data, which is why it belongs in its own terminal state gated on the longest possible age condition and, for anything auditable, placed strictly after a snapshot.

Which action for which symptom #

Policy design usually starts from a symptom — “shards are too big”, “the cold tier is out of disk”, “queries are slow on old indices” — not from an action name. This decision flow maps the common symptoms and goals onto the action that resolves each one.

Notice that delete never stands alone in the flow: when archival matters, the path routes through snapshot first so the terminal action can never destroy the only copy. That ordering — an expensive-but-reversible action guarding a cheap-but-irreversible one — is the recurring shape of a safe policy.

Where each action fires in the lifecycle #

The comparison abstracts away sequence, but the actions only make sense in order. This state machine shows a representative policy and pins each action to the state that runs it, so you can see why force_merge and shrink sit in warm (after rollover has frozen the index) and why delete sits alone behind the longest age gate.

1. rollover — end the write phase cheaply #

rollover is the only action that operates on the alias, not the backing index, and it is the cheapest of the shape-changing operations because it creates one empty index and repoints a pointer. It must run in hot, and it requires the write index to be bootstrapped correctly. The deeper trigger mechanics live in Rollover Trigger Configuration.

{
  "rollover": {
    "min_index_age": "1d",
    "min_primary_shard_size": "50gb",
    "min_doc_count": 200000000
  }
}

Any one condition being met triggers the roll (conditions are OR-ed). Prefer min_primary_shard_size over min_size — it bounds the per-shard recovery cost, which is what actually hurts you on a node restart.

2. force_merge — reclaim segment overhead #

force_merge rewrites the index down to max_num_segments segments. Fewer segments mean less per-segment memory and faster queries, but the merge reads and rewrites every byte, so it is the single most I/O-expensive action per gigabyte. Never run it while the index is still ingesting — the merge fights the write path and the freshly written segments immediately re-fragment.

{
  "force_merge": {
    "max_num_segments": 1
  }
}

Merging to a single segment is optimal for read-only warm indices; it is a mistake for anything still receiving writes.

3. shrink — collapse an over-sharded index #

shrink produces a new index with fewer primary shards. It is the correct fix when rollover sizing left you with many small shards whose per-shard overhead dominates. Its preconditions are the strictest of any action: every primary must sit on one node, the source must be read-only, and the new shard count must divide the old.

{
  "shrink": {
    "num_new_shards": 1,
    "force_unsafe": false
  }
}

Because both shrink and force_merge are warm-tier layout rewrites with a mandatory ordering, the decision of which to run first — and when to run both — is detailed in choosing between force_merge and shrink for warm indices.

4. allocation — move shards between tiers #

allocation sets routing filters that make the allocator relocate shards onto the target tier. It is a pointer-and-relocation operation, not a rewrite, and it is fully reversible: set the filter back and the shards move back. It is the workhorse of the data tier routing patterns that move data hot→warm→cold.

{
  "allocation": {
    "require": { "data": "warm" },
    "wait_for": true
  }
}

Set wait_for: false if you do not want the ISM worker to block on relocation completing — pair that with a fallback strategy so a full target tier does not silently strand shards.

5. snapshot, close, and delete — the retention endgame #

These three actions govern what happens at end-of-life. snapshot copies the index to a registered repository (reversible via restore); close unloads it from memory while keeping it on disk (reversible via open); delete frees the storage permanently (never reversible).

{
  "snapshot": {
    "repository": "s3-archive",
    "snapshot": "-lifecycle"
  }
}

The safe pattern is always the same: snapshot into a state of its own, transition to a delete state gated on the longest age condition, and let the snapshot be the durable copy the delete is allowed to destroy.

Production automation: which actions has each index run? #

The operational question this whole page serves is “which of these actions has ISM actually executed against my managed indices, and did any fail?”. The _plugins/_ism/explain endpoint answers it, but its raw output is verbose. The opensearch-py helper below queries explain, extracts the current state and last action per index, flags failures, and prints a compact per-action audit. It uses structured logging and narrow exception handling so it is safe to schedule. Scope its service account per Security & Access Boundaries to read-only ISM explain.

import logging
from collections import Counter
from opensearchpy import OpenSearch, exceptions

logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
logger = logging.getLogger(__name__)

# Actions we expect to see across a healthy hot-warm-cold lifecycle.
KNOWN_ACTIONS = {"rollover", "force_merge", "shrink", "allocation", "snapshot", "close", "delete"}

class ActionAuditor:
    def __init__(self, client: OpenSearch):
        self.client = client

    def explain(self, pattern: str) -> dict:
        """Fetch the ISM explain document for every index matching the pattern."""
        try:
            return self.client.transport.perform_request(
                "GET", f"/_plugins/_ism/explain/{pattern}"
            )
        except exceptions.ConnectionError:
            logger.error("Cannot reach OpenSearch cluster.")
            return {}
        except exceptions.TransportError as exc:
            logger.error("ISM explain failed for %s: %s", pattern, exc)
            return {}

    def audit(self, pattern: str = "logs-*") -> Counter:
        """Report the current state and last action per managed index; flag failures."""
        doc = self.explain(pattern)
        run_counts: Counter = Counter()
        for index, info in doc.items():
            if not isinstance(info, dict) or "state" not in info:
                continue  # skip the 'total_managed_indices' summary key
            state = info.get("state", {}).get("name", "unknown")
            action = info.get("action", {}).get("name")
            failed = info.get("action", {}).get("failed", False)
            retries = info.get("retry_info", {}).get("consumed_retries", 0)
            if action in KNOWN_ACTIONS:
                run_counts[action] += 1
            if failed:
                logger.warning(
                    "FAILED action=%s on %s (state=%s, retries=%d)",
                    action, index, state, retries,
                )
            else:
                logger.info("%s -> state=%s last_action=%s", index, state, action)
        logger.info("Action run distribution: %s", dict(run_counts))
        return run_counts

if __name__ == "__main__":
    client = OpenSearch(
        hosts=[{"host": "localhost", "port": 9200}],
        http_auth=("admin", "admin"),
        use_ssl=True,
        verify_certs=True,
    )
    ActionAuditor(client).audit("logs-*")

The run_counts Counter gives you a fleet-wide picture: a spike in force_merge on the hot tier, or a delete count climbing faster than your snapshot count, is exactly the kind of misapplied-action signal the troubleshooting section below chases down.

Operational guardrails #

Actions interact with cluster-level settings that decide whether they can even run. The expensive shape-changing actions need throttling headroom; the tier-moving actions need watermark headroom. Set these before turning on an aggressive policy.

The I/O a force_merge performs scales with index size $S_{index}$ and the ratio of current to target segments — which is why it is cheap on a freshly-rolled index and ruinous on a large, heavily-updated one.

Troubleshooting misapplied actions #

The failures below are all the right action in the wrong place or the wrong action for the symptom — the class of problem this comparison exists to prevent.

For the follower case specifically, remember that follower indices are read-only: rollover, force_merge, shrink, and open/close all fail against them, so a CCR topology must run its write-mutating actions on the leader and let replication carry the settings across.

Frequently asked questions #

Related #

• Choosing between force_merge and shrink for warm indices — the decision procedure for the two warm-tier layout rewrites.
• Hot-Warm-Cold Tier Design — the tier hardware profiles that decide which action is cheap where.
• Node Role Allocation — how allocation routing filters map to node attributes.
• Rollover Trigger Configuration — deep dive on the size/age conditions that fire the rollover action.
• Index Lifecycle Basics — the state-and-transition model these actions operate within.

Up: OpenSearch ISM Architecture & Fundamentals