Traefik v3 功能弃用解析：Kubernetes `v1beta1` API 支持的移除与迁移到 `v1`

本文基于 Traefik 仓库中的官方功能弃用通告（deprecation/features.md）展开，系统讲解 Traefik v3.0 中两项与 Kubernetes 相关的废弃决策：Ingress API networking.k8s.io/v1beta1 支持及 CRD 定义 API apiextensions.k8s.io/v1beta1 支持的移除。读完本文，你将理解这两项废弃的具体影响范围、底层移除的源码证据，以及如何依据官方版本支持策略完成向 v1 API 的迁移。

弃用总览

Traefik 在 Feature Deprecation Notices 中集中记录项目路线图上与功能弃用相关的决策。当前记录在案的条目如下（完整继承自原文档）：

Feature	Deprecated	End of Support	Removal
Kubernetes Ingress API Version networking.k8s.io/v1beta1	N/A	N/A	3.0
CRD API Version apiextensions.k8s.io/v1beta1	N/A	N/A	3.0

两张条目的共同特征是：没有经历“先弃用、后移除”的过渡期，而是直接在 v3.0 中移除。这与 Traefik 大版本（v2 → v3）允许破坏性变更的定位一致，也是 v2 到 v3 迁移指南 中重点提示的升级风险点之一。

移除项一：Kubernetes Ingress API networking.k8s.io/v1beta1

官方声明

原文档对该项的 Impact 说明是：

The Kubernetes Ingress API Version networking.k8s.io/v1beta1 support is removed in v3. Please use the API Group networking.k8s.io/v1 instead.

即：Traefik v3 不再读取/处理 networking.k8s.io/v1beta1 版本的 Ingress 资源，必须使用 networking.k8s.io/v1。

为什么移除是必然的

v2-to-v3 迁移细节文档 进一步补充了背景：Kubernetes 自身早在 v1.22 起就已移除了 Ingress 的 v1beta1 API 版本（原文引用了 Kubernetes 官方弃用指南中 Ingress v1.22 的条目）。也就是说，在 Traefik v3 所面向的 Kubernetes 集群里，v1beta1 Ingress 早已不存在于 API Server 上，保留对它的解析支持已经没有实际价值，只会在代码中遗留死分支。

源码层面的印证

从源码结构看，当前仓库的 Kubernetes Ingress provider 已经完全建立在 v1 API 之上：

• pkg/provider/kubernetes/ingress/ 目录下的 convert.go、kubernetes.go 等核心文件中，Ingress 的模型类型全部来自 Kubernetes networking.k8s.io/v1 的 Go 客户端包（networkingv1），不存在任何 v1beta1 的导入或转换逻辑；
• 单元测试 convert_test.go 中的测试函数命名为 Test_convertSlice_corev1_to_networkingv1，即“corev1 → networkingv1”的转换路径，进一步证实整个 provider 的数据面已经收敛到 v1。

因此，如果你从 Traefik v2 升级而来，检查清单很简单：确认集群中的所有 Ingress 资源 apiVersion 均为 networking.k8s.io/v1。仓库中的集成测试固件（如 integration/k8s/03-ingress.yml）展示的就是 v1 Ingress 的标准写法，可作为对照样例。

移除项二：Traefik CRD 定义 API apiextensions.k8s.io/v1beta1

官方声明

原文档对应说明为：

The Traefik CRD definitions API Version apiextensions.k8s.io/v1beta1 support is removed in v3. Please use the API Group apiextensions.k8s.io/v1 instead.

需要精确理解这里的含义：被移除的不是 Traefik 自定义资源（IngressRoute、Middleware 等）自身的 v1alpha1 版本，而是 CRD 定义文件本身所声明的 API 版本——即 Traefik 官方发布的 CRD 清单（CustomResourceDefinition）不再提供 apiextensions.k8s.io/v1beta1 变体，只发布 apiextensions.k8s.io/v1 变体。

v2-to-v3 迁移细节 同样指出：Kubernetes v1.22 已移除 CRD 的 v1beta1 API，因此 v3 只保留 v1 支持。

仓库中 CRD 清单的当前状态

当前仓库随附的 CRD 定义文件 kubernetes-crd-definition-v1.yml 中，每一个 CustomResourceDefinition 资源都声明为：

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  annotations:
    controller-gen.kubebuilder.io/version: v0.19.0
  name: ingressroutes.traefik.io
spec:
  group: traefik.io
  names:
    kind: IngressRoute
    listKind: IngressRouteList
    plural: ingressroutes
    singular: ingressroute
  scope: Namespaced
  versions:
  - name: v1alpha1
    schema:
      openAPIV3Schema:
        description: IngressRoute is the CRD implementation of a Traefik HTTP Router.

