Alibabacloud Ecs Install Extension

ECS Extension Installation Skill

You are a professional cloud operations assistant responsible for helping users query, verify, and install Alibaba Cloud ECS extensions (OOS Packages). Follow the scenario-based workflow strictly.

Scenario Description

This skill provides ECS extension program query and installation capabilities through Alibaba Cloud OOS (Operation Orchestration Service). Users can browse available extensions, check if a specific extension is supported, and install extensions on one or more ECS instances with a single click.

Architecture: ECS + OOS (Operation Orchestration Service) + Cloud Assistant

Use Cases:

• Query available extensions (BT Panel, OpenClaw, Node.js, Python, etc.)
• Check if a specific extension is supported
• Install extensions on single or multiple ECS instances
• Deploy development environments (Python, Node.js, Java, etc.)
• Install server management panels (BT Panel, etc.)

Prerequisites

Pre-check: Aliyun CLI >= 3.3.1 required

Run aliyun version to verify >= 3.3.1. If not installed or version too low,

see references/cli-installation-guide.md for installation instructions.

Then [MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.

>

Plugin Installation Fallback: If automatic plugin installation fails (e.g., network errors like connect: bad file descriptor), manually install the OOS plugin:

```bash

# Check if oos plugin is installed

aliyun plugin list

# If not listed, download and install manually:

# 1. Visit https://github.com/aliyun/alibaba-cloud-cli/releases to find the oos plugin package

# 2. Download the .tar.gz for your platform

# 3. Install: aliyun plugin install --file <path-to-downloaded-plugin.tar.gz>

# 4. Verify: aliyun plugin list (should show oos plugin)

```

Pre-check: Alibaba Cloud Credentials Required

>

Security Rules:

- NEVER read, echo, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)

- NEVER ask the user to input AK/SK directly in the conversation or command line

- NEVER use aliyun configure set with literal credential values

- ONLY use aliyun configure list to check credential status

>

```bash

aliyun configure list

```

Check the output for a valid profile (AK, STS, or OAuth identity).

>

If no valid profile exists, STOP here.

1. Obtain credentials from Alibaba Cloud Console

2. Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)

3. Return and re-run after aliyun configure list shows a valid profile

Endpoint Note (Plugin Mode): In plugin mode, the --endpoint flag is typically not needed. The OOS plugin resolves endpoints automatically based on --biz-region-id. If endpoint resolution fails, check that the --biz-region-id value is a valid Alibaba Cloud region ID (e.g., cn-hangzhou).

---

AI-Mode & Plugin Update

[MUST] Before executing any aliyun CLI command in this workflow, run the following initialization commands:

>

```bash

aliyun configure ai-mode enable

aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension"

aliyun plugin update

```

>

After the entire workflow is complete (all scenarios finished), disable AI-Mode:

>

```bash

aliyun configure ai-mode disable

```

CLI Command Standards

[MUST] Before executing any CLI command, read references/related-commands.md for command format standards.

>

Key Rules:

- ALL `aliyun` CLI commands must use plugin mode (lowercase-hyphenated) for both operation names and flags. This applies to every cloud service, not just OOS. Only lowercase-hyphenated format is allowed — any other format will cause unknown flag or unknown command errors.

- OOS commands: list-templates, get-template, start-execution, list-executions with flags --biz-region-id, --template-type, --template-name, etc.

- ECS commands: describe-instances, describe-regions, run-command, describe-invocations, describe-invocation-results, describe-cloud-assistant-status with flags --region-id, --instance-id, --command-content, etc.

>

[RECOMMENDED] Flag Verification: Run aliyun <service> <action> --help (e.g., aliyun ecs run-command --help) to confirm the exact flags supported by the installed plugin version.

Required Permissions

This skill requires the following RAM permissions:

• bss:DescribeOrderDetail (query order details for billing verification)
• ecs:DescribeCloudAssistantStatus (check Cloud Assistant status)
• ecs:DescribeInstances (instance information verification)
• ecs:DescribeInvocations (list Cloud Assistant command invocations)
• ecs:DescribeInvocationResults (view command execution results)
• ecs:RunCommand (Cloud Assistant command execution during installation)
• oos:GetApplicationGroup (get OOS application group information)
• oos:GetTemplate (get OOS template details)
• oos:ListInstancePackageStates (query instance extension package status)
• oos:ListTemplates (list available extension packages)
• oos:StartExecution (start OOS execution for installation)
• oos:UpdateInstancePackageState (update instance package state)
• oss:GetObject (download extension package files from OSS)

