cloud-onboarding

Cloud 入门

端到端搭建对 Elastic Cloud 组织的访问：配置 elastic CLI，使其能够操作控制平面，然后管理身份和访问权限——邀请用户、为 Serverless 项目分配预定义或自定义角色，以及管理 Cloud API 密钥。要创建和操作项目及部署，请使用 cloud-provisioning 技能。

环境配置

此技能配置的是 elastic CLI 本身，因此其设置在此处说明，而非默认已完成。如果尚未安装 elastic CLI，请告知用户安装它的用途。

Cloud 控制平面访问通过 Elastic Cloud API 密钥（组织级别）进行身份验证，并存储在 CLI 上下文中。注册密钥时，切勿让用户将密钥粘贴到聊天中：

• 只有组织所有者才能创建 Cloud API 密钥。请引导用户前往 Elastic Cloud API keys 生成密钥，并授予 Project Admin 或更高级别的权限，以便管理 serverless 项目。
• 如果用户没有 Elastic Cloud 账户，请建议使用免费的 Elastic Cloud 试用版（14 天，无需信用卡）。注册后，继续生成密钥。
• 将密钥添加到上下文中（密钥会存储在操作系统密钥链中，不会回显）：elastic config context add cloud --cloud-url https://api.elastic-cloud.com --cloud-api-key <KEY>，然后使用 elastic config current-context set cloud 将其设为活动上下文。

不要猜测凭据、绕过 CLI 直接调用 HTTP API，也不要要求用户透露密钥。此技能使用带 cloud: 前缀的 HTTP 简写形式引用控制平面操作（例如，GET cloud:/api/v1/organizations）；Operations 表格列出了各操作对应的 elastic cloud 命令。

有关详细的 API 架构（角色分配、Cloud API 密钥、自定义角色），请参阅 references/api-reference.md。有关超出 Cloud 角色范围的 Elasticsearch 级别角色管理（原生用户、角色映射、DLS/FLS），请参阅 elasticsearch-authz。

待完成任务

• 配置并验证 Cloud 上下文；为后续创建项目设置默认区域
• 邀请用户并分配 Serverless 项目角色；列出成员及其角色；更新或移除访问权限
• 创建、列出和撤销 Cloud API 密钥；可按需为项目授予 Elasticsearch/Kibana API 访问权限
• 在 Serverless 项目中创建自定义角色，并通过 Cloud API 的 application_roles 分配该角色
• 将自然语言访问请求转换为邀请、角色和 API 密钥任务

流程：验证环境

1. 验证 Cloud 上下文。 通过调用 GET cloud:/api/v1/organizations，确认活动上下文能够访问控制平面。成功的响应会列出密钥所属的组织，并返回其他步骤所需的组织 ID。如果返回身份验证错误，则表示上下文缺失，或密钥无效或已过期——请返回环境配置并注册有效密钥。验证成功前不要继续，也绝不要向用户索取组织 ID——请在此处获取。

2. 设置默认区域（可选）。 如果用户计划创建项目，请使用 GET cloud:/api/v1/serverless/regions 列出可用区域，并确认默认区域。除非用户另有要求，否则默认使用 gcp-us-central1；只有 project_creation_enabled: true 的区域才能创建新项目。每个项目选定的区域无法更改，因此请尽早告知用户。

权限

此技能不会预先检查角色；它会尝试执行操作，并由 API 强制执行授权。遇到 403 时，请停止操作并 让用户确认 API 密钥的权限。

操作	所需权限
邀请 / 移除成员	组织所有者（organization-admin）
分配或移除角色	组织所有者（organization-admin）
创建 / 撤销 Cloud API 密钥	组织所有者（organization-admin）
列出成员、邀请或密钥	任何组织成员
创建 / 删除自定义角色	项目 ES 端点上的 manage_security 集群权限

预定义角色

优先使用预定义角色；只有在其粒度不足以满足需求时，才创建自定义角色。

组织： organization-admin（完全管理员权限）、billing-admin（仅限账单）。

Serverless 项目角色（可在邀请时或通过角色分配更新进行分配）：

角色	role_id	可用于
管理员	admin	Search、Obs、Security
开发者	developer	Search
查看者	viewer	Search、Obs、Security
编辑者	editor	Obs、Security
分析师	t1_analyst、t2_analyst、t3_analyst、soc_manager、rule_author	Security

