升级 Ingress Controller

将 APISIX 或 API7 Ingress Controller 从 2.1.0 升级到 2.2.0 时，必须先更新 CRD，再发布新版 Controller。新版本引入 Gateway API 1.6、新增和更新的 APISIX CRD、更严格的校验，以及监听器端口匹配变更。升级前请审查这些兼容性变更。

开始升级前，请先阅读发布说明，了解两个产品的共有变更和各自特有的变更。

Helm 管理的安装使用常规 Helm 流程发布 Controller。对于 API7 Ingress Controller，请在 Dashboard 中重新生成部署命令，并运行其中的 helm upgrade --install 命令。对于 APISIX Ingress Controller，请使用所选 APISIX 安装 Chart 和已审查的 values，对现有 Release 运行 helm upgrade。由于 Helm 不会升级 Chart crds/ 目录中已有的 CRD，下面的 CRD 步骤仍需单独执行。

前置条件

升级前，请确认：

集群运行 Kubernetes 1.31 或更高版本。
已明确由 Helm、Argo CD 还是 Flux 管理 Controller。
已明确哪个部署所有者管理 Gateway API 和 APISIX CRD。保持所有者不变；若 CRD 由 GitOps 或平台版本管理，请勿手动应用 CRD。
已选择 Helm Chart 参考中列出的兼容 Controller Chart。请勿只在旧 Chart 上覆盖镜像标签，因为其 CRD、RBAC 和 Webhook 路径不兼容。
对于 API7 Ingress Controller，请始终使用同一 Controller 发布版本的 Chart、镜像和 CRD。不要把固定到其他 Controller 版本的 Dashboard 生成脚本，与本文档中的 CRD、Webhook 路径或示例混用。

备份当前部署

记录当前运行的镜像：

kubectl get deployment <ingress-controller-deployment> -n <namespace> \
  -o jsonpath='{.metadata.namespace}{"/"}{.metadata.name}{": "}{range .spec.template.spec.containers[*]}{.image}{" "}{end}{"\n"}'

对于 Argo CD 或 Flux 部署，请在变更前确认能够恢复当前 Git revision 和 Controller 配置。

对于 Helm Release，请保存计算后的配置值作为回滚参考，并导出升级要使用的用户覆盖值：

helm get values <release-name> -n <namespace> --all -o yaml \
  > ingress-controller-computed-values-backup.yaml
helm get values <release-name> -n <namespace> -o yaml \
  > ingress-controller-overrides.yaml

不要把计算后的配置值备份传给 helm upgrade，其中包含旧 Chart 的默认值。检查 ingress-controller-overrides.yaml 中已重命名或移除的设置，只向新 Chart 传入迁移后的用户覆盖值。

升级 Gateway API CRD

部署新版 Controller 前，将 Gateway API Bundle 升级到 1.6.0 Standard Channel。该 Bundle 包含 Controller 使用的 v1 TCPRoute、UDPRoute 和 TLSRoute API。

若这些 CRD 由平台 Application、Kustomization 或其他 GitOps Source 管理，请将其固定的 Bundle 更新到 Gateway API 1.6，并协调该 Source。不要对平台管理的 CRD 执行手动命令，否则可能改变字段所有权并产生配置漂移。

对于手动管理的 Bundle，请使用 Server-Side Apply，因为 CRD 超出了客户端注解大小限制：

kubectl apply --server-side --force-conflicts \
  -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.0/standard-install.yaml

确认 API Server 提供 Controller 使用的版本：

kubectl get crd tcproutes.gateway.networking.k8s.io \
  -o jsonpath='{range .spec.versions[?(@.served==true)]}{.name}{"\n"}{end}'
kubectl get crd udproutes.gateway.networking.k8s.io \
  -o jsonpath='{range .spec.versions[?(@.served==true)]}{.name}{"\n"}{end}'

两项输出都应包含 v1。

升级 Controller CRD

部署新版 Controller 前，通过现有所有者升级 APISIX CRD：

若 CRD 由独立的平台 Application 或 Kustomization 管理，请更新其固定的 APISIX CRD Source，并在协调 Controller 前先协调该 Source。
若 Argo CD Controller Application 或 Flux HelmRelease 管理打包的 CRD，请在 Git 中更新 Chart 和 CRD 设置，并执行对应工具的升级流程。不要手动应用 CRD。

