/alibabacloud-nginx-ingress-to-api-gateway

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 | Kee