# 从 NGINX Ingress Controller 迁移到 Gateway API 的工程策略 > 针对 Kubernetes 集群中 NGINX Ingress Controller 的迁移，提供到 Gateway API 的工程化策略，强调配置移植和性能保持。 ## 元数据 - 路径: /posts/2025/11/14/engineering-migration-strategies-from-nginx-ingress-to-gateway-api/ - 发布时间: 2025-11-14T11:47:05+08:00 - 分类: [systems-engineering](/categories/systems-engineering/) - 站点: https://blog.hotdry.top ## 正文 Kubernetes 中的流量管理是集群运维的核心组成部分，NGINX Ingress Controller 作为经典的 Ingress 实现，已广泛用于暴露服务。然而，随着 Kubernetes 生态的演进，Gateway API 作为 Ingress API 的继任者，提供更丰富的功能、更强的可移植性和角色导向的设计，成为迁移的首选。本文聚焦工程化迁移策略，讨论从 NGINX Ingress 到 Gateway API 的配置移植、性能等价性保障，以及可落地参数和清单，帮助团队平稳过渡。 ### 迁移必要性与背景 NGINX Ingress Controller 通过注解扩展功能，支持 HTTP/HTTPS 路由、TLS 终止和负载均衡，但其局限性日益凸显：注解依赖导致厂商锁定，权限模型单一，无法满足多团队共享基础设施的需求；功能扩展依赖特定实现，移植性差。Gateway API 由 Kubernetes SIG-NETWORK 维护，自 v1.0 起 GA，支持 L4/L7 路由、多协议（HTTP、TCP、UDP、gRPC），并引入角色分离：集群运营商管理 Gateway（入口点），应用开发者管理 HTTPRoute（路由规则）。这提升了可扩展性和安全性，同时避免注解滥用。 迁移并非 NGINX 的“退休”，而是向标准化的演进。NGINX 官方推出 NGINX Gateway Fabric，支持 Gateway API；其他替代如 Envoy Gateway、Istio（v1.16+ 支持）或 Kong，提供无缝过渡。证据显示，Gateway API 在复杂场景下性能不逊 NGINX，甚至通过 Envoy 数据平面提升吞吐（基准测试 QPS 可达 13 万+）。 ### 迁移步骤与配置移植 迁移分为准备、转换和验证三阶段，确保零中断。 1. **准备阶段：环境评估与安装** - 评估现有 Ingress：扫描注解（如 nginx.ingress.kubernetes.io/rewrite-target），识别非标准功能（如 WAF、Lua 脚本）。使用 kubectl get ingress -A 列出资源，检查兼容性。 - 安装 Gateway API CRDs：kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/standard-install.yaml（v1.1.0 为稳定版）。 - 部署 Gateway Controller：推荐 Envoy Gateway（高性能，原生支持）或 NGINX Gateway Fabric（保持 NGINX 生态）。Helm 示例：helm install eg oci://docker.io/envoyproxy/gateway-helm --version v0.0.0-latest -n envoy-gateway-system --create-namespace --set gatewayClassName=eg。 - 参数：replicaCount=3（高可用），resources.requests.cpu=500m（性能调优）。 - 验证：kubectl get gatewayclass，确保 accepted=True。 2. **转换阶段：Ingress 到 Gateway API** - 使用 ingress2gateway 工具自动化转换：安装后，ingress2gateway convert --source-namespace=default --output-dir=output ingress.yaml。工具将 Ingress 映射为 Gateway + HTTPRoute。 - 示例：原 NGINX Ingress（host: foo.com, path: /orders -> service:foo-orders）转换为： ``` apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: example-gateway spec: gatewayClassName: eg listeners: - name: https port: 443 protocol: HTTPS tls: mode: Terminate certificateRefs: - kind: Secret name: tls-secret --- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: foo-route spec: parentRefs: - name: example-gateway hostnames: - "foo.com" rules: - matches: - path: type: PathPrefix value: /orders backendRefs: - name: foo-orders port: 80 ``` - TLS 移植：Ingress tls.secretName -> Gateway listener.tls.certificateRefs。 - 注解处理：如 tls-redirect，转换为 HTTPRoute filters: type: RequestRedirect, scheme: https。 - 复杂规则：NGINX 的 host/path 匹配直接映射；权重路由（service-weight 注解）用 backendRefs.weights；header 匹配用 HTTPHeaderMatch。 - 手动调整：跨命名空间路由需 ReferenceGrant；默认后端用 catch-all rule (path: /)。 3. **验证与回滚阶段** - 测试：部署 staging 环境，curl -H "Host: foo.com" http://gateway-ip/orders 验证路由。监控 5xx 错误率 <1%。 - 渐进切流：用 Istio 或蓝绿部署，初始 10% 流量到新 Gateway，逐步增至 100%。参数：trafficPercentage=10, step=20%。 - 回滚策略：保留 NGINX Ingress 并行运行，DNS TTL 设 60s 快速切换；若失败，kubectl delete httproute -l app=migration。 配置移植率可达 80%以上，非标准注解需自定义 Policy（如 Envoy 的 Wasm 扩展）。 ### 性能等价性与监控 Gateway API 不牺牲性能：Envoy Gateway 基准显示，单连接 QPS 3.45 万，16 连接超 13 万，延迟 P99 <10ms，与 NGINX 等价（NGINX 高负载下 CPU 争用导致下降）。移植后，保持等价的关键参数： - 资源分配：Gateway Pod requests.cpu=1, limits=2；autoscaling minReplicas=2, max=10, targetCPU=70%。 - 连接管理：listener idleTimeout=30s, maxConnections=10000。 - 监控清单：Prometheus 指标如 gateway_http_requests_total, gateway_http_duration_seconds；警报阈值：latency>50ms 或 error_rate>0.5% 触发 PagerDuty。 - 优化：启用 HTTP/2，TLS 1.3；负载均衡算法：least_conn（NGINX 默认）。 风险：初始复杂性高（学习 Gateway 资源），生态不全（部分注解无直接替代）；限制造成：测试覆盖率<90% 可能漏路由冲突。缓解：从小规模服务迁移，CI/CD 集成 ingress2gateway。 ### 结论 从 NGINX Ingress 到 Gateway API 的迁移是 Kubernetes 现代化之路，提供更好可移植性和未来兼容。通过上述策略，团队可实现配置零丢失、性能持平的过渡。建议从小集群试点，逐步扩展。 资料来源： - Kubernetes Gateway API 官方迁移指南：https://gateway-api.sigs.k8s.io/guides/migrating-from-ingress/ - NGINX Ingress 文档：https://kubernetes.github.io/ingress-nginx/ - Envoy Gateway 基准：https://gateway.envoyproxy.io/ （字数：1025） ## 同分类近期文章 ### [Apache Arrow 10 周年：剖析 mmap 与 SIMD 融合的向量化 I/O 工程流水线](/posts/2026/02/13/apache-arrow-mmap-simd-vectorized-io-pipeline/) - 日期: 2026-02-13T15:01:04+08:00 - 分类: [systems-engineering](/categories/systems-engineering/) - 摘要: 深入分析 Apache Arrow 列式格式如何与操作系统内存映射及 SIMD 指令集协同，构建零拷贝、硬件加速的高性能数据流水线，并给出关键工程参数与监控要点。 ### [Stripe维护系统工程：自动化流程、零停机部署与健康监控体系](/posts/2026/01/21/stripe-maintenance-systems-engineering-automation-zero-downtime/) - 日期: 2026-01-21T08:46:58+08:00 - 分类: [systems-engineering](/categories/systems-engineering/) - 摘要: 深入分析Stripe维护系统工程实践，聚焦自动化维护流程、零停机部署策略与ML驱动的系统健康度监控体系的设计与实现。 ### [基于参数化设计和拓扑优化的3D打印人体工程学工作站定制](/posts/2026/01/20/parametric-ergonomic-3d-printing-design-workflow/) - 日期: 2026-01-20T23:46:42+08:00 - 分类: [systems-engineering](/categories/systems-engineering/) - 摘要: 通过OpenSCAD参数化设计、BOSL2库燕尾榫连接和拓扑优化，实现个性化人体工程学3D打印工作站的轻量化与结构强度平衡。 ### [TSMC产能分配算法解析：构建半导体制造资源调度模型与优先级队列实现](/posts/2026/01/15/tsmc-capacity-allocation-algorithm-resource-scheduling-model-priority-queue-implementation/) - 日期: 2026-01-15T23:16:27+08:00 - 分类: [systems-engineering](/categories/systems-engineering/) - 摘要: 深入分析TSMC产能分配策略，构建基于强化学习的半导体制造资源调度模型，实现多目标优化的优先级队列算法，提供可落地的工程参数与监控要点。 ### [SparkFun供应链重构：BOM自动化与供应商评估框架](/posts/2026/01/15/sparkfun-supply-chain-reconstruction-bom-automation-framework/) - 日期: 2026-01-15T08:17:16+08:00 - 分类: [systems-engineering](/categories/systems-engineering/) - 摘要: 分析SparkFun终止与Adafruit合作后的硬件供应链重构工程挑战，包括BOM自动化管理、替代供应商评估框架、元器件兼容性验证流水线设计