See references/ram-policies.md for detailed policy configuration.

[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:

1. Read references/ram-policies.md to get the full list of permissions required by this SKILL

2. Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions

3. Pause and wait until the user confirms that the required permissions have been granted

Parameter Confirmation

IMPORTANT: Parameter Confirmation — Before executing any installation command,

ALL user-customizable parameters MUST be confirmed with the user. Do NOT assume or use default

values without explicit user approval.

Input Validation Rules

[MUST] Before assembling any CLI command, validate ALL user-provided input values. Reject invalid input immediately and prompt the user to correct it. Never pass unvalidated user input into shell command strings.

Special Character Escaping: After validation, all user-provided string values must be properly JSON-escaped (e.g., quotes, backslashes) before embedding into the --Parameters JSON string. Use jq or equivalent tools to construct the JSON payload programmatically rather than manual string concatenation when possible.

---

Scenario-Based Routing

IMPORTANT: Before starting installation, identify the user's intent and follow the appropriate workflow.

Based on the user's request, route to the appropriate scenario:

---

Scenario 1: Query Available Extensions List

When the user asks "What extensions are available?" or similar, follow these steps:

Step 1: List Templates

Call list-templates to get all available public extension packages:

aliyun oos list-templates \
  --biz-region-id cn-hangzhou \
  --template-type Package \
  --share-type Public \
  --max-results 100 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension

Step 2: Parse and Display Results

Parse the response and present the results in a table format to the user:

Note: The Description field is a JSON string containing metadata. Parse it to extract:

- name-zh-cn: Chinese display name (preferred for display)

- name-en: English display name

- zh-cn: Chinese description

- en: English description

- categories: Category tags array

- doc-zh-cn: Chinese documentation link

- doc-en: English documentation link

- image: Icon URL

>

Example Description value:

```json

"Description": "{\"categories\":[\"application\"],\"en\":\"BaoTa Panel free edition one-click installation\",\"zh-cn\":\"BaoTa Panel free edition one-click installation\",\"name-en\":\"BaoTaPanelFree-One-Click\",\"name-zh-cn\":\"BaoTaPanelFree-One-Click\",\"image\":\"https://oos-public-template.oss-cn-beijing.aliyuncs.com/BaoTaPanelFree/icon.png\"}"

```

Note: The --biz-region-id in the command is used for API endpoint routing. The returned public templates are available across all regions.

---

Scenario 2: Query if a Specific Extension is Supported

When the user asks "Can I install XXX?" or similar, follow these steps:

Step 1: List and Search

Call list-templates (same as Scenario 1) and search for the extension by keyword:

aliyun oos list-templates \
  --biz-region-id cn-hangzhou \
  --template-type Package \
  --share-type Public \
  --max-results 100 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension

Step 2: Match Results

• If matched: return the extension details (name, description, supported OS, etc.)
• If not matched: inform the user that the extension is not currently supported, and suggest similar alternatives or Scenario 1 to browse the full list

---

Scenario 3: Install Extension

This is the core workflow. Follow these steps in strict order:

Step 1: Confirm Extension Name

Confirm the exact extension name the user wants to install.

• If the user is unsure, execute Scenario 1 or Scenario 2 first to help them find the correct extension.
• If the user provides a vague name (e.g., "BT Panel"), search and confirm the exact TemplateName (e.g., ACS-Extension-BaoTaPanelFree-One-Click-1853370294850618).

Step 2: Get Template Details

Call get-template to retrieve the extension template details. Redirect output to a temporary file to avoid terminal truncation (the Content field is usually very large):

aliyun oos get-template \
  --biz-region-id cn-hangzhou \
  --template-name "【Extension-Name】" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension > /tmp/oos-template.json

Then extract the Parameters from the template content:

jq -r '(.Content | fromjson | .Parameters)' /tmp/oos-template.json

[IMPORTANT] Output Truncation Warning: get-template returns a Content field that is typically very large (contains full installation scripts). Always redirect command output to a temporary file (> /tmp/oos-template.json) first, then use jq or file read tools to parse. Do not rely on terminal output directly — truncated JSON will cause parsing errors.

The Content field (JSON string) includes:

• Parameters: defines the installation parameters required (e.g., version number, installation path, etc.)
• Description: extension description
• TemplateVersion: template version

Parse Content.Parameters and extract all required and optional parameters.

Step 3: Guide User to Provide Parameters

Based on the Parameters parsed in Step 2, guide the user to provide necessary values:

• Required parameters: must obtain user input
• Optional parameters: inform the user of defaults; if the user does not provide, use defaults

[IMPORTANT] Only extract parameters from Content.Parameters. Do not infer parameters from InstallScript or other template content — shell variables inside scripts are internal implementation details, not user-configurable parameters.

Common parameter examples:

Note: Do not fabricate parameter values. Must be obtained from the user or template defaults.

Step 4: Confirm All Parameters

[MUST] Before executing the installation, you MUST output a parameter confirmation table to the user containing ALL of the following items and explicitly ask "Please confirm the above parameters are correct before I proceed with installation." You MUST NOT proceed to Step 5 until the user provides an affirmative response. Even if the user has already provided all parameters in their initial request, the confirmation step is still mandatory.

[MUST] Instance Count Verification: Verify that the number of InstanceIds matches the user's request. If the user mentions N instances but provides fewer IDs, ask for the missing instance IDs before proceeding.

>

[MUST] Installation operations will modify instance state. Must obtain explicit user confirmation before execution. Do NOT skip this step under any circumstances.

Step 5: Execute Installation

[MUST] Idempotency Check: Before executing, query whether a running execution already exists for the same extension and target instances:

>

```bash

aliyun oos list-executions \

--biz-region-id "【User-Provided-Region】" \

--template-name "ACS-ECS-BulkyConfigureOOSPackageWithTemporaryURL" \

--status Running \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension

```

>

If a running execution with the same packageName and targets is found:

1. Inform the user about the existing execution

2. Ask the user whether to wait for it or create a new execution

3. If the user does not respond or confirms to proceed, you MUST still call `start-execution` to create a new execution — do NOT skip `start-execution` under any circumstances

>

The `start-execution` call is the mandatory core action of this step and must always be executed unless the user explicitly requests to wait for the existing execution.

>

[RECOMMENDED] ClientToken: Generate a deterministic ClientToken to prevent duplicate submissions caused by retries. The ClientToken must be a string of 1-64 ASCII characters.

>

```bash

# Generate a deterministic ClientToken and save it for reuse

CLIENT_TOKEN="${regionId}-${packageName}-$(date +%Y%m%d%H%M)"

>

# All subsequent retries reuse the same token, ensuring idempotency

aliyun oos start-execution \

... \

--client-token "$CLIENT_TOKEN"

```

>

This ensures that no matter how many times the command is retried, the same installation intent always maps to the same token.

[MUST] Call start-execution to execute the installation task (this call must NOT be skipped):

[MUST] Parameter Recording: Before executing start-execution, save the complete --parameters JSON to a file for traceability, then use the file content for the command:

# Save parameters to file for traceability
cat > /tmp/oos-start-params.json << 'PARAMS_EOF'
{"regionId":"【User-Provided-Region】","OOSAssumeRole":"","targets":{"ResourceIds":["【User-Provided-InstanceId】"],"RegionId":"【User-Provided-Region】","Type":"ResourceIds"},"rateControl":{"Mode":"Concurrency","Concurrency":1,"MaxErrors":0},"action":"install","packageName":"【User-Specified-Package】","parameters":【User-Provided-Parameters】}
PARAMS_EOF

# Execute with parameters from file
aliyun oos start-execution \
  --biz-region-id "【User-Provided-Region】" \
  --template-name "ACS-ECS-BulkyConfigureOOSPackageWithTemporaryURL" \
  --mode "Automatic" \
  --tags "{}" \
  --parameters "$(cat /tmp/oos-start-params.json)" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension

[MUST] After executing, log the key parameter values that were passed:

Parameters passed to OOS:
  - packageName: <actual value>
  - packageVersion: <actual value, if applicable>
  - parameters.version: <actual value, if applicable>
  - targets.ResourceIds: <actual value>

Include the complete parameters JSON (from /tmp/oos-start-params.json) in the Installation Report's "Installation Parameters" field.

Parameter Description:

Example:

aliyun oos start-execution \
  --biz-region-id cn-hangzhou \
  --template-name "ACS-ECS-BulkyConfigureOOSPackageWithTemporaryURL" \
  --mode "Automatic" \
  --tags "{}" \
  --parameters "{\"regionId\":\"cn-hangzhou\",\"OOSAssumeRole\":\"\",\"targets\":{\"ResourceIds\":[\"i-bp12z30vh0xxxxxxxxxx\"],\"RegionId\":\"cn-hangzhou\",\"Type\":\"ResourceIds\"},\"rateControl\":{\"Mode\":\"Concurrency\",\"Concurrency\":1,\"MaxErrors\":0},\"action\":\"install\",\"packageName\":\"ACS-Extension-node-1853370294850618\",\"packageVersion\":\"v27\",\"parameters\":{\"version\":\"v22.13.1\"}}" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension

Step 6: Check Execution Result and Verify

After the command returns, extract ExecutionId from the response and poll the execution status:

aliyun oos list-executions \
  --biz-region-id "【User-Provided-Region】" \
  --execution-id "【ExecutionId-from-Response】" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension

Polling Strategy: Check execution status every 20 seconds. If the status is still Running, wait 20 seconds and check again. Maximum wait time is 20 minutes (60 checks).

>

[MUST] Terminal Status Requirement: You MUST continue polling until the execution reaches a terminal status (Success, Failed, or Cancelled). While the status is Running, it is absolutely forbidden to generate the Installation Report. You may ONLY stop polling and generate a report in these two cases:

1. The execution has reached a terminal status (Success, Failed, or Cancelled)

2. You have polled for the full 20 minutes (60 checks at 20-second intervals) and the status is still Running — in this case, output a PENDING report with Execution Status set to Pending (timed out after 20 minutes) and include in Result Details: "Installation is still in progress, exceeded the 20-minute maximum wait time. Please check status manually using: aliyun oos list-executions --biz-region-id <region> --execution-id <exec-id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension"

>

Any other situation (e.g., polling fewer than 60 times while status is still `Running`) absolutely forbids generating a report. You must keep polling.

Installation status explanation:

---

Installation Report Output Format

[MUST] Only generate this report when one of the following conditions is met:

1. The execution has reached a terminal status (Success, Failed, Cancelled)

2. You have polled for the full 20 minutes (60 checks) and the status is still Running (report as Pending (timed out after 20 minutes))

>

It is absolutely forbidden to generate this report if polling has not reached 60 checks and the status is still `Running`. You must keep polling.

================== ECS Extension Installation Report ==================
【Extension Name】        : (Extension package name)
【Installation Target】    : (List of instance IDs)
【Installation Parameters】: (JSON-formatted installation parameters)
【Execution ID】           : (OOS ExecutionId)
【Execution Status】       : (Success / Failed / Cancelled / Pending-timed out)
【Completion Time】        : (Execution end time, or "N/A — still running" if timed out)
【Result Details】         : (Execution output or error information)
【Follow-up Suggestions】  :
  1. (Suggestion 1, e.g., verify service status)
  2. (Suggestion 2, e.g., security group port opening)
  3. (Suggestion 3, e.g., check installation logs)
=======================================================================

Best Practices

1. Confirm parameters before installation — Extension installation will modify the instance environment; must confirm all parameters with the user before execution 2. Check instance status — Ensure the target instance is in the Running state before installation 3. Choose the correct version — Version parameters vary by extension; obtain the correct version number from the user 4. Multiple instances supported — ResourceIds supports arrays; can install the same extension on multiple instances at once 5. Security awareness — Never expose AK/SK in commands or reports

Reference Links

Notes

1. Extension installation may take several minutes; wait patiently and regularly query execution status 2. On API failure, read error messages, check permissions, and retry 3. Sensitive information (AccessKey, passwords) must never appear in reports or commands 4. Some extensions may require specific operating system versions; confirm OS compatibility in get-template response 5. Extension installation failures are usually caused by: instance not running, network issues, incompatible OS versions, or insufficient disk space

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

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

Installation

macOS

Using Homebrew (Recommended)

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

# Verify version (>= 3.3.1)
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

aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou

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 6 authentication modes. All examples below use non-interactive flags.

1. AK Mode (Access Key)

Most common mode for personal accounts and scripts.

aliyun configure set \
  --mode AK \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Configuration is stored in ~/.aliyun/config.json:

{
  "current": "default",
  "profiles": [
    {
      "name": "default",
      "mode": "AK",
      "access_key_id": "LTAI5tXXXXXXXX",
      "access_key_secret": "8dXXXXXXXXXXXXXXXXXXXXXXXX",
      "region_id": "cn-hangzhou",
      "output_format": "json",
      "language": "en"
    }
  ]
}

2. StsToken Mode (Temporary Credentials)

For short-lived access (tokens expire in 1-12 hours).

aliyun configure set \
  --mode StsToken \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --sts-token v1.0:XXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access.

3. RamRoleArn Mode (Assume RAM Role)

Assume a RAM role for elevated or cross-account access.

aliyun configure set \
  --mode RamRoleArn \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --ram-role-arn acs:ram::123456789012:role/AdminRole \
  --role-session-name my-session \
  --region cn-hangzhou

Use cases: cross-account resource access, temporary elevated privileges, role-based access control.

4. EcsRamRole Mode (ECS Instance RAM Role)

Use the RAM role attached to an ECS instance — no credentials needed.

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

Requirements: must be running on an ECS instance with a RAM role attached.

Use cases: scripts and automation running on ECS instances.

5. RsaKeyPair Mode (RSA Key Pair)

Use RSA key pair for authentication (generate key pair in Aliyun Console first).

aliyun configure set \
  --mode RsaKeyPair \
  --private-key /path/to/private-key.pem \
  --key-pair-name my-key-pair \
  --region cn-hangzhou

6. RamRoleArnWithEcs Mode (ECS + RAM Role)

Combine ECS instance role with RAM role assumption for cross-account access from ECS.

aliyun configure set \
  --mode RamRoleArnWithEcs \
  --ram-role-name MyEcsRole \
  --ram-role-arn acs:ram::123456789012:role/TargetRole \
  --role-session-name my-session \
  --region cn-hangzhou

Environment Variables

Highest priority - overrides config file

Access Key Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

STS Token Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

ECS RAM Role Mode

export ALIBABA_CLOUD_ECS_METADATA=role_name

Use Case:

• CI/CD pipelines
• Docker containers
• Temporary credential override

Managing Multiple Profiles

Create Named Profiles

aliyun configure set --profile projectA \
  --mode AK \
  --access-key-id LTAI5tAAAAAAAA \
  --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \
  --region cn-hangzhou

aliyun configure set --profile projectB \
  --mode AK \
  --access-key-id LTAI5tBBBBBBBB \
  --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \
  --region cn-shanghai

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": "China East 1 (Hangzhou)"
      },
      ...
    ]
  },
  "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

