cloud-create-project

创建 Serverless 项目

使用 Serverless REST API 创建 Elastic Cloud Serverless 项目。对于列出、更新或删除项目等第 2 天运维操作，请使用 cloud-manage-project 技能。

前提条件和权限

• 确保已配置 EC_API_KEY。如果尚未配置，请先运行 cloud-setup 技能。
• 创建项目需要具有 Admin 或 Organization owner 角色的 Cloud API 密钥。
• 此技能不会单独预检查角色。请尝试执行请求的操作，并由 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 帐户。如果没有，请建议用户开始免费试用：Elastic Cloud 免费试用——14 天完整访问权限，无需信用卡。完成注册后，指导用户在 Elastic Cloud API 密钥页面生成密钥，然后按照以下步骤在本地配置。

首选方法（适合 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 密钥。 脚本会将 admin 密码保存到 .elastic-credentials，以便创建受限范围的 API 密钥。admin 用户拥有完整权限，且无法在 serverless 中修改。切勿将管理员凭据用于直接执行 Elasticsearch 操作（查询、索引等）——应始终先创建受限范围的 API 密钥（参见第 8 步）。默认情况下，load-credentials 命令会排除管理员凭据——仅在第 7/8 步使用 --include-admin，创建 API 密钥后再重新加载凭据，并且不要使用该选项。切勿在聊天中读取或显示 .elastic-credentials 的内容。
• 恢复丢失的凭据。 如果脚本未能写入 .elastic-credentials（磁盘已满、权限不足等），保存的内容可能不完整。请先检查 .elastic-credentials 中是否有密码。如果没有，请使用 cloud-manage-project 技能的 reset-credentials 命令生成新密码。
• 区域不可更改。 项目创建后无法更改其区域。
• 优先使用自动就绪检查。 将 --wait 传递给创建脚本，使其持续轮询，直到阶段从 initializing 变为 initialized。只有在 --wait 不可用时，才手动轮询状态端点。

项目类型

类型	描述	主要端点
elasticsearch	搜索、分析和向量工作负载	Elasticsearch、Kibana
observability	日志、指标、跟踪和 APM	Elasticsearch、Kibana、APM、OTLP
security	SIEM、端点防护、云安全	Elasticsearch、Kibana、OTLP

项目类型推断

将用户的请求映射到正确的 --type 值：

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

不要默默地使用任何默认类型。如果用户未指定类型，请根据对话上下文推断（例如，讨论日志摄取意味着 observability，讨论检测或 SIEM 意味着 security，讨论搜索或向量工作负载意味着 elasticsearch）。始终向用户说明推断出的类型，并在继续前征求确认。如果上下文不足以推断类型，请让用户选择。

产品层级

可观测性和安全项目支持 --product-tier 标志。除非用户明确要求其他层级，否则默认为 complete。

项目类型	层级	描述
observability	complete	完整的可观测性套件（日志、指标、跟踪、APM）
observability	logs_essentials	仅日志管理
security	complete	完整的安全套件（SIEM、云、端点）
security	essentials	仅核心 SIEM

Elasticsearch 项目没有产品层级，应改用 --optimized-for。

合理的默认值

创建前向用户展示以下默认值，并询问他们是否要使用或更改这些值：

设置	默认值
区域	gcp-us-central1

必须向用户确认项目类型，不要假定默认值。请参阅上文的“项目类型推断”。

除非用户明确要求 vector，否则始终使用 --optimized-for general_purpose。不要主动提供 vector 选项。

如果用户未指定名称，请询问名称，因为名称为必填项。

工作流：创建项目

Project Creation:
- [ ] Step 1: Verify API key is set
- [ ] Step 2: Present defaults and confirm with user
- [ ] Step 3: List available regions (optional)
- [ ] Step 4: Create the project
- [ ] Step 5: Save credentials and endpoints
- [ ] Step 6: Wait for project to initialize
- [ ] Step 7: Set environment variables
- [ ] Step 8: Recommend creating a scoped API key

步骤 1：确认已设置 API 密钥

echo "${EC_API_KEY:?Not set}"

如果未设置 EC_API_KEY，请先运行 cloud-setup 技能来配置身份验证和默认值。

步骤 2：展示摘要并向用户确认

展示摘要前，请确保用户已明确确认项目类型。如果用户未指定类型，请根据对话上下文推断并提出建议。如果上下文不明确，请让用户从 elasticsearch、observability 或 security 中选择。

创建前始终展示确认摘要。根据项目类型包含不同字段：

Elasticsearch 项目：

Project Summary:
  Type:          elasticsearch
  Name:          my-project
  Region:        gcp-us-central1

可观测性项目：

Project Summary:
  Type:          observability
  Name:          my-project
  Region:        gcp-us-central1
  Product tier:  complete

安全项目：

Project Summary:
  Type:          security
  Name:          my-project
  Region:        gcp-us-central1
  Product tier:  complete

继续前，请用户确认或修改任意值。

步骤 3：列出可用区域（可选）

python3 skills/cloud/create-project/scripts/create-project.py list-regions

输出按云服务提供商（AWS、Azure、GCP）分组，并按字母顺序排序。标有 * 的区域不支持创建项目。

步骤 4：创建项目

python3 skills/cloud/create-project/scripts/create-project.py create \
  --type elasticsearch \
  --name "my-project" \
  --region gcp-us-central1 \
  --optimized-for general_purpose \
  --wait

对于 Elasticsearch 项目，始终传入 --optimized-for general_purpose。只有在用户明确要求时，才使用 vector。

对于可观测性和安全项目，除非用户明确要求使用其他层级，否则传入 --product-tier complete。

