集群 v1beta1 API

通过集群 v1beta1 API，您可以基于默认的 ClusterClass 定义置备集群。

ClusterClass API v1beta1

Kubernetes 集群 API 是一套用于提供 Kubernetes 集群的声明式置备、升级和操作的工具。ClusterClass 是集群 API 的升级版，可用于定义管理集群集生命周期的模板。主管 上的 TKG 2 通过 v1beta1 API 支持 ClusterClass。

主管 上的 TKG 2 附带一个名为 tanzukubernetescluster 的默认 ClusterClass 定义。tanzukubernetescluster ClusterClass 为通过 v1beta API 在 主管 上创建 TKG 2 集群提供了一个模板。tanzukubernetescluster ClusterClass 在所有用户命名空间中均可用。要基于此 ClusterClass 创建集群，请在集群规范中引用它。有关指导，请参阅 v1beta 示例。

默认的 ClusterClass tanzukubernetescluster

默认的 tanzukubernetescluster ClusterClass 不可改变。此处，它仅作为参考提供。

apiVersion: cluster.x-k8s.io/v1beta1
kind: ClusterClass
metadata:
  name: tanzukubernetescluster
  annotations:
    run.tanzu.vmware.com/resolve-tkr: ""
spec:
  controlPlane:
    metadata:
      annotations:
        run.tanzu.vmware.com/resolve-os-image: os-name=photon
    ref:
      apiVersion: controlplane.cluster.x-k8s.io/v1beta1
      kind: KubeadmControlPlaneTemplate
      name: "tkc-control-plane"
    machineInfrastructure:
      ref:
        kind: VSphereMachineTemplate
        apiVersion: vmware.infrastructure.cluster.x-k8s.io/v1beta1
        name: "tkc-control-plane"
    machineHealthCheck:
      maxUnhealthy: 100%
      nodeStartupTimeout: 2h0m0s
      unhealthyConditions:
        - status: Unknown
          timeout: 5m0s
          type: Ready
        - status: "False"
          timeout: 12m0s
          type: Ready
  infrastructure:
    ref:
      apiVersion: vmware.infrastructure.cluster.x-k8s.io/v1beta1
      kind: VSphereClusterTemplate
      name: "tkc-infrastructure"
  workers:
    machineDeployments:
      - class: node-pool  
        template:
          metadata:
            annotations:
              run.tanzu.vmware.com/resolve-os-image: os-name=photon            
          bootstrap:
            ref:
              kind: KubeadmConfigTemplate
              apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
              name: "tkc-md"
          infrastructure:
            ref:
              kind: VSphereMachineTemplate
              apiVersion: vmware.infrastructure.cluster.x-k8s.io/v1beta1
              name: "tkc-md"
        machineHealthCheck:
          maxUnhealthy: 100%
          nodeStartupTimeout: 2h0m0s
          unhealthyConditions:
            - status: Unknown
              timeout: 5m0s
              type: Ready
            - status: "False"
              timeout: 12m0s
              type: Ready
  variables:
    - name: TKR_DATA
      required: false
      schema:
        openAPIV3Schema:
          type: object
          additionalProperties:
            type: object
            properties:
              kubernetesSpec:
                type: object
                properties:
                  version:
                    type: string
                  imageRepository:
                    type: string
                  etcd:
                    type: object
                    properties:
                      imageTag:
                        type: string
                  coredns:
                    type: object
                    properties:
                      imageTag:
                        type: string
              osImageRef:
                type: object
                properties:
                  name:
                    type: string
              labels:
                type: object
                additionalProperties:
                  type: string
    - name: vmClass
      required: true
      schema:
        openAPIV3Schema:
          type: string
    - name: storageClass
      required: true
      schema:
        openAPIV3Schema:
          type: string
    - name: storageClasses
      required: false
      schema:
        openAPIV3Schema:
          type: array
          items:
            type: string
    - name: defaultStorageClass
      required: false
      schema:
        openAPIV3Schema:
          type: string
    - name: extensionCert
      required: false
      schema:
        openAPIV3Schema:
          type: object
          properties:
            contentSecret:
              type: object
              properties:
                name:
                  type: string
                key:
                  type: string
    - name: clusterEncryptionConfigYaml
      required: false
      schema:
        openAPIV3Schema:
          type: string
    - name: defaultRegistrySecret
      required: false
      schema:
        openAPIV3Schema:
          type: object
          properties:
            namespace:
              type: string
            name:
              type: string
            data:
              type: string
    - name: ntp
      required: false
      schema:
        openAPIV3Schema:
          type: string
    - name: user
      required: false
      schema:
        openAPIV3Schema:
          type: object
          properties:
            passwordSecret:
              type: object
              properties:
                name:
                  type: string
                key:
                  type: string
            sshAuthorizedKey:
              type: string
    - name: nodePoolTaints
      required: false
      schema:
        openAPIV3Schema:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
              effect:
                type: string
              timeAdded:
                type: integer
    - name: nodePoolLabels
      required: false
      schema:
        openAPIV3Schema:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
    - name: proxy
      required: false
      schema:
        openAPIV3Schema:
          type: object
          properties:
            httpProxy:
              type: string
            httpsProxy:
              type: string
            noProxy:
              type: array
              items:
                type: string
    - name: trust
      required: false
      schema:
        openAPIV3Schema:
          type: object
          properties:
            additionalTrustedCAs:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
    - name: controlPlaneVolumes
      required: false
      schema:
        openAPIV3Schema:
          type: array
          items:
            type: object
            properties:
              storageClass:
                type: string
              mountPath:
                type: string
              name:
                type: string
              capacity:
                type: object
                properties:
                  storage:
                    type: string                   
    - name: nodePoolVolumes
      required: false
      schema:
        openAPIV3Schema:
          type: array
          items:
            type: object
            properties:
              storageClass:
                type: string
              mountPath:
                type: string
              name:
                type: string
              capacity:
                type: object
                properties:
                  storage:
                    type: string

