Registering Or Updating A Snapshot Repository API

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.

Endpoints

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.

The server_side_encryption setting is removed as of OpenSearch 3.1.0. S3 applies server-side encryption as the base level of encryption for all S3 buckets. Because this cannot be disabled, this value repository setting had no effect. For more information, see Protecting data with server-side encryption.

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"
  }
}

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. Additionally, this repository is configured to use SSE-KMS, and the expected bucket owner AWS account ID is 123456789000.

PUT /_snapshot/my-opensearch-repo
{
  "type": "s3",
  "settings": {
    "bucket": "my-open-search-bucket",
    "base_path": "my/snapshot/directory",
    "server_side_encryption_type": "aws:kms",
    "server_side_encryption_kms_key_id": "arn:aws:kms:us-east-1:123456789000:key/kms-key-id",
    "server_side_encryption_encryption_context": "{\"additional-enc-ctx\": \"sample-context\"}",
    "expected_bucket_owner": "123456789000",
  }
}
'

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.