[7.8] [DOCS] Updating snapshot/restore pages to align with API changes

Author: Adam Locke

docs/reference/snapshot-restore/apis/get-snapshot-status-api.asciidoc

@@ -88,9 +88,7 @@ Use the get snapshot status API to retrieve detailed information about snapshots
 
 If you specify both the repository name and snapshot, the request retrieves detailed status information for the given snapshot, even if not currently running.
 
-WARNING: Using this API to return any status results other than the currently running snapshots (`_current`) can be very expensive. Each request to retrieve snapshot status results in file reads from every shard in a snapshot, for each snapshot.
-+
-For example, if you have 100 snapshots with 1,000 shards each, the API request will result in 100,000 file reads (100 snapshots * 1,000 shards). Depending on the latency of your file storage, the request can take extremely long to retrieve results.
+include::{es-ref-dir}/snapshot-restore/monitor-snapshot-restore.asciidoc[tag=get-snapshot-status-warning]
 
 [[get-snapshot-status-api-path-params]]
 ==== {api-path-parms-title}

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

@@ -0,0 +1,47 @@
+[[delete-snapshots]]
+== Delete a snapshot
+
+////
+[source,console]
+-----------------------------------
+PUT /_snapshot/my_backup
+{
+  "type": "fs",
+  "settings": {
+    "location": "my_backup_location"
+  }
+}
+
+PUT /_snapshot/my_backup/snapshot_1?wait_for_completion=true
+
+PUT /_snapshot/my_backup/snapshot_2?wait_for_completion=true
+
+PUT /_snapshot/my_backup/snapshot_3?wait_for_completion=true
+-----------------------------------
+// TESTSETUP
+
+////
+
+Use the <<delete-snapshot-api,delete snapshot API>> to delete a snapshot
+from the repository:
+
+[source,console]
+----
+DELETE /_snapshot/my_backup/snapshot_1
+----
+
+When a snapshot is deleted from a repository, {es} deletes all files associated with the
+snapshot that are not in-use by other snapshots.
+
+If the delete snapshot operation starts while the snapshot is being
+created, the snapshot process halts and all files created as part of the snapshotting process are
+removed. Use the <<delete-snapshot-api,Delete snapshot API>> to cancel long running snapshot operations that were
+started by mistake.
+
+To delete multiple snapshots from a repository, separate snapshot names by commas or use wildcards:
+
+[source,console]
+-----------------------------------
+DELETE /_snapshot/my_backup/snapshot_2,snapshot_3
+DELETE /_snapshot/my_backup/snap*
+-----------------------------------

docs/reference/snapshot-restore/index.asciidoc

@@ -5,25 +5,29 @@
 --
 
 // tag::snapshot-intro[]
-A _snapshot_ is a backup taken from a running {es} cluster. 
-You can take snapshots of individual indices or of the entire cluster. 
-Snapshots can be stored in either local or remote repositories. 
-Remote repositories can reside on S3, HDFS, Azure, Google Cloud Storage, 
+A _snapshot_ is a backup taken from a running {es} cluster.
+You can take snapshots of an entire cluster, including all its
+indices. You can also take snapshots of only specific indices in
+the cluster.
+
+Snapshots can be stored in either local or remote repositories.
+Remote repositories can reside on Amazon S3, HDFS, Microsoft Azure,
+Google Cloud Storage,
 and other platforms supported by a repository plugin.
 
-Snapshots are incremental: each snapshot of an index only stores data that 
+Snapshots are incremental: each snapshot of an index only stores data that
 is not part of an earlier snapshot.  
 This enables you to take frequent snapshots with minimal overhead.
-// end::snapshot-intro[] 
+// end::snapshot-intro[]
 
 // tag::restore-intro[]
-You can restore snapshots to a running cluster with the <<snapshots-restore-snapshot,restore API>>. 
-By default, all indices in the snapshot are restored. 
-Alternatively, you can restore specific indices or restore the cluster state from a snapshot. 
-When restoring indices, you can modify the index name and selected index settings. 
+You can restore snapshots to a running cluster with the <<snapshots-restore-snapshot,restore API>>.
+By default, all indices in the snapshot are restored.
+Alternatively, you can restore specific indices or restore the cluster state from a snapshot.
+When restoring indices, you can modify the index name and selected index settings.
 // end::restore-intro[]
 
-You must <<snapshots-register-repository, register a snapshot repository>> 
+You must <<snapshots-register-repository, register a snapshot repository>>
 before you can <<snapshots-take-snapshot, take snapshots>>.
 
 You can use <<getting-started-snapshot-lifecycle-management, snapshot lifecycle management>>
