Cloud-Native API Gateway / AI Gateway / API Gateway Instance Inspection

Scenario Description

Perform health inspection on Alibaba Cloud gateway instances, retrieve monitoring metric data, and generate inspection reports.

Architecture: Cloud Monitor (CMS) + API Gateway (cloudapi) + Cloud-Native API Gateway / AI Gateway (apig)

Supported Product Types:

Note: API Gateway shared instances (VPC_SHARED) do not support inspection. Only dedicated instances (VPC_DEDICATED) are supported.

Installation

Pre-check: Aliyun CLI >= 3.3.3 required

Run aliyun version to verify >= 3.3.3. If not installed or version too low,
follow the upgrade/installation instructions below.

Upgrade / Install Aliyun CLI (choose one based on your platform):

• macOS (Homebrew):
  codeBlock.copy

  brew install aliyun-cli        # fresh install
  brew upgrade aliyun-cli        # upgrade existing
• Linux / macOS (binary):
  codeBlock.copy

  curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash
• Windows (PowerShell):
  codeBlock.copy

  Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"
  Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli

After upgrade, verify with aliyun version.
For more platforms and detailed instructions, see references/cli-installation-guide.md.

Pre-check: Aliyun CLI plugin update required

[MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.
[MUST] run aliyun plugin update to ensure that any existing plugins are always up-to-date.

Observability (MUST follow for every aliyun command)

Upon loading this skill, generate a random session ID (32-char lowercase hex string) once
for the entire session. Use it as {session-id} below.

Rule: Every aliyun CLI command that calls a cloud API MUST include the --user-agent flag.

Local utility commands (e.g. configure, plugin, version) do not support this flag
and should be excluded.

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

Environment Variables

No additional environment variables required. Credentials are configured via aliyun configure.

Authentication

Pre-check: Alibaba Cloud Credentials Required

Security Rules:

• NEVER read, echo, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)
• NEVER ask the user to input AK/SK directly in the conversation or command line
• NEVER use aliyun configure set with literal credential values
• ONLY use aliyun configure list to check credential status

codeBlock.copy

aliyun configure list

Check the output for a valid profile (AK, STS, or OAuth identity).

If no valid profile exists, STOP here.

1. Obtain credentials from Alibaba Cloud Console
2. Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)
3. Return and re-run after aliyun configure list shows a valid profile

RAM Permission Policy

This skill only involves read-only operations and requires the following minimum RAM permissions:

Full policy document: references/ram-policies.md

[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:

1. Read references/ram-policies.md to get the full list of permissions required by this SKILL
2. Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions
3. Pause and wait until the user confirms that the required permissions have been granted

Parameter Confirmation

IMPORTANT: Parameter Confirmation — Before executing any command or API call,
ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks,
passwords, domain names, resource specifications, etc.) MUST be confirmed with the
user. Do NOT assume or use default values without explicit user approval.

Available Region Check:

• AI Gateway Available Regions
• Cloud-Native API Gateway Available Regions
• API Gateway Available Regions

Core Workflow

Step 1: Collect Required Information

Before starting queries, the following information must be confirmed (proactively ask the user if not provided). Using default configurations is prohibited:

1. Cloud Product Type — Which cloud product the user wants to query.(Cloud-Native API Gateway / AI Gateway / API Gateway).
2. Region (RegionId) — The region where the instance is located.
3. Instance ID — The unique identifier of the instance.
4. Time Range — The time point or time range for the query.

Step 2: Query Instance Information

[MUST] API Invocation Requirement:
The gateway list MUST be queried by calling the Apig ListGateways API via CLI plugin mode.
This is a mandatory step — skipping the gateway list query is NOT allowed.

[MUST] Plugin Mode Only:
All commands in this skill MUST be executed using CLI plugin mode. Traditional API format (PascalCase action names) is NOT allowed.
If the plugin is not installed, run aliyun plugin install --names apig to install it, then retry.

2.1 Cloud-Native API Gateway / AI Gateway

API Mapping: Product Apig | Action ListGateways | Version 2019-01-01

aliyun apig list-gateways --region ${region_id} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

Note: The gatewayType in the response indicates the instance type: API (Cloud-Native API Gateway), AI (AI Gateway)

2.2 API Gateway

aliyun cloudapi describe-instances --api-version 2016-07-14 --region ${region_id} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

Note: The InstanceType in the response indicates the instance type. Only VPC_DEDICATED (dedicated) instances are supported. VPC_SHARED shared instances do not support inspection.

Step 3: Retrieve Monitoring Metric Data

3.1 Cloud-Native API Gateway / AI Gateway

[MUST] API Invocation Requirement:
Monitoring metrics MUST be queried using the Cms DescribeMetricData API via CLI plugin mode

CRITICAL — PROHIBITED APIs:

• DO NOT USE DescribeMetricList (aliyun cms describe-metric-list) — returns a different response format and is NOT accepted
• DO NOT USE DescribeMetricMetaList (aliyun cms describe-metric-meta-list) — DO NOT call this API to discover or list available metrics

ALL metric names are already provided below. No metric discovery is needed:

