Alibabacloud Opensearch App Manage

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 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.

# 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 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

Spec Types

Industry Types (for enhanced type only)

---

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

# 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)

# 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-opensearch-app-manage

Example: Create a standard (High-performance) instance

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "my_standard_instance",
    "type": "standard",
    "chargeType": "POSTPAY",
    "quota": {
      "docSize": 50,
      "computeResource": 1000,
      "spec": "opensearch.share.common"
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

Example: Create a subscription (prepaid) instance

Note: Subscription instances MUST provide order parameter

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "my_prepay_instance",
    "type": "enhanced",
    "chargeType": "PREPAY",
    "domain": "ecommerce",
    "quota": {
      "docSize": 100,
      "computeResource": 2000,
      "spec": "opensearch.private.common"
    },
    "order": {
      "duration": 1,
      "pricingCycle": "Year",
      "autoRenew": true
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

Dry-run Mode Example (validates parameters only, no actual creation):

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

Idempotent Creation Example (prevents duplicate creation):

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

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

Task 2: List Instances

aliyun opensearch list-app-groups \
  --engine-type ha3 \
  --page-number <page> \
  --page-size <size> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

Supported Filter Parameters:

• --engine-type ha3 - Engine type (default ha3, must specify)
• --name <instance_name> - Filter by name
• --instance-id <instance_id> - Filter by instance ID
• --type <standard|enhanced> - Filter by type
• standard: High-performance
• enhanced: Industry Algorithm
• --sort-by <field> - Sort field

Example: List instances

aliyun opensearch list-app-groups \
  --engine-type ha3 \
  --page-number 1 \
  --page-size 10 \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

Task 3: Describe Instance

aliyun opensearch describe-app-group \
  --app-group-identity <instance_name_or_id> \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

Example: Get instance details

aliyun opensearch describe-app-group \
  --app-group-identity my_search_instance \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

Response includes:

• Basic info (instanceId, name, type, status)
• Quota info (quota: docSize, computeResource, spec)
• Billing info (chargeType, chargingWay)
• Version info (currentVersion, versions)
• Status info (lockMode, produced)
• Engine info (engineType)

---

Success Verification

For operation verification, see references/verification-method.md

Quick Verification

Verify Instance Creation:

aliyun opensearch describe-app-group \
  --app-group-identity <instance_name> \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

Check if result.instanceId field is non-empty; if non-empty, instance creation succeeded.

---

Resource Cleanup

To delete instances, please use OpenSearch Console.

---

API and Command Reference

For complete API list, see references/related-apis.md

---

Best Practices

Write Operation Parameter Confirmation (Required)

Important: Before executing write operations (create instance, etc.), you MUST confirm the following parameters with the user:

Pre-creation Confirmation Checklist:

Confirmation Flow Example:

You are about to create the following OpenSearch instance, please confirm:

- Region: cn-hangzhou (China East 1)
- Instance Name: my_search_instance
- Instance Type: Industry Algorithm (enhanced)
- Industry: E-commerce (ecommerce)
- Charge Type: Pay-as-you-go (POSTPAY)
- Spec Type: Dedicated Common (opensearch.private.common)
- Storage: 100 GB
- Compute: 2000 LCU

Confirm creation? (yes/no)

Idempotency Best Practices

For write operations (create, restart, delete), follow these idempotency best practices:

1. Generate unique Token before each operation: Use uuidgen to generate UUID 2. Reuse Token on timeout retry: If request times out, retry with the same clientToken 3. Use different Token for different operations: Each independent operation needs a new clientToken 4. Token validity: clientToken is typically valid for 24 hours

# Example: Safe retry pattern
CLIENT_TOKEN=$(uuidgen)
echo "Using clientToken: $CLIENT_TOKEN"

# First attempt
aliyun opensearch create-app-group --client-token $CLIENT_TOKEN ...

# If timeout, retry with same Token
aliyun opensearch create-app-group --client-token $CLIENT_TOKEN ...

Other Best Practices

1. Naming Convention: Instance name must start with a letter, only lowercase letters, numbers, and underscores (_) allowed, hyphens (-) are forbidden, max 30 characters

• ✅ Correct: my_search_instance, video_search, product_search_2024
• ❌ Incorrect: my-search-instance, My_Search, 123_search

2. Quota Planning: Plan storage and compute resources based on actual data volume and query requirements 3. Charge Type Selection:

• Test/Dev environment: Use pay-as-you-go (POSTPAY)
• Production environment: Consider subscription (PREPAY) to reduce costs
• Note: Subscription instances MUST provide order parameter (including duration and pricingCycle)

4. Instance Type Selection:

• High-performance (standard): Suitable for general search scenarios
• Industry Algorithm (enhanced): Suitable for specific industry scenarios, requires domain parameter

5. Industry Selection (Industry Algorithm):

• E-commerce: ecommerce
• Gaming: esports
• Content Community: community
• Education: education
• General: general (default)

6. Spec Selection:

• Shared Common: Suitable for small-scale scenarios
• Dedicated: Suitable for production environments, more stable performance

7. Resource Cleanup: Delete unused pay-as-you-go instances promptly to avoid unnecessary costs

---

Reference Links

Acceptance Criteria: OpenSearch App Management

Scenario: OpenSearch Instance Management Purpose: Skill test acceptance criteria

Terminology: OpenSearch instance and OpenSearch app group are synonymous.

---

Correct CLI Command Patterns

1. Product — Verify Product Name

✅ CORRECT: opensearch

aliyun opensearch --help

❌ INCORRECT: open-search, OpenSearch, os

---

2. Command — Verify Command Exists

CreateAppGroup

✅ CORRECT:

aliyun opensearch create-app-group --help

❌ INCORRECT: aliyun opensearch CreateAppGroup, aliyun opensearch create_app_group

ListAppGroups

✅ CORRECT:

aliyun opensearch list-app-groups --help

❌ INCORRECT: aliyun opensearch ListAppGroups, aliyun opensearch list_app_groups

DescribeAppGroup

✅ CORRECT:

aliyun opensearch describe-app-group --help

❌ INCORRECT: aliyun opensearch DescribeAppGroup, aliyun opensearch get-app-group

---

3. Parameters — Verify Parameter Names

create-app-group Parameters

✅ CORRECT:

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "my_app",
    "type": "enhanced",
    "chargeType": "POSTPAY",
    "domain": "ecommerce",
    "quota": {
      "docSize": 100,
      "computeResource": 2000,
      "spec": "opensearch.private.common"
    }
  }' \
  --user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT (wrong parameter format):

# Wrong: Should not use separate parameters, use --body JSON instead
aliyun opensearch create-app-group \
  --name my-app \
  --type standard \
  --charge-type POSTPAY \
  --quota "doc-size=10,compute-resource=20,spec=opensearch.share.common"

Idempotency and Dry-run Parameters

✅ CORRECT:

# Dry-run mode
aliyun opensearch create-app-group \
  --dryRun true \
  --body '{...}' \
  --user-agent AlibabaCloud-Agent-Skills

# Idempotent creation (must generate token first)
CLIENT_TOKEN=$(uuidgen)
aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{...}' \
  --user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT:

# Wrong: dryRun should not be in body
aliyun opensearch create-app-group \
  --body '{"dryRun": true, ...}'

# Wrong: hardcoded token, should use uuidgen
aliyun opensearch create-app-group \
  --client-token "fixed-token-123"

# Wrong: parameter name is incorrect
aliyun opensearch create-app-group \
  --dry-run true    # Should be --dryRun

list-app-groups Parameters

✅ CORRECT:

aliyun opensearch list-app-groups \
  --page-number 1 \
  --page-size 10 \
  --user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT:

aliyun opensearch list-app-groups \
  --page 1 \                       # Wrong: should be --page-number
  --limit 10                       # Wrong: should be --page-size

describe-app-group Parameters

✅ CORRECT:

aliyun opensearch describe-app-group \
  --app-group-identity my_instance \
  --user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT:

aliyun opensearch describe-app-group \
  --name my_instance \             # Wrong: should be --app-group-identity
  --app-name my_instance           # Wrong: should be --app-group-identity

---

4. Parameter Values — Verify Valid Values

name Parameter (Instance Name)

Instance name must start with a letter, only lowercase letters, numbers, and underscores (_) allowed, hyphens (-) forbidden, max 30 characters.

✅ CORRECT: my_search_instance, video_search, product_search_2024

❌ INCORRECT: my-search-instance (contains hyphen), My_Search (uppercase), 123_search (starts with number)

type Parameter

✅ CORRECT: standard (High-performance), enhanced (Industry Algorithm)

❌ INCORRECT: basic, advanced, enterprise

domain Parameter (for enhanced type only)

✅ CORRECT: general (default), ecommerce, esports, community, education

❌ INCORRECT: retail, game, media, ECOMMERCE

chargeType Parameter

✅ CORRECT: POSTPAY, PREPAY

❌ INCORRECT: postpay, prepay, PAY_AS_YOU_GO, SUBSCRIPTION

Note: When chargeType is PREPAY, order parameter is required

order Parameter (required for PREPAY)

✅ CORRECT:

# Subscription instance must include order parameter
aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "my_prepay_instance",
    "type": "enhanced",
    "chargeType": "PREPAY",
    "quota": {...},
    "order": {
      "duration": 1,
      "pricingCycle": "Year",
      "autoRenew": true
    }
  }'

