发布说明
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 会拒绝受影响的配置，而不会只发布其内联字段。
源 release
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。
破坏性变更
以下变更可能会拒绝此前可接受的资源，或改变现有路由的匹配方式。
审查监听器端口匹配
在 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 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 路由的变更。
对齐 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 配置。