创建和恢复快照

快照并非即时完成。它们需要时间来完成，并且不代表集群的完美时间点视图。在快照进行期间，您仍然可以索引文档并向集群发送其他请求，但新文档和对现有文档的更新通常不包含在快照中。快照包含 OpenSearch 启动快照时存在的主分片。根据您的快照线程池大小，不同的分片可能在略微不同的时间包含在快照中。

OpenSearch 快照是增量的，这意味着它们只存储自上次成功快照以来已更改的数据。频繁快照和不频繁快照之间的磁盘使用差异通常很小。

换句话说，每周每小时拍摄一次快照（总共 168 个快照）可能不会比在周末拍摄一次快照占用更多磁盘空间。此外，您拍摄快照的频率越高，它们完成所需的时间就越短。一些 OpenSearch 用户每 30 分钟拍摄一次快照。

如果您需要删除快照，请务必使用 OpenSearch API，而不是导航到存储位置并清除文件。来自集群的增量快照通常共享大量相同数据；当您使用 API 时，OpenSearch 只会删除没有其他快照正在使用的数据。

注册存储库

在拍摄快照之前，您必须“注册”快照存储库。快照存储库只是一个存储位置：共享文件系统、Amazon 简单存储服务 (Amazon S3)、Hadoop 分布式文件系统 (HDFS) 或 Azure 存储。

共享文件系统

1. 要使用共享文件系统作为快照存储库，请将其添加到 opensearch.yml

   path.repo: ["/mnt/snapshots"]
   

   在 RPM 和 Debian 安装中，您可以挂载文件系统。如果您使用 Docker 安装，请在启动集群之前将文件系统添加到 docker-compose.yml 中的每个节点。

   volumes:
     - /Users/jdoe/snapshots:/mnt/snapshots
   

2. 然后使用 REST API 注册存储库

   PUT /_snapshot/my-fs-repository
   {
     "type": "fs",
     "settings": {
       "location": "/mnt/snapshots"
     }
   }
   

您很可能不需要指定除 location 之外的任何参数。有关允许的请求参数，请参阅 注册或更新快照存储库 API。

Amazon S3

1. 要使用 Amazon S3 桶作为快照存储库，请在所有节点上安装 repository-s3 插件

   sudo ./bin/opensearch-plugin install repository-s3
   

   如果您使用 Docker 安装，请参阅 使用插件。您的 Dockerfile 应如下所示

   FROM opensearchproject/opensearch:3.1.0
   
   ENV AWS_ACCESS_KEY_ID <access-key>
   ENV AWS_SECRET_ACCESS_KEY <secret-key>
   
   # Optional
   ENV AWS_SESSION_TOKEN <optional-session-token>
   
   RUN /usr/share/opensearch/bin/opensearch-plugin install --batch repository-s3
   RUN /usr/share/opensearch/bin/opensearch-keystore create
   
   RUN echo $AWS_ACCESS_KEY_ID | /usr/share/opensearch/bin/opensearch-keystore add --stdin s3.client.default.access_key
   RUN echo $AWS_SECRET_ACCESS_KEY | /usr/share/opensearch/bin/opensearch-keystore add --stdin s3.client.default.secret_key
   
   # Optional
   RUN echo $AWS_SESSION_TOKEN | /usr/share/opensearch/bin/opensearch-keystore add --stdin s3.client.default.session_token
   

   Docker 集群启动后，跳到步骤 7。

   如果您使用 AWS IAM 实例配置文件以允许 AWS EC2 实例上的 OpenSearch 节点在授予 AWS S3 桶访问权限时继承策略角色，请跳到步骤 8。

2. 将您的 AWS 访问密钥和 secret 密钥添加到 OpenSearch 密钥库

   sudo ./bin/opensearch-keystore add s3.client.default.access_key
   sudo ./bin/opensearch-keystore add s3.client.default.secret_key
   

3. (可选) 如果您使用自定义 S3 端点（例如 MinIO），请禁用 Amazon EC2 元数据连接

   export AWS_EC2_METADATA_DISABLED=true
   

   如果您使用 Helm 安装 OpenSearch，请更新您的 values 文件中的以下设置

   extraEnvs:
     - name: AWS_EC2_METADATA_DISABLED
       value: "true"
   

4. (可选) 如果您使用临时凭据，请添加您的会话令牌

   sudo ./bin/opensearch-keystore add s3.client.default.session_token
   

