823 lines
27 KiB
Plaintext
823 lines
27 KiB
Plaintext
[role="xpack"]
|
|
[testenv="basic"]
|
|
[[snapshot-lifecycle-management-api]]
|
|
== Snapshot lifecycle management API
|
|
|
|
The Snapshot Lifecycle Management APIs are used to manage policies for the time
|
|
and frequency of automatic snapshots. Snapshot Lifecycle Management is related
|
|
to <<index-lifecycle-management,Index Lifecycle Management>>, however, instead
|
|
of managing a lifecycle of actions that are performed on a single index, SLM
|
|
allows configuring policies spanning multiple indices. Snapshot Lifecycle
|
|
Management can also perform deletion of older snapshots based on a configurable
|
|
retention policy.
|
|
|
|
SLM policy management is split into three different CRUD APIs, a way to put or update
|
|
policies, a way to retrieve policies, and a way to delete unwanted policies, as
|
|
well as a separate API for immediately invoking a snapshot based on a policy.
|
|
|
|
SLM can be stopped temporarily and restarted using the <<slm-stop,Stop SLM>> and
|
|
<<slm-start,Start SLM>> APIs. To disable SLM's functionality entirely, set the
|
|
cluster setting `xpack.slm.enabled` to `false` in elasticsearch.yml.
|
|
|
|
[[slm-api-put]]
|
|
=== Put snapshot lifecycle policy API
|
|
++++
|
|
<titleabbrev>Put snapshot lifecycle policy</titleabbrev>
|
|
++++
|
|
|
|
Creates or updates a snapshot lifecycle policy.
|
|
|
|
|
|
[[slm-api-put-request]]
|
|
==== {api-request-title}
|
|
|
|
`PUT /_slm/policy/<snapshot-lifecycle-policy-id>`
|
|
|
|
|
|
[[slm-api-put-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
If you use {es} {security-features},
|
|
you must have:
|
|
|
|
* `manage_slm` <<privileges-list-cluster,cluster privileges>>
|
|
* `manage` <<privileges-list-indices,index privileges>> for any included indices
|
|
|
|
{slm-cap} operations are executed
|
|
as the user that last created or updated the policy.
|
|
|
|
For more information,
|
|
see <<security-privileges>>.
|
|
|
|
|
|
[[slm-api-put-desc]]
|
|
==== {api-description-title}
|
|
|
|
Use the put snapshot lifecycle policy API
|
|
to create or update a snapshot lifecycle policy.
|
|
|
|
If the policy already exists,
|
|
this request increments the policy's version.
|
|
Only the latest version of the policy is stored.
|
|
|
|
|
|
|
|
[[slm-api-put-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<snapshot-lifecycle-policy-id>`::
|
|
(Required, string)
|
|
ID for the snapshot lifecycle policy
|
|
you want to create or update.
|
|
|
|
|
|
[[slm-api-put-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
|
|
|
|
|
|
[[slm-api-put-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
`schedule`::
|
|
(Required, <<schedule-cron,Cron scheduler configuration>>)
|
|
Periodic or absolute schedule
|
|
at which the policy creates snapshots
|
|
and deletes expired snapshots.
|
|
+
|
|
Schedule changes to existing policies
|
|
are applied immediately.
|
|
|
|
`name`::
|
|
+
|
|
--
|
|
(Required, string)
|
|
Name automatically assigned to each snapshot
|
|
created by the policy.
|
|
|
|
This value supports the same <<date-math-index-names,date math>>
|
|
supported in index names.
|
|
|
|
To prevent conflicting snapshot names,
|
|
a UUID is automatically appended to each snapshot name.
|
|
--
|
|
|
|
`repository`::
|
|
+
|
|
--
|
|
(Required, 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 <<modules-snapshots,snapshot repository API>>.
|
|
--
|
|
|
|
`config`::
|
|
+
|
|
--
|
|
(Required, object)
|
|
Configuration for each snapshot
|
|
created by the policy.
|
|
|
|
Parameters include:
|
|
|
|
`indices`::
|
|
(Optional, array of strings)
|
|
Array of index names or wildcard pattern of index names
|
|
included in snapshots.
|
|
|
|
`ignore_unavailable`::
|
|
(Optional, boolean)
|
|
If `true`,
|
|
missing indices do *not* cause snapshot creation to fail
|
|
and return an error.
|
|
Defaults to `false`.
|
|
|
|
`include_global_state`::
|
|
(Optional, boolean)
|
|
If `true`,
|
|
cluster states are included in snapshots.
|
|
Defaults to `false`.
|
|
--
|
|
|
|
`retention`::
|
|
+
|
|
--
|
|
(Optional, object)
|
|
Retention rules used to retain
|
|
and delete snapshots
|
|
created by the policy.
|
|
|
|
Parameters include:
|
|
|
|
`expire_after`::
|
|
(Optional, <<time-units, time units>>)
|
|
Time period after which
|
|
a snapshot is considered expired
|
|
and eligible for deletion.
|
|
|
|
`max_count`::
|
|
(Optional, integer)
|
|
Maximum number of snapshots to retain,
|
|
even if the snapshots have not yet expired.
|
|
+
|
|
If the number of snapshots in the repository exceeds this limit,
|
|
the policy retains the most recent snapshots
|
|
and deletes older snapshots.
|
|
|
|
`min_count`::
|
|
(Optional, integer)
|
|
Minimum number of snapshots to retain,
|
|
even if the snapshots have expired.
|
|
--
|
|
|
|
|
|
[[slm-api-put-example]]
|
|
==== {api-examples-title}
|
|
|
|
The following request creates a snapshot lifecycle policy
|
|
with an ID of `daily-snapshots`:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /_slm/policy/daily-snapshots
|
|
{
|
|
"schedule": "0 30 1 * * ?", <1>
|
|
"name": "<daily-snap-{now/d}>", <2>
|
|
"repository": "my_repository", <3>
|
|
"config": { <4>
|
|
"indices": ["data-*", "important"], <5>
|
|
"ignore_unavailable": false,
|
|
"include_global_state": false
|
|
},
|
|
"retention": { <6>
|
|
"expire_after": "30d", <7>
|
|
"min_count": 5, <8>
|
|
"max_count": 50 <9>
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TEST[setup:setup-repository]
|
|
|
|
<1> When the snapshot should be taken, in this case, 1:30am daily
|
|
<2> The name each snapshot should be given
|
|
<3> Which repository to take the snapshot in
|
|
<4> Any extra snapshot configuration
|
|
<5> Which indices the snapshot should contain
|
|
<6> Optional retention configuration
|
|
<7> Keep snapshots for 30 days
|
|
<8> Always keep at least 5 successful snapshots, even if they're more than 30 days old
|
|
<9> Keep no more than 50 successful snapshots, even if they're less than 30 days old
|
|
|
|
|
|
[[slm-api-get]]
|
|
=== Get snapshot lifecycle policy API
|
|
++++
|
|
<titleabbrev>Get snapshot lifecycle policy</titleabbrev>
|
|
++++
|
|
|
|
Returns information
|
|
about one or more snapshot lifecycle policies.
|
|
|
|
|
|
[[slm-api-get-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /_slm/policy/<snapshot-lifecycle-policy-id>`
|
|
|
|
`GET /_slm/policy/`
|
|
|
|
|
|
[[slm-api-get-desc]]
|
|
==== {api-description-title}
|
|
|
|
Use the snapshot lifecycle policy API
|
|
to retrieve information
|
|
about one or more snapshot lifecycle policies.
|
|
The API response also includes information
|
|
about the latest successful and failed attempts
|
|
to create automatic snapshots.
|
|
|
|
[[slm-api-get-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<snapshot-lifecycle-policy-id>`::
|
|
(Optional, string)
|
|
Comma-separated list of snapshot lifecycle policy IDs
|
|
to retrieve.
|
|
|
|
|
|
[[slm-api-get-example]]
|
|
==== {api-examples-title}
|
|
|
|
|
|
[[slm-api-get-specific-ex]]
|
|
===== Get a specific policy
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_slm/policy/daily-snapshots?human
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"daily-snapshots" : {
|
|
"version": 1, <1>
|
|
"modified_date": "2019-04-23T01:30:00.000Z", <2>
|
|
"modified_date_millis": 1556048137314,
|
|
"policy" : {
|
|
"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
|
|
}
|
|
},
|
|
"stats": {
|
|
"policy": "daily-snapshots",
|
|
"snapshots_taken": 0,
|
|
"snapshots_failed": 0,
|
|
"snapshots_deleted": 0,
|
|
"snapshot_deletion_failures": 0
|
|
},
|
|
"next_execution": "2019-04-24T01:30:00.000Z", <3>
|
|
"next_execution_millis": 1556048160000
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/"modified_date": "2019-04-23T01:30:00.000Z"/"modified_date": $body.daily-snapshots.modified_date/ s/"modified_date_millis": 1556048137314/"modified_date_millis": $body.daily-snapshots.modified_date_millis/ s/"next_execution": "2019-04-24T01:30:00.000Z"/"next_execution": $body.daily-snapshots.next_execution/ s/"next_execution_millis": 1556048160000/"next_execution_millis": $body.daily-snapshots.next_execution_millis/]
|
|
<1> The version of the snapshot policy, only the latest verison is stored and incremented when the policy is updated
|
|
<2> The last time this policy was modified.
|
|
<3> The next time this policy will be executed.
|
|
|
|
|
|
[[slm-api-get-all-ex]]
|
|
===== Get all policies
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_slm/policy
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
|
|
[[slm-api-execute]]
|
|
=== Execute snapshot lifecycle policy API
|
|
++++
|
|
<titleabbrev>Execute snapshot lifecycle policy</titleabbrev>
|
|
++++
|
|
|
|
Executes a snapshot lifecycle policy, immediately creating a snapshot
|
|
without waiting for the scheduled creation time.
|
|
|
|
|
|
[[slm-api-execute-request]]
|
|
==== {api-request-title}
|
|
|
|
`PUT /_slm/policy/<snapshot-lifecycle-policy-id>/_execute`
|
|
|
|
|
|
[[slm-api-execute-desc]]
|
|
==== {api-description-title}
|
|
|
|
Sometimes it can be useful to immediately execute a snapshot based on policy,
|
|
perhaps before an upgrade or before performing other maintenance on indices. The
|
|
execute snapshot policy API allows you to perform a snapshot immediately without
|
|
waiting for a policy's scheduled invocation.
|
|
|
|
|
|
[[slm-api-execute-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<snapshot-lifecycle-policy-id>`::
|
|
(Required, string)
|
|
ID of the snapshot lifecycle policy to execute.
|
|
|
|
|
|
[[slm-api-execute-example]]
|
|
==== {api-examples-title}
|
|
|
|
To take an immediate snapshot using a policy, use the following request:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST /_slm/policy/daily-snapshots/_execute
|
|
--------------------------------------------------
|
|
// TEST[skip:we can't easily handle snapshots from docs tests]
|
|
|
|
This API returns the following response with the generated snapshot name:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"snapshot_name": "daily-snap-2019.04.24-gwrqoo2xtea3q57vvg0uea"
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[skip:we can't handle snapshots from docs tests]
|
|
|
|
The snapshot will be taken in the background, you can use the
|
|
<<modules-snapshots,snapshot APIs>> to monitor the status of the snapshot.
|
|
|
|
Once a snapshot has been kicked off, you can see the latest successful or failed
|
|
snapshot using the get snapshot lifecycle policy API:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_slm/policy/daily-snapshots?human
|
|
--------------------------------------------------
|
|
// TEST[skip:we already tested get policy above, the last_failure may not be present though]
|
|
|
|
Which, in this case shows an error because the index did not exist:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"daily-snapshots" : {
|
|
"version": 1,
|
|
"modified_date": "2019-04-23T01:30:00.000Z",
|
|
"modified_date_millis": 1556048137314,
|
|
"policy" : {
|
|
"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
|
|
}
|
|
},
|
|
"stats": {
|
|
"policy": "daily-snapshots",
|
|
"snapshots_taken": 0,
|
|
"snapshots_failed": 1,
|
|
"snapshots_deleted": 0,
|
|
"snapshot_deletion_failures": 0
|
|
}
|
|
"last_failure": { <1>
|
|
"snapshot_name": "daily-snap-2019.04.02-lohisb5ith2n8hxacaq3mw",
|
|
"time_string": "2019-04-02T01:30:00.000Z",
|
|
"time": 1556042030000,
|
|
"details": "{\"type\":\"index_not_found_exception\",\"reason\":\"no such index [important]\",\"resource.type\":\"index_or_alias\",\"resource.id\":\"important\",\"index_uuid\":\"_na_\",\"index\":\"important\",\"stack_trace\":\"[important] IndexNotFoundException[no such index [important]]\\n\\tat org.elasticsearch.cluster.metadata.IndexNameExpressionResolver$WildcardExpressionResolver.indexNotFoundException(IndexNameExpressionResolver.java:762)\\n\\tat org.elasticsearch.cluster.metadata.IndexNameExpressionResolver$WildcardExpressionResolver.innerResolve(IndexNameExpressionResolver.java:714)\\n\\tat org.elasticsearch.cluster.metadata.IndexNameExpressionResolver$WildcardExpressionResolver.resolve(IndexNameExpressionResolver.java:670)\\n\\tat org.elasticsearch.cluster.metadata.IndexNameExpressionResolver.concreteIndices(IndexNameExpressionResolver.java:163)\\n\\tat org.elasticsearch.cluster.metadata.IndexNameExpressionResolver.concreteIndexNames(IndexNameExpressionResolver.java:142)\\n\\tat org.elasticsearch.cluster.metadata.IndexNameExpressionResolver.concreteIndexNames(IndexNameExpressionResolver.java:102)\\n\\tat org.elasticsearch.snapshots.SnapshotsService$1.execute(SnapshotsService.java:280)\\n\\tat org.elasticsearch.cluster.ClusterStateUpdateTask.execute(ClusterStateUpdateTask.java:47)\\n\\tat org.elasticsearch.cluster.service.MasterService.executeTasks(MasterService.java:687)\\n\\tat org.elasticsearch.cluster.service.MasterService.calculateTaskOutputs(MasterService.java:310)\\n\\tat org.elasticsearch.cluster.service.MasterService.runTasks(MasterService.java:210)\\n\\tat org.elasticsearch.cluster.service.MasterService$Batcher.run(MasterService.java:142)\\n\\tat org.elasticsearch.cluster.service.TaskBatcher.runIfNotProcessed(TaskBatcher.java:150)\\n\\tat org.elasticsearch.cluster.service.TaskBatcher$BatchedTask.run(TaskBatcher.java:188)\\n\\tat org.elasticsearch.common.util.concurrent.ThreadContext$ContextPreservingRunnable.run(ThreadContext.java:688)\\n\\tat org.elasticsearch.common.util.concurrent.PrioritizedEsThreadPoolExecutor$TieBreakingPrioritizedRunnable.runAndClean(PrioritizedEsThreadPoolExecutor.java:252)\\n\\tat org.elasticsearch.common.util.concurrent.PrioritizedEsThreadPoolExecutor$TieBreakingPrioritizedRunnable.run(PrioritizedEsThreadPoolExecutor.java:215)\\n\\tat java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)\\n\\tat java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)\\n\\tat java.base/java.lang.Thread.run(Thread.java:834)\\n\"}"
|
|
} ,
|
|
"next_execution": "2019-04-24T01:30:00.000Z",
|
|
"next_execution_millis": 1556048160000
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[skip:the presence of last_failure is asynchronous and will be present for users, but is untestable]
|
|
|
|
<1> The last unsuccessfully initiated snapshot by this policy, along with the details of its failure
|
|
|
|
In this case, it failed due to the "important" index not existing and
|
|
`ignore_unavailable` setting being set to `false`.
|
|
|
|
Updating the policy to change the `ignore_unavailable` setting is done using the
|
|
same put snapshot lifecycle policy API:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /_slm/policy/daily-snapshots
|
|
{
|
|
"schedule": "0 30 1 * * ?",
|
|
"name": "<daily-snap-{now/d}>",
|
|
"repository": "my_repository",
|
|
"config": {
|
|
"indices": ["data-*", "important"],
|
|
"ignore_unavailable": true,
|
|
"include_global_state": false
|
|
},
|
|
"retention": {
|
|
"expire_after": "30d",
|
|
"min_count": 5,
|
|
"max_count": 50
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
Another snapshot can immediately be executed to ensure the new policy works:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST /_slm/policy/daily-snapshots/_execute
|
|
--------------------------------------------------
|
|
// TEST[skip:we can't handle snapshots in docs tests]
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"snapshot_name": "daily-snap-2019.04.24-tmtnyjtrsxkhbrrdcgg18a"
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[skip:we can't handle snapshots in docs tests]
|
|
|
|
Now retrieving the policy shows that the policy has successfully been executed:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_slm/policy/daily-snapshots?human
|
|
--------------------------------------------------
|
|
// TEST[skip:we already tested this above and the output may not be available yet]
|
|
|
|
Which now includes the successful snapshot information:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"daily-snapshots" : {
|
|
"version": 2, <1>
|
|
"modified_date": "2019-04-23T01:30:00.000Z",
|
|
"modified_date_millis": 1556048137314,
|
|
"policy" : {
|
|
"schedule": "0 30 1 * * ?",
|
|
"name": "<daily-snap-{now/d}>",
|
|
"repository": "my_repository",
|
|
"config": {
|
|
"indices": ["data-*", "important"],
|
|
"ignore_unavailable": true,
|
|
"include_global_state": false
|
|
},
|
|
"retention": {
|
|
"expire_after": "30d",
|
|
"min_count": 5,
|
|
"max_count": 50
|
|
}
|
|
},
|
|
"stats": {
|
|
"policy": "daily-snapshots",
|
|
"snapshots_taken": 1,
|
|
"snapshots_failed": 1,
|
|
"snapshots_deleted": 0,
|
|
"snapshot_deletion_failures": 0
|
|
},
|
|
"last_success": { <2>
|
|
"snapshot_name": "daily-snap-2019.04.24-tmtnyjtrsxkhbrrdcgg18a",
|
|
"time_string": "2019-04-24T16:43:49.316Z",
|
|
"time": 1556124229316
|
|
} ,
|
|
"last_failure": {
|
|
"snapshot_name": "daily-snap-2019.04.02-lohisb5ith2n8hxacaq3mw",
|
|
"time_string": "2019-04-02T01:30:00.000Z",
|
|
"time": 1556042030000,
|
|
"details": "{\"type\":\"index_not_found_exception\",\"reason\":\"no such index [important]\",\"resource.type\":\"index_or_alias\",\"resource.id\":\"important\",\"index_uuid\":\"_na_\",\"index\":\"important\",\"stack_trace\":\"[important] IndexNotFoundException[no such index [important]]\\n\\tat org.elasticsearch.cluster.metadata.IndexNameExpressionResolver$WildcardExpressionResolver.indexNotFoundException(IndexNameExpressionResolver.java:762)\\n\\tat org.elasticsearch.cluster.metadata.IndexNameExpressionResolver$WildcardExpressionResolver.innerResolve(IndexNameExpressionResolver.java:714)\\n\\tat org.elasticsearch.cluster.metadata.IndexNameExpressionResolver$WildcardExpressionResolver.resolve(IndexNameExpressionResolver.java:670)\\n\\tat org.elasticsearch.cluster.metadata.IndexNameExpressionResolver.concreteIndices(IndexNameExpressionResolver.java:163)\\n\\tat org.elasticsearch.cluster.metadata.IndexNameExpressionResolver.concreteIndexNames(IndexNameExpressionResolver.java:142)\\n\\tat org.elasticsearch.cluster.metadata.IndexNameExpressionResolver.concreteIndexNames(IndexNameExpressionResolver.java:102)\\n\\tat org.elasticsearch.snapshots.SnapshotsService$1.execute(SnapshotsService.java:280)\\n\\tat org.elasticsearch.cluster.ClusterStateUpdateTask.execute(ClusterStateUpdateTask.java:47)\\n\\tat org.elasticsearch.cluster.service.MasterService.executeTasks(MasterService.java:687)\\n\\tat org.elasticsearch.cluster.service.MasterService.calculateTaskOutputs(MasterService.java:310)\\n\\tat org.elasticsearch.cluster.service.MasterService.runTasks(MasterService.java:210)\\n\\tat org.elasticsearch.cluster.service.MasterService$Batcher.run(MasterService.java:142)\\n\\tat org.elasticsearch.cluster.service.TaskBatcher.runIfNotProcessed(TaskBatcher.java:150)\\n\\tat org.elasticsearch.cluster.service.TaskBatcher$BatchedTask.run(TaskBatcher.java:188)\\n\\tat org.elasticsearch.common.util.concurrent.ThreadContext$ContextPreservingRunnable.run(ThreadContext.java:688)\\n\\tat org.elasticsearch.common.util.concurrent.PrioritizedEsThreadPoolExecutor$TieBreakingPrioritizedRunnable.runAndClean(PrioritizedEsThreadPoolExecutor.java:252)\\n\\tat org.elasticsearch.common.util.concurrent.PrioritizedEsThreadPoolExecutor$TieBreakingPrioritizedRunnable.run(PrioritizedEsThreadPoolExecutor.java:215)\\n\\tat java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)\\n\\tat java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)\\n\\tat java.base/java.lang.Thread.run(Thread.java:834)\\n\"}"
|
|
} ,
|
|
"next_execution": "2019-04-24T01:30:00.000Z",
|
|
"next_execution_millis": 1556048160000
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[skip:the presence of last_failure and last_success is asynchronous and will be present for users, but is untestable]
|
|
|
|
<1> The policy's version has been incremented because it was updated
|
|
<2> The last successfully initiated snapshot information
|
|
|
|
It is a good idea to test policies using the execute API to ensure they work.
|
|
|
|
[[slm-get-stats]]
|
|
=== Get snapshot lifecycle stats API
|
|
++++
|
|
<titleabbrev>Get snapshot lifecycle stats</titleabbrev>
|
|
++++
|
|
|
|
Returns global and policy-level statistics about actions taken by {slm}.
|
|
|
|
|
|
[[slm-api-stats-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /_slm/stats`
|
|
|
|
|
|
[[slm-api-stats-example]]
|
|
==== {api-examples-title}
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_slm/stats
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
The API returns the following response:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"retention_runs": 13,
|
|
"retention_failed": 0,
|
|
"retention_timed_out": 0,
|
|
"retention_deletion_time": "1.4s",
|
|
"retention_deletion_time_millis": 1404,
|
|
"policy_stats": [ ],
|
|
"total_snapshots_taken": 1,
|
|
"total_snapshots_failed": 1,
|
|
"total_snapshots_deleted": 0,
|
|
"total_snapshot_deletion_failures": 0
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/runs": 13/runs": $body.retention_runs/ s/_failed": 0/_failed": $body.retention_failed/ s/_timed_out": 0/_timed_out": $body.retention_timed_out/ s/"1.4s"/$body.retention_deletion_time/ s/1404/$body.retention_deletion_time_millis/ s/total_snapshots_taken": 1/total_snapshots_taken": $body.total_snapshots_taken/ s/total_snapshots_failed": 1/total_snapshots_failed": $body.total_snapshots_failed/ s/"policy_stats": [.*]/"policy_stats": $body.policy_stats/]
|
|
|
|
|
|
[[slm-api-delete]]
|
|
=== Delete snapshot lifecycle policy API
|
|
++++
|
|
<titleabbrev>Delete snapshot lifecycle policy</titleabbrev>
|
|
++++
|
|
|
|
Deletes an existing snapshot lifecycle policy.
|
|
|
|
|
|
[[slm-api-delete-request]]
|
|
==== {api-request-title}
|
|
|
|
`DELETE /_slm/policy/<snapshot-lifecycle-policy-id>`
|
|
|
|
|
|
[[slm-api-delete-desc]]
|
|
==== {api-description-title}
|
|
|
|
A policy can be deleted by issuing a delete request with the policy id. Note
|
|
that this prevents any future snapshots from being taken, but does not cancel
|
|
any currently ongoing snapshots or remove any previously taken snapshots.
|
|
|
|
|
|
[[slm-api-delete-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<snapshot-lifecycle-policy-id>`::
|
|
(Required, string)
|
|
ID of the snapshot lifecycle policy to delete.
|
|
|
|
|
|
[[slm-api-delete-example]]
|
|
==== {api-examples-title}
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
DELETE /_slm/policy/daily-snapshots
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
|
|
[[slm-api-execute-retention]]
|
|
=== Execute snapshot lifecycle retention API
|
|
++++
|
|
<titleabbrev>Execute snapshot lifecycle retention</titleabbrev>
|
|
++++
|
|
|
|
Deletes any expired snapshots based on lifecycle policy retention rules.
|
|
|
|
|
|
[[slm-api-execute-retention-request]]
|
|
==== {api-request-title}
|
|
|
|
`POST /_slm/_execute_retention`
|
|
|
|
|
|
[[slm-api-execute-retention-desc]]
|
|
==== {api-description-title}
|
|
|
|
While Snapshot Lifecycle Management retention is usually invoked through the global cluster settings
|
|
for its schedule, it can sometimes be useful to invoke a retention run to expunge expired snapshots
|
|
immediately. This API allows you to run a one-off retention run.
|
|
|
|
|
|
[[slm-api-execute-retention-example]]
|
|
==== {api-examples-title}
|
|
|
|
To immediately start snapshot retention, use the following request:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST /_slm/_execute_retention
|
|
--------------------------------------------------
|
|
|
|
This API returns the following response as retention runs asynchronously in the
|
|
background:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"acknowledged": true
|
|
}
|
|
--------------------------------------------------
|
|
|
|
[[slm-stop]]
|
|
=== Stop Snapshot Lifecycle Management API
|
|
|
|
[subs="attributes"]
|
|
++++
|
|
<titleabbrev>Stop Snapshot Lifecycle Management</titleabbrev>
|
|
++++
|
|
|
|
Stop the Snapshot Lifecycle Management (SLM) plugin.
|
|
|
|
[[slm-stop-request]]
|
|
==== {api-request-title}
|
|
|
|
`POST /_ilm/stop`
|
|
|
|
[[slm-stop-desc]]
|
|
==== {api-description-title}
|
|
|
|
Halts all snapshot lifecycle management operations and stops the SLM plugin.
|
|
This is useful when you are performing maintenance on the cluster and need to
|
|
prevent SLM from performing any actions on your indices. Note that this API does
|
|
not stop any snapshots that are currently in progress, and that snapshots can
|
|
still be taken manually via the <<slm-api-execute,Execute Policy API>> even
|
|
when SLM is stopped.
|
|
|
|
The API returns as soon as the stop request has been acknowledged, but the
|
|
plugin might continue to run until in-progress operations complete and the plugin
|
|
can be safely stopped. Use the <<slm-get-status, Get SLM Status>> API to see
|
|
if SLM is running.
|
|
|
|
==== Request Parameters
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
|
|
|
|
==== Authorization
|
|
|
|
You must have the `manage_slm` cluster privilege to use this API.
|
|
For more information, see <<security-privileges>>.
|
|
|
|
[[slm-stop-example]]
|
|
==== {api-examples-title}
|
|
|
|
Stops the SLM plugin.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST _slm/stop
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
If the request does not encounter errors, you receive the following result:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"acknowledged": true
|
|
}
|
|
--------------------------------------------------
|
|
|
|
[[slm-start]]
|
|
=== Start Snapshot Lifecycle Management API
|
|
|
|
[subs="attributes"]
|
|
++++
|
|
<titleabbrev>Start Snapshot Lifecycle Management</titleabbrev>
|
|
++++
|
|
|
|
Start the Snapshot Lifecycle Management (SLM) plugin.
|
|
|
|
[[slm-start-request]]
|
|
==== {api-request-title}
|
|
|
|
`POST /_slm/start`
|
|
|
|
[[slm-start-desc]]
|
|
==== {api-description-title}
|
|
|
|
Starts the SLM plugin if it is currently stopped. SLM is started
|
|
automatically when the cluster is formed. Restarting SLM is only
|
|
necessary if it has been stopped using the <<slm-stop, Stop SLM API>>.
|
|
|
|
==== Request Parameters
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
|
|
|
|
==== Authorization
|
|
|
|
You must have the `manage_slm` cluster privilege to use this API.
|
|
For more information, see <<security-privileges>>.
|
|
|
|
[[slm-start-example]]
|
|
==== {api-examples-title}
|
|
|
|
Starts the SLM plugin.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST _slm/start
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
If the request succeeds, you receive the following result:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"acknowledged": true
|
|
}
|
|
--------------------------------------------------
|
|
|
|
[[slm-get-status]]
|
|
=== Get Snapshot Lifecycle Management status API
|
|
|
|
[subs="attributes"]
|
|
++++
|
|
<titleabbrev>Get Snapshot Lifecycle Management status</titleabbrev>
|
|
++++
|
|
|
|
Retrieves the current Snapshot Lifecycle Management (SLM) status.
|
|
|
|
[[slm-get-status-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /_slm/status`
|
|
|
|
[[slm-get-status-desc]]
|
|
==== {api-description-title}
|
|
|
|
Returns the status of the SLM plugin. The `operation_mode` field in the
|
|
response shows one of three states: `STARTED`, `STOPPING`,
|
|
or `STOPPED`. You can change the status of the SLM plugin with the
|
|
<<slm-start, Start SLM>> and <<slm-stop, Stop SLM>> APIs.
|
|
|
|
==== Request Parameters
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
|
|
|
|
==== Authorization
|
|
|
|
You must have the `manage_slm` or `read_slm` or both cluster privileges to use this API.
|
|
For more information, see <<security-privileges>>.
|
|
|
|
[[slm-get-status-example]]
|
|
==== {api-examples-title}
|
|
|
|
Gets the SLM plugin status.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET _slm/status
|
|
--------------------------------------------------
|
|
|
|
If the request succeeds, the body of the response shows the operation mode:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"operation_mode": "RUNNING"
|
|
}
|
|
--------------------------------------------------
|