Back to Details

cloud-onboarding

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cloud Onboarding

Elastic Cloud 组织入门配置

Stand up access to an Elastic Cloud organization end to end: configure the 
elastic
CLI so it can operate the control plane, then manage identity and access — invite users, assign predefined or custom roles to Serverless projects, and manage Cloud API keys. For creating and operating projects and deployments, use the cloud-provisioning skill.
完整搭建Elastic Cloud组织的访问体系：配置
elastic
CLI以使其能够操作控制平面，然后管理身份与访问权限——邀请用户、为Serverless项目分配预定义或自定义角色，以及管理Cloud API密钥。如需创建和运营项目与部署，请使用cloud-provisioning技能。

Environment Configuration

环境配置

This skill configures the 
elastic
CLI itself, so its setup lives here rather than being assumed. If the 
elastic
CLI is not installed, tell the user what it is needed for.
Cloud control-plane access is authenticated by an Elastic Cloud API key (organization scope), stored in a CLI context. Register it without ever having the user paste the secret into the chat:
  • Only Organization owners can create Cloud API keys. Direct the user to generate one at Elastic Cloud API keys with Project Admin privileges or higher so it can manage serverless projects.
  • If the user has no Elastic Cloud account, propose the free Elastic Cloud trial (14 days, no credit card). Once registered, continue with key generation.
  • Add the key to a context (the secret is stored in the OS keychain, not echoed): 
    elastic config context add cloud --cloud-url https://api.elastic-cloud.com --cloud-api-key <KEY>
    , then make it active with 
    elastic config current-context set cloud
    .
Do not guess credentials, bypass the CLI to call the HTTP API directly, or ask the user to reveal the key. This skill references control-plane operations in HTTP-shorthand form with the 
cloud:
prefix (for example, 
GET cloud:/api/v1/organizations
); the Operations table maps each to the equivalent 
elastic cloud
command.
For detailed API schemas (role assignments, Cloud API keys, custom roles), see references/api-reference.md. For Elasticsearch-level role management beyond Cloud roles (native users, role mappings, DLS/FLS) see elasticsearch-authz.
本技能会配置
elastic
CLI本身，因此其设置流程包含在此处，而非默认已完成。如果未安装
elastic
CLI，请告知用户其用途。
Cloud控制平面的访问通过Elastic Cloud API密钥（组织范围）进行身份验证，密钥存储在CLI的上下文中。注册密钥时，无需让用户在聊天框中粘贴密钥明文：
  • 只有组织所有者可以创建Cloud API密钥。引导用户前往Elastic Cloud API密钥页面，生成拥有项目管理员或更高权限的密钥，用于管理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
）；操作列表表格会映射每个操作对应的
elastic cloud
命令。
如需详细的API schema（角色分配、Cloud API密钥、自定义角色），请查看references/api-reference.md。如需Cloud角色之外的Elasticsearch级角色管理（原生用户、角色映射、DLS/FLS），请查看elasticsearch-authz技能。

Jobs to be done

待完成任务

  • Configure and validate a Cloud context; establish a default region for later project creation
  • Invite a user and assign a Serverless project role; list members and their roles; update or remove access
  • Create, list, and revoke Cloud API keys, optionally with Elasticsearch/Kibana API access on projects
  • Create a custom role in a Serverless project and assign it via the Cloud API's 
    application_roles
  • Translate a natural-language access request into invite, role, and API key tasks
  • 配置并验证Cloud上下文；为后续项目创建设置默认区域
  • 邀请用户并分配Serverless项目角色；列出成员及其角色；更新或移除访问权限
  • 创建、列出和撤销Cloud API密钥，可选为其配置项目的Elasticsearch/Kibana API访问权限
  • 在Serverless项目中创建自定义角色，并通过Cloud API的
    application_roles
    进行分配
  • 将自然语言描述的访问请求转化为邀请、角色分配和API密钥管理任务

Process: validate the environment

