huaweicloud/huawei-cloud-ecs-manage

Huawei Cloud ECS Manage (Create-Failure Diagnosis & Instance Management)

STOP - Do not answer from general knowledge. Follow the procedure below.

Step 0: Ensure skill-quality-cli (required; installed on first use)

bash scripts/ensure_cli.sh   # idempotent: installs only if absent (no auto-upgrade)
export PATH="$HOME/.local/bin:$PATH"
skill-quality-cli version    # verify it works

Run this step first: quality reporting depends on skill-quality-cli, ensured idempotently by scripts/ensure_cli.sh (installs once if missing, skips if present; no auto-upgrade — run skill-quality-cli upgrade to update manually). If offline or the download fails, the skill degrades silently (business flow unaffected); re-run this step once back online.

Always run hcloud ECS <Operation> --help before constructing commands to discover exact parameter names and requirements.

Overview

This skill provides AI Agent capabilities for Huawei Cloud ECS (Elastic Cloud Server / 弹性云服务器): instance lifecycle management (create/start/stop/restart/delete), instance/ quota/ flavor/ image querying, and a 6-step create-failure root-cause diagnosis that eliminates the most common causes of "ECS instance creation failed" in order: quota → flavor → image → network → keypair → disk.

It exposes 23 huawei_* actions in five capability groups:

Capability	Risk level	Actions
Query (read-only)	R3 — auto execute	huawei_list_ecs_instances, huawei_get_ecs_instance, huawei_list_ecs_flavors, huawei_list_ecs_images, huawei_list_ecs_quotas
Diagnose (read-only)	R3 — auto execute	huawei_diagnose_ecs_create_failure, huawei_analyze_ecs_health
Manage — lifecycle	R2 — preview + confirm	huawei_create_ecs_instance, huawei_start_ecs_instance, huawei_stop_ecs_instance, huawei_restart_ecs_instance
Manage — lifecycle	R1 — preview + confirm	huawei_delete_ecs_instance
Manage — change operations (§5)	R2 — preview + confirm	huawei_resize_ecs_instance, huawei_reinstall_ecs_os, huawei_reset_ecs_password, huawei_replace_ecs_keypair, huawei_bind_ecs_eip, huawei_change_ecs_security_group, huawei_add_ecs_nic, huawei_attach_ecs_volume, huawei_detach_ecs_volume
Manage — change operations (§5)	R1 — preview + confirm	huawei_unbind_ecs_eip, huawei_remove_ecs_nic

Every write action is asynchronous: the API returns a job_id and the real work continues in the background. Polling that job is a mandatory post-step, not an optional extra — see §6 Async job polling.

Scope boundaries:

• ✅ Query ECS instances, flavors, images, quotas (read-only)
• ✅ Diagnose ECS create failures (quota → flavor → image → network → keypair → disk) and analyze instance health (status / disk / network)
• ✅ Create (post-paid), start, stop, restart, delete ECS instances (R2/R1: always preview + confirm)
• ✅ Change an existing instance: resize flavor, reinstall OS, reset password, replace keypair, bind/unbind EIP, attach/detach an existing security group, add/remove a NIC, attach/detach a volume (R2/R1: always preview + confirm)
• ❌ NEVER create, delete or reconfigure the VPC / subnet / security-group resource or the EVS volume resource itself. This skill only attaches or detaches existing resources to an instance; use the dedicated VPC / EVS skills for resource-level mutation.
• ❌ NEVER execute any write action without explicit user confirmation
• ❌ NEVER report a write as "done" before its async job reaches SUCCESS and, for create, before the instance reaches ACTIVE
• ❌ NEVER echo credentials (AK/SK, passwords, tokens) in any output or report
• ➡️ Out of scope: RDS / database queries. This skill manages compute only. When the user asks about a database that an ECS instance depends on, hand the question back to the user with a pointer to a dedicated RDS skill or the Huawei Cloud RDS console — this skill never invokes another skill. See references/related-skills.md for the hand-off wording.

Dependency: Quality telemetry is collected automatically via skill-quality-cli (installed by scripts/ensure_cli.sh if absent).

Critical Warnings

