Ingress2Gateway 用户指南：支持的所有 Ingress 控制器和转换策略详解

Ingress2Gateway 用户指南：支持的所有 Ingress 控制器和转换策略详解

【免费下载链接】ingress2gatewayConvert Ingress resources to Gateway API resources项目地址: https://gitcode.com/gh_mirrors/in/ingress2gateway

🚀 你是否正在为 Kubernetes Ingress NGINX 的退役而烦恼？想要从传统的 Ingress 平滑迁移到现代化的 Gateway API 吗？那么 Ingress2Gateway 就是你的完美解决方案！这款强大的转换工具能够帮助你轻松将各种 Ingress 控制器资源转换为标准的 Gateway API 资源，让你的 Kubernetes 网络配置迈入新时代。

什么是 Ingress2Gateway？

Ingress2Gateway是由 Kubernetes SIG-Network 子项目管理的开源工具，专门用于将 Ingress 资源和特定提供商的 CRD 转换为 Gateway API 资源。随着 Kubernetes 社区宣布 Ingress NGINX 即将退役，Ingress2Gateway 成为了迁移到 Gateway API 的关键桥梁。

该工具支持多种流行的 Ingress 控制器，包括 ingress-nginx、Traefik、Kong、Istio、GCE 等，能够处理复杂的注解转换和资源配置，让你的迁移过程更加顺畅。

支持的 Ingress 控制器完整列表

Ingress2Gateway 目前支持以下主流 Ingress 控制器的转换：

1.ingress-nginx- Kubernetes 社区标准

• 支持位置: pkg/i2gw/providers/ingressnginx/
• 核心功能: 金丝雀发布、URL 重写、重定向、CORS 配置、超时设置
• 特色转换:
  • 金丝雀权重路由 (canary-weight)
  • SSL 透传 (ssl-passthrough)
  • 后端 TLS 验证 (proxy-ssl-verify)

2.Traefik- 云原生代理

• 支持位置: pkg/i2gw/providers/traefik/
• 核心功能: TLS 配置、入口点管理、HTTP/HTTPS 重定向
• 特色转换:
  • 自动 HTTPS 重定向 (router.entrypoints: websecure)
  • 自定义入口点配置
  • 智能 TLS 处理

3.Kong- API 网关

• 支持位置: pkg/i2gw/providers/kong/
• 核心功能: 方法匹配、头部匹配、插件集成
• 特色转换:
  • HTTP 方法匹配 (konghq.com/methods)
  • 自定义头部路由 (konghq.com/headers.*)
  • 插件配置转换

4.Istio- 服务网格

• 支持位置: pkg/i2gw/providers/istio/
• 核心功能: Gateway 和 VirtualService 转换
• 特色转换:
  • 复杂重写规则处理
  • 跨命名空间引用 (ReferenceGrant)
  • 协议转换 (HTTP2/GRPC → HTTPS)

5.GCE- Google Cloud Engine

• 支持位置: pkg/i2gw/providers/gce/
• 核心功能: GKE Ingress 特定功能
• 特色转换:
  • 内部/外部负载均衡器
  • Cloud Armor 安全策略
  • 自定义健康检查

6.NGINX- NGINX 官方控制器

• 支持位置: pkg/i2gw/providers/nginx/
• 核心功能: SSL 服务、gRPC、WebSocket 支持
• 特色转换:
  • gRPC 服务转换 (nginx.org/grpc-services)
  • WebSocket 支持通知
  • HSTS 头部配置

7.其他支持的控制器

• APISIX: 高性能 API 网关
• Cilium: eBPF 网络方案
• OpenAPI 3: 基于 OpenAPI 规范的配置

核心转换策略详解

🔄 架构设计：Provider 与 Emitter 分离

Ingress2Gateway 采用创新的双组件架构：

1. Provider（提供者）: 读取 Ingress 资源和特定提供商的 CRD，将其转换为通用的中间表示（IR）
2. Emitter（发射器）: 将中间表示转换为最终的 Gateway API 输出

这种设计使得工具既灵活又易于扩展，支持多种输出格式：

• standard: 标准 Gateway API 资源（默认）
• envoy-gateway: Envoy Gateway 特定资源
• gce: Google Cloud Engine 特定配置
• agentgateway: Agent Gateway 实现
• airlock-microgateway: Airlock 微网关
• kgateway: KGateway 实现

📋 Ingress 字段到 Gateway API 的映射关系

