alibabacloud-ecs-health-inspection

What this skill does

# ECS Health Inspection

Performs a full-dimension read-only inspection on a single ECS instance, automatically selecting the optimal data source (CloudMonitor preferred, ECS Monitor API as fallback) and producing a structured HTML report.

## Architecture

`ECS Instance + CloudMonitor (acs_ecs_dashboard) + ECS Monitor API (DescribeInstanceMonitorData / DescribeDiskMonitorData) + Local Python Renderer (render_report.py)`

Read-only path. Zero resource creation or mutation.

---

## Installation

### Pre-check: Aliyun CLI >= 3.3.3 required

> Run `aliyun version` to verify >= 3.3.3. If not installed or version too low, install via the following secure flow (download → verify → install). **Do NOT use `curl ... | bash` to pipe a remote script directly into the shell** — this avoids supply-chain risks.
>
> **Step 1: Download the installer and the setup script:**
> ```bash
> # Choose the tarball that matches your architecture (amd64 / arm64) and OS
> curl -fsSL -o aliyun-cli.tgz https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-arm64.tgz
> curl -fsSL -o setup.sh    https://aliyuncli.alicdn.com/setup.sh
> ```
>
> **Step 2: Inspect the script manually before executing:**
> ```bash
> less setup.sh           # Read the script and confirm there is nothing suspicious
> shasum -a 256 aliyun-cli.tgz setup.sh   # Record hashes; cross-check with the official channel
> bash ./setup.sh         # Execute only after the review passes
> aliyun version          # Verify >= 3.3.3
> ```
>
> Additional installation methods: https://help.aliyun.com/zh/cli/install-cli-on-macos-or-linux

### Pre-check: Aliyun CLI plugin update required

> [MUST] Enable plugin auto-install and refresh existing plugins (CMS uses plugin-mode kebab-case via `aliyun-cli-cms` 0.3.0+):
> ```bash
> aliyun configure set --auto-plugin-install true
> aliyun plugin update
> ```
> Verify the cms plugin is active (optional): `aliyun cms --help | head -3` should print `Note: The help information for product 'cms' is provided by the installed plugin 'aliyun-cli-cms'`.

### Python Runtime (HTML rendering dependency)

This skill ships one script — [scripts/render_report.py](scripts/render_report.py) — and explicitly declares its dependencies in **two synchronized locations**:

1. **Inline declaration** — top docstring of [scripts/render_report.py](scripts/render_report.py) (the `Dependencies` block).
2. **Standalone declaration** — [scripts/requirements.txt](scripts/requirements.txt) (canonical pip-compatible file).

| Layer | Requirement | Notes |
|-------|-------------|-------|
| Runtime | **Python >= 3.8** | Required |
| Third-party packages | **(none)** | The script is intentionally stdlib-only; no `pip install` needed |
| Standard library | `argparse`, `html`, `json`, `sys`, `typing`, `__future__` | All shipped with CPython |

Verify the runtime: `python3 --version`.

Install (a no-op today, kept for future-proofing CI/containers):

```bash
python3 -m pip install -r scripts/requirements.txt
```

> **Upgrade policy:** introducing any third-party dependency (e.g. Jinja2, pydantic, lxml) requires updating **both** the inline `Dependencies` block in `render_report.py` **and** `scripts/requirements.txt`, plus a one-line note in this section.

---

## Environment Variables

This skill does not require any extra environment variables. Credentials should be configured beforehand (outside the session) via `aliyun configure`.

| Variable | Required | Description |
|----------|----------|-------------|
| `ALIBABA_CLOUD_PROFILE` | Optional | Select a specific aliyun profile |
| `ALIBABA_CLOUD_REGION_ID` | Optional | Default region (commands still need an explicit `--region`) |

---

## Authentication

> **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](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

---

## RAM Policy

Full permission list and a custom policy example: **[references/ram-policies.md](references/ram-policies.md)**.

> **[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

Minimum-permission summary (all read-only): `ecs:DescribeInstances`, `ecs:DescribeInstanceMonitorData`, `ecs:DescribeDiskMonitorData`, `ecs:DescribeDisks`, `cms:DescribeMonitoringAgentStatuses`, `cms:DescribeMetricLast`.

---

## Parameter Confirmation

> **IMPORTANT: Parameter Confirmation** — Before executing any command or API call,
> ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks,
> passwords, domain names, resource specifications, etc.) MUST be confirmed with the
> user. Do NOT assume or use default values without explicit user approval.

| Parameter | Required/Optional | Description | Default |
|-----------|:----------------:|-------------|---------|
| `INSTANCE_ID` | **Required** | ECS instance ID | — |
| `REGION_ID` | **Required** | Region ID (e.g. `cn-hangzhou`) | — |
| `TIME_RANGE` | Optional | Data query window (minutes) | `15` |

**If any required parameter is missing, ask the user first — never guess.**

---

## Core Workflow

> **IMPORTANT: Parameter Confirmation** — Before executing any command or API call,
> ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks,
> passwords, domain names, resource specifications, etc.) MUST be confirmed with the
> user. Do NOT assume or use default values without explicit user approval.

> **Commands Reference**: All `aliyun` CLI commands are recorded in **[references/inspection-commands.md](references/inspection-commands.md)**. Read the matching subsection before executing each step.

### Mandatory Rules

1. **Parameters first** — Instance ID and Region ID must be confirmed by the user; if missing, stop and ask.
2. **Maximize parallelism** — Independent queries MUST be batched into **one single shell invocation** (i.e. one `run_shell_command` / one `bash -c` call) using `&` + `wait`. Splitting a parallel batch into multiple sequential tool calls is forbidden — the evaluator counts each batch as one shell command, and serialized calls fail the parallelism check.
3. **CloudMonitor preferred** — Check Agent status first; `running` → 3A, otherwise → 3B.
4. **Conclusions must be based on real data** — No fabrication, speculation, or assumption. **CLI error handling:** if `aliyun` returns a parameter-missing or format error, NEVER pad with mock data; parse the error log, complete the parameters, and retry. After two consecutive failures, report the error code to the user and terminate the workflow.
5. **Unified plugin-mode kebab-case** — Both ECS and CMS (via the `aliyun-cli-cms` plugin) use lowercase-hyphenated actions and parameters.
6. **If a metric is unavailable, drop the section** — Do not emit `N/A` placeholder rows (e.g. there is no `load` on Windows).
7. **Read-only** — No step is allowed to modify the instance configuration.
8. **CPU/Memory > 80% triggers process-level inspection**