elastic / elastic/cli

add auto ops support

Open
#393 0 comments 2 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
41
Forks
24
Avg merge
1d 3h
Merged PRs (30d)
56

Description

## Summary

Add AutoOps support to the Elastic CLI so users can query AutoOps **insights** for their Elastic Cloud resources from the command line.

## What the AutoOps API does

The AutoOps API (`v1.0.0`, OpenAPI 3.0.3) exposes AutoOps **insights** — issues/events that AutoOps detects for a monitored Elasticsearch resource (e.g. cluster yellow/red, capacity problems, ECH plan changes). Each insight carries a severity, a human-readable title and message, the rule that triggered it, lifecycle timestamps (open/closed/duration), tags, and an ordered list of recommended **actions** (often with a ready-to-run command). It's read-only — there are no mutating endpoints; the CLI would consume insights, not create or modify them.

Insights are scoped to a **resource**, identified by a `resourceType` + `resourceId`:

- `resourceType` is one of `deployments`, `projects`, or `clusters` (ECH deployment, Serverless project, or connected/self-managed cluster).
- `resourceId` is the corresponding ID, or the special value `_all` to return insights across all resources of that type in the organization.
- An optional `region` query parameter selects the Elastic Cloud region (default `us-east-1`).

### Endpoints

1. **Search insights** — `POST /api/v1/monitoring/{resourceType}/{resourceId}/insights/_search`
Returns a paginatable list of insights that were open at any point during a selected time window and match the given criteria. Request body supports:
- `from` / `to` — ISO8601 (or epoch) time window.
- `order` — `asc` / `desc` (default `desc`, newest first).
- `size` + `cursor` — cursor-based pagination.
- `rules` — filter by rule IDs (e.g. `status_yellow`, `status_red`); available rules depend on resource type.
- `severities` — `high` / `medium` / `low`.
- `tags` — e.g. `performance`, `capacity`; available tags depend on resource type.
- `include_closed` — by default only currently-open insights are returned; set `true` to also include closed insights that overlapped the window.
- `actionable_only` — only insights that have recommended actions.
- `include_context` — populate each insight's raw `autoops.context` (cluster/org/deployment IDs, nodes, indices).
Response includes `match_count`, `return_count`, a `cursor` for the next page, and the `insights` array.

2. **Get insight by ID** — `GET /api/v1/monitoring/{resourceType}/{resourceId}/insights/{insightId}`
Returns a single insight by its UUID. Supports the `include_context` query parameter.

### Insight shape (key fields)

- `event` — `id`, `start`, `end` (null while open), `duration` (ns), `updated`, `url`.
- `service` — `type` (always `elasticsearch`), cluster `id`, `name`.
- `rule` — `id`, `name`, `description` (impact explanation).
- `message` — the conditions that triggered the insight.
- `autoops` — `title`, `severity`, `actions[]` (each with `type`, `title`, `description`, and optional `command`), and optional `context`.
- `observer.name` is always `autoops`; `organization.id` and `tags` are also included.

### Auth & errors

- **Auth:** HTTP bearer token (JWT) via `Authorization: Bearer `.
- **Errors:** standard `{ ok: false, error: { message, type } }` envelope with `400` / `401` / `403` / `404` / `500`.

## API reference

AutoOps OpenAPI spec: https://backstage.elastic.dev/catalog/default/api/autoops-api/definition

## UX / command structure

A command structure will be proposed and is **TBD** for now.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.