Huawei Cloud APIG API Gateway Management

Step 0: Install skill-quality-cli (idempotent, skip if already installed)

The CLI installs into ~/.local/bin/, which is not always in $PATH (bare skill-quality-cli may exit 127). Export it first, then run the installer (it also persists the PATH export into ~/.bashrc / ~/.profile):

export PATH="$HOME/.local/bin:$PATH"
bash scripts/ensure_cli.sh

The script installs the bundled scripts/cli/ sources to ~/.local/bin/ when skill-quality-cli is not found (offline, no external download), re-exports PATH into ~/.bashrc / ~/.profile; it never blocks. If still not found, call the absolute path: ~/.local/bin/skill-quality-cli.

Overview

This skill manages Huawei Cloud APIG (API Gateway) dedicated instances and their resources through the hcloud CLI (KooCLI). It covers instance lifecycle management, API groups, API create/update, batch publish/offline, request throttling policies, and public ingress EIP binding, together with read-only diagnosis of public access configuration and the publish chain.

Capabilities (17 huawei_* actions):

NOT covered by this skill (use the Huawei Cloud APIG console for these): signature keys / app credentials, API plugins, ACL policies, domain binding, API group update/rename, and any other APIG operations not listed above. Requests for these operations must be declined explicitly.

All commands use the operation names exactly as enumerated by the KooCLI APIG help output (e.g. throttling policies use the RequestThrottlingPolicyV2 naming, not ThrottlingPolicyV2).

Critical Warnings

Prerequisites

1. hcloud CLI installed and authenticated — see references/cli-installation-guide.md
2. Authentication: AK/SK via environment variables (HUAWEI_ACCESS_KEY / HUAWEI_SECRET_KEY or any HUAWEI*/HW* pair containing access/secret key) or a local KooCLI profile created with the configure command
3. Region: APIG is region-specific. Always pass --cli-region={region} (e.g. cn-north-4, ap-southeast-1); if omitted, the profile region is used.
4. IAM permissions — see references/iam-policies.md for least-privilege policies
5. Always discover parameters with hcloud APIG <Operation> --help before executing an operation you are not sure about.

Workflow

1. Identify the target APIG instance (huawei_list_apig_instances / huawei_get_apig_instance)
2. Route by intent:
   ├── Query   → list instances / groups / APIs / throttling policies
   ├── Analyze → public access analysis (eip_address vs sl_domain), publish chain analysis
   ├── Manage  → create instance (poll to Running), add ingress EIP, create group/API,
   │             update API, publish API, create throttling policy (preview + confirm)
   └── Delete  → delete instance / API / API group (empty the group first — see Delete — API; preview + explicit confirm, never automatic)
3. Return results: read-only actions return the command JSON; mutations return the
   resource snapshot read back after the operation completes

Core Commands

Command naming: operation names are taken verbatim from the KooCLI APIG help enumeration. Service name APIG is shown in the CLI help (the KooCLI metadata directory is lowercase apig; both forms are accepted).

Query — Instances

huawei_list_apig_instances — list APIG instances and status (including eip_address):

# --limit / --offset are optional pagination filters (example values shown)
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListInstancesV2 --cli-region={region} --limit=20 --offset=0

huawei_get_apig_instance — query a single instance detail:

# Narrow to a single instance: add --instance_id=<your_instance_id> (a UUID)
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListInstancesV2 --cli-region={region} --instance_id={instance_id}

Empty result means NOT found: ListInstancesV2 returns {"total": 0, "instances": []} (exit 0, no error) when the instance does not exist. Report "实例不存在，请确认 instance_id" instead of treating it as a successful query.

Query — API Groups

huawei_list_apig_api_groups — list API groups (response includes sl_domain):

skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListApiGroupsV2 --cli-region={region} --instance_id={instance_id} --limit=20

Query — APIs

huawei_list_apig_apis — list APIs in an instance:

# --group_id={group_id} optionally filters to a single API group
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListApisV2 --cli-region={region} --instance_id={instance_id} --limit=20

Query — Throttling Policies

huawei_list_apig_throttling_policies — list request throttling policies (operation name per the KooCLI APIG help enumeration):

skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListRequestThrottlingPolicyV2 --cli-region={region} --instance_id={instance_id} --limit=20

Analyze — Public Access

huawei_analyze_apig_public_access — analyze whether an instance is publicly reachable and what address to use:

skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListInstancesV2 --cli-region={region} --instance_id={instance_id} --cli-output=json
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListApiGroupsV2 --cli-region={region} --instance_id={instance_id} --cli-output=json