始终传入 --wait，以便脚本自动轮询，直到项目就绪。

步骤 5：保存凭据和端点

脚本会自动将凭据写入工作目录中的 .elastic-credentials。标准输出中的 JSON 会隐去密码。

如果保存成功，请告知用户：

Credentials saved to .elastic-credentials — open that file to retrieve your password.

请勿在聊天中读取、使用 cat 命令查看或显示 .elastic-credentials 的内容。

如果保存失败，脚本会向 stderr 输出错误。检查 .elastic-credentials 是否存在且包含密码（可能只写入了部分内容）。如果缺少密码或文件不存在，请立即运行 cloud-manage-project 技能的 reset-credentials 命令来生成新密码。

创建响应还包含：

• 项目 ID — 后续所有操作都需要此 ID
• Cloud ID — 供客户端库使用
• Elasticsearch 和 Kibana 端点 — 可以安全地在聊天中显示

管理员凭据仅用于初始引导。建议创建一个范围受限的 API 密钥，以便后续访问（步骤 8）。

步骤 6：等待项目初始化

传入 --wait 时（推荐），脚本会自动轮询，直到项目阶段变为 initialized。无需手动轮询。

如果 Agent 运行时未传入 --wait，请手动轮询：

python3 skills/cloud/create-project/scripts/create-project.py status \
  --type elasticsearch \
  --id <project-id>

重复此操作，直到 phase 从 initializing 变为 initialized。

步骤 7：设置环境变量

创建脚本会将凭据和端点连同项目名称写入 .elastic-credentials 的文件头中。请使用 --include-admin 将它们载入当前 Shell，以便管理员凭据可用于步骤 8 中创建 API 密钥：

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

这会设置 ELASTICSEARCH_URL、KIBANA_URL、特定项目类型的端点（APM_URL、INGEST_URL），以及用于引导创建 API 密钥的管理员 ELASTICSEARCH_USERNAME/ELASTICSEARCH_PASSWORD。

步骤 8：创建范围受限的 API 密钥

admin 用户拥有完整权限，在无服务器项目中无法修改。**请勿使用管理员凭据执行 Elasticsearch 操作。**创建一个权限仅涵盖用户所需操作的 Elasticsearch API 密钥。

如果有 elasticsearch-authn 技能，请用它创建 API 密钥——它涵盖完整生命周期（创建、授权、失效、查询），并能正确处理权限范围。如果未安装该技能，请让用户安装该技能，或通过 Kibana > Stack Management > API keys 手动创建 API 密钥。创建后，使用特定项目的文件头格式将 API 密钥保存到 .elastic-credentials（参见 manage-project 技能中的“凭据文件格式”部分），然后在不使用 --include-admin 的情况下重新载入，以从环境中移除管理员凭据：

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

示例

使用默认设置创建 Elasticsearch 项目

python3 skills/cloud/create-project/scripts/create-project.py create \
  --type elasticsearch \
  --name "my-search-project" \
  --region gcp-us-central1 \
  --optimized-for general_purpose \
  --wait

创建可观测性项目

python3 skills/cloud/create-project/scripts/create-project.py create \
  --type observability \
  --name "prod-o11y" \
  --region aws-eu-west-1 \
  --product-tier complete \
  --wait

创建安全项目

python3 skills/cloud/create-project/scripts/create-project.py create \
  --type security \
  --name "siem-prod" \
  --region gcp-us-central1 \
  --product-tier complete \
  --wait

指南

• 如果未设置 EC_API_KEY，请先运行 cloud-setup 技能。
• 创建项目前，始终与用户确认项目配置。
• 切勿在聊天中显示密码或 API 密钥。请引导用户前往 .elastic-credentials。
• 切勿静默地默认项目类型。请根据上下文推断，并与用户确认。
• 默认使用 general_purpose 优化。仅在用户明确要求时使用 vector。
• 可观测性和安全项目默认使用 complete 产品层级。仅在用户明确要求时使用 logs_essentials 或 essentials。
• 始终传入 --wait，以便脚本轮询直至项目就绪。
• 如果凭据保存失败，请立即使用 cloud-manage-project 技能重置凭据。
• 创建后，建议创建范围受限的 API 密钥，而不要依赖管理员凭据。
• 创建后无法更改区域——请在继续操作前确认选择。

脚本参考

命令	描述
create	创建新的无服务器项目
status	获取项目初始化状态
list-regions	列出可用区域

标志	命令	描述
--type	create, status	项目类型：elasticsearch、observability、security
--name	create	项目名称（必填）
--region	create	区域 ID（默认：gcp-us-central1）
--id	status	项目 ID
--optimized-for	create	Elasticsearch 子类型：general_purpose 或 vector
--product-tier	create	可观测性／安全层级（参见“产品层级”部分）
--wait	create	退出前轮询，直至项目初始化完成

环境变量

变量	必需	描述
EC_API_KEY	是	Elastic Cloud API 密钥
EC_BASE_URL	否	Cloud API 基础 URL（默认：https://api.elastic-cloud.com）
ELASTICSEARCH_URL	输出	Elasticsearch URL（创建后通过 load-credentials 加载）
KIBANA_URL	输出	Kibana URL（创建后通过 load-credentials 加载）
APM_URL	输出	APM 端点（仅限可观测性项目）
INGEST_URL	输出	OTLP 摄取端点（可观测性和安全项目）
ELASTICSEARCH_API_KEY	输出	Elasticsearch API 密钥（在步骤 8 中创建，通过 load-credentials 加载）

其他资源

• 如需完整的 API 详情、请求／响应架构和项目类型选项，请参阅 references/api-reference.md