S3 存储库

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

唯一强制设置是存储桶名称

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

您用于连接到 S3 的客户端有许多可用设置。这些设置的形式为 s3.client.CLIENT_NAME.SETTING_NAME。默认情况下，s3 存储库使用名为 default 的客户端，但可以使用 存储库设置 client 修改此设置。例如

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

大多数客户端设置可以添加到 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 中的存储方式。这些设置可以在创建存储库时指定。例如

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

支持以下设置

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

例如

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

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

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

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

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

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

您可以使用 intellligent_tiering 存储类自动管理对象的类，但您不得启用可选的 Archive Access 或 Deep Archive Access 层。如果您使用这些层，则可能会永久失去对存储库内容的访问权限。

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

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

如果您想使用 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 存储库都会使用它。

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，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 的存储系统示例。s3 存储库类型允许 Elasticsearch 使用 MinIO 支持的存储库以及存储在 AWS S3 上的存储库。其他 S3 兼容的存储系统也可能与 Elasticsearch 一起使用，但这些系统不在 Elasticsearch 测试套件的覆盖范围内。

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

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

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

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

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

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

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

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