❌ INCORRECT:

# Wrong: Subscription instance missing order parameter
aliyun opensearch create-app-group \
  --body '{
    "chargeType": "PREPAY",
    "quota": {...}
  }'

# Wrong: order missing required fields
aliyun opensearch create-app-group \
  --body '{
    "chargeType": "PREPAY",
    "order": {
      "duration": 1
    }
  }'

spec Parameter

✅ CORRECT:

• opensearch.share.common
• opensearch.private.common
• opensearch.private.compute
• opensearch.private.storage

❌ INCORRECT:

• opensearch.share.junior
• opensearch.share.compute
• opensearch.share.storage
• share.common
• common

---

5. User-Agent Flag — Verify User-Agent

✅ CORRECT: Every command includes --user-agent AlibabaCloud-Agent-Skills

aliyun opensearch list-app-groups --user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT: Missing user-agent

aliyun opensearch list-app-groups

---

Correct Python Common SDK Code Patterns (Fallback)

If CLI is unavailable, Python Common SDK can be used as a fallback.

1. Import Patterns

✅ CORRECT:

from alibabacloud_tea_openapi.client import Client as OpenApiClient
from alibabacloud_credentials.client import Client as CredentialClient
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_tea_util import models as util_models

❌ INCORRECT:

# Wrong: using deprecated SDK
from aliyunsdkcore.client import AcsClient