5. (可选) 如果您通过代理连接到互联网，请添加这些凭据

   sudo ./bin/opensearch-keystore add s3.client.default.proxy.username
   sudo ./bin/opensearch-keystore add s3.client.default.proxy.password
   

6. (可选) 将其他设置添加到 opensearch.yml

   s3.client.default.endpoint: s3.amazonaws.com # S3 has alternate endpoints, but you probably don't need to change this value.
   s3.client.default.max_retries: 3 # number of retries if a request fails
   s3.client.default.path_style_access: false # whether to use the deprecated path-style bucket URLs.
   # You probably don't need to change this value, but for more information, see https://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html#path-style-access.
   s3.client.default.protocol: https # http or https
   s3.client.default.proxy.host: my-proxy-host # the hostname for your proxy server
   s3.client.default.proxy.port: 8080 # port for your proxy server
   s3.client.default.read_timeout: 50s # the S3 connection timeout
   s3.client.default.use_throttle_retries: true # whether the client should wait a progressively longer amount of time (exponential backoff) between each successive retry
   s3.client.default.region: us-east-2 # AWS region to use. For non-AWS S3 storage, this value is required but has no effect.
   

7. (可选) 如果您不想使用 AWS 访问密钥和 secret 密钥，可以将 S3 插件配置为使用 AWS Identity and Access Management (IAM) 角色用于服务账户

   sudo ./bin/opensearch-keystore add s3.client.default.role_arn
   sudo ./bin/opensearch-keystore add s3.client.default.role_session_name
   

   如果您不想配置 AWS 访问密钥和 secret 密钥，请修改以下 opensearch.yml 设置。确保 repository-s3 插件可以访问该文件

   s3.client.default.identity_token_file: /usr/share/opensearch/plugins/repository-s3/token
   

   如果复制不可行，您可以在 ${OPENSEARCH_PATH_CONFIG} 文件夹中为 web identity token 文件创建符号链接

   ln -s $AWS_WEB_IDENTITY_TOKEN_FILE "${OPENSEARCH_PATH_CONFIG}/aws-web-identity-token-file"
   

   您可以通过指定相对于 ${OPENSEARCH_PATH_CONFIG} 解析的相对路径，在以下 opensearch.yml 设置中引用 web identity token 文件

   s3.client.default.identity_token_file: aws-web-identity-token-file
   

   IAM 角色至少需要上述设置之一。其他设置将从环境变量中获取（如果可用）：AWS_ROLE_ARN、AWS_WEB_IDENTITY_TOKEN_FILE、AWS_ROLE_SESSION_NAME。

8. 如果您更改了 opensearch.yml，则必须重启集群中的每个节点。否则，您只需重新加载安全的集群设置即可

   POST /_nodes/reload_secure_settings
   

9. 如果您还没有 S3 桶，请创建一个。要拍摄快照，您需要访问该桶的权限。以下 IAM 策略是这些权限的一个示例

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

10. 使用 REST API 注册存储库

    PUT /_snapshot/my-s3-repository
    {
      "type": "s3",
      "settings": {
        "bucket": "my-s3-bucket",
        "base_path": "my/snapshot/directory"
      }
    }
    

您很可能不需要指定除 bucket 和 base_path 之外的任何参数。有关允许的请求参数，请参阅 注册或更新快照存储库 API。

使用 Helm 注册 Microsoft Azure 存储账户

请按照以下步骤为使用 Helm 部署的 OpenSearch 集群注册由 Azure 存储账户支持的快照存储库。

1. 创建 Azure 存储账户。然后在存储账户中创建一个容器。更多信息，请参阅 Azure 存储简介。

2. 使用 bash 脚本创建 OpenSearch 密钥库文件。要创建 bash 脚本，请将以下示例内容复制到名为 create-keystore.sh 的文件中

   #!/bin/bash
   
   /usr/share/opensearch/bin/opensearch-keystore create
   echo $AZURE_SNAPSHOT_STORAGE_ACCOUNT | /usr/share/opensearch/bin/opensearch-keystore add --stdin azure.client.default.account
   echo $AZURE_SNAPSHOT_STORAGE_ACCOUNT_KEY | /usr/share/opensearch/bin/opensearch-keystore add --stdin azure.client.default.key
   cp /usr/share/opensearch/config/opensearch.keystore /tmp/keystore/opensearch.keystore
   

