Huawei Cloud MRS Cluster List

Overview

Query the MRS cluster list of a tenant region through KooCLI hcloud MRS ListClusters (official read-only GET /v1.1/{project_id}/cluster_infos, verified in the huaweicloudsdkmrs v1 client _list_clusters_http_info metadata). The skill is aimed at MRS inventory inspection, daily operations patrol, and as a pre-query step for other MRS skills that need a cluster_id.

Architecture:

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

Key properties:

• Read-only by design — the only API ever invoked is ListClusters (GET). A write-intent guard scans user arguments and validates the operation name; mutating intents (create / delete / update / scale / restart / terminate / submit job ...) are rejected with an explicit message before any command runs.
• Full-field table output — the default table renders the union of all fields returned by ListClusters (clusterId, clusterName, clusterState, billingType, version, node counts, enterprise project, tags, ...), not a trimmed subset.
• Offline-testable — every code path (paging, filters, error classification, guard) is covered by unit tests that mock the hcloud subprocess.

Out of scope: every mutating MRS action (create / delete / scale-out / scale-in / restart / patch / submit or stop jobs). Those require a dedicated write-capable skill and explicit user confirmation.

Prerequisites

1. KooCLI (hcloud) installed — see references/cli-installation-guide.md.
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.
3. IAM permission — read-only mrs:cluster: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 MRS 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_mrs.py --region cn-north-4

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

# Compact cluster-name list only
python3 scripts/list_mrs.py --names-only

# Filter by cluster state
python3 scripts/list_mrs.py --cluster-state running

# Combine filters
python3 scripts/list_mrs.py --region cn-south-1 --cluster-state running --names-only

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

hcloud MRS ListClusters --cli-region=cn-north-4 --pageSize=10 --currentPage=1

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, scale, restart, terminate, and MRS operation names such as CreateCluster, DeleteCluster, ScaleOut).
• Any hit raises GuardError, prints [错误] 检测到写操作意图 ... 已被守卫拦截, and exits with code 1 before a single hcloud command is executed.
• Only hcloud MRS ListClusters (GET) is ever constructed by build_command() — there is no code path that can issue a mutating MRS API call.

KooCLI Command Format Standard

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

• Service name — exact KooCLI title-case service name: MRS.
• Operation name — PascalCase: ListClusters.
• Region parameter — --cli-region=<value>, e.g. --cli-region=cn-north-4 (required for every concrete MRS call).
• Simple parameter — --key=value, e.g. --clusterState=running, --pageSize=10, --currentPage=2, --clusterName=mrs-01.
• REST path (official SDK _http_info) — GET /v1.1/{project_id}/cluster_infos (huaweicloudsdkmrs v1 _list_clusters_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 / scale / restart / normalize variants / operation whitelist), command construction, JSON extraction, failure classification (missing AK/SK, 403, generic), paging (total / full-page / isFinished), output rendering (table full fields / names / fallbacks), and all main() output modes including empty, filter, and error paths.

Reference Documents