Skip to main content
Glama
ingress2gateway-aws-mcp

ingress2gateway-aws-mcp

by toreydai

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 专属后处理,提供对话式迁移体验。

Related MCP server: ARC Config MCP Server

工具列表

工具

功能

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/deployment.md

部署手册(本地/Docker/Kiro+Claude 接入、EKS 前置条件)+ 故障排查

开发

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

License

MIT - see the LICENSE file for details.

免责声明

  • 本项目仅供学习与技术参考,不构成生产部署方案。

  • 使用本工具生成的 Gateway API YAML 在 apply 到集群前,请结合实际业务进行安全评估与调整。

  • 部署过程中会在 AWS 上创建 EKS 集群、ALB/NLB 及相关资源并产生费用,请在实验结束后及时清理。

  • 作者不对因使用本项目产生的任何费用或损失承担责任。

  • 本项目与 Amazon Web Services 及 Kubernetes SIGs 无官方关联,相关服务的可用性与定价以各方官方文档为准。

Available Tools

5 tools
analyze_ingressA

Analyze Nginx Ingress configuration and return a structured summary. Reports annotation compatibility, route type distribution, TLS hosts, cross-namespace refs, and cost estimate.

Args: ingress_yaml: Nginx Ingress YAML content (multi-document supported) or file path. tcp_services_yaml: Optional tcp-services ConfigMap YAML for L4 TCP routes. udp_services_yaml: Optional udp-services ConfigMap YAML for L4 UDP routes.

Inputs: ingress_yaml (required), tcp_services_yaml, udp_services_yaml. Returns: result

check_prerequisitesA

Check if the target environment meets AWS Gateway API migration prerequisites.

Args: lbc_version: AWS Load Balancer Controller version (e.g. "2.14.1"). Leave empty to skip. needs_l4: Set true if migration includes TCP/UDP/TLS routes (requires experimental channel). tls_hostnames: Comma-separated TLS hostnames to check ACM certificate coverage.

Inputs: needs_l4, lbc_version, tls_hostnames. Returns: result

convert_to_gateway_apiA

Convert Nginx Ingress YAML to AWS Gateway API resources (full pipeline).

Steps: base conversion → GatewayClass injection → TLS fixup → L4/L7 split → Gateway merge → LoadBalancerConfiguration → TargetGroupConfiguration → ListenerRuleConfiguration

Args: ingress_yaml: Nginx Ingress YAML content or file path. tcp_services_yaml: Optional tcp-services ConfigMap YAML for TCP routes. udp_services_yaml: Optional udp-services ConfigMap YAML for UDP routes. scheme: ALB scheme — "internet-facing" or "internal". namespace: Default namespace if not specified in resources. alb_gateway_class: Name for the ALB GatewayClass (default: aws-alb). nlb_gateway_class: Name for the NLB GatewayClass (default: aws-nlb). gateway_grouping: Gateway consolidation strategy: "by-class-scheme" (default) | "by-namespace" | "by-host" | "single" health_check_path: TargetGroupConfiguration health check path. health_check_interval: TargetGroupConfiguration health check interval seconds. healthy_threshold: TargetGroupConfiguration healthy threshold count. unhealthy_threshold: TargetGroupConfiguration unhealthy threshold count.

Inputs: ingress_yaml (required), scheme, namespace, gateway_grouping, +8 more. Returns: result

generate_migration_reportB

Generate a complete Markdown migration report. Includes: summary, cost impact, DNS changes, annotation analysis, health check reminders, ACM checklist, migration checklist, and rollback plan.

Args: ingress_yaml: Nginx Ingress YAML content or file path. tcp_services_yaml: Optional tcp-services ConfigMap YAML. udp_services_yaml: Optional udp-services ConfigMap YAML. scheme: ALB scheme — "internet-facing" or "internal". gateway_grouping: Gateway consolidation strategy. lbc_version: AWS LBC version for pre-flight checks (optional). health_check_path: TargetGroupConfiguration health check path. health_check_interval: TargetGroupConfiguration health check interval seconds. healthy_threshold: TargetGroupConfiguration healthy threshold count. unhealthy_threshold: TargetGroupConfiguration unhealthy threshold count.

Inputs: ingress_yaml (required), scheme, lbc_version, gateway_grouping, +6 more. Returns: result

validate_outputA

Validate Gateway API YAML against schema rules and AWS LBC constraints. Checks: required fields, L4/L7 mixing, certificateRefs misuse, parentRef consistency, experimental channel requirements, and cross-namespace reference coverage.

Args: yaml_content: Gateway API YAML content to validate, or file path.

Inputs: yaml_content (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool serves a distinct step in the migration pipeline: analysis, prerequisites check, conversion, validation, and report generation. No overlapping purposes.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern (e.g., analyze_ingress, check_prerequisites), with clear and specific verbs appropriate to the action.

    Tool Count5/5

    5 tools cover the essential migration workflow without excess or deficiency. Each tool has a clear role and sufficient parameters.

    Completeness5/5

    The toolset covers the full migration lifecycle from analysis to validation and reporting, including prerequisites checking and rollback planning in the report. No obvious gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language management of GitHub Actions Runner Controller (ARC) in Kubernetes clusters. Supports automated installation, scaling, monitoring, and troubleshooting of GitHub Actions runners through conversational AI commands.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Exposes a Kubernetes cluster to MCP-compatible AI clients, enabling read-only and optional write operations on cluster resources like pods, deployments, and namespaces through natural language.
      9
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables conversational management of Nginx Proxy Manager, including reverse-proxy routing, TLS certificates, access lists, and stream forwards, with built-in safety guardrails for production use.
      1
      MIT