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	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:
    # 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 网关 完成迁移。
   • 不完全兼容（存在不兼容注解）：按以下顺序操作：
     1. 构建并推送自定义 WasmPlugin OCI 镜像
     2. 将迁移后 Ingress YAML 中的 OCI URL 占位符替换为真实的 WasmPlugin 镜像地址
     3. 将替换后的 Ingress YAML 部署到集群中
     4. 参考 Nginx Ingress 迁移到云原生 API 网关 继续后续操作，在步骤一「指定 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:

# 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 无需任何权限）