用于自定义集群的 ClusterClass 变量

您可以使用变量基于 tanzukubernetescluster ClusterClass 自定义一个集群。变量使用名称-值对进行定义。语法必须符合 openAPIV3Schema 的要求。

使用 v1beta1 API 置备集群需要两个变量：

• 虚拟机类
• 存储类

还可以使用其他变量来自定义集群，例如：

• 代理
• TLS 证书
• SSH 密钥

以下部分列出了默认 tanzukubernetescluster ClusterClass 可用的所有变量。

clusterEncryptionConfigYaml

使用 clusterEncryptionConfigYaml 变量配置集群加密。

clusterEncryptionConfigYaml

一个字符串，表示提供加密配置详细信息的 YAML 文件。

您可以使用 kube-apiserver 加密配置软件包配置对 etcd 数据库数据的加密。请参见 Kubernetes 文档中的 加密静态密钥数据。

...
    variables:
    #clusterEncryptionConfigYaml specifies the base64 encoded 
    #EncryptionConfiguration YAML
    #the YAML contains a base64 encryption configuration for the cluster identity
    #the key is generated randomly
    - name: clusterEncryptionConfigYaml
      value: string which is name of the EncryptionConfiguration YAML 

controlPlaneVolumes

使用 controlPlaneVolumes 变量为控制平面节点配置持久卷。

controlPlaneVolumes

一个可选对象数组，其中每个对象都包括 name、 storageClass 和 mountPath（均为字符串），以及一个可选的 capacity 对象，其中包含 storage 字符串。

...
    variables:
      #controlPlaneVolumes is an optional set of PVCs to create and
      #attach to each node; use for high-churn components like etcd
      - name: controlPlaneVolumes
        value: |
          #name of the PVC to be used as the suffix (node.name)
          - name: etcd
            #mountPath is the directory where the volume device is mounted
            #takes the form /dir/path
            mountPath: /var/lib/etcd
            #storageClass is the storage class to use for the PVC
            storageClass: tkg2-storage-profile
            #capacity is the PVC storage capacity
            capacity:
              #storage sets the capacity for the disk volume
              #if not specified defaults to storageClass capacity
              storage: 4Gi           

