Alibabacloud Ecs Diagnose

ECS Instance Diagnostics Skill

You are a professional operations diagnostics assistant responsible for systematic troubleshooting of Alibaba Cloud ECS instances. Follow the two-level diagnostic workflow (Basic + Deep) strictly.

Scenario Description

This skill provides comprehensive diagnostics for Alibaba Cloud ECS instances experiencing operational issues. It combines cloud platform-side monitoring and inspection with optional in-depth guest OS diagnostics via Cloud Assistant.

Architecture: ECS + VPC + Security Group + Cloud Monitor (CMS) + Cloud Assistant

Use Cases:

• Instance unreachable / inaccessible
• SSH connection timeout or refused
• Instance performance degradation / lag
• Disk space exhaustion
• Network connectivity issues / high latency
• Abnormal instance status (Stopped, Locked, etc.)
• High CPU / memory utilization
• System event alerts

Prerequisites

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 install/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 on your local machine are always up-to-date.

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

---

Observability (MUST follow for every aliyun command)

Upon loading this skill, generate a random session ID (32-char lowercase hex string) once for the entire session. Use it as {session-id} in the User-Agent below.

Rule: Every `aliyun` CLI command that calls a cloud API MUST include the `--user-agent` flag:

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Local utility commands (e.g. configure, plugin, version) do not support this flag and must be excluded.

---

CLI Command Standards

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

>

Key Rules:

- Use kebab-case command names: run-command (not RunCommand)

- Region parameter varies by command type:

- Cloud Assistant commands: --biz-region-id

- All other commands: --region-id

- Instance ID format varies: --instance-id.1, --instance-ids '["..."]', or --instance-id

- Always include --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

[MUST] CLI User-Agent — Every aliyun CLI command invocation must include: --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Required Permissions

This skill requires the following RAM permissions:

• ecs:DescribeInstances
• ecs:DescribeInstanceAttribute
• ecs:DescribeInstanceStatus
• ecs:DescribeInstancesFullStatus
• ecs:DescribeSecurityGroupAttribute
• ecs:DescribeInstanceHistoryEvents
• vpc:DescribeVpcs
• vpc:DescribeEipAddresses
• cms:DescribeMetricLast
• ecs:RunCommand (for Deep Diagnostics)
• ecs:DescribeInvocationResults (for Deep Diagnostics)

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 command or API call,

ALL user-customizable parameters (e.g., RegionId, instance names, instance IDs,

IP addresses, etc.) MUST be confirmed with the user. Do NOT assume or use default

values without explicit user approval.

---

Phase 0: Instance Discovery (MUST run BEFORE Scenario-Based Routing)

[MUST] This phase runs first for ALL scenarios. Do NOT enter the Scenario-Based

Routing table until an instance has been successfully located. Every downstream

workflow assumes a valid instance already exists.

>

Step A — Locate the instance via ecs:DescribeInstances. If RegionId is unknown

or the first lookup is empty, traverse candidate regions.

Region-traversal method: see references/remote-connection-diagnose-design.md §1.2.

>

Step B — Check the result. Inspect TotalCount / Instances.Instance.

>

If `TotalCount > 0` → proceed to Scenario-Based Routing.

>

If `TotalCount = 0` (no ECS instance found) → execute the empty-result protocol below.

[MUST] Empty-result protocol

1. STOP. Terminate the diagnostic workflow. Do NOT proceed to routing or any

diagnostic step. An empty result is NOT a healthy system; continuing would produce

a false-negative diagnosis.

2. [FORBIDDEN] Do NOT enumerate or list other instances in the account.

[FORBIDDEN] Do NOT suggest the user "pick one of the available instances".

[FORBIDDEN] Do NOT switch to any instance the user did not specify.

Rationale: the user asked to diagnose instance A; diagnosing B is a wrong answer

and hides the real conclusion (A is hybrid-cloud / released / in another account).

3. Output the fixed message template below verbatim (adapt id/region/region-count).

4. The ONLY follow-up allowed: ask the user to re-check the original

InstanceId / RegionId for typos, or to provide another explicit, valid standard ECS instance.

Empty-result message template:

Instance <InstanceId> not found (region <RegionId>, searched <N> regions). Possible causes:
1. Non-standard Alibaba Cloud ECS: hybrid-cloud / third-party managed (TRIPARTITE) servers
   are not covered by DescribeInstances and cannot be diagnosed by this skill;
2. InstanceId / RegionId was entered incorrectly;
3. The instance has been released or belongs to another account.
This skill only supports troubleshooting of standard Alibaba Cloud ECS instances. Please
re-check the identifier and region and retry, or provide a valid standard ECS instance ID.
-> Diagnostic workflow terminated.

---

Scenario-Based Routing

IMPORTANT: Before starting diagnostics, identify the problem scenario and follow the appropriate diagnostic approach.

>

CRITICAL: The diagnostic workflow document MUST be read BEFORE executing any diagnostic commands.

This is not optional — skip this step will result in incorrect diagnosis.

Based on the user's problem description, route to the appropriate diagnostic approach:

---

Diagnostic Report Output Format

After completing diagnostics, output a report with these sections:

================== ECS Diagnostic Report ==================
【Basic Information】Instance ID, Name, Status, OS, IPs, Time
【Basic Diagnostics】Instance Status, System Events, Security Group, Network, Metrics
【Deep Diagnostics】System Load, Disk, Network, Logs, Processes
【Issue Summary】List all discovered issues
【Recommendations】Specific remediation steps
【Risk Warnings】Security risks requiring attention
===========================================================

Success Verification Method

See references/verification-method.md for detailed verification steps for each diagnostic stage.

Cleanup

This diagnostic skill does not create any cloud resources and therefore requires no cleanup operations.

Best Practices

1. Basic Diagnostics first - Cloud platform checks can quickly locate most issues (~80%) 2. Deep Diagnostics requires confirmation - Always get user approval before executing system commands 3. Security group focus - ~70% of connectivity issues stem from security group misconfigurations 4. Windows adaptation - Use PowerShell commands and RunPowerShellScript type for Windows instances 5. Security awareness - Report mining processes, abnormal connections immediately; never expose AK/SK

Reference Links

Notes

1. Prioritize read-only APIs; avoid operations that modify instance state. 2. On API failure, log error and continue with subsequent diagnostics. 3. Sensitive information (AccessKey, passwords) must never appear in reports.

Acceptance Criteria: alibabacloud-ecs-diagnose

Scenario: ECS Instance Comprehensive Diagnostics Purpose: Skill testing acceptance criteria

---

1. CLI Command Patterns

Product Validation

✅ CORRECT - Valid product names

aliyun ecs describe-instances --user-agent AlibabaCloud-Agent-Skills
aliyun vpc describe-vpcs --user-agent AlibabaCloud-Agent-Skills
aliyun cms describe-metric-last --user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT - Invalid product names

aliyun ec2 describe-instances  # Wrong: "ec2" is AWS, not Aliyun
aliyun elastic-compute describe-instances  # Wrong: Use "ecs" not full name
aliyun cloudmonitor describe-metric-last  # Wrong: Use "cms" not "cloudmonitor"

Explanation: Aliyun CLI uses abbreviated product codes, not full names or AWS equivalents.

---

Command/Action Validation

✅ CORRECT - Valid actions in plugin mode

# ECS actions
aliyun ecs describe-instances --user-agent AlibabaCloud-Agent-Skills
aliyun ecs describe-instance-attribute --user-agent AlibabaCloud-Agent-Skills
aliyun ecs describe-instance-status --user-agent AlibabaCloud-Agent-Skills
aliyun ecs describe-instance-history-events --user-agent AlibabaCloud-Agent-Skills
aliyun ecs describe-security-group-attribute --user-agent AlibabaCloud-Agent-Skills
aliyun ecs run-command --user-agent AlibabaCloud-Agent-Skills
aliyun ecs describe-invocation-results --user-agent AlibabaCloud-Agent-Skills

# VPC actions
aliyun vpc describe-vpcs --user-agent AlibabaCloud-Agent-Skills
aliyun vpc describe-eip-addresses --user-agent AlibabaCloud-Agent-Skills