# Create new access key in RAM Console, then update configuration
aliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET
# Delete old access key from console

4. Use STS Tokens for Temporary Access

aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token XXXX --region cn-hangzhou

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
aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token NEW_TOKEN --region cn-hangzhou

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.1+ 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 for ECS Extension Installation

Required RAM permissions for the ECS Extension Installation skill.

Permission List

Minimum Permission Policy

Use this policy when you only need extension installation functionality:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bss:DescribeOrderDetail",
        "ecs:DescribeCloudAssistantStatus",
        "ecs:DescribeInstances",
        "ecs:DescribeInvocations",
        "ecs:DescribeInvocationResults",
        "ecs:RunCommand",
        "oos:GetApplicationGroup",
        "oos:GetTemplate",
        "oos:ListInstancePackageStates",
        "oos:ListTemplates",
        "oos:StartExecution",
        "oos:UpdateInstancePackageState",
        "oss:GetObject"
      ],
      "Resource": "*"
    }
  ]
}

Full Permission Policy (Recommended)

Recommended for production use with additional query and monitoring permissions:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bss:DescribeOrderDetail",
        "ecs:DescribeCloudAssistantStatus",
        "ecs:DescribeInstances",
        "ecs:DescribeInvocations",
        "ecs:DescribeInvocationResults",
        "ecs:RunCommand",
        "oos:GetApplicationGroup",
        "oos:GetTemplate",
        "oos:ListExecutions",
        "oos:ListInstancePackageStates",
        "oos:ListTemplates",
        "oos:StartExecution",
        "oos:UpdateInstancePackageState",
        "oss:GetObject"
      ],
      "Resource": "*"
    }
  ]
}

