将 Tanzu Kubernetes 集群规范自动转换为 v1alpha2 API 格式后，要对 Tanzu Kubernetes 集群执行滚动更新（通常通过更改 Tanzu Kubernetes 发行版本完成），可能需要对集群规范进行一些预处理以避免出现错误。

集群规范的自动转换

要将 vSphere with Tanzu 环境更新为 Tanzu Kubernetes Grid 服务 v1alpha2 API，请更新运行服务的 主管集群。

在 Tanzu Kubernetes Grid 服务 运行 v1alpha2 API 后，系统会自动将所有现有的 Tanzu Kubernetes 集群规范从 v1alpha1 格式转换为 v1alpha2 格式。在自动转换过程中，系统会为每个集群清单创建并填充所需字段。API 弃用设置和新增设置列出了 v1alpha2 API 中新增和弃用的集群规范字段。

要更新清单已自动转换为 v1alpha2 格式的集群的 Tanzu Kubernetes 发行版本，需要执行一些手动预处理以避免错误。集群更新示例列出了各种选项。

API 弃用设置和新增设置

下表列出了 v1alpha2 API 中已弃用并替换为新设置的集群规范设置。
弃用设置 新增设置 备注

spec.distribution.version

spec.distribution.fullVersion

spec.topology.controlPlane.tkr.refernece.name

spec.topology.nodePools[*].tkr.reference.name

必须使用 TKR NAME 格式。请参见示例。

spec.topology.workers

spec.topology.nodePools[*]

 在转换后的集群中，块 spec.topology.workers 将变为 spec.topology.nodePools[0]。

nodePools 列表中的第一个条目是 name: workers。

spec.topology.controlPlane.count

spec.topology.workers.count

spec.topology.controlPlane.replicas

spec.topology.nodePools[*].replicas

 count 将替换为 replicas

spec.topology.controlPlane.class

spec.topology.workers.class

spec.topology.controlPlane.vmClass

spec.topology.nodePools[*].vmClass

 class 将替换为 vmClass

不适用

spec.topology.nodePools[*].labels

用于对象和分类组织的可选密钥对值；标签将传播到创建的节点

不适用

spec.topology.nodePools[*].taints

用于注册节点的可选污点；用户定义的污点将传播到创建的节点

需要 TKR NAME 格式

除了 spec.distribution.version 字段已弃用外，用于指定 Tanzu Kubernetes 发行版本的 DISTRIBUTION 格式也不再受支持。这意味着不能使用以下字符串格式引用目标版本：1.21.2+vmware.1-tkg.1.ee25d55、1.21.2 和 1.21。

在 v1alpha2 API 集群规范中引用 Tanzu Kubernetes 发行版本时，必须使用 TKR NAME 格式，而不是弃用的 DISTRIBUTION 格式。尽管已弃用的格式显示在 UPDATES AVAILABLE 列中，但唯一支持的格式是 TKR NAME 列中列出的格式。 
kubectl get tanzukubernetescluster
NAMESPACE        NAME            CONTROL PLANE   WORKER   TKR NAME                             AGE    READY   TKR COMPATIBLE   UPDATES AVAILABLE
tkgs-cluster-1   test-cluster    3               3        v1.21.2---vmware.1-tkg.1.ee25d55     38h    True    True             [1.21.2+vmware.1-tkg.1.ee25d55]

使用 kubectl edit 更新集群规范

如果需要对集群规范进行编辑，使其符合 TKGS v1alpha2 API，请使用 kubectl edit 方法。请勿尝试对此类型的更新使用 kubectl patch 方法。请参见编辑集群清单的方法。要使用编辑器配置 kubectl，请参见为 Kubectl 指定默认的文本编辑器。

集群更新示例

由于更改 spec.distribution.version 是触发集群滚动更新的最常见方法（请参见更新 Tanzu Kubernetes 集群），并且此字段在 v1alpha2 API 中已弃用，因此需要注意一些事项并遵循一些预处理建议，以避免潜在的集群升级问题。

以下示例说明了如何将使用 v1alpha1 API 置备的 Tanzu Kubernetes 集群版本更新为运行 v1alpha2 API 的系统。

集群升级示例 1：在控制平面中使用单个 TKR NAME 引用

建议的方法是从转换后的规范中移除所有 nodePools[*].tkr.reference.name 块，并将 controlPlane.tkr.reference.name 更新为目标版本的 TKR NAME。在这种情况下，相同的 Tanzu Kubernetes 版本将传播到所有 nodePools[*] 节点。

将来，Tanzu Kubernetes 发行版本在 controlPlane 和 nodePools[*] 之间可以有所不同。但是，目前，集群中的所有版本都必须匹配，因此在 controlPlane 中放置一个 TKR NAME 引用就足够了。