# CMS actions
aliyun cms describe-metric-last --user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT - Wrong action format or non-existent actions

# Wrong: Using API-style PascalCase instead of plugin mode kebab-case
aliyun ecs DescribeInstances  # Should be: describe-instances
aliyun ecs RunCommand  # Should be: run-command

# Wrong: Non-existent actions
aliyun ecs get-instances  # Should be: describe-instances
aliyun ecs list-instances  # Should be: describe-instances
aliyun ecs show-instance  # Should be: describe-instances

Explanation: Aliyun CLI plugin mode uses lowercase kebab-case (words connected with hyphens), NOT PascalCase from API names.

---

Parameter Validation

✅ CORRECT - Valid parameter names and formats

# Instance query with correct parameters
aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --instance-ids '["i-xxxxx"]' \
  --user-agent AlibabaCloud-Agent-Skills

# Query by instance name
aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --instance-name "my-instance" \
  --user-agent AlibabaCloud-Agent-Skills

# Query by private IP
aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --private-ip-addresses '["192.168.1.10"]' \
  --user-agent AlibabaCloud-Agent-Skills

# Security group query
aliyun ecs describe-security-group-attribute \
  --region-id cn-hangzhou \
  --security-group-id sg-xxxxx \
  --direction ingress \
  --user-agent AlibabaCloud-Agent-Skills

# System events query
aliyun ecs describe-instance-history-events \
  --region-id cn-hangzhou \
  --instance-id i-xxxxx \
  --instance-event-cycle-status.1 Executing \
  --instance-event-cycle-status.2 Inquiring \
  --user-agent AlibabaCloud-Agent-Skills

# Cloud Assistant command execution
aliyun ecs run-command \
  --region-id cn-hangzhou \
  --instance-id.1 i-xxxxx \
  --type RunShellScript \
  --command-content "dXB0aW1l" \
  --timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

# Monitoring metrics query
aliyun cms describe-metric-last \
  --region-id cn-hangzhou \
  --namespace acs_ecs_dashboard \
  --metric-name CPUUtilization \
  --dimensions '[{"instanceId":"i-xxxxx"}]' \
  --user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT - Invalid parameter names or formats

# Wrong parameter names (API-style PascalCase)
aliyun ecs describe-instances \
  --RegionId cn-hangzhou \  # Should be: --region-id
  --InstanceIds '["i-xxxxx"]'  # Should be: --instance-ids

# Wrong array format for instance IDs
aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --instance-ids i-xxxxx  # Should be: '["i-xxxxx"]' (JSON array)

# Wrong multiple instance specification
aliyun ecs run-command \
  --region-id cn-hangzhou \
  --instance-ids '["i-xxxxx","i-yyyyy"]' \  # Wrong parameter name
  --type RunShellScript \
  --command-content "dXB0aW1l"

# Correct way for multiple instances
aliyun ecs run-command \
  --region-id cn-hangzhou \
  --instance-id.1 i-xxxxx \
  --instance-id.2 i-yyyyy \  # Correct: use .1, .2, .3, etc.
  --type RunShellScript \
  --command-content "dXB0aW1l"

# Wrong dimensions format
aliyun cms describe-metric-last \
  --namespace acs_ecs_dashboard \
  --metric-name CPUUtilization \
  --dimensions instanceId:i-xxxxx  # Should be: '[{"instanceId":"i-xxxxx"}]' (JSON)

Explanation: 1. Plugin mode uses kebab-case for parameter names (--region-id, not --RegionId) 2. Array parameters use JSON format with quotes 3. Repeated parameters use .1, .2, .3 suffix notation 4. Dimensions parameter requires JSON format

---

User-Agent Header

✅ CORRECT - Always include user-agent

aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --instance-ids '["i-xxxxx"]' \
  --user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT - Missing user-agent

aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --instance-ids '["i-xxxxx"]'

Explanation: All commands in this skill MUST include --user-agent AlibabaCloud-Agent-Skills for tracking and analytics.

---

2. Enum Value Validation

Instance Event Cycle Status

✅ CORRECT - Valid enum values

# Valid status values
--instance-event-cycle-status.1 Executing
--instance-event-cycle-status.2 Inquiring
--instance-event-cycle-status.3 Scheduled
--instance-event-cycle-status.4 Avoided
--instance-event-cycle-status.5 Canceled
--instance-event-cycle-status.6 Failed

❌ INCORRECT - Invalid enum values

--instance-event-cycle-status.1 Running  # Wrong: Use "Executing"
--instance-event-cycle-status.1 Pending  # Wrong: Use "Scheduled"
--instance-event-cycle-status.1 Active  # Wrong: Not a valid value

---

Security Group Direction

✅ CORRECT

--direction ingress  # Inbound rules
--direction egress   # Outbound rules

❌ INCORRECT

--direction inbound   # Wrong: Use "ingress"
--direction outbound  # Wrong: Use "egress"
--direction in        # Wrong: Use "ingress"

---

Cloud Assistant Command Type

✅ CORRECT

--type RunShellScript      # For Linux
--type RunPowerShellScript # For Windows

❌ INCORRECT

--type ShellScript        # Wrong: Add "Run" prefix
--type Bash               # Wrong: Use "RunShellScript"
--type PowerShell         # Wrong: Use "RunPowerShellScript"

---

3. Parameter Confirmation Patterns

✅ CORRECT - Confirm before use

Agent: I'll help diagnose your ECS instance. Please confirm the following parameters:
- Region ID: cn-hangzhou
- Instance ID: i-bp1234567890abcde

User: Confirmed

Agent: [Proceeds with diagnostics using the confirmed values]

❌ INCORRECT - Using hardcoded defaults

Agent: I'll diagnose the instance in cn-hangzhou region with default VPC settings.
[Proceeds without user confirmation]

Explanation: All user-specific parameters (RegionId, InstanceId, etc.) must be confirmed with the user before execution.

---

4. Credential Handling Patterns

✅ CORRECT - Check credential status only

# Check if credentials are configured
aliyun configure list

❌ INCORRECT - Reading or displaying credentials

# NEVER do this - reads credential values
echo $ALIBABA_CLOUD_ACCESS_KEY_ID
cat ~/.aliyun/config.json
aliyun configure get

# NEVER ask user to input credentials directly
read -p "Enter your AccessKey ID: " AK

Explanation: For security, NEVER read, display, or ask users to input AccessKey/SecretKey directly. Only check if credentials exist.

---

5. Output Handling Patterns

Base64 Decoding for Cloud Assistant

✅ CORRECT - Decode output properly

# Get invocation result and decode
aliyun ecs describe-invocation-results \
  --region-id cn-hangzhou \
  --invoke-id t-xxxxx \
  --user-agent AlibabaCloud-Agent-Skills \
  | jq -r '.Invocation.InvocationResults.InvocationResult[0].Output' \
  | base64 -d

❌ INCORRECT - Display without decoding

# Wrong: Shows Base64 encoded string
aliyun ecs describe-invocation-results \
  --region-id cn-hangzhou \
  --invoke-id t-xxxxx \
  --user-agent AlibabaCloud-Agent-Skills \
  | jq -r '.Invocation.InvocationResults.InvocationResult[0].Output'

---

Base64 Encoding for Command Content

✅ CORRECT - Encode commands before sending

# Encode command content
COMMAND=$(echo 'df -h' | base64)

aliyun ecs run-command \
  --region-id cn-hangzhou \
  --instance-id.1 i-xxxxx \
  --type RunShellScript \
  --command-content "$COMMAND" \
  --timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT - Send plain text commands

# Wrong: Command content must be Base64 encoded
aliyun ecs run-command \
  --region-id cn-hangzhou \
  --instance-id.1 i-xxxxx \
  --type RunShellScript \
  --command-content "df -h" \
  --timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

---

6. Error Handling Patterns

Permission Errors

✅ CORRECT - Handle permission failures

Error: Forbidden.RAM - User not authorized to operate on the specified resource