defaultRegistrySecret

使用 defaultRegistrySecret 变量为集群配置默认的容器注册表。

defaultRegistrySecret

一个对象，此对象包含默认容器注册表的公钥、证书名称和命名空间。

如果在 主管 上启用 Harbor 注册表，则 defaultRegistrySecret 变量将指定集群信任的注册表服务证书。证书密钥标有 managed-by: vmware-vRegistry。创建集群时，系统会将 defaultRegistry 证书插入到 defaultRegistrySecret 变量中。创建集群后，您可以通过手动更新此变量来管理证书轮换或任何更新。

...
    variables:
    - name: defaultRegistrySecret
      value:
        #data holds the base64 encoded data.ca\.crt content
        #data.ca\.crt is already encoded, so raw cert data is encoded twice
        data: LS0tLS1CRUdJTiBDRVJU...S0tRU5EIENFUlRJRklDQVRFL
        #name specifies the name of the registry cert secret 
        name: harbor-ca-key-pair
        #namespace specifies the ns of the registry cert secret
        namespace: svc-harbor-domain-c9

defaultStorageClass

使用 defaultStorageClass 变量为集群配置默认存储类。

defaultStorageClass

一个字符串，此字符串用于标识要用作默认存储类的存储类，通常，Helm 图表和 Tanzu 软件包等应用程序需要它。

...
    variables:
    - name: defaultStorageClass
      value: tkg2-storage-profile

extensionCert

使用 extensionCert 变量配置 TLS 证书。

extensionCert

一个对象，此对象包含具有 name 和 key 字符串的 contentSecret 对象。 contentSecret 引用为 TLS 证书创建的 Kubernetes 密钥对象。

...
    variables:
    #extensionCert specifies the cert and key for Extensions Controller
    #self-signed issuer and certificates must be created in advance
    - name: extensionCert
      value: 
        contentSecret:
          #name specifies the name of secret
          name: string
          #key specifies the content of tls\.crt in the secret's data map
          key: string

nodePoolLabels

使用 nodePoolLabels 变量为工作节点配置标签。

nodePoolLabels

一个或多个对象组成的数组，其中每个对象都包含一个键/值（均为字符串）对。

通过标签，您可以根据自己的需要组织系统对象，以便于查询和报告。有关用法详情，请参阅 Kubernetes 标签文档。

nodePoolTaints

使用 nodePoolTaints 变量将污点应用于工作节点。

nodePoolTaints

一个对象数组，其中每个对象都包含一个适用于工作节点的 污点。

每个污点对象都包括一个 key（字符串）、一个 value（字符串）和一个 effect（字符串）。系统会在创建或更新时填充 timeAdded 字段。

nodePoolVolumes

使用 nodePoolVolumes 变量为集群节点指定持久卷。

nodePoolVolumes

一个可选对象数组，其中每个对象都包括 name、 storageClass 和 mountPath（均为字符串），以及一个可选的 capacity 对象，其中包含 storage 字符串。

...
    variables:
      #nodePoolVolumes is an optional set of PVCs to create and
      #attach to each node; use for high-churn components like containerd
      - name: nodePoolVolumes
        value: |
          #name of the PVC to be used as the suffix (node.name)
          - name: etcd
            #mountPath is the directory where the volume device is mounted
            #takes the form /dir/path
            mountPath: /var/lib/containerd
            #storageClass is the storage class to use for the PVC
            storageClass: tkg2-storage-profile
            #capacity is the PVC storage capacity
            capacity:
              #storage sets the capacity for the disk volume
              #if not specified defaults to storageClass capacity
              storage: 4Gi           

ntp

使用 ntp 变量为集群配置 NTP 服务器。

ntp

一个字符串，表示 NTP 服务器的 FQDN 或 IP 地址。

NTP 变量用于指定 NTP 服务器的域名，如示例中所示。NTP 服务器会在创建集群时插入到集群变量中。创建集群后，您可以通过手动更新此集群变量来管理服务器名称轮换或任何更新。

