# Alicloud Nat Ops

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-buhaiqing-aliyun-skills-alicloud-nat-ops`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [buhaiqing](https://agentstack.voostack.com/s/buhaiqing)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [buhaiqing](https://github.com/buhaiqing)
- **Source:** https://github.com/buhaiqing/aliyun-skills/tree/main/alicloud-nat-ops

## Install

```sh
agentstack add skill-buhaiqing-aliyun-skills-alicloud-nat-ops
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> This skill follows the [Agent Skill OpenSpec](https://agentskills.io/specification).

# Alibaba Cloud NAT Operations Skill

## Runtime Rules

| Area | Rule | Reference |
| --- | --- | --- |
| CLI path | **MANDATORY**: Always prefer the SkillOpt wrapper `./scripts/vpc-skillopt-wrapper.sh` for all NAT CLI operations to enable automated self-repair and dynamic optimization; fallback to native `aliyun nat` only when the wrapper is unavailable or `skillopt-lib.sh` is missing. | [CLI](references/cli-usage.md), [SkillOpt](references/skillopt-integration.md) |

## Overview

Alibaba Cloud NAT (Network Address Translation) Gateway enables private instances in VPCs to access the internet (SNAT) or be accessed from the internet (DNAT). This skill is an **operational runbook** for agents: explicit scope, credential rules, pre-flight checks, **cli-first execution** (official **`aliyun` CLI** as primary path, **JIT Go SDK** as fallback), response validation, and failure recovery.

### CLI applicability (repository policy)

- **`cli_applicability: cli-first`:** Official `aliyun` fully supports NAT. CLI is the **primary** execution path for all operations. JIT Go SDK is the **fallback** only when CLI lacks support for a specific edge-case operation.

### Quick Start

不知道从哪里开始？直接看 [Prompt Examples](references/prompt-examples.md)，里面有 30+ 条自然语言提示词示例，覆盖 NAT 网关创建、SNAT/DNAT 配置、NAT 释放、端口映射、故障诊断等场景，复制即用。

## Trigger & Scope (Agent-Readable)

### SHOULD Use This Skill When

- User mentions "Alibaba Cloud NAT" OR "NAT网关" OR "SNAT" OR "DNAT" OR "Network Address Translation"
- Task involves CRUD or lifecycle operations on **NAT Gateway** (create, describe, modify, delete)
- Task involves **SNAT entries** (create, describe, delete) for outbound internet access
- Task involves **DNAT entries / ForwardTable** (create, describe, delete) for inbound port mapping
- Task involves **FULLNAT entries** (create, describe, delete) for bidirectional NAT
- Task involves **NAT Gateway billing modification** (PayBySpec ↔ PayByActualUsage)
- Task involves **NAT quota management** (check limits, SNAT/DNAT entry counts)
- Task keywords: NAT, NAT Gateway, SNAT, DNAT, FULLNAT, 弹性NAT, 增强型NAT, 地址转换, 端口映射, CreateNatGateway, CreateSnatEntry, CreateForwardEntry, SNAT表, DNAT表
- User asks to deploy, configure, troubleshoot, or monitor NAT resources **via API, SDK, CLI, or automation**

### SHOULD NOT Use This Skill When

- Task is purely billing / account management → delegate to: `alicloud-billing-ops` (when present)
- Task is RAM / permission model only → delegate to: `alicloud-ram-ops` (when present)
- Task is about **EIP allocation/management** → delegate to: `alicloud-eip-ops`
- Task is about **VPC/vSwitch creation** → delegate to: `alicloud-vpc-ops` (when present)
- Task is about **ECS instances** → delegate to: `alicloud-ecs-ops`
- Task is about **RDS / databases** → delegate to: `alicloud-rds-ops` (when present)
- Task is about **SLB / load balancing** → delegate to: `alicloud-slb-ops`

## Delegation Rules

| 能力 | 委托目标 | 说明 |
|------|----------|------|
| GCL 质量门禁 | `alicloud-gcl-runner-ops` | 对写操作执行前，委托 GCL 循环进行对抗性评审 |

## Variable Convention (Agent-Readable)

| Placeholder | Meaning | Agent Action |
|-------------|---------|--------------|
| `{{env.ALIBABA_CLOUD_ACCESS_KEY_ID}}` | From runtime environment | NEVER ask the user; fail if unset |
| `{{env.ALIBABA_CLOUD_ACCESS_KEY_SECRET}}` | From runtime environment | NEVER ask the user; fail if unset |
| `{{env.ALIBABA_CLOUD_REGION_ID}}` | From runtime environment | Use documented default only if skill explicitly allows |
| `{{user.region}}` | User-supplied region | Ask once; reuse |
| `{{user.nat_gateway_id}}` | User-supplied NAT Gateway ID | Ask once; reuse |
| `{{user.nat_name}}` | User-supplied NAT Gateway name | Ask once; reuse |
| `{{user.vpc_id}}` | User-supplied VPC ID | Ask once; reuse |
| `{{user.vswitch_id}}` | User-supplied VSwitch ID | Ask once; reuse |
| `{{user.snat_table_id}}` | User-supplied SNAT Table ID | Ask once; reuse |
| `{{user.snat_entry_id}}` | User-supplied SNAT Entry ID | Ask once; reuse |
| `{{user.forward_table_id}}` | User-supplied Forward Table ID | Ask once; reuse |
| `{{user.forward_entry_id}}` | User-supplied DNAT Entry ID | Ask once; reuse |
| `{{user.source_cidr}}` | SNAT source CIDR | Ask once; reuse |
| `{{user.eip_id}}` | User-supplied EIP Allocation ID | Ask once; reuse |

> **凭据安全（强制）：** 参考 [Credential Masking 规则](../alicloud-skill-generator/references/credential-masking.md)

## API and Response Conventions (Agent-Readable)

### Response Field Table

| Operation | JSON Path | Type | Description |
|-----------|-----------|------|-------------|
| CreateNatGateway | `$.NatGatewayId` | string | New NAT Gateway ID |
| DescribeNatGateways | `$.NatGateways.NatGateway[].NatGatewayId` | array | NAT Gateway IDs |
| DescribeNatGateways | `$.NatGateways.NatGateway[].Status` | array | Status: Creating/Available/Modifying/Deleting |
| CreateSnatEntry | `$.SnatTableId` | string | SNAT Table ID (gateway-level) |
| DescribeSnatTableEntries | `$.SnatTableEntries.SnatTableEntry[].SnatEntryId` | array | SNAT Entry IDs |
| CreateForwardEntry | `$.ForwardTableId` | string | Forward Table ID (gateway-level) |
| DescribeForwardTableEntries | `$.ForwardTableEntries.ForwardTableEntry[].ForwardEntryId` | array | DNAT Entry IDs |
| DeleteNatGateway | `$.RequestId` | string | Request ID |

### Expected State Transitions

| Operation | Initial State | Target State | Poll Interval | Max Wait |
|-----------|---------------|--------------|---------------|----------|
| CreateNatGateway | `Creating` | `Available` | 5s | 300s |
| DeleteNatGateway | any | (absent) | 5s | 300s |
| CreateSnatEntry | — | `Available` | 2s | 60s |
| CreateForwardEntry | — | `Available` | 2s | 60s |

## Quick Start

### What This Skill Does

This skill enables you to create, manage, and release Alibaba Cloud NAT Gateways and their SNAT/DNAT entries using the `aliyun` CLI (primary) or JIT Go SDK (fallback).

### Prerequisites

- [ ] `aliyun` CLI installed (or Go runtime for JIT fallback)
- [ ] Credentials configured: `ALIBABA_CLOUD_ACCESS_KEY_ID`, `ALIBABA_CLOUD_ACCESS_KEY_SECRET`
- [ ] Region set: `ALIBABA_CLOUD_REGION_ID`
- [ ] VPC and VSwitch exist (pre-requisites for NAT Gateway)

### Verify Setup

```bash
# Check CLI and credentials
aliyun vpc DescribeNatGateways --RegionId {{env.ALIBABA_CLOUD_REGION_ID}} --PageSize 1
```

### Your First Command

```bash
# Example: List all NAT Gateways
aliyun vpc DescribeNatGateways --RegionId {{env.ALIBABA_CLOUD_REGION_ID}} \
  --output cols=NatGatewayId,Name,Status,Spec,VpcId rows=NatGateways.NatGateway[].{NatGatewayId:NatGatewayId,Name:Name,Status:Status,Spec:Spec,VpcId:VpcId}
```

### Next Steps

- [Core Concepts](references/core-concepts.md) — Understand NAT Gateway architecture and types
- [Common Operations](#execution-flows) — Create NAT, configure SNAT/DNAT, release
- [Troubleshooting](references/troubleshooting.md) — Fix SNAT/DNAT failures

## Capabilities at a Glance

| Operation | Description | Complexity | Risk Level |
|-----------|-------------|------------|------------|
| Create NAT Gateway | Create enhanced NAT or VPC NAT gateway | Medium | Low |
| Describe | View NAT Gateway details | Low | None |
| Modify | Change NAT Gateway attributes or billing | Low | Low |
| Delete | Remove NAT Gateway | Low | **High** — irreversible |
| Create SNAT | Create SNAT entry for outbound access | Medium | Low |
| Create DNAT (ForwardEntry) | Create DNAT entry for inbound port mapping | Medium | Medium |
| Create FULLNAT | Create FULLNAT entry for bidirectional NAT | Medium | Low |
| List | View all SNAT/DNAT entries | Low | None |

> **EXECUTION MANDATORY RULE**: 所有 control-plane CLI 执行步骤 **必须** 通过 SkillOpt wrapper `./scripts/vpc-skillopt-wrapper.sh` 运行。
> 以下所有代码块中的 `aliyun vpc ...` 命令在执行时应替换为 `./scripts/vpc-skillopt-wrapper.sh  ...`。
> 仅在 wrapper 脚本不可用或 `skillopt-lib.sh` 缺失时，才退回到原生 `aliyun vpc` CLI 调用。
> 参考 `## Runtime Rules` 中的 CLI path 规则。

## Execution Flows (Agent-Readable)

### Operation: Create NAT Gateway

**When to use:**
- You need private ECS instances to access the internet (outbound via SNAT)
- You need to expose private instances via port mapping (inbound via DNAT)
- Enhanced NAT Gateway (recommended) or VPC NAT gateway

**What you need:**
- VPC ID
- VSwitch ID (must be in the same VPC — Required for Enhanced NAT)
- NAT type: `Enhanced` (recommended) or `Normal`
- Billing method: `PayBySpec` (fixed spec) or `PayByActualUsage` (usage-based)

**What to expect:**
- NAT Gateway provisioning takes ~1-2 minutes
- Enters `Available` state when ready

#### Pre-flight Checks

| Check | Method | Expected | On Failure |
|-------|--------|----------|------------|
| CLI availability | `aliyun vpc DescribeRegions` | Exit code 0 | HALT; install CLI |
| VPC exists | `aliyun vpc DescribeVpcs --VpcId {{user.vpc_id}}` | VPC found, Status=Available | HALT; create VPC |
| VSwitch exists | `aliyun vpc DescribeVSwitches --VSwitchId {{user.vswitch_id}}` | VSwitch found, Status=Available | HALT; create VSwitch |
| VSwitch in VPC | VSwitch.VpcId == VpcId | Match | HALT; use correct VSwitch |
| NAT quota | DescribeNatGateways + TotalCount | Under NAT Gateway quota | HALT; request quota increase |

#### Execution — CLI

```bash
# Create Enhanced NAT Gateway
aliyun vpc CreateNatGateway \
  --RegionId "{{user.region}}" \
  --VpcId "{{user.vpc_id}}" \
  --NatType "Enhanced" \
  --VSwitchId "{{user.vswitch_id}}" \
  --Name "{{user.nat_name}}" \
  --BillingMethod "PayBySpec"
```

#### Post-execution Validation

1. Capture `{{output.nat_gateway_id}}` from response `$.NatGatewayId`.
2. Poll until `Available`:

```bash
aliyun vpc DescribeNatGateways \
  --RegionId "{{user.region}}" \
  --NatGatewayId "{{output.nat_gateway_id}}" \
  --waiter expr='NatGateways.NatGateway[0].Status' to=Available timeout=300 interval=5
```

### Operation: Create SNAT Entry

**When to use:**
- You need instances in a vSwitch/CIDR to access the internet via NAT
- You want to use specific EIPs as the SNAT source IP

**What you need:**
- NAT Gateway ID (must be `Available`)
- EIP Allocation ID for SNAT source
- Source CIDR or vSwitch ID

**What to expect:**
- SNAT entry created within seconds
- Instances in source range can now reach internet via the EIP

#### Pre-flight Checks

| Check | Method | Expected | On Failure |
|-------|--------|----------|------------|
| NAT Gateway Available | DescribeNatGateways | Status=`Available` | HALT; wait for NAT creation |
| EIP exists and Available | `aliyun vpc DescribeEipAddresses --AllocationId {{user.eip_id}}` | Status=Available or InUse on same NAT | Verify/allocate EIP via `alicloud-eip-ops` |
| Source CIDR is valid | Validate CIDR format | Valid subnet CIDR | Fix CIDR format |

#### Execution

```bash
# Create SNAT entry for a CIDR
aliyun vpc CreateSnatEntry \
  --RegionId "{{user.region}}" \
  --NatGatewayId "{{user.nat_gateway_id}}" \
  --SnatIp "{{user.eip_address}}" \
  --SourceCIDR "{{user.source_cidr}}" \
  --SnatEntryName "{{user.snat_entry_name}}"
```

#### Post-execution Validation

```bash
aliyun vpc DescribeSnatTableEntries \
  --RegionId "{{user.region}}" \
  --NatGatewayId "{{user.nat_gateway_id}}"
```

### Operation: Create DNAT Entry (Forward Entry)

**When to use:**
- You need to expose a private port to the internet (e.g., port 80, 443, SSH)
- You want to map an external port on an EIP to an internal port on an ECS

**What you need:**
- NAT Gateway ID (Available)
- EIP address for external IP
- Internal IP (private ECS IP)
- Protocol (TCP/UDP/Any)
- External port and Internal port

**What to expect:**
- DNAT entry created within seconds
- External traffic to EIP:port is forwarded to internal_ip:internal_port

#### Execution

```bash
# Create DNAT entry (TCP port mapping)
aliyun vpc CreateForwardEntry \
  --RegionId "{{user.region}}" \
  --NatGatewayId "{{user.nat_gateway_id}}" \
  --IpProtocol "TCP" \
  --ExternalIp "{{user.external_ip}}" \
  --ExternalPort "{{user.external_port}}" \
  --InternalIp "{{user.internal_ip}}" \
  --InternalPort "{{user.internal_port}}" \
  --ForwardEntryName "{{user.forward_entry_name}}"
```

#### Post-execution Validation

```bash
aliyun vpc DescribeForwardTableEntries \
  --RegionId "{{user.region}}" \
  --NatGatewayId "{{user.nat_gateway_id}}"
```

### Operation: Delete NAT Gateway

#### Pre-flight (Safety Gate)

- **MUST** delete ALL SNAT entries first.
- **MUST** delete ALL DNAT entries first.
- **MUST** unbind ALL associated EIPs first.
- **MUST** obtain explicit confirmation: irreversible delete.
- Check dependencies:

```bash
# Check SNAT entries
aliyun vpc DescribeSnatTableEntries --RegionId {{env.ALIBABA_CLOUD_REGION_ID}} --NatGatewayId {{user.nat_gateway_id}}
# Check DNAT entries
aliyun vpc DescribeForwardTableEntries --RegionId {{env.ALIBABA_CLOUD_REGION_ID}} --NatGatewayId {{user.nat_gateway_id}}
```

#### Execution

```bash
aliyun vpc DeleteNatGateway \
  --RegionId "{{user.region}}" \
  --NatGatewayId "{{user.nat_gateway_id}}"
```

### Operation: List Resources

```bash
# List all NAT Gateways
aliyun vpc DescribeNatGateways --RegionId "{{env.ALIBABA_CLOUD_REGION_ID}}" \
  --output cols=NatGatewayId,Name,Status,Spec,VpcId rows=NatGateways.NatGateway[].{NatGatewayId:NatGatewayId,Name:Name,Status:Status,Spec:Spec,VpcId:VpcId}

# List SNAT entries for a NAT Gateway
aliyun vpc DescribeSnatTableEntries --RegionId "{{env.ALIBABA_CLOUD_REGION_ID}}" --NatGatewayId "{{user.nat_gateway_id}}" \
  --output cols=SnatEntryId,SnatIp,SourceCIDR rows=SnatTableEntries.SnatTableEntry[].{SnatEntryId:SnatEntryId,SnatIp:SnatIp,SourceCIDR:SourceCIDR}

# List DNAT entries for a NAT Gateway
aliyun vpc DescribeForwardTableEntries --RegionId "{{env.ALIBABA_CLOUD_REGION_ID}}" --NatGatewayId "{{user.nat_gateway_id}}" \
  --output cols=ForwardEntryId,IpProtocol,ExternalIp:ExternalPort rows=ForwardTableEntries.ForwardTableEntry[].{ForwardEntryId:ForwardEntryId,IpProtocol:IpProtocol,ExternalIpIpPort:ExternalIp":"ExternalPort}
```

## Failure Recovery

| Error pattern | Max retries | Backoff | Agent Action | UX Feedback |
|---------------|-------------|---------|--------------|-------------|
| `InvalidParameter` | 0–1 | — | Fix args; retry once | `[ERROR] InvalidParameter. Check parameters against API spec.` |
| `InvalidVpcId.NotFound` | 0 | — | HALT | `[ERROR] VPC not found. Verify VpcId.` |
| `InvalidVSwitchId.NotFound` | 0 | — | HALT | `[ERROR] VSwitch not found. Verify VSwitchId.` |
| `QuotaExceeded.NatGateway` | 0 | — | HALT | `[ERROR] NAT Gateway quota reached. Delete unused or request increase.` |
| `QuotaExceeded.SnatEntry` | 0 | — | HALT | `[ERROR] SNAT entry quota reached (200 per NAT Gateway). Delete unused entries.` |
| `DependencyViolation.SnatEntryExists` | 0 | — | HALT | `[ERROR] Delete all SNAT entries before deleting NAT Gateway.` |
| `DependencyViolation.ForwardEntryExists` | 0 | — | HALT | `[ERROR] Delete all DNAT entries before deleting NAT Gateway.` |
| `InvalidEipStatus.InUseByOtherNat` | 0 | — | HALT | `[ERROR] EIP is bound to another NAT Gateway. Unbind first.` |
| `InsufficientBalance` | 0 | — | HALT | `[ERROR] Insufficient balance. Recharge account.` |
| `Forbidden.RAMUser` | 0 | — | HALT | `[ERROR] RAM user lacks permissions. Add AliyunNATFullAccess policy.` |
| `Throttling` / 429 | 3 | exponential | Back off | `⚠️ Rate limit. Retrying in {backoff}s...` |
| `InternalError` / 5xx | 3 | 2s,4s,8s | Retry; then HALT | `[ERROR] InternalError. Retry or escalate.` |

## Prerequisites

见 [执行环境配置](../alicloud-skill-generator/references/execution-environment.md)

**Go SDK:** `github.com/alibabacloud-go/vpc-20160428/v3/client`

---

## Advanced Analytics

以下深度分析文档仅在用户明确需要时加载，**不要在常规操作中读取**：

| 场景 | 文档 |
|------|------|
| 成本优化、资源分析 | [advanced/finops-optimization.md](references/advanced/finops-optimization.md) |

---

## Well-Architected Assessment (卓越架构)

This skill's operations are evaluated against Alibaba Cloud's [Well-Archi

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [buhaiqing](https://github.com/buhaiqing)
- **Source:** [buhaiqing/aliyun-skills](https://github.com/buhaiqing/aliyun-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-buhaiqing-aliyun-skills-alicloud-nat-ops
- Seller: https://agentstack.voostack.com/s/buhaiqing
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.