完整的 role_assignments 架构（组织、部署和项目范围）以及完整的 Security 角色列表，请参阅 references/api-reference.md。

流程：分解访问请求

当用户用自然语言描述访问需求时（例如“将 Alice 添加到我的搜索项目并设为开发者”），请先分解需求，再执行操作。

1. 识别组成部分。 谁（新邀请还是现有成员）、内容（哪个项目或组织级别）、访问级别 （预定义角色还是自定义角色），以及是否还需要 API 密钥。

2. 先检查现有状态。 使用 GET cloud:/api/v1/organizations/{org_id}/members 列出成员；对于密钥 请求，使用 GET cloud:/api/v1/users/auth/keys 列出已有密钥。如果用户已经是成员，请更新其角色，而不是发送邀请。如果已有有效密钥用途相同、角色正确且剩余有效期足够，则重复使用该密钥。

3. 执行满足需求的最小变更。

   • 邀请新成员：使用 POST cloud:/api/v1/organizations/{org_id}/invitations（包含项目角色 分配；如果之后要分配自定义角色，也可以先不分配角色就发送邀请）。
   • 更新现有成员的角色：使用 POST cloud:/api/v1/users/{user_id}/role_assignments；使用 DELETE 变体移除角色。
   • 移除成员：使用 DELETE cloud:/api/v1/organizations/{org_id}/members/{user_ids}（先确认）。
   • 创建 Cloud API 密钥：使用 POST cloud:/api/v1/users/auth/keys；使用 DELETE cloud:/api/v1/users/auth/keys 撤销密钥（先确认）。执行破坏性操作（移除成员、撤销密钥）前，先向用户确认。

4. 验证。 再次列出成员或密钥，确认变更已生效。

自定义角色（Serverless）

当预定义角色的粒度不够时，可通过 Elasticsearch 安全 API 在项目中创建自定义角色，并通过 Cloud API 的 application_roles 分配该角色：

1. 使用 PUT /_security/role/{name} 在项目中创建角色（请求发送到项目的 Elasticsearch 端点；需要 manage_security）。角色名称必须以字母或数字开头，且只能包含字母、数字、_、-、.。Serverless 中不提供 Run-as 权限。
2. 如有需要，邀请用户——不分配项目角色（由自定义角色处理项目访问权限）。
3. 在项目范围的角色分配中设置 application_roles，以分配自定义角色（POST cloud:/api/v1/users/{user_id}/role_assignments），并将 role_id 设置为项目类型的查看者角色（elasticsearch-viewer、observability-viewer、security-viewer）。

请勿为同一项目同时分配预定义 Cloud 角色。 自定义角色已授予查看者级别的 Cloud 访问权限；再添加 viewer（或其他预定义角色），会让用户获得两者权限的并集，扩大自定义角色原本设定的访问范围。

可访问堆栈的 Cloud API 密钥

Cloud API 密钥也可以通过在 role_assignments 中加入 application_roles，调用 Serverless 项目上的 Elasticsearch 和 Kibana API。与用户不同，API 密钥绝不会从 role_id 继承堆栈角色——如果没有 application_roles，密钥只能访问 Cloud API，调用 ES/Kibana 时会收到 403。

• 默认使用项目范围的角色分配（project 键），让密钥只能访问指定项目或某一类型的所有项目。
• 组织范围的角色分配（organization 键）可授予对所有当前及未来项目的 ES/Kibana 访问权限，这是数据平面的最大范围。仅在确有跨项目自动化需求时使用，并先与用户确认。
• application_roles 中的自定义角色名称必须存在于每个目标项目中，否则密钥在该项目中会静默地无法获得访问权限。预定义角色（admin、developer、viewer）默认存在于每个项目中。

示例

“设置我的 Cloud 环境”——验证是否存在 Cloud 上下文，然后通过 GET cloud:/api/v1/organizations 对其进行验证。如果失败，引导用户生成组织级别的 Cloud API 密钥并将其注册为上下文（绝不在聊天中提供），然后重新验证并报告发现的组织。

“在 EU 区域设置 Cloud”——验证上下文后，通过 GET cloud:/api/v1/serverless/regions 列出区域，选择一个 EU 区域（例如 aws-eu-west-1），并确认将其设为后续创建项目时的默认区域。

