Amazon Elasticsearch Service
Developer Guide (API Version 2015-01-01)

Working with Amazon Elasticsearch Service Index Snapshots

Snapshots are backups of a cluster's data and state. They provide a convenient way to migrate data across Amazon ES domains and recover from failure. The service supports restoring from snapshots taken on both Amazon ES domains and self-managed Elasticsearch clusters.

Amazon ES takes daily automated snapshots of the primary index shards in a domain, as described in Configuring Automatic Snapshots. It stores these automated snapshots in a preconfigured Amazon S3 bucket for 14 days at no additional charge to you. You can use these snapshots to restore the domain.

You cannot, however, use automated snapshots to migrate to new domains. Automated snapshots are read-only from within a given domain. For migrations, you must use manual snapshots stored in your own repository (an S3 bucket). Standard S3 charges apply to manual snapshots.


Some users find tools like the Curator CLI convenient for index and snapshot management. The Curator CLI offers advanced filtering functionality that can help simplify tasks on complex clusters.

Manual Snapshot Prerequisites

To create index snapshots manually, you must work with IAM and Amazon S3. Verify that you have met the following prerequisites before you attempt to take a snapshot.

Prerequisite Description
S3 bucket Stores manual snapshots for your Amazon ES domain.
IAM role Delegates permissions to Amazon Elasticsearch Service. The trust relationship for the role must specify Amazon Elasticsearch Service in the Principal statement. The IAM role also is required to register your snapshot repository with Amazon ES. Only IAM users with access to this role may register the snapshot repository.
IAM policy Specifies the actions that Amazon S3 may perform with your S3 bucket. The policy must be attached to the IAM role that delegates permissions to Amazon Elasticsearch Service. The policy must specify an S3 bucket in a Resource statement.

S3 Bucket

You need an S3 bucket to store manual snapshots. Make a note of its Amazon Resource Name (ARN), which takes the form of arn:aws:s3:::bucket-name. You need it in two places:

  • Resource statement of the IAM policy that is attached to your IAM role

  • Python client that is used to register a snapshot repository

For more information, see Create a Bucket in the Amazon S3 Getting Started Guide.

IAM Role

You must have a role that specifies Amazon Elasticsearch Service,, in a Service statement in its trust relationship, as shown in the following example:

{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "" }, "Action": "sts:AssumeRole" } ] }

If you create this role using the IAM console, Amazon ES is not included in the Select role type list. However, you can still create the role by choosing Amazon EC2, following the steps to create the role, and then editing the role's trust relationships to instead of For instructions and additional information, see Creating a Role for an AWS Service and Modifying a Role in the IAM User Guide.


Only IAM users or roles with access to this service role may register snapshot repositories. A common way to provide access is to attach the following policy to a different user or role:

