S3 存储库

要注册 S3 存储库，请在创建存储库时将类型指定为 s3。存储库默认使用 ECS IAM 角色 凭据进行身份验证。您也可以使用 Kubernetes 服务帐户 进行身份验证。

唯一必需的设置是存储桶名称

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

您用于连接到 S3 的客户端提供了一些可用的设置。这些设置的格式为 s3.client.CLIENT_NAME.SETTING_NAME。默认情况下，s3 存储库使用名为 default 的客户端，但这可以使用 存储库设置 client 进行修改。例如

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

大多数客户端设置可以添加到 elasticsearch.yml 配置文件中，除了安全设置，您需要将其添加到 Elasticsearch 密钥库中。有关创建和更新 Elasticsearch 密钥库的更多信息，请参阅 安全设置。

例如，如果您想使用特定凭据访问 S3，请运行以下命令将这些凭据添加到密钥库中。

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

如果您想使用实例角色或容器角色访问 S3，则应将这些设置保留为空。您可以通过从密钥库中删除这些设置来从使用特定凭据切换回使用实例角色或容器角色的默认值，如下所示

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

所有 此存储库类型的客户端安全设置都是 可重新加载的。您可以在节点启动之前定义这些设置，或者在定义设置后调用 节点重新加载安全设置 API 以将其应用于正在运行的节点。

重新加载设置后，用于传输快照内容的内部 s3 客户端将使用密钥库中的最新设置。任何现有的 s3 存储库以及任何新创建的存储库都将获取存储在密钥库中的新值。

以下列表包含可用的客户端设置。必须存储在密钥库中的那些被标记为“安全”并且是 可重新加载的；其他设置属于 elasticsearch.yml 文件。

S3 存储库类型支持多种设置，用于自定义数据在 S3 中的存储方式。这些设置可以在创建存储库时指定。例如

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

支持以下设置

除了上述设置之外，您还可以在存储库设置中指定所有非安全客户端设置。在这种情况下，存储库设置中找到的客户端设置将与存储库使用的命名客户端的客户端设置合并。客户端设置和存储库设置之间的冲突将通过存储库设置优先于客户端设置来解决。

例如

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