“将 [email protected] 添加到我的搜索项目，并赋予只读权限”——通过 GET cloud:/api/v1/organizations/{org_id}/members 检查成员；如果 Alice 是新成员，则通过 POST cloud:/api/v1/organizations/{org_id}/invitations 邀请她，并为 Elasticsearch 项目分配项目范围的 viewer 角色。

“创建一个有效期为 30 天、可向我们的搜索项目编入索引的 CI 密钥”——通过 GET cloud:/api/v1/users/auth/keys 列出密钥以避免重复，然后通过 POST cloud:/api/v1/users/auth/keys 创建密钥，并为其分配项目范围的 developer 角色，其中包含 application_roles: ["developer"] 和 expiration: "30d"。密钥仅显示一次——绝不在聊天中重复提供。

“让 [email protected] 只读访问我的搜索项目中的 marketing-*”——使用 PUT /_security/role/marketing-reader 创建自定义角色（对 marketing-* 具有读取权限），在不分配项目角色的情况下邀请 Bob，然后通过 POST cloud:/api/v1/users/{user_id}/role_assignments 中的 application_roles 分配自定义角色。不要同时分配 viewer。

“显示谁有权访问我的组织”——调用 GET cloud:/api/v1/organizations/{org_id}/members，并列出每位成员的 ID、邮箱和角色。

指南

• 首先验证 Cloud 上下文；通过 GET cloud:/api/v1/organizations 获取组织 ID——不要向用户索要。
• 切勿在聊天中接收、复述或记录凭据。 将 Cloud API 密钥注册到 CLI 上下文中，以便将密钥存入 OS 密钥链；如果用户提出要粘贴密钥，请婉拒并引导其改为注册上下文。创建的密钥只会显示一次——告知用户妥善保存；切勿重复密钥。
• 默认区域为 gcp-us-central1——仅在用户要求使用其他区域时才更改。
• 执行破坏性操作（移除成员、撤销密钥）前，先确认。
• 优先使用预定义角色；仅在需要时使用自定义角色，并且绝不要在同一个项目上同时分配预定义 Cloud 角色和自定义角色。
• API 密钥安全规范： 创建密钥前先检查现有密钥；将 expiration 设置为与任务时长相符；提醒用户撤销不再需要的密钥。每个组织最多支持 500 个有效密钥；默认有效期为 3 个月。邀请默认在 72 小时后过期。Cloud API 密钥在创建时继承角色，之后无法更新——如需更改角色，请先撤销密钥再重新创建。
• 有关创建和管理项目、流量筛选器及部署的信息，请参阅 cloud-provisioning；有关 ES 级别的角色管理，请参阅 elasticsearch-authz。

Operations

HTTP API (shorthand)	elastic CLI command
GET cloud:/api/v1/organizations	elastic cloud orgs list-organizations
GET cloud:/api/v1/serverless/regions	elastic cloud serverless regions list-regions
GET cloud:/api/v1/organizations/{org_id}/members	elastic cloud orgs list-organization-members --organization-id <org_id>
POST cloud:/api/v1/organizations/{org_id}/invitations	elastic cloud orgs create-organization-invitations --organization-id <org_id> --input-file <json>
GET cloud:/api/v1/organizations/{org_id}/invitations	elastic cloud orgs list-organization-invitations --organization-id <org_id>
DELETE cloud:/api/v1/organizations/{org_id}/invitations/{tokens}	elastic cloud orgs delete-organization-invitations --organization-id <org_id> --invitation-tokens <csv>
DELETE cloud:/api/v1/organizations/{org_id}/members/{user_ids}	elastic cloud orgs delete-organization-memberships --organization-id <org_id> --user-ids <csv>
POST cloud:/api/v1/users/{user_id}/role_assignments	elastic cloud users add-role-assignments --user-id <user_id> --input-file <json>
DELETE cloud:/api/v1/users/{user_id}/role_assignments	elastic cloud users remove-role-assignments --user-id <user_id> --input-file <json>
POST cloud:/api/v1/users/auth/keys	elastic cloud auth create-api-key --input-file <json>
GET cloud:/api/v1/users/auth/keys	elastic cloud auth get-api-keys
DELETE cloud:/api/v1/users/auth/keys	elastic cloud auth delete-api-keys --input-file <json>
PUT /_security/role/{name}	elastic es security put-role --name <name> --input-file <json>
GET /_security/role	elastic es security get-role
DELETE /_security/role/{name}	elastic es security delete-role --name <name>