elasticsearch/docs/reference/snapshot-restore/restore-snapshot.asciidoc

[[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 pattern. If you use {es}'s security features,
this will delete system indices required for authentication. Instead, target the
`*,-.*` wildcard pattern to exclude these system indices and other index names
that begin with a dot (`.`).

[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 and other index names that begin with a dot (`.`), append the
`-.*` wildcard pattern. To restore all indices and data streams except dot
indices, use `*,-.*`.

[source,console]
----
POST _snapshot/my_repository/my_snapshot_2099.05.06/_restore 
{
  "indices": "my-index,logs-my_app-default"
}
----
// TEST[continued]
// TEST[s/_restore/_restore?wait_for_completion=true/]

[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.

The following restore snapshot API request prepends `restored-` to the name of
any restored index or data stream.

[source,console]
----
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/]

If the rename options produce two or more indices or data streams with the same
name, the restore operation fails.

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`.

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.

[source,console]
----
# Delete the original index
DELETE my-index

# Reindex the restored index to rename it
POST _reindex
{
  "source": {
    "index": "restored-my-index"
  },
  "dest": {
    "index": "my-index"
  }
}

# Delete the original data stream
DELETE _data_stream/logs-my_app-default

# 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]

[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.

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.

. Temporarily stop indexing and turn off the following features:
+
--
* ILM
+
[source,console]
----
POST _ilm/stop
----

////
[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]
----
PUT _cluster/settings
{
  "persistent": {
    "xpack.monitoring.collection.enabled": true
  }
}
----
// TEST[warning:[xpack.monitoring.collection.enabled] setting was deprecated in Elasticsearch and will be removed in a future release! See the breaking changes documentation for the next major version.]
// TEST[continued]
////

* Watcher
+
[source,console]
----
POST _watcher/_stop
----

////
[source,console]
----
POST _watcher/_start
----
// TEST[continued]
////
--

. 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.

. Use the <<cluster-update-settings,cluster update 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]

. Delete existing indices and data streams on the cluster.
+
[source,console]
----
# Delete all indices
DELETE *

# 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/]

. When the restore operation is complete, resume indexing and restart any
features you stopped:
+
--
* ILM
+
[source,console]
----
POST _ilm/start
----

* Machine Learning
+
[source,console]
----
POST _ml/set_upgrade_mode?enabled=false
----

* Watcher
+
[source,console]
----
POST _watcher/_start
----
--

. If wanted, reset the `action.destructive_requires_name` cluster setting.
+
[source,console]
----
PUT _cluster/settings
{
  "persistent": {
    "action.destructive_requires_name": null
  }
}
----

[discrete]
[[monitor-restore]]
=== Monitor a restore

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>>.

[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.

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]
[[cancel-restore]]
=== Cancel a restore

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.

[source,console]
----
# Delete an index
DELETE my-index

# Delete a data stream
DELETE _data_stream/logs-my_app-default
----
// TEST[setup:setup-snapshots]

[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
index will not be successfully restored unless these index allocation settings are changed during the restore operation.

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>>.