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.

    External documentation
  • timeout string

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

    External documentation
application/json

Body

  • policy object
    Hide policy attributes Show policy attributes object
    • phases object Required
      Hide phases attributes Show phases attributes object
      • cold object
      • delete object
      • frozen object
      • hot object
      • warm object
    • _meta object

      Arbitrary metadata that is not automatically generated or used by Elasticsearch.

      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 }