Support for no_alias and min_state_age in ISM TransitionsFeature/ism enhancement

[Tarun-kishore]

Description

This PR introduces two new transition conditions to OpenSearch Index State Management (ISM):

• no_alias (boolean):

  • Allows transitions to be gated based on whether an index is associated with any aliases.
  • When true: transition only if the index has no aliases.
  • When false: transition only if the index has at least one alias.

• min_state_age (string duration):

  • Allows transitions only if the index has spent a minimum duration in the current ISM state.
  • Accepts time values like "5m", "7d".
  • Useful for implementing retention delays or controlled state progression.

Why min_state_age is required even though min_index_age is supported

The existing min_index_age condition measures time since index creation, which is not sufficient for lifecycle transitions that depend on how long an index has been in a specific state.

For example, if an index transitions to an archive state several days after creation, using min_index_age could cause it to immediately move to the next state — even though it just entered archive. Let's say we use a no_alias condition to move an index to archive; we wouldn't be able to guarantee that it stays in archive for a defined period if relying on min_index_age alone, since alias removal is independent of index age.

By contrast, min_state_age starts counting from when the index enters the current state, allowing policies to enforce precise retention windows or delay transitions. This enables reliable patterns like “stay in archive for 7 days” or “delay deletion for 24 hours after entering a cold state.”

---

Use Cases

• Prevent deletion or archiving of indexes still in use via aliases.
• Delay transitions (e.g., delete, freeze) for a fixed period after entering a state.
• Improve expressiveness of lifecycle policies to match real-world operational workflows.

---

Testing

Added integration tests for both new conditions.

Also validated through local testing in a controlled OpenSearch cluster using REST APIs and ISM Explain API.

Test 1: no_alias: true

• Setup: Created an index with an alias and attached a policy with no_alias: true.
• Expected: Transition should be blocked while alias is present.
• Action: Removed alias.
• Result: Transition successfully occurred after alias removal.
• Validation: Confirmed via ISM Explain API.

---

Test 2: no_alias: false

• Setup: Created a new index without alias, attached a policy with no_alias: false.
• Expected: Transition should be blocked while alias is absent.
• Action: Added alias.
• Result: Transition proceeded after alias was added.
• Validation: Confirmed via ISM Explain API.

---

Test 3: min_state_age

• Setup: Created an index and attached a policy with min_state_age: 20m.
• Expected: Transition should be blocked until the index has been in the current state for at least 20 minutes.
• Action: Checked status before and after 20-minute window.
• Result: Transition was initially blocked, and succeeded after the duration.
• Validation: Confirmed via ISM Explain API.

---

Related Issues

Resolves #1439

Check List

• New functionality includes testing.
• New functionality has been documented.
• API changes companion pull request created.
• Commits are signed per the DCO using --signoff.
• Public documentation issue/PR created.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[bowenlan-amzn]

Thanks for the contribution!
Could you fix the CI failure.

I'm a little confused if no_alias is useful. I see we have an alias action, seems the no_alias in transition is similar to an alias action before the transition. If we want to do some check on the status of index aliases, we probably can do it also in alias action.

min_state_age seems useful in certain scenario. It doesn't seem play well with min_index_age, so maybe we need to require user specify only one in a transition?

[Tarun-kishore]

While ISM provides an alias action to programmatically add or remove aliases from an index, the no_alias condition plays a fundamentally different role: it controls when a transition should happen based on whether the index is currently referenced by any alias.

In simple terms considering an example for archiving the index:

• The alias action tells ISM to remove an alias before transitioning.
• The no_alias condition tells ISM to wait and transition only after all aliases have already been removed—typically by an external system.

This distinction is essential in workflows like rollovers or index promotions, where alias updates are managed outside ISM (e.g., by ingestion pipelines). Using no_alias ensures that lifecycle transitions such as archiving or deletion occur only after the index is no longer in active use, preventing premature data removal.

Regarding concerns for having min_state_age and min_index_age at same time, ISM doesn't allow more than one condition per transition so that should not be a concern.

[bowenlan-amzn]

Makes sense. if no_alias is to work with external system.

ISM doesn't allow more than one condition per transition so that should not be a concern.

I see, this feels like a limitation (for example no_alias and min_state_age can be ANDed together), but helps simplify things here.

[Tarun-kishore]

I see, this feels like a limitation (for example no_alias and min_state_age can be ANDed together), but helps simplify things here.

Yeah, agreed — it’s feels like a limitation that conditions like no_alias and min_state_age can’t be combined directly in a single transition block. Chaining transitions sequentially keeps things simple and easier to reason about, even if it's a bit more verbose

[Tarun-kishore]

Fixed the CI builds

[Tarun-kishore]

Quick question — once this PR is merged, should the ISM docs be updated immediately or only after the next release? Just want to be sure I follow the right process.

[bowenlan-amzn]

@Tarun Kishore commented on Jul 11, 2025, 8:48 PM PDT:

Quick question — once this PR is merged, should the ISM docs be updated immediately or only after the next release? Just want to be sure I follow the right process.

I think we can specify which release in the documentation issue. And the reviewer there can take care of that

[Tarun-kishore]

I think we can specify which release in the documentation issue. And the reviewer there can take care of that

The change will be available in the next release after merging, correct?

Let me know if there are some changes needed in PR after fixing the CI builds.

[bowenlan-amzn]

Seems our bwc only runs subset of IT specifically written for bwc... otherwise I would expect failure for this new test in bwc workflow

[Tarun-kishore]

Why would this change fail bwc though, It isn't modifying any existing conditions, just adding two new conditions.

[vikasvb90]

@bowenlan-amzn is right. Test would have failed in workflow if it was written under bwc directory to validate this change. This is because during upgrade if a policy with this transition was created on a new node and an old node asked for the policies, then the entire stream would have been corrupted and there could have been serious issues. The opposite of this is also true.
Your change looks safe now after you have added version check over your fields in streams read and write methods. Even though I am not mandating but I would still vote for having a bwc test written.

[bowenlan-amzn]

@vikasvb90 Please review this PR of enhancement in ISM transition.

[vikasvb90]

Overall change looks good to me. Let me know if you plan to add a bwc test.

[Tarun-kishore]

Adding bwc test makes sense for this change, I'll add it.
I'm getting access denied error when downloading opensearch-min-2.20.0 tar for bwc test though, not sure if it's an issue with my network or some gradle issue.

[Tarun-kishore]

@vikasvb90 I've added bwc test for ISM policy.

[Tarun-kishore]

Hi @bowenlan-amzn @vikasvb90, just a quick nudge — I’ve addressed all the requested changes. Would appreciate a review when you get a chance. Thanks!

[vikasvb90]

Thanks @Tarun-kishore for adding BWC test! Approving PR. @bowenlan-amzn Can you take another pass and approve?

[bowenlan-amzn]

Nice change!

[Tarun-kishore]

Thanks @bowenlan-amzn @vikasvb90 for your feedback and review. 🙌