# Wrong: incorrect module name
from alibabacloud_opensearch import Client

2. Authentication — Must Use CredentialClient

✅ CORRECT:

credential = CredentialClient()
config = open_api_models.Config(credential=credential)
config.endpoint = 'opensearch.cn-hangzhou.aliyuncs.com'
client = OpenApiClient(config)

❌ INCORRECT (hardcoded credentials):

# FORBIDDEN: hardcoding credentials
config = open_api_models.Config()
config.access_key_id = 'LTAI5txxxxxxxx'
config.access_key_secret = 'xxxxxxxxxxxxxxxx'

3. API Style — OpenSearch Uses ROA Style

✅ CORRECT:

params = open_api_models.Params(
    action='CreateAppGroup',
    version='2017-12-25',
    protocol='HTTPS',
    method='POST',
    auth_type='AK',
    style='ROA',
    pathname='/v4/openapi/app-groups',
    req_body_type='json',
    body_type='json'
)

❌ INCORRECT (wrong API style):

params = open_api_models.Params(
    style='RPC',                    # Wrong: OpenSearch uses ROA style
    pathname='/',                   # Wrong: ROA requires specific path
)

---

Critical Patterns Checklist

• [ ] All CLI commands use lowercase hyphen format (plugin mode)
• [ ] All commands include --user-agent AlibabaCloud-Agent-Skills
• [ ] Parameter names are correct (kebab-case format)
• [ ] Parameter values are within allowed enum range
• [ ] SDK code uses CredentialClient, no hardcoded credentials
• [ ] OpenSearch API uses ROA style with correct pathname

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

