cloud-manage-project

管理 Serverless 项目

使用 Serverless REST API 对 Elastic Cloud Serverless 项目执行日常运维。

前提条件和权限

• 确保已配置 EC_API_KEY。如果未配置，请先运行 cloud-setup 技能。
• 更新项目设置需要在目标项目中拥有 Admin 或 Editor 角色。
• 此技能不会单独预先检查角色。尝试执行所请求的操作，并由 API 强制执行授权。如果 API 返回授权错误（例如 403 Forbidden），请停止操作，并让用户确认所提供的 API 密钥权限。

手动设置备用方案（当 cloud-setup 不可用时）

如果单独安装此技能且 cloud-setup 不可用，请指示用户在运行命令前手动配置 Cloud 环境变量。切勿要求用户在聊天中粘贴 API 密钥。

变量	必填	说明
EC_API_KEY	是	用于项目管理操作的 Elastic Cloud API 密钥。
EC_BASE_URL	否	Cloud API 基础 URL（默认值：https://api.elastic-cloud.com）。

**注意：**如果缺少 EC_API_KEY，或者用户尚未拥有 Cloud API 密钥，请引导用户前往 Elastic Cloud API keys 生成密钥，然后按照以下步骤在本地配置。

首选方法（便于 Agent 使用）：在项目根目录创建 .env 文件：

EC_API_KEY=your-api-key
EC_BASE_URL=https://api.elastic-cloud.com

