cloud-provisioning

Cloud 资源配置

通过 Cloud API 配置并运行 Elastic Cloud 基础设施：Serverless 项目（创建和日常运维）、流量过滤器（为这些项目提供网络安全），以及 Elastic Cloud Hosted 部署。如需配置 Cloud 身份验证和管理组织访问权限，请使用 cloud-onboarding skill。

环境配置

此 skill 通过 elastic CLI 操作 Elastic Cloud 控制平面。如果未安装 elastic CLI，请告知用户需要安装它。不要猜测凭据、绕过 CLI 直接调用 HTTP API，也不要尝试其他变通方法。

控制平面操作使用 Elastic Cloud API 进行身份验证（组织范围），而非针对单个 stack 部署。 elastic CLI 从其活动上下文中读取此信息，该上下文会在 OS 密钥链中存储 Elastic Cloud API 密钥。如果控制平面调用因身份验证错误而失败，则说明上下文缺失或未配置 Cloud API 密钥——请指示用户添加密钥，绝不要要求用户在聊天中粘贴 API 密钥：

“为 elastic CLI 配置 Elastic Cloud 上下文，然后重新运行。在 Elastic Cloud API keys 生成组织级密钥，并在注册时不要在聊天中回显密钥。”

此 skill 以 HTTP 简写形式引用控制平面操作，并使用 cloud: 前缀（例如， GET cloud:/api/v1/organizations、POST cloud:/api/v1/serverless/projects/elasticsearch）。本文档末尾的 操作表将每个简写映射到对应的 elastic cloud 命令——务必使用 CLI，而不要直接调用 HTTP API。通过 GET cloud:/api/v1/organizations 查找组织 ID；不要向用户询问。

重要原则

• 绝不要在聊天中显示机密信息。 不要在对话或 Agent 思考过程中回显、记录或重复密码或 API 密钥。将凭据保存到 CLI 上下文（OS 密钥链）中，并引导用户前往该处操作。
• 创建或销毁前务必确认。 项目或部署的区域是永久的；删除操作不可撤销。创建、删除或重置凭据前，先展示配置并取得明确确认。
• 管理员凭据仅用于引导初始化。 创建或重置时返回的 admin 密码仅用于创建限定范围的 API 密钥。绝不要将管理员凭据用于持续的 Elasticsearch 操作——请先生成限定范围的密钥。
• 等待就绪。 新项目或部署的初始状态为 initializing；请等待其变为 initialized 后再使用。
• 两种凭据类型。 Cloud 上下文（Cloud API 密钥）用于授权此处的控制平面操作。项目或部署的 Elasticsearch API 密钥用于授权对其 Elasticsearch 端点执行数据平面操作——切勿混淆二者。请参阅 references/credentials-and-context.md。

---

Serverless 项目

项目类型

类型	描述	包含的服务
elasticsearch	搜索、分析和向量工作负载	Elasticsearch、Kibana
observability	日志、指标、跟踪和 APM	Elasticsearch、Kibana、APM、OTLP
security	SIEM、终端保护、云安全	Elasticsearch、Kibana、OTLP

将用户的请求映射到正确的类型；绝不要默默采用默认类型——应根据上下文推断并确认，或在有歧义时询问。"search"/"elasticsearch"/向量搜索 → elasticsearch；"o11y"/日志/指标/跟踪/APM → observability； "SIEM"/检测/终端 → security。

层级和优化。 Elasticsearch：将 optimized_for 设为 general_purpose（默认值），除非用户明确要求使用 vector。Observability：将 product_tier 设为 complete（默认值）或 logs_essentials。Security：按产品线（security、cloud、endpoint）将 product_types 层级设为 complete（默认值）或 essentials。各类型的完整请求正文架构请参阅references/api-reference.md。

流程：创建无服务器项目

1. 确认项目类型。 根据对话推断并提出建议，或请用户选择。不得基于假定的类型继续操作。
2. 确认配置。 提供摘要——名称（必填；缺少时询问）、区域（默认值为 gcp-us-central1），以及该类型对应的层级/优化设置——并获得明确确认。如果区域 不确定，请先使用 GET cloud:/api/v1/serverless/regions 列出选项；只有 project_creation_enabled: true 的区域才能创建新项目。区域一经确定便不可更改。
3. 创建项目。 使用确认后的正文调用 POST cloud:/api/v1/serverless/projects/{type}。等待 initialized 阶段，并将返回的凭据保存到命名的 CLI 上下文中（密码应存入操作系统 钥匙串，绝不能输出到标准输出或聊天中）。
4. 验证就绪状态。 如果创建操作没有等待项目就绪，轮询 GET cloud:/api/v1/serverless/projects/{type}/{id}/status，直到 phase 为 initialized。创建响应中的 Elasticsearch 和 Kibana 端点可以安全分享；密码不可分享。
5. 创建范围受限的 API 密钥。 使用项目上下文，通过 POST /_security/api_key（项目的 Elasticsearch 端点）创建权限仅包含用户所需权限的 Elasticsearch API 密钥，然后在所有数据平面操作中使用该密钥。如果 elasticsearch-authn 技能可用，请使用它来完整处理密钥生命周期。

