Back to Details

cloud-provisioning

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cloud Provisioning

云资源配置

Provision and run Elastic Cloud infrastructure through the Cloud API: Serverless projects (create and day-2 operations), traffic filters (network security for those projects), and Elastic Cloud Hosted deployments. For configuring Cloud authentication and managing organization access, use the cloud-onboarding skill.
<!-- begin-partial: cloud-preamble -->
通过Cloud API配置并运行Elastic Cloud基础设施：Serverless项目（创建及日常运维操作）、流量过滤器（这些项目的网络安全）以及Elastic Cloud托管部署。如需配置Cloud身份验证和管理组织访问权限，请使用cloud-onboarding技能。
<!-- begin-partial: cloud-preamble -->

Environment Configuration

环境配置

This skill operates the Elastic Cloud control plane through the 
elastic
CLI. If the 
elastic
CLI is not installed, tell the user what it is needed for. Do not guess credentials, bypass the CLI to call the HTTP API directly, or attempt other workarounds.
Control-plane operations authenticate against the Elastic Cloud API (organization scope), not a single stack deployment. The 
elastic
CLI reads this from its active context, which stores an Elastic Cloud API key in the OS keychain. If a control-plane call fails with an authentication error, the context is missing or lacks a Cloud API key — instruct the user to add one, and never ask the user to paste an API key into the chat:
"Configure an Elastic Cloud context for the 
elastic
CLI, then re-run. Generate an Organization-level key at Elastic Cloud API keys and register it without echoing the secret in chat."
This skill references control-plane operations in HTTP-shorthand form with the 
cloud:
prefix (e.g., 
GET cloud:/api/v1/organizations
, 
POST cloud:/api/v1/serverless/projects/elasticsearch
). The Operations table at the end of this document maps each shorthand to the equivalent 
elastic cloud
command — always use the CLI rather than calling the HTTP API directly. Discover the organization ID from 
GET cloud:/api/v1/organizations
; do not ask the user for it.
<!-- end-partial: cloud-preamble -->
本技能通过
elastic
CLI操作Elastic Cloud控制平面。如果未安装
elastic
CLI，请告知用户其用途。请勿猜测凭据、绕过CLI直接调用HTTP API或尝试其他变通方法。
控制平面操作针对Elastic Cloud API（组织范围）进行身份验证，而非单个堆栈部署。
elastic
CLI从其活动上下文读取身份验证信息，该上下文将Elastic Cloud API密钥存储在操作系统密钥链中。如果控制平面调用因身份验证错误失败，说明上下文缺失或缺少Cloud API密钥——请指导用户添加密钥，切勿要求用户在聊天中粘贴API密钥：
“为
elastic
CLI配置Elastic Cloud上下文，然后重新运行。在Elastic Cloud API密钥生成组织级密钥，并在不泄露密钥的情况下完成注册。”
本技能使用带
cloud:
前缀的HTTP简写形式引用控制平面操作（例如
GET cloud:/api/v1/organizations
、
POST cloud:/api/v1/serverless/projects/elasticsearch
）。本文档末尾的操作表格将每个简写映射为等效的
elastic cloud
命令——始终使用CLI而非直接调用HTTP API。通过
GET cloud:/api/v1/organizations
获取组织ID；请勿向用户索要该ID。
<!-- end-partial: cloud-preamble -->

Critical principles