Note: oos:ListExecutions is used to query execution status and history, which is helpful for tracking installation progress. ecs:DescribeInvocationResults is used to view Cloud Assistant command execution results. ecs:DescribeCloudAssistantStatus checks if Cloud Assistant is installed and running on the instance. oos:ListInstancePackageStates and oos:UpdateInstancePackageState are used for managing extension package states on instances. oss:GetObject is required when the extension package needs to be downloaded from OSS. bss:DescribeOrderDetail is used for billing and order verification when installing paid extensions.

Permission Verification Command

After attaching the policy, verify permissions:

# Verify OOS template query permission
aliyun oos list-templates \
  --biz-region-id cn-hangzhou \
  --template-type Package \
  --share-type Public \
  --max-results 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension

# Verify ECS instance query permission
aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --max-results 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension

If all commands return data successfully, permissions are correctly configured.

Common Permission Errors and Troubleshooting

Error: Forbidden.RAM / NoPermission

Cause: The RAM user does not have the required permissions.

Solution: 1. Log in to RAM Console 2. Find the target RAM user 3. Click "Add Permissions" 4. Select "Custom Policy" and paste the minimum permission policy JSON above 5. Or select system policies: AliyunOOSFullAccess + AliyunECSFullAccess (broader permissions)

Error: Forbidden on oos:StartExecution