工作流：连接到现有项目

当用户要求查询或管理当前会话中未创建的项目时，请使用此工作流。此流程仅适用于 Elastic Cloud Serverless 项目——如果集群是自行管理的或托管在 Elastic Cloud Hosted 上，请使用 Hosted 部署 工作流，或跳过。如果不确定，请询问：“您的 Elasticsearch 实例是 Elastic Cloud Serverless 项目吗？”

1. 解析项目。 推断类型，并使用 GET cloud:/api/v1/serverless/projects/{type} 列出项目。匹配 用户提到的项目（名称或别名）。如果匹配到多个或没有匹配项，请列出候选项并询问用户。
2. 加载端点和凭据。 使用 GET cloud:/api/v1/serverless/projects/{type}/{id} 获取项目的 Elasticsearch 和 Kibana 端点，并选择或创建绑定到该项目的 CLI 上下文。
3. 获取 Elasticsearch 凭据。 使用 GET /_security/_authenticate 验证任何现有项目 API 密钥 （预期 "authentication_type": "api_key"）。如果均无法使用，请先征得用户确认，使用 POST cloud:/api/v1/serverless/projects/{type}/{id}/_reset-credentials 重置管理员引导凭据，然后仅使用一次管理员密码， 通过 POST /_security/api_key 创建受限范围的密钥，将其保存到上下文中，重新验证，并删除管理员 凭据。

第 2 天：列出、获取、更新、删除、恢复

• 列出指定类型的项目：GET cloud:/api/v1/serverless/projects/{type}。
• 获取一个项目：GET cloud:/api/v1/serverless/projects/{type}/{id}。
• 更新（PATCH 语义——仅更改提供的字段）：PATCH cloud:/api/v1/serverless/projects/{type}/{id}。
• 重置凭据（先确认）：POST cloud:/api/v1/serverless/projects/{type}/{id}/_reset-credentials。
• 删除（先确认——永久删除）：DELETE cloud:/api/v1/serverless/projects/{type}/{id}。
• 恢复已暂停的项目，然后轮询状态，直到状态变为 initialized： POST cloud:/api/v1/serverless/projects/{type}/{id}/_resume。

更新字段及其风险。 支持的 PATCH 字段：name、alias、metadata.tags、traffic_filters，以及—— 对于 Elasticsearch——search_lake.search_power（28–3000）和 search_lake.boost_window（1–180 天）；对于 Security—— 数据保留期限限制。

• 更改别名会重写所有端点 URL，导致现有客户端失效。更改前请提醒用户。
• 标签会替换整个标签集。 先使用 GET 读取当前标签，并包含用户希望保留的标签。
• search_power 会影响成本。 数值越高，VCU 消耗越多。提高数值前请提醒并征得用户确认（预设值： 按需为 28，高性能为 100，高可用性为 250）。
• 降低最长保留期限会永久删除超出新期限的数据。 降低前请提醒并征得用户确认。

---

流量筛选器（网络安全）

流量筛选器用于限制对 Serverless 项目的网络访问。Elastic Cloud UI 将此功能称为 网络安全； Cloud API 则使用 流量筛选器（路径中为 traffic-filters，项目 JSON 中为 traffic_filters）。两种类型 分别是 IP 筛选器（类型 ip，允许列表中的 IP/CIDR）和 VPC 筛选器（类型 vpce，AWS PrivateLink 端点 ID）。

AWS 中的私有连接默认可用。只有需要将流量限制到特定端点 ID 时，才需要 VPC 筛选器。如果只需要私有连接 （无需筛选），请在 AWS 中创建 VPC 端点和 DNS 记录——无需筛选器。在 AWS 中创建端点之前，请使用 GET cloud:/api/v1/serverless/traffic-filters/metadata 查询相应区域的 PrivateLink 服务 名称。

流程：创建并关联筛选器

