Configure Elasticsearch ILM Rollover for Time‑Based Indices

How ILM Rollover Works

Index Lifecycle Management (ILM) rollover automatically creates a new write index when the current index reaches a size, age, or document‑count threshold. The write alias always points to the newest index, so indexing traffic continues without interruption while older indices become read‑only and can be subject to downstream phases (e.g., shrink, delete). This keeps the hot shard set small and enables predictable retention policies.

Example Configuration

The following steps illustrate a minimal rollover setup for a time‑based index pattern logs-. Adjust the placeholder values to match your cluster.

1. Define an ILM policy that specifies a hot phase with rollover conditions.

PUT _ilm/policy/logs_rollover_policy
{
  "policy": {
    "phases": {
      "hot": {
        "actions": {
          "rollover": {
            "max_size": "50gb",
            "max_age": "30d"
          }
        }
      },
      "delete": {
        "min_age": "90d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}

1. Create an index template that applies the policy and sets the index name pattern.

PUT _index_template/logs_template
{
  "index_patterns": ["logs-*"],
  "template": {
    "settings": {
      "number_of_shards": 1,
      "number_of_replicas": 1,
      "index.lifecycle.name": "logs_rollover_policy",
      "index.lifecycle.rollover_alias": "logs_write"
    }
  }
}

1. Bootstrap the first index under the write alias. The initial index must match the rollover pattern and be indexed under the alias.

PUT logs-000001
{
  "aliases": {
    "logs_write": {
      "is_write_index": true
    }
  }
}

After the above, Elasticsearch will manage the logs_write alias. When logs-000001 exceeds 50 GB or 30 days, a rollover occurs, creating logs-000002 and moving the alias to point there.

Limits and Considerations

• Rollover only works on indices that are managed by a write alias with is_write_index set to true.
• The policy cannot change the number of shards of an existing index; shard count is fixed at index creation.
• Excessively frequent rollover (e.g., every few minutes) can lead to shard explosion and increased cluster metadata load, degrading performance.
• ILM does not automatically shrink or force‑merge indices; those actions must be added as separate phases if desired.

Common Mistakes

• Failing to set is_write_index": true on the initial index causes the first rollover to fail with a "write index not found" error.
• Using illegal characters (e.g., colons, commas) in the index name pattern breaks the rollover naming convention.
• Manually creating an index that matches the pattern but not attaching it to the write alias leads to policy mismatches and orphaned indices.
• Assuming the rollover will change the shard count of the existing index; the new index inherits the template’s shard setting, not the old one’s.

Verification Steps

1. Check the policy definition: GET _ilm/policy/logs_rollover_policy
2. Confirm the write alias points to the current index: GET logs_write/_alias
3. Watch for a new index after a threshold is met: GET _cat/indices/logs-*?v&s=index will show indices like logs-000001, logs-000002, etc.
4. Monitor shard count per node to ensure rollover frequency is not creating too many small shards: GET _cat/shards?v&h=index,shard,prirep,state,store,node