mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-24 15:17:30 -04:00
[DOCS] Align with ILM API docs (#48705)
* [DOCS] Reconciled with Snapshot/Restore reorg
This commit is contained in:
debadair
GitHub
parent
f3c66ef158
commit
ec9437832d
27 changed files with 906 additions and 900 deletions
72
docs/reference/slm/apis/index.asciidoc
Normal file
72
docs/reference/slm/apis/index.asciidoc
Normal file
|
|
@ -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) <<snapshot-lifecycle-management-api, CRUD APIs>> 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[]
|
||||
44
docs/reference/slm/apis/slm-api.asciidoc
Normal file
44
docs/reference/slm/apis/slm-api.asciidoc
Normal file
|
|
@ -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 <<snapshot-lifecycle-management>>.
|
||||
|
||||
[float]
|
||||
[[slm-api-policy-endpoint]]
|
||||
=== Policy management APIs
|
||||
|
||||
* <<slm-api-put-policy,Create lifecycle policy>>
|
||||
* <<slm-api-get-policy,Get lifecycle policy>>
|
||||
* <<slm-api-delete-policy,Delete lifecycle policy>>
|
||||
|
||||
[float]
|
||||
[[slm-api-index-endpoint]]
|
||||
=== Snapshot management APIs
|
||||
|
||||
* <<slm-api-execute-lifecycle,Execute snapshot lifecycle policy>> (take snapshots)
|
||||
* <<slm-api-execute-retention,Execute snapshot retention policy>> (delete expired snapshots)
|
||||
|
||||
[float]
|
||||
[[slm-api-management-endpoint]]
|
||||
=== Operation management APIs
|
||||
|
||||
* <<slm-api-get-status,Get {slm-init} status>>
|
||||
* <<slm-api-get-stats,Get global and policy-level action statistics>>
|
||||
* <<slm-api-start,Start {slm-init}>>
|
||||
* <<slm-api-stop,Stop {slm-init}>>
|
||||
|
||||
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[]
|
||||
67
docs/reference/slm/apis/slm-delete.asciidoc
Normal file
67
docs/reference/slm/apis/slm-delete.asciidoc
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
[[slm-api-delete-policy]]
|
||||
=== Delete snapshot lifecycle policy API
|
||||
++++
|
||||
<titleabbrev>Delete policy</titleabbrev>
|
||||
++++
|
||||
|
||||
Deletes an existing snapshot lifecycle policy.
|
||||
|
||||
[[slm-api-delete-lifecycle-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`DELETE /_slm/policy/<snapshot-lifecycle-policy-id>`
|
||||
|
||||
[[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
|
||||
<<security-privileges>>.
|
||||
|
||||
[[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}
|
||||
|
||||
`<policy-id>`::
|
||||
(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": "<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]
|
||||
////
|
||||
|
||||
[source,console]
|
||||
--------------------------------------------------
|
||||
DELETE /_slm/policy/daily-snapshots
|
||||
--------------------------------------------------
|
||||
// TEST[continued]
|
||||
37
docs/reference/slm/apis/slm-execute-retention.asciidoc
Normal file
37
docs/reference/slm/apis/slm-execute-retention.asciidoc
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
[[slm-api-execute-retention]]
|
||||
=== Execute snapshot retention policy API
|
||||
++++
|
||||
<titleabbrev>Execute snapshot retention policy</titleabbrev>
|
||||
++++
|
||||
|
||||
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
|
||||
<<security-privileges>>.
|
||||
|
||||
[[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.
|
||||
61
docs/reference/slm/apis/slm-execute.asciidoc
Normal file
61
docs/reference/slm/apis/slm-execute.asciidoc
Normal file
|
|
@ -0,0 +1,61 @@
|
|||
[[slm-api-execute-lifecycle]]
|
||||
=== Execute snapshot lifecycle policy API
|
||||
++++
|
||||
<titleabbrev>Execute snapshot lifecycle policy</titleabbrev>
|
||||
++++
|
||||
|
||||
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/<snapshot-lifecycle-policy-id>/_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
|
||||
<<security-privileges>>.
|
||||
|
||||
[[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}
|
||||
|
||||
`<policy-id>`::
|
||||
(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<<modules-snapshots,snapshot APIs>> to monitor the status of the snapshot.
|
||||
|
||||
To see the status of a policy's most recent snapshot, you can use the <<slm-api-get-policy>>.
|
||||
53
docs/reference/slm/apis/slm-get-status.asciidoc
Normal file
53
docs/reference/slm/apis/slm-get-status.asciidoc
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
[[slm-api-get-status]]
|
||||
=== Get {slm} status API
|
||||
|
||||
[subs="attributes"]
|
||||
++++
|
||||
<titleabbrev>Get {slm} status</titleabbrev>
|
||||
++++
|
||||
|
||||
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
|
||||
<<slm-api-stop, stop>> and <<slm-api-start, start>> 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 <<security-privileges>>.
|
||||
|
||||
[[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/]
|
||||
124
docs/reference/slm/apis/slm-get.asciidoc
Normal file
124
docs/reference/slm/apis/slm-get.asciidoc
Normal file
|
|
@ -0,0 +1,124 @@
|
|||
[[slm-api-get-policy]]
|
||||
=== Get snapshot lifecycle policy API
|
||||
++++
|
||||
<titleabbrev>Get policy</titleabbrev>
|
||||
++++
|
||||
|
||||
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/<policy-id>`
|
||||
|
||||
`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
|
||||
<<security-privileges>>.
|
||||
|
||||
[[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}
|
||||
|
||||
`<policy-id>`::
|
||||
(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": "<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]
|
||||
////
|
||||
|
||||
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": "<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]
|
||||
177
docs/reference/slm/apis/slm-put.asciidoc
Normal file
177
docs/reference/slm/apis/slm-put.asciidoc
Normal file
|
|
@ -0,0 +1,177 @@
|
|||
[[slm-api-put-policy]]
|
||||
=== Put snapshot lifecycle policy API
|
||||
++++
|
||||
<titleabbrev>Put 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 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 <<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 a 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}
|
||||
|
||||
Create a `daily-snapshots` lifecycle policy:
|
||||
|
||||
[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
|
||||
51
docs/reference/slm/apis/slm-start.asciidoc
Normal file
51
docs/reference/slm/apis/slm-start.asciidoc
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
[[slm-api-start]]
|
||||
=== Start {slm} API
|
||||
|
||||
[subs="attributes"]
|
||||
++++
|
||||
<titleabbrev>Start {slm}</titleabbrev>
|
||||
++++
|
||||
|
||||
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
|
||||
<<security-privileges>>.
|
||||
|
||||
[[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 <<slm-api-stop>>.
|
||||
|
||||
==== {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
|
||||
}
|
||||
--------------------------------------------------
|
||||
46
docs/reference/slm/apis/slm-stats.asciidoc
Normal file
46
docs/reference/slm/apis/slm-stats.asciidoc
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
[[slm-api-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-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
|
||||
<<security-privileges>>.
|
||||
|
||||
[[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/]
|
||||
48
docs/reference/slm/apis/slm-stop.asciidoc
Normal file
48
docs/reference/slm/apis/slm-stop.asciidoc
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
[[slm-api-stop]]
|
||||
=== Stop {slm} API
|
||||
|
||||
[subs="attributes"]
|
||||
++++
|
||||
<titleabbrev>Stop {slm}</titleabbrev>
|
||||
++++
|
||||
|
||||
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
|
||||
<<security-privileges>>.
|
||||
|
||||
[[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 <<slm-api-execute-lifecycle>> 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 <<slm-api-get-status>> 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
|
||||
--------------------------------------------------
|
||||
Loading…
Add table
Add a link
Reference in a new issue