1. 确定组件。 筛选器类型（IP 或 VPC）、目标区域、来源规则（IP/CIDR 或 VPC 端点 ID），以及筛选器应应用于哪些项目。
2. 检查现有状态。 使用 GET cloud:/api/v1/serverless/traffic-filters 列出当前筛选器（可按区域筛选）。如果已有筛选器针对相同用途覆盖相同来源，请重复使用——筛选器按区域划分，可关联到多个项目。
3. 创建筛选器。 调用 POST cloud:/api/v1/serverless/traffic-filters 并提供 type、region 和 rules。响应中包含生成的筛选器 id。
4. 关联到项目。 通过项目 PATCH 端点完成筛选器与项目的关联（使用 traffic_filters 数组调用 PATCH cloud:/api/v1/serverless/projects/{type}/{id}）。请提供筛选器 ID 的完整列表；未提供的任何 ID 都会解除关联。
5. 验证。 再次列出筛选器或 GET 项目，以确认更改已生效。

筛选器指南： 筛选器按区域划分（筛选器只能关联到其所在区域的项目）。更新规则会替换整个规则集，因此请包含所有现有规则以及新增规则。筛选器仍与项目关联时无法删除——请先解除关联，然后调用 DELETE cloud:/api/v1/serverless/traffic-filters/{id}。include_by_default 会自动将筛选器关联到该区域中的所有新项目——请谨慎使用。完整架构请参阅 references/traffic-filters.md。

---

托管部署

Elastic Cloud 托管部署是完整堆栈部署（Elasticsearch、Kibana，以及可选的 APM/Integrations Server/Enterprise Search），根据部署模板确定规模，与 Serverless 项目不同。请通过 Cloud API 的部署端点管理其生命周期。

流程：创建托管部署

1. 选择区域和模板。 使用 GET cloud:/api/v1/deployments/templates 列出目标区域的部署模板，并与用户确认模板和堆栈版本。区域一经选定便不可更改。
2. 确认配置（名称、区域、模板、版本、规模），并在创建前获得明确确认。
3. 创建部署。 使用资源定义（或 template_id）调用 POST cloud:/api/v1/deployments。响应会返回部署 ID、一次性 elastic 用户密码和端点——请将凭据保存到 CLI 上下文（密钥链），切勿发送到聊天中。
4. 验证就绪状态并创建作用域受限的密钥。 轮询 GET cloud:/api/v1/deployments/{id}，直到状态健康，然后通过 POST /_security/api_key 创建作用域受限的 Elasticsearch API 密钥，并停止使用引导用的 elastic 密码。创建请求体和模板架构请参阅 references/hosted-deployments.md。

第 2 天：获取、更新、关闭、恢复

• 列出部署：GET cloud:/api/v1/deployments。
• 获取单个部署：GET cloud:/api/v1/deployments/{id}。
• 更新（调整规模、升级版本、更改资源）：PUT cloud:/api/v1/deployments/{id}。
• 关闭（请先确认——此操作会停止部署）：POST cloud:/api/v1/deployments/{id}/_shutdown。
• 恢复已关闭的部署：POST cloud:/api/v1/deployments/{id}/_restore。

托管部署使用独立的流量筛选器规则集，与上文的 Serverless 流量筛选器分开管理——请勿混用。请参阅 references/hosted-deployments.md。

---

示例

“创建一个名为 acme-search 的搜索项目” — 确认类型为 elasticsearch，展示摘要（名称 acme-search、区域 gcp-us-central1、optimized_for general_purpose），并在确认后调用 POST cloud:/api/v1/serverless/projects/elasticsearch，等待状态变为 initialized，保存凭据，然后创建一个范围受限的 API 密钥，调用 POST /_security/api_key。

“列出我的安全项目” — 调用 GET cloud:/api/v1/serverless/projects/security 并展示名称和 ID； 将其视为只读的日常运维请求。

“连接到我的搜索项目 prod-search” — 列出 Elasticsearch 项目，匹配 prod-search，调用 GET 获取 端点，然后在进行任何数据平面操作前，验证或生成范围受限的 Elasticsearch API 密钥。

“将我的搜索项目的搜索算力提升到 500” — 提醒用户成本会增加，确认后调用 PATCH cloud:/api/v1/serverless/projects/elasticsearch/{id}，设置 search_lake.search_power = 500。

“仅允许我们的办公网络 203.0.113.0/24 访问 us-east-1 中的项目” — 列出 us-east-1 中现有的筛选器， 通过 POST cloud:/api/v1/serverless/traffic-filters 创建 ip 筛选器（规则来源为 203.0.113.0/24），然后通过 PATCH cloud:/api/v1/serverless/projects/{type}/{id} 将筛选器 ID 关联到目标项目。

