📦 Alibabacloud Nginx Ingress To Api Gateway — alibabacloud-nginx-ingress-to-api-gateway — Nginx Ingress 迁移至 APIG

场景描述

将 Kubernetes nginx Ingress 资源迁移至阿里云 API Gateway（APIG）。APIG 是一个基于 Envoy 的网关（Higress），使用 ingressClassName: apig。该技能将每个 nginx.ingress.kubernetes.io/ 注解分类为 Compatible / Ignorable / Unsupported，通过四级决策树解析不支持的注解（Higress 原生 → 安全可丢弃 → 内置插件 → 自定义 WasmPlugin），生成迁移后的 Ingress YAML，并生成可直接部署的迁移报告。

架构: nginx Ingress Controller → APIG (Envoy/Higress) + optional WasmPlugin (Go, proxy-wasm-go-sdk)

核心分析工作流完全在用户提供的 YAML 上离线运行 — 无需集群访问、CLI 工具或云凭证。

安装

此技能完全在用户提供的 YAML 上离线运行。无需 CLI 工具、SDK 或云凭证。

按需工具（仅在工作流到达需要它们的步骤时）：

工具	何时需要	检查命令	最低版本
jq	基于脚本的离线分析	jq --version	>= 1.6
python3 + PyYAML	YAML 解析（yq 的替代方案）	python3 -c "import yaml; print(yaml.__version__)"	python3 >= 3.8, PyYAML >= 5.0
yq	YAML 解析（python3+PyYAML 的替代方案）	yq --version	>= 4.0
Go	步骤 3 判定需要自定义 WasmPlugin	go version	>= 1.24
Docker	自定义 WasmPlugin 需要构建为 OCI 镜像	docker version	—

在分析期间，请勿预检查或提示安装任何工具。

环境变量

无需环境变量。此技能不调用任何云 API 或 CLI 工具。

认证

不适用。此技能不调用阿里云 API 或 CLI。不需要凭证。

RAM 策略

不适用。此技能完全在本地 YAML 文件上运行，不调用任何云 API。

参数确认

此技能仅执行分析和代码生成 — 不执行任何部署或集群写入操作。

>

当用户提供 Ingress YAML 时，立即继续执行完整工作流（步骤 1→5）并输出完整结果。请勿询问 RegionId、OCI registry 或任何其他参数。在输出中使用 和 占位符。

>

请避免以下交互模式，直接执行对应操作即可：
- "是否需要我分析这个 Ingress？" — 建议直接分析
- "是否需要生成迁移后的 YAML？" — 建议直接生成
- "是否需要创建迁移配置文件/检查清单？" — 建议直接创建
- "是否需要开发 WasmPlugin？" — 如果决策树判定需要，建议直接开发
- "请确认 RegionId / OCI 地址" — 建议使用占位符

参数名称	必需/可选	描述	默认值
Ingress YAML	必需	要迁移的 nginx Ingress YAML（粘贴、文件或目录）	—

当未提供 Ingress YAML 时：如果用户询问迁移但未提供 YAML，
响应：「请提供需要迁移的 nginx Ingress YAML（可以直接粘贴、提供文件路径或目录路径）。」
请勿中止对话 — 引导用户提供所需输入。

核心工作流

建议：收到 YAML 后一次性完成全部分析步骤

>

当用户提供 Ingress YAML 时，建议立即执行全部步骤（Step 1→5）并在一次响应中输出完整结果。
- 对于未指定的参数（如 RegionId、OCI registry），使用 等占位符
- 收到 YAML 后直接进入分析流程，无需额外确认
- 各步骤之间连续执行，无需中途暂停询问用户
- 迁移配置文件和检查清单作为标准输出的一部分自动生成
- 整个工作流是确定性的：YAML 输入 → 完整迁移报告输出，无需中间确认
- 唯一必需的输入是 Ingress YAML 本身

步骤 1：解析 Ingress YAML

接受以下任何输入格式的 YAML：

• 对话中直接粘贴（带或不带 markdown 代码块）
• 文件路径（例如 ingress.yaml、./k8s/ingress.yaml）
• 目录路径（扫描所有 .yaml/.yml 文件以查找 Ingress 资源）
• 多文档 YAML（用 --- 分隔）
• 部分 YAML（缺少 apiVersion/kind — 如果存在带 nginx.ingress.kubernetes.io/ 的 annotations，则推断为 Ingress）