Action:
1. Read references/ram-policies.md
2. Inform user of required permissions
3. Wait for user to grant permissions
4. Retry after confirmation

❌ INCORRECT - Ignore or skip

Error: Forbidden.RAM

Action: Skip this check and continue

---

Invalid Instance ID

✅ CORRECT - Validate and inform

Error: InvalidInstanceId.NotFound

Action:
1. Inform user the instance ID does not exist in the specified region
2. Ask user to verify the instance ID and region
3. Suggest checking the console or listing instances

❌ INCORRECT - Assume and guess

Error: InvalidInstanceId.NotFound

Action: Try with a different region automatically

---

7. Workflow Execution Patterns

Basic and Deep Diagnostics Separation

✅ CORRECT - Execute Basic Diagnostics first, ask for Deep Diagnostics

1. Execute all Basic Diagnostics (read-only APIs)
2. Present Basic Diagnostics results to user
3. Ask: "Would you like to proceed with Deep Diagnostics (System & Service Checks)?"
4. If yes, execute Deep Diagnostics commands

❌ INCORRECT - Execute everything without asking

1. Execute Basic Diagnostics
2. Automatically execute Deep Diagnostics
3. Present all results

Explanation: Deep Diagnostics execute commands inside the instance and require explicit user consent.

---

Command Execution Order

✅ CORRECT - Follow diagnostic workflow

Basic Diagnostics:
1. Identify instance
2. Check instance status
3. Query system events
4. Check security groups
5. Check network config
6. Query monitoring data
7. Present summary and ask for Deep Diagnostics

Deep Diagnostics (if approved):
7. System load diagnostics
8. Disk usage diagnostics
9. Network connectivity diagnostics
10. System log diagnostics
11. Process status diagnostics
12. Present final report

❌ INCORRECT - Random order or skipping steps

1. Query monitoring data
2. Check security groups
3. Skip instance status check
4. Execute Deep Diagnostics without asking

---

8. Regional Parameters

✅ CORRECT - Always specify region

aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --instance-ids '["i-xxxxx"]' \
  --user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT - Omit region or use wrong format

# Missing region
aliyun ecs describe-instances \
  --instance-ids '["i-xxxxx"]' \
  --user-agent AlibabaCloud-Agent-Skills

# Wrong region format
aliyun ecs describe-instances \
  --region hangzhou \  # Should be: cn-hangzhou
  --instance-ids '["i-xxxxx"]' \
  --user-agent AlibabaCloud-Agent-Skills

Explanation: Region ID is required for most ECS/VPC APIs and must use the full format (e.g., cn-hangzhou, not hangzhou).

---

9. JSON Output Parsing

✅ CORRECT - Use jq for reliable parsing

# Extract instance ID
aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --instance-name "my-instance" \
  --user-agent AlibabaCloud-Agent-Skills \
  | jq -r '.Instances.Instance[0].InstanceId'

# Extract CPU utilization value
aliyun cms describe-metric-last \
  --namespace acs_ecs_dashboard \
  --metric-name CPUUtilization \
  --dimensions '[{"instanceId":"i-xxxxx"}]' \
  --user-agent AlibabaCloud-Agent-Skills \
  | jq -r '.Datapoints' | jq -r '.[0].Average'

❌ INCORRECT - Use grep/sed/awk on JSON

# Wrong: Fragile parsing
aliyun ecs describe-instances --region-id cn-hangzhou \
  | grep InstanceId | cut -d'"' -f4

Explanation: Always use jq for JSON parsing to ensure reliability and correctness.

---

10. Timeout and Retry Patterns

Cloud Assistant Command Timeout

✅ CORRECT - Set appropriate timeout

# Short command: 30-60 seconds
aliyun ecs run-command \
  --region-id cn-hangzhou \
  --instance-id.1 i-xxxxx \
  --type RunShellScript \
  --command-content "$(echo 'uptime' | base64)" \
  --timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills

# Long command: 120-600 seconds
aliyun ecs run-command \
  --region-id cn-hangzhou \
  --instance-id.1 i-xxxxx \
  --type RunShellScript \
  --command-content "$(echo 'du -sh /*' | base64)" \
  --timeout 600 \
  --user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT - No timeout or too short

# Missing timeout (may use default)
aliyun ecs run-command \
  --region-id cn-hangzhou \
  --instance-id.1 i-xxxxx \
  --type RunShellScript \
  --command-content "$(echo 'du -sh /*' | base64)" \
  --user-agent AlibabaCloud-Agent-Skills

# Timeout too short for long operation
aliyun ecs run-command \
  --region-id cn-hangzhou \
  --instance-id.1 i-xxxxx \
  --type RunShellScript \
  --command-content "$(echo 'find / -name "*.log"' | base64)" \
  --timeout 10 \  # Too short!
  --user-agent AlibabaCloud-Agent-Skills

---

Testing Checklist

Before considering the skill complete, verify:

• [ ] All CLI commands use plugin mode format (kebab-case)
• [ ] All commands include --user-agent AlibabaCloud-Agent-Skills
• [ ] All parameters use correct naming (kebab-case, not PascalCase)
• [ ] Array parameters use correct JSON format
• [ ] Enum values are valid and correct
• [ ] Region ID is always specified
• [ ] User parameters are confirmed before execution
• [ ] Credentials are checked via aliyun configure list only
• [ ] Cloud Assistant output is Base64 decoded
• [ ] Cloud Assistant input is Base64 encoded
• [ ] Basic and Deep Diagnostics are properly separated
• [ ] Permission errors trigger help workflow
• [ ] JSON output parsed with jq
• [ ] Appropriate timeouts set for commands
• [ ] Diagnostic report follows template format

---

Related Documentation

• Aliyun CLI Plugin Mode
• ECS API Reference
• Cloud Assistant Documentation
• Cloud Monitor Metrics

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.

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

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": "华东 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

# 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.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 for ECS Diagnostics Skill

This document lists all RAM permissions required by the alibabacloud-ecs-diagnose skill.

Required Permissions

Basic Diagnostics: Cloud Platform Checks (Read-Only)

Deep Diagnostics: System & Service Checks

Policy JSON Template

Minimum Read-Only Policy (Basic Diagnostics Only)

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecs:DescribeInstances",
        "ecs:DescribeInstanceAttribute",
        "ecs:DescribeInstanceStatus",
        "ecs:DescribeInstancesFullStatus",
        "ecs:DescribeInstanceHistoryEvents",
        "ecs:DescribeSecurityGroupAttribute"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "vpc:DescribeVpcs",
        "vpc:DescribeEipAddresses"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "cms:DescribeMetricLast"
      ],
      "Resource": "*"
    }
  ]
}

Full Diagnostics Policy (Basic + Deep)

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecs:DescribeInstances",
        "ecs:DescribeInstanceAttribute",
        "ecs:DescribeInstanceStatus",
        "ecs:DescribeInstancesFullStatus",
        "ecs:DescribeInstanceHistoryEvents",
        "ecs:DescribeSecurityGroupAttribute",
        "ecs:RunCommand",
        "ecs:DescribeInvocationResults"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "vpc:DescribeVpcs",
        "vpc:DescribeEipAddresses"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "cms:DescribeMetricLast"
      ],
      "Resource": "*"
    }
  ]
}

Applying Permissions

Option 1: Using RAM Console (Recommended for Production)

1. Log in to RAM Console 2. Navigate to Policies → Create Policy 3. Choose JSON mode 4. Copy the appropriate policy JSON above 5. Save the policy with name: ECS-Diagnostics-Policy 6. Navigate to Users or Roles 7. Attach the ECS-Diagnostics-Policy to the target user/role

Option 2: Using Aliyun CLI

Create policy file ecs-diagnostics-policy.json with the JSON above, then:

# Create the policy
aliyun ram create-policy \
  --policy-name ECS-Diagnostics-Policy \
  --policy-document file://ecs-diagnostics-policy.json \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Attach to a user
aliyun ram attach-policy-to-user \
  --policy-name ECS-Diagnostics-Policy \
  --policy-type Custom \
  --user-name <your-ram-user-name> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Attach to a role
