\r \r

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

\r

Language / 语言: Respond in the same language the user uses.\r If the user speaks Chinese, use the Chinese (zh-CN) prompts below.\r If the user speaks English, use the English (en) prompts below.\r \r Guides an agent through interactive network reachability analysis using Alibaba Cloud NIS.\r Covers forward/reverse path analysis, topology visualization (Mermaid), and monitoring diagnostics\r for resources along the path.\r \r Architecture: NIS (CreateAndAnalyzeNetworkPath + GetNetworkReachableAnalysis) + CloudMonitor (DescribeMetricData)\r \r ⚠️ CRITICAL / 关键: READ-ONLY OPERATIONS ONLY\r \r This skill performs read-only network diagnostics. DO NOT create, modify, or delete any cloud resources.\r \r 本技能仅执行只读网络诊断操作。严禁创建、修改或删除任何云资源。\r \r Allowed: CreateAndAnalyzeNetworkPath, GetNetworkReachableAnalysis, DescribeMetricData, Describe* APIs\r \r 允许：分析任务创建与查询、监控数据查询、Describe* 类查询 API\r \r Forbidden: Create* (except CreateAndAnalyzeNetworkPath), Modify*, Delete*, Start*, Stop*, Run* APIs\r \r 禁止：创建类 API（除 CreateAndAnalyzeNetworkPath 外）、修改、删除、启停、执行类 API\r \r

Installation\r

\r

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