3. 创建 Docker 文件。此文件包含您的密钥库、OpenSearch 实例和 Azure 存储库的详细信息。要创建此文件，请复制以下示例并将其保存为 Dockerfile

   FROM opensearchproject/opensearch:3.1.0
   
   RUN /usr/share/opensearch/bin/opensearch-plugin install --batch repository-azure
   COPY --chmod=0775 create-keystore.sh create-keystore.sh
   

4. 使用以下 docker build 命令从您的 Dockerfile 构建 OpenSearch 镜像

   docker build -t opensearch-custom:3.1.0 -f Dockerfile .
   

5. 使用以下清单和命令创建包含 Azure 存储账户密钥的 Kubernetes secret

   apiVersion: v1
   kind: Secret
   metadata:
     name: opensearch
   data:
     azure-snapshot-storage-account-key: ### Insert base64 encoded key
   

6. 使用 Helm 部署 OpenSearch，并添加以下额外值。在 AZURE_SNAPSHOT_STORAGE_ACCOUNT 环境变量中指定存储账户的值

   extraInitContainers:
   - name: keystore-generator
     image: opensearch-custom:3.1.0
     command: ["/bin/bash", "-c"]
     args: ["bash create-keystore.sh"]
     env:
     - name: AZURE_SNAPSHOT_STORAGE_ACCOUNT
       value: ### Insert storage account name
     - name: AZURE_SNAPSHOT_STORAGE_ACCOUNT_KEY
       valueFrom:
         secretKeyRef:
           name: opensearch
           key: azure-snapshot-storage-account-key
     volumeMounts:
     - name: keystore
       mountPath: /tmp/keystore
   
   extraVolumeMounts:
   - name: keystore
     mountPath: /usr/share/opensearch/config/opensearch.keystore
     subPath: opensearch.keystore
     
   extraVolumes:
   - name: keystore
     emptyDir: {}
   
   image:
     repository: "opensearch-custom"
     tag: 3.1.0
   

7. 使用快照 API 注册存储库。将 snapshot_container 替换为你在步骤 1 中指定的名称，如以下命令所示

   PUT /_snapshot/my-azure-snapshot
   {
     "type": "azure",
     "settings": {
       "client": "default",
       "container": "snapshot_container"
     }
   }
   

设置 Microsoft Azure Blob 存储

要将 Azure Blob 存储用作快照存储库，请遵循以下步骤

1. 使用以下命令在所有节点上安装 repository-azure 插件

   ./bin/opensearch-plugin install repository-azure
   

2. 安装 repository-azure 插件后，在初始化节点之前定义你的 Azure Blob 存储设置。首先使用以下安全设置定义你的 Azure 存储账户名称

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

选择以下选项之一来设置你的 Azure Blob 存储身份验证凭据。

使用 Azure 存储账户密钥

使用以下设置指定你的 Azure 存储账户密钥

./bin/opensearch-keystore add azure.client.default.key

共享访问签名

使用共享访问签名 (SAS) 访问 Azure 时，请使用以下设置

./bin/opensearch-keystore add azure.client.default.sas_token      

Azure 令牌凭据

从 OpenSearch 2.15 开始，你可以选择在 opensearch.yml 中配置令牌凭据身份验证流。此方法与需要 SAS 或账户密钥的连接字符串身份验证不同。

如果选择使用令牌凭据身份验证，则需要选择一种令牌凭据类型。尽管 Azure 提供了多种令牌凭据类型，但截至 OpenSearch 2.15 版，仅支持托管标识。

要使用托管标识，请使用 managed 或 managed_identity 值将你的令牌凭据类型添加到 opensearch.yml 中。这表示正在使用托管标识执行令牌凭据身份验证

azure.client.default.token_credential_type: "managed_identity"

使用 Azure 令牌凭据时请注意以下事项

• 默认情况下，opensearch.yml 中禁用令牌凭据支持。
• 当配置了多个选项时，令牌凭据优先于 Azure 存储账户密钥或 SAS。

拍摄快照

创建快照时，你需要指定两部分信息

• 你的快照存储库名称
• 快照的名称

以下快照包括所有索引和集群状态

PUT /_snapshot/my-repository/1

你还可以添加请求体以包含或排除某些索引或指定其他设置

PUT /_snapshot/my-repository/2
{
  "indices": "opensearch-dashboards*,my-index*,-my-index-2016",
  "ignore_unavailable": true,
  "include_global_state": false,
  "partial": false
}

有关更多信息，请参阅创建快照 API。

如果你在拍摄快照后立即请求快照，可能会看到如下内容