对于 APISIX CRD 不受其他协调器管理的直接 Helm 部署，请下载兼容的 Controller Chart，并只应用其中的 APISIX CRD 文件。不要应用 Chart 的聚合 CRD 输出，因为它还包含可能由其他所有者管理的 Gateway API Bundle。Helm 会安装 Chart crds/ 目录中的资源，但执行 helm upgrade 时不会升级已有 CRD。对于 Helm 用户，应用 CRD 是常规 Controller 升级前需要单独完成的前置步骤。

对于 APISIX Ingress Controller，下载并应用 APISIX CRD：

helm pull apisix/apisix-ingress-controller \
  --version 1.3.0 \
  --untar --untardir <chart-download-directory>
kubectl apply --server-side --force-conflicts \
  -f <chart-download-directory>/apisix-ingress-controller/crds/apisixic-crds.yaml

对于 API7 Ingress Controller，下载并应用 APISIX CRD：

helm pull api7/api7-ingress-controller \
  --version 0.1.26 \
  --untar --untardir <chart-download-directory>
kubectl apply --server-side --force-conflicts \
  -f <chart-download-directory>/api7-ingress-controller/crds/apisix-crds.yaml

若通过 APISIX Umbrella Chart 安装 APISIX Ingress Controller，请使用其依赖项声明的 Controller Chart 版本。CRD 所有者完成协调后，确认所选 Source 包含新的策略 CRD：

kubectl get crd l4routepolicies.apisix.apache.org

审查配置变更

升级前处理以下兼容性变更。

跨命名空间消费者凭证

Consumer 引用其他命名空间中的凭证 Secret 时，现在必须在 Secret 所在命名空间中存在 ReferenceGrant。部署新版 Controller 前请先创建该授权；否则 Controller 不再下发该凭证。参见配置跨命名空间引用。

CSRF 注解

设置了 k8s.apisix.apache.org/enable-csrf: "true" 的 Ingress 还必须设置非空的 k8s.apisix.apache.org/csrf-key。启用准入 Webhook 时，缺少 Key 或 Key 为空的 Ingress 会被拒绝。若 Webhook 被禁用或绕过，Kubernetes 可以接受该 Ingress，但 Controller 会记录注解错误，并在转换路由时忽略 CSRF 插件。

部署前修复所有受影响的 Ingress，避免原本需要 CSRF 防护的路由在无防护状态下发布。参见 CSRF 注解参考。

插件配置

格式错误的插件 config 现在会导致转换失败，不再以空配置发布插件。请检查 Controller 日志和资源状态，查找此前被忽略的配置，尤其是 ip-restriction 等安全插件。

监听器端口匹配

Controller 二进制在省略 listener_port_match_mode 字段时默认为 off。这可以避免 Gateway 监听器使用 80 等 Service 端口，而网关在 9080 等容器端口接收连接时注入 server_port 匹配条件。

Helm 并不总是安装该二进制默认值：

安装入口	安装此版本后的有效模式
API7 Ingress Controller Chart	`off`
APISIX Ingress Controller Chart（包括 APISIX umbrella Chart）	`auto`

使用 APISIX Chart 升级会保留或设置 auto。若要在该路径上使用 off，请在独立 Chart 上设置 config.listenerPortMatchMode=off，或在 umbrella Chart 上设置 ingress-controller.config.listenerPortMatchMode=off。

若使用 explicit 或 auto，该模式同样作用于 TCPRoute 和 UDPRoute。请根据配置参考审查满足注入条件的路由和监听器。每当 Controller 注入 server_port 条件时，声明的 Gateway 监听器端口都必须与对应的物理 HTTP、TLS 或 Stream 监听端口一致。保留任一模式前，请审查所有 HTTP、gRPC、TCP 和 UDP 监听器。

手动管理的 Webhook

Chart 会把 TCPRoute 和 UDPRoute Webhook 的规则与路径从 v1alpha2 更新到 v1。若在 Chart 外管理 ValidatingWebhookConfiguration，请同时更新 rules[].apiVersions 和 clientConfig.service.path：

资源	API 版本	Webhook 路径
TCPRoute	`v1`	`/validate-gateway-networking-k8s-io-v1-tcproute`
UDPRoute	`v1`	`/validate-gateway-networking-k8s-io-v1-udproute`

API7 Ingress Controller Chart 0.1.26 将 webhook.failurePolicy 的默认值从 Fail 改为 Ignore，避免集群级 Webhook 不可用时阻塞其他 Controller 所属资源的变更。若要保留故障时关闭的准入策略，请显式将该值设置为 Fail，并确保 Webhook 高可用。

