本文档采用自动化机器翻译技术翻译。 尽管我们力求提供准确的译文，但不对翻译内容的完整性、准确性或可靠性作出任何保证。 若出现任何内容不一致情况，请以原始 英文 版本为准，且原始英文版本为权威文本。

升级到 CAPI v1beta2

Rancher Turtles 的 v0.26.0 版本采用了 CAPI v1beta2 合同，随之而来的是 CAPI 内核 v1.12.2。如果您正在使用基于 CAPI 的配置，请在升级前查看一些事项。

这些更改分为三个领域：

在进行任何更改之前，请仔细阅读适用于您设置的部分。

关于向后兼容性的说明

CAPI v1.12 继续为 v1beta1 和 v1beta2 资源提供服务。集群上的现有资源将继续工作，无需立即迁移，因为 API 服务器在两个版本之间透明地转换。也就是说，您编写的任何新清单应针对 v1beta2，并且您应计划逐步迁移现有清单。v1beta1 API 计划在未来的 CAPI 版本中移除（2026 年 8 月），届时生态系统将有时间在 v1beta2 上稳定下来。

建议：首先评估您是否准备好采用 v1beta2，并相应采取行动。如果您选择不立即迁移，请制定计划以切换到使用新 API，以避免未来的中断。

此外，上游社区提供了官方迁移指南：

ClusterClass

模板引用

在 v1beta1 中，指向 ClusterClass 模板对象的字段被称为 ref。在 v1beta2 中称为 templateRef。这适用于 spec.infrastructure、spec.controlPlane 和 spec.controlPlane.machineInfrastructure。

之前：

spec:
  infrastructure:
    ref:
      apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
      kind: DockerClusterTemplate
      name: my-cluster-template

此时间后：

spec:
  infrastructure:
    templateRef:
      apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
      kind: DockerClusterTemplate
      name: my-cluster-template

工作器部分

在 v1beta1 中，机器部署的启动和基础设施引用嵌套在 template 字段下。在 v1beta2 中，这个 root 已被删除。bootstrap 和 infrastructure 现在是机器部署条目的直接子项。

之前：

workers:
  machineDeployments:
    - class: default-worker
      template:
        bootstrap:
          ref:
            apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
            kind: KubeadmConfigTemplate
            name: my-bootstrap-template
        infrastructure:
          ref:
            apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
            kind: DockerMachineTemplate
            name: my-worker-template

此时间后：

workers:
  machineDeployments:
    - class: default-worker
      bootstrap:
        templateRef:
          apiVersion: bootstrap.cluster.x-k8s.io/v1beta2
          kind: KubeadmConfigTemplate
          name: my-bootstrap-template
      infrastructure:
        templateRef:
          apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
          kind: DockerMachineTemplate
          name: my-worker-template

群集

Cluster 资源现在通过结构化对象而不是内联字符串引用其 ClusterClass。在 v1beta1 中，类名和名称空间被指定为 spec.topology.class 和 spec.topology.classNamespace。在 v1beta2 中，这两个字段被一个单一的 spec.topology.classRef 对象替代。

之前：

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
spec:
  topology:
    class: my-clusterclass
    classNamespace: capi-system

此时间后：

apiVersion: cluster.x-k8s.io/v1beta2
kind: Cluster
spec:
  topology:
    classRef:
      name: my-clusterclass
      namespace: capi-system

其余的 Cluster 规格（网络设置、controlPlane.replicas、workers.machineDeployments、variables、version 等）保持不变。

RKE2 提供者（CAPRKE2）

此版本发布了 CAPRKE2 v0.23.1，升级自 v0.22.1。RKE2 启动和控制平面资源的 v1beta2 API 在 v0.22.0 中引入，并支持 CAPI v1.11，而 v0.23.0 通过升级到 CAPI v1.12.2 完成了这项工作。v0.22.1和v0.23.1都是在各自小版本之上的补丁版本。

注意：请阅读提供者文档，了解来自 CAPI 提供者 RKE2 书籍 的 API 更改。

新的v1beta2 API

CAPRKE2 现在提供自己的 v1beta2 API，用于 RKE2ControlPlane、RKE2ControlPlaneTemplate 和 RKE2Config/RKE2ConfigTemplate。v1beta1 API 仍然可用，但在 v1beta1 中标记为弃用的几个字段现在在 v1beta2 中被删除。

RKE2ControlPlane中删除的字段

以下字段已从 RKE2ControlPlane.spec 中删除，在 v1beta2 版本中：

  • infrastructureRef — 请改用 spec.machineTemplate.spec.infrastructureRef。

  • nodeDrainTimeout — 请改用 spec.machineTemplate.spec.deletion.nodeDrainTimeout。

重命名超时字段

RKE2ControlPlaneMachineTemplate 中的超时字段已移动到 deletion 子对象下并重命名。它们的类型也已从 metav1.Duration 更改为 int32，现在期望的值以秒为单位，而不是持续时间字符串。

v1beta1 v1beta2

nodeDrainTimeout

deletion.nodeDrainTimeoutSeconds

nodeVolumeDetachTimeout

deletion.nodeVolumeDetachTimeoutSeconds

nodeDeletionTimeout

deletion.nodeDeletionTimeoutSeconds

RKE2ControlPlaneMachineTemplate 对象现在也需要一个 spec 字段。

v1alpha1 废弃

在 CAPRKE2 v0.22.0 中，v1alpha1 API 已被废弃。如果您仍在使用 v1alpha1 资源，现在是迁移到至少 v1beta1 的好时机。

升级前建议采取的步骤

  1. 更新您维护的任何 ClusterClass 清单：将 ref 重命名为 templateRef，在工作器部分中移除 template 封装程序，并将 CAPI 内核的 apiVersion 字符串更新为 v1beta2。

  2. 更新任何 Cluster 清单：将 spec.topology.class 和 spec.topology.classNamespace 替换为 spec.topology.classRef.name 和 spec.topology.classRef.namespace。

  3. 如果您使用 CAPRKE2 v1beta2 资源，请从 RKE2ControlPlane.spec 中移除任何直接的 infrastructureRef 或 nodeDrainTimeout 字段，并将它们移动到 spec.machineTemplate.spec。

  4. 查看 examples/clusterclasses/ 中的更新示例，以获取每个认证 CAPI 提供者的完整、有效的清单。