alibabacloud-nginx-ingress-to-api-gateway

Nginx Ingress 迁移到 APIG

场景描述

将 Kubernetes nginx Ingress 资源迁移到阿里云 API Gateway（APIG）。APIG 是基于 Envoy 的网关（Higress），使用 ingressClassName: apig。此技能会将每个 nginx.ingress.kubernetes.io/* 注解归类为兼容、可忽略或不支持，并通过四级决策树（Higress 原生功能 → 可安全删除 → 内置插件 → 自定义 WasmPlugin）处理不支持的注解、生成迁移后的 Ingress YAML，并提供可用于部署的迁移报告。

架构：nginx Ingress Controller → APIG (Envoy/Higress) + 可选 WasmPlugin（Go、proxy-wasm-go-sdk）

核心分析工作流完全离线处理用户提供的 YAML，无需访问集群、使用命令行工具或提供云凭证。

安装

此技能完全离线处理用户提供的 YAML，无需命令行工具、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 或命令行工具。

身份验证

不适用。此技能不会调用阿里云 API 或命令行工具。无需凭证。

RAM 策略

不适用。此技能完全处理本地 YAML 文件，不会调用任何云 API。

参数确认

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

用户提供 Ingress YAML 后，立即执行完整工作流（第 1 步 → 第 5 步）并输出完整结果。不要询问 RegionId、OCI registry 或其他任何参数。在输出中使用 <REGION> 和 <YOUR_REGISTRY> 占位符。

请避免以下交互模式，直接执行对应操作即可：

• “是否需要我分析这个 Ingress？”——建议直接分析
• “是否需要生成迁移后的 YAML？”——建议直接生成
• “是否需要创建迁移配置文件/检查清单？”——建议直接创建
• “是否需要开发 WasmPlugin？”——如果决策树判定需要，建议直接开发
• “请确认 RegionId / OCI 地址”——建议使用占位符

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

未提供 Ingress YAML 时：如果用户询问迁移事宜但未提供 YAML， 请回复：“请提供需要迁移的 nginx Ingress YAML（可以直接粘贴、提供文件路径或目录路径）。” 不要中止对话——引导用户提供所需输入。

核心工作流

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

当用户提供 Ingress YAML 时，建议立即执行全部步骤（第 1 步 → 第 5 步），并在一次响应中输出完整结果。

• 对于未指定的参数（如 RegionId、OCI registry），使用 <REGION> 等占位符
• 收到 YAML 后直接进入分析流程，无需额外确认
• 各步骤之间连续执行，无需中途暂停询问用户
• 迁移配置文件和检查清单作为标准输出的一部分自动生成
• 整个工作流具有确定性：输入 YAML → 输出完整迁移报告，无需中途确认
• 唯一必需的输入是 Ingress YAML 本身

第 1 步：解析 Ingress YAML

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

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

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

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

第 2 步：对注解分类

将每个注解准确归入以下三个类别之一。完整的 117 个注解对照表见 references/annotation-mapping.md。

类别	数量	操作	示例
兼容	50	保留在迁移后的 YAML 中	rewrite-target、enable-cors、canary-weight、ssl-redirect
可忽略	16	移除（Envoy 原生处理）	proxy-connect-timeout、proxy-buffering、proxy-body-size
不支持	51	移除 → 通过决策树处理	auth-url、server-snippet、limit-rps

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

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

如果上表中没有某个注解，请在 references/annotation-mapping.md 中查找。如果仍未找到，则归类为不支持，并通过第 3 步中的决策树处理。

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

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

第 3 步：处理不支持的注解

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

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

完整决策树请参见 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: <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

第 5 步：输出迁移报告

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

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

为每个 Ingress 输出以下所有内容：

1. 兼容性分析表 — 注解、值、类别（兼容/可忽略/不支持）、操作
2. 迁移后的 Ingress YAML — 可供用户直接应用
3. 自定义 WasmPlugin 源码 — 如果第 3 步确定需要自定义插件（仅在不需要自定义插件时跳过）
4. 迁移总结 — 变更内容、值变更、所需插件
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 及以上，否则需要升级版本或创建新网关

指南模板请参见 references/deployment-guide-template.md。

范围边界：此技能会生成所有产物和说明，但不会执行 kubectl apply、docker push 或任何集群/镜像仓库写入操作。这些操作由用户自行完成。 无需确认：始终生成以上所有内容。切勿询问“是否需要生成迁移文件/检查清单/部署指南？”

成功验证方法

迁移报告中应包含的验证步骤请参见 references/verification-method.md。

迁移报告应指导用户使用以下命令进行验证：

# 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

此技能会输出供用户使用的验证说明，但不会执行这些命令。

清理

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

API 和命令表

此技能不会执行任何 CLI 命令或 API 调用。所有输出均为文本（YAML、Go 源码、包含用户操作说明的迁移报告）。

最佳实践

1. 生成迁移后的 YAML 前，始终对所有注解进行分类——绝不跳过任何注解
2. 对未指定的参数使用占位符（<REGION>、<YOUR_REGISTRY>）；绝不硬编码用户专属值
3. 在迁移后的 YAML 中保留原有的 rules、tls 和 namespace
4. 在迁移后的 Ingress 名称后添加 -apig 后缀，以便轻松识别
5. 优先使用内置插件，而非自定义 WasmPlugin——请先查看 references/builtin-plugins.md
6. 对于自定义 WasmPlugin，只能使用 github.com/higress-group/wasm-go/pkg/wrapper SDK
7. 在报告中明确记录注解值的变更（例如，ewma → round_robin）
8. 对于 server-snippet/configuration-snippet，逐一列出每条指令，并确认转换完整、一一对应
9. 绝不执行集群写入操作（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 仓库地址
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 无需任何权限）