“在 us-east-1 中启动一个托管部署” — 通过 GET cloud:/api/v1/deployments/templates 列出模板，确认 模板和堆栈版本，然后调用 POST cloud:/api/v1/deployments，等待状态变为健康，再生成一个范围受限的 API 密钥。

指南

• 首先验证 Cloud 上下文（请参阅环境配置）；如果验证失败，请使用 cloud-onboarding 进行配置。
• 切勿在聊天中显示密码或 API 密钥 — 将其保存到 CLI 上下文（OS 密钥链）中，并生成范围受限的 API 密钥， 而不是依赖引导管理员凭据。
• 切勿默默地默认项目类型；应推断并确认。默认采用 general_purpose 优化和 complete 层级；仅在用户明确要求时更改。
• 创建后无法更改区域，删除或关闭操作不可逆 — 请在继续前确认。
• 流量筛选器按区域限定；更新规则会替换整个规则集；删除筛选器前，先将其从所有项目中解除关联。
• Serverless 流量筛选器和 Hosted 部署流量筛选规则集应分开处理 — 它们属于不同的 API。
• 有关授予用户访问权限和 Cloud API 密钥的信息，请参阅 cloud-onboarding；有关 Elasticsearch 数据平面密钥生命周期，请参阅 elasticsearch-authn。

操作

HTTP API (shorthand)	elastic CLI command
GET cloud:/api/v1/serverless/regions	elastic cloud serverless regions list-regions
POST cloud:/api/v1/serverless/projects/elasticsearch	elastic cloud serverless projects search create --input-file <json> --wait --save-as <ctx>
POST cloud:/api/v1/serverless/projects/observability	elastic cloud serverless projects observability create --input-file <json> --wait --save-as <ctx>
POST cloud:/api/v1/serverless/projects/security	elastic cloud serverless projects security create --input-file <json> --wait --save-as <ctx>
GET cloud:/api/v1/serverless/projects/elasticsearch	elastic cloud serverless projects search list
GET cloud:/api/v1/serverless/projects/elasticsearch/{id}	elastic cloud serverless projects search get --id <id>
GET cloud:/api/v1/serverless/projects/elasticsearch/{id}/status	elastic cloud serverless projects search get-status --id <id>
PATCH cloud:/api/v1/serverless/projects/elasticsearch/{id}	elastic cloud serverless projects search patch --id <id> --input-file <json>
DELETE cloud:/api/v1/serverless/projects/elasticsearch/{id}	elastic cloud serverless projects search delete --id <id>
POST cloud:/api/v1/serverless/projects/elasticsearch/{id}/_reset-credentials	elastic cloud serverless projects search reset-credentials --id <id> --save-as <ctx>
POST cloud:/api/v1/serverless/projects/elasticsearch/{id}/_resume	elastic cloud serverless projects search resume --id <id>
GET cloud:/api/v1/serverless/traffic-filters	elastic cloud serverless traffic-filters list-traffic-filters --region <region>
POST cloud:/api/v1/serverless/traffic-filters	elastic cloud serverless traffic-filters create-traffic-filter --input-file <json>
GET cloud:/api/v1/serverless/traffic-filters/{id}	elastic cloud serverless traffic-filters get-traffic-filter --id <id>
PATCH cloud:/api/v1/serverless/traffic-filters/{id}	elastic cloud serverless traffic-filters patch-traffic-filter --id <id> --input-file <json>
DELETE cloud:/api/v1/serverless/traffic-filters/{id}	elastic cloud serverless traffic-filters delete-traffic-filter --id <id>
GET cloud:/api/v1/serverless/traffic-filters/metadata	elastic cloud serverless traffic-filters get-traffic-filter-metadata --region <region>
GET cloud:/api/v1/deployments/templates	elastic cloud hosted deployment-templates get-deployment-templates-v2
GET cloud:/api/v1/deployments	elastic cloud hosted deployments list-deployments
POST cloud:/api/v1/deployments	elastic cloud hosted deployments create-deployment --input-file <json>
GET cloud:/api/v1/deployments/{id}	elastic cloud hosted deployments get-deployment --deployment-id <id>
PUT cloud:/api/v1/deployments/{id}	elastic cloud hosted deployments update-deployment --deployment-id <id> --input-file <json>
POST cloud:/api/v1/deployments/{id}/_shutdown	elastic cloud hosted deployments shutdown-deployment --deployment-id <id>
POST cloud:/api/v1/deployments/{id}/_restore	elastic cloud hosted deployments restore-deployment --deployment-id <id>
GET /_security/_authenticate	elastic es security authenticate
POST /_security/api_key	elastic es security create-api-key --input-file <json>

对于可观测性和安全项目类型，请使用相应的 projects observability … / projects security … 命令。