每次操作一个 API 调用：Elastic Cloud Hosted 如何让大规模部署管理变得可行

作者：来自 Elastic Omer Kushmaro

Elastic Cloud Hosted 增加了五个针对性的 API，用于升级、分层扩展、用户设置、标签以及快照仓库关联，每一个 API 都用一次专注的调用替代了多步骤的部署计划编辑操作。

使用 Elastic Cloud Hosted 实现强大且现代的搜索体验。立即注册以获得即时访问权限。

五个新的 Elastic Cloud Hosted API 取代了一种令人痛苦的操作模式：先获取完整部署计划，手动编辑拓扑元素，然后重新提交整个配置，只是为了更改一个层级或升级一个版本。升级、扩展、配置、打标签以及共享快照仓库，现在都可以通过单一、针对性的 API 调用完成。相同的校验规则仍然适用，而且所有操作也都可以在 Elastic Cloud Console 中完成。如果你管理的不只是少量部署，那么这套面向集群运维的操作接口正是你一直在等待的能力。

以下是新增内容。

如何通过 API 升级 Elastic Cloud Hosted 部署

升级 API：POST /deployments/{id}/upgrade

在过去，将一个部署中的 Elastic Stack 版本升级到所有资源，需要你构造并提交完整的部署计划更新。现在，你只需一次 API 调用，就可以将一个部署中的所有资源（Elasticsearch、Kibana 以及其他组件）升级到目标 Elastic Stack 版本。

复制代码

curl -X POST https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/upgrade \
  -H "Authorization: ApiKey $EC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_version": "9.4.0"}'

当你需要在大量部署之间快速推送新的 Elastic Stack 版本时，这一点的价值体现得最为明显。

如何在 Elastic Cloud Hosted 中调整 Elasticsearch 分层大小

**扩展 API：**GET / PATCH /deployments/{id}/elasticsearch/{ref_id}/tiers

分层 API 允许你通过一次 PATCH 请求调整任何 Elasticsearch 分层（热层 hot、温层 warm、冷层 cold、冻结层 frozen、主节点 master、协调节点 coordinating 或机器学习 ML）。该请求仅作用于你希望修改的分层范围。

你只需发送一个以分层 ID 为键的请求体。未提及的部分会保持原样，因此你可以在不影响其他分层的情况下，单独修改某一个分层。

复制代码

curl -X PATCH https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/elasticsearch/main/tiers \
  -H "Authorization: ApiKey $EC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hot_content": {
      "memory_size": 4096,
      "zone_count": 2
    },
    "warm": {
      "memory_size": 5120,
      "zone_count": 1
    },
    "master": {
      "memory_size": 1024,
      "zone_count": 3
    }
  }'

有几点需要注意：

有效的分层 ID 包括 hot_content、warm、cold、frozen、master、coordinating 和 ml。无效的键会被拒绝，并返回可用分层列表。
memory_size 和 zone_count 在每个分层中都是可选的。你只需要包含你想要修改的字段，另一个字段会保持不变。
专用主节点的处理是自动的。当你为 master 分层设置 memory_size 和 zone_count 大于 0 时，该接口会自动将 hot_content 分层从"可担任主节点角色"中移除，从而让新的专用主节点接管。当你将 master 的 memory_size 设置为 0 时，hot_content 分层会重新恢复为可担任主节点的角色，无需单独的控制标志。
与完整部署计划 API 使用相同的校验机制。修改后的计划会通过现有的验证器处理，因此会统一执行诸如实例配置与规模匹配错误、分区数量限制以及拓扑规则等检查。

对于那些基于摄取负载自动化分层扩缩容、在维护窗口前重新平衡分区，或随着集群增长将部署升级为专用主节点的团队来说，这一设计将原本需要多步骤的计划编辑操作压缩为一次针对性的请求。

如何在 Elastic Cloud Hosted 中更新 elasticsearch.yml 设置

**用户设置 API：**GET 和 PUT /deployments/{id}/{resource_kind}/{ref_id}/user_settings

