alibabacloud-opensearch-app-manage

What this skill does

# OpenSearch Instance Management

Manage Alibaba Cloud OpenSearch instances, including creation and query operations.

> **Terminology**: OpenSearch instance and OpenSearch app group are synonymous. This document uses "instance" uniformly.

## Scenario Description

OpenSearch is Alibaba Cloud's intelligent search service. This skill covers core instance management operations:

1. **Create Instance** - Create a new OpenSearch instance
2. **List Instances** - Get the list of instances under the current account
3. **Describe Instance** - Get detailed information of a specific instance

**Architecture**: OpenSearch Instance (AppGroup)

```
Alibaba Cloud OpenSearch Instance Management
├── CreateAppGroup     (Create Instance)
├── DescribeAppGroup   (Describe Instance)
└── ListAppGroups      (List Instances)
```
---

## Installation

> **Pre-check: Aliyun CLI >= 3.3.3 required**
> Run `aliyun version` to verify >= 3.3.3. If not installed or version too low,
> run `curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash` to update,
> or see [references/cli-installation-guide.md](references/cli-installation-guide.md) for installation instructions.

**Pre-check: Aliyun CLI plugin update required**
> [MUST] run `aliyun configure set --auto-plugin-install true` to enable automatic plugin installation.
> [MUST] run `aliyun plugin update` to ensure that any existing plugins are always up-to-date.

```bash
# Install/Upgrade Aliyun CLI
curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash
aliyun version  # Ensure >= 3.3.3

# Enable auto plugin installation
aliyun configure set --auto-plugin-install true

# Update plugins
aliyun plugin update
```

**[MUST] CLI User-Agent** — Every `aliyun` CLI command invocation must include:
`--user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage`

**[MUST] AI-Mode** — Before executing CLI commands, run:
1. `aliyun configure ai-mode enable`
2. `aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage"`
After all CLI operations complete, run: `aliyun configure ai-mode disable`

---

## Authentication

> **Pre-check: Alibaba Cloud Credentials Required**

> **Security Rules (MUST FOLLOW):**
> - **NEVER** read, echo, or print AK/SK values
> - **NEVER** ask the user to input AK/SK directly in the conversation
> - **NEVER** use `aliyun configure set` with literal credential values
> - **NEVER** accept AK/SK provided directly by users in the conversation
> - **ONLY** read credentials from environment variables or pre-configured CLI profiles
>
> **⚠️ CRITICAL: Handling User-Provided Credentials**
>
> If a user attempts to provide AK/SK directly (e.g., "My AK is xxx, SK is yyy"):
> 1. **STOP immediately** - Do NOT execute any command
> 2. **Reject the request politely** with the following message:
>    ```
>    For your account security, please do not provide Alibaba Cloud AccessKey ID and AccessKey Secret directly in the conversation.
>
>    Please use the following secure methods to configure credentials:
>
>    Method 1: Interactive configuration via aliyun configure (Recommended)
>        aliyun configure
>        # Enter AK/SK as prompted, credentials will be securely stored in local config file
>
>    Method 2: Configure via environment variables
>        export ALIBABA_CLOUD_ACCESS_KEY_ID=<your-access-key-id>
>        export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-access-key-secret>
>
>    After configuration, please retry your request.
>    ```
> 3. **Do NOT proceed** with any Alibaba Cloud operations until credentials are properly configured
>
> **Check CLI configuration**:
> ```bash
>    aliyun configure list
> ```
>    Check the output for a valid profile (AK, STS, or OAuth identity).
>
> **If no valid credentials exist, STOP here.**
---

## RAM Permissions
> **[MUST] RAM Permission Pre-check:** 
> Before executing any operation, ensure the current user has the required RAM permissions.
> See [references/ram-policies.md](references/ram-policies.md) for detailed permission list.

---

## Parameter Confirmation
> **IMPORTANT: Parameter Confirmation** — Before executing any command or API call,
> ALL user-customizable parameters (e.g., instance name, instance type, charge type, quota spec, etc.) MUST be confirmed with the user. 
> Do NOT assume or use default values without explicit user approval.

### Required Parameters
| Parameter | Required | Description | Default |
|-----------|----------|-------------|---------|
| `name` | Yes | Instance name | None |
| `type` | Yes | Instance type: `standard` (High-performance) / `enhanced` (Industry Algorithm) | None |
| `chargeType` | No | Charge type: `POSTPAY` / `PREPAY` | `POSTPAY` |
| `quota.spec` | Yes | Spec type (see table below) | None |
| `quota.docSize` | Yes | Storage capacity (GB) | None |
| `quota.computeResource` | Yes | Compute resource (LCU) | None |
| `domain` | No | Industry type (required for enhanced type, see table below) | `general` |
| `order` | Conditional | Subscription order info (required when PREPAY) | None |
| `order.duration` | Conditional | Subscription period quantity | None |
| `order.pricingCycle` | Conditional | Period unit: `Year` / `Month` | None |
| `order.autoRenew` | No | Auto-renewal | `false` |

### Spec Types
| Spec Code | Description |
|-----------|-------------|
| `opensearch.share.common` | Shared Common |
| `opensearch.private.common` | Dedicated Common |
| `opensearch.private.compute` | Dedicated Compute |
| `opensearch.private.storage` | Dedicated Storage |

### Industry Types (for enhanced type only)
| Industry Code | Description |
|---------------|-------------|
| `general` | General (default) |
| `ecommerce` | E-commerce |
| `esports` | Gaming |
| `community` | Content Community |
| `education` | Education |

---

## Core Workflow

> **Note:** OpenSearch APIs use **ROA (RESTful)** style. You can use `--body` to specify the HTTP request body as a JSON string. See examples in each task below.

> **Idempotency:** For write operations (create, restart, delete, etc.), you **MUST** use `--client-token` parameter for idempotency.
> - Use a UUID format unique identifier as clientToken
> - When request times out or fails, you can safely retry with **the same clientToken**; recommend waiting 10s before retry
> - Repeated requests with the same clientToken will not execute the operation multiple times
> - Generation: `uuidgen` (macOS/Linux) or `[guid]::NewGuid()` (PowerShell)

### Task 1: Create OpenSearch Instance

```bash
# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "<instance_name>",
    "type": "<standard|enhanced>",
    "chargeType": "<POSTPAY|PREPAY>",
    "quota": {
      "docSize": <storage_GB>,
      "computeResource": <compute_LCU>,
      "spec": "<spec_type>"
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage
```

**Optional Parameters** (add in body):
- `domain` - Industry type (only for enhanced type): `general` (default) / `ecommerce` / `esports` / `community` / `education`

**Idempotency and Dry-run Support** (via Query parameters):
- `--dryRun true` - Dry-run mode, validates parameters without actual creation
- `--client-token <unique_id>` - Idempotency token, same token multiple requests only creates once

**Example**: Create an enhanced (Industry Algorithm) pay-as-you-go instance (E-commerce)

```bash
# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "my_search_instance",
    "type": "enhanced",
    "chargeType": "POSTPAY",
    "domain": "ecommerce",
    "quota": {
      "docSize": 100,
      "computeResource": 2000,
      "spec": "opensearch.private.common"
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-op