Skill: sdk-team/alibabacloud-nginx-ingress-to-api-gateway (version 0.0.1)

--- 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 `key-rate-limit` plugin | | `enable-modsecurity` | ❌ Unsupported | Built-in `waf` plugin | | `denylist-source-range` | ❌ Unsupported | Higress native `higress.io/blacklist-source-range` | | `service-upstream` | ❌ Unsupported | Safe to drop (Envoy default behavior) | | `ssl-ciphers` | ❌ Unsupported | Rename to `ssl-cipher` (compatible) | > **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: ```yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: <original-name>-apig namespace: <original-namespace> annotations: # Compatible annotations preserved # Unsupported annotations replaced with higress.io/wasmplugin if needed spec: ingressClassName: apig # MUST be hardcoded to apig rules: ... # Preserved from original tls: ... # Preserved from original ``` ### Step 5: Output Migration Report > 所有输出建议使用中文（中文）。包括分析表、迁移总结、后续操作指南及所有说明性文字。代码块（YAML、Go、bash）保持原始语法。 > > 以下所有内容均为标准输出项，建议在一次响应中完整输出，无需逐项询问用户。 Output ALL of the following for each Ingress: 1. **兼容性分析表** — annotation, value, category (兼容/可忽略/不支持), action 2. **迁移后的 Ingress YAML** — ready for user to apply 3. **自定义 WasmPlugin 源码** — if Step 3 determined custom plugins are needed (skip only if no custom plugin is needed) 4. **迁移总结** — what changed, value changes, plugins needed 5. **后续操作指南** — 根据兼容性分析结果，分场景告知用户完整的迁移操作路径： - **完全兼容（无不兼容注解）**：所有注解均为兼容或可忽略类型，用户可直接参考 [Nginx Ingress 迁移到云原生 API 网关](https://help.aliyun.com/zh/api-gateway/cloud-native-api-gateway/user-guide/migrating-from-nginx-ingress-to-cloud-native-api-gateway) 完成迁移。 - **不完全兼容（存在不兼容注解）**：按以下顺序操作： 1. 构建并推送自定义 WasmPlugin OCI 镜像 2. 将迁移后 Ingress YAML 中的 OCI URL 占位符替换为真实的 WasmPlugin 镜像地址 3. 将替换后的 Ingress YAML 部署到集群中 4. 参考 [Nginx Ingress 迁移到云原生 API 网关](https://help.aliyun.com/zh/api-gateway/cloud-native-api-gateway/user-guide/migrating-from-nginx-ingress-to-cloud-native-api-gateway) 继续后续操作，在步骤一「指定 IngressClass」处需指定为 `apig` 5. **网关版本要求**：使用 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: ```bash # Validate migrated YAML syntax (user runs this) kubectl apply --dry-run=client -f <migrated-ingress>.yaml # Confirm ingressClassName is apig 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 1. Always classify ALL annotations before generating migrated YAML — never skip annotations 2. Use placeholders (`<REGION>`, `<YOUR_REGISTRY>`) for unspecified parameters; never hardcode user-specific values 3. Preserve original `rules`, `tls`, and `namespace` in migrated YAML 4. Add `-apig` suffix to migrated Ingress name for easy identification 5. Prefer built-in plugins over custom WasmPlugin — check `references/builtin-plugins.md` first 6. For custom WasmPlugin, use `github.com/higress-group/wasm-go/pkg/wrapper` SDK exclusively 7. Track annotation value changes (e.g., `ewma` → `round_robin`) explicitly in the report 8. For `server-snippet`/`configuration-snippet`, enumerate every directive and verify 1:1 conversion completeness 9. 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 无需任何权限） |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)