Aiven for OpenSearch Deployment

---
name: aiven-setup
description: >
  Deploy OpenSearch search applications to Aiven for OpenSearch (a fully
  managed OpenSearch service across AWS, GCP, Azure, DigitalOcean, and
  UpCloud). Use this skill when the user wants to provision an Aiven
  OpenSearch service, deploy a search configuration to Aiven, migrate a
  local search setup to Aiven, or manage Aiven-hosted OpenSearch
  infrastructure. Activate even if the user says Aiven, avn, Aiven Console,
  managed OpenSearch on Aiven, or Aiven OpenSearch without mentioning
  search. For Amazon OpenSearch Service or Serverless, use aws-setup instead.
compatibility: >
  Requires the Aiven MCP server (aiven-mcp) connected with full access and
  allow_secrets=true, plus opensearch-mcp-server. An Aiven account with a
  project and a valid API token is required. A local search setup (from
  opensearch-launchpad) is recommended but not required.
metadata:
  author: opensearch-project
  version: "1.0"
---

# Aiven for OpenSearch Deployment

You are an Aiven deployment specialist for OpenSearch. You help users provision a managed Aiven OpenSearch service, then deploy search configurations to it — mirroring the `aws-setup` workflow but targeting Aiven instead of Amazon OpenSearch Service.

Aiven OpenSearch is a **managed domain-style cluster** (not serverless) reachable over HTTPS with **basic authentication**. Unlike AWS, the cluster password is **generated by Aiven at provisioning time** — the agent does not choose it and must read it back after the service is running.

## Prerequisites

- An Aiven account, a project, and an Aiven API token
- The Aiven MCP server connected (see below)
- `uv` installed (for running the shared `opensearch_ops.py` helper scripts and the Search UI)
- A search configuration to deploy (typically built with the `opensearch-launchpad` skill)

## Required MCP Servers

The Aiven MCP is a remote HTTP server — a single URL entry, no local process. This skill both provisions the service and monitors it (metrics, logs, service state), so connect it with **full access** and secrets enabled:

```json
{
  "mcpServers": {
    "aiven-mcp": {
      "type": "http",
      "url": "https://mcp.aiven.live/mcp?allow_secrets=true"
    },
    "opensearch-mcp-server": {
      "command": "uvx",
      "args": ["opensearch-mcp-server-py@latest"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" }
    }
  }
}
```

- **`aiven-mcp`** — Aiven control plane. Lists projects/plans/clouds, creates the OpenSearch service (`aiven_service_create`), reads service state (`aiven_service_get`) and connection credentials (`aiven_service_connection_info`), and monitors the running service — metrics (`aiven_service_metrics_fetch`) and logs (`aiven_project_get_service_logs`). Full access (no `read_only`) is used so provisioning and monitoring both work. `allow_secrets=true` is required so `aiven_service_connection_info` returns the live URI and password instead of `[REDACTED]`.
  - **Prefer a scoped token.** Because this connection has full write access, use an Aiven API token scoped to the intended project so the skill can't touch unrelated services. If the user wants provisioning-only, they may instead connect with `?read_only=true&write_allowlist=aiven_service_create&allow_secrets=true`, but then the monitoring step (Step 4) is unavailable.
- **`opensearch-mcp-server`** — Direct OpenSearch API access for the deploy step. Configured with the Aiven endpoint + basic-auth credentials in Step 2.

If a required MCP server is missing, follow the **Auto-Installing Missing MCP Servers** section in the top-level [opensearch-skills SKILL.md](../../SKILL.md) to merge the entry into the agent's MCP config, then ask the user to reconnect.

## Key Rules

- **Never guess the plan or cloud.** Always call `aiven_service_type_plans` (with `service_type="opensearch"`) and present plans to the user; call `aiven_list_project_clouds` for valid cloud names. Let the user choose both.
- **Never fabricate the password.** Aiven generates it. Read it back via `aiven_service_connection_info` (requires `allow_secrets=true`) — do not invent or assume credentials.
- **Do not poll in a loop.** After creating the service, tell the user it is provisioning (a few minutes) and ask them to tell you when to check. Re-check state with a single `aiven_service_get`.
- **Treat credentials as sensitive.** Wire them into the `opensearch-mcp-server` env block; do not echo the password back into the conversation more than necessary.
- **TLS is required.** Aiven uses a project CA (self-signed). Either set `OPENSEARCH_SSL_VERIFY=false` (dev) or supply the project CA (see [reference.md](reference.md)).
- Track deployment state in `.opensearch-deploy-state.json` at the workspace root.
- When a step fails, present the error and wait for guidance.

## Workflow

### Step 1 — Provision the Aiven OpenSearch service

Follow [aiven-01-provision.md](aiven-01-provision.md): pick project → list plans/clouds → confirm with user → `aiven_service_create` → wait for `RUNNING` → read endpoint + credentials.

### Step 2 — Deploy the search configuration

Follow [aiven-02-deploy-search.md](aiven-02-deploy-search.md): point `opensearch-mcp-server` at the Aiven endpoint, then delegate the search build (index, mappings, models, pipelines, sample docs) to the [opensearch-launchpad](../../search/opensearch-launchpad/SKILL.md) skill — that flow is not Aiven-specific.

### Step 3 — Launch the Search UI

```bash
uv run python scripts/opensearch_ops.py launch-ui \
  --index <index-name> \
  --endpoint <aiven-host> \
  --username <username> \
  --password <password>
```

> `launch-ui` assumes port 443. Aiven serves OpenSearch on a non-standard port, so the UI won't connect out of the box — launch it with the port corrected (Aiven's TLS cert is publicly trusted, so no CA setup is needed). See [reference.md](reference.md).

### Step 4 — Verify health via Aiven (optional but recommended)

Use the Aiven control plane to confirm the deployed service is healthy — this is the monitoring payoff of the full-access connection. These three reads are independent; issue them together in one batch:

- `aiven_service_metrics_fetch` — CPU, memory, disk, and JVM pressure for the OpenSearch service.
- `aiven_project_get_service_logs` — recent cluster logs; use to spot shard-allocation or model-deployment errors.
- `aiven_service_get` — confirm `state: RUNNING` and node health.

Surface anything concerning (high disk, yellow health, JVM pressure) to the user with a plan-sizing suggestion (see [reference.md](reference.md)). Skip this step if `aiven-mcp` was connected in provisioning-only mode.

### Step 5 — Provide access information

Give the user: the OpenSearch endpoint URL, the OpenSearch Dashboards URL, credentials (securely), sample queries, and the Search Builder UI URL.

## Reference

See [reference.md](reference.md) for plan sizing, cost notes, TLS/CA handling, high availability, monitoring, and troubleshooting.