From 9f1e3bc82b3c04c31b906d528783a972a911288a Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 26 May 2020 11:39:39 -0400 Subject: [PATCH] [DOCS] Document impact of restore API's `include_global_state` param (#57067) (#57155) Previously, the restore API snippet included a `include_global_state` value of `true`. Some users copy and paste the code example verbatim, updating only the index and snapshot value names. Running the snippet could inadvertently wipe out a cluster's current ILM policies, index templates, and ingest pipelines. This change updates the snippet to use a `include_global_state` value of `false`. It also adds a callout that better describes impacts of using a `include_global_state` argument of `true`. Co-authored-by: Mike Wong Co-authored-by: James Rodewig Co-authored-by: David Turner --- .../restore-snapshot.asciidoc | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/reference/snapshot-restore/restore-snapshot.asciidoc b/docs/reference/snapshot-restore/restore-snapshot.asciidoc index 1e1d8b914bb..5fc592c4363 100644 --- a/docs/reference/snapshot-restore/restore-snapshot.asciidoc +++ b/docs/reference/snapshot-restore/restore-snapshot.asciidoc @@ -47,22 +47,27 @@ POST /_snapshot/my_backup/snapshot_1/_restore { "indices": "index_1,index_2", "ignore_unavailable": true, - "include_global_state": true, + "include_global_state": false, <1> "rename_pattern": "index_(.+)", - "rename_replacement": "restored_index_$1" + "rename_replacement": "restored_index_$1", + "include_aliases": false } ----------------------------------- // TEST[continued] +<1> By default, `include_global_state` is `false`, meaning the snapshot's +cluster state is not restored. ++ +If `true`, the snapshot's persistent settings, index templates, ingest +pipelines, and {ilm-init} policies are restored into the current cluster. This +overwrites any existing cluster settings, templates, pipelines and {ilm-init} +policies whose names match those in the snapshot. + The restore operation can be performed on a functioning cluster. However, an existing index can be only restored if it's <> 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. If cluster state is restored -with `include_global_state` (defaults to `false`), the restored templates that -don't currently exist in the cluster are added and existing templates with the -same name are replaced by the restored templates. The restored persistent -settings are added to the existing persistent settings. +new indices if they didn't exist in the cluster. [float] === Partial restore