注册快照仓库

要启用 Azure 仓库，首先通过指定一个或多个形式的设置来配置 Azure 仓库客户端 azure.client.CLIENT_NAME.SETTING_NAME。默认情况下，azure 仓库使用名为 default 的客户端，但在注册每个仓库时可以指定不同的客户端名称。

唯一必须的 Azure 仓库客户端设置是 account，这是一个在 安全设置 中定义的 Elasticsearch 密钥库。要提供此设置，请在每个节点上使用 elasticsearch-keystore 工具：

bin/elasticsearch-keystore add azure.client.default.account

如果在节点启动后调整此设置，请调用 Nodes reload secure settings API 以重新加载新值。

您可以通过设置它们的 account 值来定义多个客户端。例如，要设置 default 客户端和另一个名为 secondary 的客户端，请在每个节点上运行以下命令：

bin/elasticsearch-keystore add azure.client.default.account
bin/elasticsearch-keystore add azure.client.secondary.account

The key 和 sas_token 设置也是安全设置，可以使用以下命令进行设置：

bin/elasticsearch-keystore add azure.client.default.key
bin/elasticsearch-keystore add azure.client.secondary.sas_token

其他 Azure 仓库客户端设置必须在节点启动前在 elasticsearch.yml 中设置。例如：

azure.client.default.timeout: 10s
azure.client.default.max_retries: 7
azure.client.default.endpoint_suffix: core.chinacloudapi.cn
azure.client.secondary.timeout: 30s

在这个例子中，使用default客户端的仓库每次尝试的客户端超时时间为10s，在失败前重试7次，并且端点后缀为core.chinacloudapi.cn。使用secondary客户端的仓库每次尝试的超时时间为30s，但将使用默认端点，并在默认重试次数后失败。

一旦正确配置了Azure存储库客户端，请按如下方式注册Azure存储库，使用client提供客户端名称，并参考存储库设置：

PUT _snapshot/my_backup
{
  "type": "azure",
  "settings": {
    "client": "secondary"
  }
}

如果你使用的是默认客户端，你可以省略客户端仓库设置：

PUT _snapshot/my_backup
{
  "type": "azure"
}

以下列表描述了可用的客户端设置。那些必须存储在密钥库中的设置标记为（安全， 可重新加载）；其他设置必须存储在elasticsearch.yml文件中。默认的CLIENT_NAME是default，但您可以配置一个具有不同名称的客户端，并在注册存储库时通过名称指定该客户端。

Azure 仓库支持以下设置，可以在注册 Azure 仓库时按如下方式指定：

PUT _snapshot/my_backup
{
  "type": "azure",
  "settings": {
    "client": "secondary",
    "container": "my_container",
    "base_path": "snapshots_prefix"
  }
}

根据 容器命名指南，容器名称必须是有效的DNS名称，并符合以下命名规则：

用于Azure存储库的可线性化寄存器实现基于Azure对强一致性租约的支持。每个租约在任何时候只能由一个节点持有。节点在进行受保护的blob的读或写操作时会出示其租约。如果租约无效或已过期，受租约保护的操作将失败。为了对寄存器执行比较并交换操作，Elasticsearch首先获取blob的租约，然后在租约下读取blob内容，最后在同一租约下上传更新的blob。此过程确保读和写操作以原子方式发生。

此仓库类型使用Google Cloud Java Client for Storage 连接到存储服务。如果您是第一次使用 Google Cloud Storage，您 必须连接到Google Cloud Platform Console 并创建一个新项目。在您的项目创建完成后，您必须为您的项目启用 Cloud Storage服务。

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "service-account-for-your-repository@your-project-id.iam.gserviceaccount.com",
  "client_id": "...",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/your-bucket@your-project-id.iam.gserviceaccount.com"
}

PUT _snapshot/my_gcs_repository
{
  "type": "gcs",
  "settings": {
    "bucket": "my_bucket",
    "client": "my_alternate_client"
  }
}

