Name: alibabacloud-ecs-diagnose
Author: aliyun

Comprehensive Alibaba Cloud ECS instance diagnostics skill. Performs systematic troubleshooting including cloud platform status checks and GuestOS internal diagnostics via Cloud Assistant. Use when users report server connectivity issues, SSH timeout, instance lag, website unavailability, disk full,

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, prefer the signed package path from references/cli installation guide.md (download the official universal binary, verify it, and install into your user directory — no remote script, no sudo, no system level writes; you can see the full scope of changes before running anything). The one line remote installer curl fsSL https://aliyuncli.alicdn.com/setup.sh bash is a manual fallback only — it pipes a remote script into bash and may write into system directories via sudo, so do not run it unless you have reviewed it and explicitly accepted that risk. Tested with: Aliyun CLI 3.5.0 and 3.3.3, plugin versions ecs/vpc/cms 0.9.x. Minimum required CLI version: 3.3.3. Pre check: Alibaba Cloud Credentials AND Region Required (run BEFORE any plugin setup) 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 Check the output for a valid profile (AK, STS, or OAuth identity) and a non empty Region . If no valid profile or no region is configured, STOP here. 1. Obtain credentials from [Alibaba Cloud Console](https://ram.console.aliyun.com/manage/ak) 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 with a region Why credentials and region come first: aliyun configure set auto plugin install true fails with region can't be empty when no region is configured. Plugin setup MUST follow the credential/region gate, never precede it. Pre check: Aliyun CLI plugin update (ONLY AFTER credentials + region are confirmed) [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: EBS plugin (only for Disk Performance Diagnosis) The EBS diagnosis APIs are exposed by the aliyun cli ebs plugin, which the auto plugin install / aliyun plugin update pre checks above already take care of. Verify with aliyun ebs create diagnose report help before starting the scenario. The CLI is the primary path; the Python SDK ( scripts/requirements.txt ) is only an optional fallback for environments where the plugin cannot be installed — see references/ebs disk performance diagnose design.md . Observability (MUST follow for every aliyun command) Upon loading this skill: 1. 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. 2. Read the skill version from references/manifest.json (the top level version field). Use it as {skill version} in the User Agent below. Rule: Every aliyun CLI command that calls a cloud API MUST include the user agent flag: Why two components? {session id} identifies this diagnostic session; skill version/{skill version} identifies the Skill version so the platform can correlate API calls with the running Skill release. 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 is product specific : ecs / ebs / vpc commands: biz region id <region (the API's RegionId). region id does NOT exist and fails with unknown flag . cms commands (plugin 0.9.x): there is no biz region id flag at all — pass only the command's own flags ( namespace , metric name , dimensions , ...). Use the global region <region flag if you need to override the endpoint. The global region <region flag overrides the service endpoint. Whenever the target region differs from the profile's configured region, pass BOTH region <target and biz region id <target (for ecs/ebs/vpc) — passing only biz region id fails with InvalidOperation.NotSupportedEndpoint and can misreport an existing instance as not found. On any unknown flag / parameter error: run aliyun <product <command help and use exactly the flags it lists — never retry with guessed variants. Instance ID format is command specific — instance id.1 indexed syntax is REMOVED in plugin 0.9.x (fails with unknown flag ). Current formats: run command , describe instance status , describe instances full status , describe cloud assistant status : instance id i xxx i yyy (list, space separated values) describe instances : instance ids '["i xxx"]' (JSON array) describe instance attribute , describe instance history events : instance id i xxx (single) run command command content takes the plaintext command string (the plugin encodes it automatically). Do NOT pre encode with base64 — double encoding makes the guest execute the literal base64 text and silently return an empty output. Always include user agent "AlibabaCloud Agent Skills/alibabacloud ecs diagnose/{session id} skill version/{skill version}" [MUST] CLI User Agent — Every aliyun CLI command invocation must include: user agent "AlibabaCloud Agent Skills/alibabacloud ecs diagnose/{session id} skill version/{skill version}" 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:QueryMetricLast (RAM action for the DescribeMetricLast API — the API name and the RAM action differ!) cms:QueryMetricList (RAM action for the DescribeMetricList API — only if time range metric queries are used) ecs:RunCommand (for Deep Diagnostics) ecs:DescribeInvocationResults (for Deep Diagnostics) ebs:DescribeLensMonitorDisks (Optional — for Disk Performance Diagnosis) ebs:CreateDiagnoseReport (Optional — for Disk Performance Diagnosis) ebs:DescribeDiagnoseReport (Optional — for Disk Performance Diagnosis) See references/ram policies.md for detailed policy configuration. [MUST] Permission Failure Handling — decision table: When any command or API call fails due to permission errors (403 / Forbidden.RAM / NoPermission ) at any point during execution, classify the failed check FIRST, then follow the matching row — do not mix the two behaviors: Failed check Classification Action DescribeInstances (Phase 0 instance location) Required STOP the whole workflow. Read references/ram policies.md , guide the user through requesting permissions (optionally via the ram permission diagnose skill), and wait for explicit confirmation before retrying. Instance status / system events / security group / VPC EIP / CMS metrics used by the matched scenario's mandatory checklist Required Same as above: STOP, guide, wait for confirmation. Supplementary evidence outside the mandatory checklist (e.g. an extra CMS metric, EIP info in a non connection scenario) Optional evidence Log the failure, mark that section of the report as "permission denied — not checked", and continue the workflow. Never present the skipped check as "normal". In every case the diagnostic report MUST state which checks could not run and why. A missing permission is never silently dropped, and never reported as a healthy result. 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. Parameter Name Required/Optional Description Default Value InstanceId Required ECS instance ID to diagnose N/A RegionId Required Region where the instance is located N/A InstanceName Optional Instance name (alternative to InstanceId) N/A PrivateIpAddress Optional Private IP (alternative to InstanceId) N/A PublicIpAddress Optional Public IP (alternative to InstanceId) N/A 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 (the only exception is the disk scoped rule below). 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, unless the disk scoped exception below applies. [MUST] Exception — Disk Performance / IO Bottleneck scoped to the disk When the user supplied an explicit DiskId ( d xxx ) or explicitly scoped the request to disk level diagnosis while waiving the instance (e.g. "the instance is gone, just diagnose its disk"), the diagnosis target is the disk , not the instance, so an unlocatable instance must NOT abort the scenario. With an explicit DiskId — verify the disk instead of terminating: Disk found → continue to the Disk Performance / IO Bottleneck row of Scenario Based Routing. Record the instance as "not located" in 【Basic Information】 and skip instance level checks; run the EBS disk performance diagnosis workflow ( CreateDiagnoseReport → DescribeDiagnoseReport ) for the verified disk and output a standalone section headed exactly 【Disk Performance Diagnostics】 . Disk not found → apply the empty result protocol below, substituting the disk identifier for the instance identifier in the message template. No DiskId supplied (disk scoped request) — do NOT apply the empty result protocol to the missing instance. Record the instance as "not located" in 【Basic Information】, skip instance level checks, and continue to the Disk Performance / IO Bottleneck row of Scenario