• For Cloud-Native API Gateway instances: select metric names from the Supported Metrics for Cloud-Native API Gateway table below
• For AI Gateway instances: select metric names from the Supported Metrics for AI Gateway table below
• Use the exact Metric Name values from the corresponding table directly as the --metric-name parameter

API Mapping: Product Cms | Action DescribeMetricData | Version 2019-01-01 | Namespace acs_cnapigateway

aliyun cms describe-metric-data \
--namespace acs_cnapigateway \
--region ${region} \
--api-version 2019-01-01 \
--metric-name ${metric-name} \
--period 60 \
--start-time ${start-time} \
--end-time ${end-time} \
--dimensions '[{"instanceId": "${instanceId}"}]' \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

Notes:

• start-time / end-time use Unix millisecond timestamps
• instanceId must be passed in dimensions
• MUST query ALL of the following metric categories: CPU Usage, Memory Usage, Connections, Network IO, Rate Limiting
• Only check CPU, memory, connections, network IO, rate limiting, and bandwidth

Supported Metrics for Cloud-Native API Gateway:

Supported Metrics for AI Gateway:

3.2 API Gateway Dedicated Instances

[MUST] API Invocation Requirement:
For API Gateway dedicated instances, you MUST use the CloudAPI dedicated APIs via CLI plugin mode to query monitoring data.
DO NOT use Cloud Monitor (CMS) for API Gateway dedicated instances. CMS is only for Cloud-Native API Gateway / AI Gateway (Step 3.1).

The following 5 API calls are ALL mandatory:

#	API	Product	Action	Version	Notes
1	Dropped packets	cloudapi	DescribeInstanceDropPacket	2016-07-14
2	Dropped connections	cloudapi	DescribeInstanceDropConnections	2016-07-14
3	SLB connections	cloudapi	DescribeInstanceSlbConnect	2016-07-14
4	Traffic	cloudapi	DescribeInstanceTraffic	2016-07-14	Query RELEASE, PRE, TEST separately
5	QPS	cloudapi	DescribeInstanceQps	2016-07-14	Query RELEASE, PRE, TEST separately

CRITICAL: Traffic and QPS must each be queried 3 times — once for each environment (RELEASE, PRE, TEST).
This means a total of 7 API calls (5 base APIs, but Traffic and QPS each × 3 environments).

Note: For API Gateway, skip 3.1 and execute this step directly. Time format uses ISO8601 UTC (YYYY-MM-DDThh:mm:ssZ)

# 1. Dropped packets
aliyun cloudapi describe-instance-drop-packet \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --sbc-name Maximum \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

# 2. Dropped connections
aliyun cloudapi describe-instance-drop-connections \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --sbc-name Maximum \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

# 3. SLB connections
aliyun cloudapi describe-instance-slb-connect \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --sbc-name Maximum \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

# 4. Traffic — MUST query RELEASE, PRE, and TEST environments separately (3 calls)
aliyun cloudapi describe-instance-traffic \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --stage-name RELEASE \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

aliyun cloudapi describe-instance-traffic \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --stage-name PRE \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

aliyun cloudapi describe-instance-traffic \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --stage-name TEST \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

# 5. QPS — MUST query RELEASE, PRE, and TEST environments separately (3 calls)
aliyun cloudapi describe-instance-qps \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --stage-name RELEASE \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

aliyun cloudapi describe-instance-qps \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --stage-name PRE \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

aliyun cloudapi describe-instance-qps \
--start-time ${start-time} --end-time ${end-time} \
--instance-id ${instanceId} --stage-name TEST \
--api-version 2016-07-14 --region ${region} \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-apigw-inspection/{session-id}

Step 4: Generate Inspection Report

4.1 Anomaly Check Rules

Spike Detection: Alert when the increase within a period exceeds the threshold (CPU > 30%, Memory > 25%, Connections > 50%, Network IO > 40%)

4.2 Report Structure

The inspection report should include the following sections:

1. Basic Information — Product type, instance ID, region, inspection time
2. Inspection Results Overview — Table format showing the status of each metric
3. Detailed Analysis — Peak values, trends, and analysis for each metric
4. Risk Assessment — List of high/medium risk items
5. Optimization Recommendations — Recommendations based on actual issues (omit if all metrics are normal)
6. Conclusion — Summary of inspection results

Important: All data must come from actual API responses. Fabricating data is strictly prohibited.

Success Verification

For verification methods, see references/verification-method.md

Cleanup

This skill only involves read-only operations. No resource cleanup is required.

Command List

For the full command list, see references/related-commands.md

Best Practices

1. Plugin Mode Only: All commands MUST be executed using aliyun CLI plugin mode. Traditional API format (PascalCase action names) is NOT allowed. If a required plugin is not installed, run aliyun plugin install --names <plugin-name> to install it first.
2. Confirm Parameters: All user-customizable parameters must be confirmed before execution
3. Check Region: Ensure the region is within the available regions for the corresponding product
4. Check Instance Type: API Gateway only supports dedicated instance inspection
5. Time Format: Cloud Monitor uses millisecond timestamps; API Gateway uses ISO8601 UTC
6. Data Accuracy: Report data must come from actual API responses
7. Risk Classification: Strictly follow threshold standards for risk assessment

Reference Links