@@ -92,5 +96,5 @@ include::register-repository.asciidoc[]
 include::take-snapshot.asciidoc[]
 include::restore-snapshot.asciidoc[]
 include::monitor-snapshot-restore.asciidoc[]
+include::delete-snapshot.asciidoc[]
 include::../slm/index.asciidoc[]
-

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

@@ -1,13 +1,15 @@
 [[snapshots-monitor-snapshot-restore]]
 == Monitor snapshot and restore progress
-
 ++++
 <titleabbrev>Monitor snapshot and restore</titleabbrev>
 ++++
 
-There are several ways to monitor the progress of the snapshot and restore processes while they are running. Both
-operations support `wait_for_completion` parameter that would block client until the operation is completed. This is
-the simplest method that can be used to get notified about operation completion.
+Use the <<get-snapshot-api,get snapshot API>> or the
+<<get-snapshot-status-api,get snapshot status API>> to monitor the
+progress of snapshot operations. Both APIs support the
+`wait_for_completion` parameter that blocks the client until the
+operation finishes, which is the simplest method of being notified
+about operation completion.
 
 ////
 [source,console]
@@ -20,70 +22,155 @@ PUT /_snapshot/my_backup
   }
 }
 
+PUT /_snapshot/my_fs_backup
+{
+  "type": "fs",
+  "settings": {
+    "location": "my_other_backup_location"
+  }
+}
+
 PUT /_snapshot/my_backup/snapshot_1?wait_for_completion=true
+
+PUT /_snapshot/my_backup/some_other_snapshot?wait_for_completion=true
 -----------------------------------
 // TESTSETUP
 
 ////
 
-The snapshot operation can be also monitored by periodic calls to the snapshot info:
+Use the `_current` parameter to retrieve all currently running
+snapshots in the cluster:
+
+[source,console]
+-----------------------------------
+GET /_snapshot/my_backup/_current
+-----------------------------------
+
+Including a snapshot name in the request retrieves information about a single snapshot:
 
 [source,console]
 -----------------------------------
 GET /_snapshot/my_backup/snapshot_1
 -----------------------------------
 
-Please note that snapshot info operation uses the same resources and thread pool as the snapshot operation. So,
-executing a snapshot info operation while large shards are being snapshotted can cause the snapshot info operation to wait
-for available resources before returning the result. On very large shards the wait time can be significant.
+This request retrieves basic information about the snapshot, including start and end time, version of
+{es} that created the snapshot, the list of included indices, the current state of the
+snapshot and the list of failures that occurred during the snapshot.
 
-To get more immediate and complete information about snapshots the snapshot status command can be used instead:
+Similar to repositories, you can retrieve information about multiple snapshots in a single request, and wildcards are supported:
 
 [source,console]
 -----------------------------------
-GET /_snapshot/my_backup/snapshot_1/_status
+GET /_snapshot/my_backup/snapshot_*,some_other_snapshot
+-----------------------------------
+
+Separate repository names with commas or use wildcards to retrieve snapshots from multiple repositories:
+
+[source,console]
+-----------------------------------
+GET /_snapshot/_all
+GET /_snapshot/my_backup,my_fs_backup
+GET /_snapshot/my*
+-----------------------------------
+
+Add the `_all` parameter to the request to list all snapshots currently stored in the repository:
+
+[source,console]
+-----------------------------------
+GET /_snapshot/my_backup/_all
 -----------------------------------
-// TEST[continued]
 
-While snapshot info method returns only basic information about the snapshot in progress, the snapshot status returns
+This request fails if some of the snapshots are unavailable. Use the boolean parameter `ignore_unavailable` to
+return all snapshots that are currently available.
+
+Getting all snapshots in the repository can be costly on cloud-based repositories,
+both from a cost and performance perspective.  If the only information required is
+the snapshot names or UUIDs in the repository and the indices in each snapshot, then
+the optional boolean parameter `verbose` can be set to `false` to execute a more
+performant and cost-effective retrieval of the snapshots in the repository.
+
+NOTE: Setting `verbose` to `false` omits additional information
+about the snapshot, such as metadata, start and end time, number of shards that include the snapshot, and error messages. The default value of the `verbose` parameter is `true`.
+
+[discrete]
+[[get-snapshot-detailed-status]]
+=== Retrieving snapshot status
+To retrieve more detailed information about snapshots, use the <<get-snapshot-status-api,get snapshot status API>>. While snapshot request returns only basic information about the snapshot in progress, the snapshot status request returns
 complete breakdown of the current state for each shard participating in the snapshot.
 
