cloud-manage-project

What this skill does

# Manage Serverless Project

Perform day-2 operations on Elastic Cloud Serverless projects using the Serverless REST API.

## Prerequisites and permissions

- Ensure `EC_API_KEY` is configured. If not, run `cloud-setup` skill first.
- Updating project settings requires **Admin** or **Editor** role on the target project.
- This skill does not perform a separate role pre-check. Attempt the requested operation and let the API enforce
  authorization. If the API returns an authorization error (for example, `403 Forbidden`), stop and ask the user to
  verify the provided API key permissions.

### Manual setup fallback (when `cloud-setup` is unavailable)

If this skill is installed standalone and `cloud-setup` is not available, instruct the user to configure Cloud
environment variables manually before running commands. Never ask the user to paste API keys in chat.

| Variable      | Required | Description                                                    |
| ------------- | -------- | -------------------------------------------------------------- |
| `EC_API_KEY`  | Yes      | Elastic Cloud API key used for project management operations.  |
| `EC_BASE_URL` | No       | Cloud API base URL (default: `https://api.elastic-cloud.com`). |

> **Note:** If `EC_API_KEY` is missing, or the user does not have a Cloud API key yet, direct the user to generate one
> at [Elastic Cloud API keys](https://cloud.elastic.co/account/keys), then configure it locally using the steps below.

Preferred method (agent-friendly): create a `.env` file in the project root:

```bash
EC_API_KEY=your-api-key
EC_BASE_URL=https://api.elastic-cloud.com
```

All `cloud/*` scripts auto-load `.env` from the working directory.

Alternative: export directly in the terminal:

```bash
export EC_API_KEY="<your-cloud-api-key>"
export EC_BASE_URL="https://api.elastic-cloud.com"
```

Terminal exports may not be visible to sandboxed agents running in separate shell sessions, so prefer `.env` when using
an agent.

## Critical principles

- **Never display secrets in chat.** Do not echo, log, or repeat API keys, passwords, or credentials in conversation
  messages or agent thinking. Direct the user to the `.elastic-credentials` file instead. The admin password must
  **never** appear in chat history, thinking traces, or agent output — even when using it to create an API key, pass it
  directly via shell variable substitution without echoing.
- **Confirm before destructive actions.** Always ask the user to confirm before deleting a project or resetting
  credentials.
- **Credentials are saved to file.** After a credential reset, the script writes the new password to
  `.elastic-credentials` automatically. The password is redacted from stdout. Never read or display the contents of
  `.elastic-credentials` in chat.
- **Admin credentials are for API key creation only.** The `admin` password saved by `create-project` and
  `reset-credentials` exists solely to bootstrap a scoped API key — never use it for direct Elasticsearch operations.
  `load-credentials` excludes admin credentials by default; pass `--include-admin` only for key creation.
- **Always prefer API keys.** Do not proceed with Elasticsearch operations until an `ELASTICSEARCH_API_KEY` is set. If
  only admin credentials are available, create a scoped API key via `elasticsearch-authn`. If that skill is not
  installed, ask the user to install it or create the key manually in **Kibana > Stack Management > API keys**.
- **Identify projects by type and ID.** Every command requires both `--type` and `--id` (except `list`, which only needs
  `--type`).
- **Two kinds of API keys.** This skill uses the **Cloud API key** (`EC_API_KEY`) for project management operations
  (list, get, update, delete). Elasticsearch operations require a separate **Elasticsearch API key**
  (`ELASTICSEARCH_API_KEY`) that authenticates against the project's Elasticsearch endpoint. Do not confuse the two.

## Workflow: Connect to an existing project

Use this workflow when the user asks to query or manage a project the agent did not create in the current session. It
resolves the project, saves its endpoints, and ensures working Elasticsearch credentials before proceeding.

This workflow only applies to **Elastic Cloud Serverless projects**. If the user's Elasticsearch instance is
self-managed or Elastic Cloud Hosted, this skill does not apply — skip it and proceed with the relevant skill directly.
If unsure, ask the user: **"Is your Elasticsearch instance an Elastic Cloud Serverless project?"**

```text
Connect to Existing Project:
- [ ] Step 1: Resolve the project
- [ ] Step 2: Get project details and load credentials
- [ ] Step 3: Acquire Elasticsearch credentials
```

### Step 1: Resolve the project

Ask the user for the **project name** if not already provided. Infer the project type from the user's request:

| User says                                                   | `--type`        |
| ----------------------------------------------------------- | --------------- |
| "search project", "elasticsearch project", vector search    | `elasticsearch` |
| "observability project", "o11y", logs, metrics, traces, APM | `observability` |
| "security project", "SIEM", detections, endpoint protection | `security`      |

If the type is ambiguous, list all three types to find the project.

```bash
python3 skills/cloud/manage-project/scripts/manage-project.py list \
  --type elasticsearch
```

Match the user's reference (name, partial name, or alias) against the list results. If multiple projects match or none
match, present the candidates and ask the user to pick.

### Step 2: Get project details and load credentials

Once a single project is identified, check whether `.elastic-credentials` already has entries for this project (from a
previous session). If so, load them with `load-credentials`:

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

This sets all saved environment variables for the project — endpoints and any previously created Elasticsearch API keys
— in a single command. Admin credentials (`ELASTICSEARCH_USERNAME`/`ELASTICSEARCH_PASSWORD`) are intentionally excluded.
Later sections for the same project automatically overwrite earlier values, so the most recent credentials always win.

If `load-credentials` reports no matching entries, fetch the project details from the API and export endpoints manually:

```bash
python3 skills/cloud/manage-project/scripts/manage-project.py get \
  --type elasticsearch \
  --id <project-id>
```

Then export the endpoint URLs from the response. The available endpoints depend on the project type.

**All project types:**

```bash
export ELASTICSEARCH_URL="<elasticsearch_endpoint>"
export KIBANA_URL="<kibana_endpoint>"
```

**Observability projects** (additional):

```bash
export APM_URL="<apm_endpoint>"
export INGEST_URL="<ingest_endpoint>"
```

**Security projects** (additional):

```bash
export INGEST_URL="<ingest_endpoint>"
```

### Step 3: Acquire Elasticsearch credentials

If `load-credentials` set `ELASTICSEARCH_API_KEY`, verify the credentials work:

```bash
curl -H "Authorization: ApiKey ${ELASTICSEARCH_API_KEY}" \
  "${ELASTICSEARCH_URL}/_security/_authenticate"
```

Confirm the response contains a valid `username` and `"authentication_type": "api_key"` before proceeding. If
verification succeeds, skip the rest of this step.

If no credentials were loaded, or verification fails, ask the user: **"Do you have an existing Elasticsearch API key for
this project?"**

**If yes** — have the user add it to `.elastic-credentials` (see "Credential file format"). Do not accept keys in chat.
Reload and verify:

```bash
eval $(python3 skills/cloud/manage-project/scripts/manage-project.py load-credentials \
  --name "<project-name>")
curl -H "Authorization: ApiKey ${ELASTICSEARCH_API_KEY}" \
  "${ELASTICSEARCH_URL}/_security/_authenticate"
```

**If no** — follow thi