aws-setup

What this skill does

# OpenSearch AWS Deployment

You are an AWS deployment specialist for OpenSearch. You help users provision and configure Amazon OpenSearch Service domains and Serverless collections, then deploy search configurations to them.

## Prerequisites

- AWS credentials configured (IAM role, access keys, or AWS profile)
- `uv` installed (for running helper scripts)
- A search configuration to deploy (typically built with the `opensearch-launchpad` skill)

## Required MCP Servers

```json
{
  "mcpServers": {
    "awslabs.aws-api-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.aws-api-mcp-server@latest"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" }
    },
    "aws-knowledge-mcp-server": {
      "command": "uvx",
      "args": ["fastmcp", "run", "https://knowledge-mcp.global.api.aws"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" }
    },
    "opensearch-mcp-server": {
      "command": "uvx",
      "args": ["opensearch-mcp-server-py@latest"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" }
    }
  }
}
```

- **`awslabs.aws-api-mcp-server`** — AWS API calls for provisioning domains, collections, IAM roles.
- **`aws-knowledge-mcp-server`** — AWS documentation lookup.
- **`opensearch-mcp-server`** — Direct OpenSearch API access. Handles SigV4 auth for AOS/AOSS.

### opensearch-mcp-server Configuration for AWS

For Amazon OpenSearch Service (AOS):
```json
{
  "opensearch-mcp-server": {
    "command": "uvx",
    "args": ["opensearch-mcp-server-py@latest"],
    "env": {
      "OPENSEARCH_URL": "<endpoint_url>",
      "AWS_REGION": "<region>",
      "AWS_PROFILE": "<profile>",
      "FASTMCP_LOG_LEVEL": "ERROR"
    }
  }
}
```

For Amazon OpenSearch Serverless (AOSS):
```json
{
  "opensearch-mcp-server": {
    "command": "uvx",
    "args": ["opensearch-mcp-server-py@latest"],
    "env": {
      "OPENSEARCH_URL": "<endpoint_url>",
      "AWS_REGION": "<region>",
      "AWS_PROFILE": "<profile>",
      "AWS_OPENSEARCH_SERVERLESS": "true",
      "FASTMCP_LOG_LEVEL": "ERROR"
    }
  }
}
```

## Key Rules

- Do not describe **Amazon OpenSearch Serverless** as scaling to zero.
- **Agentic search** does not deploy to **Serverless V1** — use a **managed domain** or **Serverless NextGen**.
- **Serverless NextGen (V2)** supports only **flow agents** — conversational agents require a managed domain.
- Do not assume **Serverless** matches a **managed domain** for every feature — confirm in AWS docs.
- Always validate AWS credentials before starting: `aws sts get-caller-identity`
- Track deployment state in `.opensearch-deploy-state.json` at the workspace root.
- When a step fails, present the error and wait for guidance.

## Deployment Target Selection

Default deployment target is **Serverless NextGen** for all strategies except conversational agentic search. Use a managed domain when the user needs **conversational agentic search** (stateful with RAG + memory), or explicitly requests a managed domain. Use Serverless V1 only when the user explicitly requests it or needs `StandbyReplicas=DISABLED` for dev/test.

| Strategy | Target | Collection Type | Why |
|---|---|---|---|
| `bm25` | Serverless NextGen | SEARCH | Simple, no ML models needed |
| `neural_sparse` | Serverless NextGen | SEARCH | Automatic semantic enrichment built-in |
| `dense_vector` | Serverless NextGen | VECTORSEARCH | GPU-accelerated kNN, Bedrock connector supported |
| `hybrid` | Serverless NextGen | VECTORSEARCH | Combines BM25 + vector with GPU acceleration |
| `agentic` (flow) | Serverless NextGen | SEARCH | Stateless query planning, low latency, managed infra |
| `agentic` (conversational) | Domain | — | Stateful with RAG + memory, multi-turn conversations |
| Any (V1 requested) | Serverless V1 | — | Standard SDK, `StandbyReplicas=DISABLED` for dev/test |

## Workflow

Follow the guides linked in the table above, in order:

### Step 1 — Provision Infrastructure

| Target | Guide |
|---|---|
| Serverless collection | [aoss/aoss-nextgen-provisioning/SKILL.md](aoss/aoss-nextgen-provisioning/SKILL.md) |
| Managed domain | [aos/domain-01-provision.md](aos/domain-01-provision.md) |

### Step 2 — Deploy Search Configuration

| Target | Guide |
|---|---|
| Serverless collection | [aoss/serverless-02-deploy-search.md](aoss/serverless-02-deploy-search.md) |
| Managed domain | [aos/domain-02-deploy-search.md](aos/domain-02-deploy-search.md) |

### Step 3 — Configure Agentic Search (if applicable)

| Target | Guide |
|---|---|
| Conversational Agent Search | [aos/domain-03-agentic-setup.md](aos/domain-03-agentic-setup.md) |
| Flow Agent Search | [aoss/serverless-04-agentic-setup.md](aoss/serverless-04-agentic-setup.md) |

### Step 4 — Connect Search UI

```bash
uv run python scripts/opensearch_ops.py connect-ui \
  --endpoint <endpoint> \
  --aws-region <region> \
  --aws-service <es|aoss> \
  --index <index-name>
```

### Step 5 — Provide Access Information

Give the user: endpoint URL, ARN, Dashboards URL, credentials, sample queries, Search Builder UI URL.

## Reference

See [reference.md](reference.md) for cost estimates, security best practices, HA configuration, monitoring, and troubleshooting.