核心原则

  • Never display secrets in chat. Do not echo, log, or repeat passwords or API keys in conversation or agent thinking. Persist credentials into a CLI context (OS keychain) and direct the user there.
  • Confirm before creating or destroying. A project's or deployment's region is permanent; deletion is irreversible. Present the configuration and get explicit confirmation before creating, deleting, or resetting credentials.
  • Admin credentials are bootstrap-only. The 
    admin
    password returned on creation or reset exists solely to create a scoped API key. Never use admin credentials for ongoing Elasticsearch operations — mint a scoped key first.
  • Wait for readiness. A new project or deployment starts 
    initializing
    ; wait until 
    initialized
    before using it.
  • Two kinds of credentials. The Cloud context (Cloud API key) authorizes control-plane operations here. A project's or deployment's Elasticsearch API key authorizes data-plane operations against its Elasticsearch endpoint — do not confuse the two. See references/credentials-and-context.md.
  • 切勿在聊天中显示机密信息。请勿在对话或Agent思维中回显、记录或重复密码或API密钥。将凭据持久化到CLI上下文（操作系统密钥链）中，并引导用户通过该方式管理。
  • 创建或销毁前确认。项目或部署的区域是永久性的；删除操作不可逆转。在创建、删除或重置凭据前，展示配置信息并获取用户明确确认。
  • 管理员凭据仅用于初始化。创建或重置时返回的
    admin
    密码仅用于创建范围限定的API密钥。切勿将管理员凭据用于Elasticsearch的日常操作——请先生成范围限定的密钥。
  • 等待就绪状态。新项目或部署启动时处于
    initializing
    状态；需等待至
    initialized
    状态后方可使用。
  • 两种类型的凭据。Cloud上下文（Cloud API密钥）用于授权此处的控制平面操作。项目或部署的Elasticsearch API密钥用于授权针对其Elasticsearch端点的数据平面操作——请勿混淆两者。请参阅references/credentials-and-context.md。

Serverless projects

Serverless项目

Project types

项目类型

TypeDescriptionIncluded services
elasticsearch
Search, analytics, and vector workloadsElasticsearch, Kibana
observability
Logs, metrics, traces, and APMElasticsearch, Kibana, APM, OTLP
security
SIEM, endpoint protection, cloud securityElasticsearch, Kibana, OTLP
Map the user's request to the correct type; never silently default — infer from context and confirm, or ask when ambiguous. "search"/"elasticsearch"/vector search → 
elasticsearch
; "o11y"/logs/metrics/traces/APM → 
observability
; "SIEM"/detections/endpoint → 
security
.
Tiers and optimization. Elasticsearch: set 
optimized_for
to 
general_purpose
(default) unless the user explicitly requests 
vector
. Observability: set 
product_tier
to 
complete
(default) or 
logs_essentials
. Security: set 
product_types
tiers to 
complete
(default) or 
essentials
per product line (
security
, 
cloud
, 
endpoint
). See references/api-reference.md for the full request-body schema of each type.
类型描述包含的服务
elasticsearch
搜索、分析和向量工作负载Elasticsearch、Kibana
observability
日志、指标、追踪和APMElasticsearch、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。

Process: create a serverless project

