Create or update a snapshot repository
- POST also PUT /_snapshot/{repository}
If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters.
To register a snapshot repository, the cluster's global metadata must be writeable.
Ensure there are no cluster blocks (for example, cluster.blocks.read_only and clsuter.blocks.read_only_allow_delete settings) that prevent write access.
Several options for this API can be specified using a query parameter or a request body parameter. If both parameters are specified, only the query parameter is used.
About managing snapshotRequired authorization
- Cluster privileges manage
Authentication
Authorization: <value>Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:
curl -X GET "${ES_URL}/_cat/indices?v=true" \
-H "Authorization: ApiKey ${API_KEY}"
To get API keys, use the /_security/api_key APIs.
Authorization: Basic <credentials>Authorization: Bearer <token>Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API.
For examples, refer to Token-based authentication services
Query parameters
-
master_timeoutstring · default: 30s -
The period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to
-1. -
timeoutstring · default: 30s -
The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata. If no response is received before the timeout expires, the cluster metadata update still applies but the response will indicate that it was not completely acknowledged. To indicate that the request should never timeout, set it to
-1.
Request body
type: azure
-
settingsobject -
The repository settings.
-
chunk_sizenumber | string -
Big files can be broken down into multiple smaller blobs in the blob store during snapshotting. It is not recommended to change this value from its default unless there is an explicit reason for limiting the size of blobs in the repository. Setting a value lower than the default can result in an increased number of API calls to the blob store during snapshot create and restore operations compared to using the default value and thus make both operations slower and more costly. Specify the chunk size as a byte unit, for example:
10MB,5KB, 500B. The default varies by repository type. -
compressboolean · default: true -
When set to
true, metadata files are stored in compressed format. This setting doesn't affect index files that are already compressed by default. -
max_restore_bytes_per_secnumber | string -
The maximum snapshot restore rate per node. It defaults to unlimited. Note that restores are also throttled through recovery settings.
-
max_snapshot_bytes_per_secnumber | string -
The maximum snapshot creation rate per node. It defaults to 40mb per second. Note that if the recovery settings for managed services are set, then it defaults to unlimited, and the rate is additionally throttled through recovery settings.
-
base_pathstring -
The path to the repository data within the container. It defaults to the root directory.
NoteDon't set
base_pathwhen configuring a snapshot repository for Elastic Cloud Enterprise. Elastic Cloud Enterprise automatically generates thebase_pathfor each deployment so that multiple deployments can share the same bucket. -
delete_objects_max_sizenumber · default: 256 -
The maxmimum batch size, between 1 and 256, used for
BlobBatchrequests. Defaults to 256 which is the maximum number supported by the Azure blob batch API. -
location_modestring · default: primary_only -
Either
primary_onlyorsecondary_only. Note that if you set it tosecondary_only, it will forcereadonlytotrue. -
max_concurrent_batch_deletesnumber · default: 10 -
The maximum number of concurrent batch delete requests that will be submitted for any individual bulk delete with
BlobBatch. Note that the effective number of concurrent deletes is further limited by the Azure client connection and event loop thread limits. Defaults to 10, minimum is 1, maximum is 100. -
readonlyboolean · default: false -
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.Only a cluster with write access can create snapshots in the repository. All other clusters connected to the repository should have the
readonlyparameter set totrue. Iffalse, the cluster can write to the repository and create snapshots in it.ImportantIf 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.
type: gcs
-
settingsobjectrequired -
The repository settings.
-
chunk_sizenumber | string -
Big files can be broken down into multiple smaller blobs in the blob store during snapshotting. It is not recommended to change this value from its default unless there is an explicit reason for limiting the size of blobs in the repository. Setting a value lower than the default can result in an increased number of API calls to the blob store during snapshot create and restore operations compared to using the default value and thus make both operations slower and more costly. Specify the chunk size as a byte unit, for example:
10MB,5KB, 500B. The default varies by repository type. -
compressboolean · default: true -
When set to
true, metadata files are stored in compressed format. This setting doesn't affect index files that are already compressed by default. -
max_restore_bytes_per_secnumber | string -
The maximum snapshot restore rate per node. It defaults to unlimited. Note that restores are also throttled through recovery settings.
-
max_snapshot_bytes_per_secnumber | string -
The maximum snapshot creation rate per node. It defaults to 40mb per second. Note that if the recovery settings for managed services are set, then it defaults to unlimited, and the rate is additionally throttled through recovery settings.
-
application_namestringdeprecated -
The name used by the client when it uses the Google Cloud Storage service.
-
base_pathstring -
The path to the repository data within the bucket. It defaults to the root of the bucket.
NoteDon't set
base_pathwhen configuring a snapshot repository for Elastic Cloud Enterprise. Elastic Cloud Enterprise automatically generates thebase_pathfor each deployment so that multiple deployments can share the same bucket. -
readonlyboolean · default: false -
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.Only a cluster with write access can create snapshots in the repository. All other clusters connected to the repository should have the
readonlyparameter set totrue.If
false, the cluster can write to the repository and create snapshots in it.ImportantIf 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.
type: s3
-
settingsobjectrequired -
The repository settings.
NoteIn addition to the specified settings, you can also use all non-secure client settings in the repository settings. In this case, the client settings found in the repository settings will be merged with those of the named client used by the repository. Conflicts between client and repository settings are resolved by the repository settings taking precedence over client settings.
-
chunk_sizenumber | string -
Big files can be broken down into multiple smaller blobs in the blob store during snapshotting. It is not recommended to change this value from its default unless there is an explicit reason for limiting the size of blobs in the repository. Setting a value lower than the default can result in an increased number of API calls to the blob store during snapshot create and restore operations compared to using the default value and thus make both operations slower and more costly. Specify the chunk size as a byte unit, for example:
10MB,5KB, 500B. The default varies by repository type. -
compressboolean · default: true -
When set to
true, metadata files are stored in compressed format. This setting doesn't affect index files that are already compressed by default. -
max_restore_bytes_per_secnumber | string -
The maximum snapshot restore rate per node. It defaults to unlimited. Note that restores are also throttled through recovery settings.
-
max_snapshot_bytes_per_secnumber | string -
The maximum snapshot creation rate per node. It defaults to 40mb per second. Note that if the recovery settings for managed services are set, then it defaults to unlimited, and the rate is additionally throttled through recovery settings.
-
bucketstringrequired -
The name of the S3 bucket to use for snapshots. The bucket name must adhere to Amazon's S3 bucket naming rules.
- External docs
-
base_pathstring -
The path to the repository data within its bucket. It defaults to an empty string, meaning that the repository is at the root of the bucket. The value of this setting should not start or end with a forward slash (
/).NoteDon't set base_path when configuring a snapshot repository for Elastic Cloud Enterprise. Elastic Cloud Enterprise automatically generates the
base_pathfor each deployment so that multiple deployments may share the same bucket. -
buffer_sizenumber | string -
The minimum threshold below which the chunk is uploaded using a single request. Beyond this threshold, the S3 repository will use the AWS Multipart Upload API to split the chunk into several parts, each of
buffer_sizelength, and to upload each part in its own request. Note that setting a buffer size lower than 5mb is not allowed since it will prevent the use of the Multipart API and may result in upload errors. It is also not possible to set a buffer size greater than 5gb as it is the maximum upload size allowed by S3. Defaults to100mbor 5% of JVM heap, whichever is smaller. -
canned_aclstring · default: private -
The S3 repository supports all S3 canned ACLs:
private,public-read,public-read-write,authenticated-read,log-delivery-write,bucket-owner-read,bucket-owner-full-control. You could specify a canned ACL using thecanned_aclsetting. When the S3 repository creates buckets and objects, it adds the canned ACL into the buckets and objects. - External docs
-
delete_objects_max_sizenumber · default: 1000 -
The maxmimum batch size, between 1 and 1000, used for
DeleteObjectsrequests. Defaults to 1000 which is the maximum number supported by the AWS DeleteObjects API. - External docs
-
get_register_retry_delaystring · default: 5s -
The time to wait before trying again if an attempt to read a linearizable register fails.
-
max_multipart_partsnumber · default: 10000 -
The maximum number of parts that Elasticsearch will write during a multipart upload of a single object. Files which are larger than
buffer_size × max_multipart_partswill be chunked into several smaller objects. Elasticsearch may also split a file across multiple objects to satisfy other constraints such as thechunk_sizelimit. Defaults to10000which is the maximum number of parts in a multipart upload in AWS S3. -
max_multipart_upload_cleanup_sizenumber · default: 1000 -
The maximum number of possibly-dangling multipart uploads to clean up in each batch of snapshot deletions. Defaults to 1000 which is the maximum number supported by the AWS ListMultipartUploads API. If set to
0, Elasticsearch will not attempt to clean up dangling multipart uploads. - External docs
-
readonlyboolean · default: false -
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.
Only a cluster with write access can create snapshots in the repository. All other clusters connected to the repository should have the
readonlyparameter set totrue.If
false, the cluster can write to the repository and create snapshots in it.ImportantIf 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.
-
server_side_encryptionboolean · default: false -
When set to
true, files are encrypted on server side using an AES256 algorithm. -
storage_classstring · default: standard -
The S3 storage class for objects written to the repository. Values may be
standard,reduced_redundancy,standard_ia,onezone_ia, andintelligent_tiering. - Reference
-
throttled_delete_retry.delay_incrementstring · default: 50ms -
The delay before the first retry and the amount the delay is incremented by on each subsequent retry. The default is 50ms and the minimum is 0ms.
-
throttled_delete_retry.maximum_delaystring · default: 5s -
The upper bound on how long the delays between retries will grow to. The default is 5s and the minimum is 0ms.
-
throttled_delete_retry.maximum_number_of_retriesnumber -
The number times to retry a throttled snapshot deletion. The default is 10 and the minimum value is 0 which will disable retries altogether. Note that if retries are enabled in the Azure client, each of these retries comprises that many client-level retries.
type: fs
-
settingsobjectrequired -
The repository settings.
-
chunk_sizenumber | string -
Big files can be broken down into multiple smaller blobs in the blob store during snapshotting. It is not recommended to change this value from its default unless there is an explicit reason for limiting the size of blobs in the repository. Setting a value lower than the default can result in an increased number of API calls to the blob store during snapshot create and restore operations compared to using the default value and thus make both operations slower and more costly. Specify the chunk size as a byte unit, for example:
10MB,5KB, 500B. The default varies by repository type. -
compressboolean · default: true -
When set to
true, metadata files are stored in compressed format. This setting doesn't affect index files that are already compressed by default. -
max_restore_bytes_per_secnumber | string -
The maximum snapshot restore rate per node. It defaults to unlimited. Note that restores are also throttled through recovery settings.
-
max_snapshot_bytes_per_secnumber | string -
The maximum snapshot creation rate per node. It defaults to 40mb per second. Note that if the recovery settings for managed services are set, then it defaults to unlimited, and the rate is additionally throttled through recovery settings.
-
locationstringrequired -
The location of the shared filesystem used to store and retrieve snapshots. This location must be registered in the
path.reposetting on all master and data nodes in the cluster. Unlikepath.repo, this setting supports only a single file path. -
max_number_of_snapshotsnumber · default: 2147483647 -
The maximum number of snapshots the repository can contain. The default is
Integer.MAX_VALUE, which is 2^31-1 or2147483647. -
readonlyboolean · default: false -
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.Only a cluster with write access can create snapshots in the repository. All other clusters connected to the repository should have the
readonlyparameter set totrue.If
false, the cluster can write to the repository and create snapshots in it.ImportantIf 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.
type: url
-
settingsobjectrequired -
The repository settings.
-
chunk_sizenumber | string -
Big files can be broken down into multiple smaller blobs in the blob store during snapshotting. It is not recommended to change this value from its default unless there is an explicit reason for limiting the size of blobs in the repository. Setting a value lower than the default can result in an increased number of API calls to the blob store during snapshot create and restore operations compared to using the default value and thus make both operations slower and more costly. Specify the chunk size as a byte unit, for example:
10MB,5KB, 500B. The default varies by repository type. -
compressboolean · default: true -
When set to
true, metadata files are stored in compressed format. This setting doesn't affect index files that are already compressed by default. -
max_restore_bytes_per_secnumber | string -
The maximum snapshot restore rate per node. It defaults to unlimited. Note that restores are also throttled through recovery settings.
-
max_snapshot_bytes_per_secnumber | string -
The maximum snapshot creation rate per node. It defaults to 40mb per second. Note that if the recovery settings for managed services are set, then it defaults to unlimited, and the rate is additionally throttled through recovery settings.
-
http_socket_timeoutstring · default: 50s -
The maximum wait time for data transfers over a connection.
-
max_number_of_snapshotsnumber · default: 2147483647 -
The maximum number of snapshots the repository can contain. The default is
Integer.MAX_VALUE, which is 2^31-1 or2147483647. -
urlstringrequired -
The URL location of the root of the shared filesystem repository. The following protocols are supported:
fileftphttphttpsjar
URLs using the HTTP, HTTPS, or FTP protocols must be explicitly allowed with the
repositories.url.allowed_urlscluster setting. This setting supports wildcards in the place of a host, path, query, or fragment in the URL.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.reposetting. You don't need to register URLs using the FTP, HTTP, HTTPS, or JAR protocols in thepath.reposetting.
type: source