Registering or updating a snapshot repository

Introduced 1.0

You can register a new repository in which to store snapshots or update information for an existing repository by using the snapshots API.

There are two types of snapshot repositories:

• File system (fs): For instructions on creating an fs repository, see Register repository shared file system.

• Amazon Simple Storage Service (Amazon S3) bucket (s3): For instructions on creating an s3 repository, see Register repository Amazon S3.

For instructions on creating a repository, see Register repository.

Path and HTTP methods

POST /_snapshot/<repository>/ 
PUT /_snapshot/<repository>/

Path parameters

Request parameters

Request parameters depend on the type of repository: fs or s3.

Common parameters

The following table lists parameters that can be used with both the fs and s3 repositories.

shard_path_type values

The following values are supported in the shard_path_type setting:

• FIXED: Keeps the path structure in the existing hierarchical manner, such as <ROOT>/<BASE_PATH>/indices/<index-id>/0/<SHARD_BLOBS>.
• HASHED_PREFIX: Prepends a hashed prefix at the start of the path for each unique shard ID, for example, <ROOT>/<HASH-OF-INDEX-ID-AND-SHARD-ID>/<BASE_PATH>/indices/<index-id>/0/<SHARD_BLOBS>.
• HASHED_INFIX: Appends a hashed prefix after the base path for each unique shard ID, for example, <ROOT>/<BASE-PATH>/<HASH-OF-INDEX-ID-AND-SHARD-ID>/indices/<index-id>/0/<SHARD_BLOBS>. The hash method used is FNV_1A_COMPOSITE_1, which uses the FNV1a hash function and generates a custom-encoded 64-bit hash value that scales well with most remote store options. FNV1a takes the most significant 6 bits to create a URL-safe Base64 character and the next 14 bits to create a binary string.

fs repository

s3 repository

For the base_path parameter, do not enter the s3:// prefix when entering your S3 bucket details. Only the name of the bucket is required.

Example requests

fs

The following example registers an fs repository using the local directory /mnt/snapshots as location:

PUT /_snapshot/my-fs-repository
{
  "type": "fs",
  "settings": {
    "location": "/mnt/snapshots"
  }
}

s3

The following request registers a new S3 repository called my-opensearch-repo in an existing bucket called my-open-search-bucket. By default, all snapshots are stored in the my/snapshot/directory:

PUT /_snapshot/my-opensearch-repo
{
  "type": "s3",
  "settings": {
    "bucket": "my-open-search-bucket",
    "base_path": "my/snapshot/directory"
  }
}

Example response

Upon success, the following JSON object is returned:

{
  "acknowledged": true
}

To verify that the repository was registered, use the Get snapshot repository API, passing the repository name as the repository path parameter.