aliyun ram attach-policy-to-role \
  --policy-name ECS-Diagnostics-Policy \
  --policy-type Custom \
  --role-name <your-ram-role-name> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Least Privilege Principle

• If you only need Basic Diagnostics, use the Minimum Read-Only Policy
• If you need both Basic and Deep Diagnostics, use the Full Diagnostics Policy
• Never grant more permissions than necessary
• Regularly audit and review permission usage

Permission Verification

After applying permissions, verify they work correctly:

# Test ECS read permission
aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --page-size 1 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Test VPC read permission
aliyun vpc describe-vpcs \
  --region-id cn-hangzhou \
  --page-size 1 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Test CMS read permission
aliyun cms describe-metric-last \
  --namespace acs_ecs_dashboard \
  --metric-name CPUUtilization \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Test Cloud Assistant permission (only if Deep Diagnostics is needed)
aliyun ecs describe-invocation-results \
  --region-id cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Troubleshooting Permission Issues

Error: "Forbidden.RAM"

Cause: Current account lacks required permissions

Solution: 1. Check which API action failed 2. Verify the corresponding permission exists in your policy 3. Re-attach the policy or add missing permissions

Error: "InvalidAccessKeyId.NotFound"

Cause: Invalid or deleted AccessKey

Solution: Reconfigure credentials using aliyun configure

Error: "Forbidden.Risk"

Cause: Account locked due to security risk

Solution: Contact Alibaba Cloud support to unlock account

Security Best Practices

1. Use RAM users instead of root account for daily operations 2. Enable MFA (Multi-Factor Authentication) for sensitive operations 3. Rotate AccessKeys regularly (recommended every 90 days) 4. Use RAM roles for applications running on ECS instances 5. Audit permission usage via ActionTrail logs 6. Apply IP restrictions if accessing from fixed locations 7. Use resource-level permissions when possible (though this skill requires * for flexibility)

Related Links

• RAM Product Documentation
• ECS API Reference
• VPC API Reference
• Cloud Monitor API Reference

Related CLI Commands

This document provides a comprehensive reference of all Aliyun CLI commands used in the ECS diagnostics skill.

---

CLI Command Standards

CRITICAL: All CLI commands MUST follow these standards to avoid parameter errors.

General Rules

Region Parameter (Command-Specific)

Instance ID Parameter (Command-Specific)

---

Cloud Assistant Commands (use --biz-region-id)

RunCommand Standard Format

# Linux instance
aliyun ecs run-command \
  --biz-region-id <region-id> \
  --instance-id.1 <instance-id> \
  --type RunShellScript \
  --command-content '<base64-encoded-command>' \
  --timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Windows instance
aliyun ecs run-command \
  --biz-region-id <region-id> \
  --instance-id.1 <instance-id> \
  --type RunPowerShellScript \
  --command-content '<base64-encoded-command>' \
  --timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Query Invocation Results

aliyun ecs describe-invocation-results \
  --biz-region-id <region-id> \
  --invoke-id <invoke-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Note: The Output field in response is Base64 encoded. Decode before analysis.

---

ECS Commands (use --region-id)

Instance Query Commands

System Event Commands

Security Group Commands

Security Group Rule Operations

Add ingress rule (allow SSH from specific IP):

aliyun ecs authorize-security-group \
  --region-id cn-hangzhou \
  --security-group-id sg-xxxxx \
  --ip-protocol tcp \
  --port-range 22/22 \
  --source-cidr-ip 1.2.3.4/32 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Add ingress rule (allow HTTP from anywhere):

aliyun ecs authorize-security-group \
  --region-id cn-hangzhou \
  --security-group-id sg-xxxxx \
  --ip-protocol tcp \
  --port-range 80/80 \
  --source-cidr-ip 0.0.0.0/0 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Remove ingress rule (MUST specify all matching parameters):

aliyun ecs revoke-security-group \
  --region-id cn-hangzhou \
  --security-group-id sg-xxxxx \
  --ip-protocol tcp \
  --port-range 22/22 \
  --source-cidr-ip 0.0.0.0/0 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Important: When revoking a security group rule, you MUST specify --ip-protocol, --port-range, and --source-cidr-ip (or --source-group-id). Using --security-group-rule-id alone will fail.

Cloud Assistant Commands

VPC Commands (use --region-id)

VPC Query Commands

EIP Commands

Cloud Monitor (CMS) Commands (use --region-id)

Monitoring Metrics Commands

Common Monitoring Metrics

Common Command Patterns

Query Instance by Different Identifiers

By Instance ID:

aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --instance-ids '["i-xxxxx","i-yyyyy"]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

By Instance Name:

aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --instance-name "my-instance" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

By Private IP:

aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --private-ip-addresses '["192.168.1.10"]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

By Public IP:

aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --public-ip-addresses '["47.100.1.1"]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

By VPC ID:

aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --vpc-id vpc-xxxxx \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

By Security Group ID:

aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --security-group-id sg-xxxxx \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Execute Cloud Assistant Commands

Execute Shell script (Linux):

aliyun ecs run-command \
  --biz-region-id cn-hangzhou \
  --instance-id.1 i-xxxxx \
  --type RunShellScript \
  --command-content "$(echo 'df -h' | base64)" \
  --timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Execute PowerShell script (Windows):

aliyun ecs run-command \
  --biz-region-id cn-hangzhou \
  --instance-id.1 i-xxxxx \
  --type RunPowerShellScript \
  --command-content "$(echo 'Get-Volume' | base64)" \
  --timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Execute with parameters:

aliyun ecs run-command \
  --biz-region-id cn-hangzhou \
  --instance-id.1 i-xxxxx \
  --type RunShellScript \
  --command-content "$(echo 'echo {{param1}} {{param2}}' | base64)" \
  --parameters '{"param1":"value1","param2":"value2"}' \
  --timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Execute on multiple instances:

aliyun ecs run-command \
  --biz-region-id cn-hangzhou \
  --instance-id.1 i-xxxxx \
  --instance-id.2 i-yyyyy \
  --instance-id.3 i-zzzzz \
  --type RunShellScript \
  --command-content "$(echo 'uptime' | base64)" \
  --timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Query Monitoring with Time Range

Last 15 minutes:

aliyun cms describe-metric-list \
  --region-id cn-hangzhou \
  --namespace acs_ecs_dashboard \
  --metric-name CPUUtilization \
  --dimensions '[{"instanceId":"i-xxxxx"}]' \
  --start-time $(date -d '15 minutes ago' +%s)000 \
  --end-time $(date +%s)000 \
  --period 60 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Last 1 hour:

aliyun cms describe-metric-list \
  --region-id cn-hangzhou \
  --namespace acs_ecs_dashboard \
  --metric-name CPUUtilization \
  --dimensions '[{"instanceId":"i-xxxxx"}]' \
  --start-time $(date -d '1 hour ago' +%s)000 \
  --end-time $(date +%s)000 \
  --period 300 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Advanced Usage

Pagination

When results exceed page limit, use pagination:

# First page
aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --page-size 50 \
  --page-number 1 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Second page
aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --page-size 50 \
  --page-number 2 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Output Formatting

JSON format (default):

aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --instance-ids '["i-xxxxx"]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Table format:

aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --instance-ids '["i-xxxxx"]' \
  --output table \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Extract specific fields with jq:

aliyun ecs describe-instances \
  --region-id cn-hangzhou \
  --instance-ids '["i-xxxxx"]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq '.Instances.Instance[0].InstanceId'

Troubleshooting Commands

Check Cloud Assistant Status

# Check if Cloud Assistant is installed
aliyun ecs describe-cloud-assistant-status \
  --region-id cn-hangzhou \
  --instance-id.1 i-xxxxx \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# List Cloud Assistant agents
aliyun ecs describe-instance-attribute \
  --region-id cn-hangzhou \
  --instance-id i-xxxxx \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq '.CloudAssistantStatus'

Check Recent Failed Commands