{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": "iam:PassRole", "Resource": "arn:aws:iam::123456789012:role/TheServiceRole" } }

IAM Policy

You must attach an IAM policy to the IAM role. The policy specifies the S3 bucket that is used to store manual snapshots for your Amazon ES domain. The following example specifies the ARN of the es-index-backups bucket:

{ "Version":"2012-10-17", "Statement":[ { "Action":[ "s3:ListBucket" ], "Effect":"Allow", "Resource":[ "arn:aws:s3:::es-index-backups" ] }, { "Action":[ "s3:GetObject", "s3:PutObject", "s3:DeleteObject" ], "Effect":"Allow", "Resource":[ "arn:aws:s3:::es-index-backups/*" ] } ] }

For more information, see Creating Customer Managed Policies and Attaching Managed Policies in the IAM User Guide.

Registering a Manual Snapshot Repository

You must register a snapshot repository with Amazon Elasticsearch Service before you can take manual index snapshots. This one-time operation requires that you sign your AWS request with credentials for one of the users or roles specified in the IAM role's trust relationship, as described in Manual Snapshot Prerequisites.

You can't use curl to perform this operation because it doesn't support AWS request signing. Instead, use the sample Python client to register your snapshot directory.

If your domain resides within a VPC, your computer must be connected to the VPC in order for the Python client to successfully register the snapshot repository. Accessing a VPC varies by network configuration, but likely involves connecting to a VPN or corporate network. To check that you can reach the Amazon ES domain, navigate to in a web browser and verify that you receive the default JSON response.

Sample Python Client

Save the following sample Python code as a Python file, such as The client requires the requests and requests-aws4auth packages.

Registering a snapshot directory is a one-time operation, but to migrate from one domain to another, you must register the same snapshot repository on the old domain and the new domain. The client also contains commented-out examples for other snapshot operations.

You must update the following in your code:


IAM credential


IAM credential


AWS region where you created the snapshot repository


Endpoint for your Amazon ES domain


Name of the snapshot repository


Must include the name of the S3 bucket and the ARN for the IAM role that you created in Manual Snapshot Prerequisites. To enable server-side encryption with S3-managed keys for the snapshot repository, add "server_side_encryption": true to the "settings" JSON.

import requests from requests_aws4auth import AWS4Auth AWS_ACCESS_KEY_ID='' AWS_SECRET_ACCESS_KEY='' region = 'us-west-1' service = 'es' awsauth = AWS4Auth(AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, region, service) host = '' # include https:// and trailing / # REGISTER REPOSITORY path = '_snapshot/my-snapshot-repo' # the Elasticsearch API endpoint url = host + path payload = { "type": "s3", "settings": { "bucket": "s3-bucket-name", "region": "us-west-1", "role_arn": "arn:aws:iam::123456789012:role/TheServiceRole" } } headers = {"Content-Type": "application/json"} r = requests.put(url, auth=awsauth, json=payload, headers=headers) # requests.get, post, put, and delete all have similar syntax print(r.text) # # TAKE SNAPSHOT # # path = '_snapshot/my-snapshot-repo/my-snapshot' # url = host + path # # r = requests.put(url, auth=awsauth) # # print(r.text) # # # DELETE INDEX # # path = 'my-index' # url = host + path # # r = requests.delete(url, auth=awsauth) # # print(r.text) # # # RESTORE SNAPSHOT (ALL INDICES) # # path = '_snapshot/my-snapshot-repo/my-snapshot/_restore' # url = host + path # # r =, auth=awsauth) # # print(r.text) # # # RESTORE SNAPSHOT (ONE INDEX) # # path = '_snapshot/my-snapshot-repo/my-snapshot/_restore' # url = host + path # # payload = {"indices": "my-index"} # # headers = {"Content-Type": "application/json"} # # r =, auth=awsauth, json=payload, headers=headers) # # print(r.text)


If the S3 bucket is in the us-east-1 region, you need to use "endpoint": "" instead of "region": "us-east-1".

Taking Manual Snapshots

You specify two pieces of information when you create a snapshot:

  • Name of your snapshot repository

  • Name for the snapshot

The examples in this chapter use curl, a common HTTP client, for convenience and brevity. If your access policies specify IAM users or roles, however, you must sign your snapshot requests. You can use the commented-out examples in the sample Python client to make signed HTTP requests to the same endpoints that the curl commands use.

To manually take a snapshot

  • Run the following command to manually take a snapshot:

    curl -XPUT 'elasticsearch-domain-endpoint/_snapshot/repository/snapshot-name'


The time required to take a snapshot increases with the size of the Amazon ES domain. Long-running snapshot operations commonly encounter the following error: 504 GATEWAY_TIMEOUT. Typically, you can ignore these errors and wait for the operation to complete successfully. Use the following command to verify the state of all snapshots of your domain:

curl -XGET 'elasticsearch-domain-endpoint/_snapshot/repository/_all?pretty'

For more information about the options available to you when taking a snapshot, see Snapshot and Restore in the Elasticsearch documentation.

Restoring Snapshots

To restore a snapshot, perform the following procedure:

  1. Identify the snapshot that you want to restore. To see all snapshot repositories, run the following command:

    curl -XGET 'elasticsearch-domain-endpoint/_snapshot?pretty'

    After you identify the repository, run the following command to see all snapshots:

    curl -XGET 'elasticsearch-domain-endpoint/_snapshot/repository/_all?pretty'


    Most automated snapshots are stored in the cs-automated repository. If your domain encrypts data at rest, they are stored in the cs-automated-enc repository. If you don't see the manual snapshot repository that you're looking for, make sure that you registered it to the domain.

  2. Delete or rename all open indices in the Amazon ES domain.

    You can't restore a snapshot of your indices to an Elasticsearch cluster that already contains indices with the same names. Currently, Amazon ES does not support the Elasticsearch _close API, so you must use one of the following alternatives:

    • Delete the indices on the same Amazon ES domain, and then restore the snapshot.

    • Restore the snapshot to a different Amazon ES domain (only possible with manual snapshots).

    The following example shows how to delete all existing indices for a domain:

    curl -XDELETE 'elasticsearch-domain-endpoint/_all'

    If you don't plan to restore all indices, though, you might want to delete only one:

    curl -XDELETE 'elasticsearch-domain-endpoint/index-name'
  3. To restore a snapshot, run the following command:

    curl -XPOST 'elasticsearch-domain-endpoint/_snapshot/repository/snapshot/_restore'

    Due to special permissions on the .kibana index, attempts to restore all indices might fail, especially if you try to restore from an automated snapshot. The following example restores just one index, my-index, from 2017-snapshot in the cs-automated snapshot repository:

    curl -XPOST 'elasticsearch-domain-endpoint/_snapshot/cs-automated/2017-snapshot/_restore' -d '{"indices": "my-index"}' -H 'Content-Type: application/json'

For more information about restoring only certain indices from a snapshot, see Snapshot and Restore in the Elasticsearch documentation.


If not all primary shards were available for the indices involved, a snapshot might have a state of PARTIAL. This value indicates that data from at least one shard was not stored successfully. You can still restore from a partial snapshot, but you might need to use older snapshots to restore any missing indices.