...
    variables:
    - name: ntp
      value: time1.vmware.com

代理

使用 proxy 变量为集群配置代理服务器。

代理

一个对象，其参数可引用出站集群连接的代理服务器。

必需的 proxy 参数为 httpProxy、 httpsProxy 和 noProxy。如果要在集群定义中包含 proxy 变量，则必须提供这三个字段。

字段 httpProxy 和 httpsProxy 会接受相应字符串值，以引用某个代理服务器的 URI，该代理服务器会配置为管理 TKG 集群的出站 HTTP 和 HTTPS 连接。您可以使用 HTTP 连接到代理服务器。不支持 HTTPS 连接。

noProxy 字段是一个字符串数组。从 主管 工作负载网络获取 noProxy 值。您必须在 noProxy 字段中包含命名空间网络、输入和输出子网。

无需在 noProxy 字段中包含服务子网。TKG 集群不与此子网交互。

无需在 noProxy 字段中包括 clusterNetwork.services.cidrBlocks 和 clusterNetwork.pods.cidrBlocks。系统不会自动代理这些端点。

无需在 noProxy 字段中包括 localhost 和 127.0.0.1。系统不会自动代理这些端点。

...
    variables:
    #proxy specifies a proxy server to be used for the cluster
    #if omitted no proxy is configured
    - name: proxy
      value:
        #httpProxy is the proxy URI for HTTP connections
        #to endpoints outside the cluster
        httpProxy: http://<user>:<pwd>@<ip>:<port>
        #httpsProxy is the proxy URL for HTTPS connections 
        #to endpoints outside the cluster
        httpsProxy: http://<user>:<pwd>@<ip>:<port>
        #noProxy is the list of destination domain names, domains, 
        #IP addresses, and other network CIDRs to exclude from proxying
        #must include Supervisor Pod, Egress, Ingress CIDRs
        noProxy: [array of strings, comma-separated]

storageClass

使用 storageClass 变量为集群配置存储类。

storageClass

一个字符串，此字符串是已分配给置备了 TKG 集群的 vSphere 命名空间 的 vSphere 存储配置文件的名称。

...
    variables:
    - name: storageClass
      value: tkg2-storage-profile 

使用以下命令列出可用的存储类：

kubectl describe namespace VSPHERE-NAMESPACE-NAME

或者，如果您具有 vSphere 管理员权限：

kubectl describe storageclasses

storageClasses

使用 storageClasses 变量为集群配置存储类阵列。

storageClasses

一个或多个字符串组成的数组，每个字符串都是已分配给置备了 TKG 集群的 vSphere 命名空间 的 vSphere 存储配置文件的名称。

...
    variables:
    - name: storageClasses
      value: [tkg2-storage-profile, tkg2-storage-profile-latebinding] 

使用以下命令列出可用的存储类：

kubectl describe namespace VSPHERE-NAMESPACE-NAME

或者，如果您具有 vSphere 管理员权限：

kubectl describe storageclasses

TKR_DATA

使用 TKR_DATA 变量指定 TKR 信息。

TKR_DATA

用于指定 TKR 版本和其他详细信息的对象。

version 是一个由集群节点使用的字符串，采用 TKR NAME 格式。

只有不具备 legacy-tkr 标签的 TKR 才与 TKG 2 兼容。请参见 将 Tanzu Kubernetes 版本与 主管 上的 TKG 2 集群配合使用。

默认操作系统为 PhotonOS。使用注释指定 Ubuntu TKR。

trust

使用 trust 变量为集群指定一个或多个受信任的 CA 证书。

trust

一个对象，用于向集群添加 TLS 证书（其他 CA 证书或终端证书）。

此值为 additionalTrustedCAs，它是一个字符串数组。其中每个字符串都是 Kubernetes 密钥的名称，该密钥包含以 PEM 格式 base64 编码字符串形式表示的其他受信任证书的内容。

要配置 trust 变量，请执行以下操作：