例如： 
apiVersion: run.tanzu.vmware.com/v1alpha2
kind: TanzuKubernetesCluster
metadata:
  name: tkgs-cluster-update-example1
  namespace: tkgs-cluster-ns
spec:
  settings:
    network:
      cni:
        name: antrea
      pods:
        cidrBlocks:
        - 192.0.2.0/16
      serviceDomain: cluster.local
      services:
        cidrBlocks:
        - 198.51.100.0/12
  topology:
    controlPlane:
      replicas: 3
      storageClass: vwt-storage-policy
      tkr:
        reference:
          name: v1.21.2---vmware.1-tkg.1.ee25d55
      vmClass: best-effort-medium
    nodePools:
    - name: workers
      replicas: 3
      storageClass: vwt-storage-policy
      vmClass: best-effort-medium

集群升级示例 2：对每个节点池使用 TKR NAME 引用

第二个示例是将 TKR NAME 放在 controlPlane 和 nodePools[*] 拓扑的 tkr.reference.name 块中。

此方法的优点是，可以为未来版本做好准备，届时，Tanzu Kubernetes 版本在节点池之间可以有所不同。目前，它们必须匹配。

例如： 
apiVersion: run.tanzu.vmware.com/v1alpha2
kind: TanzuKubernetesCluster
metadata:
  name: tkgs-cluster-update-example2
  namespace: tkgs-cluster-ns
spec:
  settings:
    network:
      cni:
        name: antrea
      pods:
        cidrBlocks:
        - 192.0.2.0/16
      serviceDomain: cluster.local
      services:
        cidrBlocks:
        - 198.51.100.0/12
  topology:
    controlPlane:
      replicas: 3
      storageClass: vwt-storage-policy
      vmClass: best-effort-medium
      tkr:
        reference:
          name: v1.21.2---vmware.1-tkg.1.ee25d55
    nodePools:
    - name: workers
      replicas: 3
      storageClass: vwt-storage-policy
      vmClass: best-effort-medium
      tkr:
        reference:
          name: v1.21.2---vmware.1-tkg.1.ee25d55

集群升级示例 3：使用已弃用的分发字段

最后一个选择方案是使用已弃用的字段 spec.distribution.fullVersion 和 spec.distribution.version，并手动移除所有 tkr.reference.name 块。必须同时包含这两个字段，其中一个字段使用 TKR NAME 格式，另一个为空。不支持版本快捷方式，如 v1.21.2 和 v1.21。
注： 对于 Ubuntu 上的 Tanzu Kubernetes 版本，不支持使用 spec.distribution.version。
以下示例对 fullVersion 使用 TKR NAME，对 version 字段使用空值。移除所有 tkr.reference.name 条目。 
apiVersion: run.tanzu.vmware.com/v1alpha2
kind: TanzuKubernetesCluster
metadata:
  name: tkgs-cluster-update-example3a
  namespace: tkgs-cluster-ns
spec:
  distribution:
    fullVersion: v1.21.2---vmware.1-tkg.1.ee25d55
    version: ""
  settings:
    network:
      cni:
        name: antrea
      pods:
        cidrBlocks:
        - 192.0.2.0/16
      serviceDomain: cluster.local
      services:
        cidrBlocks:
        - 198.51.100.0/12
  topology:
    controlPlane:
      replicas: 3
      storageClass: vwt-storage-policy
      vmClass: best-effort-medium
    nodePools:
    - name: workers
      replicas: 3
      storageClass: vwt-storage-policy
      vmClass: best-effort-medium
或者，也可以对 version 字段使用 TKR NAME，对 fullVersion 字段使用空值。即使使用 version 字段，也不支持版本快捷方式。移除所有 tkr.reference.name 条目。 
apiVersion: run.tanzu.vmware.com/v1alpha2
kind: TanzuKubernetesCluster
metadata:
  name: tkgs-cluster-update-example3b
  namespace: tkgs-cluster-ns
spec:
  distribution:
    fullVersion: ""
    version: v1.21.2---vmware.1-tkg.1.ee25d55
  settings:
    network:
      cni:
        name: antrea
      pods:
        cidrBlocks:
        - 192.0.2.0/16
      serviceDomain: cluster.local
      services:
        cidrBlocks:
        - 198.51.100.0/12
  topology:
    controlPlane:
      replicas: 3
      storageClass: vwt-storage-policy
      vmClass: best-effort-medium
    nodePools:
    - name: workers
      replicas: 3
      storageClass: vwt-storage-policy
      vmClass: best-effort-medium