aliyun version\r
aliyun configure set --auto-plugin-install true\r
```\r
\r
## Authentication\r
\r
> **Pre-check: Alibaba Cloud Credentials Required**\r
>\r
> **Security Rules:**\r
> - **NEVER** read, echo, or print AK/SK values (e.g., `echo $ALIBABA_CLOUD_ACCESS_KEY_ID` is FORBIDDEN)\r
> - **NEVER** ask the user to input AK/SK directly in the conversation or command line\r
> - **NEVER** use `aliyun configure set` with literal credential values\r
> - **ONLY** use `aliyun configure list` to check credential status\r
>\r
> ```bash\r
> aliyun configure list --user-agent AlibabaCloud-Agent-Skills\r
> ```\r
> Check the output for a valid profile (AK, STS, or OAuth identity).\r
>\r
> **If no valid profile exists, STOP here.**\r
> 1. Obtain credentials from [Alibaba Cloud Console](https://ram.console.aliyun.com/manage/ak)\r
> 2. Configure credentials **outside of this session** (via `aliyun configure` in terminal or environment variables in shell profile)\r
> 3. Return and re-run after `aliyun configure list` shows a valid profile\r
\r
\r
## RAM Permissions\r
\r
See [references/ram-policies.md](references/ram-policies.md) for the full RAM policy.\r
\r
Required actions: `nis:CreateAndAnalyzeNetworkPath`, `nis:GetNetworkReachableAnalysis`, `cms:DescribeMetricData`.\r
\r
## Parameter Confirmation\r
\r
> **IMPORTANT: Parameter Confirmation** — Before executing any command or API call,\r
> ALL user-customizable parameters (e.g., RegionId, instance IDs, IP addresses,\r
> protocol, ports, resource types, etc.) MUST be confirmed with the user.\r
> Do NOT assume or use default values without explicit user approval.\r
\r
Collect the following parameters interactively:\r
\r
| Parameter | Required | Description (EN) | 说明 (ZH) | Default |\r
|-----------|----------|-------------------|-----------|---------|\r
| RegionId | Yes | Region of the analysis task | 分析任务所在地域 | — |\r
| SourceType | Yes | `ecs`, `vsw`, `internetIp`, `vpn`, `vbr` | 源端类型 | — |\r
| SourceId | Yes | Source resource ID (or public IP if `internetIp`) | 源资源 ID（公网 IP 类型直接填 IP） | — |\r
| SourceIpAddress | Conditional | On-Premise IP, **required** for `vpn`/`vbr` | 云下私网 IP，`vpn`/`vbr` 时**必填** | — |\r
| TargetType | Yes | `ecs`, `vsw`, `internetIp`, `vpn`, `vbr`, `clb` | 目的端类型 | — |\r
| TargetId | Yes | Target resource ID (or public IP if `internetIp`) | 目的资源 ID（公网 IP 类型直接填 IP） | — |\r
| TargetIpAddress | Conditional | On-Premise IP, **required** for `vpn`/`vbr` | 云下私网 IP，`vpn`/`vbr` 时**必填** | — |\r
| Protocol | Yes | `tcp`, `udp`, or `icmp` | 协议类型 | — |\r
| TargetPort | Conditional | Required for `tcp`/`udp` | `tcp`/`udp` 时必填 | — |\r
| SourcePort | Optional | Source port | 源端口 | — |\r
\r
### Interactive Collection Logic / 交互收集逻辑\r
\r
Use the prompts matching the user's language:\r
\r
**Step 1 — Ask resource types / 询问资源类型**\r
\r
| EN | ZH |\r
|----|-----|\r
| "What is the **source resource type**? (ecs / vsw / internetIp / vpn / vbr)" | "请问**源端资源类型**是什么？（ecs / vsw / internetIp / vpn / vbr）" |\r
| "What is the **target resource type**? (ecs / vsw / internetIp / vpn / vbr / clb)" | "请问**目的端资源类型**是什么？（ecs / vsw / internetIp / vpn / vbr / clb）" |\r
\r
**Step 2 — Type-specific prompts / 按类型提示**\r
\r
| Condition | EN Prompt | ZH Prompt |\r
|-----------|-----------|-----------|\r
| `internetIp` | "For public IP analysis, please provide the **public IP address** directly as the ID." | "分析公网路径时，请直接提供**公网 IP 地址**作为 ID 传入。" |\r
| `vpn` / `vbr` | "For hybrid cloud analysis, besides the resource ID, please also provide the **On-Premise IP** (private IP on your side)." | "连接云下环境时，除了资源 ID，请务必提供您的**云下私网 IP (On-Premise IP)** 以确保分析准确。" |\r
\r
**Step 3 — Protocol & ports / 协议和端口**\r
\r
| EN | ZH |\r
|----|-----|\r
| "What protocol? (tcp / udp / icmp) And what is the target port?" | "请问使用什么协议？（tcp / udp / icmp）目的端口是多少？" |\r
\r
## Core Workflow\r
\r
### Step 1: Forward Path Analysis / 正向路径分析\r
\r
```bash\r
aliyun nis create-and-analyze-network-path \\r
  --source-id \x3CSourceId> \\r
  --source-type \x3CSourceType> \\r
  --target-id \x3CTargetId> \\r
  --target-type \x3CTargetType> \\r
  --protocol \x3CProtocol> \\r
  --target-port \x3CTargetPort> \\r
  --source-ip-address \x3CSourceIpAddress> \\r
  --target-ip-address \x3CTargetIpAddress> \\r
  --region \x3CRegionId> \\r
  --user-agent AlibabaCloud-Agent-Skills\r
```\r
\r
> Omit `--source-ip-address` / `--target-ip-address` if SourceType/TargetType is not `vpn` or `vbr`.\r
> Omit `--target-port` if Protocol is `icmp`.\r
\r
Record the returned `NetworkReachableAnalysisId`.\r
\r
> ⚠️ **MANDATORY / 强制**: **ALWAYS perform reverse path analysis after forward analysis completes.**\r
> \r
> **MUST** execute Step 3 (Reverse Path Analysis) immediately after Step 2 finishes. Do NOT skip or omit reverse path check.\r
> \r
> **必须**在正向分析完成后立即执行 Step 3（反向路径分析）。严禁跳过或省略反向路径检查。\r
\r
### Step 2: Poll for Forward Result / 轮询正向结果\r
\r
```bash\r
aliyun nis get-network-reachable-analysis \\r
  --network-reachable-analysis-id \x3CForwardAnalysisId> \\r
  --region \x3CRegionId> \\r
  --user-agent AlibabaCloud-Agent-Skills\r