1. 使用以下内容创建 Kubernetes 密钥定义 YAML 文件。

   apiVersion: v1
   data:
     additional-ca-1: TFMwdExTMUNSGlSzZ3Jaa...VVNVWkpRMEMwdExTMHRDZz09
   kind: Secret
   metadata:
     name: cluster01-user-trusted-ca-secret
     namespace: tkg2-cluster-ns
   type: Opaque

   密钥数据映射的内容是一个由用户定义的证书名称 ( additional-ca-1)，其值为双 base64 编码的证书。

   注： 需要使用双 base64 编码。如果数据映射值的内容没有使用双 base6 编码，则无法处理生成的 PEM 文件。

   将此密钥命名为 CLUSTER-NAME-user-trusted-ca-secret，其中 CLUSTER-NAME 是集群的名称。必须在集群所在的同一 vSphere 命名空间 中创建此密钥。

2. 使用 kubectl -f apply additional-ca-1.yaml 创建 Kubernetes 密钥。
3. 验证密钥创建。

   kubeclt get secret -n tkg2-cluster-ns cluster01-user-trusted-ca-secret
   NAME                                             TYPE     DATA   AGE
   cluster01-user-trusted-ca-secret                   Opaque   12     2d22h
   

4. 将 trust 变量包含在集群规范中，用于引用此密钥的数据映射的 name 值（在此示例中为 additional-ca-1）。

   spec:
     clusterNetwork:
       pods:
         cidrBlocks:
         - 193.0.0.0/16
       serviceDomain: cluster.local
       services:
         cidrBlocks:
         - 198.201.0.0/16
     topology:
       class: tanzukubernetescluster
       controlPlane:
         metadata: {}
         replicas: 3
       variables:
       - name: storageClass
         value: tkg2-storage-profile
       - name: trust
         value:
           additionalTrustedCAs:
           - name: additional-ca-1

user

使用 user 变量指定集群用户凭据。

user

一个对象，此对象包含具有名称和密钥字符串以及 sshAuthorizedKey 字符串的 passwordSecret 对象。您可以使用此变量将用户的 SSH 密钥添加到集群节点中以进行远程 SSH 访问。

此用户变量用于指定 SSH 登录凭据，包括密码和授权密钥。默认情况下，用户名为 vmware-system-user。密码需要进行哈希处理，并存储在置备了此集群的命名空间的一个密钥中。 passwordSecret 对象用于引用此密钥。例如，在 Linux 上，您可以使用 mkpasswd --method=SHA-512 --rounds=4096 生成安全哈希。有关详细信息，请参见 包括用户和组。

...
    variables:
    #user specifies an authorized user and credentials
    - name: user
      value:
        #passwordSecret is an object that contains a Kubernetes secret and key
        passwordSecret:
          #name specifies the secret name
          name: string
          #key specifies the key value pair in the secret's data map
          key: string
        sshAuthorizedKey: string that is the base64-encoded public key

vmClass

使用 vmClass 变量为集群节点配置虚拟机类。

vmClass

一个必需字符串，此字符串将映射到与置备了 TKG 集群的 vSphere 命名空间 绑定的虚拟机类的名称。

vmClass 是 VirtualMachineClass 的名称，描述集群节点要使用的虚拟硬件设置。VirtualMachineClass 用于控制节点可用的 CPU 和内存，以及对这些资源的请求和限制。请参见 对主管上的 TKG 2 集群使用虚拟机类。

只能使用那些与正在置备 TKG 集群的 vSphere 命名空间 绑定的虚拟机类。使用命令 kubectl get virtualmachineclassbinding 列出绑定类。

您可以在不同的范围定义 vmClass 变量，以便对控制平面节点和节点池工作节点使用不同的虚拟机类。

例如，此处的内嵌 vmClass 变量 overrides 是此特定 machineDeployment 拓扑的主 vmClass 变量。

...
    workers:
      machineDeployments:
      - class: tkg-worker
        name: compute
        replicas: 3
        variables:
          overrides:
          - name: vmClass
            value: guaranteed-large