ingress2gateway-aws-mcp

MCP Server：将 Nginx Ingress 转换为 AWS Gateway API（ALB / NLB）资源的对话式迁移工具。

背景

Ingress-NGINX 已于 2026 年 3 月退役，AWS Load Balancer Controller v2.14+ 正式支持 Kubernetes Gateway API。本工具封装社区官方转换器 ingress2gateway，在其基础上叠加 AWS 专属后处理，提供对话式迁移体验。

工具列表

工具	功能
check_prerequisites	检查 LBC 版本、Gateway API CRD、feature gate、ACM 证书
analyze_ingress	分析 Nginx Ingress 注解分布、路由类型、成本预估
convert_to_gateway_api	完整转换管道 → 生成可 kubectl apply 的 YAML
generate_migration_report	输出 Markdown 迁移报告（成本/DNS/健康检查/Checklist）
validate_output	离线校验生成的 Gateway API YAML

安装

方式一：本地 pip

pip install .

需要 Python 3.11+。可选：安装 ingress2gateway Go 二进制以获得官方转换器覆盖；AWS LBC 不支持的能力仍会由本工具报告为 warning/error（不安装时自动使用内置转换器）：

go install github.com/kubernetes-sigs/ingress2gateway@v1.1.0

方式二：Docker

docker build -t ingress2gateway-aws-mcp .
docker run --rm -i ingress2gateway-aws-mcp

连接到 AI 客户端

Kiro

Kiro CLI：

kiro-cli mcp add --name ingress2gateway-aws-mcp \
  --scope global \
  --command python3 \
  --args "/path/to/ingress2gateway-aws-mcp/src/server.py"

Kiro IDE（工作区：.kiro/settings/mcp.json，全局：~/.kiro/settings/mcp.json）：

{
  "mcpServers": {
    "ingress2gateway-aws-mcp": {
      "command": "python3",
      "args": ["/path/to/ingress2gateway-aws-mcp/src/server.py"]
    }
  }
}

Kiro IDE 支持热重载，修改 mcp.json 后无需重启，下次空闲时自动生效。

Claude

Claude Code CLI：

claude mcp add ingress2gateway-aws-mcp python3 /path/to/ingress2gateway-aws-mcp/src/server.py

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "ingress2gateway-aws-mcp": {
      "command": "python3",
      "args": ["/path/to/ingress2gateway-aws-mcp/src/server.py"]
    }
  }
}

EKS 集群前置要求

目标集群必须满足以下条件，生成的 YAML 才能成功 apply：

项目	要求
AWS LBC 版本	≥ v2.14.0（L7）/ ≥ v2.13.3（L4）
LBC feature gate	ALBGatewayAPI=true（默认开启）
Gateway API standard channel	v1.5.0+（HTTPRoute / GRPCRoute / ReferenceGrant）
Gateway API experimental channel	仅当有 TCP/UDP/TLSRoute 或 BackendTLSPolicy 时需要
AWS 定制 CRD	LoadBalancerConfiguration、TargetGroupConfiguration、ListenerRuleConfiguration
ACM 证书	每个 TLS hostname 在同 Region 有对应证书
Subnet 标签	kubernetes.io/role/elb: "1"（公网）/ kubernetes.io/role/internal-elb: "1"（内网）

快速搭建满足上述条件的集群，参见 infra/cluster.yaml。

使用示例

你：帮我分析一下这个 Ingress 文件
<粘贴 ingress.yaml 内容>

AI 调用 analyze_ingress →
返回注解兼容性报告、路由类型分布、成本预估

你：转换成 Gateway API YAML
AI 调用 convert_to_gateway_api → 返回可直接 apply 的 YAML

你：生成完整迁移报告
AI 调用 generate_migration_report → 返回 Markdown 报告

示例输入文件见 examples/input/，对应转换结果见 examples/output/。

项目结构

详见 docs/architecture.md。

转换管道概览

Ingress YAML
    │
    ▼ converter.run()          ← ingress2gateway 二进制 / 内置 Python 转换器
    │
    ▼ gateway.inject()         ← 注入 aws-alb / aws-nlb GatewayClass
    ▼ gateway.fix_tls()        ← 移除 certificateRefs，改 hostname → ACM 自动发现
    ▼ gateway.split()          ← L4/L7 强制分离，重写 parentRefs
    ▼ gateway.merge()          ← 按策略合并 Gateway，控制 ALB/NLB 数量
    │
    ▼ crd.generate_for_resources()   ← LoadBalancerConfiguration（每个 Gateway）
    ▼ crd.generate_for_routes()      ← TargetGroupConfiguration（每个 Service / 健康检查 / stickiness）
    ▼ crd.generate_for_ingresses()   ← ListenerRuleConfiguration（OIDC / 源 IP）
    ▼ crd.attach_listener_rule_configs() ← 通过 HTTPRoute ExtensionRef 绑定认证 / 源 IP 条件
    │
    ▼ 可 kubectl apply 的 Gateway API YAML

文档

文档	内容
docs/architecture.md	模块职责、转换管道数据流、AWS 资源模型、关键设计决策
docs/annotation-reference.md	Nginx 注解兼容性速查表（auto / partial / warning / error 分类）
docs/ops.md	部署手册（本地/Docker/Kiro+Claude 接入、EKS 前置条件）+ 故障排查

开发

pip install -e ".[dev]"
pytest tests/ -v

License

MIT

免责声明

本项目仅供学习与技术参考，不构成生产部署方案。使用本工具生成的 Gateway API YAML 在 apply 到集群前，请结合实际业务进行安全评估与调整。部署过程中会在 AWS 上创建 EKS 集群、ALB/NLB 及相关资源并产生费用，请在实验结束后及时清理。作者不对因使用本项目产生的任何费用或损失承担责任。本项目与 Amazon Web Services 及 Kubernetes SIGs 无官方关联，相关服务的可用性与定价以各方官方文档为准。