-The restore process piggybacks on the standard recovery mechanism of the Elasticsearch. As a result, standard recovery
-monitoring services can be used to monitor the state of restore. When restore operation is executed the cluster
-typically goes into `red` state. It happens because the restore operation starts with "recovering" primary shards of the
-restored indices. During this operation the primary shards become unavailable which manifests itself in the `red` cluster
-state. Once recovery of primary shards is completed Elasticsearch is switching to standard replication process that
-creates the required number of replicas at this moment cluster switches to the `yellow` state. Once all required replicas
-are created, the cluster switches to the `green` states.
+// tag::get-snapshot-status-warning[]
+[WARNING]
+====
+Using the get snapshot status API to return any status results other than the currently running snapshots (`_current`) can be very expensive. Each request to retrieve snapshot status results in file reads from every shard in a snapshot, for each snapshot. Such requests are taxing to machine resources and can also incur high processing costs when running in the cloud.
+
+For example, if you have 100 snapshots with 1,000 shards each, the API request will result in 100,000 file reads (100 snapshots * 1,000 shards). Depending on the latency of your file storage, the request can take extremely long to retrieve results.
+====
+// end::get-snapshot-status-warning[]
+
+The following request retrieves all currently running snapshots with
+detailed status information:
+
+[source,console]
+-----------------------------------
+GET /_snapshot/_status
+-----------------------------------
+
+By specifying a repository name, it's possible
+to limit the results to a particular repository:
+
+[source,console]
+-----------------------------------
+GET /_snapshot/my_backup/_status
+-----------------------------------
+
+If both repository name and snapshot name are specified, the request
+returns detailed status information for the given snapshot, even
+if not currently running:
+
+[source,console]
+-----------------------------------
+GET /_snapshot/my_backup/snapshot_1/_status
+-----------------------------------
+
+[discrete]
+=== Monitoring restore operations
+
+The restore process piggybacks on the standard recovery mechanism of
+{es}. As a result, standard recovery monitoring services can be used
+to monitor the state of restore. When the restore operation starts, the
+cluster typically goes into `yellow` state because the restore operation works
+by recovering primary shards of the restored indices. After the recovery of the
+primary shards is completed, {es} switches to the standard replication
+process that creates the required number of replicas. When all required
+replicas are created, the cluster switches to the `green` states.
 
 The cluster health operation provides only a high level status of the restore process. It's possible to get more
 detailed insight into the current state of the recovery process by using <<indices-recovery, index recovery>> and
 <<cat-recovery, cat recovery>> APIs.
 
-[float]
+[discrete]
+[[get-snapshot-stop-snapshot]]
 === Stop snapshot and restore operations
-
 The snapshot and restore framework allows running only one snapshot or one restore operation at a time. If a currently
-running snapshot was executed by mistake, or takes unusually long, it can be terminated using the snapshot delete operation.
-The snapshot delete operation checks if the deleted snapshot is currently running and if it does, the delete operation stops
+running snapshot was started by mistake, or takes unusually long, it can be stopped using the <<delete-snapshot-api,delete snapshot API>>.
+This operation checks whether the deleted snapshot is currently running. If it is, the delete snapshot operation stops
 that snapshot before deleting the snapshot data from the repository.
 
 [source,console]
 -----------------------------------
 DELETE /_snapshot/my_backup/snapshot_1
 -----------------------------------
-// TEST[continued]
 
 The restore operation uses the standard shard recovery mechanism. Therefore, any currently running restore operation can
-be canceled by deleting indices that are being restored. Please note that data for all deleted indices will be removed
+be canceled by deleting indices that are being restored. Data for all deleted  indices will be removed
 from the cluster as a result of this operation.
 
-[float]
-=== Effect of cluster blocks on snapshot and restore 
-
+[discrete]
+[[get-snapshot-cluster-blocks]]
+=== Effect of cluster blocks on snapshot and restore
 Many snapshot and restore operations are affected by cluster and index blocks. For example, registering and unregistering
-repositories require write global metadata access. The snapshot operation requires that all indices and their metadata as
-well as the global metadata were readable. The restore operation requires the global metadata to be writable, however
+repositories require global metadata write access. The snapshot operation requires that all indices, backing indices, and their metadata (including
+global metadata) are readable. The restore operation requires the global metadata to be writable. However,
 the index level blocks are ignored during restore because indices are essentially recreated during restore.
-Please note that a repository content is not part of the cluster and therefore cluster blocks don't affect internal
-repository operations such as listing or deleting snapshots from an already registered repository.
+A repository content is not part of the cluster and therefore cluster blocks do not affect internal
+repository operations such as listing or deleting snapshots from an already registered repository.