Trap	Why
Quota exhaustion is the #1 create failure	Insufficient quota / Quota exceeded means instances/cores/RAM/volumes hit the project limit — check ShowServerLimits first
Flavor must exist in the target region/AZ	A flavor exists globally but may be sold out or unavailable in the chosen AZ — filter ListFlavors by --availability_zone
Image must be active and match the flavor architecture	Deleted/private images with wrong __os_type/architecture (x86 vs ARM) fail provisioning — check IMS ListImages --status=active
Subnet with no free IPs blocks create	If the subnet CIDR is exhausted or dhcp disabled, NIC allocation fails
Security group must exist before create	Referencing a non-existent security group ID fails the request
Keypair errors are misleading	If key_name is set but the keypair does not exist, creation fails with KeypairNotFound — verify with KPS ListKeypairs
Disk/AZ availability	Root/data volume types (SATA/SAS/GPSSD) may be unavailable in the target AZ — check EVS ListVolumes and volume quotas
Deletion is irreversible	R1: verify the instance first, confirm no data dependency, then require explicit user confirmation

Prerequisites

1. hcloud CLI (KooCLI 7.2.x or later) installed and authenticated.
   • Installation and configuration guide: see references/cli-installation-guide.md
   • Two supported authentication modes:
     • AK/SK credentials: environment variables HUAWEICLOUD_SDK_AK / HUAWEICLOUD_SDK_SK (or HUAWEI_ACCESS_KEY / HUAWEI_SECRET_KEY), or interactive setup via the hcloud configure wizard
     • Local hcloud profile: run "hcloud configure list"; it must show a valid profile with mode AKSK and a real accessKeyId
   • Verify authentication with "hcloud configure list"
2. Region: ECS is region-specific. Always pass --cli-region={region} (e.g. cn-north-4). --project_id is auto-filled from the profile when omitted.
3. IAM permissions: least-privilege policies are provided in references/iam-policies.md.
   • Query/diagnose: ecs:cloudServers:list, ecs:cloudServers:get, ecs:cloudServerFlavors:list, ecs:cloudServerImages:list, ecs:jobs:get, ecs:serverVolumes:list, ims:images:list, vpc:subnets:list, vpc:securityGroups:list, vpc:publicIps:list, evs:volumes:list, kps:keypairs:list (diagnosis step 5, hcloud KPS ListKeypairs)
   • Manage: ecs:cloudServers:create, ecs:cloudServers:action (start/stop/restart, resize, reinstall, reset password, NIC and security-group changes), ecs:cloudServers:delete
   • Change operations (§5) also need the write action of each resource they touch, e.g. evs:volumes:delete with --delete_volume=true, vpc:publicIps:delete with --delete_publicip=true; the exact list is in references/iam-policies.md.
4. skill-quality-cli — ensured by bash scripts/ensure_cli.sh (idempotent, skips if present)
   • Upgrade: run skill-quality-cli upgrade manually (no auto-upgrade)
   • Disable telemetry report: set SKILL_QUALITY_REPORT=0

Workflow

1. Identify target → region, instance_id / flavor_id / image_id / vpc_id / subnet_id / key_name, intent keywords
2. Classify intent →
     - Query/Diagnose (R3): list / show / analyze / diagnose — auto execute
     - Manage lifecycle (R2): create / start / stop / restart — ALWAYS show preview and ask for explicit confirmation
     - Manage lifecycle (R1): delete — ALWAYS show the instance details, irreversible warning, explicit confirmation
     - Manage change ops (R2): resize / reinstall / reset password / replace keypair / bind EIP /
       change security group / add NIC / attach volume — ALWAYS preview + confirm
     - Manage change ops (R1): unbind EIP / remove NIC / delete keypair — ALWAYS show the current
       attachment, irreversible warning, explicit confirmation
3. Preflight → for create and for every change op, run the relevant read-only checks first
   (quota, flavor, image, network, keypair, disk) so the user confirms against real state
4. Execute → build the hcloud command from the verified templates below
5. Capture the job id → the write API returns a job_id immediately; the work is still running
6. Poll async job → `hcloud ECS ShowJob` until `status=SUCCESS|FAIL`; for create ALSO poll
   `hcloud ECS ShowServer` until `status=ACTIVE`; then report the FINAL state to the user
