从 Nginx Ingress 迁移到 APIG

场景说明

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

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

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

安装

此 skill 完全基于用户提供的 YAML 离线运行，无需使用 CLI 工具和 SDKs，也无需提供云凭证。

按需工具（仅当工作流进行到需要这些工具的步骤时）：

| 工具 | 何时需要 | 检查命令 | 最低版本 | |------|------------|---------------|-----------------| | 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 | — |

分析期间不得预先检查任何工具，也不得提示安装任何工具。

环境变量

不需要任何环境变量。此 skill 不调用任何云 APIs，也不使用 CLI 工具。

身份认证

不适用。此 skill 不调用阿里云 APIs，也不使用 CLI。无需任何凭证。

RAM 权限策略

不适用。此 skill 完全基于本地 YAML 文件运行，不调用任何云 APIs。

参数确认

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

用户提供 Ingress YAML 后，立即执行完整工作流（步骤 1→5）并输出完整结果。不得询问 RegionId、OCI 镜像仓库或任何其他参数。输出中使用 <REGION> 和 <YOUR_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），使用 <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。

范围边界：此 skill 生成所有产物和操作说明，但不执行 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

此 skill 为用户输出验证说明，但不执行这些命令。

清理

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

API 和命令表

此 skill 不执行任何 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，逐一列出每条指令，并验证 1:1 转换的完整性
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 插件 SDK 参考文档（核心 API） | | references/wasm-http-client.md | WasmPlugin HTTP 客户端模式（外部认证、外部调用） | | references/wasm-redis-client.md | WasmPlugin Redis 客户端模式（速率限制、会话） | | references/wasm-advanced-patterns.md | 高级 WasmPlugin 模式（流式处理、定时触发、领导者选举） | | 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 无需任何权限） |