GET /_snapshot/my-repository/2
{
  "snapshots": [{
    "snapshot": "2",
    "version": "6.5.4",
    "indices": [
      "opensearch_dashboards_sample_data_ecommerce",
      "my-index",
      "opensearch_dashboards_sample_data_logs",
      "opensearch_dashboards_sample_data_flights"
    ],
    "include_global_state": true,
    "state": "IN_PROGRESS",
    ...
  }]
}

有关更多信息，请参阅获取快照 API。

请注意，快照仍在进行中。如果你想等待快照完成后再继续，请在请求中添加 wait_for_completion 参数。快照可能需要一段时间才能完成，因此请考虑此选项是否适合你的用例

PUT _snapshot/my-repository/3?wait_for_completion=true

快照具有以下状态

如果当前有快照正在进行中，则无法拍摄快照。要检查状态

GET /_snapshot/_status

恢复快照

恢复快照的第一步是检索现有快照。要查看所有快照存储库

GET /_snapshot/_all

要查看存储库中的所有快照

GET /_snapshot/my-repository/_all

然后恢复快照

POST /_snapshot/my-repository/2/_restore

就像拍摄快照一样，你可以添加请求体以包含或排除某些索引或指定其他设置

POST /_snapshot/my-repository/2/_restore
{
  "indices": "opensearch-dashboards*,my-index*",
  "ignore_unavailable": true,
  "include_global_state": false,
  "include_aliases": false,
  "partial": false,
  "rename_pattern": "opensearch-dashboards(.+)",
  "rename_replacement": "restored-opensearch-dashboards$1",
  "index_settings": {
    "index.blocks.read_only": false
  },
  "ignore_index_settings": [
    "index.refresh_interval"
  ]
}

有关更多信息，请参阅恢复快照 API。

冲突与兼容性

避免恢复索引时出现索引命名冲突的一种方法是使用 rename_pattern 和 rename_replacement 选项。然后，如果需要，可以使用 _reindex API 将两者结合起来。但是，在从快照恢复索引之前删除导致冲突的索引可能会更简单。

类似地，为了避免恢复带有别名的索引时出现别名命名冲突，可以使用 rename_alias_pattern 和 rename_alias_replacement 选项。

在从快照恢复之前，你可以使用 _close API 关闭现有索引，但快照中的索引必须与现有索引具有相同数量的分片。

我们建议在从快照恢复之前停止对集群的写入请求，这有助于避免以下场景，例如

1. 你删除了一个索引，同时也删除了它的别名。
2. 对现在已删除的别名的写入请求创建了一个与别名同名的新索引。
3. 由于与新索引存在命名冲突，快照中的别名未能恢复。

快照仅向前兼容一个主要版本。由早期 OpenSearch 版本拍摄的快照可以继续由最初拍摄快照的 OpenSearch 版本恢复，即使在版本升级后也是如此。例如，由 OpenSearch 2.11 或更早版本拍摄的快照，即使升级到 2.12 后，也可以继续由 2.11 集群恢复。

如果你有一个从早期 OpenSearch 主要版本拍摄的旧快照，你可以将其恢复到比快照版本新一个主要版本的中间集群，重新索引所有索引，拍摄新快照，并重复此过程直到达到所需的主要版本，但你可能会发现手动将数据索引到新集群中会更容易。

安全注意事项

如果你正在使用安全插件，快照有一些额外的限制

• 要执行快照和恢复操作，用户必须具有内置的 manage_snapshots 角色。
• 你无法恢复包含全局状态或 .opendistro_security 索引的快照。

如果快照包含全局状态，则在执行恢复时必须将其排除。如果你的快照还包含 .opendistro_security 索引，则要么将其排除，要么列出你希望包含的所有其他索引

POST /_snapshot/my-repository/3/_restore
{
  "indices": "-.opendistro_security",
  "include_global_state": false
}

.opendistro_security 索引包含敏感数据，因此我们建议你在拍摄快照时将其排除。如果你确实需要从快照恢复该索引，则必须在请求中包含管理证书

curl -k --cert ./kirk.pem --key ./kirk-key.pem -XPOST 'https://:9200/_snapshot/my-repository/3/_restore?pretty'

我们强烈建议不要使用管理证书恢复 .opendistro_security，因为这样做会改变整个集群的安全状况。有关备份和恢复安全插件配置的建议过程，请参阅注意事项。

索引编解码器注意事项

有关索引编解码器注意事项，请参阅索引编解码器。

相关文章

• 快照 API