7. Output → structured JSON summary + readable diagnosis report
8. Report quality → automatic via skill-quality-cli run wrapping (see Step 0 / Prerequisites #4)

Confirmation gates (MUST NOT be skipped):

• R2 actions (huawei_create_ecs_instance, huawei_start_ecs_instance, huawei_stop_ecs_instance, huawei_restart_ecs_instance): show the full command, the target instance(s), and ask "confirm?" before running.
• R1 action (huawei_delete_ecs_instance): first run the read-only check (ShowServer to confirm the instance exists and record its status/flavor/volumes). Show the full command with the irreversible deletion warning, and require explicit confirmation before running.
• Change-operation actions (R2: huawei_resize_ecs_instance, huawei_reinstall_ecs_os, huawei_reset_ecs_password, huawei_replace_ecs_keypair, huawei_bind_ecs_eip, huawei_change_ecs_security_group, huawei_add_ecs_nic, huawei_attach_ecs_volume): show the current state (via ShowServer / ListServerVolumeAttachments / ListServerInterfaces), the full command and the expected end state, then ask "confirm?".
• Change-operation actions (R1: huawei_unbind_ecs_eip, huawei_remove_ecs_nic): show what will be detached and the connectivity impact (an unbound EIP loses public access; a removed NIC loses that network path and its private IP), require explicit confirmation, and never chain them with a delete. For huawei_detach_ecs_volume (R2) warn that --delete_flag=1 deletes the data disk.
• Create preflight: before huawei_create_ecs_instance, ALWAYS run huawei_diagnose_ecs_create_failure (or at least the quota + flavor + image checks) so the user sees the environment is ready, then confirm.
• Async polling is mandatory: never close out a write action before the job reaches a terminal state. A job_id without polling is an incomplete action, not a success.

Write operations are marked [W] / 写操作 in the command blocks below (检测关键字: create / start / stop / restart / delete — same verbs the test pipeline's write-operation detector keys on).

Core Commands

All commands below are shown in dual form: the bare executable hcloud <Service> <Operation> command and the identical payload wrapped with skill-quality-cli run --skill-name huawei-cloud-ecs-manage -- ... for quality reporting. They require the KooCLI (hcloud CLI) installed and authenticated (see Prerequisites); no Python SDK package is needed for any business command.

⚠️ Mandatory: every hcloud command in this skill MUST be wrapped with skill-quality-cli run --skill-name huawei-cloud-ecs-manage -- <command> — bare hcloud calls are strictly forbidden.

1. Query (R3 — read-only, auto execute)

huawei_list_ecs_instances — list ECS instances and their status:

# Optional: --limit={n} --offset={n} --status={ACTIVE|SHUTOFF|ERROR|BUILD|...} --name={name} --server_id={id1,id2}
hcloud ECS ListServersDetails --cli-region={region}
skill-quality-cli run --skill-name huawei-cloud-ecs-manage -- hcloud ECS ListServersDetails --cli-region={region}

huawei_get_ecs_instance — query one instance's full detail (status, addresses, flavor, volumes, fault):

hcloud ECS ShowServer --cli-region={region} --server_id={server_id}
skill-quality-cli run --skill-name huawei-cloud-ecs-manage -- hcloud ECS ShowServer --cli-region={region} --server_id={server_id}

huawei_list_ecs_flavors — list available flavors (optionally scoped to one AZ):

# Optional: --availability_zone={az} --flavor_id={flavor_id} --limit={n} --marker={marker}
hcloud ECS ListFlavors --cli-region={region}
skill-quality-cli run --skill-name huawei-cloud-ecs-manage -- hcloud ECS ListFlavors --cli-region={region}

huawei_list_ecs_images — list available images (filter by OS type / architecture / status):

# Optional: --__os_type={Linux|Windows} --architecture={x86|arm} --status={active} --name={name} --limit={n}
hcloud IMS ListImages --cli-region={region}
skill-quality-cli run --skill-name huawei-cloud-ecs-manage -- hcloud IMS ListImages --cli-region={region}

huawei_list_ecs_quotas — query project quota usage:

hcloud ECS ShowServerLimits --cli-region={region}
skill-quality-cli run --skill-name huawei-cloud-ecs-manage -- hcloud ECS ShowServerLimits --cli-region={region}

ShowServerLimits returns absolute limits and usage (maxTotalInstances/totalInstancesUsed, maxTotalCores/totalCoresUsed, maxTotalRAMSize/totalRamUsed, maxTotalKeypairs). Note it has no volume field — for disk volume quotas, additionally use:

# Required: --target_project_id={project_id} --usage=True
hcloud EVS CinderListQuotas --target_project_id={project_id} --usage=True --cli-region={region}
skill-quality-cli run --skill-name huawei-cloud-ecs-manage -- hcloud EVS CinderListQuotas --target_project_id={project_id} --usage=True --cli-region={region}

2. Diagnose (R3 — read-only, auto execute)

huawei_diagnose_ecs_create_failure — 6-step create-failure

…

[truncated for translation]