aliyun ecs describe-invocations \
  --biz-region-id cn-hangzhou \
  --instance-id i-xxxxx \
  --invocation-status Failed \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

View Command Output in Detail

aliyun ecs describe-invocation-results \
  --biz-region-id cn-hangzhou \
  --invoke-id t-xxxxx \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Invocation.InvocationResults.InvocationResult[0].Output' \
  | base64 -d

Reference Links

• ECS API Reference
• VPC API Reference
• Cloud Monitor API Reference
• Cloud Assistant Documentation
• Aliyun CLI Documentation

Alibaba Cloud ECS Remote Connection / Service Access Diagnostic Guide

Overview

This guide provides a systematic diagnostic workflow for Alibaba Cloud ECS remote connection issues, applicable to scenarios such as SSH/RDP failures and inaccessible services.

---

1. Problem Localization Strategy

1.1 Initial Information Gathering

When a user reports "cannot remotely connect to an ECS instance" or "service is inaccessible", use a progressive information-gathering strategy:

Step 1: Ask for key information

✩ Instance ID (required) — format: i-xxxxxxxxxxxxxxxxx ✩ Region (required) — e.g., cn-hangzhou, cn-beijing, cn-shanghai ✩ Connection method — SSH(22) / RDP(3389) / VNC / other ports / Workbench / Web service ✩ Error message or symptom description

Rationale:

✫ Avoid blind guessing; gather the minimum necessary information ✫ Provide a common-issues checklist so the user can do initial self-triage ✫ If the user provides only partial information, proactively request what is missing

1.2 Adaptive Lookup

When the user says "find it for me" or the information is incomplete, switch strategy immediately:

✩ Traverse common Alibaba Cloud regions to locate the instance ✩ Prioritize high-frequency regions: cn-hangzhou, cn-beijing, cn-shanghai, cn-shenzhen ✩ Stop searching as soon as the instance is found

⚠️ Empty-result handling ([MUST]): If describe-instances still returns an empty

result after traversing the candidate regions (TotalCount = 0), **follow the

"Empty-result protocol" in Phase 0 of SKILL.md** strictly (terminate the workflow,

do NOT enumerate/switch instances, output the fixed message template). This document

does not repeat the rule, to keep a single source of truth.

Region-traversal commands:

# Get the list of all regions
aliyun ecs describe-regions --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Look up the instance in a specific region
aliyun ecs describe-instances \
  --biz-region-id cn-hangzhou \
  --instance-ids '["i-xxx"]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

---

2. Systematic Diagnostic Workflow

2.1 Layered Diagnostic Model

Layer 1: Instance basic status
  ├─ Whether the instance exists
  ├─ Instance running status (Running/Stopped/Pending/Starting/Stopping)
  └─ System status check (StatusKey)

Layer 2: Network reachability
  ├─ Whether a public IP / Elastic IP (EIP) exists
  ├─ VPC / VSwitch configuration
  └─ Route tables and NAT gateway

Layer 3: Security control
  ├─ Security group inbound rules ⭐ most common issue
  ├─ Network ACL rules (Enterprise Edition VPC)
  └─ OS firewall (iptables/firewalld/Windows Firewall)

Layer 4: Authentication configuration
  ├─ Key pair configuration (Linux SSH)
  ├─ Login password (Linux/Windows)
  └─ Username correctness (root/ecs-user/Administrator)

2.2 Diagnostic Execution Order

Step 1: Get complete instance information

aliyun ecs describe-instances \
  --biz-region-id <region> \
  --instance-ids '["<instance-id>"]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

A single call returns:

✫ Running status (Status) ✫ Public IP (PublicIpAddress) ✫ Elastic IP (EipAddress) ✫ Security group ID list (SecurityGroupIds) ✫ VPC / VSwitch ID (VpcAttributes) ✫ Key pair name (KeyPairName) ✫ Operating system type (OSType: linux/windows)

Key field parsing:

{
  "Status": "Running",
  "PublicIpAddress": {"IpAddress": ["47.xx.xx.xx"]},
  "EipAddress": {"IpAddress": "47.xx.xx.xx"},
  "SecurityGroupIds": {"SecurityGroupId": ["sg-xxx"]},
  "VpcAttributes": {
    "VpcId": "vpc-xxx",
    "VSwitchId": "vsw-xxx",
    "PrivateIpAddress": {"IpAddress": ["192.168.x.x"]}
  },
  "KeyPairName": "my-keypair",
  "OSType": "linux"
}

Step 2: Check security group rules

# Query security group inbound rules
aliyun ecs describe-security-group-attribute \
  --biz-region-id <region> \
  --security-group-id <sg-id> \
  --direction ingress \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Focus on:

✫ Whether SSH port 22 (Linux) or RDP port 3389 (Windows) is open ✫ Whether the target service port is open (e.g., 80, 443, 8080) ✫ Whether the authorization object (SourceCidrIp) includes the user's IP or 0.0.0.0/0

Security group rule response example:

{
  "Permissions": {
    "Permission": [
      {
        "PortRange": "22/22",
        "SourceCidrIp": "0.0.0.0/0",
        "IpProtocol": "TCP",
        "Policy": "Accept",
        "Direction": "ingress"
      }
    ]
  }
}

Step 3: Check instance system status

# Check instance status
aliyun ecs describe-instance-status \
  --biz-region-id <region> \
  --instance-id.1 <instance-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Check system events (planned maintenance, anomalies, etc.)
aliyun ecs describe-instance-history-events \
  --biz-region-id <region> \
  --instance-id <instance-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Step 4: Check Cloud Assistant status (backup connection method)

aliyun ecs describe-cloud-assistant-status \
  --biz-region-id <region> \
  --instance-id.1 <instance-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Step 5: Provide solutions based on findings

---

3. Problem Identification Logic

3.1 Typical Diagnostic Result Example

Instance status check:
  ✓ Status: Running
  ✓ PublicIp: 47.xx.xx.xx
  ✓ KeyPairName: my-keypair

Security group rule check:
  ✓ 80/80 TCP - 0.0.0.0/0 (HTTP)
  ✓ 443/443 TCP - 0.0.0.0/0 (HTTPS)
  ❌ Missing 22/22 TCP (SSH) inbound rule

Diagnostic conclusion: Security group does not open the SSH port → this is the root cause of 80% of connection issues.

3.2 Common Problem Patterns and Priority

---

4. Solution Library

4.1 Add Security Group Rules

Add SSH access rule (Linux):

# Temporary option - allow all IPs (not recommended for production)
aliyun ecs authorize-security-group \
  --biz-region-id <region> \
  --security-group-id <sg-id> \
  --ip-protocol tcp \
  --port-range 22/22 \
  --source-cidr-ip 0.0.0.0/0 \
  --description "SSH access - temporary" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Recommended option - restrict to a specific IP
aliyun ecs authorize-security-group \
  --biz-region-id <region> \
  --security-group-id <sg-id> \
  --ip-protocol tcp \
  --port-range 22/22 \
  --source-cidr-ip <user-ip>/32 \
  --description "SSH access - specific IP" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Add RDP access rule (Windows):

aliyun ecs authorize-security-group \
  --biz-region-id <region> \
  --security-group-id <sg-id> \
  --ip-protocol tcp \
  --port-range 3389/3389 \
  --source-cidr-ip <user-ip>/32 \
  --description "RDP remote desktop access" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Add Web service ports:

# HTTP 80
aliyun ecs authorize-security-group \
  --biz-region-id <region> \
  --security-group-id <sg-id> \
  --ip-protocol tcp \
  --port-range 80/80 \
  --source-cidr-ip 0.0.0.0/0 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# HTTPS 443
aliyun ecs authorize-security-group \
  --biz-region-id <region> \
  --security-group-id <sg-id> \
  --ip-protocol tcp \
  --port-range 443/443 \
  --source-cidr-ip 0.0.0.0/0 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

4.2 Solution for Instance Without Public IP

Option A: Bind an Elastic IP

# 1. Create an EIP
aliyun vpc allocate-eip-address \
  --biz-region-id <region> \
  --bandwidth 5 \
  --internet-charge-type PayByTraffic \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# 2. Bind the EIP to the instance
