Create or update a lifecycle policy Generally available; Added in 6.6.0

PUT /_ilm/policy/{policy}
Api key auth Basic auth Bearer auth

If the specified policy exists, it is replaced and the policy version is incremented.

NOTE: Only the latest version of the policy is stored, you cannot revert to previous versions.

Required authorization

  • Index privileges: manage
  • Cluster privileges: manage_ilm
External documentation

Path parameters

  • policy string Required

    Identifier for the policy.

Query parameters

  • master_timeout string

    Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

    Values are -1 or 0.

  • timeout string

    Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

    Values are -1 or 0.

application/json

Body

  • policy object
    Hide policy attributes Show policy attributes object
    • phases object Required
      Hide phases attributes Show phases attributes object
      • cold object
        Hide cold attributes Show cold attributes object
        • actions object
          Hide actions attributes Show actions attributes object
          • allocate object
            Hide allocate attributes Show allocate attributes object
            • number_of_replicas number
            • total_shards_per_node number
            • include object
              Hide include attribute Show include attribute object
              • * string Additional properties
            • exclude object
              Hide exclude attribute Show exclude attribute object
              • * string Additional properties
            • require object
              Hide require attribute Show require attribute object
              • * string Additional properties
          • delete object
            Hide delete attribute Show delete attribute object
            • delete_searchable_snapshot boolean
          • downsample object
            Hide downsample attributes Show downsample attributes object
            • fixed_interval string Required

              A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)

            • wait_timeout string

              A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

          • freeze object

            For empty Class assignments

          • forcemerge object
            Hide forcemerge attributes Show forcemerge attributes object
            • max_num_segments number Required
            • index_codec string
          • migrate object
            Hide migrate attribute Show migrate attribute object
            • enabled boolean
          • readonly object

            For empty Class assignments

          • rollover object
            Hide rollover attributes Show rollover attributes object

            • max_size number | string

              One of:
              number-1 number string-2 string

            • max_primary_shard_size number | string

              One of:
              number-1 number string-2 string
            • max_age string

              A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

            • max_docs number
            • max_primary_shard_docs number

            • min_size number | string

              One of:
              number-1 number string-2 string

            • min_primary_shard_size number | string

              One of:
              number-1 number string-2 string
            • min_age string

              A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

            • min_docs number
            • min_primary_shard_docs number
          • set_priority object
            Hide set_priority attribute Show set_priority attribute object
            • priority number
          • searchable_snapshot object
            Hide searchable_snapshot attributes Show searchable_snapshot attributes object
            • snapshot_repository string Required
            • force_merge_index boolean
          • shrink object
            Hide shrink attributes Show shrink attributes object
          • unfollow object

            For empty Class assignments

          • wait_for_snapshot object
            Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
            • policy string Required
        • min_age string

          A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

      • delete object
        Hide delete attributes Show delete attributes object
        • actions object
          Hide actions attributes Show actions attributes object
          • allocate object
            Hide allocate attributes Show allocate attributes object
            • number_of_replicas number
            • total_shards_per_node number
            • include object
              Hide include attribute Show include attribute object
              • * string Additional properties
            • exclude object
              Hide exclude attribute Show exclude attribute object
              • * string Additional properties
            • require object
              Hide require attribute Show require attribute object
              • * string Additional properties
          • delete object
            Hide delete attribute Show delete attribute object
            • delete_searchable_snapshot boolean
          • downsample object
            Hide downsample attributes Show downsample attributes object
            • fixed_interval string Required

              A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)

            • wait_timeout string

              A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

          • freeze object

            For empty Class assignments

          • forcemerge object
            Hide forcemerge attributes Show forcemerge attributes object
            • max_num_segments number Required
            • index_codec string
          • migrate object
            Hide migrate attribute Show migrate attribute object
            • enabled boolean
          • readonly object

            For empty Class assignments

          • rollover object
            Hide rollover attributes Show rollover attributes object

            • max_size number | string

              One of:
              number-1 number string-2 string

            • max_primary_shard_size number | string

              One of:
              number-1 number string-2 string
            • max_age string

              A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

            • max_docs number
            • max_primary_shard_docs number

            • min_size number | string

              One of:
              number-1 number string-2 string

            • min_primary_shard_size number | string

              One of:
              number-1 number string-2 string
            • min_age string

              A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

            • min_docs number
            • min_primary_shard_docs number
          • set_priority object
            Hide set_priority attribute Show set_priority attribute object
            • priority number
          • searchable_snapshot object
            Hide searchable_snapshot attributes Show searchable_snapshot attributes object
            • snapshot_repository string Required
            • force_merge_index boolean
          • shrink object
            Hide shrink attributes Show shrink attributes object
          • unfollow object

            For empty Class assignments

          • wait_for_snapshot object
            Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
            • policy string Required
        • min_age string

          A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

      • frozen object
        Hide frozen attributes Show frozen attributes object
        • actions object
          Hide actions attributes Show actions attributes object
          • allocate object
            Hide allocate attributes Show allocate attributes object
            • number_of_replicas number
            • total_shards_per_node number
            • include object
              Hide include attribute Show include attribute object
              • * string Additional properties
            • exclude object
              Hide exclude attribute Show exclude attribute object
              • * string Additional properties
            • require object
              Hide require attribute Show require attribute object
              • * string Additional properties
          • delete object
            Hide delete attribute Show delete attribute object
            • delete_searchable_snapshot boolean
          • downsample object
            Hide downsample attributes Show downsample attributes object
            • fixed_interval string Required

              A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)

            • wait_timeout string

              A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

          • freeze object

            For empty Class assignments

          • forcemerge object
            Hide forcemerge attributes Show forcemerge attributes object
            • max_num_segments number Required
            • index_codec string
          • migrate object
            Hide migrate attribute Show migrate attribute object
            • enabled boolean
          • readonly object

            For empty Class assignments

          • rollover object
            Hide rollover attributes Show rollover attributes object

            • max_size number | string

              One of:
              number-1 number string-2 string

            • max_primary_shard_size number | string

              One of:
              number-1 number string-2 string
            • max_age string

              A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

            • max_docs number
            • max_primary_shard_docs number

            • min_size number | string

              One of:
              number-1 number string-2 string

            • min_primary_shard_size number | string

              One of:
              number-1 number string-2 string
            • min_age string

              A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

            • min_docs number
            • min_primary_shard_docs number
          • set_priority object
            Hide set_priority attribute Show set_priority attribute object
            • priority number
          • searchable_snapshot object
            Hide searchable_snapshot attributes Show searchable_snapshot attributes object
            • snapshot_repository string Required
            • force_merge_index boolean
          • shrink object
            Hide shrink attributes Show shrink attributes object
          • unfollow object

            For empty Class assignments

          • wait_for_snapshot object
            Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
            • policy string Required
        • min_age string

          A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

      • hot object
        Hide hot attributes Show hot attributes object
        • actions object
          Hide actions attributes Show actions attributes object
          • allocate object
            Hide allocate attributes Show allocate attributes object
            • number_of_replicas number
            • total_shards_per_node number
            • include object
              Hide include attribute Show include attribute object
              • * string Additional properties
            • exclude object
              Hide exclude attribute Show exclude attribute object
              • * string Additional properties
            • require object
              Hide require attribute Show require attribute object
              • * string Additional properties
          • delete object
            Hide delete attribute Show delete attribute object
            • delete_searchable_snapshot boolean
          • downsample object
            Hide downsample attributes Show downsample attributes object
            • fixed_interval string Required

              A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)

            • wait_timeout string

              A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

          • freeze object

            For empty Class assignments

          • forcemerge object
            Hide forcemerge attributes Show forcemerge attributes object
            • max_num_segments number Required
            • index_codec string
          • migrate object
            Hide migrate attribute Show migrate attribute object
            • enabled boolean
          • readonly object

            For empty Class assignments

          • rollover object
            Hide rollover attributes Show rollover attributes object

            • max_size number | string

              One of:
              number-1 number string-2 string

            • max_primary_shard_size number | string

              One of:
              number-1 number string-2 string
            • max_age string

              A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

            • max_docs number
            • max_primary_shard_docs number

            • min_size number | string

              One of:
              number-1 number string-2 string

            • min_primary_shard_size number | string

              One of:
              number-1 number string-2 string
            • min_age string

              A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

            • min_docs number
            • min_primary_shard_docs number
          • set_priority object
            Hide set_priority attribute Show set_priority attribute object
            • priority number
          • searchable_snapshot object
            Hide searchable_snapshot attributes Show searchable_snapshot attributes object
            • snapshot_repository string Required
            • force_merge_index boolean
          • shrink object
            Hide shrink attributes Show shrink attributes object
          • unfollow object

            For empty Class assignments

          • wait_for_snapshot object
            Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
            • policy string Required
        • min_age string

          A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

      • warm object
        Hide warm attributes Show warm attributes object
        • actions object
          Hide actions attributes Show actions attributes object
          • allocate object
            Hide allocate attributes Show allocate attributes object
            • number_of_replicas number
            • total_shards_per_node number
            • include object
              Hide include attribute Show include attribute object
              • * string Additional properties
            • exclude object
              Hide exclude attribute Show exclude attribute object
              • * string Additional properties
            • require object
              Hide require attribute Show require attribute object
              • * string Additional properties
          • delete object
            Hide delete attribute Show delete attribute object
            • delete_searchable_snapshot boolean
          • downsample object
            Hide downsample attributes Show downsample attributes object
            • fixed_interval string Required

              A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)

            • wait_timeout string

              A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

          • freeze object

            For empty Class assignments

          • forcemerge object
            Hide forcemerge attributes Show forcemerge attributes object
            • max_num_segments number Required
            • index_codec string
          • migrate object
            Hide migrate attribute Show migrate attribute object
            • enabled boolean
          • readonly object

            For empty Class assignments

          • rollover object
            Hide rollover attributes Show rollover attributes object

            • max_size number | string

              One of:
              number-1 number string-2 string

            • max_primary_shard_size number | string

              One of:
              number-1 number string-2 string
            • max_age string

              A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

            • max_docs number
            • max_primary_shard_docs number

            • min_size number | string

              One of:
              number-1 number string-2 string

            • min_primary_shard_size number | string

              One of:
              number-1 number string-2 string
            • min_age string

              A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

            • min_docs number
            • min_primary_shard_docs number
          • set_priority object
            Hide set_priority attribute Show set_priority attribute object
            • priority number
          • searchable_snapshot object
            Hide searchable_snapshot attributes Show searchable_snapshot attributes object
            • snapshot_repository string Required
            • force_merge_index boolean
          • shrink object
            Hide shrink attributes Show shrink attributes object
          • unfollow object

            For empty Class assignments

          • wait_for_snapshot object
            Hide wait_for_snapshot attribute Show wait_for_snapshot attribute object
            • policy string Required
        • min_age string

          A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

    • _meta object
      Hide _meta attribute Show _meta attribute object
      • * object Additional properties

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • acknowledged boolean Required

      For a successful response, this value is always true. On failure, an exception is returned instead.
