The index.lifecycle.rollover_alias setting tells Elasticsearch's Index Lifecycle Management (ILM) which alias to update when an index rolls over. It is required for any alias-based rollover pattern: without it, the ILM rollover action fails with setting [index.lifecycle.rollover_alias] for index [...] is empty or not defined. The setting has no default and must be explicit on every index that participates in alias-based rollover. For greenfield time-series workloads, data streams supersede this pattern and handle rollover bookkeeping internally; the rollover_alias setting only applies to the older write-alias model.
Definition
index.lifecycle.rollover_alias is a per-index static setting (set at index creation or via index template, not dynamic). When ILM evaluates a rollover condition (max age, max size, max docs) and decides to roll over, it creates the next index in the sequence and updates the named alias to point its write target at the new index. The previous index becomes a read-only member of the alias.
Available since Elasticsearch 6.6 (when ILM was introduced).
Default and Allowed Values
| Property | Value |
|---|---|
| Default | None - must be set explicitly |
| Type | String, static (set at index creation) |
| Scope | Per index |
| Required for | ILM policies using the rollover action with alias-based rollover |
| Not required for | Data streams (data streams handle rollover internally) |
The aliased index must also have is_write_index: true for at least one underlying index when the alias spans multiple indices.
How to Set It
The standard pattern: bootstrap the first index and the alias together.
# Create the ILM policy
PUT /_ilm/policy/logs-policy
{
"policy": {
"phases": {
"hot": {
"actions": {
"rollover": { "max_primary_shard_size": "40gb", "max_age": "30d" }
}
},
"delete": {
"min_age": "90d",
"actions": { "delete": {} }
}
}
}
}
# Create the first index with the alias pointed at it as write index
PUT /logs-000001
{
"settings": {
"index.lifecycle.name": "logs-policy",
"index.lifecycle.rollover_alias": "logs"
},
"aliases": {
"logs": { "is_write_index": true }
}
}
Applications write to logs. ILM checks the policy conditions; when met, it creates logs-000002, points the logs alias's write index at the new one, and demotes logs-000001 to read-only within the alias.
Via index template, so every new alias-based rollover index inherits both settings:
PUT /_index_template/logs-template
{
"index_patterns": ["logs-*"],
"template": {
"settings": {
"index.lifecycle.name": "logs-policy",
"index.lifecycle.rollover_alias": "logs"
}
}
}
Inspect:
GET /logs-*/_settings?filter_path=*.settings.index.lifecycle.*
GET /_alias/logs
Operational Impact
The setting wires ILM's rollover action to alias updates. When it works:
- New index gets created automatically on rollover conditions.
- The alias updates atomically; application code keeps writing to
logsand notices nothing. - The old index goes through subsequent ILM phases (warm, cold, delete) on schedule.
When it is misconfigured, you typically see one of:
index name is requiredorrollover_alias is emptyerrors in the ILM explain output.- Rollover blocked because the alias does not point at the current index, or
is_write_indexis missing. - ILM stuck in
check-rollover-readystep indefinitely.
Use GET /<index>/_ilm/explain to inspect ILM status on a stuck index. It reports the current phase, action, step, and any failure.
Data Streams: The Modern Alternative
For new time-series workloads on Elasticsearch 7.9+, prefer data streams. A data stream encapsulates rollover internally: there is no explicit alias to manage, no rollover_alias setting to remember, and no is_write_index flag to keep in sync. You declare a data stream in an index template and write to the data stream name; Elasticsearch creates and rolls backing indices for you.
The rollover_alias pattern remains relevant when you have existing alias-based rollover deployed (which you cannot convert in place to a data stream without reindexing) or when the data lifecycle does not match the data-stream model.
Common Mistakes
- Setting
index.lifecycle.rollover_aliasbut no alias actually exists. ILM fails at the rollover step with a missing-alias error. - Alias name in
rollover_aliasdoes not match the alias defined in the index. They must be byte-identical. - Forgetting
is_write_index: trueon the initial index. Without it, ILM cannot identify which underlying index is the rollover target. - Setting
rollover_aliason multiple indices that share the same alias name without coordination. Only one index per alias can be the write index; settingrollover_aliason others is misleading and risks duplicate rollover attempts. - Using
rollover_aliason data stream backing indices. Not supported; data streams handle rollover internally and reject the setting.
Frequently Asked Questions
Q: What does index.lifecycle.rollover_alias do in Elasticsearch?
A: It tells ILM's rollover action which alias to update when this index rolls over. ILM creates the next index in the sequence and points the named alias's write target at the new index. The setting is required for alias-based rollover and has no default.
Q: Do I need index.lifecycle.rollover_alias for data streams?
A: No. Data streams handle rollover internally and do not use the rollover_alias setting. It applies only to the older alias-based rollover pattern. For greenfield work on 7.9+, prefer data streams.
Q: What happens if I do not set index.lifecycle.rollover_alias on an index with an ILM rollover action?
A: ILM rollover fails with an error like setting [index.lifecycle.rollover_alias] for index [...] is empty or not defined. The index gets stuck on the rollover step and does not progress through the rest of the lifecycle.
Q: Can I change index.lifecycle.rollover_alias on an existing index?
A: It is technically a dynamic setting but changing it mid-flight is risky - ILM may have already started executing a rollover against the old alias. Treat it as set-once. If the alias must change, perform a manual rollover and update the new index's settings at creation.
Q: How is index.lifecycle.rollover_alias different from a regular index alias?
A: The alias itself is created and managed via the aliases API. index.lifecycle.rollover_alias is a per-index setting that names which alias ILM should update on rollover. The two work together: the alias provides the application-facing name, and the setting tells ILM which alias to maintain.
Q: Why is my ILM rollover stuck even though rollover_alias is set?
A: Common causes: the alias does not exist, is_write_index: true is missing from the alias definition, the alias name in the setting does not match the actual alias name, or the cluster is at a shard limit and cannot create the new index. Run GET /<index>/_ilm/explain for the specific failure.