运行中的部署中的用户自定义设置（例如 elasticsearch.yml 风格的覆盖配置、Kibana 设置、APM 配置等），现在都有独立的 API 端点。你可以通过一个专注的 JSON 请求直接读取或更新这些设置，并且作用范围仅限于单个资源。

这些端点覆盖 Elasticsearch、Kibana、Elastic APM、App Search、Enterprise Search 以及 Integrations Server。所有资源使用相同的端点结构，只是 {resource_kind} 路径部分不同。

读取某个资源的当前设置：

复制代码

curl https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/elasticsearch/main/user_settings \
  -H "Authorization: ApiKey $EC_API_KEY"

使用一个仅包含你想要设置的键的 JSON 请求体来更新这些设置：

复制代码

curl -X PUT https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/elasticsearch/main/user_settings \
  -H "Authorization: ApiKey $EC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search.allow_expensive_queries": false,
    "indices.recovery.max_bytes_per_sec": "200mb"
  }'

有几点需要注意：

JSON 输入 ，JSON 输出。这是一个 JSON 契约，便于模板化、差异对比，并纳入源代码管理。
现有 YAML 会自动迁移。你当前在 YAML 中配置的任何分层级用户设置，在第一次执行 PUT 时会自动转换为 JSON，因此现有部署无需手动重写或执行一次性迁移步骤。
允许列表与拒绝列表规则依然适用。不被平台允许的设置会被拒绝，并使用与完整部署计划 API 相同的校验机制。
异步执行。该操作会立即被确认，并在后台应用，与本次发布中的其他针对性 API 保持一致。
非破坏性变更。完整的 PUT /deployments/{id} 接口仍然可用；这是一个新增能力，而不是替代方案。

对于那些在发布流程中调整配置、在整个集群范围内批量推送配置变更，或希望将集群覆盖配置作为代码管理的团队来说，这一能力将每个部署的操作压缩为一次针对性的 PUT 请求。

如何在 Elastic Cloud Hosted 中管理部署标签

**标签 API：**GET 和 PUT /deployments/{id}/tags

部署标签用于为部署附加元数据（例如环境、所有者、成本中心、应用程序），以便进行过滤、报表和策略管理。Tags API 提供了 GET 用于获取当前标签，以及 PUT 用于替换标签，两者都通过一次针对性的调用完成。

复制代码

curl -X PUT https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/tags \
  -H "Authorization: ApiKey $EC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": [{"key": "env", "value": "prod"}, {"key": "owner", "value": "search-platform"}]}'

PUT 会替换部署上的所有标签。校验规则限制每个部署最多 64 个标签，键长度不超过 32 个字符，值长度不超过 128 个字符，任何违规都会返回明确的 400 错误。授权机制与部署更新端点保持一致。

如何在 Elastic Cloud Hosted 中跨部署关联快照仓库

**快照仓库 API：**完整 CRUD 接口位于 /deployments/{id}/elasticsearch/{ref_id}/snapshot/repository，同时在 Elastic Cloud 控制台中提供新的工作流

在 Elastic Cloud Hosted（ ECH ）中，一个常见的运维模式是让一个部署访问另一个部署的快照：用于迁移验证、为测试环境填充数据，或在整个集群中选择性恢复某个租户的索引。快照仓库关联功能使你无需将完整快照数据复制到新部署中即可实现这一点。

该能力在源部署的托管快照仓库与目标部署之间建立链接。目标部署可以浏览源部署的快照，并仅恢复其实际需要的部分；在建立链接时不会发生任何数据复制。只要用户对两个部署都拥有管理员权限，跨存储桶的凭据和仓库都会自动完成配置。

此功能专门且仅适用于 Elastic Cloud 托管的快照仓库，其凭据由 Elastic Cloud 统一管理。

你可以通过两种方式管理这些链接：在 Elastic Cloud 控制台中进行点选式操作，用于临时或一次性工作；或者通过 API 进行自动化管理，以支持基础设施即代码（ IaC ）工作流。

从 Elastic Cloud 控制台关联快照仓库

对于一次性恢复演练、测试环境刷新，或任何你不想编写脚本的场景，Elastic Cloud 控制台现在提供了一个引导式流程，用于将源部署的快照仓库关联到目标部署。