Cause: Missing OOS execution permission.

Solution: Ensure the policy includes oos:StartExecution action.

Error: Forbidden on ecs:RunCommand

Cause: Cloud Assistant command execution permission is missing.

Solution: Ensure the policy includes ecs:RunCommand action. The extension installation process requires Cloud Assistant to execute installation scripts on the instance.

Error: InvalidAccount.NotFound

Cause: Incorrect AccessKey or the account does not exist.

Solution:

• Check if AccessKey ID is correct
• Verify if the AccessKey is active in the RAM console
• Reconfigure credentials outside of this session using aliyun configure interactively or via environment variables

Using Predefined System Policies

If custom policies are not convenient, you can directly attach the following system policies:

Attach method:

# Attach through RAM console or CLI
aliyun ram attach-policy-to-user \
  --policy-type System \
  --policy-name AliyunOOSFullAccess \
  --user-name <your-ram-username> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension

Security Recommendation: For production environments, use custom minimum permission policies instead of full-access system policies to follow the principle of least privilege.

OOS Related Commands Reference

CLI command reference for ECS Extension Installation skill.

Command Format Standards

• For OOS commands, use plugin mode (lowercase-hyphenated) operation names: list-templates, get-template, start-execution, list-executions
• All OOS plugin flags use kebab-case: --biz-region-id, --template-type, --share-type, --max-results, --template-name, --execution-id, etc.
• Always include --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension
• OOS command format: aliyun oos <action> --biz-region-id <region> [parameters]

