跳到主要内容

发布说明

APISIX Ingress Controller 和 API7 Ingress Controller 让 Kubernetes 用户能够通过 Gateway API 和 APISIX 自定义资源配置各自的网关。从 2.1.0 开始，两个 Controller 使用一致的版本号，其发布历史也合并到同一视图中。产品特有的功能可用性或行为会在相应位置明确说明。

如需查看 2.1.0 之前的版本，请使用各自独立的 APISIX Ingress Controller 和 API7 Ingress Controller 发布归档。

2.2.0​

产品发布日期
APISIX Ingress Controller2026-08-18
API7 Ingress Controller2026-08-21

此版本扩展了 Gateway API 和四层流量支持，新增下游双向 TLS（mTLS），并加强校验和凭证安全。两个 Controller 均支持 Kubernetes 1.31 或更高版本，以及 Gateway API 1.6.0。

破坏性变更​

以下变更可能会拒绝此前可接受的资源，或改变现有路由的匹配方式。

审查监听器端口匹配​

在 config.yaml 中省略 listener_port_match_mode 时，APISIX Ingress Controller 使用的值从 auto 改为 off。API7 Ingress Controller 在此版本中新增基于端口的监听器匹配，省略该字段时使用相同的默认值。

官方 Helm Chart 会显式渲染该字段，因此安装后的行为由对应 Chart 的默认值决定。APISIX Helm 安装默认为 auto，API7 Helm 安装默认为 off；显式配置的 Chart 值会覆盖相应默认值。

APISIX Ingress Controller 还新增保护措施：决定是否添加 server_port 匹配条件时排除带主机名的监听器。API7 Ingress Controller 在此版本中新增基于端口的匹配，但不包含此保护措施。当所选 Gateway 监听器端口与网关实际接收流量的端口不同时，路由可能无法匹配。

**升级操作：**发布前检查挂载的 config.yaml 中实际生效的 listener_port_match_mode，以及网关实际使用的端口。如果声明的 Gateway 监听器端口与实际网关端口不同，且无法对齐端口，请使用 off。

授权跨命名空间 Consumer Secret​

当 Consumer 引用其他命名空间中的凭证 Secret 时，两个 Controller 现在都要求配置 ReferenceGrant。如果没有授权，凭证不会下发。

**升级操作：**发布前在 Secret 所在的命名空间中创建授权。

修正无效的插件配置​

当插件 config 值无法解码为对象时，两个 Controller 现在都会使协调失败。此前的 Controller 可能会丢弃格式错误的值，并使用空配置发布插件，从而静默移除原本预期的强制策略。

**升级操作：**发布前查找并修正内联、引用、全局、基于注解以及 Consumer 插件配置中的格式错误。

补充缺失的 CSRF Key​

设置了 k8s.apisix.apache.org/enable-csrf: "true" 的 Ingress 现在必须同时设置非空的 k8s.apisix.apache.org/csrf-key。启用准入 Webhook 时，它会拒绝无效资源；如果准入被禁用或绕过，Controller 会记录注解错误并省略 CSRF 插件，使路由失去预期保护。

**升级操作：**发布前为所有受影响的 Ingress 添加非空 Key。

更新手动管理的四层 Webhook​

TCPRoute 和 UDPRoute 的 Webhook 规则及 Service 路径从 v1alpha2 迁移到 v1。发布的 Controller Manifest 包含新路径，但单独维护的 ValidatingWebhookConfiguration 不会自动更新。

**升级操作：**发布 Controller 前同时更新 API 版本和 Service 路径。

安全修复​

  • 两个 Controller 都会在 Controller 日志中遮蔽凭证和 Admin API Key。
  • Consumer Webhook 不再泄露其他命名空间中是否存在某个 Secret。
  • 跨命名空间访问 Consumer 凭证现在需要通过 ReferenceGrant 显式授权。
  • 无效的插件配置会导致失败，而不是以空配置应用。

新功能​

此版本新增以下流量管理与安全能力。

使用 mTLS 保护 Gateway 监听器​

两个 Controller 均可要求客户端出示由所配置证书颁发机构签名的证书。Gateway API 在 Gateway 上声明此校验，可为所有 HTTPS 监听器设置默认配置，也可按端口覆盖。

