Nginx Ingress迁移实战：阿里云API网关平滑升级指南

随着Nginx Ingress逐步停止维护，用户需要将其迁移至新的网关方案。阿里云云原生API网关作为API网关产品线的重要组成部分，统一了流量网关、微服务网关和安全网关功能，为Nginx Ingress用户提供了平滑的迁移路径和功能升级。

云原生API网关提供两种核心配置模式以适应不同的管理需求：

1. 监听K8s Ingress（Ingress模式）：网关作为APIG Ingress Controller运行，兼容K8s Ingress资源及Nginx Ingress注解，适用于希望保持K8s原生工作流的团队。

2. 控制台配置API（API管理模式）：通过阿里云控制台或API进行配置，提供完整的API生命周期管理、高级安全策略和运营能力，适用于需要集中治理的场景。

模式一：监听K8s Ingress（Ingress模式）

此模式将云原生API网关部署为Kubernetes集群的Ingress Controller，用于管理集群的南北向流量。

核心优势与适用场景

• 平滑迁移：提供一键式迁移工具，最大程度降低迁移成本和业务中断风险
• 保持K8s原生工作流：完全兼容K8s Ingress资源和注解，支持kubectl apply、GitOps等现有工作流
• 功能增强：在兼容Nginx Ingress基础上，提供更强大的治理能力

适用场景：

• Nginx Ingress存量用户迁移
• 以K8s为中心、依赖GitOps流程的团队
• 需要快速实现集群流量路由和基础治理的团队

功能详情

高度兼容Nginx Ingress注解

APIG Ingress支持绝大多数Nginx Ingress注解（支持51种，覆盖90%用户场景）。现有K8s Ingress YAML文件无需大量修改即可迁移。

关键兼容注解示例：

独有的功能增强（Higress注解）

通过higress.ingress.kubernetes.io/前缀注解提供Nginx Ingress不具备的高级功能：

流量预热

• 提供原生higress.ingress.kubernetes.io/warmup注解，保证新节点上线时流量逐步调大

全局限流

• higress.ingress.kubernetes.io/rate-limit提供跨所有网关实例的全局限流，精确控制总QPS

全局并发控制

• higress.ingress.kubernetes.io/concurrency-limit提供全局并发数限制，保护后端服务

流量镜像

• higress.ingress.kubernetes.io/mirror-target-service注解便捷复制流量到测试服务

模式二：控制台配置API（API管理模式）

此模式将云原生API网关作为中心化API管理平台，通过阿里云控制台定义和管理API。

核心优势与适用场景

• 集中化治理：平台团队从统一视图管理所有API，强制执行安全合规策略
• 全生命周期管理：支持API设计、开发、测试、发布到下线完整周期
• 高级安全能力：原生集成OIDC、JWT等复杂认证机制
• API运营与生态：支持消费者管理、订阅关系和调用配额

适用场景：

• 需要对API进行精细化、集中化治理的企业
• 对API安全身份认证有高要求的业务
• 构建开放平台，管理第三方开发者的场景

功能详情

完整的API生命周期管理

支持API版本管理、发布历史记录和一键回滚功能

高级的企业级安全

• 原生支持JWT、OIDC认证
• 深度集成WAF、支持mTLS双向认证
• IP黑白名单及自定义安全插件

强大的可扩展性

• 插件市场提供丰富官方插件
• 支持热更新，无需重启实例

API运营与多源服务发现

• 消费者管理功能
• 支持从Nacos、函数计算等多种来源发现服务

模式对比总结

下表总结了两种配置模式的关键差异：

如何选择：推荐的迁移与演进路径

场景一：平滑迁移

• 适用对象：优先考虑迁移速度、保持现有K8s工作流的团队
• 推荐方案：采用模式一（K8s Ingress模式）
• 实施步骤：
  1. 使用官方迁移工具将Nginx Ingress配置迁移至云原生API网关
  2. 审查迁移报告，处理不兼容注解
  3. 可选使用higress注解启用高级功能

场景二：新业务架构

• 适用对象：构建全新API平台或对安全治理有高要求的企业
• 推荐方案：采用模式二（控制台API模式）
• 实施步骤：
  1. 在控制台定义API、配置安全策略
  2. 使用网关服务发现能力指向后端服务

场景三：渐进式演进（推荐策略）

• 适用对象：既要解决存量迁移又要提升治理能力的组织
• 推荐方案：从模式一开始，逐步演进到模式二
• 实施步骤：
  1. 采用模式一完成所有Nginx Ingress平滑迁移
  2. 识别组织内核心API
  3. 将核心API逐步纳管到模式二

路由优先级说明

对于相同域名和路径的路由，控制台创建的API优先级高于Ingress方式同步的路由。迁移过程中可以逐个在控制台配置，发现问题可通过删除控制台配置立即恢复。

注意：优先级基于单个路由粒度，不是整个域名。可以对某个域名下的部分路径使用控制台配置，其他路径继续使用Ingress。

迁移示例

初始状态（仅Ingress配置）

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: api-service-v1
            port:
              number: 8080
      - path: /web
        pathType: Prefix
        backend:
          service:
            name: web-service-v1
            port:
              number: 80

迁移中（控制台配置/api路径） 在控制台为example.com创建路由，配置/api指向新版本服务api-service-v2:8080。

实际路由顺序：

• /api → api-service-v2:8080（控制台配置，优先匹配）
• /api → api-service-v1:8080（Ingress配置，不会匹配到）
• /web → web-service-v1:80（Ingress配置，正常生效）

快速回退 删除控制台/api路由配置后，流量立即回退到Ingress配置的api-service-v1。

完全迁移 在控制台配置所有路径后，所有流量由控制台配置控制，可安全删除对应Ingress配置。