升级 APISIX Ingress Controller

APISIX Ingress Controller 2.2 引入 Gateway API 1.6、新增和更新的 APISIX CRD、更严格的校验，以及监听器端口匹配变更。从 2.1.0 升级前，请更新 CRD，并审查可能影响现有资源的兼容性变更。

API7 可用性

API7 Ingress Controller 尚未发布对应版本。请勿对最新公开的 API7 2.1.0 版本执行此流程，也不要只替换其 Controller 镜像。在 API7 发布兼容套件前，请继续使用 API7 版本所选定的 Controller、Chart 和安装包。

前置条件

升级前，请确认：

集群运行 Kubernetes 1.31 或更高版本。
已明确由 Helm、Argo CD 还是 Flux 管理 Controller。
已明确哪个部署所有者管理 Gateway API 和 APISIX CRD。保持所有者不变；若 CRD 由 GitOps 或平台版本管理，请勿手动应用 CRD。
已选择 APISIX Ingress Controller Chart 1.3.0。请勿只在旧 Chart 上覆盖镜像标签，因为其 CRD、RBAC 和 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。

升级 APISIX 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。

下载并应用 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

若通过 APISIX Umbrella Chart 安装 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 等安全插件。

监听器端口匹配

listener_port_match_mode 默认为 off。当 Gateway 监听器使用 80 等 Service 端口，而 APISIX 在 9080 等容器端口接收连接时，该设置会阻止 Controller 注入 server_port 匹配条件。

若将该模式设为 explicit 或 auto，它同样作用于 TCPRoute 和 UDPRoute。每个 Gateway 监听器端口都必须等于实际的 APISIX 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`

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

升级部署

将 Chart 版本、Controller 镜像、CRD、RBAC 和 Webhook 配置作为一个经过审查的版本变更统一更新。若 Controller 使用 NetworkPolicy，请在同一轮发布中更新它，以允许所需的 Webhook 流量。

对于 Helm 管理的部署，应用 CRD 更新，刷新 Chart 仓库元数据，然后使用 Chart 1.3.0 和已审查的 ingress-controller-overrides.yaml 文件运行 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​

升级 APISIX CRD​

审查配置变更​

跨命名空间消费者凭证​

CSRF 注解​

插件配置​

监听器端口匹配​

手动管理的 Webhook​

升级部署​

验证升级​

回滚​