将策略应用于四层流量​

两个 Controller 均新增 L4RoutePolicy，用于把 Stream 插件附加到 TCPRoute、UDPRoute 和 TLSRoute 资源。Stream Backend 还可选择 tcp、tls 或 udp 作为上游 Scheme。

使用 Gateway API 1.6.0​

两个 Controller 均支持 Gateway API 1.6.0，包括 v1 版本的 TCPRoute、UDPRoute、TLSRoute 和 ReferenceGrant API。监听器端口匹配也扩展到 TCPRoute 和 UDPRoute。

按监听器端口匹配 API7 路由​

API7 Ingress Controller 新增针对 Gateway API 路由的端口匹配。APISIX Ingress Controller 已在 2.1.0 中提供此能力。

Bug 修复​

以下修复提升了路由正确性、状态报告和 Controller 可靠性。

Gateway 与路由协调​

  • Gateway 状态条件现在会报告 Gateway API 1.6.0 要求的 Reason。
  • 对大写主机名和 Server Name 进行规范化，使路由能够继续匹配。
  • TCPRoute 和 UDPRoute 会遵循显式选择的监听器名称或端口。
  • BackendTrafficPolicy 会遵循通过 targetRefs.sectionName 选择的 Service 端口。
  • HTTPRoute 会读取 ExternalName Service 的 appProtocol。

Controller 可靠性​

  • 新 Leader 会重新构建同步基线，而不是使用过期状态。
  • 提供的 NetworkPolicy 允许准入 Webhook 流量进入 Controller Pod。
  • 使用 ImplementationSpecific 路径且注解为空的 Ingress 不再导致 Panic。

源代码版本​

2.1.0​

产品发布日期
APISIX Ingress Controller2026-06-01
API7 Ingress Controller2026-05-29

此版本为两个 Controller 新增更丰富的路由、Consumer、健康检查和准入校验能力。APISIX Ingress Controller 还新增监听器端口匹配；API7 Ingress Controller 要到 2.2.0 才提供此能力。

破坏性变更​

APISIX Ingress Controller 引入一项可能影响现有 Gateway API 路由的变更。

对齐 APISIX 监听器端口​

APISIX Ingress Controller 会为部分 Gateway API 路由添加 server_port 条件，并使用 auto 作为 Controller 默认值。APISIX 会用实际接受连接的物理端口评估该条件。如果此端口与所选 Gateway 监听器端口不同，请求会返回 404。

API7 Ingress Controller 2.1.0 不提供基于端口的匹配。

**升级操作：**发布前将 listener_port_match_mode 设置为 off，或使 Gateway 监听器端口与 APISIX 监听器端口保持一致。

新功能​

两个 Controller 均扩展了路由与资源校验能力，其中一项仅由 APISIX 提供。

配置更丰富的路由与 Consumer​

两个 Controller 均为 ApisixRoute 新增请求体匹配、为 ApisixConsumer 新增插件配置，并支持从 Kubernetes 元数据派生 Consumer Label。BackendTrafficPolicy 也可以配置主动上游健康检查。

在协调前校验自定义资源​

两个 Controller 均为 APISIX 自定义资源新增准入校验。无效资源可以在进入转换和同步阶段前被拒绝。

按监听器端口匹配 APISIX 路由​

APISIX Ingress Controller 新增针对 Gateway API 路由的端口匹配。API7 Ingress Controller 在 2.2.0 中新增此能力。

Bug 修复​

以下修复提升了路由转换、状态报告、同步和健康检查能力。

路由转换与状态​

  • 正则表达式 HTTPRoute 路径不再生成无效的 URI 匹配。
  • Gateway API 路由状态条件现在会正确更新 observedGeneration。
  • 仅包含状态的 API 资源不再阻塞 Controller 就绪。
  • HTTPRoute 转换会保留已选择的 Backend Scheme。

同步与健康检查​

  • 配置后，两个 Controller 均会对独立的主动健康检查执行 HTTPS 证书校验。
  • APISIX Ingress Controller 移除了会导致持续差异和不必要同步的冗余路由 Host 配置。

源代码版本​