Actions

edit

The below list shows the actions which are available in each phase.

The order that configured actions are performed in within each phase is determined automatically by ILM, and cannot be changed by changing the policy definition.

Allocate

edit

Phases allowed: warm, cold.

The Allocate action allows you to specify which nodes are allowed to host the shards of the index and set the number of replicas. Behind the scenes, it is modifying the index settings for shard filtering and/or replica counts. When updating the number of replicas, configuring allocation rules is optional. When configuring allocation rules, setting number of replicas is optional. Although this action can be treated as two separate index settings updates, both can be configured at once.

For more information about how Elasticsearch uses replicas for scaling, see Scalability and resilience. See Index-level shard allocation filtering for more information about controlling where Elasticsearch allocates shards of a particular index.

Note: As allocate action is not allowed in hot phase, the initial allocation for the index should be done manually or via index templates, as ILM won’t take care of index allocation during hot phase.

Table 66. Allocate Options

Name Required Default Description

number_of_replicas

no

-

The number of replicas to assign to the index

include

no

-

assigns an index to nodes having at least one of the attributes

exclude

no

-

assigns an index to nodes having none of the attributes

require

no

-

assigns an index to nodes having all of the attributes

If number_of_replicas is not configured, then at least one of include, exclude, and require is required. An empty Allocate Action with no configuration is invalid.

Example: Change number of replicas

edit

In this example, the index’s number of replicas is changed to 2, while allocation rules are unchanged.

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "warm": {
        "actions": {
          "allocate" : {
            "number_of_replicas" : 2
          }
        }
      }
    }
  }
}

Example: Assign index to node with specific "box_type" attribute

edit

This example assigns the index to nodes with box_type attribute of "hot" or "warm".

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "warm": {
        "actions": {
          "allocate" : {
            "include" : {
              "box_type": "hot,warm"
            }
          }
        }
      }
    }
  }
}

Example: Assign index to a specific node and update replica settings

edit

This example updates the index to have one replica per shard and be allocated to nodes with a box_type attribute of "cold".

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "warm": {
        "actions": {
          "allocate" : {
            "number_of_replicas": 1,
            "require" : {
              "box_type": "cold"
            }
        }
        }
      }
    }
  }
}

Delete

edit

Phases allowed: delete.

The Delete Action does just that, it deletes the index.

This action does not have any options associated with it.

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "delete": {
        "actions": {
          "delete" : { }
        }
      }
    }
  }
}

Force Merge

edit

Phases allowed: warm.

Index will be be made read-only when this action is run (see: index.blocks.write)

The Force Merge Action force merges the index into at most a specific number of segments.

Table 67. Force Merge Options

Name Required Default Description

max_num_segments

yes

-

The number of segments to merge to. To fully merge the index, set it to 1

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "warm": {
        "actions": {
          "forcemerge" : {
            "max_num_segments": 1
          }
        }
      }
    }
  }
}

Freeze

edit

Phases allowed: cold.

This action will freeze the index by calling the Freeze Index API.

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "cold": {
        "actions": {
          "freeze" : { }
        }
      }
    }
  }
}
Freezing an index will close the index and reopen it within the same API call.
This causes primaries to not be allocated for a short amount of time and
causes the cluster to go red until the primaries are allocated again.
This limitation might be removed in the future.

Read-Only

edit

Phases allowed: warm.

This action will set the index to be read-only (see: index.blocks.write)

This action does not have any options associated with it.

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "warm": {
        "actions": {
          "readonly" : { }
        }
      }
    }
  }
}

Rollover

edit

Phases allowed: hot.

index format must match pattern ^.*-\\d+$, for example (logs-000001).

The managed index must set index.lifecycle.rollover_alias as the alias to rollover. The index must also be the write index for the alias.

If a policy using the Rollover action is used on a follower index, policy execution will wait until the leader index rolls over (or has otherwise been marked as complete), then convert the follower index into a regular index as if the Unfollow action had been used instead of rolling over.

For example, if an index to be managed has an alias my_data. The managed index "my_index-000001" must be the write index for the alias. For more information, read Write Index Alias Behavior.

PUT my_index-000001
{
  "settings": {
    "index.lifecycle.name": "my_policy",
    "index.lifecycle.rollover_alias": "my_data"
  },
  "aliases": {
    "my_data": {
      "is_write_index": true
    }
  }
}

The Rollover Action rolls an alias over to a new index when the existing index meets one of the rollover conditions.

Table 68. Rollover Options

Name Required Default Description

max_size

no

-

max primary shard index storage size. See Byte Units for formatting

max_docs

no

-

max number of documents an index is to contain before rolling over.

max_age

no

-