用于连接到 Google Cloud Storage 的客户端有许多可用的设置。客户端设置名称的形式为 gcs.client.CLIENT_NAME.SETTING_NAME，并在 elasticsearch.yml 中指定。默认客户端名称由 gcs 仓库查找，称为 default，但可以通过仓库设置 client 进行自定义。

例如：

PUT _snapshot/my_gcs_repository
{
  "type": "gcs",
  "settings": {
    "bucket": "my_bucket",
    "client": "my_alternate_client"
  }
}

某些设置是敏感的，必须存储在 Elasticsearch 密钥库中。服务帐户文件就是这种情况：

bin/elasticsearch-keystore add-file gcs.client.default.credentials_file /path/service-account.json

以下是可用的客户端设置。那些必须存储在密钥库中的设置被标记为安全。

The gcs 存储库类型支持许多设置，以自定义数据在 Google Cloud Storage 中的存储方式。

这些可以在创建仓库时指定。例如：

PUT _snapshot/my_gcs_repository
{
  "type": "gcs",
  "settings": {
    "bucket": "my_other_bucket",
    "base_path": "dev"
  }
}

支持以下设置：

GCS 仓库的可线性化寄存器实现基于 GCS 对 put-blob 操作的强一致性前提条件的支持。为了在寄存器上执行比较并交换操作，Elasticsearch 会检索寄存器 blob 及其当前代数，然后使用观察到的代数作为其前提条件上传更新的 blob。该前提条件确保代数在此期间没有发生变化。

要注册一个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文件。

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

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

支持以下设置：

get_register_retry_delay

(<<time-units,time value>>) Sets the time to wait before trying again if an attempt to read a
<<repository-s3-linearizable-registers,linearizable register>> fails. Defaults to `5s`.

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

例如：

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

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

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

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

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

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

您可以使用intelligent_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 服务账户 进行身份验证，您需要将一个符号链接到 $AWS_WEB_IDENTITY_TOKEN_FILE 环境变量 （该变量应由 Kubernetes pod 自动设置）到 S3 仓库配置目录中，以便仓库 可以拥有对服务账户的读取权限（仓库无法读取其配置目录之外的任何文件）。 例如：

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 的行为，却声称提供与 S3 兼容的 API。 如果您正在使用这样的系统进行快照，请考虑使用基于标准化协议（如 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 日志记录器：

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

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

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

Elasticsearch 与共享文件系统仓库交互时，使用操作系统中的文件系统抽象。这意味着每个 Elasticsearch 节点都必须能够在仓库路径中执行操作，例如创建、打开和重命名文件，以及创建和列出目录，并且一个节点执行的操作必须能够在操作完成后立即被其他节点看到。

使用验证快照仓库API和仓库分析API检查常见的配置错误。当仓库正确配置时，这些API将成功完成。如果验证仓库或仓库分析API报告了问题，那么您将能够在Elasticsearch外部通过直接在文件系统上执行类似操作来重现此问题。

如果验证仓库或仓库分析API因权限不足而失败，请调整操作系统中仓库的配置，以赋予Elasticsearch适当的访问权限。要直接重现此类问题，请在Elasticsearch运行的相同安全上下文中执行相同的操作。例如，在Linux上，可以使用su命令切换到Elasticsearch运行的用户。

如果验证存储库或存储库分析API因错误而失败，该错误表明在一个节点上的操作在另一个节点上不是立即可见的，那么请调整操作系统中存储库的配置以解决此问题。如果您的存储库无法配置为提供足够强的可见性保证，则它不适合用作Elasticsearch快照存储库。

验证仓库和仓库分析API在访问仓库时，如果操作系统返回任何其他类型的I/O错误，也会失败。如果发生这种情况，请解决操作系统报告的I/O错误的原因。

共享文件系统仓库的可线性化寄存器实现基于文件锁定。为了对寄存器执行比较和交换操作，Elasticsearch首先锁定底层文件，然后在同一锁下写入更新内容。这确保了文件在此期间没有发生变化。