流程：创建Serverless项目

  1. Confirm the project type. Infer it from the conversation and propose it, or ask the user to choose. Do not proceed on an assumed type.
  2. Confirm the configuration. Present a summary — name (required; ask if missing), region (default 
    gcp-us-central1
    ), and the tier/optimization for the type — and get explicit confirmation. If the region is uncertain, list options with 
    GET cloud:/api/v1/serverless/regions
    first; only regions with 
    project_creation_enabled: true
    accept new projects. Region is permanent.
  3. Create the project. Call 
    POST cloud:/api/v1/serverless/projects/{type}
    with the confirmed body. Wait for the 
    initialized
    phase and persist the returned credentials into a named CLI context (the password goes to the OS keychain, never to stdout or chat).
  4. Verify readiness. If creation did not block until ready, poll 
    GET cloud:/api/v1/serverless/projects/{type}/{id}/status
    until 
    phase
    is 
    initialized
    . The Elasticsearch and Kibana endpoints in the creation response are safe to share; the password is not.
  5. Bootstrap a scoped API key. Using the project context, create a scoped Elasticsearch API key with only the privileges the user needs via 
    POST /_security/api_key
    (the project's Elasticsearch endpoint), then rely on that key for all data-plane work. If the elasticsearch-authn skill is available, use it for full key lifecycle handling.
  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技能可用，请使用它处理完整的密钥生命周期。

Workflow: connect to an existing project

工作流：连接到现有项目

Use this when the user asks to query or manage a project not created in the current session. It applies to Elastic Cloud Serverless projects only — if the cluster is self-managed or Elastic Cloud Hosted, use the Hosted deployment workflow or skip. If unsure, ask: "Is your Elasticsearch instance an Elastic Cloud Serverless project?"
  1. Resolve the project. Infer the type and list projects with 
    GET cloud:/api/v1/serverless/projects/{type}
    . Match the user's reference (name or alias). If multiple or none match, present candidates and ask.
  2. Load endpoints and credentials. Fetch the project with 
    GET cloud:/api/v1/serverless/projects/{type}/{id}
    to get its Elasticsearch and Kibana endpoints, and select or create a CLI context bound to it.
  3. Acquire Elasticsearch credentials. Verify any existing project API key with 
    GET /_security/_authenticate
    (expect 
    "authentication_type": "api_key"
    ). If none works, confirm with the user, reset the admin bootstrap credentials with 
    POST cloud:/api/v1/serverless/projects/{type}/{id}/_reset-credentials
    , use the admin password once to create a scoped key via 
    POST /_security/api_key
    , persist it to the context, re-verify, and drop the admin credentials.
当用户要求查询或管理当前会话中未创建的项目时使用此流程。它仅适用于Elastic Cloud Serverless项目——如果集群是自托管或Elastic Cloud托管部署，请使用托管部署工作流或跳过。如果不确定，请询问：“您的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
    创建范围限定的密钥，将其持久化到上下文，重新验证，然后丢弃管理员凭据。

Day-2: list, get, update, delete, resume

日常运维：列出、获取、更新、删除、恢复

  • List projects of a type: 
    GET cloud:/api/v1/serverless/projects/{type}
    .
  • Get one project: 
    GET cloud:/api/v1/serverless/projects/{type}/{id}
    .
  • Update (PATCH semantics — only supplied fields change): 
    PATCH cloud:/api/v1/serverless/projects/{type}/{id}
    .
  • Reset credentials (confirm first): 
    POST cloud:/api/v1/serverless/projects/{type}/{id}/_reset-credentials
    .
  • Delete (confirm first — permanent): 
    DELETE cloud:/api/v1/serverless/projects/{type}/{id}
    .
  • Resume a suspended project, then poll status until 
    initialized
    : 
    POST cloud:/api/v1/serverless/projects/{type}/{id}/_resume
    .
Update fields and their risks. Supported PATCH fields: 
name
, 
alias
, 
metadata.tags
, 
traffic_filters
, and — for Elasticsearch — 
search_lake.search_power
(28–3000) and 
search_lake.boost_window
(1–180 days); for Security — data-retention limits.
  • Alias changes rewrite every endpoint URL, breaking existing clients. Warn before changing it.
  • Tags replace the whole tag set. Read current tags with a 
    GET
    first and include any the user wants to keep.
  • search_power
    drives cost.     Higher values increase VCU consumption. Warn and confirm before raising it (presets: 28 on-demand, 100 performant, 250 high availability).
  • Reducing max retention permanently deletes data older than the new limit. Warn and confirm before lowering it.
  • 列出指定类型的项目：
    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高可用型）。
  • 降低最大保留期限会永久删除超过新限制的旧数据。降低前需发出警告并确认。

Traffic filters (network security)

流量过滤器（网络安全）

Traffic filters restrict network access to Serverless projects. The Elastic Cloud UI calls this network security; the Cloud API uses traffic filters (
traffic-filters
in paths, 
traffic_filters
in project JSON). The two types are IP filters (type 
ip
, allowlist IPs/CIDRs) and VPC filters (type 
vpce
, AWS PrivateLink endpoint IDs).
Private connectivity in AWS is accepted by default. A VPC filter is only needed to restrict traffic to specific endpoint IDs. If you only need private connectivity (not filtering), create the VPC endpoint and DNS record in AWS — no filter is required. Use 
GET cloud:/api/v1/serverless/traffic-filters/metadata
to look up the PrivateLink service name for a region before creating the endpoint in AWS.
流量过滤器用于限制对Serverless项目的网络访问。Elastic Cloud UI将其称为网络安全；Cloud API使用traffic filters（路径中为
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服务名称。

Process: create and attach a filter

流程：创建并附加过滤器

  1. Identify components. Filter type (IP vs VPC), target region, source rules (IPs/CIDRs or VPC endpoint IDs), and which projects the filter should apply to.
  2. Check existing state. List current filters with 
    GET cloud:/api/v1/serverless/traffic-filters
    (optionally scoped by region). If a filter already covers the same sources for the same purpose, reuse it — filters are region-scoped and can attach to many projects.
  3. Create the filter. Call 
    POST cloud:/api/v1/serverless/traffic-filters
    with the 
    type
    , 
    region
    , and 
    rules
    . The response contains the generated filter 
    id
    .
  4. Associate with projects. Filter-to-project association is done through the project PATCH endpoint (
    PATCH cloud:/api/v1/serverless/projects/{type}/{id}
    with a 
    traffic_filters
    array). Provide the complete list of filter IDs; any ID omitted is disassociated.
  5. Verify. List filters again or 
    GET
    the project to confirm the change took effect.
Filter guidance: filters are region-scoped (a filter can only attach to projects in its region). Updating rules replaces the entire rule set — include all existing rules plus the new one. A filter cannot be deleted while still associated with a project — disassociate first, then 
DELETE cloud:/api/v1/serverless/traffic-filters/{id}
. 
include_by_default
auto-attaches a filter to all new projects in the region — use with caution. See references/traffic-filters.md for the full schemas.
  1. 确定组件。过滤器类型（IP或VPC）、目标区域、源规则（IP/CIDR或VPC端点ID）以及过滤器应应用到的项目。
  2. 检查现有状态。通过
    GET cloud:/api/v1/serverless/traffic-filters
    列出当前过滤器（可按区域范围筛选）。如果已有过滤器针对相同用途覆盖相同源，可复用该过滤器——过滤器是区域范围的，可附加到多个项目。
  3. 创建过滤器。使用
    type
    、
    region
    和
    rules
    调用
    POST cloud:/api/v1/serverless/traffic-filters
    。响应包含生成的过滤器
    id
    。
  4. 关联到项目。过滤器与项目的关联通过项目PATCH端点完成（
    PATCH cloud:/api/v1/serverless/projects/{type}/{id}
    ，携带
    traffic_filters
    数组）。提供完整的过滤器ID列表；任何被省略的ID都会被解除关联。
  5. 验证。再次列出过滤器或通过
    GET
    获取项目信息，确认更改已生效。
过滤器指南：过滤器是区域范围的（过滤器只能附加到同一区域的项目）。更新规则会替换整个规则集——需包含所有现有规则和新规则。过滤器在仍关联到项目时无法删除——先解除关联，然后调用
DELETE cloud:/api/v1/serverless/traffic-filters/{id}
。
include_by_default
会自动将过滤器附加到该区域的所有新项目——请谨慎使用。有关完整架构，请参阅references/traffic-filters.md。

Hosted deployments

托管部署

Elastic Cloud Hosted deployments are full stack deployments (Elasticsearch, Kibana, and optional APM/Integrations Server/Enterprise Search) sized from a deployment template, distinct from Serverless projects. Manage their lifecycle through the Cloud API's deployment endpoints.
Elastic Cloud托管部署是全栈部署（Elasticsearch、Kibana，以及可选的APM/集成服务器/企业搜索），根据部署模板调整规模，与Serverless项目不同。通过Cloud API的部署端点管理其生命周期。

Process: create a hosted deployment

流程：创建托管部署

  1. Choose a region and template. List deployment templates with 
    GET cloud:/api/v1/deployments/templates
    for the target region and confirm the template and stack version with the user. Region is permanent.
  2. Confirm the configuration (name, region, template, version, sizing) and get explicit confirmation before creating.
  3. Create the deployment. Call 
    POST cloud:/api/v1/deployments
    with the resource definition (or a 
    template_id
    ). The response returns the deployment ID and a one-time 
    elastic
    user password and endpoints — persist the credentials into a CLI context (keychain), never to chat.
  4. Verify readiness and bootstrap a scoped key. Poll 
    GET cloud:/api/v1/deployments/{id}
    until healthy, then mint a scoped Elasticsearch API key via 
    POST /_security/api_key
    and stop using the bootstrap 
    elastic
    password. See references/hosted-deployments.md for the create body and template schema.
  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。

Day-2: get, update, shut down, restore

日常运维：获取、更新、关闭、恢复

  • List deployments: 
    GET cloud:/api/v1/deployments
    .
  • Get one deployment: 
    GET cloud:/api/v1/deployments/{id}
    .
  • Update (resize, upgrade version, change resources): 
    PUT cloud:/api/v1/deployments/{id}
    .
  • Shut down (confirm first — stops the deployment): 
    POST cloud:/api/v1/deployments/{id}/_shutdown
    .
  • Restore a shut-down deployment: 
    POST cloud:/api/v1/deployments/{id}/_restore
    .
Hosted deployments use their own traffic-filter rulesets, managed separately from the Serverless traffic filters above — do not mix the two. See references/hosted-deployments.md.
  • 列出部署：
    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。

Examples

示例

"Create a search project called acme-search" — confirm type 
elasticsearch
, present the summary (name 
acme-search
, region 
gcp-us-central1
, 
optimized_for general_purpose
), and on confirmation call 
POST cloud:/api/v1/serverless/projects/elasticsearch
, wait for 
initialized
, persist credentials, then create a scoped API key with 
POST /_security/api_key
.
"List my security projects" — call 
GET cloud:/api/v1/serverless/projects/security
and present the names and IDs; treat it as a read-only day-2 request.
"Connect to my search project prod-search" — list Elasticsearch projects, match 
prod-search
, 
GET
it for endpoints, then verify or mint a scoped Elasticsearch API key before any data-plane work.
"Bump search power to 500 on my search project" — warn about the cost increase, confirm, then 
PATCH cloud:/api/v1/serverless/projects/elasticsearch/{id}
with 
search_lake.search_power = 500
.
"Only allow our office network 203.0.113.0/24 to projects in us-east-1" — list existing filters for 
us-east-1
, create an 
ip
filter with 
POST cloud:/api/v1/serverless/traffic-filters
(rule source 
203.0.113.0/24
), then attach the filter ID to the target projects via 
PATCH cloud:/api/v1/serverless/projects/{type}/{id}
.
"Spin up a hosted deployment in us-east-1" — list templates with 
GET cloud:/api/v1/deployments/templates
, confirm the template and stack version, then 
POST cloud:/api/v1/deployments
, wait until healthy, and mint a scoped API key.
“创建名为acme-search的搜索项目”——确认类型为
elasticsearch
，展示摘要信息（名称
acme-search
、区域
gcp-us-central1
、
optimized_for general_purpose
），确认后调用
POST cloud:/api/v1/serverless/projects/elasticsearch
，等待至
initialized
状态，持久化凭据，然后通过
POST /_security/api_key
创建范围限定的API密钥。
“列出我的安全项目”——调用
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密钥。

Guidelines

指南

  • Validate the Cloud context first (see Environment Configuration); use cloud-onboarding to configure it when validation fails.
  • Never display passwords or API keys in chat — persist them to a CLI context (OS keychain), and mint a scoped API key instead of relying on bootstrap admin credentials.
  • Never silently default a project type; infer and confirm. Default to 
    general_purpose
    optimization and the 
    complete
    tier; only change on explicit request.
  • Region cannot be changed after creation, and deletion/shutdown is permanent — confirm before proceeding.
  • Traffic filters are region-scoped; updating rules replaces the whole set; disassociate a filter from all projects before deleting it.
  • Keep Serverless traffic filters and Hosted deployment traffic-filter rulesets separate — they are different APIs.
  • For granting user access and Cloud API keys, see cloud-onboarding; for Elasticsearch data-plane key lifecycle, see elasticsearch-authn.
  • 首先验证Cloud上下文（请参阅环境配置）；验证失败时使用cloud-onboarding技能进行配置。
  • 切勿在聊天中显示密码或API密钥——将其持久化到CLI上下文（操作系统密钥链），并生成范围限定的API密钥，而非依赖初始化的管理员凭据。
  • 切勿默认选择项目类型；推断后需确认。默认使用
    general_purpose
    优化和
    complete
    层级；仅在用户明确要求时更改。
  • 创建后无法更改区域，删除/关闭操作是永久性的——操作前需确认。
  • 流量过滤器是区域范围的；更新规则会替换整个规则集；删除过滤器前需先解除与所有项目的关联。
  • 将Serverless流量过滤器和托管部署流量过滤器规则集分开——它们是不同的API。
  • 有关授予用户访问权限和Cloud API密钥的内容，请参阅cloud-onboarding；有关Elasticsearch数据平面密钥生命周期的内容，请参阅elasticsearch-authn。

Operations

操作

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>
Use the matching 
projects observability …
/ 
projects security …
commands for observability and security project types.
HTTP API（简写）
elastic
CLI命令
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>
对于observability和security类型的项目，使用对应的
projects observability …
/ 
projects security …
命令。