Aliyun CLI 3.3.3+: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 or later for full plugin ecosystem coverage.

Table of Contents

• Installation
• macOS
• Linux
• Windows
• Configuration
• Quick Start
• Configuration Modes
• Environment Variables
• Managing Multiple Profiles
• Credential Priority
• Verification
• Test Authentication
• Debug Configuration
• Security Best Practices
• Troubleshooting
• Advanced Configuration
• Custom Endpoint
• Proxy Settings
• Timeout Settings
• Next Steps
• References

---

Installation

macOS

Using Homebrew (Recommended)

brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

# Verify version (>= 3.3.3)
aliyun version

Using Binary

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz

# Extract
tar -xzf aliyun-cli-macosx-latest-amd64.tgz

# Move to PATH
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

Linux

Debian/Ubuntu

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

CentOS/RHEL

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

ARM64 Architecture

# Download ARM64 version
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-arm64.tgz
sudo mv aliyun /usr/local/bin/

Windows

Using Binary 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: aliyun version

Using PowerShell

# Download
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"

# Extract
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli

# Add to PATH (requires admin privileges)
$env:Path += ";C:\aliyun-cli"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine)

# Verify
aliyun version

Configuration

Quick Start

All aliyun configure commands support non-interactive flags, which is the recommended approach — it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts.

Where to Get Access Keys

1. Log in to Aliyun Console: https://ram.console.aliyun.com/ 2. Navigate to: AccessKey Management 3. Create a new AccessKey pair 4. Save the secret immediately — it's only shown once

Configuration Modes

Aliyun CLI supports several authentication modes. For security reasons, credential configuration is not shown in this guide. Please refer to the official Aliyun CLI documentation for secure credential setup.

Available Authentication Modes:

Configure using interactive mode (recommended):

aliyun configure

This will prompt you to enter credentials securely without exposing them in command history.

Environment Variables

Environment variables provide the highest priority credential source and override config file settings.

Supported Environment Variables:

Security Best Practices:

- Set environment variables in your shell profile (e.g., ~/.bashrc, ~/.zshrc) or CI/CD secret stores

- NEVER commit credentials to version control

- NEVER echo or print environment variable values

- Use your shell's secure credential management or CI/CD secret stores

Use Cases:

• CI/CD pipelines (via secret environment variables)
• Docker containers
• Temporary credential override

Managing Multiple Profiles

Create Named Profiles

Use interactive mode to create profiles securely:

# Create a new profile
aliyun configure --profile projectA

# Or use the set command with --mode only, then configure credentials interactively
aliyun configure set --profile projectA --mode AK --region cn-hangzhou
# Then run 'aliyun configure' to set credentials

Security Note: Avoid using --access-key-id and --access-key-secret flags in commands as they may be recorded in shell history. Use interactive mode instead.

Use Specific Profile

aliyun ecs describe-instances --profile projectA

export ALIBABA_CLOUD_PROFILE=projectA
aliyun ecs describe-instances   # Uses projectA

List and Switch Profiles

aliyun configure list                      # List all profiles
aliyun configure set --current projectA    # Switch default profile

Credential Priority

Credentials are loaded in this order (first found wins):

1. Command-line flag: --profile <name> 2. Environment variable: ALIBABA_CLOUD_PROFILE 3. Environment credentials: ALIBABA_CLOUD_ACCESS_KEY_ID, etc. 4. Configuration file: ~/.aliyun/config.json (current profile) 5. ECS Instance RAM Role: If running on ECS with attached role

