Consolify snapshot documentation (#23189)
This commit brings the snapshot documentation in conformity with the CONSOLE format, and fixes the docs so that the documentation tests can be run against them.
This commit is contained in:
Ali Beyad
GitHub
parent
6cdf4f3f72
commit
71739623d3
|
|
@ -121,7 +121,7 @@ buildRestTests.expectedUnconvertedCandidates = [
|
|||
'reference/mapping/types/percolator.asciidoc',
|
||||
'reference/modules/scripting/security.asciidoc',
|
||||
'reference/modules/scripting/using.asciidoc',
|
||||
'reference/modules/cross-cluster-search.asciidoc', // this is hart to test since we need 2 clusters -- maybe we can trick it into referencing itself...
|
||||
'reference/modules/cross-cluster-search.asciidoc', // this is hard to test since we need 2 clusters -- maybe we can trick it into referencing itself...
|
||||
'reference/query-dsl/exists-query.asciidoc',
|
||||
'reference/query-dsl/function-score-query.asciidoc',
|
||||
'reference/query-dsl/geo-shape-query.asciidoc',
|
||||
|
|
@ -154,7 +154,7 @@ integTest {
|
|||
}
|
||||
}
|
||||
|
||||
// Build the cluser with all plugins
|
||||
// Build the cluster with all plugins
|
||||
|
||||
project.rootProject.subprojects.findAll { it.parent.path == ':plugins' }.each { subproj ->
|
||||
/* Skip repositories. We just aren't going to be able to test them so it
|
||||
|
|
@ -176,8 +176,6 @@ buildRestTests.docs = fileTree(projectDir) {
|
|||
exclude 'build.gradle'
|
||||
// That is where the snippets go, not where they come from!
|
||||
exclude 'build'
|
||||
// This file simply doesn't pass yet. We should figure out how to fix it.
|
||||
exclude 'reference/modules/snapshots.asciidoc'
|
||||
}
|
||||
|
||||
Closure setupTwitter = { String name, int count ->
|
||||
|
|
|
|||
|
|
@ -28,10 +28,12 @@ PUT /_snapshot/my_backup
|
|||
{
|
||||
"type": "fs",
|
||||
"settings": {
|
||||
... repository specific settings ...
|
||||
"location": "my_backup_location"
|
||||
}
|
||||
}
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TESTSETUP
|
||||
|
||||
Once a repository is registered, its information can be obtained using the following command:
|
||||
|
||||
|
|
@ -49,12 +51,12 @@ which returns:
|
|||
"my_backup": {
|
||||
"type": "fs",
|
||||
"settings": {
|
||||
"compress": true,
|
||||
"location": "/mount/backups/my_backup"
|
||||
"location": "my_backup_location"
|
||||
}
|
||||
}
|
||||
}
|
||||
-----------------------------------
|
||||
// TESTRESPONSE
|
||||
|
||||
Information about multiple repositories can be fetched in one go by using a comma-delimited list of repository names.
|
||||
Star wildcards are supported as well. For example, information about repositories that start with `repo` or that contain `backup`
|
||||
|
|
@ -64,6 +66,7 @@ can be obtained using the following command:
|
|||
-----------------------------------
|
||||
GET /_snapshot/repo*,*backup*
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
|
||||
If a repository name is not specified, or `_all` is used as repository name Elasticsearch will return information about
|
||||
all repositories currently registered in the cluster:
|
||||
|
|
@ -72,6 +75,7 @@ all repositories currently registered in the cluster:
|
|||
-----------------------------------
|
||||
GET /_snapshot
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
|
||||
or
|
||||
|
||||
|
|
@ -79,6 +83,7 @@ or
|
|||
-----------------------------------
|
||||
GET /_snapshot/_all
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
|
||||
[float]
|
||||
===== Shared File System Repository
|
||||
|
|
@ -109,28 +114,34 @@ the name `my_backup`:
|
|||
|
||||
[source,js]
|
||||
-----------------------------------
|
||||
$ curl -XPUT 'http://localhost:9200/_snapshot/my_backup' -d '{
|
||||
PUT /_snapshot/my_fs_backup
|
||||
{
|
||||
"type": "fs",
|
||||
"settings": {
|
||||
"location": "/mount/backups/my_backup",
|
||||
"location": "/mount/backups/my_fs_backup_location",
|
||||
"compress": true
|
||||
}
|
||||
}'
|
||||
}
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[skip:no access to absolute path]
|
||||
|
||||
If the repository location is specified as a relative path this path will be resolved against the first path specified
|
||||
in `path.repo`:
|
||||
|
||||
[source,js]
|
||||
-----------------------------------
|
||||
$ curl -XPUT 'http://localhost:9200/_snapshot/my_backup' -d '{
|
||||
PUT /_snapshot/my_fs_backup
|
||||
{
|
||||
"type": "fs",
|
||||
"settings": {
|
||||
"location": "my_backup",
|
||||
"location": "my_fs_backup_location",
|
||||
"compress": true
|
||||
}
|
||||
}'
|
||||
}
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
The following settings are supported:
|
||||
|
||||
|
|
@ -183,24 +194,25 @@ verification when registering or updating a repository:
|
|||
|
||||
[source,js]
|
||||
-----------------------------------
|
||||
PUT /_snapshot/s3_repository?verify=false
|
||||
PUT /_snapshot/my_unverified_backup?verify=false
|
||||
{
|
||||
"type": "s3",
|
||||
"type": "fs",
|
||||
"settings": {
|
||||
"bucket": "my_s3_bucket",
|
||||
"region": "eu-west-1"
|
||||
"location": "my_unverified_backup_location"
|
||||
}
|
||||
}
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
The verification process can also be executed manually by running the following command:
|
||||
|
||||
[source,js]
|
||||
-----------------------------------
|
||||
POST /_snapshot/s3_repository/_verify
|
||||
POST /_snapshot/my_unverified_backup/_verify
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
It returns a list of nodes where repository was successfully verified or an error message if verification process failed.
|
||||
|
||||
|
|
@ -216,6 +228,7 @@ command:
|
|||
PUT /_snapshot/my_backup/snapshot_1?wait_for_completion=true
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
The `wait_for_completion` parameter specifies whether or not the request should return immediately after snapshot
|
||||
initialization (default) or wait for snapshot completion. During snapshot initialization, information about all
|
||||
|
|
@ -227,7 +240,7 @@ specifying the list of indices in the body of the snapshot request.
|
|||
|
||||
[source,js]
|
||||
-----------------------------------
|
||||
PUT /_snapshot/my_backup/snapshot_1
|
||||
PUT /_snapshot/my_backup/snapshot_2?wait_for_completion=true
|
||||
{
|
||||
"indices": "index_1,index_2",
|
||||
"ignore_unavailable": true,
|
||||
|
|
@ -235,6 +248,7 @@ PUT /_snapshot/my_backup/snapshot_1
|
|||
}
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
The list of indices that should be included into the snapshot can be specified using the `indices` parameter that
|
||||
supports <<search-multi-index-type,multi index syntax>>. The snapshot request also supports the
|
||||
|
|
@ -271,6 +285,7 @@ Once a snapshot is created information about this snapshot can be obtained using
|
|||
GET /_snapshot/my_backup/snapshot_1
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
Similar as for repositories, information about multiple snapshots can be queried in one go, supporting wildcards as well:
|
||||
|
||||
|
|
@ -279,6 +294,7 @@ Similar as for repositories, information about multiple snapshots can be queried
|
|||
GET /_snapshot/my_backup/snapshot_*,some_other_snapshot
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
All snapshots currently stored in the repository can be listed using the following command:
|
||||
|
||||
|
|
@ -287,6 +303,7 @@ All snapshots currently stored in the repository can be listed using the followi
|
|||
GET /_snapshot/my_backup/_all
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
The command fails if some of the snapshots are unavailable. The boolean parameter `ignore_unavailable` can be used to
|
||||
return all snapshots that are currently available.
|
||||
|
|
@ -295,16 +312,19 @@ A currently running snapshot can be retrieved using the following command:
|
|||
|
||||
[source,sh]
|
||||
-----------------------------------
|
||||
$ curl -XGET "localhost:9200/_snapshot/my_backup/_current"
|
||||
GET /_snapshot/my_backup/_current
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
A snapshot can be deleted from the repository using the following command:
|
||||
|
||||
[source,sh]
|
||||
-----------------------------------
|
||||
DELETE /_snapshot/my_backup/snapshot_1
|
||||
DELETE /_snapshot/my_backup/snapshot_2
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
When a snapshot is deleted from a repository, Elasticsearch deletes all files that are associated with the deleted
|
||||
snapshot and not used by any other snapshots. If the deleted snapshot operation is executed while the snapshot is being
|
||||
|
|
@ -316,9 +336,10 @@ A repository can be deleted using the following command:
|
|||
|
||||
[source,sh]
|
||||
-----------------------------------
|
||||
DELETE /_snapshot/my_backup
|
||||
DELETE /_snapshot/my_fs_backup
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
When a repository is deleted, Elasticsearch only removes the reference to the location where the repository is storing
|
||||
the snapshots. The snapshots themselves are left untouched and in place.
|
||||
|
|
@ -333,6 +354,7 @@ A snapshot can be restored using the following command:
|
|||
POST /_snapshot/my_backup/snapshot_1/_restore
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
By default, all indices in the snapshot are restored, and the cluster state is
|
||||
*not* restored. It's possible to select indices that should be restored as well
|
||||
|
|
@ -358,6 +380,7 @@ POST /_snapshot/my_backup/snapshot_1/_restore
|
|||
}
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
The restore operation can be performed on a functioning cluster. However, an
|
||||
existing index can be only restored if it's <<indices-open-close,closed>> and
|
||||
|
|
@ -398,6 +421,7 @@ POST /_snapshot/my_backup/snapshot_1/_restore
|
|||
}
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
Please note, that some settings such as `index.number_of_shards` cannot be changed during restore operation.
|
||||
|
||||
|
|
@ -432,6 +456,7 @@ A list of currently running snapshots with their detailed status information can
|
|||
GET /_snapshot/_status
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
In this format, the command will return information about all currently running snapshots. By specifying a repository name, it's possible
|
||||
to limit the results to a particular repository:
|
||||
|
|
@ -441,6 +466,7 @@ to limit the results to a particular repository:
|
|||
GET /_snapshot/my_backup/_status
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
If both repository name and snapshot id are specified, this command will return detailed status information for the given snapshot even
|
||||
if it's not currently running:
|
||||
|
|
@ -450,6 +476,7 @@ if it's not currently running:
|
|||
GET /_snapshot/my_backup/snapshot_1/_status
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
Multiple ids are also supported:
|
||||
|
||||
|
|
@ -458,6 +485,7 @@ Multiple ids are also supported:
|
|||
GET /_snapshot/my_backup/snapshot_1,snapshot_2/_status
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
[float]
|
||||
=== Monitoring snapshot/restore progress
|
||||
|
|
@ -473,6 +501,7 @@ The snapshot operation can be also monitored by periodic calls to the snapshot i
|
|||
GET /_snapshot/my_backup/snapshot_1
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
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
|
||||
|
|
@ -485,6 +514,7 @@ To get more immediate and complete information about snapshots the snapshot stat
|
|||
GET /_snapshot/my_backup/snapshot_1/_status
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
While snapshot info method returns only basic information about the snapshot in progress, the snapshot status returns
|
||||
complete breakdown of the current state for each shard participating in the snapshot.
|
||||
|
|
@ -514,6 +544,7 @@ that snapshot before deleting the snapshot data from the repository.
|
|||
DELETE /_snapshot/my_backup/snapshot_1
|
||||
-----------------------------------
|
||||
// CONSOLE
|
||||
// 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
|
||||
|
|
|
|||
Loading…
Reference in New Issue