Webhook Service 将端口 443 转发到容器端口 9443。若 NetworkPolicy 限制 Controller Pod，请允许访问 Pod 的 TCP 端口 9443。

升级部署

CRD 准备就绪后，使用常规部署流程。若 Controller 使用 NetworkPolicy，请在同一轮发布中更新它，以允许所需的 Webhook 流量。

对于直接使用 Helm 管理的 API7 Ingress Controller，请在 Dashboard 中为现有网关组重新生成部署脚本。加入经过审查的自定义覆盖值，然后运行生成的 helm upgrade --install 命令。
对于直接使用 Helm 管理的 APISIX Ingress Controller，请刷新 Chart 仓库元数据，并使用所选 APISIX 安装 Chart 和经过审查的 ingress-controller-overrides.yaml 文件，对现有 Release 运行 helm upgrade。
对于 Argo CD 或 Flux，在 Git 中更新 CRD Source 以及 Controller Chart 或 Manifest Pin。先协调 CRD 所有者，等待所需 CRD 进入 Established 状态，再协调 Controller。根据所选所有权模型执行 Argo CD 或 Flux 流程。

等待部署完成：

kubectl rollout status deployment/<ingress-controller-deployment> -n <namespace>

验证升级

确认正在运行的镜像和 Webhook 端点：

kubectl get deployment <ingress-controller-deployment> -n <namespace> \
  -o jsonpath='{range .spec.template.spec.containers[*]}{.image}{"\n"}{end}'

kubectl get validatingwebhookconfiguration \
  -o jsonpath='{range .items[*].webhooks[*]}{.clientConfig.service.path}{"\t"}{range .rules[*].apiVersions[*]}{.}{" "}{end}{"\n"}{end}' \
  | grep -E 'v1-(tcp|udp)route'

每条 TCPRoute 和 UDPRoute 记录都应先显示其 v1 Webhook 路径，再显示 v1 API 版本。

确认 Gateway API 和策略资源均被接受：

kubectl get gateway,httproute,grpcroute,tcproute,udproute,tlsroute -A
kubectl get backendtrafficpolicy,l4routepolicy -A

验证环境中使用的流量路径：

HTTP 和 gRPC 路由返回预期响应。
TLSRoute 终止提供预期证书，并按 SNI 路由。
TCPRoute 和 UDPRoute 流量到达所选监听器和后端。
下游 mTLS 接受有效客户端证书，并拒绝缺少证书的请求。
仅当存在匹配的 ReferenceGrant 时，跨命名空间 Consumer 凭证才有效。
启用准入 Webhook 时，应用已启用 CSRF 但未设置 Key 的 Ingress 应被拒绝。若禁用 Webhook，请确认不存在启用了 CSRF 但未设置非空 Key 的 Ingress。

回滚

使用同一部署所有者回滚 Controller：

对于直接 Helm 部署，运行 helm history <release-name> -n <namespace> 确定升级前的 revision，再运行 helm rollback <release-name> <revision> -n <namespace> --wait。保留已保存的配置值作为参考，但不要将其传给 helm rollback。
对于 Argo CD，按照 Argo CD 回滚流程在 Git 中还原 Controller 版本和配置值。不要运行 helm rollback 或直接编辑 Deployment。
对于 Flux，按照 Flux 回滚流程在 Git 中还原 Controller 版本和配置值。不要运行 helm rollback 或直接编辑 Deployment。

回滚时不要删除或降级 Gateway API 或 APISIX CRD。删除 CRD 也会删除其自定义资源。请让已安装的 CRD 继续由现有所有者管理，并确认它们仍与旧版 Controller 兼容。

旧版 Controller 不会协调新的 L4RoutePolicy 资源，也可能不会监视 Gateway API v1 四层资源路径。回滚后，在恢复兼容 Controller 前，应将 TCP、UDP 和 TLS 路由视为不可用。若某个资源导致回滚，请移除或修正该资源，而不是降级集群范围的 CRD。

前置条件​

备份当前部署​

升级 Gateway API CRD​

升级 Controller CRD​

审查配置变更​

跨命名空间消费者凭证​

CSRF 注解​

插件配置​

监听器端口匹配​

手动管理的 Webhook​

升级部署​

验证升级​

回滚​