Create or update a policy

PUT /_slm/policy/{policy_id}

Create or update a snapshot lifecycle policy. If the policy already exists, this request increments the policy version. Only the latest version of a policy is stored.

Authentication

Api key

Authorization: <value>

Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:

		curl -X GET "${ES_URL}/_cat/indices?v=true" \
  -H "Authorization: ApiKey ${API_KEY}"

To get API keys, use the /_security/api_key APIs.

Basic

Authorization: Basic <credentials>

Bearer

Authorization: Bearer <token>

Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API. For examples, refer to Token-based authentication services

Request body

config object: Configuration for each snapshot created by the policy.
name string: Name automatically assigned to each snapshot created by the policy. Date math is supported. To prevent conflicting snapshot names, a UUID is automatically appended to each snapshot name.
repository string: Repository used to store snapshots created by this policy. This repository must exist prior to the policy’s creation. You can create a repository using the snapshot repository API.
retention object: Retention rules used to retain and delete snapshots created by the policy.
schedule string: Periodic or absolute schedule at which the policy creates snapshots. SLM applies schedule changes immediately.

Response

application/json

Examples

Request Console 1 / 8 languages

Run PUT /_slm/policy/daily-snapshots to create a lifecycle policy. The schedule is when the snapshot should be taken, in this case, 1:30am daily. The retention details specify to: keep snapshots for 30 days; always keep at least 5 successful snapshots, even if they're more than 30 days old; keep no more than 50 successful snapshots, even if they're less than 30 days old.

Console Kibana Dev Tools

PUT /_slm/policy/daily-snapshots
{
  "schedule": "0 30 1 * * ?",
  "name": "<daily-snap-{now/d}>",
  "repository": "my_repository",
  "config": {
    "indices": ["data-*", "important"],
    "ignore_unavailable": false,
    "include_global_state": false
  },
  "retention": {
    "expire_after": "30d",
    "min_count": 5,
    "max_count": 50
  }
}

JavaScript Elasticsearch JavaScript Client

const response = await client.slm.putLifecycle({
  policy_id: "daily-snapshots",
  schedule: "0 30 1 * * ?",
  name: "<daily-snap-{now/d}>",
  repository: "my_repository",
  config: {
    indices: ["data-*", "important"],
    ignore_unavailable: false,
    include_global_state: false,
  },
  retention: {
    expire_after: "30d",
    min_count: 5,
    max_count: 50,
  },
});

Python Elasticsearch Python Client

resp = client.slm.put_lifecycle(
    policy_id="daily-snapshots",
    schedule="0 30 1 * * ?",
    name="<daily-snap-{now/d}>",
    repository="my_repository",
    config={
        "indices": [
            "data-*",
            "important"
        ],
        "ignore_unavailable": False,
        "include_global_state": False
    },
    retention={
        "expire_after": "30d",
        "min_count": 5,
        "max_count": 50
    },
)

curl Shell

curl -X PUT "$ELASTICSEARCH_URL/_slm/policy/daily-snapshots" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "0 30 1 * * ?",
    "name": "\u003Cdaily-snap-{now/d}\u003E",
    "repository": "my_repository",
    "config": {
      "indices": [
        "data-*",
        "important"
      ],
      "ignore_unavailable": false,
      "include_global_state": false
    },
    "retention": {
      "expire_after": "30d",
      "min_count": 5,
      "max_count": 50
    }
  }'

Java Elasticsearch Java Client

client.slm().putLifecycle(p -> p
    .config(c -> c
        .ignoreUnavailable(false)
        .indices(List.of("data-*","important"))
        .includeGlobalState(false)
    )
    .name("<daily-snap-{now/d}>")
    .policyId("daily-snapshots")
    .repository("my_repository")
    .retention(r -> r
        .expireAfter(e -> e
            .time("30d")
        )
        .maxCount(50)
        .minCount(5)
    )
    .schedule("0 30 1 * * ?")
);

C# Elasticsearch .NET Client

var response = await client.SnapshotLifecycleManagement
    .PutLifecycleAsync(policyId: "daily-snapshots", d1 => d1
        .Config(d2 => d2
            .IgnoreUnavailable(false)
            .IncludeGlobalState(false)
            .Indices(new[] { "data-*", "important" })
        )
        .Name("<daily-snap-{now/d}>")
        .Repository("my_repository")
        .Retention(d2 => d2
            .ExpireAfter("30d")
            .MaxCount(50)
            .MinCount(5)
        )
        .Schedule("0 30 1 * * ?")
    );

PHP Elasticsearch PHP Client

$resp = $client->slm()->putLifecycle([
    "policy_id" => "daily-snapshots",
    "body" => [
        "schedule" => "0 30 1 * * ?",
        "name" => "<daily-snap-{now/d}>",
        "repository" => "my_repository",
        "config" => [
            "indices" => array(
                "data-*",
                "important",
            ),
            "ignore_unavailable" => false,
            "include_global_state" => false,
        ],
        "retention" => [
            "expire_after" => "30d",
            "min_count" => 5,
            "max_count" => 50,
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.slm.put_lifecycle(
  policy_id: "daily-snapshots",
  body: {
    "schedule": "0 30 1 * * ?",
    "name": "<daily-snap-{now/d}>",
    "repository": "my_repository",
    "config": {
      "indices": [
        "data-*",
        "important"
      ],
      "ignore_unavailable": false,
      "include_global_state": false
    },
    "retention": {
      "expire_after": "30d",
      "min_count": 5,
      "max_count": 50
    }
  }
)

Response

No example

Request Console 1 / 2 languages

Run PUT /_slm/policy/hourly-snapshots to create a lifecycle policy that uses interval scheduling. It creates a snapshot once every hour. The first snapshot will be created one hour after the policy is modified, with subsequent snapshots every hour afterward.

Console Kibana Dev Tools

PUT /_slm/policy/hourly-snapshots
{
  "schedule": "1h",
  "name": "<hourly-snap-{now/d}>",
  "repository": "my_repository",
  "config": {
    "indices": ["data-*", "important"]
  }
}

Generated from the API spec

curl Shell

curl -X PUT "$ELASTICSEARCH_URL/_slm/policy/hourly-snapshots" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "1h",
    "name": "<hourly-snap-{now/d}>",
    "repository": "my_repository",
    "config": {
      "indices": ["data-*", "important"]
    }
  }'

Generated from the API spec

Response

No example

Create or update a policy

Required authorization

Authentication

Path parameters

Query parameters

Request body

Response

Required authorization

Authentication

Path parameters

Query parameters

Request body { }

Response

Request body