SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsalibabacloud-network-reachability-analysis

alibabacloud-network-reachability-analysis

Deployment & operations

View repository

Updated 10-15 08:54

About this skill

NIS Network Reachability Analysis / NIS 网络可达性分析

Language / 语言: Respond in the same language the user uses. If the user speaks Chinese, use the Chinese (zh-CN) prompts below. If the user speaks English, use the English (en) prompts below.

Guides an agent through interactive network reachability analysis using Alibaba Cloud NIS. Covers forward/reverse path analysis, topology visualization (Mermaid), and monitoring diagnostics for resources along the path.

Architecture: NIS (CreateAndAnalyzeNetworkPath + GetNetworkReachableAnalysis) + CloudMonitor (DescribeMetricData)

⚠️ CRITICAL / 关键: READ-ONLY OPERATIONS ONLY

This skill performs read-only network diagnostics. DO NOT create, modify, or delete any cloud resources.

This skill only performsread-onlynetwork diagnostic operations.Strictly prohibitedto create, modify, or delete any cloud resources.

Allowed: CreateAndAnalyzeNetworkPath, GetNetworkReachableAnalysis, DescribeMetricData, Describe* APIs

Allowed: analysis task creation and query, monitoring data query, Describe* type query APIs

Forbidden: Create* (except CreateAndAnalyzeNetworkPath), Modify*, Delete*, Start*, Stop*, Run* APIs

Prohibited: creation-type APIs (except CreateAndAnalyzeNetworkPath ), modification, deletion, start/stop, execution-type APIs

Installation