Verification

Test Authentication

# Basic test - list regions
aliyun ecs describe-regions

# Expected output: JSON array of regions

If successful, you'll see:

{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "华东 1（杭州）"
      },
      ...
    ]
  },
  "RequestId": "..."
}

If failed, you'll see error messages:

• InvalidAccessKeyId.NotFound - Wrong Access Key ID
• SignatureDoesNotMatch - Wrong Access Key Secret
• InvalidSecurityToken.Expired - STS token expired (for StsToken mode)
• Forbidden.RAM - Insufficient permissions

Debug Configuration

# Show current configuration
aliyun configure get

# Test with debug logging
aliyun ecs describe-regions --log-level=debug

# Check credential provider
aliyun configure get mode

Security Best Practices

1. Use RAM Users (Not Root Account)

❌ Don't: Use Aliyun root account credentials ✅ Do: Create RAM users with specific permissions

# Create RAM user in console
# Attach only necessary policies
# Use RAM user's access keys

2. Principle of Least Privilege

Grant only the minimum permissions needed:

# Example: Read-only ECS access
# Attach policy: AliyunECSReadOnlyAccess

3. Rotate Access Keys Regularly

1. Create new access key in RAM Console 2. Update configuration using interactive mode:

   aliyun configure

3. Delete old access key from console

Security Note: Use interactive mode (aliyun configure) to avoid exposing credentials in shell history.

4. Use STS Tokens for Temporary Access

Configure STS Token mode interactively:

aliyun configure --mode StsToken

Or use environment variables for temporary credentials in CI/CD pipelines.

5. Use ECS RAM Roles When Possible

aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou

6. Never Commit Credentials

# Add to .gitignore
echo "~/.aliyun/config.json" >> .gitignore

# Use environment variables in CI/CD instead

7. Secure Config File

# Restrict permissions
chmod 600 ~/.aliyun/config.json

Troubleshooting

Issue: Command Not Found

# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH

Issue: Authentication Failed

# Verify configuration
aliyun configure get

# Test with debug
aliyun ecs describe-regions --log-level=debug

# Check credentials in console
# Verify access key is active

Issue: Permission Denied

# Error: Forbidden.RAM

# Check RAM user permissions
# Attach necessary policies in RAM console
# Example: AliyunECSFullAccess for ECS operations

Issue: STS Token Expired

# Error: InvalidSecurityToken.Expired

# Reconfigure with new token using interactive mode
aliyun configure --mode StsToken

Security Note: Use interactive mode to avoid exposing credentials in shell history.

Issue: Wrong Region

# Some resources may not exist in the specified region

# Check available regions
aliyun ecs describe-regions

# Update default region
aliyun configure set region cn-shanghai

Advanced Configuration

Custom Endpoint

# Use custom or private endpoint
export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com

Proxy Settings

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# No proxy for specific domains
export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com

Timeout Settings

# Connection timeout (default: 10s)
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30

# Read timeout (default: 10s)
export ALIBABA_CLOUD_READ_TIMEOUT=30

Next Steps

After installation and configuration:

1. Install plugins for services you need (v3.3.3+ supports all published product plugins):

   aliyun plugin install --names ecs vpc rds

   # List all available plugins
   aliyun plugin list-remote

2. Explore commands:

   aliyun ecs --help
   aliyun fc --help

3. Read documentation:

• Command Syntax Guide
• Global Flags Reference
• Common Scenarios

References

• Official Documentation: https://help.aliyun.com/zh/cli/
• RAM Console: https://ram.console.aliyun.com/
• Access Key Management: https://ram.console.aliyun.com/manage/ak
• Plugin Repository: https://github.com/aliyun/aliyun-cli

RAM Policies

RAM (Resource Access Management) permissions required for OpenSearch instance management.

Terminology: OpenSearch instance and OpenSearch app group are synonymous.

Permission Summary

RAM Policy Document