打开目标部署，进入快照仓库管理界面，从你有权限访问的部署列表中选择源部署，然后确认即可。控制台会在后台处理凭据和注册流程，无需手动编写 JSON，也无需操作 keystore。

一旦建立链接，同一界面会列出所有已关联的部署：

删除链接同样直接：选择已关联的仓库并取消链接即可。源部署不会受到影响；仅会移除目标端的只读关联链接。

通过 API 管理仓库关联

快照仓库关联操作（创建、列表、删除）同样提供 API 端点，用于自动化和基础设施即代码（ IaC ）工作流。

创建一个链接

复制代码

curl -X POST https://api.elastic-cloud.com/api/v1/deployments/{target_deployment_id}/elasticsearch/{ref_id}/snapshot/repository \
  -H "Authorization: ApiKey $EC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_deployment_id": "<source-deployment-id>"
  }'

该端点是幂等的。在发生部分失败后进行重试时，会从上一次执行的位置继续，因此不会出现"半配置"的链接状态。该操作是异步执行的：你会立即收到确认响应，随后由 Elastic Cloud 控制平面完成后续工作（获取源仓库配置、将凭据注入目标集群的 keystore，并在 Elasticsearch 中注册只读仓库）。只要调用方对两个部署都具备相应权限，链接流程就会继续执行。

列出已关联的快照仓库

复制代码

curl https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/elasticsearch/{ref_id}/snapshot/repository \
  -H "Authorization: ApiKey $EC_API_KEY"

响应中的每个条目都包含一个 repository_name 字段，该字段表示该仓库在 Elasticsearch 中注册的实际名称（例如 _clone_abcd1234）。你不需要从内部 ID 约定中推导它；直接使用响应中的名称即可，并且可以在任何需要引用仓库的 Elasticsearch 快照与恢复 API 中使用它。

移除一个链接

复制代码

curl -X DELETE https://api.elastic-cloud.com/api/v1/deployments/{deployment_id}/elasticsearch/{ref_id}/snapshot/repository/{repository_name} \
  -H "Authorization: ApiKey $EC_API_KEY"

DELETE 直接使用 repository_name（即上方 GET 返回的相同值）。这种设计使 API 保持对称性，并避免在解除链接时还需要通过 ID 去查找源部署。

一个典型的生命周期：

复制代码

POST   .../snapshot/repository            (link target → source)
GET    .../snapshot/repository            (confirm the link, read back repository_name)
DELETE .../snapshot/repository/{name}     (unlink when done)

这在多环境工作流中尤其有用，例如：让一个 staging（测试）部署从 production（生产）快照读取数据、支持按租户划分的集群并进行选择性恢复，或需要针对特定索引执行恢复的多租户恢复流程。

在 Elastic Cloud Hosted 中为各分层选择实例配置

实例配置自定义：Elastic Cloud 控制台 UI

Elastic Cloud Hosted 现在允许你在 Elastic Cloud 控制台中，直接为每个数据分层（hot、warm、cold、frozen）选择对应的实例配置。

通过为不同数据分层选择合适的实例配置，将部署硬件与具体工作负载匹配：

进入部署的概览页面，点击硬件配置中的"编辑"。
在硬件配置弹窗中，为每个数据分层选择最适合其工作负载的实例配置。
检查更改后，点击"更新"。在应用之前，确认对话框会清晰展示所有将要发生的变更。

无论你是需要在 warm 分层上获得更高的存储密度，在 hot 分层上提升面向搜索密集型工作负载的计算能力，还是想在你的区域中切换到更新的机器类型，现在都可以直接在控制台完成这些更改，而不必手动编写 API 请求。如果你的选择与现有硬件配置文件一致，该配置文件会被自动应用；否则，该部署会被标记为 custom，并允许在该区域支持范围内进行任意组合。

API 仍然支持对数据分层以及无状态资源（ Kibana、机器学习节点 $ML$ 、主节点）的实例配置变更，以满足自动化场景的需求。

完整的实例配置自定义文档可在 Elastic Docs 中查看。

Elastic Cloud Hosted API 参考：升级、扩容、配置、打标签、快照