流程：验证环境

  1. Validate the Cloud context. Confirm the active context can reach the control plane by calling 
    GET cloud:/api/v1/organizations
    . A successful response lists the organizations the key belongs to and yields the organization ID other steps need. If it returns an authentication error, the context is missing or the key is invalid or expired — return to Environment Configuration and register a valid key. Do not proceed until validation succeeds, and never ask the user for the organization ID — discover it here.
  2. Establish a default region (optional). When the user plans to create projects, list the available regions with 
    GET cloud:/api/v1/serverless/regions
    and confirm a default. Default to 
    gcp-us-central1
    unless the user requests otherwise; only regions with 
    project_creation_enabled: true
    accept new projects. Region choice is permanent per project, so surface it early.
  1. 验证Cloud上下文。通过调用
    GET cloud:/api/v1/organizations
    确认活跃上下文能够连接到控制平面。成功响应会列出密钥所属的组织，并返回后续步骤所需的组织ID。如果返回身份验证错误，说明上下文缺失或密钥无效/过期——回到环境配置步骤注册有效密钥。验证成功前请勿继续，且切勿向用户索要组织ID——在此步骤自动获取。
  2. 设置默认区域（可选）。当用户计划创建项目时，调用
    GET cloud:/api/v1/serverless/regions
    列出可用区域并确认默认区域。除非用户另有要求，否则默认使用
    gcp-us-central1
    ；仅
    project_creation_enabled: true
    的区域支持创建新项目。区域选择对每个项目是永久性的，因此需提前告知用户。

Permissions

权限

This skill does not pre-check roles; it attempts the operation and lets the API enforce authorization. On a 
403
, stop and ask the user to verify the API key's permissions.
OperationRequired permission
Invite / remove membersOrganization owner (
organization-admin
)
Assign or remove rolesOrganization owner (
organization-admin
)
Create / revoke Cloud API keysOrganization owner (
organization-admin
)
List members, invitations, or keysAny organization member
Create / delete custom roles
manage_security
cluster privilege on the project ES endpoint
本技能不会预先检查角色权限；会直接尝试执行操作，由API强制执行授权。如果返回
403
错误，请停止操作并要求用户验证API密钥的权限。
操作所需权限
邀请/移除成员组织所有者（
organization-admin
）
分配/移除角色组织所有者（
organization-admin
）
创建/撤销Cloud API密钥组织所有者（
organization-admin
）
列出成员、邀请信息或密钥任何组织成员
创建/删除自定义角色项目ES端点的
manage_security
集群权限

Predefined roles

预定义角色

Prefer predefined roles; only create a custom role when they lack the required granularity.
Organization: 
organization-admin
(full admin), 
billing-admin
(billing only).
Serverless project roles (assign at invitation or via role-assignment update):
Role
role_id
Available on
Admin
admin
Search, Obs, Security
Developer
developer
Search
Viewer
viewer
Search, Obs, Security
Editor
editor
Obs, Security
Analysts
t1_analyst
, 
t2_analyst
, 
t3_analyst
, 
soc_manager
, 
rule_author
Security
See references/api-reference.md for the full 
role_assignments
schema (organization, deployment, and project scopes) and the complete Security role list.
优先使用预定义角色；仅当预定义角色粒度不足时才创建自定义角色。
组织角色：
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
schema（组织、部署和项目范围）以及完整的Security角色列表，请查看references/api-reference.md。

Process: decompose an access request

流程：拆解访问请求

