Create or update snapshot repository API
- Create or update snapshot repository API

Create or update snapshot repository API

Registers or updates a snapshot repository.

PUT /_snapshot/my_repository
{
  "type": "fs",
  "settings": {
    "location": "my_backup_location"
  }
}

Request

PUT /_snapshot/<repository>

POST /_snapshot/<repository>

Prerequisites

If the Elasticsearch security features are enabled, you must have the manage cluster privilege to use this API.
To register a snapshot repository, the cluster’s global metadata must be writeable. Ensure there aren’t any cluster blocks that prevent write access.

Path parameters

<repository>

(Required, string) Name of the snapshot repository to register or update.

Query parameters

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.

master_timeout

(Optional, 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.

timeout

(Optional, 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.

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 verify snapshot repository API.

Request body

type

(Required, string) Repository type.

Valid values for type

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.

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 Shared file system repository.

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 _source field is enabled and no source-filtering is applied.

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 reindex the data into a new index.

See 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 Read-only URL repository.

More repository types are available through these official plugins:

repository-s3 for S3 repository support
repository-hdfs for HDFS repository support in Hadoop environments
repository-azure for Azure storage repositories
repository-gcs for Google Cloud Storage repositories

settings

(Required, object) Contains settings for the repository.

The following settings properties are valid for all repository types:

Properties of settings

chunk_size

(Optional, 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.

max_number_of_snapshots

(Optional, integer) Maximum number of snapshots the repository can contain. Defaults to 500.

We do not recommend increasing max_number_of_snapshots. Larger snapshot repositories may degrade master node performance and cause stability issues. Instead, delete older snapshots or use multiple repositories.

max_restore_bytes_per_sec

(Optional, byte value) Maximum snapshot restore rate per node. Defaults to unlimited. Note that restores are also throttled through recovery settings.

max_snapshot_bytes_per_sec

(Optional, 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.

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.

Other accepted settings properties depend on the repository type, set using the type parameter.

Valid settings properties for fs repositories

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.

Valid settings properties for source repositories

delegate_type

(Optional, string) Delegated repository type. For valid values, see the type parameter.

source repositories can use settings properties for its delegated repository type. See Source-only repository.

Valid settings properties for url repositories

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 http, https, or ftp protocols must be explicitly allowed with the repositories.url.allowed_urls cluster 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.repo setting. You don’t need to register URLs using the ftp, http, https, or jar protocols in the path.repo setting. —-

http_max_retries

(Optional, integer) Maximum number of retries for http and https URLs. Defaults to 5.

http_socket_timeout

(Optional, time value) Maximum wait time for data transfers over a connection. Defaults to 50s.

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 verify snapshot repository API.