Full Access Policy (Read-Write)

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "opensearch:CreateAppGroup",
        "opensearch:ListAppGroups",
        "opensearch:DescribeAppGroup"
      ],
      "Resource": "acs:opensearch:*:*:apps/*"
    }
  ]
}

Read-Only Policy

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "opensearch:ListAppGroups",
        "opensearch:DescribeAppGroup"
      ],
      "Resource": "acs:opensearch:*:*:apps/*"
    }
  ]
}

Create Instance Policy

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "opensearch:CreateAppGroup",
      "Resource": "acs:opensearch:*:*:apps/*"
    }
  ]
}

System Policies

Alibaba Cloud provides the following OpenSearch system policies:

Usage

1. Log in to RAM Console 2. Create custom policy or use system policy 3. Attach policy to RAM user or role

Best Practices

1. Principle of Least Privilege: Only grant minimum permissions required for the task 2. Use System Policies: Prefer Alibaba Cloud provided system policies 3. Regular Auditing: Regularly review and clean up unnecessary permissions 4. Resource-Level Restrictions: Restrict access to specific resources when possible

Reference Documentation

• RAM Policy Overview
• OpenSearch Authorization Info

Related APIs

Complete API list for OpenSearch instance management.

Terminology: OpenSearch instance and OpenSearch app group are synonymous.

Instance Management APIs

API Details

CreateAppGroup - Create Instance

• API Version: 2017-12-25
• API Style: ROA
• HTTP Method: POST
• Path: /v4/openapi/app-groups
• Operation Type: write
• Billing: paid

Request Parameters:

Query Parameters (Idempotency and Dry-run):

CLI Example:

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "my_instance",
    "type": "enhanced",
    "chargeType": "POSTPAY",
    "domain": "ecommerce",
    "quota": {
      "docSize": 100,
      "computeResource": 2000,
      "spec": "opensearch.private.common"
    }
  }' \
  --user-agent AlibabaCloud-Agent-Skills

---

ListAppGroups - List Instances

• API Version: 2017-12-25
• API Style: ROA
• HTTP Method: GET
• Path: /v4/openapi/app-groups
• Operation Type: read
• Billing: free

Request Parameters:

CLI Example:

aliyun opensearch list-app-groups \
  --engine-type ha3 \
  --page-number 1 \
  --page-size 10 \
  --user-agent AlibabaCloud-Agent-Skills

---

DescribeAppGroup - Describe Instance

• API Version: 2017-12-25
• API Style: ROA
• HTTP Method: GET
• Path: /v4/openapi/app-groups/{appGroupIdentity}
• Operation Type: read
• Billing: free

Request Parameters:

Response Parameters:

CLI Example:

aliyun opensearch describe-app-group \
  --app-group-identity my_app \
  --user-agent AlibabaCloud-Agent-Skills

---

Response Status Codes

Common Response Structure

{
  "requestId": "xxx-xxx-xxx",
  "result": { ... }
}

Error Response Structure

{
  "code": "ErrorCode",
  "message": "Error message",
  "requestId": "xxx-xxx-xxx",
  "httpCode": 400
}

Reference Documentation

• CreateAppGroup API Doc
• ListAppGroups API Doc
• DescribeAppGroup API Doc

Verification Method

Success verification methods for OpenSearch instance management operations.

Terminology: OpenSearch instance and OpenSearch app group are synonymous.

Scenario Verification

Verify Instance Creation Success

Expected Result: OpenSearch instance created successfully, instanceId field is non-empty

Verification Flow: First call create-app-group to create instance, then call describe-app-group to check status

Verification Command:

aliyun opensearch describe-app-group \
  --app-group-identity <instance_name> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

Success Criteria:

• Response status code is 200
• Response contains result object
• result.instanceId field is non-empty (key indicator of successful creation)

Example Response (Success):