PUT /_ilm/policy/{policy} 
PUT _ilm/policy/my_policy { "policy": { "_meta": { "description": "used for nginx log", "project": { "name": "myProject", "department": "myDepartment" } }, "phases": { "warm": { "min_age": "10d", "actions": { "forcemerge": { "max_num_segments": 1 } } }, "delete": { "min_age": "30d", "actions": { "delete": {} } } } } }
resp = client.ilm.put_lifecycle( name="my_policy", policy={ "_meta": { "description": "used for nginx log", "project": { "name": "myProject", "department": "myDepartment" } }, "phases": { "warm": { "min_age": "10d", "actions": { "forcemerge": { "max_num_segments": 1 } } }, "delete": { "min_age": "30d", "actions": { "delete": {} } } } }, )
const response = await client.ilm.putLifecycle({ name: "my_policy", policy: { _meta: { description: "used for nginx log", project: { name: "myProject", department: "myDepartment", }, }, phases: { warm: { min_age: "10d", actions: { forcemerge: { max_num_segments: 1, }, }, }, delete: { min_age: "30d", actions: { delete: {}, }, }, }, }, });
response = client.ilm.put_lifecycle( policy: "my_policy", body: { "policy": { "_meta": { "description": "used for nginx log", "project": { "name": "myProject", "department": "myDepartment" } }, "phases": { "warm": { "min_age": "10d", "actions": { "forcemerge": { "max_num_segments": 1 } } }, "delete": { "min_age": "30d", "actions": { "delete": {} } } } } } )
$resp = $client->ilm()->putLifecycle([ "policy" => "my_policy", "body" => [ "policy" => [ "_meta" => [ "description" => "used for nginx log", "project" => [ "name" => "myProject", "department" => "myDepartment", ], ], "phases" => [ "warm" => [ "min_age" => "10d", "actions" => [ "forcemerge" => [ "max_num_segments" => 1, ], ], ], "delete" => [ "min_age" => "30d", "actions" => [ "delete" => new ArrayObject([]), ], ], ], ], ], ]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"policy":{"_meta":{"description":"used for nginx log","project":{"name":"myProject","department":"myDepartment"}},"phases":{"warm":{"min_age":"10d","actions":{"forcemerge":{"max_num_segments":1}}},"delete":{"min_age":"30d","actions":{"delete":{}}}}}}' "$ELASTICSEARCH_URL/_ilm/policy/my_policy"
client.ilm().putLifecycle(p -> p .name("my_policy") .policy(po -> po .phases(ph -> ph .delete(d -> d .actions(a -> a .delete(de -> de) ) .minAge(m -> m .time("30d") ) ) .warm(w -> w .actions(a -> a .forcemerge(f -> f .maxNumSegments(1) ) ) .minAge(m -> m .time("10d") ) ) ) .meta(Map.of("description", JsonData.fromJson("\"used for nginx log\""),"project", JsonData.fromJson("{\"name\":\"myProject\",\"department\":\"myDepartment\"}"))) ) );
Request example
Run `PUT _ilm/policy/my_policy` to create a new policy with arbitrary metadata. 
{ "policy": { "_meta": { "description": "used for nginx log", "project": { "name": "myProject", "department": "myDepartment" } }, "phases": { "warm": { "min_age": "10d", "actions": { "forcemerge": { "max_num_segments": 1 } } }, "delete": { "min_age": "30d", "actions": { "delete": {} } } } } }
Response examples (200)
A successful response when creating a new lifecycle policy. 
{ "acknowledged": true }