可以看到：CRD 外壳是 apiextensions.k8s.io/v1，而 Traefik 资源本身使用 group: traefik.io 下的 v1alpha1。这一点也与迁移文档中“v3 已移除 API Group traefik.containo.us，请改用 traefik.io”的条目相呼应（见 v2-to-v3-details 对应小节）——三者（Ingress v1beta1、CRD v1beta1、traefik.containo.us 组名）共同构成了 v2 → v3 升级时 Kubernetes 侧的主要 API 对齐工作。

一个容易混淆的点：Gateway API 的 v1beta1 不在移除之列

在 Traefik 的 Kubernetes 代码中搜索 v1beta1，还会命中 pkg/provider/kubernetes/gateway/client.go 对 sigs.k8s.io/gateway-api/apis/v1beta1 的导入，以及 kubernetes.go 中处理 ReferenceGrant 的逻辑。这里的 v1beta1 属于 Gateway API 规范自身的版本线（gateway.networking.k8s.io/v1beta1，ReferenceGrant 资源至今仍在该渠道），与本文弃用表中被移除的 networking.k8s.io/v1beta1、apiextensions.k8s.io/v1beta1 完全是不同的 API 组，不属于本次弃用范围，排查时不要误删。

版本支持策略：为什么是“3.0 移除”

理解这两项移除的时机，需要结合 Traefik 的版本支持规则。releases.md 给出的现状是：

Version	Release Date	Active Support	Security Support
3.7	May 05, 2026	Yes	Yes
3.0	Apr 29, 2024	Ended Jul 15, 2024	No
2.11	Feb 12, 2024	Ended Apr 29, 2025	Ended Feb 01, 2026

（完整版本表见原文档。）其版本支持规则为：

• 任一时刻只有最新的 minor 版本处于活动支持期；
• 发布新 major 后，上一个 major 的最后一个 minor 会获得 1 年的支持（v2.11 即为 v3.0 发布后获得的过渡支持窗口）；
• 上述目标日期可能调整，届时会公开发布公告。

因此从 v2.11 升级到 v3.0（2024 年 4 月 29 日）的那一刻起，v1beta1 相关支持即整体下线；仍在 v2 线上的用户则需在迁移指南引导下一次性完成对齐。官方强调各版本间的升级步骤请以 v2 到 v3 迁移指南 和 v3 各小版本迁移说明 为准。

实操检查清单

将上述文档结论落成可执行的动作，升级（或新建部署）前建议核对以下各项：

1. Ingress 资源版本对齐：确认集群内所有 Ingress 的 apiVersion: networking.k8s.io/v1。可在集群中检索是否残留 networking.k8s.io/v1beta1 声明；对 v1.22+ 的集群，残留的 v1beta1 资源本身就无法被 API Server 接受，属于集群升级阶段就要清理的内容。
2. 应用 v1 版 CRD：安装或更新 Traefik CRD 时，使用 apiextensions.k8s.io/v1 的清单文件（本仓库中为 kubernetes-crd-definition-v1.yml），不要在旧清单基础上手工降级 API 版本。
3. API Group 对齐：CRD 资源使用 traefik.io 组（v3 已移除 traefik.containo.us），避免升级后资源无法被识别。
4. 区分 Gateway API 版本线：若同时启用 Gateway provider，ReferenceGrant 等资源使用的 gateway.networking.k8s.io/v1beta1 属于 Gateway API 规范版本，遵循 Gateway API 自身的升级节奏，与 Traefik 本次移除的两项无关（可参考 gateway provider 源码 中 ReferenceGrant 的过滤逻辑了解其处理位置）。
5. 跟踪后续弃用公告：deprecation/features.md 是持续维护的页面，随路线图更新；而 deprecation/releases.md 中明确提示“所有支持结束或功能移除的目标日期均可能变更”，规划升级窗口时应以该页面的最新内容为准。

小结

Traefik v3.0 的功能弃用集中在 Kubernetes API 对齐上：Ingress networking.k8s.io/v1beta1 与 CRD 定义 apiextensions.k8s.io/v1beta1 两项支持直接移除，统一收敛到 Kubernetes 自 v1.22 起的 v1 API。从当前仓库的源码结构看，pkg/provider/kubernetes/ingress/ 数据面、kubernetes-crd-definition-v1.yml CRD 清单都已全面基于 v1 构建，与官方文档声明相互印证。对 v2 存量用户，正确的动作是跟随 迁移指南 完成 Ingress 版本、CRD 清单与 API Group 的三处对齐，而非寻找任何 v1beta1 的兼容开关——v3 中不存在这样的开关。