```\r
\r
Repeat until `NetworkReachableAnalysisStatus` is `finish`. Extract `Reachable`, `NetworkReachableAnalysisResult`.\r
\r
### Step 3: Reverse Path Analysis / 反向路径分析\r
\r
Swap source and target / 交换源和目的:\r
- Forward `SourceId/Type` → Reverse `TargetId/Type`\r
- Forward `TargetId/Type` → Reverse `SourceId/Type`\r
- Forward `SourceIpAddress` → Reverse `TargetIpAddress`\r
- Forward `TargetIpAddress` → Reverse `SourceIpAddress`\r
\r
**Port handling / 端口处理**:\r
- Reverse `--source-port` = Forward `TargetPort` (server listening port / 服务端监听端口)\r
- Reverse `--target-port` = Random ephemeral port in range **49152 ~ 65535** (client ephemeral port / 客户端随机端口)\r
\r
> 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.\r
>\r
> 由于客户端发起连接时使用动态分配的临时端口，反向路径（服务端→客户端）的目的端口应使用临时端口范围（49152-65535）内的随机值来模拟真实回程流量。\r
\r
```bash\r
aliyun nis create-and-analyze-network-path \\r
  --source-id \x3COriginalTargetId> \\r
  --source-type \x3COriginalTargetType> \\r
  --target-id \x3COriginalSourceId> \\r
  --target-type \x3COriginalSourceType> \\r
  --protocol \x3CProtocol> \\r
  --source-port \x3COriginalTargetPort> \\r
  --target-port \x3CRandomPort_49152_to_65535> \\r
  --source-ip-address \x3COriginalTargetIpAddress> \\r
  --target-ip-address \x3COriginalSourceIpAddress> \\r
  --region \x3CRegionId> \\r
  --user-agent AlibabaCloud-Agent-Skills\r
```\r
\r
> Omit `--source-ip-address` / `--target-ip-address` if SourceType/TargetType is not `vpn` or `vbr`.\r
> 若源/目的类型不是 `vpn` 或 `vbr`，可省略 `--source-ip-address` / `--target-ip-address`。\r
\r
### Step 4: Poll for Reverse Result / 轮询反向结果\r
\r
Same as Step 2, using the reverse `NetworkReachableAnalysisId`.\r
\r
### Step 5: Result Interpretation / 结果解读\r
\r
> **CRITICAL / 关键**: Always use `topologyData.positive` from the **actively initiated** analysis task.\r
> **IGNORE** `topologyData.reverse` in any response — it is unreliable.\r
> \r
> 始终使用**主动发起**的分析任务返回的 `topologyData.positive`。\r
> **忽略**任何响应中的 `topologyData.reverse`——它不可靠。\r
\r
For each direction (forward/reverse) / 对正向和反向分别：\r
\r
1. Check `Reachable` field. If `true`, path is connected. / 检查 `Reachable` 字段，`true` 表示可达。\r
2. If `false`, analyze from `NetworkReachableAnalysisResult`: / 若为 `false`，分析以下字段定位阻断点：\r
   - `errorCode` — root cause code / 根因错误码\r
   - `securityGroupData` — security group rules blocking traffic / 安全组拦截规则\r
   - `routeData` — route table entries causing drops / 路由表丢包条目\r
\r
### Step 6: Topology Visualization / 拓扑可视化 (Mermaid)\r
\r
Generate a Mermaid diagram from `topologyData.positive`:\r
\r
```\r
graph LR\r
```\r
\r
- **Nodes**: Extract `nodeType` and `bizInsId` from `nodeList`\r
- **Links**: Build directional edges from `linkList`\r
\r
Example:\r
```mermaid\r
graph LR\r
    ECS_i-src["ECS: i-bp1xxx"] --> VRouter_vrt-1["VRouter: vrt-xxx"]\r
    VRouter_vrt-1 --> VSW_vsw-1["VSW: vsw-xxx"]\r
    VSW_vsw-1 --> ENI_eni-1["ENI: eni-xxx"]\r
    ENI_eni-1 --> ECS_i-dst["ECS: i-bp2xxx"]\r
