From 0fed96eebc2126556d3fa6d3a3a563a4c5fd7b36 Mon Sep 17 00:00:00 2001 From: debadair Date: Tue, 21 Jan 2020 19:58:17 -0800 Subject: [PATCH] [DOCS] Align with ILM API docs (#48705) * [DOCS] Reconciled with Snapshot/Restore reorg --- .../ilm/apis/delete-lifecycle.asciidoc | 2 +- docs/reference/ilm/apis/ilm-api.asciidoc | 4 +- docs/reference/ilm/apis/slm-api.asciidoc | 822 ------------------ docs/reference/ilm/index.asciidoc | 4 - docs/reference/modules.asciidoc | 4 - docs/reference/redirects.asciidoc | 25 + docs/reference/rest-api/index.asciidoc | 2 +- docs/reference/slm/apis/index.asciidoc | 72 ++ docs/reference/slm/apis/slm-api.asciidoc | 44 + docs/reference/slm/apis/slm-delete.asciidoc | 67 ++ .../slm/apis/slm-execute-retention.asciidoc | 37 + docs/reference/slm/apis/slm-execute.asciidoc | 61 ++ .../slm/apis/slm-get-status.asciidoc | 53 ++ docs/reference/slm/apis/slm-get.asciidoc | 124 +++ docs/reference/slm/apis/slm-put.asciidoc | 177 ++++ docs/reference/slm/apis/slm-start.asciidoc | 51 ++ docs/reference/slm/apis/slm-stats.asciidoc | 46 + docs/reference/slm/apis/slm-stop.asciidoc | 48 + .../{ilm => slm}/getting-started-slm.asciidoc | 67 +- docs/reference/slm/index.asciidoc | 72 ++ .../{ilm => slm}/slm-retention.asciidoc | 12 +- .../reference/snapshot-restore/index.asciidoc | 2 + .../api/slm.delete_lifecycle.json | 2 +- .../api/slm.execute_lifecycle.json | 2 +- .../rest-api-spec/api/slm.get_lifecycle.json | 2 +- .../rest-api-spec/api/slm.get_stats.json | 2 +- .../rest-api-spec/api/slm.put_lifecycle.json | 2 +- 27 files changed, 906 insertions(+), 900 deletions(-) delete mode 100644 docs/reference/ilm/apis/slm-api.asciidoc create mode 100644 docs/reference/slm/apis/index.asciidoc create mode 100644 docs/reference/slm/apis/slm-api.asciidoc create mode 100644 docs/reference/slm/apis/slm-delete.asciidoc create mode 100644 docs/reference/slm/apis/slm-execute-retention.asciidoc create mode 100644 docs/reference/slm/apis/slm-execute.asciidoc create mode 100644 docs/reference/slm/apis/slm-get-status.asciidoc create mode 100644 docs/reference/slm/apis/slm-get.asciidoc create mode 100644 docs/reference/slm/apis/slm-put.asciidoc create mode 100644 docs/reference/slm/apis/slm-start.asciidoc create mode 100644 docs/reference/slm/apis/slm-stats.asciidoc create mode 100644 docs/reference/slm/apis/slm-stop.asciidoc rename docs/reference/{ilm => slm}/getting-started-slm.asciidoc (84%) create mode 100644 docs/reference/slm/index.asciidoc rename docs/reference/{ilm => slm}/slm-retention.asciidoc (91%) diff --git a/docs/reference/ilm/apis/delete-lifecycle.asciidoc b/docs/reference/ilm/apis/delete-lifecycle.asciidoc index 32bf21980068b..bcc2107f2da28 100644 --- a/docs/reference/ilm/apis/delete-lifecycle.asciidoc +++ b/docs/reference/ilm/apis/delete-lifecycle.asciidoc @@ -6,7 +6,7 @@ Delete policy ++++ -Deletes a lifecycle policy. +Deletes an index lifecycle policy. [[ilm-delete-lifecycle-request]] ==== {api-request-title} diff --git a/docs/reference/ilm/apis/ilm-api.asciidoc b/docs/reference/ilm/apis/ilm-api.asciidoc index d8b71b937765c..e2b1f74020b38 100644 --- a/docs/reference/ilm/apis/ilm-api.asciidoc +++ b/docs/reference/ilm/apis/ilm-api.asciidoc @@ -1,8 +1,8 @@ [[index-lifecycle-management-api]] == {ilm-cap} API -You can use the following APIs to manage policies on indices. For more -information, see <>. +You use the following APIs to set up policies to automatically manage the index lifecycle. +For more information about {ilm} ({ilm-init}), see <>. [float] [[ilm-api-policy-endpoint]] diff --git a/docs/reference/ilm/apis/slm-api.asciidoc b/docs/reference/ilm/apis/slm-api.asciidoc deleted file mode 100644 index 51e095f72ef69..0000000000000 --- a/docs/reference/ilm/apis/slm-api.asciidoc +++ /dev/null @@ -1,822 +0,0 @@ -[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 <>, 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 <> and -<> 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 -++++ -Put snapshot lifecycle policy -++++ - -Creates or updates a snapshot lifecycle policy. - - -[[slm-api-put-request]] -==== {api-request-title} - -`PUT /_slm/policy/` - - -[[slm-api-put-prereqs]] -==== {api-prereq-title} - -If you use {es} {security-features}, -you must have: - -* `manage_slm` <> -* `manage` <> for any included indices - -{slm-cap} operations are executed -as the user that last created or updated the policy. - -For more information, -see <>. - - -[[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} - -``:: -(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, <>) -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 <> -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 <>. --- - -`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 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": "", <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 -++++ -Get snapshot lifecycle policy -++++ - -Returns information -about one or more snapshot lifecycle policies. - - -[[slm-api-get-request]] -==== {api-request-title} - -`GET /_slm/policy/` - -`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} - -``:: -(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": "", - "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 version 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 -++++ -Execute snapshot lifecycle policy -++++ - -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//_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} - -``:: -(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 -<> 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": "", - "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": "", - "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": "", - "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 -++++ -Get snapshot lifecycle stats -++++ - -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 -++++ -Delete snapshot lifecycle policy -++++ - -Deletes an existing snapshot lifecycle policy. - - -[[slm-api-delete-request]] -==== {api-request-title} - -`DELETE /_slm/policy/` - - -[[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} - -``:: -(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 -++++ -Execute snapshot lifecycle retention -++++ - -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"] -++++ -Stop Snapshot Lifecycle Management -++++ - -Stop the Snapshot Lifecycle Management (SLM) plugin. - -[[slm-stop-request]] -==== {api-request-title} - -`POST /_slm/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 <> 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 <> 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 <>. - -[[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"] -++++ -Start Snapshot Lifecycle Management -++++ - -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 <>. - -==== 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 <>. - -[[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"] -++++ -Get Snapshot Lifecycle Management status -++++ - -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 -<> and <> 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 <>. - -[[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" -} --------------------------------------------------- diff --git a/docs/reference/ilm/index.asciidoc b/docs/reference/ilm/index.asciidoc index 10af04f8a14b1..c26e698efda25 100644 --- a/docs/reference/ilm/index.asciidoc +++ b/docs/reference/ilm/index.asciidoc @@ -85,7 +85,3 @@ include::ilm-and-snapshots.asciidoc[] include::start-stop-ilm.asciidoc[] include::ilm-with-existing-indices.asciidoc[] - -include::getting-started-slm.asciidoc[] - -include::slm-retention.asciidoc[] diff --git a/docs/reference/modules.asciidoc b/docs/reference/modules.asciidoc index 23f7f7692142d..0852e259f6462 100644 --- a/docs/reference/modules.asciidoc +++ b/docs/reference/modules.asciidoc @@ -50,10 +50,6 @@ The modules in this section are: Using plugins to extend Elasticsearch. -<>:: - - Backup your data with snapshot/restore. - <>:: Information about the dedicated thread pools used in Elasticsearch. diff --git a/docs/reference/redirects.asciidoc b/docs/reference/redirects.asciidoc index 266fc39aa9dcf..9725496d48e15 100644 --- a/docs/reference/redirects.asciidoc +++ b/docs/reference/redirects.asciidoc @@ -320,3 +320,28 @@ See <>. This page was deleted. See <>. + +[role="exclude",id="slm-api-delete"] +=== {slm-init} delete policy API + +See <>. + +[role="exclude",id="slm-api-execute"] +=== {slm-init} execute lifecycle API + +See <>. + +[role="exclude",id="slm-api-get"] +=== {slm-init} get policy API + +See <>. + +[role="exclude",id="slm-get-stats"] +=== {slm-init} get stats API + +See <>. + +[role="exclude",id="slm-api-put"] +=== {slm-init} put policy API + +See <>. diff --git a/docs/reference/rest-api/index.asciidoc b/docs/reference/rest-api/index.asciidoc index 7250f14660870..a703b1c7646e4 100644 --- a/docs/reference/rest-api/index.asciidoc +++ b/docs/reference/rest-api/index.asciidoc @@ -53,7 +53,7 @@ include::{es-repo-dir}/indices/apis/reload-analyzers.asciidoc[] include::{es-repo-dir}/rollup/rollup-api.asciidoc[] include::{es-repo-dir}/search.asciidoc[] include::{xes-repo-dir}/rest-api/security.asciidoc[] -include::{es-repo-dir}/ilm/apis/slm-api.asciidoc[] +include::{es-repo-dir}/slm/apis/slm-api.asciidoc[] include::{es-repo-dir}/transform/apis/index.asciidoc[] include::{xes-repo-dir}/rest-api/watcher.asciidoc[] include::defs.asciidoc[] diff --git a/docs/reference/slm/apis/index.asciidoc b/docs/reference/slm/apis/index.asciidoc new file mode 100644 index 0000000000000..86014c415f477 --- /dev/null +++ b/docs/reference/slm/apis/index.asciidoc @@ -0,0 +1,72 @@ +[role="xpack"] +[testenv="basic"] +[[snapshot-lifecycle-management]] +== Manage the snapshot lifecycle + +You can set up snapshot lifecycle policies to automate the timing, frequency, and retention of snapshots. +Snapshot policies can apply to multiple indices. + +The snapshot lifecycle management (SLM) <> provide +the building blocks for the snapshot policy features that are part of the Management application in {kib}. +The Snapshot and Restore UI makes it easy to set up policies, register snapshot repositories, +view and manage snapshots, and restore indices. + +You can stop and restart SLM to temporarily pause automatic backups while performing +upgrades or other maintenance. +To disable SLM entirely, set `xpack.slm.enabled` to `false` in `elasticsearch.yml`. + +[float] +[[slm-and-security]] +=== Security and SLM + +Two built-in cluster privileges control access to the SLM actions when +{es} {security-features} are enabled: + +`manage_slm`:: Allows a user to perform all SLM actions, including creating and updating policies +and starting and stopping SLM. + +`read_slm`:: Allows a user to perform all read-only SLM actions, +such as getting policies and checking the SLM status. + +`cluster:admin/snapshot/*`:: Allows a user to take and delete snapshots of any +index, whether or not they have access to that index. + +For example, the following request configures an `slm-admin` role that grants the privileges +necessary for administering SLM. + +[source,console] +----------------------------------- +POST /_security/role/slm-admin +{ + "cluster": ["manage_slm", "cluster:admin/snapshot/*"], + "indices": [ + { + "names": [".slm-history-*"], + "privileges": ["all"] + } + ] +} +----------------------------------- +// TEST[skip:security is not enabled here] + +Or, for a read-only role that can retrieve policies (but not update, execute, or +delete them), as well as only view the history index: + +[source,console] +----------------------------------- +POST /_security/role/slm-read-only +{ + "cluster": ["read_slm"], + "indices": [ + { + "names": [".slm-history-*"], + "privileges": ["read"] + } + ] +} +----------------------------------- +// TEST[skip:security is not enabled here] + +include::getting-started-slm.asciidoc[] + +include::slm-retention.asciidoc[] \ No newline at end of file diff --git a/docs/reference/slm/apis/slm-api.asciidoc b/docs/reference/slm/apis/slm-api.asciidoc new file mode 100644 index 0000000000000..295356fbe81d9 --- /dev/null +++ b/docs/reference/slm/apis/slm-api.asciidoc @@ -0,0 +1,44 @@ +[role="xpack"] +[testenv="basic"] +[[snapshot-lifecycle-management-api]] +== {slm-cap} API + +You use the following APIs to set up policies to automatically take snapshots and +control how long they are retained. +For more information about {slm} ({slm-init}), see <>. + +[float] +[[slm-api-policy-endpoint]] +=== Policy management APIs + +* <> +* <> +* <> + +[float] +[[slm-api-index-endpoint]] +=== Snapshot management APIs + +* <> (take snapshots) +* <> (delete expired snapshots) + +[float] +[[slm-api-management-endpoint]] +=== Operation management APIs + +* <> +* <> +* <> +* <> + +include::slm-put.asciidoc[] +include::slm-get.asciidoc[] +include::slm-delete.asciidoc[] + +include::slm-execute.asciidoc[] +include::slm-execute-retention.asciidoc[] + +include::slm-get-status.asciidoc[] +include::slm-stats.asciidoc[] +include::slm-start.asciidoc[] +include::slm-stop.asciidoc[] \ No newline at end of file diff --git a/docs/reference/slm/apis/slm-delete.asciidoc b/docs/reference/slm/apis/slm-delete.asciidoc new file mode 100644 index 0000000000000..b02eecfc6be94 --- /dev/null +++ b/docs/reference/slm/apis/slm-delete.asciidoc @@ -0,0 +1,67 @@ +[[slm-api-delete-policy]] +=== Delete snapshot lifecycle policy API +++++ +Delete policy +++++ + +Deletes an existing snapshot lifecycle policy. + +[[slm-api-delete-lifecycle-request]] +==== {api-request-title} + +`DELETE /_slm/policy/` + +[[slm-api-delete-lifecycle-prereqs]] +==== {api-prereq-title} + +If the {es} {security-features} are enabled, you must have the `manage_slm` +cluster privilege to use this API. For more information, see +<>. + +[[slm-api-delete-lifecycle-desc]] +==== {api-description-title} + +Deletes the specified lifecycle policy definition. +This prevents any future snapshots from being taken +but does not cancel in-progress snapshots +or remove previously-taken snapshots. + + +[[slm-api-delete-lifecycle-path-params]] +==== {api-path-parms-title} + +``:: +(Required, string) +ID of the snapshot lifecycle policy to delete. + +[[slm-api-delete-lifecycle-example]] +==== {api-examples-title} + +//// +[source,console] +-------------------------------------------------- +PUT /_slm/policy/daily-snapshots +{ + "schedule": "0 30 1 * * ?", <1> + "name": "", <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] +//// + +[source,console] +-------------------------------------------------- +DELETE /_slm/policy/daily-snapshots +-------------------------------------------------- +// TEST[continued] \ No newline at end of file diff --git a/docs/reference/slm/apis/slm-execute-retention.asciidoc b/docs/reference/slm/apis/slm-execute-retention.asciidoc new file mode 100644 index 0000000000000..1ff4efd6be32b --- /dev/null +++ b/docs/reference/slm/apis/slm-execute-retention.asciidoc @@ -0,0 +1,37 @@ +[[slm-api-execute-retention]] +=== Execute snapshot retention policy API +++++ +Execute snapshot retention policy +++++ + +Deletes any snapshots that are expired according to the policy's retention rules. + +[[slm-api-execute-retention-request]] +==== {api-request-title} + +`POST /_slm/_execute_retention` + +[[slm-api-execute-retention-prereqs]] +==== {api-prereq-title} + +If the {es} {security-features} are enabled, you must have the `manage_slm` +cluster privilege to use this API. For more information, see +<>. + +[[slm-api-execute-retention-desc]] +==== {api-description-title} + +Manually applies the retention policy to force immediate removal of expired snapshots. +The retention policy is normally applied according to its schedule. + +[[slm-api-execute-retention-example]] +==== {api-examples-title} + +To force removal of expired snapshots: + +[source,console] +-------------------------------------------------- +POST /_slm/_execute_retention +-------------------------------------------------- + +Retention runs asynchronously in the background. \ No newline at end of file diff --git a/docs/reference/slm/apis/slm-execute.asciidoc b/docs/reference/slm/apis/slm-execute.asciidoc new file mode 100644 index 0000000000000..f764f0419bb5f --- /dev/null +++ b/docs/reference/slm/apis/slm-execute.asciidoc @@ -0,0 +1,61 @@ +[[slm-api-execute-lifecycle]] +=== Execute snapshot lifecycle policy API +++++ +Execute snapshot lifecycle policy +++++ + +Immediately creates a snapshot according to the lifecycle policy, +without waiting for the scheduled time. + +[[slm-api-execute-lifecycle-request]] +==== {api-request-title} + +`PUT /_slm/policy//_execute` + +[[slm-api-execute-lifecycle-prereqs]] +==== {api-prereq-title} + +If the {es} {security-features} are enabled, you must have the `manage_slm` +cluster privilege to use this API. For more information, see +<>. + +[[slm-api-execute-lifecycle-desc]] +==== {api-description-title} + +Manually applies the snapshot policy to immediately create a snapshot. +The snapshot policy is normally applied according to its schedule, +but you might want to manually execute a policy before performing an upgrade +or other maintenance. + +[[slm-api-execute-lifecycle-path-params]] +==== {api-path-parms-title} + +``:: +(Required, string) +ID of the snapshot lifecycle policy to execute. + +[[slm-api-execute-lifecycle-example]] +==== {api-examples-title} + +To take an immediate snapshot according to the `daily-snapshots` policy: + +[source,console] +-------------------------------------------------- +POST /_slm/policy/daily-snapshots/_execute +-------------------------------------------------- +// TEST[skip:we can't easily handle snapshots from docs tests] + +If successful, this request returns 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 is taken in the background. +You can use the<> to monitor the status of the snapshot. + +To see the status of a policy's most recent snapshot, you can use the <>. \ No newline at end of file diff --git a/docs/reference/slm/apis/slm-get-status.asciidoc b/docs/reference/slm/apis/slm-get-status.asciidoc new file mode 100644 index 0000000000000..bda8a77f0505a --- /dev/null +++ b/docs/reference/slm/apis/slm-get-status.asciidoc @@ -0,0 +1,53 @@ +[[slm-api-get-status]] +=== Get {slm} status API + +[subs="attributes"] +++++ +Get {slm} status +++++ + +Retrieves the status of {slm} ({slm-init}). + +[[slm-api-get-status-request]] +==== {api-request-title} + +`GET /_slm/status` + +[[slm-api-get-status-desc]] +==== {api-description-title} + +Returns the status of the {slm-init} plugin. +The `operation_mode` field in the response shows one of three states: +`STARTED`, `STOPPING`, or `STOPPED`. +You halt and restart the {slm-init} plugin with the +<> and <> APIs. + +==== {api-query-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] + +[[slm-api-get-status-prereqs]] +==== {api-prereq-title} + +If the {es} {security-features} are enabled, you must have the +`manage_slm` or `read_slm` cluster privileges to use this API. +For more information, see <>. + +[[slm-api-get-status-example]] +==== {api-examples-title} + + +[source,console] +-------------------------------------------------- +GET _slm/status +-------------------------------------------------- + +The API returns the following result: + +[source,console-result] +-------------------------------------------------- +{ + "operation_mode": "RUNNING" +} +-------------------------------------------------- +// TESTRESPONSE[s/"operation_mode": "RUNNING"/"operation_mode": $body.operation_mode/] \ No newline at end of file diff --git a/docs/reference/slm/apis/slm-get.asciidoc b/docs/reference/slm/apis/slm-get.asciidoc new file mode 100644 index 0000000000000..c0614dc820c37 --- /dev/null +++ b/docs/reference/slm/apis/slm-get.asciidoc @@ -0,0 +1,124 @@ +[[slm-api-get-policy]] +=== Get snapshot lifecycle policy API +++++ +Get policy +++++ + +Retrieves one or more snapshot lifecycle policy definitions and +information about the latest snapshot attempts. + +[[slm-api-get-request]] +==== {api-request-title} + +`GET /_slm/policy/` + +`GET /_slm/policy` + +[[slm-api-get-lifecycle-prereqs]] +==== {api-prereq-title} + +If the {es} {security-features} are enabled, you must have the `manage_slm` +cluster privilege to use this API. For more information, see +<>. + +[[slm-api-get-desc]] +==== {api-description-title} + +Returns the specified policy definition and +information about the latest successful and failed attempts to create snapshots. +If no policy is specified, returns all defined policies. + +[[slm-api-get-path-params]] +==== {api-path-parms-title} + +``:: +(Optional, string) +Comma-separated list of snapshot lifecycle policy IDs. + +[[slm-api-get-example]] +==== {api-examples-title} + +[[slm-api-get-specific-ex]] +===== Get a specific policy + +//// +[source,console] +-------------------------------------------------- +PUT /_slm/policy/daily-snapshots +{ + "schedule": "0 30 1 * * ?", <1> + "name": "", <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] +//// + +Get the `daily-snapshots` policy: + +[source,console] +-------------------------------------------------- +GET /_slm/policy/daily-snapshots?human +-------------------------------------------------- +// TEST[continued] + +This request 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": "", + "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] \ No newline at end of file diff --git a/docs/reference/slm/apis/slm-put.asciidoc b/docs/reference/slm/apis/slm-put.asciidoc new file mode 100644 index 0000000000000..0c253aaafc941 --- /dev/null +++ b/docs/reference/slm/apis/slm-put.asciidoc @@ -0,0 +1,177 @@ +[[slm-api-put-policy]] +=== Put snapshot lifecycle policy API +++++ +Put policy +++++ + +Creates or updates a snapshot lifecycle policy. + + +[[slm-api-put-request]] +==== {api-request-title} + +`PUT /_slm/policy/` + +[[slm-api-put-prereqs]] +==== {api-prereq-title} + +If the {es} {security-features} are enabled, you must have the +`manage_slm` cluster privilege and the `manage` index privilege +for any included indices to use this API. +For more information, see <>. + +[[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 a policy is stored. + +[[slm-api-put-path-params]] +==== {api-path-parms-title} + +``:: +(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, <>) +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 <> +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 <>. +-- + +`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 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} + +Create a `daily-snapshots` lifecycle policy: + +[source,console] +-------------------------------------------------- +PUT /_slm/policy/daily-snapshots +{ + "schedule": "0 30 1 * * ?", <1> + "name": "", <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 \ No newline at end of file diff --git a/docs/reference/slm/apis/slm-start.asciidoc b/docs/reference/slm/apis/slm-start.asciidoc new file mode 100644 index 0000000000000..db7be92b82b4a --- /dev/null +++ b/docs/reference/slm/apis/slm-start.asciidoc @@ -0,0 +1,51 @@ +[[slm-api-start]] +=== Start {slm} API + +[subs="attributes"] +++++ +Start {slm} +++++ + +Turns on {slm} ({slm-init}). + +[[slm-api-start-request]] +==== {api-request-title} + +`POST /_slm/start` + +[[slm-api-start-prereqs]] +==== {api-prereq-title} + +If the {es} {security-features} are enabled, you must have the `manage_slm` +cluster privilege to use this API. For more information, see +<>. + +[[slm-api-start-desc]] +==== {api-description-title} + +Starts the {slm-init} plugin if it's not running. +{slm-init} starts automatically when a cluster is formed. +Manually starting {slm-init} is only necessary if it has been stopped using the <>. + +==== {api-query-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] + +[[slm-api-start-example]] +==== {api-examples-title} + +Start the {slm-init} plugin: + +[source,console] +-------------------------------------------------- +POST _slm/start +-------------------------------------------------- + +If successful, this request returns: + +[source,console-result] +-------------------------------------------------- +{ + "acknowledged": true +} +-------------------------------------------------- \ No newline at end of file diff --git a/docs/reference/slm/apis/slm-stats.asciidoc b/docs/reference/slm/apis/slm-stats.asciidoc new file mode 100644 index 0000000000000..198ec813dbdb6 --- /dev/null +++ b/docs/reference/slm/apis/slm-stats.asciidoc @@ -0,0 +1,46 @@ +[[slm-api-get-stats]] +=== Get snapshot lifecycle stats API +++++ +Get snapshot lifecycle stats +++++ + +Returns global and policy-level statistics about actions taken by {slm}. + +[[slm-api-stats-request]] +==== {api-request-title} + +`GET /_slm/stats` + +[[slm-api-stats-prereqs]] +==== {api-prereq-title} + +If the {es} {security-features} are enabled, you must have the `manage_slm` +cluster privilege to use this API. For more information, see +<>. + +[[slm-api-stats-example]] +==== {api-examples-title} + +[source,console] +-------------------------------------------------- +GET /_slm/stats +-------------------------------------------------- + +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/] \ No newline at end of file diff --git a/docs/reference/slm/apis/slm-stop.asciidoc b/docs/reference/slm/apis/slm-stop.asciidoc new file mode 100644 index 0000000000000..dacbe61ac7a18 --- /dev/null +++ b/docs/reference/slm/apis/slm-stop.asciidoc @@ -0,0 +1,48 @@ +[[slm-api-stop]] +=== Stop {slm} API + +[subs="attributes"] +++++ +Stop {slm} +++++ + +Turn off {slm} ({slm-init}). + +[[slm-api-stop-request]] +==== {api-request-title} + +`POST /_slm/stop` + +[[slm-api-stop-prereqs]] +==== {api-prereq-title} + +If the {es} {security-features} are enabled, you must have the `manage_slm` +cluster privilege to use this API. For more information, see +<>. + +[[slm-api-stop-desc]] +==== {api-description-title} + +Halts all {slm} ({slm-init}) operations and stops the {slm-init} plugin. +This is useful when you are performing maintenance on a cluster and need to +prevent {slm-init} from performing any actions on your indices. +Stopping {slm-init} does not stop any snapshots that are in progress. +You can manually trigger snapshots with the <> even if {slm-init} is stopped. + +The API returns a response as soon as the request is acknowledged, but +the plugin might continue to run until in-progress operations complete and it can be safely stopped. +This conversation was marked as resolved by debadair +Use the <> to see if {slm-init} is running. + +==== {api-query-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] + +[[slm-api-stop-example]] +==== {api-examples-title} + + +[source,console] +-------------------------------------------------- +POST _slm/stop +-------------------------------------------------- \ No newline at end of file diff --git a/docs/reference/ilm/getting-started-slm.asciidoc b/docs/reference/slm/getting-started-slm.asciidoc similarity index 84% rename from docs/reference/ilm/getting-started-slm.asciidoc rename to docs/reference/slm/getting-started-slm.asciidoc index 24c1b8ca284f4..85fb8392199e3 100644 --- a/docs/reference/ilm/getting-started-slm.asciidoc +++ b/docs/reference/slm/getting-started-slm.asciidoc @@ -1,62 +1,17 @@ [role="xpack"] [testenv="basic"] [[getting-started-snapshot-lifecycle-management]] -== Getting started with snapshot lifecycle management +=== Configure snapshot lifecycle policies -Let's get started with snapshot lifecycle management (SLM) by working through a +Let's get started with {slm} ({slm-init}) by working through a hands-on scenario. The goal of this example is to automatically back up {es} indices using the <> every day at a particular time. Once these snapshots have been created, they are kept for a configured amount of time and then deleted per a configured retention policy. [float] -[[slm-and-security]] -=== Security and SLM -Before starting, it's important to understand the privileges that are needed -when configuring SLM if you are using the security plugin. There are two -built-in cluster privileges that can be used to assist: `manage_slm` and -`read_slm`. It's also good to note that the `cluster:admin/snapshot/*` -permission allows taking and deleting snapshots even for indices the role may -not have access to. - -An example of configuring an administrator role for SLM follows: - -[source,console] ------------------------------------ -POST /_security/role/slm-admin -{ - "cluster": ["manage_slm", "cluster:admin/snapshot/*"], - "indices": [ - { - "names": [".slm-history-*"], - "privileges": ["all"] - } - ] -} ------------------------------------ -// TEST[skip:security is not enabled here] - -Or, for a read-only role that can retrieve policies (but not update, execute, or -delete them), as well as only view the history index: - -[source,console] ------------------------------------ -POST /_security/role/slm-read-only -{ - "cluster": ["read_slm"], - "indices": [ - { - "names": [".slm-history-*"], - "privileges": ["read"] - } - ] -} ------------------------------------ -// TEST[skip:security is not enabled here] - -[float] -[[slm-gs-create-policy]] -=== Setting up a repository +[[slm-gs-register-repository]] +==== Register a repository Before we can set up an SLM policy, we'll need to set up a snapshot repository where the snapshots will be @@ -76,12 +31,13 @@ PUT /_snapshot/my_repository ----------------------------------- [float] -=== Setting up a policy +[[slm-gs-create-policy]] +==== Setting up a snapshot policy Now that we have a repository in place, we can create a policy to automatically take snapshots. Policies are written in JSON and will define when to take snapshots, what the snapshots should be named, and which indices should be -included, among other things. We'll use the <> API +included, among other things. We'll use the <> API to create the policy. When configurating a policy, retention can also optionally be configured. See @@ -131,13 +87,14 @@ request>>, so you can specify, for example, whether the snapshot should fail in special cases, such as if one of the specified indices cannot be found. [float] -=== Making sure the policy works +[[slm-gs-test-policy]] +==== Test the snapshot policy While snapshots taken by SLM policies can be viewed through the standard snapshot API, SLM also keeps track of policy successes and failures in ways that are a bit easier to use to make sure the policy is working. Once a policy has executed at -least once, when you view the policy using the <>, -some metadata will be returned indicating whether the snapshot was successfully +least once, when you view the policy using the <>, +some metadata will be returned indicating whether the snapshot was sucessfully initiated or not. Instead of waiting for our policy to run, let's tell SLM to take a snapshot @@ -219,7 +176,7 @@ field - it's included above only as an example. You should, however, see a `last_success` field and a snapshot name. If you do, you've successfully taken your first snapshot using SLM! -While only the most recent success and failure are available through the Get Policy +While only the most recent sucess and failure are available through the Get Policy API, all policy executions are recorded to a history index, which may be queried by searching the index pattern `.slm-history*`. diff --git a/docs/reference/slm/index.asciidoc b/docs/reference/slm/index.asciidoc new file mode 100644 index 0000000000000..86014c415f477 --- /dev/null +++ b/docs/reference/slm/index.asciidoc @@ -0,0 +1,72 @@ +[role="xpack"] +[testenv="basic"] +[[snapshot-lifecycle-management]] +== Manage the snapshot lifecycle + +You can set up snapshot lifecycle policies to automate the timing, frequency, and retention of snapshots. +Snapshot policies can apply to multiple indices. + +The snapshot lifecycle management (SLM) <> provide +the building blocks for the snapshot policy features that are part of the Management application in {kib}. +The Snapshot and Restore UI makes it easy to set up policies, register snapshot repositories, +view and manage snapshots, and restore indices. + +You can stop and restart SLM to temporarily pause automatic backups while performing +upgrades or other maintenance. +To disable SLM entirely, set `xpack.slm.enabled` to `false` in `elasticsearch.yml`. + +[float] +[[slm-and-security]] +=== Security and SLM + +Two built-in cluster privileges control access to the SLM actions when +{es} {security-features} are enabled: + +`manage_slm`:: Allows a user to perform all SLM actions, including creating and updating policies +and starting and stopping SLM. + +`read_slm`:: Allows a user to perform all read-only SLM actions, +such as getting policies and checking the SLM status. + +`cluster:admin/snapshot/*`:: Allows a user to take and delete snapshots of any +index, whether or not they have access to that index. + +For example, the following request configures an `slm-admin` role that grants the privileges +necessary for administering SLM. + +[source,console] +----------------------------------- +POST /_security/role/slm-admin +{ + "cluster": ["manage_slm", "cluster:admin/snapshot/*"], + "indices": [ + { + "names": [".slm-history-*"], + "privileges": ["all"] + } + ] +} +----------------------------------- +// TEST[skip:security is not enabled here] + +Or, for a read-only role that can retrieve policies (but not update, execute, or +delete them), as well as only view the history index: + +[source,console] +----------------------------------- +POST /_security/role/slm-read-only +{ + "cluster": ["read_slm"], + "indices": [ + { + "names": [".slm-history-*"], + "privileges": ["read"] + } + ] +} +----------------------------------- +// TEST[skip:security is not enabled here] + +include::getting-started-slm.asciidoc[] + +include::slm-retention.asciidoc[] \ No newline at end of file diff --git a/docs/reference/ilm/slm-retention.asciidoc b/docs/reference/slm/slm-retention.asciidoc similarity index 91% rename from docs/reference/ilm/slm-retention.asciidoc rename to docs/reference/slm/slm-retention.asciidoc index 6362af3e3d5b7..2e28ad6517b9b 100644 --- a/docs/reference/ilm/slm-retention.asciidoc +++ b/docs/reference/slm/slm-retention.asciidoc @@ -1,7 +1,7 @@ [role="xpack"] [testenv="basic"] [[slm-retention]] -== Snapshot lifecycle management retention +=== Snapshot retention Automatic deletion of older snapshots is an optional feature of snapshot lifecycle management. Retention is run as a cluster level task that is not associated with a particular policy's schedule @@ -11,7 +11,7 @@ run and for how long, the second configured on a policy for which snapshots shou retention. The cluster level settings for retention are shown below, and can be changed dynamically using the -<> API: +<> API: |===================================== | Setting | Default value | Description @@ -19,7 +19,7 @@ The cluster level settings for retention are shown below, and can be changed dyn | `slm.retention_schedule` | `0 30 1 * * ?` | A periodic or absolute time schedule for when retention should be run. Supports all values supported by the cron scheduler: <>. Retention can also be manually run using the - <>. Defaults to daily at 1:30am in the master + <> API. Defaults to daily at 1:30am in the master node's timezone. | `slm.retention_duration` | `"1h"` | A limit of how long SLM should spend deleting old snapshots. @@ -70,12 +70,12 @@ successful snapshots. ____ If multiple policies are configured to snapshot to the same repository, or manual snapshots have -been taken without using the <>, they are treated as not +been taken without using the <> API, they are treated as not eligible for retention, and do not count towards any limits. This allows multiple policies to have differing retention configuration while using the same snapshot repository. -Statistics for snapshot retention can be retrieved using the <>: +Statistics for snapshot retention can be retrieved using the +<> API: [source,console] -------------------------------------------------- diff --git a/docs/reference/snapshot-restore/index.asciidoc b/docs/reference/snapshot-restore/index.asciidoc index 3752fd36a6d3b..31b5d81da28cc 100644 --- a/docs/reference/snapshot-restore/index.asciidoc +++ b/docs/reference/snapshot-restore/index.asciidoc @@ -87,4 +87,6 @@ include::register-repository.asciidoc[] include::take-snapshot.asciidoc[] include::restore-snapshot.asciidoc[] include::monitor-snapshot-restore.asciidoc[] +include::../slm/index.asciidoc[] + diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.delete_lifecycle.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.delete_lifecycle.json index 8f18b5fcdadd5..93a45abd91f65 100644 --- a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.delete_lifecycle.json +++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.delete_lifecycle.json @@ -1,7 +1,7 @@ { "slm.delete_lifecycle":{ "documentation":{ - "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-delete.html" + "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-delete-policy.html" }, "stability":"stable", "url":{ diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.execute_lifecycle.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.execute_lifecycle.json index 6353fac6391fa..6538dabd23086 100644 --- a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.execute_lifecycle.json +++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.execute_lifecycle.json @@ -1,7 +1,7 @@ { "slm.execute_lifecycle":{ "documentation":{ - "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-execute.html" + "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-execute-policy.html" }, "stability":"stable", "url":{ diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_lifecycle.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_lifecycle.json index 1413438d2ca1c..a4a3b436f179b 100644 --- a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_lifecycle.json +++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_lifecycle.json @@ -1,7 +1,7 @@ { "slm.get_lifecycle":{ "documentation":{ - "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-get.html" + "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-get-policy.html" }, "stability":"stable", "url":{ diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_stats.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_stats.json index ce8acf46a4c58..747bdccdba7c6 100644 --- a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_stats.json +++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.get_stats.json @@ -1,7 +1,7 @@ { "slm.get_stats":{ "documentation":{ - "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/slm-get-stats.html" + "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/slm-api-get-stats.html" }, "stability":"stable", "url":{ diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.put_lifecycle.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.put_lifecycle.json index 4028d924c3d39..ce10a7b482c0c 100644 --- a/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.put_lifecycle.json +++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/slm.put_lifecycle.json @@ -1,7 +1,7 @@ { "slm.put_lifecycle":{ "documentation":{ - "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-put.html" + "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/slm-api-put-policy.html" }, "stability":"stable", "url":{