发布说明
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.1
| 产品 | 发布日期 |
|---|---|
| API7 Ingress Controller | 2026-09-10 |
API7 Ingress Controller 已发布 2.2.1,而 APISIX Ingress Controller 仍为 2.2.0。本条记录适用于 API7 Ingress Controller 2.2.1;该版本增强了 Secret 与证书处理的安全性,并修正了路由校验、监听器匹配以及过期数据面配置问题。
破坏性变更
以下修正可能会停止提供旧版 Controller 曾继续接受或保留的配置。
路由不再被接受时停止服务
编辑操作确认路由不再具有受管 Gateway 或已接受的监听器后,Controller 现在会从数据面移除该路由。这包括将路由移到其他 GatewayClass、移除其选定监听器、限制 allowedRoutes,或修改 主机名直至不再相交。
暂时无法解析的 Gateway 或 GatewayClass 不会触发移除,因为此时尚无法确定所有权。
**升级:**升级前,请修正应继续生效但没有已接受父级和监听器的所有路由。路由所有权或监听器准入被撤销后,不要依赖先前同步的配置继续生效。
插件配置被删除时路由停止服务
删除 ApisixPluginConfig 后,现在会移除仍引用该对象的 ApisixRoute 或 Ingress 配置。旧版可能在报告引用无效的同时,仍继续使用最后一次同步的插件。重新创建被引用对象后,协调过程可以恢复路由。
**升级:**删除 ApisixPluginConfig 前,请先应用移除引用的变更。在所有依赖该对象的路由和 Ingress 更新完成前,请保持该对象可用。
拒绝无效的 ApisixRoute Service 端口
如果 ApisixRoute 后端的 servicePort 为空,或与被引用 Service 的任何端口都不匹配,该路由现在会被拒绝,而不会再以空上游的形式被接受。空字符串也不再意外匹配单端口 Service 上未命名的端口。
**升级:**发布前,请确认每个 servicePort 都是有效的 Service 端口名称或端口号。
路由遵循已接受监听器的协议
HTTPRoute 和 GRPCRoute 资源现在只通过其所附加监听器接受的协议提供流量。仅附加到 HTTPS 监听器的路由不再响应明文 HTTP 请求;仅附加到 HTTP 监听器的路由也不再通过 TLS 响应。同时附加到两种协议的路由仍会继续提供两种协议的服务。
**升级:**请根据路由已接受的 Gateway 监听器所声明的协议检查客户端和健康探针。
新功能
以下两个选项在 API7 Ingress Controller 2.2.1 中可用,但 APISIX Ingress Controller 2.2.0 不支持。
信任私有控制面 CA
GatewayProxy 可以在 spec.provider.controlPlane.caCert.value 中提供 PEM 编码的证书包。设置 tlsVerify: true 后,Controller 连接使用私有或自签名证书颁发机构的控制面时,会使用该证书包替代系统信任存储。无效的证书材料会被拒绝;禁用证书验证时,此字段不生效。
从 Secret 加载插件配置
v1alpha1 PluginConfig、Consumer 和 L4RoutePolicy 资源中的插件可以通过 secretRef 引用同一命名空间中的 Secret。Secret Key 使用指向插件配置的点分隔路径,其值以字符串形式合并,并覆盖匹配的内联字段。更新 Secret 会触发重新协调。如果 Secret 缺失,Controller 会拒绝受影响的配置,而不会只发布其内联字段。
源代码版本
2.2.0
| 产品 | 发布日期 |
|---|---|
| APISIX Ingress Controller | 2026-08-18 |
| API7 Ingress Controller | 2026-08-21 |
此版本扩展了 Gateway API 和四层流量支持,新增下游双向 TLS(mTLS),并加强校验和凭证安全。两个 Controller 均支持 Kubernetes 1.31 或更高版本,以及 Gateway API 1.6.0。
Kubernetes 1.31 是受支持版本的边界,而不是启动所需的最低版本。在更早的集群上,Controller 会记录警告并继续运行,但该集群版本不在此版本已测试和受支持的范围内。
破坏性变更
以下变更可能会拒绝此前可接受的资源 ,或改变现有路由的匹配方式。
使用服务端应用更新 Gateway API CRD
Gateway API 1.6.0 的 CRD 超过了客户端应用所用的注解大小限制。因此,手动管理的 CRD 包若继续使用客户端应用,可能在 Controller 升级前就更新失败。
**升级操作:**在发布 Controller 前,使用当前管理 Gateway API CRD 的同一部署机制,将它们更新为 1.6.0 版本。对于手动管理的 CRD 包,应使用 kubectl apply --server-side --force-conflicts,而不是客户端应用。
审查监听器端口匹配
在 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。
- 状态条件消息会限制在 Kubernetes 的 32,768 字节上限内。
- 对大写主机名和 Server Name 进行规范化,使路由能够继续匹配。
- TCPRoute 和 UDPRoute 会遵循显式选择的监听器名称或端口。
BackendTrafficPolicy会遵循通过targetRefs.sectionName选择的 Service 端口。ApisixUpstream会保留已选择的健康检查类型。- HTTPRoute 会读取 ExternalName Service 的
appProtocol。 - 以逗号分隔的注解值会忽略两侧空白字符。
Controller 可靠性
- 新 Leader 会重新构建同步基线,而不是使用过期状态。
- Kubernetes API Server 暂时不可用时,Controller 不再误判为 API 资源不可用。
- 从 Secret 加载的 HMAC 凭证会将
signed_headers解析为以逗号或空白字符分隔的 Header 列表。 - 提供的 NetworkPolicy 允许准入 Webhook 流量进入 Controller Pod。
- 使用
ImplementationSpecific路径且注解为空的 Ingress 不再导致 Panic。 - APISIX Ingress Controller 修正了随附的 Kustomize Manifest,使 Overlay 可以一致地构建和部署。
源代码版本
2.1.0
| 产品 | 发布日期 |
|---|---|
| APISIX Ingress Controller | 2026-06-01 |
| API7 Ingress Controller | 2026-05-29 |
此版本为两个 Controller 新增更丰富的路由、Consumer、健康检查和准入校验能力。APISIX Ingress Controller 还新增监听器端口匹配;API7 Ingress Controller 要到 2.2.0 才提供此能力。
破坏性变更
APISIX Ingress Controller 引入一项可能影响现有 Gateway API 路由的变更。