From fe92f21a61388f042650cfe83e2ce21781d92b98 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 18 May 2020 08:42:26 -0400 Subject: [PATCH] [DOCS] Add put snapshot repo API docs (#56827) --- .../apis/put-repo-api.asciidoc | 266 ++++++++++++++++++ .../apis/snapshot-restore-apis.asciidoc | 4 +- .../reference/snapshot-restore/index.asciidoc | 1 + 3 files changed, 270 insertions(+), 1 deletion(-) create mode 100644 docs/reference/snapshot-restore/apis/put-repo-api.asciidoc diff --git a/docs/reference/snapshot-restore/apis/put-repo-api.asciidoc b/docs/reference/snapshot-restore/apis/put-repo-api.asciidoc new file mode 100644 index 0000000000000..eba3b7ee47be0 --- /dev/null +++ b/docs/reference/snapshot-restore/apis/put-repo-api.asciidoc @@ -0,0 +1,266 @@ +[[put-snapshot-repo-api]] +=== Put snapshot repository API +++++ +Put snapshot repository +++++ + +Registers or updates a <>. + +[source,console] +---- +PUT /_snapshot/my_repository +{ + "type": "fs", + "settings": { + "location": "my_backup_location" + } +} +---- + +[[put-snapshot-repo-api-request]] +==== {api-request-title} + +`PUT /_snapshot/` + +`POST /_snapshot/` + +[[put-snapshot-repo-api-desc]] +==== {api-description-title} + +A snapshot repository must be registered before you can perform +<> operations. You can use the put +snapshot repository API to register new repositories and update existing ones. +See <>. + +TIP: Because snapshot formats can change between major versions of +{es}, we recommend registering a new snapshot repository for each major version. +See <>. + +[[create-snapshot-repo-api-path-params]] +==== {api-path-parms-title} + +``:: +(Required, string) +Name of the snapshot repository to register or update. + +[[put-snapshot-repo-api-query-params]] +==== {api-query-parms-title} + +`master_timeout`:: +(Optional, <>) Specifies the period of time to wait for +a connection to the master node. If no response is received before the timeout +expires, the request fails and returns an error. Defaults to `30s`. ++ +IMPORTANT: You can also specify this value using the `master_timeout` request +body parameter. If both parameters are specified, only the query parameter is +used. + +`timeout`:: +(Optional, <>) Specifies the period of time to wait for +a response. If no response is received before the timeout expires, the request +fails and returns an error. Defaults to `30s`. ++ +IMPORTANT: You can also specify this value using the `timeout` request body +parameter. If both parameters are specified, only the query parameter is used. + +`verify`:: +(Optional, boolean) +If `true`, the request verifies the repository is functional on all master and +data nodes in the cluster. If `false`, this verification is skipped. Defaults to +`true`. ++ +You can manually perform this verification using the +<>. ++ +IMPORTANT: You can also specify this value using the `verify` request body +parameter. If both parameters are specified, only the query parameter is used. + +[role="child_attributes"] +[[put-snapshot-repo-api-request-body]] +==== {api-request-body-title} + +`master_timeout`:: +(Optional, <>) +Specifies the period of time to wait for +a connection to the master node. If no response is received before the timeout +expires, the request fails and returns an error. Defaults to `30s`. ++ +IMPORTANT: You can also specify this value using the `master_timeout` query +parameter. If both parameters are specified, only the query parameter is used. + +`timeout`:: +(Optional, <>) +Specifies the period of time to wait for +a response. If no response is received before the timeout expires, the request +fails and returns an error. Defaults to `30s`. ++ +IMPORTANT: You can also specify this value using the `timeout` query +parameter. If both parameters are specified, only the query parameter is used. + +[[put-snapshot-repo-api-request-type]] +`type`:: ++ +-- +(Required, string) +Repository type. + +.Valid values for `type` +[%collapsible%open] +==== +`fs`:: +Shared file system repository. Repositories of this type use a shared file +system to store snapshots. This file system must accessible to all master and +data nodes in the cluster. ++ +IMPORTANT: To register a shared file system repository, you must mount the same +shared filesystem to the same location on all master and data nodes. This +location must be registered in the `path.repo` setting on all master and data +nodes in the cluster. ++ +See <>. + +[xpack]#`source`#:: +Source-only repository. You can use source-only repositories to create minimal, +source-only snapshots that take up to 50% less space on disk. ++ +Source-only snapshots are only supported if the <> is enabled and no +<> is applied. ++ +WARNING: Source-only snapshots contain stored fields and index metadata. They do +not include index or doc values structures and are not searchable when restored. +After restoring a source-only snapshot, you must <> the +data into a new index. ++ +See <>. + +`url`:: +URL repository. Repositories of this type are read-only +for the cluster. This means the cluster can retrieve or restore snapshots from +the repository but cannot write or create snapshots in it. ++ +You can use URL repositories as an alternative way to give a cluster read-only +access to a shared file system (`fs`) repository. ++ +See <>. +==== + +More repository types are available through these official +plugins: + +* {plugins}/repository-s3.html[repository-s3] for S3 repository support +* {plugins}/repository-hdfs.html[repository-hdfs] for HDFS repository support in + Hadoop environments +* {plugins}/repository-azure.html[repository-azure] for Azure storage + repositories +* {plugins}/repository-gcs.html[repository-gcs] for Google Cloud Storage + repositories +-- + +`settings`:: ++ +-- +(Required, object) +Contains settings for the repository. Valid properties for the `settings` object +depend on the repository type, set using the +<> parameter. + +.Valid `settings` properties for `fs` repositories +[%collapsible%open] +==== +`chunk_size`:: +(Optional, <>) +Maximum size of files in snapshots. In snapshots, files larger than this are +broken down into chunks of this size or smaller. Defaults to `null` (unlimited +file size). + +`compress`:: +(Optional, boolean) +If `true`, metadata files, such as index mappings and settings, are compressed +in snapshots. Data files are not compressed. Defaults to `true`. + +`location`:: +(Required, string) +Location of the shared filesystem used to store and retrieve snapshots. This +location must be registered in the `path.repo` setting on all master and data +nodes in the cluster. + +`max_restore_bytes_per_sec`:: +(Optional, <>) +Maximum snapshot restore rate per node. Defaults to `40mb` per second. + +`max_snapshot_bytes_per_sec`:: +(Optional, <>) +Maximum snapshot creation rate per node. Defaults to `40mb` per second. + +`readonly`:: +(Optional, boolean) +If `true`, the repository is read-only. The cluster can retrieve and restore +snapshots from the repository but not write to the repository or create +snapshots in it. ++ +If `false`, the cluster can write to the repository and create snapshots in it. +Defaults to `false`. ++ +[TIP] +===== +If you register the same snapshot repository with multiple clusters, only +one cluster should have write access to the repository. Having multiple clusters +write to the repository at the same time risks corrupting the contents of the +repository. + +Only a cluster with write access can create snapshots in the repository. All +other clusters connected to the repository should have the `readonly` parameter +set to `true`. This means those clusters can retrieve or restore snapshots from +the repository but not create snapshots in it. +===== +==== + +.Valid `settings` properties for `source` repositories +[%collapsible%open] +==== +`delegate_type`:: +(Optional, string) +Delegated repository type. For valid values, see the +<>. ++ +`source` repositories can use `settings` properties for its delegated repository +type. See <>. + +==== + +.Valid `settings` properties for `url` repositories +[%collapsible%open] +==== +`url`:: +(Required, string) +URL location of the root of the shared filesystem repository. The following +protocols are supported: + +* `file` +* `ftp` +* `http` +* `https` +* `jar` + +URLs using the `file` protocol must point to the location of a shared filesystem +accessible to all master and data nodes in the cluster. This location must be +registered in the `path.repo` setting. + +URLs using the `http`, `https`, or `ftp` protocols must be whitelisted in the +`repositories.url.allowed_urls` setting. This setting supports wildcards in the +place of a host, path, query, or fragment in the URL. +==== +-- + +`verify`:: +(Optional, boolean) +If `true`, the request verifies the repository is functional on all master and +data nodes in the cluster. If `false`, this verification is skipped. Defaults to +`true`. ++ +You can manually perform this verification using the +<>. ++ +IMPORTANT: You can also specify this value using the `verify` query +parameter. If both parameters are specified, only the query parameter is used. \ No newline at end of file diff --git a/docs/reference/snapshot-restore/apis/snapshot-restore-apis.asciidoc b/docs/reference/snapshot-restore/apis/snapshot-restore-apis.asciidoc index f820fc5e09674..14bfc454bad7e 100644 --- a/docs/reference/snapshot-restore/apis/snapshot-restore-apis.asciidoc +++ b/docs/reference/snapshot-restore/apis/snapshot-restore-apis.asciidoc @@ -17,6 +17,8 @@ content may not be included yet. === Snapshot repository management APIs * <> +* <> -include::clean-up-repo-api.asciidoc[] \ No newline at end of file +include::clean-up-repo-api.asciidoc[] +include::put-repo-api.asciidoc[] \ No newline at end of file diff --git a/docs/reference/snapshot-restore/index.asciidoc b/docs/reference/snapshot-restore/index.asciidoc index 31b5d81da28cc..a428ca4e39850 100644 --- a/docs/reference/snapshot-restore/index.asciidoc +++ b/docs/reference/snapshot-restore/index.asciidoc @@ -42,6 +42,7 @@ cluster is by using the snapshot and restore functionality. // end::backup-warning[] [float] +[[snapshot-restore-version-compatibility]] === Version compatibility IMPORTANT: Version compatibility refers to the underlying Lucene index