aliyun vpc associate-eip-address \
  --biz-region-id <region> \
  --allocation-id <eip-allocation-id> \
  --instance-id <instance-id> \
  --instance-type EcsInstance \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Option B: Use a NAT gateway (private-network instance)

# Query NAT gateways
aliyun vpc describe-nat-gateways \
  --biz-region-id <region> \
  --vpc-id <vpc-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

4.3 Solution for Instance Not Running

# Start the instance
aliyun ecs start-instance \
  --instance-id <instance-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Check startup status
aliyun ecs describe-instance-status \
  --biz-region-id <region> \
  --instance-id.1 <instance-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

4.4 Password Reset (when login is impossible)

# Reset password (requires a reboot to take effect)
aliyun ecs modify-instance-attribute \
  --instance-id <instance-id> \
  --password '<NewPassword123!>' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Reboot the instance to apply the new password
aliyun ecs reboot-instance \
  --instance-id <instance-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

4.5 Connect via Cloud Assistant (backup option)

When neither SSH nor RDP is usable:

# 1. Check Cloud Assistant status
aliyun ecs describe-cloud-assistant-status \
  --biz-region-id <region> \
  --instance-id.1 <instance-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# 2. Send a diagnostic command (command content must be Base64-encoded)
aliyun ecs run-command \
  --biz-region-id <region> \
  --instance-id.1 <instance-id> \
  --type RunShellScript \
  --command-content '<base64-encoded-command>' \
  --timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# 3. View command execution results
aliyun ecs describe-invocation-results \
  --biz-region-id <region> \
  --invoke-id <invoke-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

4.6 Use the VNC Console (last resort)

Via the Alibaba Cloud console: ✩ Log in to the ECS console ✩ Find the target instance → Remote Connect → VNC connection ✩ Log in with the VNC password to perform internal diagnostics

---

5. Verification Strategy

5.1 Multi-Layer Verification

Verification 1: Configuration layer

# Confirm the security group rule has been added
aliyun ecs describe-security-group-attribute \
  --biz-region-id <region> \
  --security-group-id <sg-id> \
  --direction ingress \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

Verification 2: Network layer

# Test port reachability (10s timeout)
nc -zv -w 10 <public-ip> 22

# Or wrap telnet with timeout (10s timeout)
timeout 10 telnet <public-ip> 22

Verification 3: Application layer

# SSH connection test (10s timeout)
ssh -o ConnectTimeout=10 -i <key-file> root@<public-ip>

# RDP connection test (Windows) - use a remote desktop client or PowerShell
Test-NetConnection -ComputerName <public-ip> -Port 3389 -InformationLevel Detailed

5.2 Problem-Transfer Handling

Process for handling newly discovered issues:

SSH port is open but connection still fails
    ↓
Check the OS firewall
    ↓
Run via Cloud Assistant: iptables -L / firewall-cmd --list-all
    ↓
Found iptables blocking → provide disable/configure commands
    ↓
Verify the connection

---

6. User Interaction Design Principles

6.1 Progressive Disclosure

Stage 1: Quick diagnosis ✫ Start acting without waiting for the user to provide all information ✫ User says "find it for me" → immediately auto-search common regions

Stage 2: Problem presentation

Diagnostic result:
✓ Instance status: Running
✓ Public IP: 47.xx.xx.xx
✓ Cloud Assistant: installed
❌ Security group does not open port 22 ← root cause

Stage 3: Solution ✫ Provide concrete CLI commands ✫ Ask whether to execute them ✫ Give security recommendations

6.2 Operation Confirmation Rules

Operations requiring user confirmation: ✩ Modify security group rules ✩ Reboot the instance ✩ Reset the password ✩ Bind/unbind an EIP

Operations that can run automatically: ✩ Query instance information ✩ Check configuration status ✩ Test port connectivity ✩ Check Cloud Assistant status

6.3 Security Reminder

⚠️ Security recommendation:
The current configuration allows access from all IPs (0.0.0.0/0). Recommendations:
1. Restrict the source IP to your actual IP address
2. Your current public IP is: <obtained via API>
3. Recommended command: --SourceCidrIp <your-ip>/32

---

7. Parallel Diagnostics Optimization

7.1 Checks That Can Run in Parallel

# The following checks can run simultaneously:
Parallel task 1: aliyun ecs describe-instances ... --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}        # Instance status
Parallel task 2: aliyun ecs describe-security-group-attribute ... --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}  # Security group
Parallel task 3: aliyun ecs describe-cloud-assistant-status ... --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}    # Cloud Assistant
Parallel task 4: nc -zv -w 10 <ip> 22                    # Port test (10s timeout)

7.2 Smart Recommendation

Infer the required ports from the instance name/tags:

---

8. Common CLI Command Quick Reference

8.1 Instance Operations

# Query instance details
aliyun ecs describe-instances \
  --biz-region-id <region> \
  --instance-ids '["<id>"]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Query instance status
aliyun ecs describe-instance-status \
  --biz-region-id <region> \
  --instance-id.1 <id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Start instance
aliyun ecs start-instance \
  --instance-id <id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Stop instance
aliyun ecs stop-instance \
  --instance-id <id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Reboot instance
aliyun ecs reboot-instance \
  --instance-id <id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

8.2 Security Group Operations

# Query the security groups associated with the instance
aliyun ecs describe-security-groups \
  --biz-region-id <region> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Query security group rules
aliyun ecs describe-security-group-attribute \
  --biz-region-id <region> \
  --security-group-id <sg-id> \
  --direction ingress \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Add an inbound rule
aliyun ecs authorize-security-group \
  --biz-region-id <region> \
  --security-group-id <sg-id> \
  --ip-protocol tcp \
  --port-range <port>/<port> \
  --source-cidr-ip <cidr> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Delete an inbound rule
aliyun ecs revoke-security-group \
  --biz-region-id <region> \
  --security-group-id <sg-id> \
  --ip-protocol tcp \
  --port-range <port>/<port> \
  --source-cidr-ip <cidr> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

8.3 Network Operations

# Query EIPs
aliyun vpc describe-eip-addresses \
  --biz-region-id <region> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Allocate an EIP
aliyun vpc allocate-eip-address \
  --biz-region-id <region> \
  --bandwidth 5 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Bind an EIP
aliyun vpc associate-eip-address \
  --biz-region-id <region> \
  --allocation-id <eip-id> \
  --instance-id <instance-id> \
  --instance-type EcsInstance \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Unbind an EIP
aliyun vpc unassociate-eip-address \
  --allocation-id <eip-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

8.4 Cloud Assistant Operations

# Check Cloud Assistant status
aliyun ecs describe-cloud-assistant-status \
  --biz-region-id <region> \
  --instance-id.1 <id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Run a Shell command (Linux) - command content must be Base64-encoded
aliyun ecs run-command \
  --biz-region-id <region> \
  --instance-id.1 <id> \
  --type RunShellScript \
  --command-content '<base64-encoded-command>' \
  --timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# Run a PowerShell command (Windows) - command content must be Base64-encoded
aliyun ecs run-command \
  --biz-region-id <region> \
  --instance-id.1 <id> \
  --type RunPowerShellScript \
  --command-content '<base64-encoded-command>' \
  --timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

# View command execution results
aliyun ecs describe-invocation-results \
  --biz-region-id <region> \
  --invoke-id <invoke-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id}

---

9. Diagnostic Decision Tree

Start diagnosis
    │
    ▼
Does the instance exist? ──No──► Check that the instance ID and region are correct
    │Yes
    ▼
Is the instance Running? ──No──► Start the instance
    │Yes
    ▼
Does it have a public IP/EIP? ──No──► Bind an EIP or configure NAT
    │Yes
    ▼
Does the security group open the target port? ──No──► Add a security group rule
    │Yes
    ▼
Is the port reachable (nc/telnet)? ──No──► Check the OS firewall (iptables/firewalld)
    │Yes
    ▼
