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

有关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 一样好的一致性和性能。您需要与您的存储系统供应商合作，以解决遇到的任何不兼容性问题。除非您可以证明在使用真正的 AWS S3 存储库时存在相同的问题，否则请不要报告涉及声称与 S3 兼容的存储系统的 Elasticsearch 问题。

您可以使用存储库分析 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 尝试完成上传。如果上传成功完成，则比较和交换操作是原子的。