升级 Ingress Controller
APISIX 与 API7 Ingress Controller 当前有不同的已发布升级目标。请选择与已安装产品和版本相符的路径，先于 Controller 更新其 CRD，并验证部署使用的流量路径。
选择升级路径
- **APISIX Ingress Controller 2.1.0 升级到 2.2.0：**完成从前置条件到验证升级的所有适用章节。
- API7 Ingress Controller 升级到 2.2.1：
- 从 2.1.0 升级时，完成从前置条件到验证升级的所有适用章节。
- 从 2.2.0 升级时，完成前置条件和备份当前部署，在升级 Gateway API CRD中验证 Gateway API 1.6，更新 Controller CRD，然后继续审查 API7 2.2.1 变更。
每条路径都需要目标 Controller 随附的 APISIX CRD。从 2.1.0 升级时，还会引入 Gateway API 1.6、其他 APISIX CRD、更严格的校验以及监听器端口匹配变更。
开始升级前，请先阅读发布说明，了解两个产品的共有变更和各自特有的变更。
API7 Dashboard 与 API7 Ingress Controller 使用独立的发布周期。重新生成的部署命令可能选择不同于你所选升级目标的 Controller release。
Helm 管理的安装使用常规 Helm 流程发布 Controller。对于 API7 Ingress Controller，请在 Dashboard 中重新生成部署命令，将其中的 Chart 和 Controller 镜像与升级目标进行比较，必要时同时调整，然后再运行 helm upgrade --install。参见 API7 部署版本。
对于 APISIX Ingress Controller，请使用所选 APISIX 安装 Chart 和已审查的 values，对现有 release 运行 helm upgrade。由于 Helm 不会升级 Chart crds/ 目录中已有的 APISIX CRD，下面的 CRD 步骤仍需单独执行。独立 APISIX Chart 1.4.0 则在另一项所有权控制下将 Gateway API 资源渲染为模板。
前置条件
升级前，请确认：
- 集群运行 Kubernetes 1.31 或更高版本。
- 已明确由 Helm、Argo CD 还是 Flux 管理 Controller。
- 已明确哪个部署所有者管理 Gateway API 和 APISIX CRD。除非正在执行有文档指导的所有权转移（例如迁移 APISIX Chart 1.3.x Gateway API 所有权），否则请保持所有者不变。若 CRD 由 GitOps 或平台版本管理，请勿手动应用 CRD。
- 已选择 Helm Chart 参考中列出的兼容 Controller Chart。请勿只在旧 Chart 上覆盖镜像标签，因为其 CRD、RBAC 和 Webhook 路径不兼容。
- 对于 API7 Ingress Controller，请始终使用同一 Controller release 的 Chart、Controller 与 ADC 镜像以及 CRD。私有 CA 连接支持需要 Chart 提供的兼容 ADC 边车（sidecar）。不要把固定到其他 Controller release 的 Dashboard 生成脚本，与本文档中的 CRD、Webhook 路径或示例混用。
备份当前部署
进行变更前，请先查看回滚，然后记录当前 Deployment 中配置的镜像：
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
两个目标版本都使用 Gateway API 1.6.0 Standard Channel，其中包含 Controller 使用的 v1 TCPRoute、UDPRoute 和 TLSRoute API。从 2.1.0 升级时，请在发布 Controller 前更新该 Bundle。
API7 Ingress Controller 2.2.0 已要求 Gateway API 1.6。从该版本升级时，请通过下面的命令验证已安装 CRD，并保持其现有所有者；除非该所有者需要更新，否则无需再次应用 Bundle。
若这些 CRD 由平台 Application、Kustomization 或其他 GitOps Source 管理，请将其固定的 Bundle 更新到 Gateway API 1.6，并协调该 Source。不要对平台管理的 CRD 执行手动命令，否则可能改变字段所有权并产生配置漂移。
对于独立 APISIX Chart 1.4.0，如果 Gateway API 由平台或其他 release 管理，请设置 crds.gatewayAPI.enabled=false。
对于手动管理的 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 Chart 1.3.x Gateway API 所有权
对于直接 Helm release 和 Flux HelmRelease，从 Chart 1.3.x 安装的 Gateway API 对象没有 1.4.0 模板查询所需的 release 注解。升级前，请将 Gateway API bundle 转移给一个固定版本的平台所有者：
- 将已安装的 Gateway API 1.6 bundle（包括准入策略及其 Binding）添加到固定版本的平台来源，例如 Flux Kustomization。
- 使用 Server-Side Apply 协调该来源，然后确认每个 CRD 都报告
Established状态，且准入资源均已存在。 - 在 Controller release 上设置
crds.gatewayAPI.enabled=false，并检查渲染出的差异，确认它不再包含 Gateway API bundle。 - 只有验证平台管理的 bundle 后，才升级 Controller。
不要手动添加 Helm 所有权注解。仅有注解不能建立兼容的字段所有权，还可能造成 apply 冲突。
Argo CD 在不查询实时所有权的情况下渲染 1.4.0 模板，因此现有 Controller Application 可以继续跟踪 Gateway API bundle。同步前请检查渲染出的差异。只有将该 bundle 移交给平台 Application 时，才应遵循安全转移 CRD 所有权。
升级 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 文件。Helm 会安装 Chart crds/ 目录中的资源，但执行 helm upgrade 时不会升级已有 CRD。因此，对于 Helm 用户，应用 APISIX CRD 是常规 Controller 升级前需要单独完成的前置步骤。
对于 APISIX Ingress Controller，下载并应用 APISIX CRD：
helm pull apisix/apisix-ingress-controller \
--version 1.4.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.28 \
--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
审查 2.2.0 配置变更
从 2.1.0 升级任一 Controller 时，以下兼容性变更均适用。如果从 API7 Ingress Controller 2.2.0 升级，请继续阅读审查 API7 2.2.1 变更。
跨命名空间消费者凭证
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 不再以空配置发布。对于 ApisixRoute 和 PluginConfig 等资源，Controller 会使转换失败；对于 Consumer，Controller 会记录错误、忽略该格式错误的插件，并继续转换其余 Consumer 配置。请检查 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 转发到 Controller 的 Webhook 端口，默认为 9443。若 NetworkPolicy 限制 Controller Pod，请允许访问所配置 Webhook 端口的 TCP 流量。
审查 API7 2.2.1 变更
只要目标为 API7 Ingress Controller 2.2.1，无论已安装版本是 2.1.0 还是 2.2.0，本节均适用。
路由不再被接受时停止服务
当路由离开受管 Gateway，或其父级监听器均不再接受该路由时，API7 Ingress Controller 2.2.1 会移除先前已同步的配置。升级前，请确认应继续生效的路由具有已接受的父级和监听器。
暂时缺少 Gateway 或 GatewayClass 不会触发移除，因为 Controller 此时尚无法判断所有权。
插件配置被删除时路由停止服务
引用已删除 ApisixPluginConfig 的 ApisixRoute 或 Ingress 现在会停止服务，而不会保留最后一次同步的插件。请在删除插件配置前移除引用，或在升级前恢复缺失对象。
监听器协议
API7 Ingress Controller 2.2.1 将 HTTPRoute 和 GRPCRoute 流量限制为其所附加监听器接受的协议。请确认客户端和健康探针访问仅附加到 HTTPS 监听器的路由时使用 HTTPS，访问仅附加到 HTTP 监听器的路由时使用 HTTP。
ApisixRoute Service 端口
API7 Ingress Controller 2.2.1 会拒绝后端 servicePort 为空或与所引用 Service 端口不匹配的 ApisixRoute。升级前请修正这些值，以免相关路由被拒绝。
升级部署
CRD 准备就绪后，使用常规部署流程。若 Controller 使用 NetworkPolicy，请在同一轮发布中更新它，以允许所需的 Webhook 流量。
- 对于直接使用 Helm 管理的 API7 Ingress Controller，请在 Dashboard 中为现有网关组重新生成部署脚本。保留现有 release 名称、命名空间、
config.controllerName和config.leaderElection.id。目标为 2.2.1 时，确认命令同时设置--version 0.1.28和--set "deployment.image.tag=2.2.1"；如果 Dashboard 仍生成旧 release，请同时更新这两个选择。保留目标 Chart 默认的 ADC 镜像，审查所有自定义覆盖值，然后运行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>
验证升级
确认升级后的 release 配置的镜像和创建的 Webhook 端点。请替换为其 ValidatingWebhookConfiguration 名称：
kubectl get deployment <ingress-controller-deployment> -n <namespace> \
-o jsonpath='{range .spec.template.spec.containers[*]}{.image}{"\n"}{end}'
kubectl get validatingwebhookconfiguration <validating-webhook-configuration> \
-o jsonpath='{range .webhooks[*]}{.clientConfig.service.namespace}{"/"}{.clientConfig.service.name}{"\t"}{.clientConfig.service.path}{"\t"}{range .rules[*].apiVersions[*]}{.}{" "}{end}{"\n"}{end}' \
| grep -E 'v1-(tcp|udp)route'
每条 TCPRoute 和 UDPRoute 记录都应显示预期的 Webhook Service、对应的 v1 路径以及 v1 API 版本。
列出 Gateway API 和策略资源：
kubectl get gateway,httproute,grpcroute,tcproute,udproute,tlsroute -A
kubectl get backendtrafficpolicy,l4routepolicy -A
确认 Gateway 针对当前 generation 报告预期的 Programmed 条件，Route 报告预期的 Accepted 和 ResolvedRefs 条件。策略列表只能确认资源仍然存在；还应通过下面的流量检查验证其行为，如果观察到的行为不同，请检查 Controller 日志。
验证环境中使用的流量路径：
- HTTP 和 gRPC 路由返回预期响应。
- TLSRoute 终止提供预期证书，并按 SNI 路由。
- TCPRoute 和 UDPRoute 流量到达所选监听器和后端。
- 下游 mTLS 接受有效客户端证书，并拒绝缺少证书的请求。
- 仅当存在匹配的
ReferenceGrant时，跨命名空间 Consumer 凭证才有效。 - 启用准入 Webhook 时，应用已启用 CSRF 但未设置 Key 的 Ingress 应被拒绝。若禁用 Webhook，请确认不存在启用了 CSRF 但未设置非空 Key 的 Ingress。
目标为 API7 Ingress Controller 2.2.1 时，还应验证：
- 应继续生效的路由具有已接受的父级并持续提供流量。
- 仅支持 HTTP 或仅支持 HTTPS 的路由能通过其监听器接受的协议正常工作。
- 配置
controlPlane.caCert时，能够在启用控制面证书验证的情况下成功同步。 - v1alpha1 插件使用
secretRef时，其行为反映所引用 Secret 的内容，并且在 Secret 变更后仍会更新。
回滚
使用同一部署所有者回滚 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 兼容。
将 API7 Ingress Controller 从 2.2.1 回滚到 2.2.0 后，Controller 不再处理 controlPlane.caCert 或 v1alpha1 插件的 secretRef。回滚前，请将对这些字段的依赖替换为 2.2.0 支持的配置，并保留较新的 CRD。
将任一 Controller 回滚到 2.1.0 后，旧版 Controller 不会协调 L4RoutePolicy，也可能不会监视 Gateway API v1 四层资源路径。在恢复兼容 Controller 前，应将 TCP、UDP 和 TLS 路由视为不可用。若某个资源导致回滚，请移除或修正该资源，而不是降级集群范围的 CRD。