cloud-provisioning

Files (5)

• SKILL.md
• api-reference.md · references/
• credentials-and-context.md · references/
• hosted-deployments.md · references/
• traffic-filters.md · references/

SKILL.md (first lines)

# Cloud Provisioning

Provision and run Elastic Cloud infrastructure through the Cloud API: **Serverless projects** (create and day-2
operations), **traffic filters** (network security for those projects), and **Elastic Cloud Hosted deployments**. For
configuring Cloud authentication and managing organization access, use the **cloud-onboarding** skill.

<!-- begin-partial: cloud-preamble -->

## Environment Configuration

This skill operates the Elastic Cloud control plane through the `elastic` CLI. If the
[`elastic` CLI](https://github.com/elastic/cli#configuration) is not installed, tell the user what it is needed for. Do
not guess credentials, bypass the CLI to call the HTTP API directly, or attempt other workarounds.

Control-plane operations authenticate against the Elastic Cloud API (organization scope), not a single stack deployment.
The `elastic` CLI reads this from its active context, which stores an Elastic Cloud API key in the OS keychain. If a
control-plane call fails with an authentication error, the context is missing or lacks a Cloud API key — instruct the
user to add one, and **never** ask the user to paste an API key into the chat:

> "Configure an Elastic Cloud context for the `elastic` CLI, then re-run. Generate an Organization-level key at
> [Elastic Cloud API keys](https://cloud.elastic.co/account/keys) and register it without echoing the secret in chat."

This skill references control-plane operations in HTTP-shorthand form with the `cloud:` prefix (e.g.,
`GET cloud:/api/v1/organizations`, `POST cloud:/api/v1/serverless/projects/elasticsearch`). The
[Operations](#operations) table at the end of this document maps each shorthand to the equivalent `elastic cloud`
command — always use the CLI rather than calling the HTTP API directly. Discover the organization ID from
`GET cloud:/api/v1/organizations`; do not ask the user for it.

<!-- end-partial: cloud-preamble -->

## Critical principles

- **Never display secrets in chat.** Do not echo, log, or repeat passwords or API keys in conversation or agent
  thinking. Persist credentials into a CLI context (OS keychain) and direct the user there.
- **Confirm before creating or destroying.** A project's or deployment's region is permanent; deletion is irreversible.
  Present the configuration and get explicit confirmation before creating, deleting, or resetting credentials.
- **Admin credentials are bootstrap-only.** The `admin` password returned on creation or reset exists solely to create a
  scoped API key. Never use admin credentials for ongoing Elasticsearch operations — mint a scoped key first.
- **Wait for readiness.** A new project or deployment starts `initializing`; wait until `initialized` before using it.
- **Two kinds of credentials.** The **Cloud context** (Cloud API key) authorizes control-plane operations here. A
  project's or deployment's **Elasticsearch API key** authorizes data-plane operations against its Elasticsearch
  endpoint — do not confuse the two. See [references/credentials-and-context.md](references/credentials-and-context.md).

---

## Serverless projects

### Project types

| Type            | Description                               | Included services                |
| --------------- | ----------------------------------------- | -------------------------------- |
| `elasticsearch` | Search, analytics, and vector workloads   | Elasticsearch, Kibana            |
| `observability` | Logs, metrics, traces, and APM            | Elasticsearch, Kibana, APM, OTLP |
| `security`      | SIEM, endpoint protection, cloud security | Elasticsearch, Kibana, OTLP      |

Map the user's request to the correct type; never silently default — infer from context and confirm, or ask when
ambiguous. "search"/"elasticsearch"/vector search → `elasticsearch`; "o11y"/logs/metrics/traces/APM → `observability`;
"SIEM"/detections/endpoint → `security`.

**Tiers and optimization.** Elasticsearch: set `optimized_for` to `general_purpose` (default) unless the user explicitly
requests `vector`. Observability: set `product_tier` to `complete` (default) or `logs_essentials`. Security: set
`product_types` tiers to `complete` (default) or `essentials` per product line (`security`, `cloud`, `endpoint`). See
[references/api-reference.md](references/api-reference.md) for the full request-body schema of each type.

### Process: create a serverless project

1. **Confirm the project type.** Infer it from the conversation and propose it, or ask the user to choose. Do not
   proceed on an assumed type.
2. **Confirm the configuration.** Present a summary — name (required; ask if missing), region (default
   `gcp-us-central1`), and the tier/optimization for the type — and get explicit confirmation. If the region is
   uncertain, list options with `GET cloud:/api/v1/serverless/regions` first; only regions with
   `project_creation_enabled: true` accept new projects. Region is permanent.
3. **Create the project.** Call `POST cloud:/api/v1/serverless/projects/{type}` with the confirmed body. Wait for the
   `initialized` phase and persist the returned credentials into a named CLI context (the password goes to the OS
   keychain, never to stdout or chat).
4. **Verify readiness.** If creation did not block until ready, poll
   `GET cloud:/api/v1/serverless/projects/{type}/{id}/status` until `phase` is `initialized`. The Elasticsearch and
   Kibana endpoints in the creation response are safe to share; the password is not.
5. **Bootstrap a scoped API key.** Using the project context, create a scoped Elasticsearch API key with only the
   privileges the user needs via `POST /_security/api_key` (the project's Elasticsearch endpoint), then rely on that key
   for all data-plane work. If the **elasticsearch-authn** skill is available, use it for full key lifecycle handling.

### Workflow: connect to an existing project

Use this when the user asks to query or manage a project not created in the current session. It applies to **Elastic
Cloud Serverless projects only** — if the cluster is self-managed or Elastic Cloud Hosted, use the Hosted deployment
workflow or skip. If unsure, ask: "Is your Elasticsearch instance an Elastic Cloud Serverless project?"

1. **Resolve the project.** Infer the type and list projects with `GET cloud:/api/v1/serverless/projects/{type}`. Match
   the user's reference (name or alias). If multiple or none match, present candidates and ask.
2. **Load endpoints and credentials.** Fetch the project with `GET cloud:/api/v1/serverless/projects/{type}/{id}` to get
   its Elasticsearch and Kibana endpoints, and select or create a CLI context bound to it.
3. **Acquire Elasticsearch credentials.** Verify any existing project API key with `GET /_security/_authenticate`
   (expect `"authentication_type": "api_key"`). If none works, confirm with the user, reset the admin bootstrap
   credentials with `POST cloud:/api/v1/serverless/projects/{type}/{id}/_reset-credentials`, use the admin password once
   to create a scoped key via `POST /_security/api_key`, persist it to the context, re-verify, and drop the admin
   credentials.

### Day-2: list, get, update, delete, resume

- **List** projects of a type: `GET cloud:/api/v1/serverless/projects/{type}`.
- **Get** one project: `GET cloud:/api/v1/serverless/projects/{type}/{id}`.
- **Update** (PATCH semantics — only supplied fields change): `PATCH cloud:/api/v1/serverless/projects/{type}/{id}`.
- **Reset credentials** (confirm first): `POST cloud:/api/v1/serverless/projects/{type}/{id}/_reset-credentials`.
- **Delete** (confirm first — permanent): `DELETE cloud:/api/v1/serverless/projects/{type}/{id}`.
- **Resume** a suspended project, then poll status until `initialized`:
  `POST cloud:/api/v1/serverless/projects/{type}/{id}/_resume`.

**Update fields and their risks.** Supported PATCH fields: `name`, `alias`, `metadata.tags`, `traffic_filters`, and —
for Elasticsearch — `search_lake.search_power` (28–3000) and `search_lake.boost_window` (1–180 days); for Security —
data-retention limits.

- **Alias changes rewrite every endpoint URL**, breaking existing clients. Warn before changing it.
- **Tags replace the whole tag set.** Read current tags with a `GET` first and include any the user wants to keep.
- **`search_power` drives cost.** Higher values increase VCU consumption. Warn and confirm before raising it (presets:
  28 on-demand, 100 performant, 250 high availability).
- **Reducing max retention permanently deletes data** older than the new limit. Warn and confirm before lowering it.

---

From elastic/agent-skills, Apache-2.0.

More from elastic/agent-skills