对于找到的每个 Ingress，提取所有 nginx.ingress.kubernetes.io/* 注解。

如果用户消息提及迁移/分析但未包含任何 YAML，响应：
「请提供需要迁移的 nginx Ingress YAML（可以直接粘贴、提供文件路径或目录路径）。」
请勿中止或报错 — 引导用户提供输入。

步骤 2：分类注解

将每个注解精确分类为三个类别之一。完整的 117 个注解查找表见 references/annotation-mapping.md。

| 类别 | 数量 | 操作 | 示例 | |----------|-------|--------|---------| | Compatible | 50 | 保留在迁移后的 YAML 中 | rewrite-target、enable-cors、canary-weight、ssl-redirect | | Ignorable | 16 | 剥离（Envoy 原生处理） | proxy-connect-timeout、proxy-buffering、proxy-body-size | | Unsupported | 51 | 剥离 → 通过决策树解析 | auth-url、server-snippet、limit-rps |

内联快速查找 — 高频注解：

注解	类别	操作
rewrite-target	✅ Compatible	保留
enable-cors	✅ Compatible	保留
cors-allow-origin	✅ Compatible	保留
ssl-redirect	✅ Compatible	保留
canary / canary-weight / canary-by-header	✅ Compatible	保留
whitelist-source-range	✅ Compatible	保留
backend-protocol	✅ Compatible	保留
use-regex	✅ Compatible	保留
upstream-vhost	✅ Compatible	保留
proxy-connect-timeout	⚪ Ignorable	剥离
proxy-read-timeout	⚪ Ignorable	剥离
proxy-send-timeout	⚪ Ignorable	剥离
proxy-body-size	⚪ Ignorable	剥离
proxy-buffering	⚪ Ignorable	剥离
client-body-buffer-size	⚪ Ignorable	剥离
auth-url	❌ Unsupported	WasmPlugin（HTTP 调用）
server-snippet	❌ Unsupported	WasmPlugin（指令转换）
configuration-snippet	❌ Unsupported	WasmPlugin（指令转换）
limit-rps	❌ Unsupported	内置 key-rate-limit 插件
limit-connections	❌ Unsupported	内置 key-rate-limit 插件
enable-modsecurity	❌ Unsupported	内置 waf 插件
denylist-source-range	❌ Unsupported	Higress 原生 higress.io/blacklist-source-range
service-upstream	❌ Unsupported	安全可丢弃（Envoy 默认行为）
ssl-ciphers	❌ Unsupported	重命名为 ssl-cipher（兼容）

如果注解不在上述表中，请在 references/annotation-mapping.md 中查找。如果仍未找到，则分类为 Unsupported 并通过步骤 3 中的决策树解析。

特殊值更改（兼容但值必须更改）：

• load-balance: ewma → round_robin（APIG 不支持 EWMA）
• ssl-ciphers → 重命名为 ssl-cipher（单数形式）
• affinity-mode: persistent → balanced（APIG 仅支持 balanced）

步骤 3：解析不支持的注解

对于每个不支持的注解，按顺序遵循以下决策树：

1. Higress 原生注解？→ 使用原生等价物（无需 WasmPlugin）
安全可丢弃？→ 无需替换即可移除
内置平台插件？→ 通过 higress.io/wasmplugin 注解使用内置 OCI 镜像
以上都不是？→ 开发自定义 WasmPlugin

完整的决策树见 references/migration-patterns.md，内置插件目录见 references/builtin-plugins.md。

Higress 原生映射：

nginx 注解	Higress 等价物
denylist-source-range	higress.io/blacklist-source-range
mirror-target	higress.io/mirror-target-service + higress.io/mirror-percentage

安全可丢弃：service-upstream、enable-access-log、proxy-request-buffering: off、connection-proxy-header

内置插件：limit-rps/limit-connections → key-rate-limit、enable-modsecurity → waf。见 references/builtin-plugins.md。

自定义 WasmPlugin（最后手段）：auth-url、server-snippet、configuration-snippet 等。SDK 参考见 references/wasm-plugin-sdk.md，转换模式见 references/snippet-patterns.md。

步骤 4：生成迁移后的 Ingress YAML

对于每个输入 Ingress，生成迁移后的副本：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: -apig
  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

步骤 5：输出迁移报告

所有输出建议使用中文（中文）。包括分析表、迁移总结、后续操作指南及所有说明性文字。代码块（YAML、Go、bash）保持原始语法。

>

以下所有内容均为标准输出项，建议在一次响应中完整输出，无需逐项询问用户。

为每个 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 网关 完成迁移。 - 不完全兼容（存在不兼容注解）：按以下顺序操作： 1. 构建并推送自定义 WasmPlugin OCI 镜像 2. 将迁移后 Ingress YAML 中的 OCI URL 占位符替换为真实的 WasmPlugin 镜像地址 3. 将替换后的 Ingress YAML 部署到集群中 4. 参考 Nginx Ingress 迁移到云原生 API 网关 继续后续操作，在步骤一「指定 IngressClass」处需指定为 apig 5. 网关版本要求：使用 WasmPlugin 需确保云原生 API 网关版本在 2.1.16 及以上，否则需要升级版本或创建新网关

部署指南模板见 references/deployment-guide-template.md。

范围边界：此技能生成所有制品和指令。它不执行 kubectl apply、docker push 或任何集群/registry 写入操作。这些留给用户。
无需确认：上述每个项目始终生成。永远不要问「是否需要生成迁移文件/检查清单/部署指南？」

成功验证方法

验证步骤见 references/verification-method.md，应包含在迁移报告中。迁移报告应指示用户使用以下命令验证：

# Validate migrated YAML syntax (user runs this)
kubectl apply --dry-run=client -f .yaml
# Confirm ingressClassName is apig
grep "ingressClassName: apig" .yaml

此技能输出验证指令供用户执行。它不执行这些命令。

清理

不适用。此技能仅生成文本输出（YAML、Go 源代码、迁移报告）。此技能不会创建任何云资源或集群对象。

API 和命令表

此技能不执行任何 CLI 命令或 API 调用。所有输出都是基于文本的（YAML、Go 源代码，包含用户指令的迁移报告）。

最佳实践

• 在生成迁移后的 YAML 之前始终分类所有注解 — 永不跳过注解
• 对未指定的参数使用占位符（、）；永不硬编码用户特定的值
• 在迁移后的 YAML 中保留原始的 rules、tls 和 namespace
• 为迁移后的 Ingress 名称添加 -apig 后缀以便识别
• 优先使用内置插件而非自定义 WasmPlugin — 首先检查 references/builtin-plugins.md
• 对于自定义 WasmPlugin，仅使用 github.com/higress-group/wasm-go/pkg/wrapper SDK
• 在报告中明确跟踪注解值更改（例如 ewma → round_robin）
• 对于 server-snippet/configuration-snippet，枚举每个指令并验证 1:1 转换完整性
• 永不执行集群写入操作（kubectl apply、docker push 等）— 仅输出供用户的指令

参考链接

参考	内容
references/annotation-mapping.md	完整的 117 个注解兼容性查找表
references/migration-patterns.md	决策树、Higress 原生映射、安全可丢弃列表、特殊处理
references/builtin-plugins.md	APIG 内置平台插件目录及 OCI URL
references/platform-oci-registry.md	内置插件的区域特定 OCI registry 地址
references/snippet-patterns.md	server-snippet / configuration-snippet → WasmPlugin 转换模式
references/wasm-plugin-sdk.md	Higress WASM Go Plugin SDK 参考（核心 API）
references/wasm-http-client.md	WasmPlugin HTTP 客户端模式（外部认证、调用）
references/wasm-redis-client.md	WasmPlugin Redis 客户端模式（限速、会话）
references/wasm-advanced-patterns.md	高级 WasmPlugin 模式（流式、tick、领导者选举）
references/wasm-local-testing.md	使用 Docker Compose 本地测试 WasmPlugin
references/plugin-deployment.md	WasmPlugin 构建、OCI 推送和 Ingress 注解绑定
references/deployment-guide-template.md	迁移报告部署指南模板
references/acceptance-criteria.md	使用正确/错误模式的测试验收标准
references/verification-method.md	成功验证步骤和命令
references/security-review-policy.md	定期安全复审策略与检查项
references/security-impact-assessment.md	安全影响评估与数据处理流程
references/ram-policies.md	RAM 权限声明（本 Skill 无需任何权限）