S3 repository

To register an S3 repository, specify the type as s3 when creating the repository. The repository defaults to using ECS IAM Role credentials for authentication. You can also use Kubernetes service accounts for authentication.

The only mandatory setting is the bucket name:

resp = client.snapshot.create_repository(
    name="my_s3_repository",
    repository={
        "type": "s3",
        "settings": {
            "bucket": "my-bucket"
        }
    },
)
print(resp)

const response = await client.snapshot.createRepository({
  name: "my_s3_repository",
  repository: {
    type: "s3",
    settings: {
      bucket: "my-bucket",
    },
  },
});
console.log(response);

PUT _snapshot/my_s3_repository
{
  "type": "s3",
  "settings": {
    "bucket": "my-bucket"
  }
}

The client that you use to connect to S3 has a number of settings available. The settings have the form s3.client.CLIENT_NAME.SETTING_NAME. By default, s3 repositories use a client named default, but this can be modified using the repository setting client. For example:

resp = client.snapshot.create_repository(
    name="my_s3_repository",
    repository={
        "type": "s3",
        "settings": {
            "bucket": "my-bucket",
            "client": "my-alternate-client"
        }
    },
)
print(resp)

const response = await client.snapshot.createRepository({
  name: "my_s3_repository",
  repository: {
    type: "s3",
    settings: {
      bucket: "my-bucket",
      client: "my-alternate-client",
    },
  },
});
console.log(response);

PUT _snapshot/my_s3_repository
{
  "type": "s3",
  "settings": {
    "bucket": "my-bucket",
    "client": "my-alternate-client"
  }
}

Most client settings can be added to the elasticsearch.yml configuration file with the exception of the secure settings, which you add to the Elasticsearch keystore. For more information about creating and updating the Elasticsearch keystore, see Secure settings.

For example, if you want to use specific credentials to access S3 then run the following commands to add these credentials to the keystore.

bin/elasticsearch-keystore add s3.client.default.access_key
bin/elasticsearch-keystore add s3.client.default.secret_key
# a session token is optional so the following command may not be needed
bin/elasticsearch-keystore add s3.client.default.session_token

If instead you want to use the instance role or container role to access S3 then you should leave these settings unset. You can switch from using specific credentials back to the default of using the instance role or container role by removing these settings from the keystore as follows:

bin/elasticsearch-keystore remove s3.client.default.access_key
bin/elasticsearch-keystore remove s3.client.default.secret_key
# a session token is optional so the following command may not be needed
bin/elasticsearch-keystore remove s3.client.default.session_token

All client secure settings of this repository type are reloadable. You can define these settings before the node is started, or call the Nodes reload secure settings API after the settings are defined to apply them to a running node.

After you reload the settings, the internal s3 clients, used to transfer the snapshot contents, will utilize the latest settings from the keystore. Any existing s3 repositories, as well as any newly created ones, will pick up the new values stored in the keystore.

The following list contains the available client settings. Those that must be stored in the keystore are marked as "secure" and are reloadable; the other settings belong in the elasticsearch.yml file.

The s3 repository type supports a number of settings to customize how data is stored in S3. These can be specified when creating the repository. For example:

resp = client.snapshot.create_repository(
    name="my_s3_repository",
    repository={
        "type": "s3",
        "settings": {
            "bucket": "my-bucket",
            "another_setting": "setting-value"
        }
    },
)
print(resp)

const response = await client.snapshot.createRepository({
  name: "my_s3_repository",
  repository: {
    type: "s3",
    settings: {
      bucket: "my-bucket",
      another_setting: "setting-value",
    },
  },
});
console.log(response);

PUT _snapshot/my_s3_repository
{
  "type": "s3",
  "settings": {
    "bucket": "my-bucket",
    "another_setting": "setting-value"
  }
}

The following settings are supported:

In addition to the above settings, you may also specify all non-secure client settings in the repository settings. In this case, the client settings found in the repository settings will be merged with those of the named client used by the repository. Conflicts between client and repository settings are resolved by the repository settings taking precedence over client settings.

For example:

resp = client.snapshot.create_repository(
    name="my_s3_repository",
    repository={
        "type": "s3",
        "settings": {
            "client": "my-client",
            "bucket": "my-bucket",
            "endpoint": "my.s3.endpoint"
        }
    },
)
print(resp)

const response = await client.snapshot.createRepository({
  name: "my_s3_repository",
  repository: {
    type: "s3",
    settings: {
      client: "my-client",
      bucket: "my-bucket",
      endpoint: "my.s3.endpoint",
    },
  },
});
console.log(response);

PUT _snapshot/my_s3_repository
{
  "type": "s3",
  "settings": {
    "client": "my-client",
    "bucket": "my-bucket",
    "endpoint": "my.s3.endpoint"
  }
}

