IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

› › ›

Actions

edit

Actions

edit

This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features.

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

Hot
- Rollover
Warm
- Allocate
- Read-Only
- Force Merge
- Shrink
Cold
- Allocate
Delete
- Delete

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.

Read more about index replicas here. Read more about shard allocation filtering in the Shard allocation filtering documentation.

Table 58. 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 59. 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
          }
        }
      }
    }
  }
}

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.

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

PUT my_index
{
  "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 60. 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.

Shrink

edit

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

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 61. 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
          }
        }
      }
    }
  }
}

« Phase Execution Full Policy »