Analysis rules: if instances[].eip_address is a valid IP the instance has a public inbound entry — use it for public access. If it is null, the instance is internal-only (BASIC spec or lvs provider). sl_domain from the API group is internal-only (e.g. *.apic.cn-north-4.huaweicloudapis.com) and must NOT be advertised as a public endpoint.

Analyze — Publish Chain

huawei_analyze_apig_publish_chain — walk the instance -> group -> API -> publish-state chain to locate where a published endpoint is broken:

skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListInstancesV2 --cli-region={region}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListApiGroupsV2 --cli-region={region} --instance_id={instance_id}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListApisV2 --cli-region={region} --instance_id={instance_id}
# Optional: add --group_id={group_id} to restrict the walk to a single API group

Report which hop is missing (no instance / no group / no API / no publish_id), and warn when sl_domain is used for public access instead of eip_address.

Manage — Create Instance (async, poll to Running)

huawei_create_apig_instance — create a pay-per-use dedicated gateway. The API is asynchronous: creation takes 5-15 minutes. Poll ListInstancesV2 until status == "Running":

# Run as a single line (no line continuations); always check CreateInstanceV2 --help first
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG CreateInstanceV2 --cli-region={region} --instance_name={instance_name} --spec_id={spec_id} --vpc_id={vpc_id} --subnet_id={subnet_id} --security_group_id={security_group_id} --loadbalancer_provider={loadbalancer_provider} --available_zone_ids.1={available_zone_id}

*The current KooCLI metadata marks CreateInstanceV2 parameters optional, but the APIG API rejects the request without spec_id, vpc_id, subnet_id, security_group_id, loadbalancer_provider and available_zone_ids — always pass them. Always check CreateInstanceV2 --help first to confirm parameter names before building the command.

Polling loop after creation:

while true; do
  status=$(skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListInstancesV2 --cli-region={region} --instance_id={instance_id} --cli-output=json | jq -r '.instances[0].status')
  [ "$status" = "Running" ] && break
  echo "instance status: $status, waiting 60s..."; sleep 60
done

Terminal state is Running (NOT "SUCCESS"). States such as CreateSuccess are intermediate and still mean the instance is being provisioned.

Manage — Add Ingress EIP

huawei_add_apig_ingress_eip — enable public inbound access on an elb-provider gateway (bandwidth minimum 5 Mbit/s):

# --bandwidth_charging_mode: bandwidth|traffic; --bandwidth_size: Mbit/s (min 5)
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG AddIngressEipV2 --cli-region={region} --instance_id={instance_id} --bandwidth_charging_mode=bandwidth --bandwidth_size=5

Verification after binding: ListInstancesV2 eip_address may not appear promptly (verified: still null 8 minutes after success) — do NOT rely on it as the sole evidence. Confirm success via the AddIngressEipV2 response/task acceptance, a retry returning APIC.7711 ("Public inbound access is enabled"), or the EIP list in the APIG console. Works only with elb-provider instances.

Manage — Create API Group

huawei_create_apig_api_group — create an API group:

# --remark={remark} is optional
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG CreateApiGroupV2 --cli-region={region} --instance_id={instance_id} --name={name}

Manage — Create API

huawei_create_apig_api — create an API in a group:

skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG CreateApiV2 --cli-region={region} --instance_id={instance_id} --group_id={group_id} --type={type} --name={name} --req_protocol={req_protocol} --req_method={req_method} --req_uri={req_uri} --auth_type={auth_type} --backend_type={backend_type}

Manage — Update API

huawei_update_apig_api — modify an existing API (auth mode, path, backend, etc.):

skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG UpdateApiV2 --cli-region={region} --instance_id={instance_id} --group_id={group_id} --api_id={api_id} --type={type} --name={name} --req_protocol={req_protocol} --req_method={req_method} --req_uri={req_uri} --auth_type={auth_type} --backend_type={backend_type}

Manage — Publish / Offline API

huawei_publish_apig_api — batch publish or take offline APIs (operation is BatchPublishOrOfflineApiV2; apis is a 1-based array):

# 1) Get the real env ID first (RELEASE is only the environment NAME, NOT accepted); replace the example UUID below with the real env_id:
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListEnvironmentsV2 --cli-region={region} --instance_id={instance_id}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG BatchPublishOrOfflineApiV2 --cli-region={region} --instance_id={instance_id} --action=online --env_id=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 --apis.1=9c8f2d0a111122223333444455556666

Manage — Create Throttling Policy

huawei_create_apig_throttling_policy — create a request throttling policy (operation name per the KooCLI APIG help enumeration):

skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG CreateRequestThrottlingPolicyV2 --cli-region={region} --instance_id={instance_id} --name={name} --time_unit={time_unit} --time_interval={time_interval} --api_call_limits={api_call_limits}

Delete — Instance

huawei_delete_apig_instance — delete a dedicated gateway (R1: explicit user confirmation required before running):

skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG DeleteInstancesV2 --cli-region={region} --instance_id={instance_id}

Delete — API

huawei_delete_apig_api — delete an API from a group (R1: explicit user confirmation required before running):

# Note: DeleteApiV2 takes --api_id + --instance_id only (--group_id is NOT a
# parameter of this operation; verified against `hcloud APIG DeleteApiV2 --help`)
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG DeleteApiV2 --cli-region={region} --instance_id={instance_id} --api_id={api_id}

An API group cannot be deleted while it still contains APIs (APIG.3415). Use this action to delete each API in the group first, then delete the group.

Delete — API Group

huawei_delete_apig_api_group — delete an API group (R1: explicit user confirmation required before running):

skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG DeleteApiGroupV2 --cli-region={region} --instance_id={instance_id} --group_id={group_id}

The group must be empty first: APIG rejects deleting a group that still contains APIs (APIG.3415 The API group cannot be deleted because it contains APIs). Delete all APIs in the group with huawei_delete_apig_api (DeleteApiV2) before deleting the group. Only after every API is gone does DeleteApiGroupV2 succeed.

Parameter Confirmation

• Every huawei_* command must be checked against hcloud APIG <Operation> --help before execution; parameter names in this skill were verified against KooCLI 7.2.12 output.
• Required vs optional: --cli-region is always passed (agent fills it). Project ID (--project_id) is resolved automatically from the profile or region parent project.
• Mutating actions (Manage R2 / Delete R1) require previewing the full command and obtaining user confirmation before execution; Delete R1 additionally requires an explicit confirmation that the resource will be permanently removed.

KooCLI Command Format Standard

The generic invocation shape is hcloud APIG <Operation> --cli-region=<region> [--key=value ...] — this is a format description only: <...> and [...] are placeholders, never executed verbatim.

Tool Parameter Validation (Mandatory)

Validate every parameter before execution; illegal input is rejected directly (never passed to hcloud):

Reference Documents

• references/cli-installation-guide.md — KooCLI install & authentication
• references/iam-policies.md — least-privilege IAM policies for APIG
• references/verification-method.md — how to verify each action
• references/dataflow-diagram.md — Mermaid data flow diagrams
• references/acceptance-criteria.md — acceptance criteria for the skill

APIG documentation: https://support.huaweicloud.com/apig/

Quality Reporting (Unified CLI)

CLI installation: see "Step 0: Install skill-quality-cli" at the top of this document (idempotent, skips instantly if installed).

Report execution quality on every run of this skill, using either mode below (the CLI auto-resolves session_id / agent from the current session metadata — zero-content light reads; user_input / tokens / steps are attached when the caller provides them).

⚠️ PATH note: the CLI is installed to ~/.local/bin/, which is NOT always in $PATH in some environments. If skill-quality-cli: command not found (exit 127) appears, run export PATH="$HOME/.local/bin:$PATH" first (ensure_cli.sh does this automatically), then retry; or call the absolute path ~/.local/bin/skill-quality-cli directly.

Mode 1 (recommended, automatic) — wrap the whole execution

For script/command-style skills, wrap the entire command with run:

skill-quality-cli run --skill-name <skill-name> -- <your command>

Mode 2 (multi-step / instruction-style skills)

Report once per step: skill-quality-cli report --skill-name <skill-name> --status <success|sys_fail|biz_fail|cancel>

⚠️ Mandatory rule: any hcloud command executed by this skill MUST be wrapped with skill-quality-cli run — bare hcloud calls are strictly forbidden.

CLI installation & auto-update

• Auto install (offline, idempotent): run bash scripts/ensure_cli.sh before execution (skips if installed); it deploys the bundled scripts/cli/ sources locally — no external download, never blocks
• Bundled version pinned: the installed wrapper runs the exact CLI version shipped with this skill package; auto-upgrade is disabled (SKILL_QUALITY_NO_AUTO_UPGRADE=1)
• Manual cold-start (fallback): if ensure_cli.sh is unavailable, run the bundled CLI directly — python3 scripts/cli/cli_entry.py run --skill-name huawei-cloud-apig-instance-management -- hcloud ... (if the wrapper ~/.local/bin/skill-quality-cli already exists, export PATH="$HOME/.local/bin:$PATH" first, then call skill-quality-cli)