Is the SSH/RDP service running? ──No──► Start the service via Cloud Assistant
    │Yes
    ▼
Are the key/password correct? ──No──► Reset the password or replace the key
    │Yes
    ▼
Connection succeeds ✓

---

10. Summary

This diagnostic workflow embodies:

✩ Systematic thinking: a layered diagnostic model, troubleshooting from outside in ✩ Efficiency first: minimal information gathering, fastest problem localization ✩ User-friendly: proactive action, clear feedback, offering choices ✩ Security awareness: balancing convenience and security ✩ Fault-tolerant design: automatically adjusting strategy on new issues, providing backups

Verification Methods for ECS Diagnostics

This document provides detailed verification steps to confirm the success of each diagnostic stage in the ECS diagnostics workflow.

Basic Diagnostics: Cloud Platform Checks Verification

Step 1: Instance Identification Verification

Success Criteria:

• Command returns HTTP 200 status
• Response contains Instances.Instance array with at least one element
• Instance details include required fields: InstanceId, Status, InstanceName

Verification Command:

aliyun ecs describe-instances \
  --region-id <region-id> \
  --instance-ids '["<instance-id>"]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq '.Instances.Instance | length'

Expected Output: A number >= 1

Failure Indicators:

• Error: InvalidInstanceId.NotFound - Instance ID does not exist in specified region
• Error: Forbidden.RAM - Insufficient permissions
• Output: 0 - No instances found matching criteria

---

Step 2: Instance Status Verification

Success Criteria:

• Status field is present in response
• Status value is one of: Running, Stopped, Starting, Stopping, Expired, Locked

Verification Command:

aliyun ecs describe-instances \
  --region-id <region-id> \
  --instance-ids '["<instance-id>"]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Instances.Instance[0].Status'

Expected Output: One of the valid status values

Status Interpretation:

• Running ✅ - Instance is operational
• Stopped ⚠️ - Instance is shut down
• Starting ⏳ - Instance is booting
• Stopping ⏳ - Instance is shutting down
• Expired ❌ - Instance subscription has expired
• Locked ❌ - Instance is locked due to security or payment issues

---

Step 3: System Events Verification

Success Criteria:

• Command executes successfully
• Response contains InstanceSystemEventSet.InstanceSystemEventType array
• Each event has EventCycleStatus, EventType, NotBefore fields

Verification Command:

aliyun ecs describe-instance-history-events \
  --region-id <region-id> \
  --instance-id <instance-id> \
  --instance-event-cycle-status.1 Executing \
  --instance-event-cycle-status.2 Inquiring \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq '.InstanceSystemEventSet.InstanceSystemEventType | length'

Expected Output:

• 0 - No active events (good)
• >0 - Active events present (requires attention)

Event Impact Assessment:

• SystemMaintenance.Reboot ⚠️ - System maintenance reboot scheduled
• SystemFailure.Reboot ❌ - System failure recovery reboot
• InstanceFailure.Reboot ❌ - Instance failure recovery reboot
• SystemMaintenance.Stop ⚠️ - Planned maintenance shutdown
• SystemMaintenance.Redeploy ⚠️ - Instance migration scheduled

---

Step 4: Security Group Rules Verification

Success Criteria:

• Command returns security group permissions array
• Response contains Permissions.Permission with rules
• Each rule has Direction, IpProtocol, PortRange, Policy fields

Verification Command:

aliyun ecs describe-security-group-attribute \
  --region-id <region-id> \
  --security-group-id <sg-id> \
  --direction ingress \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq '.Permissions.Permission | length'

Expected Output: Number of rules >= 0

Key Checks:

• ✅ SSH (port 22) allowed from trusted IPs for Linux instances
• ✅ RDP (port 3389) allowed from trusted IPs for Windows instances
• ✅ Application ports allowed as needed
• ⚠️ No overly permissive rules (0.0.0.0/0 on all ports)
• ❌ No explicit Drop rules blocking required traffic

Rule Validation Example:

# Check if SSH port 22 is open
aliyun ecs describe-security-group-attribute \
  --region-id <region-id> \
  --security-group-id <sg-id> \
  --direction ingress \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq '.Permissions.Permission[] | select(.PortRange == "22/22" and .IpProtocol == "tcp")'

---

Step 5: Network Configuration Verification

VPC Verification:

Success Criteria:

• VPC status is Available
• VPC ID matches instance's VPC

Verification Command:

aliyun vpc describe-vpcs \
  --region-id <region-id> \
  --vpc-id <vpc-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Vpcs.Vpc[0].Status'

Expected Output: Available

EIP Verification:

Success Criteria:

• If instance requires public access, EIP should be bound
• EIP status is InUse

Verification Command:

aliyun vpc describe-eip-addresses \
  --region-id <region-id> \
  --associated-instance-id <instance-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.EipAddresses.EipAddress[0].Status'

Expected Output: InUse (if EIP is bound)

---

Step 6: Monitoring Metrics Verification

Success Criteria:

• Command returns metric data points
• Datapoints field contains at least one measurement
• Values are within expected ranges

CPU Utilization Verification

Verification Command:

aliyun cms describe-metric-last \
  --region-id <region-id> \
  --namespace acs_ecs_dashboard \
  --metric-name CPUUtilization \
  --dimensions '[{"instanceId":"<instance-id>"}]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Datapoints' | jq -r '.[0].Average'

Thresholds:

• ✅ 0-70%: Normal
• ⚠️ 70-90%: High
• ❌ 90-100%: Critical

Memory Utilization Verification

Verification Command:

aliyun cms describe-metric-last \
  --region-id <region-id> \
  --namespace acs_ecs_dashboard \
  --metric-name memory_usedutilization \
  --dimensions '[{"instanceId":"<instance-id>"}]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Datapoints' | jq -r '.[0].Average'

Thresholds:

• ✅ 0-70%: Normal
• ⚠️ 70-90%: High
• ❌ 90-100%: Critical

Disk Utilization Verification

Verification Command:

aliyun cms describe-metric-last \
  --region-id <region-id> \
  --namespace acs_ecs_dashboard \
  --metric-name diskusage_utilization \
  --dimensions '[{"instanceId":"<instance-id>"}]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Datapoints' | jq -r '.[0].Average'

Thresholds:

• ✅ 0-80%: Normal
• ⚠️ 80-90%: High
• ❌ 90-100%: Critical

Network Traffic Verification

Inbound Traffic:

aliyun cms describe-metric-last \
  --region-id <region-id> \
  --namespace acs_ecs_dashboard \
  --metric-name InternetInRate \
  --dimensions '[{"instanceId":"<instance-id>"}]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Datapoints' | jq -r '.[0].Average'

Outbound Traffic:

aliyun cms describe-metric-last \
  --region-id <region-id> \
  --namespace acs_ecs_dashboard \
  --metric-name InternetOutRate \
  --dimensions '[{"instanceId":"<instance-id>"}]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Datapoints' | jq -r '.[0].Average'

Assessment:

• Compare current traffic to baseline patterns
• Check for unexpected spikes or drops
• Verify traffic doesn't exceed bandwidth limits

---

Deep Diagnostics: System & Service Checks Verification

Step 7: System Load Verification

Success Criteria:

• Command execution status is Finished
• Output is successfully decoded from Base64
• top, uptime, and free commands all return data

Verification Command:

aliyun ecs describe-invocation-results \
  --region-id <region-id> \
  --invoke-id <invoke-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Invocation.InvocationResults.InvocationResult[0].InvocationStatus'

Expected Output: Finished

Output Analysis:

# Decode and view output
aliyun ecs describe-invocation-results \
  --region-id <region-id> \
  --invoke-id <invoke-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Invocation.InvocationResults.InvocationResult[0].Output' \
  | base64 -d

Load Average Thresholds:

• ✅ Load < CPU cores: Normal
• ⚠️ Load = 1-2x CPU cores: High
• ❌ Load > 2x CPU cores: Critical

---

Step 8: Disk Usage Verification

Success Criteria:

• Command completes successfully
• df -h shows all mounted filesystems
• lsblk shows all block devices

