|
|
@@ -1,187 +1,513 @@
|
|
|
[[snapshots-restore-snapshot]]
|
|
|
== Restore a snapshot
|
|
|
|
|
|
-////
|
|
|
+This guide shows you how to restore a snapshot. Snapshots are a convenient way
|
|
|
+to store a copy of your data outside of a cluster. You can restore a snapshot
|
|
|
+to recover indices and data streams after deletion or a hardware failure. You
|
|
|
+can also use snapshots to transfer data between clusters.
|
|
|
+
|
|
|
+In this guide, you'll learn how to:
|
|
|
+
|
|
|
+* Get a list of available snapshots
|
|
|
+* Restore an index or data stream from a snapshot
|
|
|
+* Restore an entire cluster
|
|
|
+* Monitor the restore operation
|
|
|
+* Cancel an ongoing restore
|
|
|
+
|
|
|
+This guide also provides tips for <<restore-different-cluster,restoring to
|
|
|
+another cluster>> and <<troubleshoot-restore,troubleshooting common restore
|
|
|
+errors>>.
|
|
|
+
|
|
|
+[discrete]
|
|
|
+[[restore-snapshot-prereqs]]
|
|
|
+=== Prerequisites
|
|
|
+
|
|
|
+include::apis/restore-snapshot-api.asciidoc[tag=restore-prereqs]
|
|
|
+
|
|
|
+[discrete]
|
|
|
+[[restore-snapshot-considerations]]
|
|
|
+=== Considerations
|
|
|
+
|
|
|
+When restoring data from a snapshot, keep the following in mind:
|
|
|
+
|
|
|
+* If you restore a data stream, you also restore its backing indices.
|
|
|
+
|
|
|
+* You can only restore an existing index if it's <<indices-close,closed>> and
|
|
|
+the index in the snapshot has the same number of primary shards.
|
|
|
+
|
|
|
+* You can't restore an existing open index. This includes
|
|
|
+backing indices for a data stream.
|
|
|
+
|
|
|
+* The restore operation automatically opens restored indices, including backing
|
|
|
+indices.
|
|
|
+
|
|
|
+* You can restore only a specific backing index from a data stream. However, the
|
|
|
+restore operation doesn't add the restored backing index to any existing data
|
|
|
+stream.
|
|
|
+
|
|
|
+[discrete]
|
|
|
+[[get-snapshot-list]]
|
|
|
+=== Get a list of available snapshots
|
|
|
+
|
|
|
+To view a list of available snapshots in {kib}, go to the main menu and click
|
|
|
+*Stack Management > Snapshot and Restore*.
|
|
|
+
|
|
|
+You can also use the <<get-snapshot-repo-api,get repository API>> and the
|
|
|
+<<get-snapshot-api,get snapshot API>> to find snapshots that are available to
|
|
|
+restore. First, use the get repository API to fetch a list of registered
|
|
|
+snapshot repositories.
|
|
|
+
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+GET _snapshot
|
|
|
+----
|
|
|
+// TEST[setup:setup-snapshots]
|
|
|
+
|
|
|
+Then use the get snapshot API to get a list of snapshots in a specific
|
|
|
+repository.
|
|
|
+
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+GET _snapshot/my_repository/*?verbose=false
|
|
|
+----
|
|
|
+// TEST[setup:setup-snapshots]
|
|
|
+
|
|
|
+[discrete]
|
|
|
+[[restore-index-data-stream]]
|
|
|
+=== Restore an index or data stream
|
|
|
+
|
|
|
+You can restore a snapshot using {kib}'s *Snapshot and Restore* feature or the
|
|
|
+<<restore-snapshot-api,restore snapshot API>>.
|
|
|
+
|
|
|
+In most cases, you only need to restore a specific index or data stream from a
|
|
|
+snapshot. However, you can't restore an existing open index.
|
|
|
+
|
|
|
+To avoid conflicts with existing indices and data streams, use one of the
|
|
|
+following methods:
|
|
|
+
|
|
|
+* <<delete-restore>>
|
|
|
+* <<rename-on-restore>>
|
|
|
+
|
|
|
+[discrete]
|
|
|
+[[delete-restore]]
|
|
|
+==== Delete and restore
|
|
|
+
|
|
|
+The simplest way to avoid conflicts is to delete an existing index or data
|
|
|
+stream before restoring it. To prevent the accidental re-creation of the index
|
|
|
+or data stream, we recommend you temporarily stop all indexing until the restore
|
|
|
+operation is complete.
|
|
|
+
|
|
|
+WARNING: If the
|
|
|
+<<action-destructive-requires-name,`action.destructive_requires_name`>> cluster
|
|
|
+setting is `false`, don't use the <<indices-delete-index,delete index API>> to
|
|
|
+target the `*` or `.*` wildcard expression. If you use {es}'s security features,
|
|
|
+this will delete system indices required for authentication. To delete all
|
|
|
+regular indices, use `*,-.*` instead.
|
|
|
+
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+# Delete an index
|
|
|
+DELETE my-index
|
|
|
+
|
|
|
+# Delete a data stream
|
|
|
+DELETE _data_stream/logs-my_app-default
|
|
|
+----
|
|
|
+// TEST[setup:setup-snapshots]
|
|
|
+
|
|
|
+By default, a restore request attempts to restore all indices and data
|
|
|
+streams in the snapshot, including system indices. If your cluster already
|
|
|
+contains one or more of these system indices, the request will return an error.
|
|
|
+
|
|
|
+To avoid this error, specify the indices and data streams to restore. To
|
|
|
+exclude system indices, append the `-.*` wildcard pattern. To restore all
|
|
|
+indices and data streams except system indices, use `*,-.*`.
|
|
|
+
|
|
|
[source,console]
|
|
|
------------------------------------
|
|
|
-PUT /_snapshot/my_backup
|
|
|
+----
|
|
|
+POST _snapshot/my_repository/my_snapshot_2099.05.06/_restore
|
|
|
{
|
|
|
- "type": "fs",
|
|
|
- "settings": {
|
|
|
- "location": "my_backup_location"
|
|
|
- }
|
|
|
+ "indices": "my-index,logs-my_app-default"
|
|
|
}
|
|
|
+----
|
|
|
+// TEST[continued]
|
|
|
+// TEST[s/_restore/_restore?wait_for_completion=true/]
|
|
|
|
|
|
-PUT /_snapshot/my_backup/snapshot_1?wait_for_completion=true
|
|
|
------------------------------------
|
|
|
-// TESTSETUP
|
|
|
+[discrete]
|
|
|
+[[rename-on-restore]]
|
|
|
+==== Rename on restore
|
|
|
|
|
|
-////
|
|
|
+If you want to avoid deleting existing data, you can instead
|
|
|
+rename the indices and data streams you restore. You typically use this method
|
|
|
+to compare existing data to historical data from a snapshot. For example, you
|
|
|
+can use this method to review documents after an accidental update or deletion.
|
|
|
+
|
|
|
+Before you start, ensure the cluster has enough capacity for both the existing
|
|
|
+and restored data.
|
|
|
|
|
|
-Use the <<restore-snapshot-api,restore snapshot API>> to restore
|
|
|
-a snapshot of a cluster or specified data streams and indices:
|
|
|
+The following restore snapshot API request prepends `restored-` to the name of
|
|
|
+any restored index or data stream.
|
|
|
|
|
|
[source,console]
|
|
|
------------------------------------
|
|
|
-POST /_snapshot/my_backup/snapshot_1/_restore
|
|
|
------------------------------------
|
|
|
+----
|
|
|
+POST _snapshot/my_repository/my_snapshot_2099.05.06/_restore
|
|
|
+{
|
|
|
+ "indices": "my-index,logs-my_app-default",
|
|
|
+ "rename_pattern": "(.+)",
|
|
|
+ "rename_replacement": "restored-$1"
|
|
|
+}
|
|
|
+----
|
|
|
+// TEST[setup:setup-snapshots]
|
|
|
// TEST[s/_restore/_restore?wait_for_completion=true/]
|
|
|
|
|
|
-By default, all data streams and indices in the snapshot are restored, but the cluster state is
|
|
|
-*not* restored. Use the `indices` parameter to restore only specific data streams or indices. This parameter
|
|
|
-supports <<api-multi-index,multi-target syntax>>. To include the global cluster state, set
|
|
|
-`include_global_state` to `true` in the restore request body.
|
|
|
+If the rename options produce two or more indices or data streams with the same
|
|
|
+name, the restore operation fails.
|
|
|
|
|
|
-Because all indices in the snapshot are restored by default, all system indices will be restored
|
|
|
-by default as well.
|
|
|
+If you rename a data stream, its backing indices are also renamed. For example,
|
|
|
+if you rename the `logs-my_app-default` data stream to
|
|
|
+`restored-logs-my_app-default`, the backing index
|
|
|
+`.ds-logs-my_app-default-2099.03.09-000005` is renamed to
|
|
|
+`.ds-restored-logs-my_app-default-2099.03.09-000005`.
|
|
|
|
|
|
-[WARNING]
|
|
|
-====
|
|
|
-Each data stream requires a matching
|
|
|
-<<create-index-template,index template>>. The stream uses this
|
|
|
-template to create new backing indices.
|
|
|
+When the restore operation is complete, you can compare the original and
|
|
|
+restored data. If you no longer need an original index or data stream, you can
|
|
|
+delete it and use a <<docs-reindex,reindex>> to rename the restored one.
|
|
|
|
|
|
-When restoring a data stream, ensure a matching template exists for the stream.
|
|
|
-You can do this using one of the following methods:
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+# Delete the original index
|
|
|
+DELETE my-index
|
|
|
|
|
|
-* Check for existing templates that match the stream. If no matching template
|
|
|
- exists, <<create-index-template,create one>>.
|
|
|
+# Reindex the restored index to rename it
|
|
|
+POST _reindex
|
|
|
+{
|
|
|
+ "source": {
|
|
|
+ "index": "restored-my-index"
|
|
|
+ },
|
|
|
+ "dest": {
|
|
|
+ "index": "my-index"
|
|
|
+ }
|
|
|
+}
|
|
|
|
|
|
-* Restore a global cluster state that includes a matching template for the
|
|
|
- stream.
|
|
|
+# Delete the original data stream
|
|
|
+DELETE _data_stream/logs-my_app-default
|
|
|
|
|
|
-If no index template matches a data stream, the stream cannot
|
|
|
-<<manually-roll-over-a-data-stream,roll over>> or create new backing indices.
|
|
|
-====
|
|
|
+# Reindex the restored data stream to rename it
|
|
|
+POST _reindex
|
|
|
+{
|
|
|
+ "source": {
|
|
|
+ "index": "restored-logs-my_app-default"
|
|
|
+ },
|
|
|
+ "dest": {
|
|
|
+ "index": "logs-my_app-default",
|
|
|
+ "op_type": "create"
|
|
|
+ }
|
|
|
+}
|
|
|
+----
|
|
|
+// TEST[continued]
|
|
|
|
|
|
-The `rename_pattern`
|
|
|
-and `rename_replacement` options can be also used to rename data streams and indices on restore
|
|
|
-using 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.
|
|
|
+[discrete]
|
|
|
+[[restore-entire-cluster]]
|
|
|
+=== Restore an entire cluster
|
|
|
+
|
|
|
+In some cases, you need to restore an entire cluster from a snapshot, including
|
|
|
+the cluster state and all system indices. These cases should be rare, such as in
|
|
|
+the event of a catastrophic failure.
|
|
|
+
|
|
|
+Restoring an entire cluster involves deleting important system indices, including
|
|
|
+those used for authentication. Consider whether you can restore specific indices
|
|
|
+or data streams instead.
|
|
|
|
|
|
-[[rename-restored-data-stream]]
|
|
|
-// tag::rename-restored-data-stream-tag[]
|
|
|
-If you rename a restored data stream, its backing indices are also
|
|
|
-renamed. For example, if you rename the `logs` data stream to `restored-logs`,
|
|
|
-the backing index `.ds-logs-2099.03.09-000005` is renamed to
|
|
|
-`.ds-restored-logs-2099.03.09-000005`.
|
|
|
+If you're restoring to a different cluster, see <<restore-different-cluster>>
|
|
|
+before you start.
|
|
|
+
|
|
|
+. If you <<backup-cluster-configuration,backed up the cluster's configuration
|
|
|
+files>>, you can restore them to each node. This step is optional and requires a
|
|
|
+<<restart-upgrade,full cluster restart>>.
|
|
|
++
|
|
|
+After you shut down a node, copy the backed-up configuration files over to the
|
|
|
+node's `$ES_PATH_CONF` directory. Before restarting the node, ensure
|
|
|
+`elasticsearch.yml` contains the appropriate node roles, node name, and
|
|
|
+other node-specific settings.
|
|
|
++
|
|
|
+If you choose to perform this step, you must repeat this process on each node in
|
|
|
+the cluster.
|
|
|
|
|
|
-[WARNING]
|
|
|
-====
|
|
|
-If you rename a restored stream, ensure an index template matches the new stream
|
|
|
-name. If no index template matches the stream, it cannot
|
|
|
-<<manually-roll-over-a-data-stream,roll over>> or create new backing indices.
|
|
|
-====
|
|
|
-// end::rename-restored-data-stream-tag[]
|
|
|
+. Temporarily stop indexing and turn off the following features:
|
|
|
++
|
|
|
+--
|
|
|
+* ILM
|
|
|
++
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+POST _ilm/stop
|
|
|
+----
|
|
|
|
|
|
-To prevent aliases from being restored with their associated data streams and
|
|
|
-indices, set `include_aliases` to `false`.
|
|
|
+////
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+POST _ilm/start
|
|
|
+----
|
|
|
+// TEST[continued]
|
|
|
+////
|
|
|
+
|
|
|
+* Machine Learning
|
|
|
++
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+POST _ml/set_upgrade_mode?enabled=true
|
|
|
+----
|
|
|
+
|
|
|
+////
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+POST _ml/set_upgrade_mode?enabled=false
|
|
|
+----
|
|
|
+// TEST[continued]
|
|
|
+////
|
|
|
|
|
|
+////
|
|
|
[source,console]
|
|
|
------------------------------------
|
|
|
-POST /_snapshot/my_backup/snapshot_1/_restore
|
|
|
+----
|
|
|
+PUT _cluster/settings
|
|
|
{
|
|
|
- "indices": "data_stream_1,index_1,index_2",
|
|
|
- "ignore_unavailable": true,
|
|
|
- "include_global_state": false, <1>
|
|
|
- "rename_pattern": "index_(.+)",
|
|
|
- "rename_replacement": "restored_index_$1",
|
|
|
- "include_aliases": false
|
|
|
+ "persistent": {
|
|
|
+ "xpack.monitoring.collection.enabled": true
|
|
|
+ }
|
|
|
}
|
|
|
------------------------------------
|
|
|
+----
|
|
|
// TEST[continued]
|
|
|
+////
|
|
|
|
|
|
-<1> By default, `include_global_state` is `false`, meaning the snapshot's
|
|
|
-cluster state and feature states are not restored.
|
|
|
+* Watcher
|
|
|
+
|
|
|
-If `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.
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+POST _watcher/_stop
|
|
|
+----
|
|
|
|
|
|
-The restore operation must be performed on a functioning cluster. However, an
|
|
|
-existing index can only be restored if it's <<indices-close,closed>> and
|
|
|
-has the same number of shards as the index in the snapshot. The restore
|
|
|
-operation automatically opens restored indices if they were closed and creates
|
|
|
-new indices if they didn't exist in the cluster.
|
|
|
+////
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+POST _watcher/_start
|
|
|
+----
|
|
|
+// TEST[continued]
|
|
|
+////
|
|
|
+--
|
|
|
|
|
|
-If a data stream is restored, its backing indices are also restored. The restore
|
|
|
-operation automatically opens restored backing indices if they were closed.
|
|
|
+. If you use {es} security features, log in to a node host, navigate to the {es}
|
|
|
+installation directory, and add a user with the `superuser` role to the file
|
|
|
+realm using the <<users-command,`elasticsearch-users`>> tool.
|
|
|
++
|
|
|
+For example, the following command creates a user named `restore_user`.
|
|
|
++
|
|
|
+[source,sh]
|
|
|
+----
|
|
|
+./bin/elasticsearch-users useradd restore_user -p my_password -r superuser
|
|
|
+----
|
|
|
++
|
|
|
+Use this file realm user to authenticate requests until the restore operation is
|
|
|
+complete.
|
|
|
|
|
|
-In addition to entire data streams, you can restore only specific backing
|
|
|
-indices from a snapshot. However, restored backing indices are not automatically
|
|
|
-added to any existing data streams. For example, if only the
|
|
|
-`.ds-logs-2099.03.08-000003` backing index is restored from a snapshot, it is
|
|
|
-not automatically added to the existing `logs` data stream.
|
|
|
+. Use the <<cluster-update-settings,update cluster settings API>> to set
|
|
|
+<<action-destructive-requires-name,`action.destructive_requires_name`>> to
|
|
|
+`false`. This lets you delete indices and data streams using wildcards.
|
|
|
++
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+PUT _cluster/settings
|
|
|
+{
|
|
|
+ "persistent": {
|
|
|
+ "action.destructive_requires_name": false
|
|
|
+ }
|
|
|
+}
|
|
|
+----
|
|
|
+// TEST[setup:setup-snapshots]
|
|
|
|
|
|
-[discrete]
|
|
|
-=== Partial restore
|
|
|
+. Delete all existing indices and data streams on the cluster, including all
|
|
|
+system indices.
|
|
|
++
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+# Delete all indices
|
|
|
+DELETE *
|
|
|
|
|
|
-By default, the entire restore operation will fail if one or more indices or backing indices participating in the operation don't have
|
|
|
-snapshots of all shards available. It can occur if some shards failed to snapshot for example. It is still possible to
|
|
|
-restore such indices by setting `partial` to `true`. Please note, that only successfully snapshotted shards will be
|
|
|
-restored in this case and all missing shards will be recreated empty.
|
|
|
+# Delete all data streams
|
|
|
+DELETE _data_stream/*
|
|
|
+----
|
|
|
+// TEST[continued]
|
|
|
|
|
|
+. Restore the entire snapshot, including the cluster state. This also restores
|
|
|
+any system indices in the snapshot.
|
|
|
++
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+POST _snapshot/my_repository/my_snapshot_2099.05.06/_restore
|
|
|
+{
|
|
|
+ "indices": "*",
|
|
|
+ "include_global_state": true
|
|
|
+}
|
|
|
+----
|
|
|
+// TEST[continued]
|
|
|
+// TEST[s/_restore/_restore?wait_for_completion=true/]
|
|
|
|
|
|
-[discrete]
|
|
|
-[[change-index-settings-during-restore]]
|
|
|
-=== Changing index settings during restore
|
|
|
+. When the restore operation is complete, resume indexing and restart any
|
|
|
+features you stopped:
|
|
|
++
|
|
|
+--
|
|
|
+* ILM
|
|
|
++
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+POST _ilm/start
|
|
|
+----
|
|
|
|
|
|
-Use the <<restore-snapshot-api-index-settings,`index_settings`>> parameter
|
|
|
-to override index settings during the restore process. For example, the
|
|
|
-following request will restore the index `index_1` without creating any
|
|
|
-replicas while switching back to the default refresh interval:
|
|
|
+* Machine Learning
|
|
|
++
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+POST _ml/set_upgrade_mode?enabled=false
|
|
|
+----
|
|
|
|
|
|
+* Watcher
|
|
|
++
|
|
|
[source,console]
|
|
|
------------------------------------
|
|
|
-POST /_snapshot/my_backup/snapshot_1/_restore
|
|
|
+----
|
|
|
+POST _watcher/_start
|
|
|
+----
|
|
|
+--
|
|
|
+
|
|
|
+. If wanted, reset the `action.destructive_requires_name` cluster setting.
|
|
|
++
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+PUT _cluster/settings
|
|
|
{
|
|
|
- "indices": "index_1",
|
|
|
- "ignore_unavailable": true,
|
|
|
- "index_settings": {
|
|
|
- "index.number_of_replicas": 0
|
|
|
- },
|
|
|
- "ignore_index_settings": [
|
|
|
- "index.refresh_interval"
|
|
|
- ]
|
|
|
+ "persistent": {
|
|
|
+ "action.destructive_requires_name": null
|
|
|
+ }
|
|
|
}
|
|
|
------------------------------------
|
|
|
-// TEST[continued]
|
|
|
+----
|
|
|
|
|
|
-NOTE: Some settings such as `index.number_of_shards` cannot be changed during the restore operation.
|
|
|
+[discrete]
|
|
|
+[[monitor-restore]]
|
|
|
+=== Monitor a restore
|
|
|
|
|
|
-For data streams, these index settings are applied to the restored backing
|
|
|
-indices.
|
|
|
+The restore operation uses the <<indices-recovery,shard recovery process>> to
|
|
|
+restore an index's primary shards from a snapshot. While the restore operation
|
|
|
+recovers primary shards, the cluster will have a `yellow`
|
|
|
+<<cluster-health,health status>>.
|
|
|
+
|
|
|
+After all primary shards are recovered, the replication process creates and
|
|
|
+distributes replicas across eligible data nodes. When replication is complete,
|
|
|
+the cluster health status typically becomes `green`.
|
|
|
+
|
|
|
+You can monitor the cluster health status using the <<cluster-health,cluster
|
|
|
+health API>>.
|
|
|
+
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+GET _cluster/health
|
|
|
+----
|
|
|
+
|
|
|
+To get detailed information about ongoing shard recoveries, use the
|
|
|
+<<indices-recovery,index recovery API>>.
|
|
|
|
|
|
-// tag::index-settings-data-stream-warning[]
|
|
|
-[IMPORTANT]
|
|
|
-====
|
|
|
-The `index_settings` and `ignore_index_settings` parameters affect
|
|
|
-restored backing indices only. New backing indices created for a stream use the index
|
|
|
-settings specified in the stream's matching
|
|
|
-<<create-index-template,index template>>.
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+GET my-index/_recovery
|
|
|
+----
|
|
|
+// TEST[setup:setup-snapshots]
|
|
|
+
|
|
|
+To view any unassigned shards, use the <<cat-shards,cat shards API>>.
|
|
|
+
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+GET _cat/shards?v=true&h=index,shard,prirep,state,node,unassigned.reason&s=state
|
|
|
+----
|
|
|
+
|
|
|
+Unassigned shards have a `state` of `UNASSIGNED`. The `prirep` value is `p` for
|
|
|
+primary shards and `r` for replicas. The `unassigned.reason` describes why the
|
|
|
+shard remains unassigned.
|
|
|
|
|
|
-If you change index settings during a restore, we recommend you make similar
|
|
|
-changes in the stream's matching index template. This ensures new backing
|
|
|
-indices created for the stream use the same index settings.
|
|
|
-====
|
|
|
-// end::index-settings-data-stream-warning[]
|
|
|
+To get a more in-depth explanation of an unassigned shard's allocation status,
|
|
|
+use the <<cluster-allocation-explain,cluster allocation explanation API>>.
|
|
|
+
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+GET _cluster/allocation/explain?filter_path=index,node_allocation_decisions.node_name,node_allocation_decisions.deciders.*
|
|
|
+{
|
|
|
+ "index": "my-index",
|
|
|
+ "shard": 0,
|
|
|
+ "primary": false,
|
|
|
+ "current_node": "my-node"
|
|
|
+}
|
|
|
+----
|
|
|
+// TEST[s/^/PUT my-index\n/]
|
|
|
+// TEST[s/"primary": false,/"primary": false/]
|
|
|
+// TEST[s/"current_node": "my-node"//]
|
|
|
|
|
|
[discrete]
|
|
|
-=== Restoring to a different cluster
|
|
|
+[[cancel-restore]]
|
|
|
+=== Cancel a restore
|
|
|
|
|
|
-The information stored in a snapshot is not tied to a particular cluster or a cluster name. Therefore, it's possible to
|
|
|
-restore a snapshot created from one cluster into another cluster by registering the repository that contains the snapshot in the new cluster and starting the restore process.
|
|
|
+You can delete an index or data stream to cancel its ongoing restore. This also
|
|
|
+deletes any existing data in the cluster for the index or data stream. Deleting
|
|
|
+an index or data stream doesn't affect the snapshot or its data.
|
|
|
|
|
|
-The topology of the new cluster does not have to match the cluster where the snapshot was created. However, the version of the new cluster must be the same or only one major version newer than the cluster that was used to create the snapshot. For example, you can restore a 5.x snapshot to a 6.x cluster, but not a 5.x snapshot to a 7.x cluster.
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+# Delete an index
|
|
|
+DELETE my-index
|
|
|
|
|
|
-If the new cluster has a smaller capacity, consider the following changes:
|
|
|
+# Delete a data stream
|
|
|
+DELETE _data_stream/logs-my_app-default
|
|
|
+----
|
|
|
+// TEST[setup:setup-snapshots]
|
|
|
|
|
|
-* Ensure that the new cluster has enough capacity to store all data streams and indices in the snapshot.
|
|
|
-* Change the index settings during the restore operation to reduce the
|
|
|
-<<dynamic-index-number-of-replicas,number of replicas>>.
|
|
|
-* Use the `indices` parameter to choose only specific data streams or indices to restore.
|
|
|
+[discrete]
|
|
|
+[[restore-different-cluster]]
|
|
|
+=== Restore to a different cluster
|
|
|
+
|
|
|
+TIP: {ess} can help you restore snapshots from other deployments. See
|
|
|
+{cloud}/ec-restoring-snapshots.html#ec-restore-across-clusters[Restore across
|
|
|
+clusters].
|
|
|
+
|
|
|
+Snapshots aren't tied to a particular cluster or a cluster name. You can create
|
|
|
+a snapshot in one cluster and restore it in another
|
|
|
+<<snapshot-restore-version-compatibility,compatible cluster>>. The topology of
|
|
|
+the clusters doesn't need to match.
|
|
|
+
|
|
|
+To restore a snapshot, its repository must be
|
|
|
+<<snapshots-register-repository,registered>> and available to the new cluster.
|
|
|
+If the original cluster still has write access to the repository, register the
|
|
|
+repository in `readonly` mode. This prevents multiple clusters from writing to
|
|
|
+the repository at the same time and corrupting the repository's contents.
|
|
|
+
|
|
|
+Before you start a restore operation, ensure the new cluster has enough capacity
|
|
|
+for any data streams or indices you want to restore. If the new cluster has a
|
|
|
+smaller capacity, you can:
|
|
|
+
|
|
|
+* Add nodes or upgrade your hardware to increase capacity.
|
|
|
+* Restore fewer indices and data streams.
|
|
|
+* Reduce the <<dynamic-index-number-of-replicas,number of replicas>> for
|
|
|
+restored indices.
|
|
|
++
|
|
|
+For example, the following restore snapshot API request uses the
|
|
|
+`index_settings` option to set `index.number_of_replicas` to `1`.
|
|
|
++
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+POST _snapshot/my_repository/my_snapshot_2099.05.06/_restore
|
|
|
+{
|
|
|
+ "indices": "my-index,logs-my_app-default",
|
|
|
+ "index_settings": {
|
|
|
+ "index.number_of_replicas": 1
|
|
|
+ }
|
|
|
+}
|
|
|
+----
|
|
|
+// TEST[setup:setup-snapshots]
|
|
|
+// TEST[s/^/DELETE my-index\nDELETE _data_stream\/logs-my_app-default\n/]
|
|
|
+// TEST[s/_restore/_restore?wait_for_completion=true/]
|
|
|
|
|
|
If indices or backing indices in the original cluster were assigned to particular nodes using
|
|
|
<<shard-allocation-filtering,shard allocation filtering>>, the same rules will be enforced in the new cluster. If the new cluster does not contain nodes with appropriate attributes that a restored index can be allocated on, the
|
|
|
@@ -190,3 +516,24 @@ index will not be successfully restored unless these index allocation settings a
|
|
|
The restore operation also checks that restored persistent settings are compatible with the current cluster to avoid accidentally
|
|
|
restoring incompatible settings. If you need to restore a snapshot with incompatible persistent settings, try restoring it without
|
|
|
the <<restore-snapshot-api-include-global-state,global cluster state>>.
|
|
|
+
|
|
|
+[discrete]
|
|
|
+[[troubleshoot-restore]]
|
|
|
+=== Troubleshoot restore errors
|
|
|
+
|
|
|
+Here's how to resolve common errors returned by restore requests.
|
|
|
+
|
|
|
+[discrete]
|
|
|
+==== Cannot restore index [<index>] because an open index with same name already exists in the cluster
|
|
|
+
|
|
|
+You can't restore an open index that already exists. To resolve this error, try
|
|
|
+one of the methods in <<restore-index-data-stream>>.
|
|
|
+
|
|
|
+[discrete]
|
|
|
+==== Cannot restore index [<index>] with [x] shards from a snapshot of index [<snapshot-index>] with [y] shards
|
|
|
+
|
|
|
+You can only restore an existing index if it's closed and the index in the
|
|
|
+snapshot has the same number of primary shards. This error indicates the index
|
|
|
+in the snapshot has a different number of primary shards.
|
|
|
+
|
|
|
+To resolve this error, try one of the methods in <<restore-index-data-stream>>.
|
James Rodewig