Pre-check: Aliyun CLI >= 3.3.1 required Run aliyun version to verify >= 3.3.1. If not installed or version too low, see references/cli-installation-guide.md for installation instructions. Then [MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.

aliyun version
aliyun configure set --auto-plugin-install true

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
aliyun configure list --user-agent AlibabaCloud-Agent-Skills

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 Permissions

See references/ram-policies.md for the full RAM policy.

Required actions: nis:CreateAndAnalyzeNetworkPath, nis:GetNetworkReachableAnalysis, cms:DescribeMetricData.

Parameter Confirmation

IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., RegionId, instance IDs, IP addresses, protocol, ports, resource types, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

Collect the following parameters interactively:

Parameter Required Description (EN) Description (ZH) Default
RegionId Yes Region of the analysis task Region of the analysis task —
SourceType Yes ecs, vsw, internetIp, vpn, vbr Source type —
SourceId Yes Source resource ID (or public IP if internetIp) Source resource ID (for public IP type, directly enter the IP) —
SourceIpAddress Conditional On-Premise IP, required for vpn/vbr On-premise private IP,vpn/vbr whenrequired —
TargetType Yes ecs, vsw, internetIp, vpn, vbr, clb Target type —
TargetId Yes Target resource ID (or public IP if internetIp) Target resource ID (for public IP type, directly enter the IP) —
TargetIpAddress Conditional On-Premise IP, required for vpn/vbr On-premise private IP,vpn/vbr whenrequired —
Protocol Yes tcp, udp, or icmp Protocol type —
TargetPort Conditional Required for tcp/udp tcp/udp required when —
SourcePort Optional Source port Source port —

Interactive Collection Logic / 交互收集逻辑

Use the prompts matching the user's language:

Step 1 — Ask resource types / 询问资源类型

EN ZH
"What is the source resource type? (ecs / vsw / internetIp / vpn / vbr)" "What is thesource resource type? (ecs / vsw / internetIp / vpn / vbr)"
"What is the target resource type? (ecs / vsw / internetIp / vpn / vbr / clb)" "What is thetarget resource type? (ecs / vsw / internetIp / vpn / vbr / clb)"

Step 2 — Type-specific prompts / 按类型提示

Condition EN Prompt ZH Prompt
internetIp "For public IP analysis, please provide the public IP address directly as the ID." "When analyzing public network paths, please directly provide thepublic IP addressas the ID."
vpn / vbr "For hybrid cloud analysis, besides the resource ID, please also provide the On-Premise IP (private IP on your side)." "When connecting to an on-premise environment, in addition to the resource ID, please be sure to provide youron-premise private IP (On-Premise IP) to ensure accurate analysis."

Step 3 — Protocol & ports / 协议和端口

EN ZH
"What protocol? (tcp / udp / icmp) And what is the target port?" "What protocol is used? (tcp / udp / icmp) What is the target port?"

Core Workflow

Step 1: Forward Path Analysis / 正向路径分析

aliyun nis create-and-analyze-network-path \
  --source-id <SourceId> \
  --source-type <SourceType> \
  --target-id <TargetId> \
  --target-type <TargetType> \
  --protocol <Protocol> \
  --target-port <TargetPort> \
  --source-ip-address <SourceIpAddress> \
  --target-ip-address <TargetIpAddress> \
  --region <RegionId> \
  --user-agent AlibabaCloud-Agent-Skills

Omit --source-ip-address / --target-ip-address if SourceType/TargetType is not vpn or vbr. Omit --target-port if Protocol is icmp.

Record the returned NetworkReachableAnalysisId.

⚠️ MANDATORY / 强制: ALWAYS perform reverse path analysis after forward analysis completes.

MUST execute Step 3 (Reverse Path Analysis) immediately after Step 2 finishes. Do NOT skip or omit reverse path check.

Mustimmediately execute Step 3 (reverse path analysis) after the forward analysis is completed. It is strictly prohibited to skip or omit the reverse path check.

Step 2: Poll for Forward Result / 轮询正向结果

aliyun nis get-network-reachable-analysis \
  --network-reachable-analysis-id <ForwardAnalysisId> \
  --region <RegionId> \
  --user-agent AlibabaCloud-Agent-Skills

Repeat until NetworkReachableAnalysisStatus is finish. Extract Reachable, NetworkReachableAnalysisResult.

Step 3: Reverse Path Analysis / 反向路径分析

Swap source and target / 交换源和目的:

  • Forward SourceId/Type → Reverse TargetId/Type
  • Forward TargetId/Type → Reverse SourceId/Type
  • Forward SourceIpAddress → Reverse TargetIpAddress
  • Forward TargetIpAddress → Reverse SourceIpAddress

Port handling / 端口处理:

  • Reverse --source-port = Forward TargetPort (server listening port / 服务端监听端口)
  • Reverse --target-port = Random ephemeral port in range 49152 ~ 65535 (client ephemeral port / 客户端随机端口)

Since the client initiates the connection with a dynamically assigned ephemeral port, the reverse path (server → client) should use a random port in the ephemeral range (49152-65535) as the target port to simulate real return traffic.

Since the client uses a dynamically allocated ephemeral port when initiating a connection, the target port of the reverse path (server→client) should use a random value within the ephemeral port range (49152-65535) to simulate real return traffic.

aliyun nis create-and-analyze-network-path \
  --source-id <OriginalTargetId> \
  --source-type <OriginalTargetType> \
  --target-id <OriginalSourceId> \
  --target-type <OriginalSourceType> \
  --protocol <Protocol> \
  --source-port <OriginalTargetPort> \
  --target-port <RandomPort_49152_to_65535> \
  --source-ip-address <OriginalTargetIpAddress> \
  --target-ip-address <OriginalSourceIpAddress> \
  --region <RegionId> \
  --user-agent AlibabaCloud-Agent-Skills

Omit --source-ip-address / --target-ip-address if SourceType/TargetType is not vpn or vbr. If the source/target type is not vpn or vbr, you may omit --source-ip-address / --target-ip-address。

Step 4: Poll for Reverse Result / 轮询反向结果

Same as Step 2, using the reverse NetworkReachableAnalysisId.

Step 5: Result Interpretation / 结果解读

CRITICAL / 关键: Always use topologyData.positive from the actively initiated analysis task. IGNORE topologyData.reverse in any response — it is unreliable.

Always useactively initiatedthe topologyData.positive。 ignoreThe topologyData.reversein any response — it is unreliable.

For each direction (forward/reverse):

  1. Check Reachable field. If true, the path is connected. Check the Reachable field,true indicates reachability.
  2. If false, analyze from NetworkReachableAnalysisResult: If it is false, analyze the following fields to locate the blocking point:
    • errorCode — root cause code
    • securityGroupData — security group rules blocking traffic
    • routeData — route table entries causing drops

Step 6: Topology Visualization (Mermaid)

Generate a Mermaid diagram from topologyData.positive:

graph LR
  • Nodes: Extract nodeType and bizInsId from nodeList
  • Links: Build directional edges from linkList

Example:

graph LR
    ECS_i-src["ECS: i-bp1xxx"] --> VRouter_vrt-1["VRouter: vrt-xxx"]
    VRouter_vrt-1 --> VSW_vsw-1["VSW: vsw-xxx"]
    VSW_vsw-1 --> ENI_eni-1["ENI: eni-xxx"]
    ENI_eni-1 --> ECS_i-dst["ECS: i-bp2xxx"]

Step 7: Resource Monitoring Diagnostics

For resource IDs found in topologyData, if they match the prefixes below, query monitoring data for the last 1 hour: For the topologyData resource IDs along the path, if they match the following prefixes, querythe last 1 hourof monitoring data:

Prefix Namespace Metrics
ecs- acs_ecs_dashboard CPUUtilization, ConnectionUtilization, DiskReadWriteIOPSUtilization, BurstCredit, DiskIOQueueSize
eip- acs_vpc_eip out_ratelimit_drop_speed, net_out.rate_percentage, net_rxPkgs.rate
nat- acs_nat_gateway ErrorPortAllocationCount, SessionLimitDropConnection, SessionActiveConnectionWaterLever, SessionNewConnectionWaterLever, BWRateOutToOutside, DropTotalPps
clb- acs_slb_dashboard UnhealthyServerCount, UpstreamCode5xx, InstanceQpsUtilization, InstanceMaxConnectionUtilization, UpstreamRt, StatusCode4xx
vbr- acs_physical_connection VbrHealthyCheckLossPercent, VbrHealthyCheckLatency, PkgsRateLimitDropOutFromVpcToVbr, RateOutFromVpcToIDC

Query command (CMS uses PascalCase API-style, not plugin mode):

aliyun cms DescribeMetricData \
  --Namespace <Namespace> \
  --MetricName <MetricName> \
  --Dimensions '[{"instanceId":"<ResourceId>"}]' \
  --StartTime <1HourAgoTimestamp> \
  --EndTime <NowTimestamp> \
  --Period 60 \
  --user-agent AlibabaCloud-Agent-Skills

Rate limit: 10 calls/second per account. Batch queries across multiple metrics should be paced accordingly.

Cleanup

NIS reachability analysis is read-only — no cloud resources are created or modified. No cleanup is required. NIS reachability analysis is aread-only operation— it does not create or modify any cloud resources, so no cleanup is required.

Constraints

  1. IPv4 only — Only IPv4 path analysis is supported.
  2. Unidirectional analysis — Each analysis is one-way; reverse path requires a separate task with swapped source/target.
  3. CMS quota — DescribeMetricData shares 1,000,000 free calls/month with other CMS query APIs.
  4. CMS rate limit — 10 calls/second per account (including RAM users).

Best Practices

  1. Always perform both forward and reverse analysis to confirm bidirectional connectivity.
  2. When path is unreachable, check security group rules and route tables first.
  3. For vpn/vbr scenarios, always provide On-Premise IP. / vpn/vbr scenario, be sure to provide the private IP address outside the cloud.
  4. Use Mermaid topology diagrams to visualize traffic paths.
  5. Query monitoring data only for resources on the actual path.
  6. Present monitoring anomalies alongside reachability results.

References

Reference Contents (EN) Content (ZH)
references/ram-policies.md Required RAM permissions Required RAM permission policy
references/verification-method.md Step-by-step verification commands Step-by-step verification commands
references/acceptance-criteria.md Correct/incorrect CLI patterns Correct/incorrect CLI pattern comparison
references/cli-installation-guide.md Aliyun CLI installation guide Alibaba Cloud CLI installation guide