This sets up a repository that uses all client settings from the client my_client_name except for the endpoint that is overridden to my.s3.endpoint by the repository settings. `

Amazon S3 supports a variety of storage classes, each of which offers different operational characteristics. For instance, some classes cost less per byte stored per month, but cost more per request, and other classes may vary in terms of their availability guarantees.

You may specify the storage class that Elasticsearch uses to store data objects with the storage_class repository setting.

Changing the storage_class setting on an existing repository only affects the storage class for newly created objects, resulting in a mixed usage of storage classes.

You may use an S3 Lifecycle Policy to adjust the storage class of existing objects in your repository, but you must not transition objects to an unsupported class such as the Glacier classes, and you must not expire objects. If you use a Glacier storage class, or another unsupported storage class, or object expiry, then you may permanently lose access to your repository contents.

You may use the intelligent_tiering storage class to automatically manage the class of objects, but you must not enable the optional Archive Access or Deep Archive Access tiers. If you use these tiers then you may permanently lose access to your repository contents.

For more information about S3 storage classes, see AWS Storage Classes Guide.

In order to restrict the Elasticsearch snapshot process to the minimum required resources, we recommend using Amazon IAM in conjunction with pre-existing S3 buckets. Here is an example policy which will allow the snapshot access to an S3 bucket named "snaps.example.com". This may be configured through the AWS IAM console, by creating a Custom Policy, and using a Policy Document similar to this (changing snaps.example.com to your bucket name).

{
  "Statement": [
    {
      "Action": [
        "s3:ListBucket",
        "s3:GetBucketLocation",
        "s3:ListBucketMultipartUploads",
        "s3:ListBucketVersions"
      ],
      "Effect": "Allow",
      "Resource": [
        "arn:aws:s3:::snaps.example.com"
      ]
    },
    {
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:AbortMultipartUpload",
        "s3:ListMultipartUploadParts"
      ],
      "Effect": "Allow",
      "Resource": [
        "arn:aws:s3:::snaps.example.com/*"
      ]
    }
  ],
  "Version": "2012-10-17"
}

You may further restrict the permissions by specifying a prefix within the bucket, in this example, named "foo".

{
  "Statement": [
    {
      "Action": [
        "s3:ListBucket",
        "s3:GetBucketLocation",
        "s3:ListBucketMultipartUploads",
        "s3:ListBucketVersions"
      ],
      "Condition": {
        "StringLike": {
          "s3:prefix": [
            "foo/*"
          ]
        }
      },
      "Effect": "Allow",
      "Resource": [
        "arn:aws:s3:::snaps.example.com"
      ]
    },
    {
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:AbortMultipartUpload",
        "s3:ListMultipartUploadParts"
      ],
      "Effect": "Allow",
      "Resource": [
        "arn:aws:s3:::snaps.example.com/foo/*"
      ]
    }
  ],
  "Version": "2012-10-17"
}

The bucket needs to exist to register a repository for snapshots. If you did not create the bucket then the repository registration will fail.

If you want to use Kubernetes service accounts for authentication, you need to add a symlink to the $AWS_WEB_IDENTITY_TOKEN_FILE environment variable (which should be automatically set by a Kubernetes pod) in the S3 repository config directory, so the repository can have the read access for the service account (a repository can’t read any files outside its config directory). For example:

mkdir -p "${ES_PATH_CONF}/repository-s3"
ln -s $AWS_WEB_IDENTITY_TOKEN_FILE "${ES_PATH_CONF}/repository-s3/aws-web-identity-token-file"

If the symlink exists, it will be used by default by all S3 repositories that don’t have explicit client credentials.

Elasticsearch uses S3’s multi-part upload process to upload larger blobs to the repository. The multi-part upload process works by dividing each blob into smaller parts, uploading each part independently, and then completing the upload in a separate step. This reduces the amount of data that Elasticsearch must re-send if an upload fails: Elasticsearch only needs to re-send the part that failed rather than starting from the beginning of the whole blob. The storage for each part is charged independently starting from the time at which the part was uploaded.

If a multi-part upload cannot be completed then it must be aborted in order to delete any parts that were successfully uploaded, preventing further storage charges from accumulating. Elasticsearch will automatically abort a multi-part upload on failure, but sometimes the abort request itself fails. For example, if the repository becomes inaccessible or the instance on which Elasticsearch is running is terminated abruptly then Elasticsearch cannot complete or abort any ongoing uploads.

You must make sure that failed uploads are eventually aborted to avoid unnecessary storage costs. You can use the List multipart uploads API to list the ongoing uploads and look for any which are unusually long-running, or you can configure a bucket lifecycle policy to automatically abort incomplete uploads once they reach a certain age.

AWS instances resolve S3 endpoints to a public IP. If the Elasticsearch instances reside in a private subnet in an AWS VPC then all traffic to S3 will go through the VPC’s NAT instance. If your VPC’s NAT instance is a smaller instance size (e.g. a t2.micro) or is handling a high volume of network traffic your bandwidth to S3 may be limited by that NAT instance’s networking bandwidth limitations. Instead we recommend creating a VPC endpoint that enables connecting to S3 in instances that reside in a private subnet in an AWS VPC. This will eliminate any limitations imposed by the network bandwidth of your VPC’s NAT instance.

Instances residing in a public subnet in an AWS VPC will connect to S3 via the VPC’s internet gateway and not be bandwidth limited by the VPC’s NAT instance.

There are a number of storage systems that provide an S3-compatible API, and the s3 repository type allows you to use these systems in place of AWS S3. To do so, you should set the s3.client.CLIENT_NAME.endpoint setting to the system’s endpoint. This setting accepts IP addresses and hostnames and may include a port. For example, the endpoint may be 172.17.0.2 or 172.17.0.2:9000.

By default Elasticsearch communicates with your storage system using HTTPS, and validates the repository’s certificate chain using the JVM-wide truststore. Ensure that the JVM-wide truststore includes an entry for your repository. If you wish to use unsecured HTTP communication instead of HTTPS, set s3.client.CLIENT_NAME.protocol to http.

MinIO is an example of a storage system that provides an S3-compatible API. The s3 repository type allows Elasticsearch to work with MinIO-backed repositories as well as repositories stored on AWS S3. Other S3-compatible storage systems may also work with Elasticsearch, but these are not covered by the Elasticsearch test suite.

There are many systems, including some from very well-known storage vendors, which claim to offer an S3-compatible API despite failing to emulate S3’s behaviour in full. If you are using such a system for your snapshots, consider using a shared filesystem repository based on a standardized protocol such as NFS to access your storage system instead. The s3 repository type requires full compatibility with S3. In particular it must support the same set of API endpoints, with the same parameters, return the same errors in case of failures, and offer consistency and performance at least as good as S3 even when accessed concurrently by multiple nodes. You will need to work with the supplier of your storage system to address any incompatibilities you encounter. Please do not report Elasticsearch issues involving storage systems which claim to be S3-compatible unless you can demonstrate that the same issue exists when using a genuine AWS S3 repository.

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 with AWS S3 and therefore unsuitable for use as a snapshot repository. However, these checks do not guarantee full compatibility.

Most storage systems can be configured to log the details of their interaction with Elasticsearch. If you are investigating a suspected incompatibility with AWS S3, it is usually simplest to collect these logs and provide them to the supplier of your storage system for further analysis. If the incompatibility is not clear from the logs emitted by the storage system, configure Elasticsearch to log every request it makes to the S3 API by setting the logging level of the com.amazonaws.request logger to DEBUG.

To prevent leaking sensitive information such as credentials and keys in logs, Elasticsearch rejects configuring this logger at high verbosity unless insecure network trace logging is enabled. To do so, you must explicitly enable it on each node by setting the system property es.insecure_network_trace_enabled to true.

Once enabled, you can configure the com.amazonaws.request logger:

resp = client.cluster.put_settings(
    persistent={
        "logger.com.amazonaws.request": "DEBUG"
    },
)
print(resp)

response = client.cluster.put_settings(
  body: {
    persistent: {
      'logger.com.amazonaws.request' => 'DEBUG'
    }
  }
)
puts response

const response = await client.cluster.putSettings({
  persistent: {
    "logger.com.amazonaws.request": "DEBUG",
  },
});
console.log(response);

PUT /_cluster/settings
{
  "persistent": {
    "logger.com.amazonaws.request": "DEBUG"
  }
}

Collect the Elasticsearch logs covering the time period of the failed analysis from all nodes in your cluster and share them with the supplier of your storage system along with the analysis response so they can use them to determine the problem. See the AWS Java SDK documentation for further information, including details about other loggers that can be used to obtain even more verbose logs. When you have finished collecting the logs needed by your supplier, set the logger settings back to null to return to the default logging configuration and disable insecure network trace logging again. See Logger and Cluster update settings for more information.

The linearizable register implementation for S3 repositories is based on the strongly consistent semantics of the multipart upload API. Elasticsearch first creates a multipart upload to indicate its intention to perform a linearizable register operation. Elasticsearch then lists and cancels all other multipart uploads for the same register. Elasticsearch then attempts to complete the upload. If the upload completes successfully then the compare-and-exchange operation was atomic.