mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 07:37:19 -04:00
214 lines
6.4 KiB
Text
214 lines
6.4 KiB
Text
[[create-snapshot-api]]
|
|
=== Create snapshot API
|
|
++++
|
|
<titleabbrev>Create snapshot</titleabbrev>
|
|
++++
|
|
|
|
<<snapshots-take-snapshot,Takes a snapshot>> of a cluster or specified data
|
|
streams and indices.
|
|
|
|
////
|
|
[source,console]
|
|
-----------------------------------
|
|
PUT /_snapshot/my_repository
|
|
{
|
|
"type": "fs",
|
|
"settings": {
|
|
"location": "my_backup_location"
|
|
}
|
|
}
|
|
-----------------------------------
|
|
// TESTSETUP
|
|
////
|
|
|
|
[source,console]
|
|
-----------------------------------
|
|
PUT /_snapshot/my_repository/my_snapshot
|
|
-----------------------------------
|
|
// TEST[s/my_snapshot/my_snapshot?wait_for_completion=true/]
|
|
|
|
[[create-snapshot-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`PUT /_snapshot/<repository>/<snapshot>`
|
|
|
|
`POST /_snapshot/<repository>/<snapshot>`
|
|
|
|
[[create-snapshot-api-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* If the {es} {security-features} are enabled, you must have the
|
|
`create_snapshot` or `manage` <<privileges-list-cluster,cluster privilege>> to
|
|
use this API.
|
|
|
|
[[create-snapshot-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<repository>`::
|
|
(Required, string)
|
|
Name of the snapshot repository.
|
|
|
|
`<snapshot>`::
|
|
(Required, string)
|
|
Name of the snapshot. Supports <<api-date-math-index-names,date math>>. Must be
|
|
unique within the snapshot repository.
|
|
|
|
[[create-snapshot-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]
|
|
|
|
`wait_for_completion`::
|
|
(Optional, Boolean) If `true`, the request returns a response when the snapshot
|
|
is complete. If `false`, the request returns a response when the snapshot
|
|
initializes. Defaults to `false`.
|
|
|
|
[role="child_attributes"]
|
|
[[create-snapshot-api-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
// Set an attribute so we can reuse these params with anchors
|
|
:page-id: create-snapshot-api
|
|
// tag::snapshot-config[]
|
|
`expand_wildcards`::
|
|
+
|
|
--
|
|
(Optional, string) Determines how wildcard patterns in the `indices` parameter
|
|
match data streams and indices. Supports comma-separated values, such as
|
|
`open,hidden`. Defaults to `all`. Valid values are:
|
|
|
|
`all`:::
|
|
Match any data stream or index, including closed and <<multi-hidden,hidden>> ones.
|
|
|
|
`open`:::
|
|
Match open indices and data streams.
|
|
|
|
`closed`:::
|
|
Match closed indices and data streams.
|
|
|
|
`hidden`:::
|
|
Match hidden data streams and indices. Must be combined with `open`, `closed`,
|
|
or both.
|
|
|
|
`none`:::
|
|
Don't expand wildcard patterns.
|
|
--
|
|
|
|
`ignore_unavailable`::
|
|
(Optional, Boolean)
|
|
If `false`, the snapshot fails if any data stream or index in `indices` is
|
|
missing. If `true`, the snapshot ignores missing data
|
|
streams and indices. Defaults to `false`.
|
|
|
|
`include_global_state`::
|
|
+
|
|
--
|
|
(Optional, Boolean)
|
|
If `true`, include the cluster state in the snapshot. Defaults to `true`.
|
|
The cluster state includes:
|
|
|
|
include::restore-snapshot-api.asciidoc[tag=cluster-state-contents]
|
|
--
|
|
|
|
`indices`::
|
|
(Optional, string or array of strings)
|
|
Comma-separated list of data streams and indices to include in the snapshot.
|
|
Supports <<api-multi-index,multi-target syntax>>. Defaults to an empty array
|
|
(`[]`), which includes all regular data streams and regular indices. To exclude
|
|
all data streams and indices, use `-*`.
|
|
+
|
|
You can't use this parameter to include or exclude <<system-indices,system
|
|
indices or system data streams>> from a snapshot. Use
|
|
<<{page-id}-feature-states,`feature_states`>> instead.
|
|
|
|
[id="{page-id}-feature-states"]
|
|
`feature_states`::
|
|
(Optional, array of strings)
|
|
<<feature-state,Feature states>> to include in the snapshot. To get a list of
|
|
possible values and their descriptions, use the <<get-features-api,get features
|
|
API>>.
|
|
+
|
|
If `include_global_state` is `true`, the snapshot includes all feature states by
|
|
default. If `include_global_state` is `false`, the snapshot includes no feature
|
|
states by default.
|
|
+
|
|
Note that specifying an empty array will result in the default behavior. To
|
|
exclude all feature states, regardless of the `include_global_state` value,
|
|
specify an array with only the value `none` (`["none"]`).
|
|
|
|
`metadata`::
|
|
(Optional, object)
|
|
Attaches arbitrary metadata to the snapshot, such as a record of who took the snapshot, why it was taken, or any other useful data. Metadata must be less than 1024 bytes.
|
|
|
|
[id="{page-id}-partial"]
|
|
`partial`::
|
|
(Optional, Boolean)
|
|
If `false`, the entire snapshot will fail if one or more indices included in the snapshot do not have all primary shards available. Defaults to `false`.
|
|
+
|
|
If `true`, allows taking a partial snapshot of indices with unavailable shards.
|
|
// end::snapshot-config[]
|
|
|
|
// Unset the attribute
|
|
:!page-id:
|
|
|
|
[[create-snapshot-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
The following request takes a snapshot of `index_1` and `index_2`.
|
|
|
|
[source,console]
|
|
-----------------------------------
|
|
PUT /_snapshot/my_repository/snapshot_2?wait_for_completion=true
|
|
{
|
|
"indices": "index_1,index_2",
|
|
"ignore_unavailable": true,
|
|
"include_global_state": false,
|
|
"metadata": {
|
|
"taken_by": "user123",
|
|
"taken_because": "backup before upgrading"
|
|
}
|
|
}
|
|
-----------------------------------
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"snapshot": {
|
|
"snapshot": "snapshot_2",
|
|
"uuid": "vdRctLCxSketdKb54xw67g",
|
|
"repository": "my_repository",
|
|
"version_id": <version_id>,
|
|
"version": <version>,
|
|
"indices": [],
|
|
"data_streams": [],
|
|
"feature_states": [],
|
|
"include_global_state": false,
|
|
"metadata": {
|
|
"taken_by": "user123",
|
|
"taken_because": "backup before upgrading"
|
|
},
|
|
"state": "SUCCESS",
|
|
"start_time": "2020-06-25T14:00:28.850Z",
|
|
"start_time_in_millis": 1593093628850,
|
|
"end_time": "2020-06-25T14:00:28.850Z",
|
|
"end_time_in_millis": 1593094752018,
|
|
"duration_in_millis": 0,
|
|
"failures": [],
|
|
"shards": {
|
|
"total": 0,
|
|
"failed": 0,
|
|
"successful": 0
|
|
}
|
|
}
|
|
}
|
|
----
|
|
// TESTRESPONSE[s/"uuid": "vdRctLCxSketdKb54xw67g"/"uuid": $body.snapshot.uuid/]
|
|
// TESTRESPONSE[s/"version_id": <version_id>/"version_id": $body.snapshot.version_id/]
|
|
// TESTRESPONSE[s/"version": <version>/"version": $body.snapshot.version/]
|
|
// TESTRESPONSE[s/"start_time": "2020-06-25T14:00:28.850Z"/"start_time": $body.snapshot.start_time/]
|
|
// TESTRESPONSE[s/"start_time_in_millis": 1593093628850/"start_time_in_millis": $body.snapshot.start_time_in_millis/]
|
|
// TESTRESPONSE[s/"end_time": "2020-06-25T14:00:28.850Z"/"end_time": $body.snapshot.end_time/]
|
|
// TESTRESPONSE[s/"end_time_in_millis": 1593094752018/"end_time_in_millis": $body.snapshot.end_time_in_millis/]
|
|
// TESTRESPONSE[s/"duration_in_millis": 0/"duration_in_millis": $body.snapshot.duration_in_millis/]
|