[DOCS] Add put snapshot repo API docs (#56827) (#56900)

docs/reference/snapshot-restore/apis/put-repo-api.asciidoc

@@ -0,0 +1,266 @@
+[[put-snapshot-repo-api]]
+=== Put snapshot repository API
+++++
+<titleabbrev>Put snapshot repository</titleabbrev>
+++++
+
+Registers or updates a <<snapshots-register-repository,snapshot repository>>.
+
+[source,console]
+----
+PUT /_snapshot/my_repository
+{
+  "type": "fs",
+  "settings": {
+    "location": "my_backup_location"
+  }
+}
+----
+
+[[put-snapshot-repo-api-request]]
+==== {api-request-title}
+
+`PUT /_snapshot/<repository>`
+
+`POST /_snapshot/<repository>`
+
+[[put-snapshot-repo-api-desc]]
+==== {api-description-title}
+
+A snapshot repository must be registered before you can perform
+<<snapshot-restore,snapshot and restore>> operations. You can use the put
+snapshot repository API to register new repositories and update existing ones.
+See <<snapshots-register-repository>>.
+
+TIP: Because snapshot formats can change between major versions of
+{es}, we recommend registering a new snapshot repository for each major version.
+See <<snapshot-restore-version-compatibility>>.
+
+[[create-snapshot-repo-api-path-params]]
+==== {api-path-parms-title}
+
+`<repository>`::
+(Required, string)
+Name of the snapshot repository to register or update.
+
+[[put-snapshot-repo-api-query-params]]
+==== {api-query-parms-title}
+
+`master_timeout`::
+(Optional, <<time-units, time units>>) 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, <<time-units, time units>>) 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
+<<snapshots-repository-verification,verify snapshot repository API>>.
++
+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, <<time-units, time units>>)
+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, <<time-units, time units>>)
+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 <<snapshots-filesystem-repository>>.
+
+[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 <<mapping-source-field,`_source`
+field>> is enabled and no
+<<request-body-search-source-filtering,source-filtering>> 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 <<docs-reindex,reindex>> the
+data into a new index.
++
+See <<snapshots-source-only-repository>>.
+
+`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 <<snapshots-read-only-repository>>.
+====
+
+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
+<<put-snapshot-repo-api-request-type,`type`>> parameter.
+
+.Valid `settings` properties for `fs` repositories
+[%collapsible%open]
+====
+`chunk_size`::
+(Optional, <<byte-units,byte value>>)
+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, <<byte-units,byte value>>)
+Maximum snapshot restore rate per node. Defaults to `40mb` per second.
+
+`max_snapshot_bytes_per_sec`::
+(Optional, <<byte-units,byte value>>)
+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
+<<put-snapshot-repo-api-request-type,`type` parameter>>.
++
+`source` repositories can use `settings` properties for its delegated repository
+type. See <<snapshots-source-only-repository>>.
+
+====
+
+.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
+<<snapshots-repository-verification,verify snapshot repository API>>.
++
+IMPORTANT: You can also specify this value using the `verify` query
+parameter. If both parameters are specified, only the query parameter is used.

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

@@ -17,6 +17,8 @@ content may not be included yet.
 === Snapshot repository management APIs
 
 * <<clean-up-snapshot-repo-api,Clean up snapshot repository>>
+* <<put-snapshot-repo-api,Put snapshot repository>>
 
 
 include::clean-up-repo-api.asciidoc[]
+include::put-repo-api.asciidoc[]

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