When the user describes access in natural language (for example, "add Alice to my search project as a developer"), break it down before executing.
  1. Identify components. Who (new invite vs existing member), what (which project or org-level), access level (predefined vs custom role), and whether an API key is also needed.
  2. Check existing state first. List members with 
    GET cloud:/api/v1/organizations/{org_id}/members
    and, for key requests, existing keys with 
    GET cloud:/api/v1/users/auth/keys
    . If the user is already a member, update their roles instead of inviting. If an active key already exists for the same purpose with the right roles and enough remaining lifetime, reuse it.
  3. Execute the smallest sufficient change.
    • Invite a new member with 
      POST cloud:/api/v1/organizations/{org_id}/invitations
      (include project role assignments, or invite without roles when a custom role will follow).
    • Update an existing member's roles with 
      POST cloud:/api/v1/users/{user_id}/role_assignments
      ; remove with the 
      DELETE
      variant.
    • Remove a member with 
      DELETE cloud:/api/v1/organizations/{org_id}/members/{user_ids}
      (confirm first).
    • Create a Cloud API key with 
      POST cloud:/api/v1/users/auth/keys
      ; revoke with 
      DELETE cloud:/api/v1/users/auth/keys
      (confirm first). Confirm destructive actions (remove member, revoke key) with the user before executing.
  4. Verify. List members or keys again to confirm the change took effect.
当用户用自然语言描述访问需求时（例如“将Alice添加到我的搜索项目中，赋予开发者权限”），请先拆解需求再执行操作。
  1. 识别核心要素：对象（新用户邀请 vs 现有成员）、范围（项目级 vs 组织级）、访问级别（预定义角色 vs 自定义角色），以及是否需要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. 验证结果。再次列出成员或密钥，确认变更已生效。

Custom roles (Serverless)

自定义角色（Serverless）

When predefined roles lack the granularity, create a custom role in the project via the Elasticsearch security API and assign it through the Cloud API's 
application_roles
:
  1. Create the role in the project with 
    PUT /_security/role/{name}
    (runs against the project's Elasticsearch endpoint; requires 
    manage_security
    ). Role names must start with a letter or digit and contain only letters, digits, 
    _
    , 
    -
    , 
    .
    . Run-as privileges are not available in Serverless.
  2. Invite the user if needed — without project role assignments (the custom role handles project access).
  3. Assign the custom role by setting 
    application_roles
    on a project-scoped role assignment (
    POST cloud:/api/v1/users/{user_id}/role_assignments
    ) with 
    role_id
    set to the project-type viewer (
    elasticsearch-viewer
    , 
    observability-viewer
    , 
    security-viewer
    ).
Do not also assign a predefined Cloud role for the same project. A custom role already grants Viewer-level Cloud access; adding 
viewer
(or another predefined role) gives the user the union of both, widening access beyond what the custom role intends.
当预定义角色粒度不足时，通过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 keys with stack access

具备栈访问权限的Cloud API密钥

Cloud API keys can also call Elasticsearch and Kibana APIs on Serverless projects by including 
application_roles
in their 
role_assignments
. Unlike users, API keys never inherit stack roles from 
role_id
 — without 
application_roles
the key has Cloud-API-only access and receives 
403
on ES/Kibana calls.
  • Default to project-scoped assignments (
    project
    key) so the key only reaches named projects or all projects of a type.
  • Organization-scoped assignments (
    organization
    key) grant ES/Kibana access to all current and future projects — the broadest data-plane scope. Only use it for genuine cross-project automation, and confirm with the user first.
  • Custom role names in 
    application_roles
    must exist in each target project, or the key silently gets no access there. Predefined roles (
    admin
    , 
    developer
    , 
    viewer
    ) exist in every project by default.
Cloud API密钥也可通过在
role_assignments
中包含
application_roles
，调用Serverless项目的Elasticsearch和Kibana API。与用户不同，API密钥不会从
role_id
继承栈角色——如果没有
application_roles
，密钥仅具备Cloud API访问权限，调用ES/Kibana API会返回
403
错误。
  • 默认使用项目范围的分配（
    project
    字段），确保密钥仅能访问指定项目或指定类型的所有项目。
  • 组织范围的分配（
    organization
    字段）会授予对所有当前及未来项目的ES/Kibana访问权限——这是最宽泛的数据平面范围。仅在真正需要跨项目自动化时使用，且需先获得用户确认。
  • application_roles
    中的自定义角色名称必须在每个目标项目中存在，否则密钥在该项目中将无访问权限。预定义角色（
    admin
    、
    developer
    、
    viewer
    ）默认存在于所有项目中。

Examples

示例

