Alicloud Nat Ops

> This skill follows the Agent Skill OpenSpec.

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

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

Your First Command

# 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

# 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:

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

# 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

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 internalip:internalport

Execution

# 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

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:

# 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

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

Operation: List Resources

# 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
• Source: buhaiqing/aliyun-skills
• License: MIT

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