Verification Command:

aliyun ecs describe-invocation-results \
  --region-id <region-id> \
  --invoke-id <invoke-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Invocation.InvocationResults.InvocationResult[0].InvocationStatus'

Expected Output: Finished

Disk Usage Thresholds:

• ✅ 0-80%: Normal
• ⚠️ 80-90%: High
• ❌ 90-100%: Critical

Critical Checks:

• Root partition / usage
• /var partition usage (logs)
• /tmp partition usage
• Inode usage (df -i)

---

Step 9: Network Connectivity Verification

Success Criteria:

• ss -tlnp shows listening ports
• ip addr shows network interfaces
• Required ports are in LISTEN state

Verification Command:

aliyun ecs describe-invocation-results \
  --region-id <region-id> \
  --invoke-id <invoke-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Invocation.InvocationResults.InvocationResult[0].Output' \
  | base64 -d

Port Checks:

• ✅ SSH (22) listening for Linux
• ✅ RDP (3389) listening for Windows
• ✅ Application ports listening as expected
• ❌ Unexpected ports listening (security concern)

Interface Checks:

• ✅ Primary interface is UP
• ✅ IP address correctly assigned
• ⚠️ Interface is DOWN or no IP

---

Step 10: System Logs Verification

Success Criteria:

• dmesg returns recent kernel messages
• journalctl returns systemd logs (if available)
• No critical errors in logs

Verification Command:

aliyun ecs describe-invocation-results \
  --region-id <region-id> \
  --invoke-id <invoke-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Invocation.InvocationResults.InvocationResult[0].Output' \
  | base64 -d

Critical Error Patterns:

• ❌ Out of memory: Kill process - OOM killer activated
• ❌ I/O error - Disk hardware failure
• ❌ segfault - Application crashes
• ⚠️ NMI watchdog - CPU lock-up
• ⚠️ temperature above threshold - Overheating

---

Step 11: Process Status Verification

Success Criteria:

• ps aux returns process list
• Top CPU processes are identified
• No excessive zombie processes

Verification Command:

aliyun ecs describe-invocation-results \
  --region-id <region-id> \
  --invoke-id <invoke-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Invocation.InvocationResults.InvocationResult[0].Output' \
  | base64 -d

Process Checks:

• ✅ Critical services running (sshd, systemd, etc.)
• ⚠️ High CPU processes identified
• ❌ Zombie processes (state Z) > 10
• ❌ Suspicious processes (crypto miners, etc.)

---

Common Failure Scenarios and Verification

Scenario 1: Cloud Assistant Not Available

Symptoms:

• Deep Diagnostics fail to execute
• Error: The CloudAssistant is not installed on the instance

Verification:

aliyun ecs describe-instance-attribute \
  --region-id <region-id> \
  --instance-id <instance-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.CloudAssistantStatus'

Expected Output: true

Resolution:

• Install Cloud Assistant agent on the instance
• Verify agent is running: systemctl status aliyun.service (Linux)

---

Scenario 2: Command Timeout

Symptoms:

• Command invocation status is Timeout
• No output returned

Verification:

aliyun ecs describe-invocation-results \
  --region-id <region-id> \
  --invoke-id <invoke-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Invocation.InvocationResults.InvocationResult[0].InvocationStatus'

Output: Timeout

Resolution:

• Increase timeout value in run-command
• Check if instance is overloaded
• Simplify command for faster execution

---

Scenario 3: Permission Denied in Guest OS

Symptoms:

• Command status is Failed
• Error message contains Permission denied

Verification:

aliyun ecs describe-invocation-results \
  --region-id <region-id> \
  --invoke-id <invoke-id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Invocation.InvocationResults.InvocationResult[0].ErrorInfo'

Resolution:

• Cloud Assistant runs as root by default
• Check file permissions in error message
• Verify SELinux/AppArmor policies

---

End-to-End Diagnostics Verification

Complete Success Criteria: 1. ✅ All Basic Diagnostics API calls complete successfully 2. ✅ Instance status is Running 3. ✅ No critical system events active 4. ✅ Security groups allow required ports 5. ✅ Network configuration is correct 6. ✅ All monitoring metrics within normal ranges 7. ✅ (If Deep Diagnostics executed) All Cloud Assistant commands complete 8. ✅ No critical errors in system logs 9. ✅ Key services are running 10. ✅ Resource usage within acceptable limits

Partial Success:

• Some checks pass, others fail or return warnings
• Diagnostic report should clearly indicate which checks failed
• Provide specific recommendations for each failure

Complete Failure:

• Multiple critical checks fail
• Instance may be in non-running state
• Immediate intervention required

---

Automated Verification Script

For automated testing, use this verification script:

#!/bin/bash
# verify-diagnostics.sh

REGION_ID="$1"
INSTANCE_ID="$2"

echo "=== ECS Diagnostics Verification ==="
echo "Region: $REGION_ID"
echo "Instance: $INSTANCE_ID"
echo ""

# Basic Diagnostics Checks
echo "[1/6] Verifying instance exists..."
INSTANCE_COUNT=$(aliyun ecs describe-instances \
  --region-id "$REGION_ID" \
  --instance-ids "[\"$INSTANCE_ID\"]" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq '.Instances.Instance | length')

if [ "$INSTANCE_COUNT" -eq 1 ]; then
  echo "✅ Instance found"
else
  echo "❌ Instance not found"
  exit 1
fi

echo "[2/6] Verifying instance status..."
INSTANCE_STATUS=$(aliyun ecs describe-instances \
  --region-id "$REGION_ID" \
  --instance-ids "[\"$INSTANCE_ID\"]" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Instances.Instance[0].Status')

echo "Status: $INSTANCE_STATUS"
if [ "$INSTANCE_STATUS" = "Running" ]; then
  echo "✅ Instance is running"
else
  echo "⚠️ Instance is not running"
fi

echo "[3/6] Checking system events..."
EVENT_COUNT=$(aliyun ecs describe-instance-history-events \
  --region-id "$REGION_ID" \
  --instance-id "$INSTANCE_ID" \
  --instance-event-cycle-status.1 Executing \
  --instance-event-cycle-status.2 Inquiring \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq '.InstanceSystemEventSet.InstanceSystemEventType | length')

if [ "$EVENT_COUNT" -eq 0 ]; then
  echo "✅ No active system events"
else
  echo "⚠️ $EVENT_COUNT active system event(s)"
fi

echo "[4/6] Checking CPU utilization..."
CPU_UTIL=$(aliyun cms describe-metric-last \
  --region-id "$REGION_ID" \
  --namespace acs_ecs_dashboard \
  --metric-name CPUUtilization \
  --dimensions "[{\"instanceId\":\"$INSTANCE_ID\"}]" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Datapoints' | jq -r '.[0].Average // "N/A"')

echo "CPU: $CPU_UTIL%"

echo "[5/6] Checking memory utilization..."
MEM_UTIL=$(aliyun cms describe-metric-last \
  --region-id "$REGION_ID" \
  --namespace acs_ecs_dashboard \
  --metric-name memory_usedutilization \
  --dimensions "[{\"instanceId\":\"$INSTANCE_ID\"}]" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Datapoints' | jq -r '.[0].Average // "N/A"')

echo "Memory: $MEM_UTIL%"

echo "[6/6] Checking disk utilization..."
DISK_UTIL=$(aliyun cms describe-metric-last \
  --region-id "$REGION_ID" \
  --namespace acs_ecs_dashboard \
  --metric-name diskusage_utilization \
  --dimensions "[{\"instanceId\":\"$INSTANCE_ID\"}]" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-diagnose/{session-id} \
  | jq -r '.Datapoints' | jq -r '.[0].Average // "N/A"')

echo "Disk: $DISK_UTIL%"

echo ""
echo "=== Verification Complete ==="

Usage:

chmod +x verify-diagnostics.sh
./verify-diagnostics.sh cn-hangzhou i-xxxxx

---

Related Links

• ECS API Error Codes
• Cloud Assistant Troubleshooting
• Cloud Monitor Metrics Reference