Create or update a policy

PUT /_slm/policy/{policy_id}

Auth

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.

Required privileges

Index privileges manage
Cluster privileges manage_slm

Path parameters

policy_id string required: The identifier for the snapshot lifecycle policy you want to create or update.

Query parameters

master_timeout string · default: 30s: The 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. To indicate that the request should never timeout, set it to -1.
timeout string · default: 30s: The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to -1.

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

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

View as Markdown

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

{
  "acknowledged": false
}

Generated from the API spec

Request Console 1 / 8 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"]
  }
}

JavaScript Elasticsearch JavaScript Client

const response = await client.slm.putLifecycle({
  policy_id: "hourly-snapshots",
  schedule: "1h",
  name: "<hourly-snap-{now/d}>",
  repository: "my_repository",
  config: {
    indices: ["data-*", "important"],
  },
});

Python Elasticsearch Python Client

resp = client.slm.put_lifecycle(
    policy_id="hourly-snapshots",
    schedule="1h",
    name="<hourly-snap-{now/d}>",
    repository="my_repository",
    config={
        "indices": [
            "data-*",
            "important"
        ]
    },
)

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": "\u003Chourly-snap-{now/d}\u003E",
    "repository": "my_repository",
    "config": {
      "indices": [
        "data-*",
        "important"
      ]
    }
  }'

Java Elasticsearch Java Client

client.slm().putLifecycle(p -> p
    .config(c -> c
        .indices(List.of("data-*","important"))
    )
    .name("<hourly-snap-{now/d}>")
    .policyId("hourly-snapshots")
    .repository("my_repository")
    .schedule("1h")
);

C# Elasticsearch .NET Client

var response = await client.SnapshotLifecycleManagement
    .PutLifecycleAsync(policyId: "hourly-snapshots", d1 => d1
        .Config(d2 => d2
            .Indices(new[] { "data-*", "important" })
        )
        .Name("<hourly-snap-{now/d}>")
        .Repository("my_repository")
        .Schedule("1h")
    );

PHP Elasticsearch PHP Client

$resp = $client->slm()->putLifecycle([
    "policy_id" => "hourly-snapshots",
    "body" => [
        "schedule" => "1h",
        "name" => "<hourly-snap-{now/d}>",
        "repository" => "my_repository",
        "config" => [
            "indices" => array(
                "data-*",
                "important",
            ),
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.slm.put_lifecycle(
  policy_id: "hourly-snapshots",
  body: {
    "schedule": "1h",
    "name": "<hourly-snap-{now/d}>",
    "repository": "my_repository",
    "config": {
      "indices": [
        "data-*",
        "important"
      ]
    }
  }
)

Response

{
  "acknowledged": false
}

Generated from the API spec