| name | alibabacloud-nginx-ingress-to-api-gateway |
| description | Alibaba Cloud APIG Migration Skill. Migrate Kubernetes nginx Ingress resources to Alibaba Cloud API Gateway (APIG, ingressClass: apig).
Users provide Ingress YAML (paste, file, or directory) — no cluster access required for analysis.
Covers annotation compatibility classification, Higress native mapping, built-in plugin selection, custom WasmPlugin development, migrated Ingress YAML generation, and migration report with deployment guide.
Triggers: "nginx ingress migration", "APIG compatibility", "gateway migration", "ingress-nginx to APIG", "nginx迁移", "网关迁移", "Ingress兼容性分析", "APIG迁移", "迁移评估", "annotation兼容性", "WasmPlugin开发".
|
Nginx Ingress to APIG Migration
Scenario Description
Migrate Kubernetes nginx Ingress resources to Alibaba Cloud API Gateway (APIG). APIG is an Envoy-based gateway (Higress) that uses ingressClassName: apig. This skill classifies every nginx.ingress.kubernetes.io/* annotation into Compatible / Ignorable / Unsupported, resolves unsupported annotations via a four-level decision tree (Higress native → safe-to-drop → built-in plugin → custom WasmPlugin), generates migrated Ingress YAML, and produces a deployment-ready migration report.
Architecture: nginx Ingress Controller → APIG (Envoy/Higress) + optional WasmPlugin (Go, proxy-wasm-go-sdk)
The core analysis workflow operates entirely offline on user-provided YAML — no cluster access, CLI tools, or cloud credentials required.
Installation
This skill operates entirely offline on user-provided YAML. No CLI tools, SDKs, or cloud credentials are required.
On-demand tools (only when the workflow reaches a step that needs them):
| Tool | When needed | Check command | Minimum version |
|---|
| jq | Script-based offline analysis | jq --version | >= 1.6 |
| python3 + PyYAML | YAML parsing (alternative to yq) | python3 -c "import yaml; print(yaml.__version__)" | python3 >= 3.8, PyYAML >= 5.0 |
| yq | YAML parsing (alternative to python3+PyYAML) | yq --version | >= 4.0 |
| Go | Step 3 determines a custom WasmPlugin is needed | go version | >= 1.24 |
| Docker | Custom WasmPlugin needs to be built as OCI image | docker version | — |
Do NOT pre-check or prompt installation of any tool during analysis.
Environment Variables
No environment variables required. This skill does not invoke any cloud APIs or CLI tools.
Authentication
Not applicable. This skill does not invoke Alibaba Cloud APIs or CLI. No credentials are needed.
RAM Policy
Not applicable. This skill operates entirely on local YAML files and does not call any cloud APIs.
Parameter Confirmation
This skill only performs analysis and code generation — it does NOT execute any deployment or cluster write operations.
When the user provides Ingress YAML, proceed immediately with the full workflow (Step 1→5) and output the complete result. Do NOT ask for RegionId, OCI registry, or any other parameter. Use <REGION> and <YOUR_REGISTRY> placeholders in the output.
请避免以下交互模式，直接执行对应操作即可：
- "是否需要我分析这个 Ingress？" — 建议直接分析
- "是否需要生成迁移后的 YAML？" — 建议直接生成
- "是否需要创建迁移配置文件/检查清单？" — 建议直接创建
- "是否需要开发 WasmPlugin？" — 如果决策树判定需要，建议直接开发
- "请确认 RegionId / OCI 地址" — 建议使用占位符
| Parameter Name | Required/Optional | Description | Default Value |
|---|
| Ingress YAML | Required | nginx Ingress YAML to migrate (paste, file, or directory) | — |
When Ingress YAML is not provided: If the user asks about migration but does not provide YAML,
respond with: "请提供需要迁移的 nginx Ingress YAML（可以直接粘贴、提供文件路径或目录路径）。"
Do NOT abort the conversation — guide the user to provide the required input.
Core Workflow
建议：收到 YAML 后一次性完成全部分析步骤
当用户提供 Ingress YAML 时，建议立即执行全部步骤（Step 1→5）并在一次响应中输出完整结果。
- 对于未指定的参数（如 RegionId、OCI registry），使用
<REGION> 等占位符
- 收到 YAML 后直接进入分析流程，无需额外确认
- 各步骤之间连续执行，无需中途暂停询问用户
- 迁移配置文件和检查清单作为标准输出的一部分自动生成
- 整个工作流是确定性的：YAML 输入 → 完整迁移报告输出，无需中间确认
- 唯一必需的输入是 Ingress YAML 本身
Step 1: Parse Ingress YAML
Accept YAML from any of the following input formats:
- Direct paste in conversation (with or without markdown code fences)
- File path (e.g.,
ingress.yaml, ./k8s/ingress.yaml)
- Directory path (scan all
.yaml/.yml files for Ingress resources)
- Multi-document YAML (separated by
---)
- Partial YAML (missing
apiVersion/kind — infer as Ingress if annotations with nginx.ingress.kubernetes.io/* are present)
For each Ingress found, extract all nginx.ingress.kubernetes.io/* annotations.
If the user's message mentions migration/analysis but does NOT include any YAML, respond with:
"请提供需要迁移的 nginx Ingress YAML（可以直接粘贴、提供文件路径或目录路径）。"
Do NOT abort or error out — guide the user to provide input.
Step 2: Classify Annotations
Classify each annotation into exactly one of three categories. See references/annotation-mapping.md for the complete 117-annotation lookup table.
| Category | Count | Action | Example |
|---|
| Compatible | 50 | Keep in migrated YAML | rewrite-target, enable-cors, canary-weight, ssl-redirect |
| Ignorable | 16 | Strip (Envoy handles natively) | proxy-connect-timeout, proxy-buffering, proxy-body-size |
| Unsupported | 51 | Strip → resolve via decision tree | auth-url, server-snippet, limit-rps |
Inline Quick Lookup — High-Frequency Annotations:
| Annotation | Category | Action |
|---|
rewrite-target | ✅ Compatible | Keep |
enable-cors | ✅ Compatible | Keep |
cors-allow-origin | ✅ Compatible | Keep |
ssl-redirect | ✅ Compatible | Keep |
canary / canary-weight / canary-by-header | ✅ Compatible | Keep |
whitelist-source-range | ✅ Compatible | Keep |
backend-protocol | ✅ Compatible | Keep |
use-regex | ✅ Compatible | Keep |
upstream-vhost | ✅ Compatible | Keep |
proxy-connect-timeout | ⚪ Ignorable | Strip |
proxy-read-timeout | ⚪ Ignorable | Strip |
proxy-send-timeout | ⚪ Ignorable | Strip |
proxy-body-size | ⚪ Ignorable | Strip |
proxy-buffering | ⚪ Ignorable | Strip |
client-body-buffer-size | ⚪ Ignorable | Strip |
auth-url | ❌ Unsupported | WasmPlugin (HTTP callout) |
server-snippet | ❌ Unsupported | WasmPlugin (directive conversion) |
configuration-snippet | ❌ Unsupported | WasmPlugin (directive conversion) |
limit-rps | ❌ Unsupported | Built-in key-rate-limit plugin |
limit-connections | ❌ Unsupported | Built-in plugin |
If an annotation is NOT in the above table, look it up in references/annotation-mapping.md. If still not found, classify as Unsupported and resolve via the decision tree in Step 3.
Special value changes (compatible but value must change):
load-balance: ewma → round_robin (APIG does not support EWMA)ssl-ciphers → rename to ssl-cipher (singular form)affinity-mode: persistent → balanced (APIG only supports balanced)
Step 3: Resolve Unsupported Annotations
For each unsupported annotation, follow this decision tree in order:
1. Higress native annotation? → Use native equivalent (no WasmPlugin needed)
2. Safe to drop? → Remove without replacement
3. Built-in platform plugin? → Use built-in OCI image via higress.io/wasmplugin annotation
4. None of the above? → Develop custom WasmPlugin
See references/migration-patterns.md for the complete decision tree, and references/builtin-plugins.md for the built-in plugin catalog.
Higress native mappings:
| nginx annotation | Higress equivalent |
|---|
denylist-source-range | higress.io/blacklist-source-range |
mirror-target | higress.io/mirror-target-service + higress.io/mirror-percentage |
Safe-to-drop: service-upstream, enable-access-log, proxy-request-buffering: off, connection-proxy-header
Built-in plugins: limit-rps/limit-connections → key-rate-limit, enable-modsecurity → waf. See references/builtin-plugins.md.
Custom WasmPlugin (last resort): auth-url, server-snippet, configuration-snippet, etc. See references/wasm-plugin-sdk.md for SDK reference, references/snippet-patterns.md for conversion patterns.
Step 4: Generate Migrated Ingress YAML
For each input Ingress, generate a migrated copy:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: <original-name>-apig
namespace: <original-namespace>
annotations:
spec:
ingressClassName: apig
rules: ...
tls: ...
Step 5: Output Migration Report
所有输出建议使用中文（中文）。包括分析表、迁移总结、后续操作指南及所有说明性文字。代码块（YAML、Go、bash）保持原始语法。
以下所有内容均为标准输出项，建议在一次响应中完整输出，无需逐项询问用户。
Output ALL of the following for each Ingress:
- 兼容性分析表 — annotation, value, category (兼容/可忽略/不支持), action
- 迁移后的 Ingress YAML — ready for user to apply
- 自定义 WasmPlugin 源码 — if Step 3 determined custom plugins are needed (skip only if no custom plugin is needed)
- 迁移总结 — what changed, value changes, plugins needed
- 后续操作指南 — 根据兼容性分析结果，分场景告知用户完整的迁移操作路径：
- 完全兼容（无不兼容注解）：所有注解均为兼容或可忽略类型，用户可直接参考 Nginx Ingress 迁移到云原生 API 网关 完成迁移。
- 不完全兼容（存在不兼容注解）：按以下顺序操作：
- 构建并推送自定义 WasmPlugin OCI 镜像
- 将迁移后 Ingress YAML 中的 OCI URL 占位符替换为真实的 WasmPlugin 镜像地址
- 将替换后的 Ingress YAML 部署到集群中
- 参考 Nginx Ingress 迁移到云原生 API 网关 继续后续操作，在步骤一「指定 IngressClass」处需指定为
apig
- 网关版本要求：使用 WasmPlugin 需确保云原生 API 网关版本在 2.1.16 及以上，否则需要升级版本或创建新网关
See references/deployment-guide-template.md for the guide template.
Scope boundary: This skill generates all artifacts and instructions. It does NOT execute kubectl apply, docker push, or any cluster/registry write operations. Those are left to the user.
No confirmation needed: Every item above is always generated. Never ask "是否需要生成迁移文件/检查清单/部署指南？"
Success Verification Method
See references/verification-method.md for verification steps to include in the migration report.
The migration report should instruct the user to verify with:
kubectl apply --dry-run=client -f <migrated-ingress>.yaml
grep "ingressClassName: apig" <migrated-ingress>.yaml
This skill outputs verification instructions for the user. It does NOT execute these commands.
Cleanup
Not applicable. This skill only generates text output (YAML, Go source code, migration report). No cloud resources or cluster objects are created by this skill.
API and Command Tables
This skill does not execute any CLI commands or API calls. All output is text-based (YAML, Go source code, migration report with instructions for the user).
Best Practices
- Always classify ALL annotations before generating migrated YAML — never skip annotations
- Use placeholders (
<REGION>, <YOUR_REGISTRY>) for unspecified parameters; never hardcode user-specific values
- Preserve original
rules, tls, and namespace in migrated YAML
- Add
-apig suffix to migrated Ingress name for easy identification
- Prefer built-in plugins over custom WasmPlugin — check
references/builtin-plugins.md first
- For custom WasmPlugin, use
github.com/higress-group/wasm-go/pkg/wrapper SDK exclusively
- Track annotation value changes (e.g.,
ewma → round_robin) explicitly in the report
- For
server-snippet/configuration-snippet, enumerate every directive and verify 1:1 conversion completeness
- Never execute cluster write operations (
kubectl apply, docker push, etc.) — only output instructions for the user
Reference Links
| Reference | Contents |
|---|
references/annotation-mapping.md | Complete 117-annotation compatibility lookup table |
references/migration-patterns.md | Decision tree, Higress native mappings, safe-to-drop list, special handling |
references/builtin-plugins.md | APIG built-in platform plugins catalog with OCI URLs |
references/platform-oci-registry.md | Region-specific OCI registry addresses for built-in plugins |
references/snippet-patterns.md | server-snippet / configuration-snippet → WasmPlugin conversion patterns |
references/wasm-plugin-sdk.md | Higress WASM Go Plugin SDK reference (core API) |
references/wasm-http-client.md | WasmPlugin HTTP client patterns (external auth, callouts) |
references/wasm-redis-client.md | WasmPlugin Redis client patterns (rate limiting, session) |
references/wasm-advanced-patterns.md | Advanced WasmPlugin patterns (streaming, tick, leader election) |
references/wasm-local-testing.md | Local WasmPlugin testing with Docker Compose |
references/plugin-deployment.md | WasmPlugin build, OCI push, and Ingress annotation binding |
references/deployment-guide-template.md | Migration report deployment guide template |
references/acceptance-criteria.md | Testing acceptance criteria with correct/incorrect patterns |
references/verification-method.md | Success verification steps and commands |
references/security-review-policy.md | 定期安全复审策略与检查项 |
references/security-impact-assessment.md | 安全影响评估与数据处理流程 |
references/ram-policies.md | RAM 权限声明（本 Skill 无需任何权限） |