[RECOMMENDED] Flag Verification: Run aliyun oos <action> --help to confirm exact flag names for the installed plugin version.

---

list-templates

Query available OOS templates (extension packages).

Command

aliyun oos list-templates \
  --biz-region-id <region-id> \
  --template-type Package \
  --share-type Public \
  --max-results <max-results> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension

Parameters

Output Example

{
  "Templates": [
    {
      "TemplateId": "t-xxxxxxxxxxxxxxxx",
      "TemplateName": "ACS-Extension-BaoTaPanelFree-One-Click-1853370294850618",
      "TemplateVersion": "v1",
      "Description": "{\"categories\":[\"application\"],\"en\":\"BaoTa Panel free edition one-click installation\",\"zh-cn\":\"BaoTa Panel free edition one-click installation\",\"name-en\":\"BaoTaPanelFree-One-Click\",\"name-zh-cn\":\"BaoTaPanelFree-One-Click\",\"image\":\"https://oos-public-template.oss-cn-beijing.aliyuncs.com/BaoTaPanelFree/icon.png\"}",
      "ShareType": "Public",
      "TemplateType": "Package",
      "CreatedDate": "2024-01-15T08:00:00Z",
      "UpdatedDate": "2024-06-01T10:00:00Z"
    },
    {
      "TemplateId": "t-yyyyyyyyyyyyyyyy",
      "TemplateName": "ACS-Extension-node-1853370294850618",
      "TemplateVersion": "v27",
      "Description": "{\"categories\":[\"application\"],\"en\":\"Node.js environment one-click installation\",\"zh-cn\":\"Node.js environment one-click installation\",\"name-en\":\"Node.js\",\"name-zh-cn\":\"Node.js\",\"image\":\"https://oos-public-template.oss-cn-beijing.aliyuncs.com/Nodejs/icon.png\"}",
      "ShareType": "Public",
      "TemplateType": "Package",
      "CreatedDate": "2024-03-10T06:00:00Z",
      "UpdatedDate": "2024-07-15T12:00:00Z"
    }
  ],
  "MaxResults": 100,
  "TotalCount": 2,
  "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Output Field Description

Description Field Parsing: The Description field is a JSON string containing localized metadata. Parse it to extract:

- name-zh-cn: Chinese display name (preferred for display)

- name-en: English display name

- zh-cn: Chinese description

- en: English description

- categories: Category tags array

- doc-zh-cn: Chinese documentation link

- doc-en: English documentation link

- image: Icon URL

Common Errors

---

get-template

Get detailed information of a specific OOS template.

Command

Recommended: redirect output to a temporary file (the Content field is usually very large and will be truncated in terminal):

aliyun oos get-template \
  --biz-region-id <region-id> \
  --template-name <template-name> \
  [--template-version <version>] \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension > /tmp/oos-template.json

Then extract parameters using jq:

# Extract installation parameters
jq -r '(.Content | fromjson | .Parameters)' /tmp/oos-template.json

# Extract template description
jq -r '.Description' /tmp/oos-template.json

[IMPORTANT] Output Truncation Warning: get-template returns a Content field that contains full installation scripts and can be extremely large. Always redirect to a file first, then parse with jq or file read tools. Do not rely on terminal output directly.

Parameters

Output Example

{
  "Template": {
    "TemplateId": "t-xxxxxxxxxxxxxxxx",
    "TemplateName": "ACS-Extension-node-1853370294850618",
    "TemplateVersion": "v27",
    "Description": "{\"categories\":[\"application\"],\"en\":\"Node.js environment one-click installation\",\"zh-cn\":\"Node.js environment one-click installation\",\"name-en\":\"Node.js\",\"name-zh-cn\":\"Node.js\",\"image\":\"https://oos-public-template.oss-cn-beijing.aliyuncs.com/Nodejs/icon.png\"}",
    "Content": "{\"FormatVersion\":\"OOS-2019-06-01\",\"Description\":\"Node.js environment installation\",\"Parameters\":{\"version\":{\"Type\":\"String\",\"Description\":\"Node.js version number\",\"Default\":\"v22.13.1\"}},\"Tasks\":[...]}",
    "CreatedDate": "2024-03-10T06:00:00Z",
    "UpdatedDate": "2024-07-15T12:00:00Z"
  },
  "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Content Field Parsing

The Content field is a JSON string containing the complete template definition. Key fields:

{
  "FormatVersion": "OOS-2019-06-01",
  "Description": "Template description",
  "Parameters": {
    "version": {
      "Type": "String",
      "Description": "Parameter description",
      "Default": "default value",
      "AllowedValues": ["v1", "v2"]
    }
  },
  "Tasks": [...]
}

Common Errors

---

start-execution

Start an OOS execution to install the extension.

Command

aliyun oos start-execution \
  --biz-region-id <region-id> \
  --template-name "ACS-ECS-BulkyConfigureOOSPackageWithTemporaryURL" \
  --mode "Automatic" \
  --tags "{}" \
  --parameters '<json-parameters>' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension

Parameters

Parameters Field Structure

{
  "regionId": "cn-hangzhou",
  "OOSAssumeRole": "",
  "targets": {
    "ResourceIds": ["i-bp12z30vh0wadpyv3jo3"],
    "RegionId": "cn-hangzhou",
    "Type": "ResourceIds"
  },
  "rateControl": {
    "Mode": "Concurrency",
    "Concurrency": 1,
    "MaxErrors": 0
  },
  "action": "install",
  "packageName": "ACS-Extension-node-1853370294850618",
  "packageVersion": "v27",
  "parameters": {
    "version": "v22.13.1"
  }
}

Output Example

{
  "Execution": {
    "ExecutionId": "exec-xxxxxxxxxxxxxxxx",
    "TemplateName": "ACS-ECS-BulkyConfigureOOSPackageWithTemporaryURL",
    "Status": "Running",
    "CreateDate": "2024-08-01T10:00:00Z",
    "UpdateDate": "2024-08-01T10:00:00Z",
    "Parameters": {...}
  },
  "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Output Field Description

Common Errors

---

list-executions (Auxiliary Command)

Query OOS execution status and results.

Command

aliyun oos list-executions \
  --biz-region-id <region-id> \
  --execution-id <execution-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension

Parameters

Output Example

{
  "Executions": [
    {
      "ExecutionId": "exec-xxxxxxxxxxxxxxxx",
      "TemplateName": "ACS-ECS-BulkyConfigureOOSPackageWithTemporaryURL",
      "Status": "Success",
      "StatusReason": "Execution completed successfully",
      "CreateDate": "2024-08-01T10:00:00Z",
      "UpdateDate": "2024-08-01T10:05:00Z",
      "Outputs": {
        "result": "Installation completed"
      },
      "Tasks": [
        {
          "TaskName": "installPackage",
          "Status": "Success",
          "StatusReason": "Task completed"
        }
      ]
    }
  ],
  "TotalCount": 1,
  "RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Execution Status Description

Common Errors

---

JSON Parameter Escaping Notes

When passing JSON parameters via the command line, pay attention to escaping:

Bash

# Use single quotes to wrap the entire JSON to avoid shell escaping issues
aliyun oos start-execution \
  --biz-region-id cn-hangzhou \
  --template-name "ACS-ECS-BulkyConfigureOOSPackageWithTemporaryURL" \
  --parameters '{"regionId":"cn-hangzhou","targets":{"ResourceIds":["i-xxx"],"RegionId":"cn-hangzhou","Type":"ResourceIds"},"action":"install","packageName":"ACS-Extension-node-1853370294850618","parameters":{"version":"v22.13.1"}}'

Complex Parameters

For complex parameters, it is recommended to write them to a file first:

# Write parameters to file
cat > /tmp/oos-params.json << 'EOF'
{
  "regionId": "cn-hangzhou",
  "OOSAssumeRole": "",
  "targets": {
    "ResourceIds": ["i-bp12z30vh0wadpyv3jo3"],
    "RegionId": "cn-hangzhou",
    "Type": "ResourceIds"
  },
  "rateControl": {
    "Mode": "Concurrency",
    "Concurrency": 1,
    "MaxErrors": 0
  },
  "action": "install",
  "packageName": "ACS-Extension-node-1853370294850618",
  "packageVersion": "v27",
  "parameters": {
    "version": "v22.13.1"
  }
}
EOF

# Read from file
aliyun oos start-execution \
  --biz-region-id cn-hangzhou \
  --template-name "ACS-ECS-BulkyConfigureOOSPackageWithTemporaryURL" \
  --parameters "$(cat /tmp/oos-params.json)" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-install-extension

Error Handling Best Practices

1. API Failure Retry: On RateLimit or network errors, wait 5-10 seconds and retry 2. Permission Error: Ensure required RAM permissions are granted, then use ram-permission-diagnose skill 3. Parameter Error: Carefully check JSON format and required fields 4. Instance Error: Confirm instance status is Running and the instance is in the correct region 5. Execution Failure: Use list-executions to query detailed error information; check StatusReason and Tasks fields