Create or update a lifecycle policy

PUT /_ilm/policy/{policy}

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.

Read the reference documentation

Required privileges

Index privileges manage
Cluster privileges manage_ilm

Path parameters

policy string required: Identifier for the policy.

Query parameters

master_timeout string · default: 30s: 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.
timeout string · default: 30s: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Request body

policy object

Response

application/json

acknowledged boolean required: For a successful response, this value is always true. On failure, an exception is returned instead.

Examples

Request Console 1 / 8 languages

Run PUT _ilm/policy/my_policy to create a new policy with arbitrary metadata.

Console Kibana Dev Tools

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": {}
        }
      }
    }
  }
}

JavaScript Elasticsearch JavaScript Client

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: {},
        },
      },
    },
  },
});

Python Elasticsearch Python Client

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": {}
                }
            }
        }
    },
)

curl Shell

curl -X PUT "$ELASTICSEARCH_URL/_ilm/policy/my_policy" \
  -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": {}
          }
        }
      }
    }
  }'

Java Elasticsearch Java Client

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\"}")))
    )
);

C# Elasticsearch .NET Client

var response = await client.IndexLifecycleManagement
    .PutLifecycleAsync(name: "my_policy", d1 => d1
        .Policy(d2 => d2
            .Meta(new Dictionary<string, object>()
            {
                { "description", "used for nginx log" },
                { "project", JsonSerializer.Deserialize<JsonElement>("""
                {
                  "name": "myProject",
                  "department": "myDepartment"
                }
                """) }
            })
            .Phases(d3 => d3
                .Delete(d4 => d4
                    .Actions(d5 => d5
                        .Delete()
                    )
                    .MinAge("30d")
                )
                .Warm(d4 => d4
                    .Actions(d5 => d5
                        .Forcemerge(d6 => d6
                            .MaxNumSegments(1)
                        )
                    )
                    .MinAge("10d")
                )
            )
        )
    );

PHP Elasticsearch PHP Client

$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([]),
                    ],
                ],
            ],
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

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": {}
          }
        }
      }
    }
  }
)

Response

A successful response when creating a new lifecycle policy.

{
  "acknowledged": true
}