mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 07:37:19 -04:00
281 lines
9.7 KiB
Text
281 lines
9.7 KiB
Text
[[restore-snapshot-api]]
|
|
=== Restore snapshot API
|
|
++++
|
|
<titleabbrev>Restore snapshot</titleabbrev>
|
|
++++
|
|
|
|
.New API reference
|
|
[sidebar]
|
|
--
|
|
For the most up-to-date API details, refer to {api-es}/group/endpoint-snapshot[Snapshot and restore APIs].
|
|
--
|
|
|
|
Restores a <<snapshot-restore,snapshot>> of a cluster or specified data streams and indices.
|
|
|
|
////
|
|
[source,console]
|
|
----
|
|
PUT /_snapshot/my_repository
|
|
{
|
|
"type": "fs",
|
|
"settings": {
|
|
"location": "my_backup_location"
|
|
}
|
|
}
|
|
|
|
PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true
|
|
|
|
PUT /index_1
|
|
|
|
PUT /index_2
|
|
|
|
PUT /index_3
|
|
|
|
PUT /index_4
|
|
|
|
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": "Elastic Machine",
|
|
"taken_because": "backup testing"
|
|
}
|
|
}
|
|
|
|
POST /index_1/_close
|
|
|
|
POST /index_2/_close
|
|
|
|
POST /index_3/_close
|
|
|
|
POST /index_4/_close
|
|
|
|
----
|
|
// TESTSETUP
|
|
////
|
|
|
|
[source,console]
|
|
----
|
|
POST /_snapshot/my_repository/my_snapshot/_restore
|
|
----
|
|
// TEST[s/_restore/_restore?wait_for_completion=true/]
|
|
|
|
[[restore-snapshot-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`POST /_snapshot/<repository>/<snapshot>/_restore`
|
|
|
|
[[restore-snapshot-api-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* If you use {es} security features, you must have the `manage` or
|
|
`cluster:admin/snapshot/*` cluster privilege to use this API.
|
|
|
|
// tag::restore-prereqs[]
|
|
* You can only restore a snapshot to a running cluster with an elected
|
|
<<master-node-role,master node>>. The snapshot's repository must be
|
|
<<snapshots-register-repository,registered>> and available to the cluster.
|
|
|
|
* The snapshot and cluster versions must be compatible. See
|
|
<<snapshot-restore-version-compatibility>>.
|
|
|
|
* To restore a snapshot, the cluster's global metadata must be writable. Ensure
|
|
there aren't any <<cluster-read-only,cluster blocks>> that prevent writes. The
|
|
restore operation ignores <<index-modules-blocks,index blocks>>.
|
|
|
|
* Before you restore a data stream, ensure the cluster contains a
|
|
<<create-index-template,matching index template>> with data stream enabled. To
|
|
check, use {kib}'s <<manage-index-templates,**Index Management**>> feature or
|
|
the <<indices-get-template,get index template API>>:
|
|
+
|
|
[source,console]
|
|
----
|
|
GET _index_template/*?filter_path=index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream
|
|
----
|
|
+
|
|
If no such template exists, you can <<create-index-template,create one>> or
|
|
<<restore-entire-cluster,restore a cluster state>> that
|
|
contains one. Without a matching index template, a data stream can't roll over
|
|
or create backing indices.
|
|
|
|
* If your snapshot contains data from App Search or Workplace Search, ensure
|
|
you've restored the {enterprise-search-ref}/encryption-keys.html[Enterprise
|
|
Search encryption key] before restoring the snapshot.
|
|
// end::restore-prereqs[]
|
|
|
|
[[restore-snapshot-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<repository>`::
|
|
(Required, string)
|
|
Name of the repository to restore a snapshot from.
|
|
|
|
`<snapshot>`::
|
|
(Required, string)
|
|
Name of the snapshot to restore.
|
|
|
|
[[restore-snapshot-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]
|
|
|
|
`wait_for_completion`::
|
|
(Optional, Boolean) If `true`, the request returns a response when the restore
|
|
operation completes. The operation is complete when it finishes all attempts to
|
|
<<monitor-restore,recover primary shards>> for restored indices.
|
|
This applies even if one or more of the recovery attempts fail.
|
|
+
|
|
If `false`, the request returns a response when the restore
|
|
operation initializes. Defaults to `false`.
|
|
|
|
[role="child_attributes"]
|
|
[[restore-snapshot-api-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
`ignore_unavailable`::
|
|
(Optional, Boolean) If `true`, the request ignores any index or data stream in
|
|
`indices` that's missing from the snapshot. If `false`, the request returns an
|
|
error for any missing index or data stream. Defaults to `false`.
|
|
|
|
`ignore_index_settings`::
|
|
(Optional, string or array of strings) Index settings to not restore from the snapshot. You can't use this option to ignore <<index-number-of-shards,`index.number_of_shards`>>.
|
|
+
|
|
For data streams, this option only applies to restored backing indices. New
|
|
backing indices are configured using the data stream's matching index template.
|
|
|
|
`include_aliases`::
|
|
(Optional, Boolean)
|
|
If `true`, the request restores aliases for any restored data streams and
|
|
indices. If `false`, the request doesn't restore aliases. Defaults to `true`.
|
|
|
|
[[restore-snapshot-api-include-global-state]]
|
|
`include_global_state`::
|
|
+
|
|
--
|
|
(Optional, Boolean)
|
|
If `true`, restore the cluster state. Defaults to `false`.
|
|
|
|
The cluster state includes:
|
|
|
|
// tag::cluster-state-contents[]
|
|
* <<cluster-setting-types,Persistent cluster settings>>
|
|
* <<index-templates,Index templates>>
|
|
* <<indices-templates-v1,Legacy index templates>>
|
|
* <<ingest,Ingest pipelines>>
|
|
* <<index-lifecycle-management,{ilm-init} policies>>
|
|
* <<script-stored-scripts,Stored scripts>>
|
|
* For snapshots taken after 7.12.0, <<feature-state,feature states>>
|
|
// end::cluster-state-contents[]
|
|
|
|
If `include_global_state` is `true` then the restore operation merges the
|
|
legacy index templates in your cluster with the templates contained in the
|
|
snapshot, replacing any existing ones whose name matches one in the snapshot.
|
|
It completely removes all persistent settings, non-legacy index templates,
|
|
ingest pipelines and {ilm-init} lifecycle policies that exist in your cluster
|
|
and replaces them with the corresponding items from the snapshot.
|
|
|
|
Use the `feature_states` parameter to configure how feature states are restored.
|
|
|
|
If `include_global_state` is `true` and a snapshot was created without a global
|
|
state then the restore request will fail.
|
|
--
|
|
|
|
[[restore-snapshot-api-feature-states]]
|
|
`feature_states`::
|
|
(Optional, array of strings)
|
|
<<feature-state,Feature states>> to restore.
|
|
+
|
|
If `include_global_state` is `true`, the request restores all feature states
|
|
in the snapshot by default. If `include_global_state` is `false`, the request
|
|
restores no feature states by default. Note that specifying an empty array
|
|
will result in the default behavior. To restore no feature states, regardless
|
|
of the `include_global_state` value, specify an array containing only the value
|
|
`none` (`["none"]`).
|
|
|
|
[[restore-snapshot-api-index-settings]]
|
|
`index_settings`::
|
|
(Optional, object) Index settings to add or change in restored indices,
|
|
including backing indices. You can't use this option to change
|
|
<<index-number-of-shards,`index.number_of_shards`>>.
|
|
+
|
|
For data streams, this option only applies to restored backing indices. New
|
|
backing indices are configured using the data stream's matching index template.
|
|
|
|
`indices`::
|
|
(Optional, string or array of strings) Comma-separated list of indices and data
|
|
streams to restore. Supports <<api-multi-index,multi-target syntax>>. Defaults
|
|
to all regular indices and regular data streams in the snapshot.
|
|
+
|
|
You can't use this parameter to restore <<system-indices,system indices or
|
|
system data streams>>. Use
|
|
<<restore-snapshot-api-feature-states,`feature_states`>> instead.
|
|
|
|
[[restore-snapshot-api-partial]]
|
|
`partial`::
|
|
(Optional, Boolean)
|
|
If `false`, the entire restore operation will fail if one or more indices included in the snapshot do not have all primary shards available. Defaults to `false`.
|
|
+
|
|
If `true`, allows restoring a partial snapshot of indices with unavailable shards. Only shards that were successfully included in the snapshot
|
|
will be restored. All missing shards will be recreated as empty.
|
|
|
|
[[restore-snapshot-api-rename-pattern]]
|
|
`rename_pattern`::
|
|
(Optional, string)
|
|
Defines a rename pattern to apply to restored data streams and indices. Data streams and indices matching the rename pattern will be renamed according to
|
|
<<restore-snapshot-api-rename-replacement,`rename_replacement`>>.
|
|
+
|
|
The rename pattern is applied as defined by the regular expression that
|
|
supports referencing the original text, according to the https://docs.oracle.com/javase/8/docs/api/java/util/regex/Matcher.html#appendReplacement-java.lang.StringBuffer-java.lang.String-[`appendReplacement`] logic.
|
|
|
|
[[restore-snapshot-api-rename-replacement]]
|
|
`rename_replacement`::
|
|
(Optional, string)
|
|
Defines the rename replacement string. See <<restore-snapshot-api-rename-pattern,`rename_pattern`>> for more information.
|
|
|
|
[[restore-snapshot-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
[[restore-snapshot-api-example-rename]]
|
|
===== Restore renamed
|
|
|
|
The following request restores `index_1` and `index_2` from `snapshot_2`. The `rename_pattern` and `rename_replacement` parameters indicate any index matching the regular expression `index_(.+)` will be renamed using the pattern `restored_index_$1` when restored.
|
|
|
|
For example, `index_1` will be renamed to `restored_index_1`. `index_2` will be renamed to `restored_index_2`.
|
|
|
|
[source,console]
|
|
----
|
|
POST /_snapshot/my_repository/snapshot_2/_restore?wait_for_completion=true
|
|
{
|
|
"indices": "index_1,index_2",
|
|
"ignore_unavailable": true,
|
|
"include_global_state": false,
|
|
"rename_pattern": "index_(.+)",
|
|
"rename_replacement": "restored_index_$1",
|
|
"include_aliases": false
|
|
}
|
|
----
|
|
|
|
The API returns an acknowledgement if the request succeeds. If the request encounters errors, the response indicates any issues found, such as
|
|
open indices that are blocking the restore operation from completing.
|
|
|
|
[[restore-snapshot-api-example-inplace]]
|
|
===== Restore in-place
|
|
|
|
You may want to restore an index in-place, for example when no alternative
|
|
options surface after the <<cluster-allocation-explain>> API reports
|
|
`no_valid_shard_copy`.
|
|
|
|
The following request <<indices-close,closes>> `index_1` and then restores it
|
|
in-place from the `snapshot_2` snapshot in the `my_repository` repository.
|
|
|
|
[source,console]
|
|
----
|
|
POST index_1/_close
|
|
|
|
POST /_snapshot/my_repository/snapshot_2/_restore?wait_for_completion=true
|
|
{
|
|
"indices": "index_1"
|
|
}
|
|
----
|