"Set up my cloud environment" — verify a Cloud context exists, then validate it with 
GET cloud:/api/v1/organizations
. If it fails, walk the user through generating an Organization-level Cloud API key and registering it as a context (never in chat), then re-validate and report the discovered organization.
"Set up cloud in the EU region" — after validating the context, list regions with 
GET cloud:/api/v1/serverless/regions
, pick an EU region (for example 
aws-eu-west-1
), and confirm it as the default for subsequent project creation.
"Add 
alice@example.com
to my search project with read-only access" — check members with 
GET cloud:/api/v1/organizations/{org_id}/members
; if Alice is new, 
POST cloud:/api/v1/organizations/{org_id}/invitations
with a project-scoped 
viewer
role for the Elasticsearch project.
"Create a 30-day CI key that can index into our search projects" — list keys with 
GET cloud:/api/v1/users/auth/keys
to avoid duplicates, then 
POST cloud:/api/v1/users/auth/keys
with a project-scoped 
developer
role assignment including 
application_roles: ["developer"]
and 
expiration: "30d"
. The secret is shown once — never repeat it in chat.
"Give 
bob@example.com
read-only access to marketing-* on my search project" — create a custom role with 
PUT /_security/role/marketing-reader
(read on 
marketing-*
), invite Bob without project roles, then assign the custom role via 
application_roles
on 
POST cloud:/api/v1/users/{user_id}/role_assignments
. Do not also assign 
viewer
.
"Show who has access to my organization" — 
GET cloud:/api/v1/organizations/{org_id}/members
and present each member's ID, email, and roles.
"配置我的云环境"——验证是否存在Cloud上下文，然后调用
GET cloud:/api/v1/organizations
验证。如果验证失败，引导用户生成组织级Cloud API密钥并注册为上下文（切勿在聊天中传输密钥），然后重新验证并返回获取到的组织信息。
"在欧盟区域配置云环境"——验证上下文后，调用
GET cloud:/api/v1/serverless/regions
列出区域，选择一个欧盟区域（例如
aws-eu-west-1
），并将其设为后续项目创建的默认区域。
"将
alice@example.com
添加到我的搜索项目中，赋予只读权限"——调用
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"
。密钥明文仅会显示一次——切勿在聊天中重复。
"赋予
bob@example.com
对我的搜索项目中
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、邮箱和角色。

Guidelines

指导原则

  • Validate the Cloud context first; discover the organization ID from 
    GET cloud:/api/v1/organizations
    — do not ask for it.
  • Never receive, echo, or log credentials in chat. Register the Cloud API key into a CLI context so the secret goes to the OS keychain; if the user offers to paste a key, decline and point them to context registration instead. A created key's secret is shown only once — tell the user to store it securely; never repeat it.
  • Default region is 
    gcp-us-central1
     — only change it when the user requests a different region.
  • Confirm destructive actions (remove member, revoke key) before executing.
  • Prefer predefined roles; reach for custom roles only when needed, and never stack a predefined Cloud role on the same project as a custom role.
  • API key hygiene: check existing keys before creating; set an 
    expiration
    matching the task lifetime; prompt the user to revoke keys no longer needed. Each organization supports up to 500 active keys; default expiration is 3 months. Invitations expire after 72 hours by default. Cloud API keys inherit roles at creation and cannot be updated — revoke and recreate to change roles.
  • For creating and operating projects, traffic filters, and deployments, see cloud-provisioning; for ES-level role management see elasticsearch-authz.
  • 首先验证Cloud上下文；通过
    GET cloud:/api/v1/organizations
    获取组织ID——切勿向用户索要。
  • 切勿在聊天中接收、回显或记录凭证。将Cloud API密钥注册到CLI上下文，确保密钥明文存储到系统密钥链；如果用户想要粘贴密钥，请拒绝并引导其进行上下文注册。创建的密钥明文仅显示一次——告知用户安全存储；切勿重复。
  • 默认区域为
    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>
HTTP API（简写形式）
elastic
CLI命令
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>