Cloud Onboarding

Cloud Onboarding

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.

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.

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

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.

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.

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):

See references/api-reference.md for the full role_assignments schema (organization, deployment, and project scopes) and the complete Security role list.

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.

Custom roles (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.