所有 cloud/* 脚本都会自动从工作目录加载 .env。

备用方法：直接在终端中导出：

export EC_API_KEY="<your-cloud-api-key>"
export EC_BASE_URL="https://api.elastic-cloud.com"

在单独的 Shell 会话中运行的沙箱 Agent 可能无法访问终端导出的变量，因此使用 Agent 时优先采用 .env。

重要原则

• **切勿在聊天中显示机密信息。**不要在对话消息或 Agent 思考过程中回显、记录或重复 API 密钥、密码或凭据。请引导用户查看 .elastic-credentials 文件。管理员密码绝不能出现在聊天记录、思考轨迹或 Agent 输出中——即使是用它创建 API 密钥，也必须通过 Shell 变量替换直接传递，不能回显。
• **执行破坏性操作前先确认。**删除项目或重置凭据前，务必先征得用户确认。
• **凭据会保存到文件。**重置凭据后，脚本会自动将新密码写入 .elastic-credentials。标准输出会隐藏密码。切勿在聊天中读取或显示 .elastic-credentials 的内容。
• 管理员凭据仅用于创建 API 密钥。create-project 和 reset-credentials 保存的 admin 密码仅用于创建作用域受限的 API 密钥——切勿将其用于直接执行 Elasticsearch 操作。默认情况下，load-credentials 不会包含管理员凭据；仅在创建密钥时传入 --include-admin。
• **始终优先使用 API 密钥。**设置 ELASTICSEARCH_API_KEY 之前，不要执行 Elasticsearch 操作。如果只有管理员凭据，请通过 elasticsearch-authn 创建作用域受限的 API 密钥。如果未安装该技能，请让用户安装该技能，或在 Kibana > Stack Management > API keys 中手动创建密钥。
• **按类型和 ID 标识项目。**每条命令都需要同时指定 --type 和 --id（只有 list 只需要 --type）。
• **两种 API 密钥。**此技能使用 Cloud API 密钥（EC_API_KEY）执行项目管理操作（list、get、update、delete）。Elasticsearch 操作需要单独的 Elasticsearch API 密钥（ELASTICSEARCH_API_KEY），用于向项目的 Elasticsearch 端点进行身份验证。请勿混淆两者。

工作流：连接到现有项目

当用户要求查询或管理 Agent 在当前会话中未创建的项目时，请使用此工作流。此工作流会解析项目、保存其端点，并确保拥有可用的 Elasticsearch 凭据，然后再继续。

此工作流仅适用于 Elastic Cloud Serverless 项目。如果用户的 Elasticsearch 实例是自管理的或 Elastic Cloud Hosted，此技能不适用，请跳过并直接使用相关技能。 如果不确定，请询问用户：“你的 Elasticsearch 实例是 Elastic Cloud Serverless 项目吗？”

Connect to Existing Project:
- [ ] Step 1: Resolve the project
- [ ] Step 2: Get project details and load credentials
- [ ] Step 3: Acquire Elasticsearch credentials

第 1 步：解析项目

如果用户尚未提供，请询问其项目名称。根据用户的请求推断项目类型：

用户提到	--type
“搜索项目”、“elasticsearch 项目”、向量搜索	elasticsearch
“可观测性项目”、“o11y”、日志、指标、追踪、APM	observability
“安全项目”、“SIEM”、检测、端点保护	security

如果项目类型不明确，请列出全部三种类型以查找项目。

python3 skills/cloud/manage-project/scripts/manage-project.py list \
  --type elasticsearch

将用户提到的项目（名称、部分名称或别名）与列表结果进行匹配。如果有多个项目匹配或没有项目匹配，请向用户展示候选项并让其选择。

第 2 步：获取项目详情并加载凭据

确定唯一项目后，检查 .elastic-credentials 中是否已有该项目的条目（来自之前的会话）。如果有，请使用 load-credentials 加载：

eval $(python3 skills/cloud/manage-project/scripts/manage-project.py load-credentials \
  --name "<project-name>")

此命令会一次性为项目设置所有已保存的环境变量，包括端点和之前创建的任何 Elasticsearch API 密钥。管理员凭据（ELASTICSEARCH_USERNAME/ELASTICSEARCH_PASSWORD）会被刻意排除。 同一项目的后续部分会自动覆盖之前的值，因此始终以最新凭据为准。

如果 load-credentials 报告没有匹配的条目，请从 API 获取项目详情并手动导出端点：

python3 skills/cloud/manage-project/scripts/manage-project.py get \
  --type elasticsearch \
  --id <project-id>

然后从响应中导出端点 URL。可用端点取决于项目类型。

所有项目类型：

export ELASTICSEARCH_URL="<elasticsearch_endpoint>"
export KIBANA_URL="<kibana_endpoint>"

可观测性项目（额外）：

export APM_URL="<apm_endpoint>"
export INGEST_URL="<ingest_endpoint>"

安全项目（额外）：

export INGEST_URL="<ingest_endpoint>"

步骤 3：获取 Elasticsearch 凭据

如果 load-credentials 设置了 ELASTICSEARCH_API_KEY，请验证凭据是否有效：

curl -H "Authorization: ApiKey ${ELASTICSEARCH_API_KEY}" \
  "${ELASTICSEARCH_URL}/_security/_authenticate"

继续之前，请确认响应中包含有效的 username 和 "authentication_type": "api_key"。如果验证成功，请跳过本步骤的其余部分。

如果未加载凭据，或验证失败，请询问用户：“你是否已有此项目的 Elasticsearch API 密钥？”

如果有 — 请用户将其添加到 .elastic-credentials（参见“凭据文件格式”）。不要接受用户在聊天中提供密钥。 重新加载并验证：

eval $(python3 skills/cloud/manage-project/scripts/manage-project.py load-credentials \
  --name "<project-name>")
curl -H "Authorization: ApiKey ${ELASTICSEARCH_API_KEY}" \
  "${ELASTICSEARCH_URL}/_security/_authenticate"

如果没有 — 按照以下恢复流程操作：

1. 与用户确认后，重置管理员引导凭据：

   python3 skills/cloud/manage-project/scripts/manage-project.py reset-credentials \
     --type elasticsearch \
     --id <project-id>
   

   新密码会连同项目名称保存在 .elastic-credentials 的文件头中。请告知用户该文件的位置，不要显示其内容。

2. 使用 --include-admin 加载凭据，以便使用管理员密码创建 API 密钥：

   eval $(python3 skills/cloud/manage-project/scripts/manage-project.py load-credentials \
     --name "<project-name>" --include-admin)
   

   如果有 elasticsearch-authn 技能，请使用管理员凭据通过该技能创建权限范围受限的 Elasticsearch API 密钥。如果未安装该技能，请让用户安装该技能，或在 Kibana > Stack Management > API keys 中手动创建密钥。密钥权限范围仅限用户所需的权限。

3. 创建 API 密钥后，按照项目专用的文件头格式将其保存到 .elastic-credentials（参见下文的“凭据文件格式”）。然后不使用 --include-admin 重新加载，以从环境中移除管理员凭据并进行验证：

   eval $(python3 skills/cloud/manage-project/scripts/manage-project.py load-credentials \
     --name "<project-name>")
   curl -H "Authorization: ApiKey ${ELASTICSEARCH_API_KEY}" \
     "${ELASTICSEARCH_URL}/_security/_authenticate"
   

   继续之前，请确认响应中显示有效的 username 和 "authentication_type": "api_key"。

凭据文件格式

完整的格式规范请参见 references/credential-file-format.md。

工作流：加载项目凭据

eval $(python3 skills/cloud/manage-project/scripts/manage-project.py load-credentials \
  --name "<project-name>")

也可以按项目 ID 加载：

eval $(python3 skills/cloud/manage-project/scripts/manage-project.py load-credentials \
  --id <project-id>)

解析 .elastic-credentials，合并匹配项目的所有区段，并打印 export 语句。默认不包含管理员凭据（ELASTICSEARCH_USERNAME/ELASTICSEARCH_PASSWORD），仅导出端点和 API 密钥。需要使用管理员凭据创建 API 密钥时，请添加 --include-admin。

工作流：列出项目

python3 skills/cloud/manage-project/scripts/manage-project.py list \
  --type elasticsearch

使用 --type observability 或 --type security 可列出其他项目类型。

工作流：获取项目详情

python3 skills/cloud/manage-project/scripts/manage-project.py get \
  --type elasticsearch \
  --id <project-id>

工作流：更新项目

python3 skills/cloud/manage-project/scripts/manage-project.py update \
  --type elasticsearch \
  --id <project-id> \
  --name "new-project-name"

只更新提供的字段（PATCH 语义）。支持的字段：--name、--alias、--tag、 --search-power、--boost-window、--max-retention-days、--default-retention-days。

别名

别名是符合 RFC-1035 的域标签（由小写字母、数字和连字符组成，最长 50 个字符），并会成为项目端点 URL 的一部分。更改别名会更改所有端点 URL，导致指向旧 URL 的现有客户端无法继续使用。应用更改前，请提醒用户这一点。

python3 skills/cloud/manage-project/scripts/manage-project.py update \
  --type elasticsearch \
  --id <project-id> \
  --alias "prod-search"

标签

标签是用于团队跟踪、成本归属和组织管理的键值元数据对。每个标签使用 --tag KEY:VALUE 传入。一次更新可以设置多个标签。

python3 skills/cloud/manage-project/scripts/manage-project.py update \
  --type elasticsearch \
  --id <project-id> \
  --tag env:prod \
  --tag team:search

标签会作为 metadata.tags 发送到 API 请求中。设置标签会替换项目的所有现有标签，因此请一并传入用户想要保留的现有标签。

Elasticsearch search_lake 设置

对于 Elasticsearch 项目，两个字段用于控制 Search AI Lake 中的查询性能和数据缓存。摄取的数据存储在成本效益较高的通用存储中。其上的缓存层可加快对近期数据和频繁查询数据的搜索速度——这些缓存数据被视为已就绪可搜索。

标志	范围	描述
--search-power	28–3000	查询性能级别。值越高，性能越好，但成本也越高
--boost-window	1–180	符合增强缓存条件的数据天数（默认值：7）

Search Power

Search Power 通过配置更多或更少的查询资源来控制搜索速度。常用预设（与 Cloud UI 中的设置一致）：

值	预设	行为
28	按需	自动扩缩容，基线资源较低。延迟变化较大，最大吞吐量较低
100	高性能	延迟始终较低，可自动扩缩容以支持中高吞吐量
250	高可用性	针对高吞吐量场景优化，在高负载下仍能保持低延迟

当用户按名称请求某个预设时，请将其映射到对应的值。28–3000 范围内的自定义值也有效。

更新 search_power 前，提醒用户注意成本影响。 值越高，VCU 消耗越多，账单可能也越高。应用前请与用户确认新值。

Search Boost Window

非时序数据始终已就绪可搜索。增强窗口决定有多少时序数据（包含 @timestamp 字段的文档）也会保留在快速缓存层中。增大窗口意味着更多时序数据变为已就绪可搜索，这可以提高近期数据的查询速度，但会增加已就绪可搜索数据的总量。

安全数据保留设置

对于安全项目，两个字段用于控制 Search AI Lake 中的数据保留时长。保留期按数据流配置，但这些项目级设置会施加全局边界。

标志	单位	描述
--max-retention-days	天	项目中任何数据流的最长保留期限
--default-retention-days	天	对未设置自定义保留期的数据流应用的默认保留期限

• 最长保留期限 — 为所有数据流设置上限。调低后，当前保留期限较长的数据流将采用新的保留期限。早于新上限的数据将被永久删除。
• 默认保留期限 — 自动应用于未设置自定义保留期限的数据流。不影响已有自定义保留期限的数据流。

降低 max-retention-days 前，提醒用户。 降低上限会永久删除早于新上限的数据。应用前请与用户确认新值。

工作流：重置项目凭据

重置前务必与用户确认。

python3 skills/cloud/manage-project/scripts/manage-project.py reset-credentials \
  --type elasticsearch \
  --id <project-id>

新密码会自动保存到 .elastic-credentials。告知用户打开该文件——不要在聊天中显示其内容。

工作流：删除项目

删除前务必与用户确认。

python3 skills/cloud/manage-project/scripts/manage-project.py delete \
  --type elasticsearch \
  --id <project-id>

工作流：恢复已暂停的项目

试用期结束后，项目可能会自动暂停。使用以下命令恢复：

python3 skills/cloud/manage-project/scripts/manage-project.py resume \
  --type elasticsearch \
  --id <project-id>

恢复后，轮询项目状态，直到阶段从 initializing 变为 initialized。

示例

列出所有安全项目

python3 skills/cloud/manage-project/scripts/manage-project.py list --type security

更新 Elasticsearch 项目的搜索能力

python3 skills/cloud/manage-project/scripts/manage-project.py update \
  --type elasticsearch \
  --id abc123def456abc123def456abc12345 \
  --search-power 500

设置安全项目的数据保留期限

python3 skills/cloud/manage-project/scripts/manage-project.py update \
  --type security \
  --id abc123def456abc123def456abc12345 \
  --max-retention-days 396 \
  --default-retention-days 396

更改项目别名

python3 skills/cloud/manage-project/scripts/manage-project.py update \
  --type elasticsearch \
  --id abc123def456abc123def456abc12345 \
  --alias "prod-search"

为项目添加成本跟踪标签

python3 skills/cloud/manage-project/scripts/manage-project.py update \
  --type observability \
  --id abc123def456abc123def456abc12345 \
  --tag env:prod \
  --tag team:platform

重命名可观测性项目

python3 skills/cloud/manage-project/scripts/manage-project.py update \
  --type observability \
  --id abc123def456abc123def456abc12345 \
  --name "production-logs"

连接到现有项目（已有凭据）

User: I want to run a query against my search project "prod-search"
Agent: Let me find that project.
       [runs: list --type elasticsearch]
       I found "prod-search" (ID: abc123...). Loading saved credentials...
       [runs: eval $(load-credentials --name prod-search)]
       Credentials loaded. Verifying...
       [runs: curl -H "Authorization: ApiKey ..." "${ELASTICSEARCH_URL}/_security/_authenticate"]
       Verified — authenticated as user "my-service" via API key. You're all set.

连接到项目（没有保存的凭据）

User: let's ingest some logs into my o11y project "siem-prod"
Agent: Let me find that project.
       [runs: list --type observability]
       Found "siem-prod" (ID: def456...). No saved credentials found for this project.
       [runs: get --type observability --id def456...]
       Endpoints set. Since there are no Elasticsearch credentials on file, I can reset the
       admin bootstrap password to get initial access. Shall I proceed?
User: yes
Agent: [runs: reset-credentials --type observability --id def456...]
       Credentials saved to .elastic-credentials — open that file to retrieve the password.
       [runs: eval $(load-credentials --name siem-prod --include-admin)]
       Admin credentials loaded for API key creation. Creating a scoped Elasticsearch API key
       now — what access does it need?
User: read-only on logs-*
Agent: [creates scoped API key via elasticsearch-authn using admin credentials]
       [appends API key to .elastic-credentials with project header]
       [runs: eval $(load-credentials --name siem-prod)]
       [verifies against ELASTICSEARCH_URL]
       API key created and verified. Admin credentials removed from environment.

确认后删除项目

User: delete my elasticsearch project abc123...
Agent: Are you sure you want to delete project abc123...? This cannot be undone.
User: yes

python3 skills/cloud/manage-project/scripts/manage-project.py delete \
  --type elasticsearch \
  --id abc123def456abc123def456abc12345

指南

• 如果未设置 EC_API_KEY，请先运行 cloud-setup 技能。
• 使用 cloud-create-project 技能创建新项目——此技能仅处理现有项目。
• 当用户提及 Agent 未创建的项目时，请遵循“连接到现有项目”工作流。
• 删除操作不可逆。继续操作前务必向用户确认。
• 重置凭据后，提醒用户更新所有已保存的密码或环境变量。
• 提高 search_power 前，提醒用户注意成本影响。先与用户确认新值。
• 降低 max-retention-days 前，提醒用户注意数据丢失风险。超过新上限期限的数据将被永久删除。
• 提醒用户，更改项目别名会更改所有端点 URL，从而导致现有客户端无法使用。
• 设置标签会替换所有现有标签。先使用 get 获取当前标签，并包含用户希望保留的标签。

脚本参考

命令	说明
list	按类型列出项目
get	按 ID 获取项目详情
update	更新项目名称、别名、标签或 search_lake 设置
reset-credentials	重置项目凭据（新密码）
delete	删除项目
resume	恢复已暂停的项目
load-credentials	从 .elastic-credentials 加载项目已保存的凭据

标志	命令	说明
--type	list, get, update, reset-credentials, delete, resume	项目类型：elasticsearch、observability、security
--id	get, update, reset-credentials, delete, resume, load-credentials	项目 ID
--name	update, load-credentials	项目名称（update：新名称；load-credentials：用于查找）
--alias	update	新项目别名
--tag	update	格式为 KEY:VALUE 的标签（可重复，替换所有标签）
--search-power	update	搜索能力，28–3000（仅限 elasticsearch）
--boost-window	update	Boost 窗口，1–180 天（仅限 elasticsearch）
--max-retention-days	update	数据最长保留天数（仅限 security）
--default-retention-days	update	数据默认保留天数（仅限 security）
--include-admin	load-credentials	包含管理员用户名/密码（仅用于 API 密钥引导）
--wait-seconds	reset-credentials	等待凭据传播的秒数（0 表示跳过）

环境变量

变量	必需	说明
EC_API_KEY	是	Elastic Cloud API 密钥（项目管理操作）
EC_BASE_URL	否	Cloud API 基础 URL（默认值：https://api.elastic-cloud.com）
ELASTICSEARCH_URL	输出	Elasticsearch URL（解析项目后设置，供下游技能使用）
KIBANA_URL	输出	Kibana URL（解析项目后设置，供下游技能使用）
APM_URL	输出	APM 端点（仅限可观测性项目）
INGEST_URL	输出	OTLP 摄取端点（可观测性和安全项目）
ELASTICSEARCH_API_KEY	输出	Elasticsearch API 密钥（用于栈级操作）

其他资源

• 如需查看完整的 API 详情、请求/响应架构和项目类型选项，请参阅 无服务器项目 API
• 如需查看有关 Search AI Lake 设置、数据保留和项目功能的官方文档，请参阅 项目设置