⚙️ 冲突处理规则

Ingress2Gateway 采用确定的处理顺序来解决配置冲突：

1. 创建时间优先: 最早创建的 Ingress 资源具有最高优先级
2. 名称空间/名称排序: 如果创建时间相同，按命名空间和名称排序
3. 冲突报告: 对于冲突的规则（如相同路径但不同后端），会报告错误

实用转换示例

示例 1: ingress-nginx 金丝雀发布

# 原始 Ingress 配置 apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: canary-demo annotations: nginx.ingress.kubernetes.io/canary: "true" nginx.ingress.kubernetes.io/canary-weight: "20"

转换为 Gateway API 后，会生成带有权重配置的 HTTPRoute，实现精确的流量分流。

示例 2: Traefik HTTPS 重定向

# Traefik 特定配置 annotations: traefik.ingress.kubernetes.io/router.tls: "true" traefik.ingress.kubernetes.io/router.entrypoints: websecure

Ingress2Gateway 会自动生成 HTTP→HTTPS 重定向路由，确保所有 HTTP 流量都重定向到 HTTPS。

示例 3: Kong 方法匹配

# Kong 特定配置 annotations: konghq.com/methods: "POST,GET"

转换为 Gateway API 的 HTTPRoute，包含精确的 HTTP 方法匹配规则。

安装与使用指南

快速安装方法

通过 Go install 安装:

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

通过 Homebrew 安装:

brew install ingress2gateway

从源码构建:

git clone https://gitcode.com/gh_mirrors/in/ingress2gateway cd ingress2gateway make build go install .

基本使用命令

转换集群中的所有 ingress-nginx 资源:

ingress2gateway print --providers=ingress-nginx

从文件转换 Traefik 配置:

ingress2gateway print --providers=traefik --input-file=traefik-ingress.yaml

指定命名空间和输出格式:

ingress2gateway print --providers=istio --namespace=production --output=json

常用命令行选项

迁移最佳实践

🎯 1. 评估现有配置

在开始迁移前，使用 Ingress2Gateway 的--dry-run模式评估转换结果:

ingress2gateway print --providers=ingress-nginx --dry-run

🔍 2. 逐步迁移策略

• 从简单的 Ingress 开始，逐步处理复杂配置
• 优先迁移生产环境外的测试集群
• 使用金丝雀发布验证转换结果

⚠️ 3. 注意事项

• 注解转换: 不是所有注解都能完美转换，部分需要手动调整
• 功能差异: Gateway API 的功能集与 Ingress 有所不同
• 测试验证: 转换后务必进行全面的功能测试

📊 4. 监控与验证

• 使用转换报告检查未转换的注解
• 验证 Gateway API 资源的正确性
• 监控应用行为是否发生变化

高级特性与扩展

自定义 Emitter 支持

Ingress2Gateway 支持自定义发射器开发，允许你为特定的 Gateway API 实现生成优化配置。查看 docs/emitters.md 了解如何开发自己的发射器。

通知系统

工具内置通知系统，会详细报告:

• ✅ 成功转换的配置
• ⚠️ 部分支持的注解
• ❌ 无法转换的功能
• 💡 手动调整建议

实验性功能支持

通过--allow-experimental-gw-api标志，可以启用实验性 Gateway API 功能，如 URLRewrite 等高级特性。

版本兼容性

社区与贡献

Ingress2Gateway 是 Kubernetes SIG-Network 的子项目，欢迎社区贡献:

• 报告不支持的注解或功能
• 提交新的 Provider 支持
• 改进现有转换逻辑
• 添加测试用例

查看 CONTRIBUTING.md 了解如何参与贡献。

总结

Ingress2Gateway 为 Kubernetes 用户提供了从传统 Ingress 到现代 Gateway API 的平滑迁移路径。通过支持多种流行的 Ingress 控制器和灵活的转换策略，它大大降低了迁移的技术门槛和风险。

无论你使用的是 ingress-nginx、Traefik、Kong 还是其他控制器，Ingress2Gateway 都能帮助你顺利完成迁移，享受 Gateway API 带来的标准化、扩展性和未来兼容性优势。

🚀立即开始你的迁移之旅，拥抱 Kubernetes 网络的新时代！

【免费下载链接】ingress2gatewayConvert Ingress resources to Gateway API resources项目地址: https://gitcode.com/gh_mirrors/in/ingress2gateway