# Alicloud Elasticsearch Ops

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-buhaiqing-aliyun-skills-alicloud-elasticsearch-ops`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [buhaiqing](https://agentstack.voostack.com/s/buhaiqing)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [buhaiqing](https://github.com/buhaiqing)
- **Source:** https://github.com/buhaiqing/aliyun-skills/tree/main/alicloud-elasticsearch-ops

## Install

```sh
agentstack add skill-buhaiqing-aliyun-skills-alicloud-elasticsearch-ops
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> This skill follows the [Agent Skill OpenSpec](https://agentskills.io/specification).

# Alibaba Cloud Elasticsearch Operations Skill

## Overview

Alibaba Cloud Elasticsearch provides fully managed Elasticsearch clusters based on the open-source Elasticsearch, offering cloud-native search and analytics capabilities with enterprise features. This skill is an **operational runbook** for agents: explicit scope, credential rules, pre-flight checks, **SDK/API execution**, response validation, and failure recovery. **Do not use the web console as the primary agent execution path**.

> **UX Compliance:** This skill follows the [User Experience Specification](../alicloud-skill-generator/references/user-experience-spec.md). All operations include onboarding guidance, minimal prompts, smart defaults, clear feedback, and user-friendly error handling.

### CLI applicability (repository policy)

- **`cli_applicability: sdk-only`:** Official `aliyun` CLI does **not** expose Elasticsearch product. **SDK/API remains mandatory** for all operations. This skill uses JIT Go SDK for all Elasticsearch management operations.

## Five Core Standards (Quality Gates)

Every generated skill MUST satisfy these five standards. Use them as a design checklist:

| # | Standard | How This Skill Fulfills It |
|---|----------|---------------------------|
| 1 | **Clear Boundaries** | SHOULD/SHOULD NOT Use conditions with precise triggers and delegation rules |
| 2 | **Structured I/O** | Placeholder conventions (`{{env.*}}`, `{{user.*}}`, `{{output.*}}`) with type and source documented |
| 3 | **Explicit Actionable Steps** | Every operation: Pre-flight → Execute → Validate → Recover, with numbered imperative steps |
| 4 | **Complete Failure Strategies** | Error taxonomy table with ≥ 10 Elasticsearch-specific codes; HALT vs retry per error type |
| 5 | **Absolute Single Responsibility** | One product (Elasticsearch), one primary resource model (Instance); cross-product delegation to other skills |

### Well-Architected Framework Integration (卓越架构)

In addition to the Five Core Standards, every generated skill MUST map its operations to Alibaba Cloud's [Well-Architected Framework](https://help.aliyun.com/zh/product/2362200.html) five pillars:

| Pillar | Skill Integration | Reference |
|--------|-------------------|-----------|
| **安全 (Security)** | IAM permissions, credential masking, VPC endpoint, HTTPS | `references/well-architected-assessment.md` §2.1 |
| **稳定 (Stability)** | Snapshot backup, multi-zone, restart/upgrade runbook | `references/well-architected-assessment.md` §2.2 |
| **成本 (Cost)** | Instance spec selection, storage tiering | `references/well-architected-assessment.md` §2.3 |
| **效率 (Efficiency)** | Batch plugin operations, CI/CD integration | `references/well-architected-assessment.md` §2.4 |
| **性能 (Performance)** | Index template, ILM policy, cluster health metrics | `references/well-architected-assessment.md` §2.5 |

## Runtime Rules

| Area | Rule | Reference |
| --- | --- | --- |
| CLI path | **MANDATORY**: Always prefer the harness wrapper `./scripts/elasticsearch-harness-wrapper.sh` for all Elasticsearch operations to enable automated self-repair and dynamic optimization; fallback to native `aliyun` only when the wrapper is unavailable or `harness-lib.sh` is missing. | [SkillOpt](references/skillopt-integration.md) |
| Credentials | Read {{env.*}} from environment; never ask user to paste secrets | Integration |
| GCL | All write operations MUST pass GCL review before execution | GCL Rubric |

## Trigger & Scope (Agent-Readable)

### SHOULD Use This Skill When

- User mentions "Alibaba Cloud Elasticsearch" OR "阿里云ES" OR "ES实例" OR "Logstash" OR "搜索引擎"
- Task involves lifecycle operations on **Elasticsearch Instance** (create, describe, modify, delete, list, restart, upgrade)
- Task involves **Logstash Instance** management
- Task involves **Snapshot** backup and restore operations
- Task involves **Plugin** installation, configuration, or removal
- Task keywords: 集群健康, 索引管理, 快照备份, 日志分析, 全文检索, 性能调优, 版本升级, Kibana配置
- User asks to deploy, configure, troubleshoot, or monitor Elasticsearch **via API, SDK, or automation**

### SHOULD NOT Use This Skill When

- Task is purely billing / account management → delegate to: `alicloud-billing-ops` (when present)
- Task is RAM / permission model only → delegate to: `alicloud-ram-ops` (when present)
- Task is VPC network creation only → delegate to: `alicloud-vpc-ops` (VPC endpoint config is within scope)
- Task is ECS instance for Elasticsearch BEK deployment → delegate to: `alicloud-ecs-ops`
- User insists on **console-only** flows with no API → state limitation; do not invent undocumented HTTP steps

## Delegation Rules

| 能力 | 委托目标 | 说明 |
|------|----------|------|
| GCL 质量门禁 | `alicloud-gcl-runner-ops` | 对写操作执行前，委托 GCL 循环进行对抗性评审 |

## Variable Convention (Agent-Readable)

Structured placeholders reduce injection ambiguity and unsafe prompts:

| Placeholder | Meaning | Agent Action |
|-------------|---------|--------------|
| `{{env.ALIBABA_CLOUD_ACCESS_KEY_ID}}` | From runtime environment | NEVER ask the user; fail if unset |
| `{{env.ALIBABA_CLOUD_ACCESS_KEY_SECRET}}` | From runtime environment | NEVER ask the user; fail if unset |
| `{{env.ALIBABA_CLOUD_REGION_ID}}` | From runtime environment | Use documented default only if skill explicitly allows |
| `{{user.instance_id}}` | User-supplied Elasticsearch instance ID | Ask once; reuse |
| `{{user.instance_name}}` | User-supplied instance name | Ask once; reuse |
| `{{user.version}}` | Elasticsearch version (e.g., 7.10, 8.9) | Ask once; reuse |
| `{{user.node_spec}}` | Node specification (data node spec) | Ask once; reuse |
| `{{output.instance_id}}` | From last API JSON response | Parse from `Body.Result.instanceId` |

> **`{{env.*}}` MUST NOT** be collected from the user. **`{{user.*}}`** MUST be collected interactively when missing.

> **凭据安全（强制）：** 参考 [Credential Masking 规则](../alicloud-skill-generator/references/credential-masking.md)

## API and Response Conventions (Agent-Readable)

- **OpenAPI is canonical** for path, query, body fields, enums, and response shapes.
- **Endpoint:** `elasticsearch.aliyuncs.com` (public) or VPC endpoint
- **API Version:** `2017-06-13`
- **SDK Package:** `github.com/alibabacloud-go/elasticsearch-20170613/v6/client`

### Example Response Field Table

| Operation | JSON Path | Type | Description |
|-----------|-----------|------|-------------|
| CreateInstance | `$.body.result.instanceId` | string | New ES instance ID |
| DescribeInstance | `$.body.result.status` | string | Instance status (Normal, Activating, etc.) |
| ListInstance | `$.body.result.instances[].instanceId` | array | List of instance IDs |
| DescribeInstance | `$.body.result.esVersion` | string | Elasticsearch version |
| DescribeInstance | `$.body.result.nodeAmount` | int | Number of data nodes |

### Expected State Transitions

| Operation | Initial State | Target State | Poll Interval | Max Wait |
|-----------|---------------|--------------|---------------|----------|
| CreateInstance | — | `Normal` | 10s | 600s (10min) |
| RestartInstance | `Normal` | `Normal` | 10s | 300s |
| UpdateInstance | `Normal` | `Normal` | 10s | 300s |
| DeleteInstance | `Normal` | absent | 10s | 300s |

## Quick Start

### What This Skill Does
This skill enables you to deploy, configure, troubleshoot, and monitor Elasticsearch instances on Alibaba Cloud using JIT Go SDK (CLI does not support Elasticsearch).

### Prerequisites
- [ ] Go runtime installed (1.21+) or JIT download capability
- [ ] Credentials configured: `ALIBABA_CLOUD_ACCESS_KEY_ID`, `ALIBABA_CLOUD_ACCESS_KEY_SECRET`
- [ ] Region set: `ALIBABA_CLOUD_REGION_ID`

### Verify Setup
```bash
# Check Go runtime
go version

# Quick SDK test (in /tmp/aliyun-sdk-workspace)
mkdir -p /tmp/aliyun-sdk-workspace && cd /tmp/aliyun-sdk-workspace
go mod init es-test
go get github.com/alibabacloud-go/elasticsearch-20170613/v6/client
go get github.com/alibabacloud-go/darabonba-openapi/v2/client
go get github.com/alibabacloud-go/tea
```

### Your First Command
```go
// List Elasticsearch instances
package main

import (
    "fmt"
    "os"
    openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
    "github.com/alibabacloud-go/tea/tea"
    elasticsearch "github.com/alibabacloud-go/elasticsearch-20170613/v6/client"
)

func main() {
    config := &openapi.Config{
        AccessKeyId:     tea.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")),
        AccessKeySecret: tea.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")),
        Endpoint:        tea.String("elasticsearch.aliyuncs.com"),
    }
    client, _ := elasticsearch.NewClient(config)
    req := &elasticsearch.ListInstanceRequest{
        RegionId: tea.String(os.Getenv("ALIBABA_CLOUD_REGION_ID")),
    }
    resp, _ := client.ListInstance(req)
    fmt.Println(tea.ToString(resp.Body))
}
```

### Next Steps
- [Core Concepts](references/core-concepts.md) — Understand Elasticsearch architecture
- [Common Operations](#execution-flows) — Create, manage, and delete instances
- [Troubleshooting](references/troubleshooting.md) — Fix common issues

## Capabilities at a Glance

| Operation | Description | Complexity | Risk Level |
|-----------|-------------|------------|------------|
| CreateInstance | Create a new Elasticsearch cluster | High | Low |
| DescribeInstance | View instance details | Low | None |
| ListInstance | List all Elasticsearch instances | Low | None |
| UpdateInstance | Modify instance configuration | Medium | Medium |
| RestartInstance | Restart Elasticsearch cluster | Medium | Medium |
| DeleteInstance | Remove an Elasticsearch instance | Low | **High** — irreversible |
| CreateSnapshot | Create backup snapshot | Medium | Low |
| RestoreSnapshot | Restore from snapshot | Medium | Medium |
| UpgradeEngineVersion | Upgrade Elasticsearch version | High | High |

## Changelog

| Version | Date | Changes |
|---------|------|---------|
| 2.1.0 | 2026-05-17 | AIOps optimization: Added proactive-inspection.md (8 multi-metric anomaly patterns), alarm-storm-handling.md, diagnostic-report-schema.md. Enhanced monitoring.md (Section 8), troubleshooting.md (Section 6 multi-round self-reflection), integration.md (Section 6 cross-skill diagnosis). Added observability.md, prompts.md. All P0/P1 items completed. |
| 2.0.0 | 2026-05-17 | Well-Architected Framework optimization: Security (92%), Stability (88%). Added security-enhancement.md, stability-enhancement.md, knowledge-base.md, batch-operations.md. P0 gaps resolved. |
| 1.0.0 | 2026-05-17 | Initial Elasticsearch SDK-only skill based on elasticsearch-20170613 v6.3.0 |

> **EXECUTION MANDATORY RULE**: 所有 control-plane CLI 执行步骤 **必须** 通过 SkillOpt wrapper `./scripts/elasticsearch-skillopt-wrapper.sh` 运行。
> 以下所有代码块中的 `aliyun elasticsearch ...` 命令在执行时应替换为 `./scripts/elasticsearch-skillopt-wrapper.sh  ...`。
> 仅在 wrapper 脚本不可用或 `skillopt-lib.sh` 缺失时，才退回到原生 `aliyun elasticsearch` CLI 调用。
> 参考 `## Runtime Rules` 中的 CLI path 规则。

## Execution Flows (Agent-Readable)

> **MANDATORY**: All CLI/SDK examples should be executed via the SkillOpt wrapper `./scripts/elasticsearch-skillopt-wrapper.sh`; fallback to native `aliyun` CLI or direct SDK only when the wrapper is unavailable.

Every operation: **Pre-flight → Execute (SDK) → Validate → Recover**. Do not skip phases.

### Operation: Create Elasticsearch Instance

#### Pre-flight Checks

| Check | Method | Expected | On Failure |
|-------|--------|----------|------------|
| SDK / deps | Import elasticsearch client; version v6.3.0+ | No import error | Document SDK install |
| Go runtime | `go version` ≥ 1.21 | Exit code 0 | JIT download Go 1.24 |
| Credentials | Env vars set; construct credential | Non-empty keys | HALT; user configures env |
| Region | Check supported regions via DescribeRegions | Region supported | Suggest valid region |
| Quota | Check instance quota (user quota API) | Sufficient quota | HALT; user raises quota |
| VPC exists | Validate VPC and VSwitch IDs | Found in region | HALT; create via vpc-ops |

#### Execution — JIT Go SDK

**JIT Go SDK fallback:** 参见 [API & SDK Usage](references/api-sdk-usage.md)

Execute:
```bash
# In /tmp/aliyun-sdk-workspace
go mod init es-create
go get github.com/alibabacloud-go/elasticsearch-20170613/v6/client
go get github.com/alibabacloud-go/darabonba-openapi/v2/client
go get github.com/alibabacloud-go/tea
go run ./main.go
```

#### Post-execution Validation

1. Capture `{{output.instance_id}}` from response: `Body.Result.InstanceId`
2. Poll DescribeInstance until terminal success state:

```go
// Polling loop
for i := 0; i  **Stability Pillar:** Following Alibaba Cloud Well-Architected Framework §面向风险的应急快恢, backup operations are mandatory before destructive changes.

#### Pre-flight Checks

| Check | Method | Expected | On Failure |
|-------|--------|----------|------------|
| Instance exists | DescribeInstance | Found and `Normal` | HALT |
| Snapshot quota | Check snapshot limits | Sufficient | HALT; user raises quota |

#### Execution — JIT Go SDK

**JIT Go SDK fallback:** 参见 [API & SDK Usage](references/api-sdk-usage.md)

#### Post-execution Validation

Poll snapshot status until `Success` (check via DescribeSnapshot or ListSnapshots)

### Operation: Upgrade Engine Version

#### Pre-flight Checks

| Check | Method | Expected | On Failure |
|-------|--------|----------|------------|
| Instance exists | DescribeInstance | Found and `Normal` | HALT |
| Target version supported | GetRegionConfiguration | Version available | HALT; unsupported version |
| Backup exists | ListSnapshots | At least one snapshot | WARN; suggest backup first |

#### Execution — JIT Go SDK

**JIT Go SDK fallback:** 参见 [API & SDK Usage](references/api-sdk-usage.md)

#### Post-execution Validation

Poll until upgrade completes (status transitions through upgrade phases)

## Prerequisites

1. **Bootstrap Go runtime** (JIT SDK execution path):

   ```bash
   # Check if Go exists
   if ! command -v go &> /dev/null; then
       # JIT download Go 1.24 (auto-detects OS and architecture)
       OS=$(uname -s | tr '[:upper:]' '[:lower:]')
       ARCH=$(uname -m)
       [ "$ARCH" = "x86_64" ] && ARCH="amd64"
       [ "$ARCH" = "aarch64" ] && ARCH="arm64"
       
       mkdir -p /tmp/go-runtime
       curl -fsSL "https://go.dev/dl/go1.24.0.${OS}-${ARCH}.tar.gz" | tar -xz -C /tmp/go-runtime
       
       export PATH="/tmp/go-runtime/go/bin:$PATH"
       export GOPATH="/tmp/go-workspace"
       export GOCACHE="/tmp/go-cache"
       export GOMODCACHE="/tmp/go-modcache"
       export GOPROXY="https://goproxy.cn,direct"
   fi
   
   go version
   ```

2. **Configure Credentials** — Environment variables (recommended):

   ```bash
   export ALIBABA_CLOUD_ACCESS_KEY_ID="{{env.ALIBABA_CLOUD_ACCESS_KEY_ID}}"
   export ALIBABA_CLOUD_ACCESS_KEY_SECRET="{{env.ALIBABA_CLOUD_ACCESS_KEY_SECRET}}"
   export ALIBABA_CLOUD_REGION_ID="{{env.ALIBABA_CLOUD_REGION_ID}}"
   ```
   > **IMPORTANT:** When outputting the above commands to console or logs, the agent MUST replace `{{env.ALIBABA_CLOUD_ACCESS_KEY_SECRET}}` with the masking format `****` instead of the actual secret value (i.e., display as `export ALIBABA_CLOUD_ACCESS_KEY_SECRET="****"`). Never resolve `{{env.ALIBABA_CLOUD_ACCESS_KEY_SECRET}}` to its actual value in any visible output.

3. **Initialize SDK Workspace**:

   ```bash
   mkdir -p /tmp/aliyun-sdk-workspace
   cd /tmp/aliyun-sdk-workspace
   go mod init es-sdk-script
   
   # Core dependencies
   go get github.com/alibabacloud-go/darabonba-openapi/v2/client
   go get github.com/alibabacloud-go/tea
   go get github.com/alibabacloud-go/tea-utils/v2/service
   
   # Elasticsearch SDK
   go get github.com/alibabacloud-go/elasticsearch-20170613/v6/client
   ```

## Reference Directory

- [Core Concepts](references/core-concepts.md)
- [API & SDK Usage](references/api-sdk-usage.md)
- [Troubleshooting Guide](references/troubleshooting.m

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [buhaiqing](https://github.com/buhaiqing)
- **Source:** [buhaiqing/aliyun-skills](https://github.com/buhaiqing/aliyun-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-buhaiqing-aliyun-skills-alicloud-elasticsearch-ops
- Seller: https://agentstack.voostack.com/s/buhaiqing
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.