{
  "requestId": "xxx-xxx-xxx",
  "result": {
    "name": "my_search_instance",
    "instanceId": "ops-cn-xxxxx",
    "status": "normal",
    "produced": 1,
    "type": "enhanced",
    "chargeType": "POSTPAY",
    "lockMode": "Unlock",
    "domain": "ecommerce"
  }
}

Key Fields:

Status Values:

---

Verify Dry-run Mode

Expected Result: Validates parameters only, does not actually create instance

Verification Command:

aliyun opensearch create-app-group \
  --dryRun true \
  --body '{
    "name": "test_dry_run",
    "type": "enhanced",
    "chargeType": "POSTPAY",
    "domain": "general",
    "quota": {
      "docSize": 100,
      "computeResource": 2000,
      "spec": "opensearch.private.common"
    }
  }' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

Success Criteria:

• Response status code is 200
• Request succeeds but does not create instance
• Instance does not exist in list query

---

Verify Idempotent Creation (clientToken)

Expected Result: Same clientToken multiple requests only creates once

Verification Steps:

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

# First creation
aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "idempotent_test_instance",
    "type": "enhanced",
    "chargeType": "POSTPAY",
    "domain": "ecommerce",
    "quota": {
      "docSize": 100,
      "computeResource": 2000,
      "spec": "opensearch.private.common"
    }
  }' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

# Second request with same token (using same CLIENT_TOKEN)
aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "idempotent_test_instance",
    "type": "enhanced",
    "chargeType": "POSTPAY",
    "domain": "ecommerce",
    "quota": {
      "docSize": 100,
      "computeResource": 2000,
      "spec": "opensearch.private.common"
    }
  }' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

Success Criteria:

• Both requests return 200
• Only one instance created (verify with describe-app-group)

---

Verify List Instances Success

Expected Result: Successfully returns instance list

Verification Command:

aliyun opensearch list-app-groups \
  --engine-type ha3 \
  --page-number 1 \
  --page-size 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

Success Criteria:

• Response status code is 200
• Response contains result array
• totalCount field shows correct instance count

---

Verify Describe Instance Success

Expected Result: Successfully returns instance details

Verification Command:

aliyun opensearch describe-app-group \
  --app-group-identity <instance_name> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

Success Criteria:

• Response status code is 200
• Response contains result object
• result contains instance details (id, name, type, status, quota, etc.)

Example Response (Success):

{
  "requestId": "0A6EB64B-B4C8-CF02-810F-E660812972FF",
  "result": {
    "id": "110116134",
    "name": "my_search_instance",
    "instanceId": "ops-cn-xxxxx",
    "type": "enhanced",
    "status": "normal",
    "chargeType": "POSTPAY",
    "domain": "ecommerce",
    "quota": {
      "docSize": 100,
      "computeResource": 2000,
      "spec": "opensearch.private.common"
    },
    "lockMode": "Unlock",
    "produced": 1
  }
}

---

Complete Workflow Verification

Full Test Script

#!/bin/bash

APP_NAME="test_instance_$(date +%s)"

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

echo "=== 1. Create Instance ==="
aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body "{
    \"name\": \"$APP_NAME\",
    \"type\": \"enhanced\",
    \"chargeType\": \"POSTPAY\",
    \"domain\": \"general\",
    \"quota\": {
      \"docSize\": 100,
      \"computeResource\": 2000,
      \"spec\": \"opensearch.private.common\"
    }
  }" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

echo ""
echo "=== 2. Wait for Instance Production ==="
sleep 30

echo ""
echo "=== 3. Describe Instance (Verify Creation) ==="
aliyun opensearch describe-app-group \
  --app-group-identity $APP_NAME \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

echo ""
echo "=== 4. List Instances ==="
aliyun opensearch list-app-groups \
  --engine-type ha3 \
  --page-number 1 \
  --page-size 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

echo ""
echo "=== Test Complete ==="
echo "Note: To delete test instance, please use OpenSearch Console"

---

Troubleshooting

Common Errors and Solutions

Debug Commands

# Enable debug mode for detailed request/response
aliyun opensearch list-app-groups --log-level=debug --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage