Huawei Cloud RDS Instance List

Overview

Query the RDS instance list of a tenant region through KooCLI hcloud RDS ListInstances (official read-only GET /v3/{project_id}/instances, verified in the huaweicloudsdkrds v3 client _list_instances_http_info metadata). The skill is aimed at RDS inventory inspection, daily operations patrol, and as a pre-query step for other RDS skills that need an instance_id.

Architecture:

agent → python3 scripts/list_rds.py → hcloud RDS ListInstances --cli-region=<region>
      → Huawei Cloud RDS OpenAPI (regional endpoint) → parsed JSON → table / --json / --names-only

(hcloud binary missing) → fallback: huaweicloudsdkrds v3 RdsClient.list_instances

Key properties:

• Read-only by design — the only API ever invoked is ListInstances (GET). A write-intent guard scans user arguments and validates the operation name; mutating intents (create / delete / update / resize / restart / stop / restore ...) are rejected with an explicit message before any command runs.
• CLI first, SDK fallback — KooCLI is the primary execution path; when the hcloud binary is absent, the script falls back to the official huaweicloudsdkrds v3 SDK (list_instances). Credentials are always read by the CLI profile / SDK environment — never handled by the script.
• Full-field table output — the default table renders the union of all fields returned by ListInstances, with datastore flattened into engine/engineVersion and private_ips joined for readability.
• Offline-testable — every code path (paging, filters, error classification, guard, SDK fallback) is covered by unit tests that mock the hcloud subprocess.

Out of scope: every mutating RDS action (create / delete / resize / restart / stop / restore backup / change password / read-replica management). Those require a dedicated write-capable skill and explicit user confirmation.

Prerequisites

1. KooCLI (hcloud) installed — see references/cli-installation-guide.md. Alternative: pip install huaweicloudsdkrds to enable the SDK fallback path.
2. Active credential profile — configure credentials out-of-band (hcloud configure in your terminal, or credential environment variables). Never paste AK/SK into chat; the script never reads, echoes, or stores secrets itself — authentication is delegated entirely to the hcloud profile / SDK environment.
3. IAM permission — read-only rds:instance:list; least-privilege policy in references/iam-policies.md.
4. Python 3.8+ (standard library only — argparse / json / subprocess).
5. Outbound HTTPS access to *.myhuaweicloud.com.

Workflow

1. Confirm the target region (default cn-north-4); every RDS call is region-scoped.
2. Confirm hcloud readiness (optional, read-only): hcloud configure list.
3. Run the list script with the desired output mode and filters.
4. Read the result — table for humans, --json for downstream tooling, --names-only for a compact inventory.
5. Handle the empty / error cases per the Edge Cases table below (the script prints an explicit hint for empty region, 403, and missing AK/SK).

Core Commands

# Full-field table (default)
python3 scripts/list_rds.py --region cn-north-4

# Raw JSON of every returned field
python3 scripts/list_rds.py --json

# Compact instance-name list only
python3 scripts/list_rds.py --names-only

# Filter by instance status (client-side: full list fetched, then filtered
# locally — the RDS ListInstances API has no status query parameter)
python3 scripts/list_rds.py --status ACTIVE

# Filter by engine / name
python3 scripts/list_rds.py --datastore-type MySQL --name rds-demo

# Combine filters
python3 scripts/list_rds.py --region cn-south-1 --status ACTIVE --names-only

Equivalent direct KooCLI command (the script wraps exactly this call, with paging):

hcloud RDS ListInstances --cli-region=cn-north-4 --limit=100 --offset=0

Parameter Confirmation

Output-mode precedence: --names-only → --json → table (default).

Write-Intent Guard

• The script scans all user arguments plus the --operation value for mutating vocabulary (create, delete, update, resize, restart, stop, restore, and RDS operation names such as CreateInstance, DeleteInstance, ResizeFlavor).
• Any hit raises GuardError, prints [错误] 检测到写操作意图 ... 已被守卫拦截, and exits with code 1 before a single hcloud command is executed.
• Only hcloud RDS ListInstances (GET) — or the SDK list_instances call in the fallback path — is ever constructed by build_command(); there is no code path that can issue a mutating RDS API call.

KooCLI Command Format Standard

hcloud <Service> <Operation> --cli-region=<region> [--key=value ...]

• Service name — exact KooCLI title-case service name: RDS.
• Operation name — PascalCase: ListInstances.
• Region parameter — --cli-region=<value>, e.g. --cli-region=cn-north-4 (required for every concrete RDS call).
• Simple parameter — --key=value, e.g. --limit=100, --offset=20, --name=rds-01, --datastore_type=MySQL, --id=rds-01. There is no --status parameter on the real RDS ListInstances API (verified via hcloud RDS ListInstances --help); status filtering is done client-side by the script, never forwarded to the CLI/API.
• REST path (official SDK _http_info) — GET /v3/{project_id}/instances (huaweicloudsdkrds v3 _list_instances_http_info); project_id is resolved by KooCLI from the credential profile.

Error Handling

Exit codes: 0 success / empty region; 1 config, auth, guard, or API error.

Edge Cases

Testing

Offline unit tests with a mocked hcloud subprocess (no credentials, no network):

python3 -m unittest discover -s tests -v

Coverage: write-intent guard (read passes / create / delete / resize / restart / stop / restore / normalize variants / operation whitelist), command construction (including "status never sent to the server"), JSON extraction, failure classification (missing AK/SK, 403, generic, [USE_ERROR] with rc=0), client-side status filtering (exact / case-insensitive / no-match / missing field), paging (total / full-page / empty), SDK fallback (success and unavailable; request construction matches the real ListInstancesRequest signature — status= must raise TypeError), rendering (table with engine/flavor/private IP fields / names / fallbacks), and all main() output modes including empty, filter, and error paths.

Reference Documents