Huawei Cloud APIG API Gateway Management
<!-- cli-install-version: 3.9.0 -->
Step 0: Install skill-quality-cli (idempotent, skip if already installed)
The CLI installs into
, which is
not always in (bare
may
exit 127). Export it first, then run the installer (it also persists the PATH export into
/
):
bash
export PATH="$HOME/.local/bin:$PATH"
bash scripts/ensure_cli.sh
The script installs the bundled
sources to
when
is not found (offline, no external download),
re-exports PATH into
/
; 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
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 actions):
| Category | Level | Actions |
|---|
| Query | R3 (read-only, auto) | huawei_list_apig_instances
, , huawei_list_apig_api_groups
, , huawei_list_apig_throttling_policies
|
| Analyze | R3 (read-only, auto) | huawei_analyze_apig_public_access
, huawei_analyze_apig_publish_chain
|
| Manage | R2 (preview + confirm) | huawei_create_apig_instance
, huawei_add_apig_ingress_eip
, huawei_create_apig_api_group
, , , , huawei_create_apig_throttling_policy
|
| Manage (delete) | R1 (preview + explicit confirm) | huawei_delete_apig_instance
, , huawei_delete_apig_api_group
|
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 ).
Critical Warnings
| # | Trap | Why |
|---|
| 1 | API group region-locked | An API group cannot move across regions. Create it in the target region from the start. |
| 2 | Throttling default is per-API | The default throttling policy applies per API. Use app-level quotas () for per-user limits. |
| 3 | CORS must be explicit | OPTIONS preflight fails until CORS is configured on the API (). |
| 4 | spec has no public IP | Use + --loadbalancer_provider=elb
for public access ( is internal-only). |
| 5 | Instance creation takes 5-15 min | Long-running async operation. The final state is Running (NOT "SUCCESS"). Poll with and wait for . |
| 6 | is from the API Group | NOT from the instance. Get it from / response. It is an internal-only domain and may NXDOMAIN from the public internet — for public access use the instance . |
| 7 | API / throttling policy names must NOT have hyphens | only. Hyphens cause regex validation failure (verified for CreateRequestThrottlingPolicyV2
too, APIG.2011). |
| 8 | VPC params need prefix | / / --security_group.name=<n>
with KooCLI 7.x. |
| 9 | works only with provider | (without "Ingress") requires the provider. Ingress bandwidth minimum is 5 Mbit/s. |
Prerequisites
- hcloud CLI installed and authenticated — see
references/cli-installation-guide.md
- Authentication: AK/SK via environment variables ( /
or any / pair containing access/secret key)
or a local KooCLI profile created with the command
- Region: APIG is region-specific. Always pass (e.g. , ); if omitted, the profile region is used.
- IAM permissions — see
references/iam-policies.md
for least-privilege policies
- 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
is shown in the CLI help (the KooCLI metadata directory is
lowercase
; both forms are accepted).
Query — Instances
huawei_list_apig_instances
— list APIG instances and status (including
):
bash
# --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
| Parameter | Required | Description |
|---|
| Yes (auto) | Region, agent fills automatically |
| No | Items per page, default 20 (max 500) |
| No | Query offset (default 0) |
| No | Filter by gateway status, e.g. , , |
— query a single instance detail:
bash
# 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: 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.
| Parameter | Required | Description |
|---|
| No | Gateway ID (pass it to narrow to one instance) |
Query — API Groups
huawei_list_apig_api_groups
— list API groups (response includes
):
bash
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListApiGroupsV2 --cli-region={region} --instance_id={instance_id} --limit=20
| Parameter | Required | Description |
|---|
| Yes | Gateway ID |
| / | No | Pagination |
| / | No | Filter by group name / ID |
Query — APIs
— list APIs in an instance:
bash
# --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
| Parameter | Required | Description |
|---|
| Yes | Gateway ID |
| No | Filter by API group ID |
| / | No | Filter by API name / ID |
| / | No | Filter by method / URI |
| No | Filter by auth type (IAM/APP/NONE) |
Query — Throttling Policies
huawei_list_apig_throttling_policies
— list request throttling policies
(operation name per the KooCLI APIG help enumeration):
bash
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListRequestThrottlingPolicyV2 --cli-region={region} --instance_id={instance_id} --limit=20
| Parameter | Required | Description |
|---|
| Yes | Gateway ID |
| / | No | Filter by policy name / ID |
| / | No | Pagination |
Analyze — Public Access
huawei_analyze_apig_public_access
— analyze whether an instance is publicly
reachable and what address to use:
bash
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
| Parameter | Required | Description |
|---|
| Yes | Gateway ID |
Analysis rules: if
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 (
spec or
provider).
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:
bash
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
| Parameter | Required | Description |
|---|
| Yes | Gateway ID |
| No | Restrict to one API group |
Report which hop is missing (no instance / no group / no API / no
),
and warn when
is used for public access instead of
.
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
until
:
bash
# 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}
| Parameter | Required | Description |
|---|
| No* | Gateway name (needed to identify the instance) |
| No* | (no public access) / (public access with ) |
| / | No* | VPC / subnet in the target region |
| No* | Security group (create one first via the VPC service) |
| No* | for public access, for internal only |
| No* | AZ code like (NOT a UUID) |
| No | Required for enterprise accounts; use for the default project |
*The current KooCLI metadata marks CreateInstanceV2 parameters optional, but the
APIG API rejects the request without
,
,
,
,
and
— always
pass them.
Always check
first to confirm
parameter names before building the command.
Polling loop after creation:
bash
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
(NOT "SUCCESS"). States such as
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
-provider
gateway (bandwidth minimum 5 Mbit/s):
bash
# --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
| Parameter | Required | Description |
|---|
| Yes | Gateway ID |
--bandwidth_charging_mode
| No | or |
| No | Ingress bandwidth in Mbit/s (min 5) |
Verification after binding:
may
not appear
promptly (verified: still
8 minutes after success) — do NOT rely on it as
the sole evidence. Confirm success via the
response/task
acceptance, a retry returning
("Public inbound access is enabled"),
or the EIP list in the APIG console. Works only with
-provider instances.
Manage — Create API Group
huawei_create_apig_api_group
— create an API group:
bash
# --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}
| Parameter | Required | Description |
|---|
| Yes | Gateway ID |
| Yes | Group name (3-255 chars, starts with letter/digit) |
| No | Description |
Manage — Create API
— create an API in a group:
bash
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}
| Parameter | Required | Description |
|---|
| Yes | Gateway ID |
| Yes | API group ID |
| Yes | API type, e.g. (public) |
| Yes | API name — only, NO hyphens |
| Yes | / / |
| Yes | / / / / / / / |
| Yes | Request URI, e.g. |
| Yes | / / |
| Yes | / / / . Known limitation (KooCLI 7.2.12, verified): creating an HTTP-backend API via fails with APIG.2011 invalid req_protocol
for every reasonable parameter combination, while / backends succeed. If an HTTP backend is required, use the APIG console, or create the API with a / backend and switch it in the console. |
| / / | No | Backend routing when |
| No | Set when CORS preflight is required |
Manage — Update API
— modify an existing API (auth mode, path, backend, etc.):
bash
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}
| Parameter | Required | Description |
|---|
| Yes | API ID (from ) |
| / | Yes | Locate the API inside the gateway |
| remaining | Yes | Same required fields as |
Manage — Publish / Offline API
— batch publish or take offline APIs
(operation is
BatchPublishOrOfflineApiV2
;
is a 1-based array):
bash
# 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
| Parameter | Required | Description |
|---|
| Yes | (publish) / (take offline) |
| Yes | Environment ID (NOT the name). Query it first with hcloud APIG ListEnvironmentsV2 --cli-region={region} --instance_id={instance_id}
and use the returned — the name is rejected with APIG.3003. |
| Yes* | 1-based array of API IDs (max 1000). Or use instead. |
| No | Publish/offline all APIs of a group (alternative to ) |
| No | Description |
Manage — Create Throttling Policy
huawei_create_apig_throttling_policy
— create a request throttling policy
(operation name per the KooCLI APIG help enumeration):
bash
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}
| Parameter | Required | Description |
|---|
| Yes | Gateway ID |
| Yes | Policy name — only, NO hyphens (same constraint as API names, see Critical Warning 7) |
| Yes | / / / |
| Yes | Time interval in the unit |
| Yes | Max API calls within the interval |
| No | Per-app quota (use for per-user limits) |
| / | No | Per-user / per-IP limits |
--enable_adaptive_control
| No | Adaptive throttling (default false) |
Delete — Instance
huawei_delete_apig_instance
— delete a dedicated gateway (
R1: explicit user
confirmation required before running):
bash
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG DeleteInstancesV2 --cli-region={region} --instance_id={instance_id}
| Parameter | Required | Description |
|---|
| Yes | Gateway ID to delete |
Delete — API
— delete an API from a group (
R1: explicit user
confirmation required before running):
bash
# 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}
| Parameter | Required | Description |
|---|
| Yes | Gateway ID |
| Yes | API ID to delete (from ) |
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):
bash
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}
| Parameter | Required | Description |
|---|
| Yes | Gateway ID |
| Yes | API group ID to delete |
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
(
) before deleting the group. Only after every API is gone does
succeed.
Parameter Confirmation
- Every 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: is always passed (agent fills it). 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.
| Feature | Description | Example |
|---|
| Service name | (CLI help display; metadata dir ) | hcloud APIG ListInstancesV2 --cli-region={region}
|
| Operation name | PascalCase, verified against the KooCLI APIG help output | |
| Region | | |
| Simple param | | |
| Indexed array param | (1-based) | |
| Nested object param | | --backend_api.req_uri=/demo
|
Tool Parameter Validation (Mandatory)
Validate every parameter before execution; illegal input is rejected directly (never passed to
):
| Validation | Rule |
|---|
| Whitelist enum | Documented value sets (, , , , , ...) must match exactly; anything else → refuse, listing allowed values |
| Type check | Numeric params (, , , ) must parse as integers; name/ID params must be strings matching (no hyphens, see Critical Warnings #7) |
| Reject unknown | Params absent from hcloud APIG <Operation> --help
are rejected before running the command |
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
<!-- cli-inject-version: 3.9.0 -->
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
/
from the current session metadata — zero-content light reads;
/
/
are attached when the caller provides them).
⚠️ PATH note: the CLI is installed to , which is NOT always in 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
:
bash
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 — 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 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 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 )