Skip to main content
Glama
ingress2gateway-aws-mcp

ingress2gateway-aws-mcp

by toreydai
README.md
# 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

```bash
pip install .
```

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

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

### 方式二:Docker

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

## 连接到 AI 客户端

### Kiro

**Kiro CLI**:

```bash
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`):

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

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

### Claude

**Claude Code CLI**:

```bash
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`):

```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`](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/input/),对应转换结果见 [`examples/output/`](examples/output/)。

## 目录结构

详见 [`docs/architecture.md`](docs/architecture.md#3-模块职责)。

## 转换管道概览

```
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`](docs/architecture.md) | 模块职责、转换管道数据流、AWS 资源模型、关键设计决策 |
| [`docs/annotation-reference.md`](docs/annotation-reference.md) | Nginx 注解兼容性速查表(auto / partial / warning / error 分类)|
| [`docs/deployment.md`](docs/deployment.md) | 部署手册(本地/Docker/Kiro+Claude 接入、EKS 前置条件)+ 故障排查 |

## 开发

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

## License

MIT - see the [LICENSE](LICENSE) file for details.

## 免责声明

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

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