max time elapsed from index creation. See Time Units for formatting

At least one of max_size, max_docs, max_age or any combinations of the three are required to be specified.

Example: Rollover when index is too large

edit

This example rolls the index over when it is at least 100 gigabytes.

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "hot": {
        "actions": {
          "rollover" : {
            "max_size": "100GB"
          }
        }
      }
    }
  }
}

Example: Rollover when index has too many documents

edit

This example rolls the index over when it contains at least 100000000 documents.

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "hot": {
        "actions": {
          "rollover" : {
            "max_docs": 100000000
          }
        }
      }
    }
  }
}

Example: Rollover when index is too old

edit

This example rolls the index over when it has been created at least 7 days ago.

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "hot": {
        "actions": {
          "rollover" : {
            "max_age": "7d"
          }
        }
      }
    }
  }
}

Example: Rollover when index is too old or too large

edit

This example rolls the index over when it has been created at least 7 days ago or it is at least 100 gigabytes. In this case, the index will be rolled over when any of the conditions is met.

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "hot": {
        "actions": {
          "rollover" : {
            "max_age": "7d",
            "max_size": "100GB"
          }
        }
      }
    }
  }
}

Example: Rollover condition stalls phase transition

edit

The Rollover action will only complete once one of its conditions is met. This means that any proceeding phases will be blocked until Rollover succeeds.

PUT /_ilm/policy/rollover_policy
{
  "policy": {
    "phases": {
      "hot": {
        "actions": {
          "rollover": {
            "max_size": "50G"
          }
        }
      },
      "delete": {
        "min_age": "1d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}

The above example illustrates a policy which attempts to delete an index one day after the index has been rolled over. It does not delete the index one day after it has been created.

Set Priority

edit

Phases allowed: hot, warm, cold.

This action sets the index priority on the index as soon as the policy enters the hot, warm, or cold phase. Indices with a higher priority will be recovered before indices with lower priorities following a node restart. Generally, indexes in the hot phase should have the highest value and indexes in the cold phase should have the lowest values. For example: 100 for the hot phase, 50 for the warm phase, and 0 for the cold phase. Indicies that don’t set this value have an implicit default priority of 1.

Table 69. Set Priority Options

Name Required Default Description

priority

yes

-

The priority for the index. Must be 0 or greater. The value may also be set to null to remove the priority.

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "warm": {
        "actions": {
          "set_priority" : {
            "priority": 50
          }
        }
      }
    }
  }
}

Shrink

edit

Index will be be made read-only when this action is run (see: index.blocks.write)

If a policy using the Shrink action is used on a follower index, policy execution will wait until the leader index rolls over (or has otherwise been marked as complete), then convert the follower index into a regular index as if the Unfollow action had been used before shrink is applied, as shrink cannot be safely applied to follower indices.

This action shrinks an existing index into a new index with fewer primary shards. It calls the Shrink API to shrink the index. Since allocating all the primary shards of the index to one node is a prerequisite, this action will first allocate the primary shards to a valid node. After shrinking, it will swap aliases pointing to the original index into the new shrunken index. The new index will also have a new name: "shrink-<origin-index-name>". So if the original index was called "logs", then the new index will be named "shrink-logs".

Table 70. Shrink Options

Name Required Default Description

number_of_shards

yes

-

The number of shards to shrink to. must be a factor of the number of shards in the source index.

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "warm": {
        "actions": {
          "shrink" : {
            "number_of_shards": 1
          }
        }
      }
    }
  }
}

Unfollow

edit

This action may be used explicitly, as shown below, but this action is also run before the Rollover action and the Shrink action as described in the documentation for those actions.

This action turns a ccr follower index into a regular index. This can be desired when moving follower indices into the next phase. Also certain actions like shrink and rollover can then be performed safely on follower indices.

This action will wait until is it safe to convert a follower index into a regular index. In particular, the following conditions must be met:

  • The leader index must have index.lifecycle.indexing_complete set to true. This happens automatically if the leader index is rolled over using the Rollover action, or may be set manually using the Index Settings API.
  • All operations performed on the leader index must have been replicated to the follower index. This ensures that no operations will be lost when the index is converted into a regular index.

If the unfollow action encounters a follower index then the following operations will be performed on it:

  • Pauses indexing following for the follower index.
  • Closes the follower index.
  • Unfollows the follower index.
  • Opens the follower index (which is at this point is a regular index).

The unfollow action does not have any options and if it encounters a non follower index, then the unfollow action leaves that index untouched and lets the next action operate on this index.

PUT _ilm/policy/my_policy
{
  "policy": {
    "phases": {
      "hot": {
        "actions": {
          "unfollow" : {}
        }
      }
    }
  }
}