这些端点加上新的 Elastic Cloud 控制台工作流，为 ECH 提供了一套"动词化"的运维操作面：升级、扩容、设置、打标签、共享、定制。每个操作一次调用，且与完整部署计划使用相同的校验规则，同时支持 API 和 Terraform。这正是让大规模集群自动化变得可行的关键所在。

API	Endpoint	What it does
Upgrade	POST /deployments/{id}/upgrade	将所有资源升级到目标 Elastic Stack 版本
Tiers	PATCH /deployments/{id}/elasticsearch/{ref_id}/tiers	在不影响其他分层的情况下调整一个或多个分层大小
User settings	PUT /deployments/{id}/{resource_kind}/{ref_id}/user_settings	读取/更新 elasticsearch.yml 和 Kibana 设置
Tags	PUT /deployments/{id}/tags	读取/替换部署标签
Snapshot repository	POST/GET/DELETE /deployments/{id}/elasticsearch/{ref_id}/snapshot/repository	链接、列出并移除快照仓库关联

开始使用：

已经在 Elastic Cloud Hosted 上？从你的 Elastic Cloud 账户页面生成 API key，并尝试上述示例。完整参考文档见 Elastic Cloud API documentation。
更偏好基础设施即代码？Elastic Cloud Terraform provider 对这些 API 进行了封装，用于声明式部署管理。
刚接触 Elastic Cloud？开始免费试用，并在几分钟内部署你的第一个集群。

常见问题

如何将 Elastic Cloud Hosted 部署升级到新的 Elastic Stack 版本？

使用 POST /deployments/{id}/upgrade，并在请求体中包含 target_version 字段。该操作会在一次 API 调用中升级部署中的所有资源（Elasticsearch、Kibana 以及其他组件），无需构造完整部署计划。

可以在 Elastic Cloud Hosted 中只调整一个 Elasticsearch 分层而不影响其他分层吗？

可以。PATCH /deployments/{id}/elasticsearch/{ref_id}/tiers 端点接受一个以分层 ID 为键的请求体。只有你包含的分层会被修改，其余分层保持不变。有效的分层 ID 包括 hot_content、warm、cold、frozen、master、coordinating 和 ml。

如何在运行中的 Elastic Cloud Hosted 部署上更新 elasticsearch.yml 设置？

使用 PUT /deployments/{id}/elasticsearch/{ref_id}/user_settings，并提供仅包含你想设置的键的 JSON 请求体。未在请求体中包含的现有设置会被保留。当前部署中的 YAML 设置会在第一次 PUT 时自动迁移为 JSON。

如何将一个 Elastic Cloud Hosted 部署中的索引恢复到另一个部署中？

使用快照仓库关联 API：POST /deployments/{target_id}/elasticsearch/{ref_id}/snapshot/repository，并提供源部署 ID。这会创建一个对源部署托管快照仓库的只读链接。目标部署可以浏览并选择性恢复快照，而无需在链接时复制快照数据。

Elastic Cloud Hosted 的部署标签有什么限制？

每个部署最多支持 64 个标签。标签 key 最长 32 个字符，value 最长 128 个字符。如果超出限制，Tags API（GET 和 PUT /deployments/{id}/tags）会返回明确的 400 错误。

这些新的 Elastic Cloud Hosted 针对性 API 会绕过部署计划校验吗？

不会。所有五个新端点都会使用与完整 PUT /deployments/{id} 部署计划 API 相同的校验器。无论使用哪个端点，都会统一执行实例配置与规模匹配错误、分区数量限制以及拓扑规则等检查。

可以通过 Terraform 管理 Elastic Cloud Hosted 部署并使用这些新 API 吗？

可以。Elastic Cloud Terraform provider 对这些 API 进行了封装，用于声明式部署管理，包括升级、分层扩缩容、用户设置、标签以及快照仓库关联。这些针对性端点是新增能力；现有基于完整部署计划 API 的 Terraform 配置仍然可用。

这些内容对你有多大帮助？

原文：Elastic Cloud Hosted: five APIs for deployment management - Elasticsearch Labs