[DOCS] Updates Snapshot docs to include retention (#49007) (#49417)

* [DOCS] Updates Snapshot docs to include retention

* [DOCS] Creates tutorial for snapshot & restore

* [DOCS] Incorporates review comments for Snapshot doc

* [DOCS] Fixes typo

* [DOCS] Adds x-pack label

docs/management/snapshot-restore/index.asciidoc

@@ -11,11 +11,11 @@ you can restore a snapshot from the repository.
 You’ll find *Snapshot and Restore* under *Management > Elasticsearch*. 
 With this UI, you can:
 
-* <<kib-snapshot-register-repository, Register a repository for storing your snapshots>>
-* <<kib-view-snapshot, View a list of your snapshots and drill down into details>>
-* <<kib-restore-snapshot, Restore data into your cluster from a snapshot>>
-* <<kib-snapshot-policy, Create a policy for automatic snapshots>>
-* <<kib-delete-snapshot, Delete a snapshot to free storage space>>
+* Register a repository for storing your snapshots
+* View a list of your snapshots and drill down into details
+* Restore data into your cluster from a snapshot
+* Create a policy to automate snapshot creation and deletion
+* Delete a snapshot to free storage space
 
 [role="screenshot"]
 image:management/snapshot-restore/images/snapshot_list.png["Snapshot list"]
@@ -27,28 +27,34 @@ more detailed information.
 [float]
 [[kib-snapshot-register-repository]]
 === Register a repository
+A repository is where your snapshots live. You must register a snapshot 
+repository before you can perform snapshot and restore operations. 
 
-The *Repositories* view provides an overview of your repositories. 
-Click a repository name to view its type, number of snapshots, and settings, and also to verify status.
+If you don't have a repository, Kibana walks you through the process of 
+registering one. 
+{kib} supports three repository types
+out of the box: shared file system, read-only URL, and source-only.  
+For more information on these repositories and their settings, 
+see {ref}/modules-snapshots.html#snapshots-repositories[Repositories].
+To use other repositories, such as S3, see  
+{ref}/modules-snapshots.html#_repository_plugins[Repository plugins].
+
+
+Once you create a repository, it is listed in the *Repositories* 
+view. 
+Click a repository name to view its type, number of snapshots, and settings, 
+and to verify status.
 
 [role="screenshot"]
 image:management/snapshot-restore/images/repository_list.png["Repository list"]
 
-If you don't have a repository, you're prompted to register one. 
-{es} supports three repository types
-out of the box: shared file system, read-only URL, and source-only.  
-For more information on these repositories and their settings, 
-see {ref}/modules-snapshots.html#snapshots-repositories[Repositories]. For an example, 
-see <<snapshot-repositories-example, registering a shared file system repository>>.
-
-To use other repositories, such as S3, you can install plugins. See  
-{ref}/modules-snapshots.html#_repository_plugins[Repository plugins].
 
 [float]
 [[kib-view-snapshot]]
 === View your snapshots
 
-The *Snapshots* view gives an overview of your snapshots. You can drill down 
+A snapshot is a backup taken from a running {es} cluster. You'll find an overview of 
+your snapshots in the *Snapshots* view, and you can drill down 
 into each snapshot for further investigation.
 
 [role="screenshot"]
@@ -68,18 +74,25 @@ the new data.
 [[kib-restore-snapshot]]
 === Restore a snapshot
 
-The *Restore* wizard walks you through the process of restoring a snapshot 
-into a running cluster. To get started, go to the *Snapshots* view, find the 
-snapshot, and click the restore icon in the *Actions* column. 
+The information stored in a snapshot is not tied to a specific 
+cluster or a cluster name. This enables you to
+restore a snapshot made from one cluster to another cluster. You might 
+use the restore operation to:
 
-You’re presented 
-options for the restore, including which 
+* Recover data lost due to a failure
+* Migrate a current Elasticsearch cluster to a new version
+* Move data from one cluster to another cluster
+
+To get started, go to the *Snapshots* view, find the 
+snapshot, and click the restore icon in the *Actions* column. 
+The Restore wizard presents
+options for the restore operation, including which 
 indices to restore and whether to modify the index settings.
 You can restore an existing index only if it’s closed and has the same 
 number of shards as the index in the snapshot.
 
 Once you initiate the restore, you're navigated to the *Restore Status* view,
-where you can track the progress. 
+where you can track the current state for each shard in the snapshot. 
 
 [role="screenshot"]
 image:management/snapshot-restore/images/snapshot-restore.png["Snapshot details"]
@@ -89,23 +102,28 @@ image:management/snapshot-restore/images/snapshot-restore.png["Snapshot details"
 [[kib-snapshot-policy]]
 === Create a snapshot lifecycle policy
 
-You can create policies to schedule automatic snapshots of your cluster. 
-{ref}/snapshot-lifecycle-management-api.html[Snapshot lifecycle policies] are related 
-to {ref}/index-lifecycle-management.html[index lifecycle policies]. 
-However, where an index lifecycle policy applies to a single index, 
-a snapshot lifecycle policy can span multiple indices.
+Use a {ref}/snapshot-lifecycle-management-api.html[snapshot lifecycle policy] 
+to automate the creation and deletion 
+of cluster snapshots. Taking automatic snapshots:
 
-For an overview of your policies, open the *Policies* view.
-You can drill down into each policy to examine its settings and last successful and failed run. 
-
-If you don’t have any policies, use the *Create policy* wizard.
-You’ll define the snapshots and repository, when to take snapshots, and
-the settings, such as which indices the snapshot should contain.
+* Ensures your {es} indices and clusters are backed up on a regular basis
+* Ensures a recent and relevant snapshot is available if a situation 
+arises where a cluster needs to be recovered
+* Allows you to manage your snapshots in {kib}, instead of using a 
+third-party tool
+ 
+If you don’t have any snapshot policies, follow the 
+*Create policy* wizard.  It walks you through defining 
+when and where to take snapshots, the settings you want, 
+and how long to retain snapshots.
 
 [role="screenshot"]
-image:management/snapshot-restore/images/create-policy.png["Snapshot details"]
+image:management/snapshot-restore/images/snapshot-retention.png["Snapshot details"]
 
-You can perform the following actions on a policy:
+An overview of your policies is on the *Policies* view.
+You can drill down into each policy to examine its settings and last successful and failed run. 
+
+You can perform the following actions on a snapshot policy:
 
 * *Run* a policy immediately without waiting for the scheduled time.
 This action is useful before an upgrade or before performing maintenance on indices.
@@ -113,6 +131,9 @@ This action is useful before an upgrade or before performing maintenance on indi
 * *Delete* a policy to prevent any future snapshots from being taken.
 This action does not cancel any currently ongoing snapshots or remove any previously taken snapshots.
 
+[role="screenshot"]
+image:management/snapshot-restore/images/create-policy.png["Snapshot details"]
+
 [float]
 [[kib-delete-snapshot]]
 === Delete a snapshot
@@ -123,16 +144,25 @@ Find the snapshot in the *Snapshots* view and click the trash icon in the
 and then click *Delete snapshots*.
 
 [[snapshot-repositories-example]]
-[float]
-=== Example: Register a shared file system repository
 
-This example shows how to register a shared file system repository 
+[role="xpack"]
+[[snapshot-restore-tutorial]]
+=== Tutorial:  Snapshot and Restore
+
+
+Ready to try *Snapshot and Restore*? In this tutorial, you'll learn to:
+
+* Register a repository
+* Add snapshots to the repository
+* Create a snapshot lifecycle policy
+* Restore a snapshot
+
+==== Before you begin
+
+This example shows you how to register a shared file system repository 
 and store snapshots.
-
-[float]
-==== Register the repository location
-
-You must register the location of the repository in the `path.repo` setting on 
+Before you begin, you must register the location of the repository in the 
+{ref}/modules-snapshots.html#_shared_file_system_repository[path.repo] setting on 
 your master and data nodes.  You can do this in one of two ways:
 
 * Edit  your `elasticsearch.yml` to include the `path.repo` setting.
@@ -142,30 +172,26 @@ your master and data nodes.  You can do this in one of two ways:
 `bin/elasticsearch -E path.repo=/tmp/es-backups`
 
 [float]
-==== Register the repository
+[[register-repo-example]]
+==== Register a repository
 
 Use *Snapshot and Restore* to register the repository where your snapshots 
 will live. 
 
 . Go to *Management > Elasticsearch > Snapshot and Restore*.
-. Open the *Repositories* view.
-. Click *Register a repository*.
+. Click *Register a repository* in either the introductory message or *Repository view*.
 . Enter a name for your repository, for example, `my_backup`.
-. Set *Repository type* to Shared file system.
+. Select *Shared file system*.
 + 
 [role="screenshot"]
 image:management/snapshot-restore/images/register_repo.png["Register repository"]
 
 . Click *Next*.
-. In *Location*, enter the path to the snapshot repository, `/tmp/es-backups`.
-. In *Chunk size*, enter 100mb so that snapshot files are not bigger than that size.
-. Use the defaults for all other fields.
-. Click *Register*.
+. In *File system location*, enter the path to the snapshot repository, `/tmp/es-backups`.
+. In *Chunk size*, enter `100mb` so that snapshot files are not bigger than that size.
+. Use the defaults for all other fields, and then click *Register*.
 +
 Your new repository is listed on the *Repositories* view.
-+
-. Click the respository and inspect its details. 
-+
 The repository currently doesn’t have any snapshots.
 
 
@@ -174,19 +200,105 @@ The repository currently doesn’t have any snapshots.
 Use the {ref}//modules-snapshots.html#snapshots-take-snapshot[snapshot API] to create a snapshot.
 
 . Go to *Dev Tools > Console*.
-. Create the snapshot. 
+. Create the snapshot:
++
+[source,js]
+PUT /_snapshot/my_backup/2019-04-25_snapshot?wait_for_completion=true
 +
 In this example, the snapshot name is `2019-04-25_snapshot`. You can also 
 use {ref}//date-math-index-names.html[date math expression] for the snapshot name.
 +
 [role="screenshot"]
 image:management/snapshot-restore/images/create_snapshot.png["Create snapshot"]
-+
-. Open *Snapshot and Restore*. 
+
+. Return to *Snapshot and Restore*. 
 +
 Your new snapshot is available in the *Snapshots* view.
 
+[[create-policy-example]]
+==== Create a snapshot lifecycle policy
 
+Now you'll automate the creation and deletion of snapshots
+using the repository created in the previous example.
 
+. Open the *Policies* view.
+. Click *Create a policy*.
++ 
+[role="screenshot"]
+image:management/snapshot-restore/images/create-policy-example.png["Create policy wizard"]
 
+. As you walk through the wizard, enter the following values:
++
+|===
+|*Logistics* |
+
+|Policy name
+|`daily-snapshots`
+
+|Snapshot name
+|`<daily-snap-{now/d}>`
+
+|Schedule
+|Every day at 1:30 a.m.
+
+|Repository
+|`my_backup`
+
+|*Snapshot&nbsp;settings* |
+
+|Indices
+|Select the indices to back up. By default, all indices, including system indices, are backed up.
+
+|All&nbsp;other&nbsp;settings
+|Use the defaults.
+
+|*Snapshot&nbsp;retention* |
+
+|Expiration
+|`30 days`
+
+|Snapshots&nbsp;to&nbsp;retain
+|Minimum count: `5`, Maximum count: `50`
+|===
+
+. Review your input, and then click *Create policy*.
++
+Your new policy is listed in the *Policies* view, and you see a summary of its details.
+
+[[restore-snapshot-example]]
+==== Restore a snapshot
+Finally, you'll restore indices from an existing snapshot.
+
+. In the *Snapshots* view, find the snapshot you want to restore, for example `2019-04-25_snapshot`.
+. Click the restore icon in the *Actions* column.
+. As you walk through the wizard, enter the following values:
++
+|===
+|*Logistics* |
+
+|Indices
+|Toggle to choose specific indices to restore, or leave in place to restore all indices.
+
+|Rename indices
+|Toggle to give your restored indices new names, or leave in place to restore under original index names.
+
+|All other fields
+|Use the defaults.
+
+|*Index&nbsp;settings* |
+
+|Modify&nbsp;index&nbsp;settings
+|Toggle to overwrite index settings when they are restored, 
+or leave in place to keep existing settings.
+
+|Reset&nbsp;index&nbsp;settings
+|Toggle to reset index settings back to the default when they are restored, 
+or leave in place to keep existing settings.
+|===
+
+. Review your restore settings, and then click *Restore snapshot*.
++
+The operation loads for a few seconds, 
+and then you’re navigated to *Restore Status*, 
+where you can monitor the status of your restored indices.