这将设置一个存储库，该存储库使用来自客户端 my_client_name 的所有客户端设置，除了被存储库设置覆盖为 my.s3.endpoint 的 endpoint。`

Amazon S3 支持多种存储类别，每种类别都提供不同的操作特性。例如，某些类别每月每字节存储的成本更低，但每次请求的成本更高，而其他类别在可用性保证方面可能有所不同。

您可以使用 storage_class 存储库设置指定 Elasticsearch 用于存储数据对象的存储类别。

更改现有存储库的 storage_class 设置只会影响新创建对象的存储类别，从而导致混合使用存储类别。

您可以使用 S3 生命周期策略来调整存储库中现有对象的存储类别，但您不能将对象转换为不支持的类别，例如 Glacier 类别，也不能使对象过期。如果您使用 Glacier 存储类别或其他不支持的存储类别或对象过期，则您可能会永久丢失对存储库内容的访问权限。

您可以使用 intellligent_tiering 存储类别来自动管理对象的类别，但您不能启用可选的归档访问或深度归档访问层。如果您使用这些层，则您可能会永久丢失对存储库内容的访问权限。

有关 S3 存储类别的更多信息，请参阅 AWS 存储类别指南。

为了将 Elasticsearch 快照过程限制在所需的最小资源，我们建议将 Amazon IAM 与预先存在的 S3 存储桶结合使用。以下是一个示例策略，它将允许快照访问名为“snaps.example.com”的 S3 存储桶。这可以通过 AWS IAM 控制台进行配置，方法是创建自定义策略，并使用类似于此的策略文档（将 snaps.example.com 更改为您的存储桶名称）。

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

您可以通过在存储桶中指定一个前缀来进一步限制权限，在本例中，名为“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"
}

存储桶需要存在才能注册用于快照的存储库。如果您没有创建存储桶，则存储库注册将失败。

使用 IAM 角色对 Kubernetes 服务帐户进行身份验证edit

如果您想使用 Kubernetes 服务帐户 进行身份验证，您需要在 S3 存储库配置目录中添加一个指向 $AWS_WEB_IDENTITY_TOKEN_FILE 环境变量的符号链接（该变量应由 Kubernetes pod 自动设置），以便存储库可以对服务帐户具有读取权限（存储库无法读取其配置目录之外的任何文件）。例如

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

如果符号链接存在，则所有没有显式 client 凭据的 S3 存储库默认情况下都会使用它。

Elasticsearch 使用 S3 的分块上传流程将较大的 Blob 上传到存储库。分块上传流程通过将每个 Blob 分割成更小的部分，独立上传每个部分，然后在单独的步骤中完成上传来实现。这减少了 Elasticsearch 在上传失败时必须重新发送的数据量：Elasticsearch 只需要重新发送失败的部分，而无需从整个 Blob 的开头开始。每个部分的存储费用从上传该部分的时间开始独立计算。

如果无法完成分块上传，则必须中止它以删除已成功上传的任何部分，防止进一步的存储费用累积。Elasticsearch 会在失败时自动中止分块上传，但有时中止请求本身也会失败。例如，如果存储库变得不可访问或运行 Elasticsearch 的实例突然终止，则 Elasticsearch 无法完成或中止任何正在进行的上传。

您必须确保最终中止失败的上传，以避免不必要的存储成本。您可以使用 列出分块上传 API 列出正在进行的上传并查找任何运行时间过长的上传，或者您可以 配置存储桶生命周期策略 以在不完整的上传达到一定年龄时自动中止它们。

AWS 实例将 S3 端点解析为公网 IP。如果 Elasticsearch 实例驻留在 AWS VPC 中的私有子网中，则所有到 S3 的流量都将通过 VPC 的 NAT 实例。如果您的 VPC 的 NAT 实例是较小的实例大小（例如 t2.micro）或正在处理大量网络流量，则您到 S3 的带宽可能会受到该 NAT 实例的网络带宽限制的限制。相反，我们建议创建一个 VPC 端点，它允许连接到驻留在 AWS VPC 中的私有子网中的实例中的 S3。这将消除 VPC 的 NAT 实例的网络带宽对您施加的任何限制。

驻留在 AWS VPC 中的公有子网中的实例将通过 VPC 的互联网网关连接到 S3，并且不会受到 VPC 的 NAT 实例的带宽限制。

有许多存储系统提供与 S3 兼容的 API，并且 repository-s3 类型允许您使用这些系统来代替 AWS S3。为此，您应该将 s3.client.CLIENT_NAME.endpoint 设置设置为系统的端点。此设置接受 IP 地址和主机名，并且可能包含端口。例如，端点可能是 172.17.0.2 或 172.17.0.2:9000。

默认情况下，Elasticsearch 使用 HTTPS 与您的存储系统通信，并使用 JVM 范围的信任库验证存储库的证书链。确保 JVM 范围的信任库包含您存储库的条目。如果您希望使用不安全的 HTTP 通信而不是 HTTPS，请将 s3.client.CLIENT_NAME.protocol 设置为 http。

MinIO 是提供与 S3 兼容的 API 的存储系统的示例。 repository-s3 类型允许 Elasticsearch 使用 MinIO 支持的存储库以及存储在 AWS S3 上的存储库。其他与 S3 兼容的存储系统也可能与 Elasticsearch 一起使用，但这些系统不在 Elasticsearch 测试套件的范围内。

有许多系统，包括一些来自知名存储供应商的系统，声称提供与 S3 兼容的 API，尽管它们未能完全模拟 S3 的行为。如果您正在使用这样的系统进行快照，请考虑使用基于标准协议（如 NFS）的 共享文件系统存储库 来访问您的存储系统。 repository-s3 类型需要与 S3 完全兼容。特别是，它必须支持相同的 API 端点集，具有相同的参数，在发生故障时返回相同的错误，并且即使在多个节点同时访问时，也必须提供至少与 S3 一样好的一致性和性能。您需要与您的存储系统供应商合作以解决您遇到的任何不兼容问题。如果您无法证明在使用真正的 AWS S3 存储库时也存在相同的问题，请不要报告涉及声称与 S3 兼容的存储系统的 Elasticsearch 问题。

您可以使用 存储库分析 API 对您的存储系统的适用性进行一些基本检查。如果此 API 未成功完成或指示性能不佳，则您的存储系统与 AWS S3 不完全兼容，因此不适合用作快照存储库。但是，这些检查不能保证完全兼容。

大多数存储系统都可以配置为记录它们与 Elasticsearch 交互的详细信息。如果您正在调查与 AWS S3 的疑似不兼容问题，通常最简单的方法是收集这些日志并将其提供给您的存储系统供应商以进行进一步分析。如果存储系统发出的日志中没有明确的不兼容问题，请配置 Elasticsearch 通过 设置 com.amazonaws.request 记录器的日志级别 为 DEBUG 来记录它对 S3 API 的每个请求。

为了防止在日志中泄露敏感信息（如凭据和密钥），Elasticsearch 拒绝以高详细程度配置此记录器，除非 启用了不安全的网络跟踪日志记录。为此，您必须通过将系统属性 es.insecure_network_trace_enabled 设置为 true 来在每个节点上显式启用它。

启用后，您可以配置 com.amazonaws.request 记录器

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

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

收集来自集群中所有节点的涵盖失败分析时间段的 Elasticsearch 日志，并将它们与分析响应一起共享给您的存储系统供应商，以便他们可以使用它们来确定问题。有关更多信息，请参阅 AWS Java SDK 文档，包括有关其他可用于获取更详细日志的记录器的详细信息。完成收集供应商所需的日志后，将记录器设置恢复为 null 以返回到默认日志记录配置，并再次禁用不安全的网络跟踪日志记录。有关更多信息，请参阅 记录器 和 集群更新设置。

S3 存储库的线性化寄存器实现基于分块上传 API 的强一致性语义。Elasticsearch 首先创建一个分块上传，以表明它打算执行线性化寄存器操作。然后，Elasticsearch 列出并取消对同一寄存器的所有其他分块上传。然后，Elasticsearch 尝试完成上传。如果上传成功完成，则比较和交换操作是原子的。