```\r
\r
### Step 7: Resource Monitoring Diagnostics / 途经资源监控诊断\r
\r
For resource IDs found in `topologyData`, if they match the prefixes below, query monitoring data for the **last 1 hour**:\r
对 `topologyData` 中途经的资源 ID，若匹配以下前缀，查询**最近 1 小时**监控数据：\r
\r
| Prefix | Namespace | Metrics |\r
|--------|-----------|---------|\r
| `ecs-` | `acs_ecs_dashboard` | `CPUUtilization`, `ConnectionUtilization`, `DiskReadWriteIOPSUtilization`, `BurstCredit`, `DiskIOQueueSize` |\r
| `eip-` | `acs_vpc_eip` | `out_ratelimit_drop_speed`, `net_out.rate_percentage`, `net_rxPkgs.rate` |\r
| `nat-` | `acs_nat_gateway` | `ErrorPortAllocationCount`, `SessionLimitDropConnection`, `SessionActiveConnectionWaterLever`, `SessionNewConnectionWaterLever`, `BWRateOutToOutside`, `DropTotalPps` |\r
| `clb-` | `acs_slb_dashboard` | `UnhealthyServerCount`, `UpstreamCode5xx`, `InstanceQpsUtilization`, `InstanceMaxConnectionUtilization`, `UpstreamRt`, `StatusCode4xx` |\r
| `vbr-` | `acs_physical_connection` | `VbrHealthyCheckLossPercent`, `VbrHealthyCheckLatency`, `PkgsRateLimitDropOutFromVpcToVbr`, `RateOutFromVpcToIDC` |\r
\r
Query command (CMS uses **PascalCase API-style**, not plugin mode):\r
\r
```bash\r
aliyun cms DescribeMetricData \\r
  --Namespace \x3CNamespace> \\r
  --MetricName \x3CMetricName> \\r
  --Dimensions '[{"instanceId":"\x3CResourceId>"}]' \\r
  --StartTime \x3C1HourAgoTimestamp> \\r
  --EndTime \x3CNowTimestamp> \\r
  --Period 60 \\r
  --user-agent AlibabaCloud-Agent-Skills\r
```\r
\r
> **Rate limit**: 10 calls/second per account. Batch queries across multiple metrics should be paced accordingly.\r
\r
## Cleanup / 清理\r
\r
NIS reachability analysis is **read-only** — no cloud resources are created or modified.\r
No cleanup is required.\r
NIS 可达性分析为**只读操作**——不会创建或修改任何云资源，无需清理。\r
\r
## Constraints / 使用限制\r
\r
1. **IPv4 only / 仅支持 IPv4** — Only IPv4 path analysis is supported.\r
2. **Unidirectional / 单向分析** — Each analysis is one-way; reverse path requires a separate task with swapped source/target.\r
3. **CMS quota / CMS 配额** — `DescribeMetricData` shares 1,000,000 free calls/month with other CMS query APIs.\r
4. **CMS rate limit / CMS 频控** — 10 calls/second per account (including RAM users).\r
\r
## Best Practices / 最佳实践\r
\r
1. Always perform both forward and reverse analysis to confirm bidirectional connectivity. / 始终执行正向+反向分析以确认双向连通性。\r
2. When path is unreachable, check security group rules and route tables first. / 路径不可达时，优先检查安全组规则和路由表。\r
3. For `vpn`/`vbr` scenarios, always provide On-Premise IP. / `vpn`/`vbr` 场景务必提供云下私网 IP。\r
4. Use Mermaid topology diagrams to visualize traffic paths. / 使用 Mermaid 拓扑图帮助用户可视化流量路径。\r
5. Query monitoring data only for resources on the actual path. / 仅查询实际路径上的资源监控数据以减少 API 调用。\r
6. Present monitoring anomalies alongside reachability results. / 将监控异常与可达性结果一并呈现，提供完整诊断。\r
\r
## References / 参考文件\r
\r
| Reference | Contents (EN) | 内容 (ZH) |\r
|-----------|---------------|-----------|\r
| [references/ram-policies.md](references/ram-policies.md) | Required RAM permissions | 所需 RAM 权限策略 |\r
| [references/verification-method.md](references/verification-method.md) | Step-by-step verification commands | 逐步验证命令 |\r
| [references/acceptance-criteria.md](references/acceptance-criteria.md) | Correct/incorrect CLI patterns | 正确/错误 CLI 模式对照 |\r
| [references/cli-installation-guide.md](references/cli-installation-guide.md) | Aliyun CLI installation guide | 阿里云 CLI 安装指南 |\r