analytics-opensearch-expertise

Files (10)

• .skilleval.yaml
• CHANGELOG.md
• README.md
• SKILL.md
• benchmark.json · evals/
• eval_queries.json · evals/
• evals.json · evals/
• report.json · evals/
• trigger_report.json · evals/
• remediation-reference.md · references/

SKILL.md (first lines)

# OpenSearch Domain Health Assessment

## Overview

This skill performs a comprehensive, read-only health assessment of Amazon OpenSearch Service domains using AWS APIs available through the customer's local AWS profile. It produces a structured report with findings and actionable recommendations.

> **Scope:** CLI-agent compatible. No external packages, no IDE workspace, no human review gates.

## Trigger Keywords

`opensearch`, `opensearch health`, `domain health`, `cluster review`, `opensearch review`, `opensearch assessment`, `opensearch check`, `open search`, `opensearch performance`, `opensearch security`, `opensearch cost`

## Prerequisites

- AWS CLI profile configured with read-only access to the target account
- IAM permissions required:
  - `es:DescribeDomain`
  - `es:DescribeDomainHealth`
  - `es:GetCompatibleVersions`
  - `es:DescribeReservedInstances`
  - `es:ListDomainNames`
  - `cloudwatch:GetMetricData`

## Execution Flow

### Input

**Required:** Domain ARN (e.g., `arn:aws:es:us-west-2:123456789012:domain/my-domain`)

Parse the ARN to extract:
- **Region:** field 4 (e.g., `us-west-2`)
- **Account ID:** field 5 (e.g., `123456789012`)
- **Domain name:** after `domain/` in field 6

**Fallback / Target Resolution (apply these rules exactly — never silently substitute a target):**
1. **Exact match:** the ARN (or name + region) resolves via `DescribeDomain` → proceed with the assessment.
2. **No domain specified:** run `ListDomainNames` in the user's likely region(s) (cross-region scan if needed) and **present the discovered domains as options for the user to choose**. Do not pick one yourself unless exactly one domain exists in the entire account — state that you did so.
3. **Specified but NOT found:** search for candidates (`ListDomainNames` in the ARN's region, then other regions). Then **STOP and confirm — do NOT assess**:
   - Report clearly: "Domain {given} not found in {region}."
   - List the closest candidate(s) with their regions (e.g., name differs by a suffix, or same name in another region).
   - Ask the user to confirm which domain to assess. **Never run the assessment against a domain the user did not name without their explicit confirmation** — in accounts with similarly-named sibling domains (e.g., `prod-es-content` / `prod-es-users`), a silently substituted target produces a confident report about the wrong domain, which is worse than an error.
4. If the user provides only a domain name with no region, ask for the region (or apply rule 3's candidate search).

### Steps

```
1. Parse domain ARN → region, account, domain name
2. Resolve the target (Target Resolution rules above) — confirm with the user if not an exact match
3. Describe domain configuration (DescribeDomain)
4. Describe domain health (DescribeDomainHealth)
5. Pull CloudWatch metrics (last 24h)
6. Check upgrade eligibility (GetCompatibleVersions; ListVersions fallback)
7. Check reserved instance coverage (DescribeReservedInstances)
8. Analyze findings against thresholds
9. Load the Remediation Reference — read_skill_resource(skill_id='analytics-opensearch-expertise',
   path='references/remediation-reference.md') — MANDATORY before writing recommendations
10. Generate report with recommendations
```

## API Compatibility (DevOps Agent tooling)

The DevOps Agent AWS tool exposes the LEGACY Elasticsearch-compatible client. Call legacy
operation names FIRST; fall back to the modern names only if the legacy call fails:

| Purpose | Try first (legacy) | Modern equivalent |
|---|---|---|
| Domain config | `describe_elasticsearch_domain` | `describe_domain` |
| Version catalog | `list_elasticsearch_versions` | `list_versions` |
| Upgrade targets | `get_compatible_elasticsearch_versions` | `get_compatible_versions` |
| Reserved instances | `describe_reserved_elasticsearch_instances` | `describe_reserved_instances` |

- IAM note: the execution role's managed policy grants `es:Describe*` and `es:List*` —
  Describe/List operations succeed under either naming; `Get*` actions (BOTH GetCompatible
  variants) are typically denied. This is exactly why the 1.4 ListVersions fallback exists.
- `DescribeDomainHealth` has NO legacy equivalent. If it fails, do NOT skip checks 2.2/2.3 —
  use CloudWatch instead: `Shards.active` (Maximum) = active shards, `Shards.unassigned`
  (Maximum) = unassigned, TotalShards ≈ active + unassigned; `ClusterStatus.green/yellow/red`
  for 1.1/3.7. Never report the checks as SKIPPED when this fallback is available.
- All CloudWatch metrics in this skill: namespace `AWS/ES`, dimensions `DomainName` and
  `ClientId` (the account ID).

## Checks & Decision Logic

### Category 1: Cluster Health & Configuration

#### 1.1 Cluster Status
- **API:** `DescribeDomainHealth`
- **Field:** `ClusterHealth` (green | yellow | red)
- **Logic:**
  - GREEN → ✅ All primary and replica shards assigned
  - YELLOW → ⚠️ All primaries assigned, some replicas unassigned
  - RED → 🔴 Some primary shards unassigned — data loss risk

#### 1.2 Node Count & AZ Balance
- **API:** `DescribeDomain` → `ClusterConfig`
- **Fields:** `InstanceCount`, `ZoneAwarenessEnabled`, `AvailabilityZoneCount`
- **Logic:**
  - If `ZoneAwarenessEnabled == true`:
    - `InstanceCount % AvailabilityZoneCount != 0` → ⚠️ "Data node count ({count}) is not a multiple of AZ count ({az_count}). This causes uneven shard distribution across AZs, reducing fault tolerance."
    - Recommendation: "Adjust data node count to a multiple of {az_count} (e.g., {nearest_multiple})."
  - If `ZoneAwarenessEnabled == false` and `InstanceCount > 1`:
    - ⚠️ "Multi-AZ is not enabled despite having {count} data nodes. Single-AZ deployment risks full cluster unavailability during AZ failure."

#### 1.3 Dedicated Master Configuration
- **API:** `DescribeDomain` → `ClusterConfig`
- **Fields:** `DedicatedMasterEnabled`, `DedicatedMasterType`, `DedicatedMasterCount`
- **Logic:**
  - `DedicatedMasterEnabled == false` AND `InstanceCount >= 3` → ⚠️ "No dedicated master nodes. Clusters with 3+ data nodes should use dedicated masters for stability."
  - `DedicatedMasterCount == 2` → ⚠️ "Even number of master nodes ({count}) risks split-brain. Use 3 dedicated master nodes."
  - `DedicatedMasterCount < 3` → ⚠️ "Fewer than 3 master nodes reduces fault tolerance."

#### 1.4 Engine Version & Upgrade Eligibility
- **API:** `GetCompatibleVersions` with `DomainName`
- **Fallback (use when `GetCompatibleVersions` returns AccessDeniedException — do NOT skip):**
  call `ListVersions` and derive upgrade candidates using these two rules:
  1. Direct upgrade candidates = versions in `ListVersions` with the SAME major version as the
     domain and a LATER minor version (e.g., a 2.11 domain → every later 2.x in the region).
  2. Next-major path = via the LATEST available minor of the current major (compute it from
     `ListVersions`; never hard-code a specific version number).

From aws/tools-for-devops-agent, Apache-2.0.

More from aws/tools-for-devops-agent