Register a snapshot repository

This guide shows you how to register a snapshot repository. A snapshot repository is an off-cluster storage location for your snapshots. You must register a repository before you can take or restore snapshots.

In this guide, you’ll learn how to:

When registering a snapshot repository, keep the following in mind:

You can register and manage snapshot repositories in two ways:

To manage repositories in Kibana, go to the main menu and click Stack Management > Snapshot and Restore > Repositories. To register a snapshot repository, click Register repository.

You can also register a repository using the Create snapshot repository API.

Supported snapshot repository types vary based on your deployment type:

Elasticsearch Service deployments automatically register the found-snapshots repository. Elasticsearch Service uses this repository and the cloud-snapshot-policy to take periodic snapshots of your cluster. You can also use the found-snapshots repository for your own SLM policies or to store searchable snapshots.

The found-snapshots repository is specific to each deployment. However, you can restore snapshots from another deployment’s found-snapshots repository if the deployments are under the same account and in the same region. See the Cloud Snapshot and restore documentation to learn more.

Elasticsearch Service deployments also support the following repository types:

If you manage your own Elasticsearch cluster, you can use the following built-in snapshot repository types:

Other repository types are available through official plugins:

You can also use alternative storage implementations with these repository types, as long as the alternative implementation is fully compatible. For instance, MinIO provides an alternative implementation of the AWS S3 API and you can use MinIO with the s3 repository type.

Note that some storage systems claim to be compatible with these repository types without emulating their behaviour in full. Elasticsearch requires full compatibility. In particular the alternative implementation must support the same set of API endpoints, return the same errors in case of failures, and offer equivalent consistency guarantees and performance even when accessed concurrently by multiple nodes. Incompatible error codes, consistency or performance may be particularly hard to track down since errors, consistency failures, and performance issues are usually rare and hard to reproduce.

You can perform some basic checks of the suitability of your storage system using the Repository analysis API. If this API does not complete successfully, or indicates poor performance, then your storage system is not fully compatible and is therefore unsuitable for use as a snapshot repository. You will need to work with the supplier of your storage system to address any incompatibilities you encounter.

When you register a snapshot repository, Elasticsearch automatically verifies that the repository is available and functional on all master and data nodes.

To disable this verification, set the create snapshot repository API's verify query parameter to false. You can’t disable repository verification in Kibana.

response = client.snapshot.create_repository(
  repository: 'my_unverified_backup',
  verify: false,
  body: {
    type: 'fs',
    settings: {
      location: 'my_unverified_backup_location'
    }
  }
)
puts response

PUT _snapshot/my_unverified_backup?verify=false
{
  "type": "fs",
  "settings": {
    "location": "my_unverified_backup_location"
  }
}

If wanted, you can manually run the repository verification check. To verify a repository in Kibana, go to the Repositories list page and click the name of a repository. Then click Verify repository. You can also use the verify snapshot repository API.

response = client.snapshot.verify_repository(
  repository: 'my_unverified_backup'
)
puts response

POST _snapshot/my_unverified_backup/_verify

If successful, the request returns a list of nodes used to verify the repository. If verification fails, the request returns an error.

You can test a repository more thoroughly using the repository analysis API.

Repositories can over time accumulate data that is not referenced by any existing snapshot. This is a result of the data safety guarantees the snapshot functionality provides in failure scenarios during snapshot creation and the decentralized nature of the snapshot creation process. This unreferenced data does in no way negatively impact the performance or safety of a snapshot repository but leads to higher than necessary storage use. To remove this unreferenced data, you can run a cleanup operation on the repository. This will trigger a complete accounting of the repository’s contents and delete any unreferenced data.

To run the repository cleanup operation in Kibana, go to the Repositories list page and click the name of a repository. Then click Clean up repository.

You can also use the clean up snapshot repository API.

POST _snapshot/my_repository/_cleanup

The API returns:

{
  "results": {
    "deleted_bytes": 20,
    "deleted_blobs": 5
  }
}

Depending on the concrete repository implementation the numbers shown for bytes free as well as the number of blobs removed will either be an approximation or an exact result. Any non-zero value for the number of blobs removed implies that unreferenced blobs were found and subsequently cleaned up.

Please note that most of the cleanup operations executed by this endpoint are automatically executed when deleting any snapshot from a repository. If you regularly delete snapshots, you will in most cases not get any or only minor space savings from using this functionality and should lower your frequency of invoking it accordingly.

You may wish to make an independent backup of your repository, for instance so that you have an archive copy of its contents that you can use to recreate the repository in its current state at a later date.

You must ensure that Elasticsearch does not write to the repository while you are taking the backup of its contents. You can do this by unregistering it, or registering it with readonly: true, on all your clusters. If Elasticsearch writes any data to the repository during the backup then the contents of the backup may not be consistent and it may not be possible to recover any data from it in future.

Alternatively, if your repository supports it, you may take an atomic snapshot of the underlying filesystem and then take a backup of this filesystem snapshot. It is very important that the filesystem snapshot is taken atomically.

When restoring a repository from a backup, you must not register the repository with Elasticsearch until the repository contents are fully restored. If you alter the contents of a repository while it is registered with Elasticsearch then the repository may become unreadable or may silently lose some of its contents.