建立 ClusterClass

本主題說明如何建立您自己的自訂 ClusterClass 資源定義,並根據該資源定義,來建立以類別為基礎的工作負載叢集,且其具有 Tanzu Kubernetes Grid (TKG) 獨立管理叢集。若要使叢集以 ClusterClass 為基礎,請將其 spec.topology.class 設定為 ClusterClass 名稱。

此程序不適用於具有 vSphere with Tanzu 主管的 TKG。

重要

建立自訂的 ClusterClass 資源定義適用於進階使用者。VMware 不保證以任意的 ClusterClass 物件為基礎的工作負載叢集的功能。要使用預設 ClusterClass 資源建立工作負載叢集,請按照叢集部署步驟中的程序操作。

需求

若要建立 ClusterClass 定義,需要在本機安裝以下工具:

工具 版本
clusterctl v1.2.0
ytt 0.42.0
jq 1.5-1
yq v4.30.5

選項: 覆疊與新物件規格

若要建立新的 ClusterClass,VMware 建議從 ClusterClass 物件來源下連結的現有預設 ClusterClass 物件開始,然後使用 ytt 覆疊對其進行修改。發佈新版本的預設 ClusterClass 物件時,可以將覆疊套用至該新版本,以便實作相同的自訂。以下程序說明了這種建立自訂 ClusterClass 物件的方法。

若要從無物件寫入新的 ClusterClass 物件,請依照叢集 API 說明文件中的寫入 ClusterClass 進行操作。

建立自訂 ClusterClass 物件

若要根據 Tanzu Framework 存放庫中定義的現有 ClusterClass,來建立自訂 ClusterClass 物件定義,請執行以下動作:

擷取 ClusterClass 物件來源

  1. 從 Github 上的 Tanzu Framework 程式碼存放庫中,下載並解壓縮 v0.28.1 zip 服務包。

  2. 根據您的目標基礎結構,將 cd 複製到存放庫的 package 子目錄:

    • AWSpackages/tkg-clusterclass-aws
    • Azurepackages/tkg-clusterclass-azure
    • vSpherepackages/tkg-clusterclass-vsphere
  3. bundle 資料夾複製到工作區。它具有下列結構:

    $ tree bundle
    bundle
    |-- config
       |-- upstream
       │   |-- base.yaml
       │   |-- overlay-kube-apiserver-admission.yaml
       │   |-- overlay.yaml
       |-- values.yaml
    

產生基本 ClusterClass 資訊清單

  1. 根據是否已部署獨立管理叢集,在值檔案中擷取基礎結構設定,如下所示:

    • 已部署管理叢集執行以下命令以產生 default-values.yaml

      cat <<EOF > default_values.yaml
      #@data/values
      
      #@overlay/match-child-defaults missing_ok=True
      ---
      EOF
      kubectl get secret tkg-clusterclass-infra-values -o jsonpath='{.data.values\.yaml}' -n tkg-system | base64 -d >> default_values.yaml
      
    • 無獨立管理叢集

      1. bundle 目錄中,將 values.yaml 複製到新檔 default_values.yaml
      cp bundle/config/values.yaml default_values.yaml
      
      1. 編輯 default_values.yaml,然後根據您的基礎結構填寫變數設定,例如:
      VSPHERE_DATACENTER: /dc0
      VSPHERE_DATASTORE: /dc0/datastore/sharedVmfs-0
      VSPHERE_FOLDER: /dc0/vm
      

      有關基礎結構特定的變數,請參閱組態檔變數參考

  2. 透過值檔案產生基本 ClusterClass 資訊清單:

    ytt -f bundle -f default_values.yaml > default_cc.yaml
    

自訂 ClusterClass 資訊清單

若要自訂 ClusterClass 資訊清單,請在該資訊清單旁建立 ytt 覆疊檔。以下範例顯示了如何在 ClusterClass 定義中修改 Linux 核心參數。

  1. 建立 custom 資料夾,結構如下所示:

    $ tree custom
     custom
     |-- overlays
     |   -- kernels.yaml
     -- values.yaml
    
  2. 例如,編輯 custom/overlays/kernels.yaml 以將 nfConntrackMax 新增為變數,然後為其定義一個修補程式,該修補程式將新增控制平面節點的核心參數 net.netfilter.nf_conntrack_max 值。

    此覆疊在 preKubeadmCommands 欄位附加一個命令,以將組態寫入到 sysctl.conf。若要使設定生效,可以附加命令 sysctl -p 以套用此變更。

    #@ load("@ytt:overlay", "overlay")
    #@ load("@ytt:data", "data")
    
    #@overlay/match by=overlay.subset({"kind":"ClusterClass"})
    ---
    apiVersion: cluster.x-k8s.io/v1beta1
    kind: ClusterClass
    spec:
      variables:
      - name: nfConntrackMax
        required: false
        schema:
          openAPIV3Schema:
            type: string
      patches:
      - name: nfConntrackMax
        enabledIf: '{{ not (empty .nfConntrackMax) }}'
        definitions:
          - selector:
              apiVersion: controlplane.cluster.x-k8s.io/v1beta1
              kind: KubeadmControlPlaneTemplate
              matchResources:
                controlPlane: true
            jsonPatches:
              - op: add
                path: /spec/template/spec/kubeadmConfigSpec/preKubeadmCommands/-
                valueFrom:
                  template: echo "net.netfilter.nf_conntrack_max={{ .nfConntrackMax }}" >> /etc/sysctl.conf
    
  3. 預設 ClusterClass 定義不可改變,因此建立或編輯 custom/values.yaml 覆疊,透過新增 -extended 和版本來變更自訂 ClusterClass 的名稱及其所有範本,例如:

    #@data/values
    
    #@overlay/match-child-defaults missing_ok=True
    ---
    #! Change the suffix so we know from which default ClusterClass it is extended
    CC-VERSION: extended-v1.0.0
    
    #! Add other variables below if necessary
    

    其中,CC-VERSION 是叢集類別版本的名稱,例如 VSPHERE_CLUSTER_CLASS_VERSION

  4. 產生自訂 ClusterClass:

    ytt -f bundle -f default_values.yaml -f custom > custom_cc.yaml
    
  5. (選用) 檢查預設 ClusterClass 與自訂名稱之間的差異,以確認所有名稱都具有尾碼 -extended 並新增了新的變數和 JSON 修補程式,例如:

    $ diff default_cc.yaml custom_cc.yaml
    4c4
    <   name: tkg-vsphere-default-v1.0.0-cluster
    ---
    >   name: tkg-vsphere-default-extended-v1.0.0-cluster
    15c15
    <   name: tkg-vsphere-default-v1.0.0-control-plane
    ---
    >   name: tkg-vsphere-default-extended-v1.0.0-control-plane
    39c39
    <   name: tkg-vsphere-default-v1.0.0-worker
    ---
    >   name: tkg-vsphere-default-extended-v1.0.0-worker
    63c63
    <   name: tkg-vsphere-default-v1.0.0-kcp
    ---
    >   name: tkg-vsphere-default-extended-v1.0.0-kcp
    129c129
    <   name: tkg-vsphere-default-v1.0.0-md-config
    ---
    >   name: tkg-vsphere-default-extended-v1.0.0-md-config
    165c165
    <   name: tkg-vsphere-default-v1.0.0
    ---
    >   name: tkg-vsphere-default-extended-v1.0.0
    174c174
    <       name: tkg-vsphere-default-v1.0.0-kcp
    ---
    >       name: tkg-vsphere-default-extended-v1.0.0-kcp
    180c180
    <         name: tkg-vsphere-default-v1.0.0-control-plane
    ---
    >         name: tkg-vsphere-default-extended-v1.0.0-control-plane
    195c195
    <       name: tkg-vsphere-default-v1.0.0-cluster
    ---
    >       name: tkg-vsphere-default-extended-v1.0.0-cluster
    205c205
    <             name: tkg-vsphere-default-v1.0.0-md-config
    ---
    >             name: tkg-vsphere-default-extended-v1.0.0-md-config
    211c211
    <             name: tkg-vsphere-default-v1.0.0-worker
    ---
    >             name: tkg-vsphere-default-extended-v1.0.0-worker
    228c228
    <             name: tkg-vsphere-default-v1.0.0-md-config
    ---
    >             name: tkg-vsphere-default-extended-v1.0.0-md-config
    234c234
    <             name: tkg-vsphere-default-v1.0.0-worker
    ---
    >             name: tkg-vsphere-default-extended-v1.0.0-worker
    537a538,542
    >   - name: nfConntrackMax
    >     required: false
    >     schema:
    >       openAPIV3Schema:
    >         type: string
    1807a1813,1825
    >   - name: nfConntrackMax
    >     enabledIf: '{{ not (empty .nfConntrackMax) }}'
    >     definitions:
    >     - selector:
    >         apiVersion: controlplane.cluster.x-k8s.io/v1beta1
    >         kind: KubeadmControlPlaneTemplate
    >         matchResources:
    >           controlPlane: true
    >       jsonPatches:
    >       - op: add
    >         path: /spec/template/spec/kubeadmConfigSpec/preKubeadmCommands/-
    >         valueFrom:
    >           template: echo "net.netfilter.nf_conntrack_max={{ .nfConntrackMax }}" >> /etc/sysctl.conf
    

在管理叢集中安裝 ClusterClass

若要使管理叢集能夠使用自訂 ClusterClass,請依照以下方式安裝該叢集:

  1. 套用 ClusterClass 資訊清單,例如:

    $ kubectl apply -f custom_cc.yaml
    vsphereclustertemplate.infrastructure.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-cluster created
    vspheremachinetemplate.infrastructure.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-control-plane created
    vspheremachinetemplate.infrastructure.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-worker created
    kubeadmcontrolplanetemplate.controlplane.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-kcp created
    kubeadmconfigtemplate.bootstrap.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-md-config created
    clusterclass.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0 created
    
  2. 檢查自訂 ClusterClass 是否已散佈到預設命名空間,例如:

    $ kubectl get clusterclass,kubeadmconfigtemplate,kubeadmcontrolplanetemplate,vspheremachinetemplate,vsphereclustertemplate
    NAME                                                                AGE
    clusterclass.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0   3m16s
    clusterclass.cluster.x-k8s.io/tkg-vsphere-default-v1.0.0            2d18h
    
    NAME                                                                                             AGE
    kubeadmconfigtemplate.bootstrap.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-md-config   3m29s
    kubeadmconfigtemplate.bootstrap.cluster.x-k8s.io/tkg-vsphere-default-v1.0.0-md-config            2d18h
    
    NAME                                                                                                AGE
    kubeadmcontrolplanetemplate.controlplane.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-kcp   3m27s
    kubeadmcontrolplanetemplate.controlplane.cluster.x-k8s.io/tkg-vsphere-default-v1.0.0-kcp            2d18h
    
    NAME                                                                                                       AGE
    vspheremachinetemplate.infrastructure.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-control-plane   3m31s
    vspheremachinetemplate.infrastructure.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-worker          3m28s
    vspheremachinetemplate.infrastructure.cluster.x-k8s.io/tkg-vsphere-default-v1.0.0-control-plane            2d18h
    vspheremachinetemplate.infrastructure.cluster.x-k8s.io/tkg-vsphere-default-v1.0.0-worker                   2d18h
    
    NAME                                                                                                 AGE
    vsphereclustertemplate.infrastructure.cluster.x-k8s.io/tkg-vsphere-default-extended-v1.0.0-cluster   3m31s
    vsphereclustertemplate.infrastructure.cluster.x-k8s.io/tkg-vsphere-default-v1.0.0-cluster            2d18h
    

產生自訂工作負載叢集資訊清單

以自訂 ClusterClass 為基礎建立新的工作負載叢集,如下所示:

  1. 使用 --dry-run 選項執行 tanzu cluster create 以產生叢集資訊清單:

    tanzu cluster create --file workload-1.yaml --dry-run > default_cluster.yaml
    
  2. 建立 ytt 覆疊或直接編輯叢集資訊清單,以執行以下動作:

    • topology.class 值替換為自訂 ClusterClass 的名稱
    • 使用預設值將自訂變數新增到 variables 區塊

    與修改 ClusterClass 物件規格一樣,只要存在新的上游叢集版本,依照以下方式使用覆疊,即可自動將變更套用至新物件:

    #@ load("@ytt:overlay", "overlay")
    
    #@overlay/match by=overlay.subset({"kind":"Cluster"})
    ---
    apiVersion: cluster.x-k8s.io/v1beta1
    kind: Cluster
    spec:
      topology:
        class: tkg-vsphere-default-extended-v1.0.0
        variables:
        - name: nfConntrackMax
          value: "1048576"
    
  3. 產生資訊清單:

    ytt -f default_cluster.yaml -f cluster_overlay.yaml > custom_cluster.yaml
    
  4. (選用) 與上方的 ClusterClass 一樣,可以執行 diff 以將自訂類別叢集資訊清單與以預設類別為基礎的叢集進行比較,例如:

    $ diff custom_cluster.yaml default_cluster.yaml
    142c142
    <     class: tkg-vsphere-default-extended-v1.0.0
    ---
    >     class: tkg-vsphere-default-v1.0.0
    185,186d184
    <     - name: nfConntrackMax
    <       value: "1048576"
    

(選用) 試執行叢集建立

這個選用程序會顯示自訂 ClusterClass 將產生和管理的資源。

  1. 製作 custom_cluster.yaml 的複本:

    cp custom_cluster.yaml dryrun_cluster.yaml
    
  2. 從管理叢集複製變數 TKR_DATA

    kubectl get cluster mgmt -n tkg-system -o jsonpath='{.spec.topology.variables}' | jq -r '.[] | select(.name == "TKR_DATA")' | yq -p json '.'
    
  3. 手動將以上輸出附加到 dryrun_cluster.yaml 中的 .spec.topology.variables,例如,如以下 diff 輸出中所示:

    $ diff custom_cluster.yaml dryrun_cluster.yaml
    186a187,214
    >     - name: TKR_DATA
    >       value:
    >         v1.24.10+vmware.1:
    >           kubernetesSpec:
    >             coredns:
    >               imageTag: v1.8.6_vmware.12
    >             etcd:
    >               imageTag: v3.5.4_vmware.10
    >             imageRepository: projects.registry.vmware.com/tkg
    >             kube-vip:
    >               imageRepository: projects-stg.registry.vmware.com/tkg
    >               imageTag: v0.5.5_vmware.1
    >             pause:
    >               imageTag: "3.7"
    >             version: v1.24.10+vmware.1
    >           labels:
    >             image-type: ova
    >             os-arch: amd64
    >             os-name: photon
    >             os-type: linux
    >             os-version: "3"
    >             ova-version: v1.24.10+vmware.1-tkg.1-efe12079f22627aa1246398eba077476
    >             run.tanzu.vmware.com/os-image: v1.24.10---vmware.1-tkg.1-efe12079f22627aa1246398eba077476
    >             run.tanzu.vmware.com/tkr: v1.24.10---vmware.1-tkg.1-zshippable
    >           osImageRef:
    >             moid: vm-156
    >             template: /dc0/vm/photon-3-kube-v1.24.10+vmware.1-tkg.1-efe12079f22627aa1246398eba077476
    >             version: v1.24.10+vmware.1-tkg.1-efe12079f22627aa1246398eba077476
    
  4. 建立 plan 目錄:

    mkdir plan
    
  5. 試執行建立叢集,例如:

    $ clusterctl alpha topology plan -f dryrun_cluster.yaml -o plan
    Detected a cluster with Cluster API installed. Will use it to fetch missing objects.
    No ClusterClasses will be affected by the changes.
    The following Clusters will be affected by the changes:
    * default/workload-1
    
    Changes for Cluster "default/workload-1":
    
     NAMESPACE  KIND                    NAME                             ACTION
     default    KubeadmConfigTemplate   workload-1-md-0-bootstrap-lvchb  created
     default    KubeadmControlPlane     workload-1-2zmql                 created
     default    MachineDeployment       workload-1-md-0-hlr7c            created
     default    MachineHealthCheck      workload-1-2zmql                 created
     default    MachineHealthCheck      workload-1-md-0-hlr7c            created
     default    Secret                  workload-1-shim                  created
     default    VSphereCluster          workload-1-fmt2j                 created
     default    VSphereMachineTemplate  workload-1-control-plane-mf6k6   created
     default    VSphereMachineTemplate  workload-1-md-0-infra-k88bk      created
     default    Cluster                 workload-1                       modified
    
    Created objects are written to directory "plan/created"
    Modified objects are written to directory "plan/modified"
    
  6. 您應該會看到產生的以下檔案,並在 KubeadmControlPlane_default_workload-1-2zmql.yaml 中找到核心組態。

    $ tree plan
    plan
    |-- created
    |   |-- KubeadmConfigTemplate_default_workload-1-md-0-bootstrap-lvchb.yaml
    |   |-- KubeadmControlPlane_default_workload-1-2zmql.yaml
    |   |-- MachineDeployment_default_workload-1-md-0-hlr7c.yaml
    |   |-- MachineHealthCheck_default_workload-1-2zmql.yaml
    |   |-- MachineHealthCheck_default_workload-1-md-0-hlr7c.yaml
    |   |-- Secret_default_workload-1-shim.yaml
    |   |-- VSphereCluster_default_workload-1-fmt2j.yaml
    |   |-- VSphereMachineTemplate_default_workload-1-control-plane-mf6k6.yaml
    |   `-- VSphereMachineTemplate_default_workload-1-md-0-infra-k88bk.yaml
    `-- modified
       |-- Cluster_default_workload-1.diff
       |-- Cluster_default_workload-1.jsonpatch
       |-- Cluster_default_workload-1.modified.yaml
       `-- Cluster_default_workload-1.original.yaml
    
    2 directories, 13 files
    

    每當對自訂 ClusterClass 進行變更時,都應如上所述比較資源。

建立自訂叢集

以上述產生的自訂資訊清單為基礎,來建立自訂工作負載叢集,如下所示。

  1. 套用上述產生的自訂類別叢集資訊清單,例如:

    $ kubectl apply -f custom_cluster.yaml
    secret/workload-1-vsphere-credential created
    secret/workload-1-nsxt-credential created
    vspherecpiconfig.cpi.tanzu.vmware.com/workload-1 created
    vspherecsiconfig.csi.tanzu.vmware.com/workload-1 created
    clusterbootstrap.run.tanzu.vmware.com/workload-1 created
    secret/workload-1 created
    cluster.cluster.x-k8s.io/workload-1 created
    
    注意

    請勿使用 dryrun_cluster.yaml (用來產生資訊清單),因為 TKR_DATA 變數將由 TKG Webhook 注入。

  2. 檢查建立的物件內容。例如,對於上述核心修改,請擷取 KubeadmControlPlane 物件並確認已設定核心組態:

    $ kubectl get kcp workload-1-jgwd9 -o yaml
    apiVersion: controlplane.cluster.x-k8s.io/v1beta1
    kind: KubeadmControlPlane
    ...
       preKubeadmCommands:
       - hostname "{{ ds.meta_data.hostname }}"
       - echo "::1         ipv6-localhost ipv6-loopback" >/etc/hosts
       - echo "127.0.0.1   localhost" >>/etc/hosts
       - echo "127.0.0.1   {{ ds.meta_data.hostname }}" >>/etc/hosts
       - echo "{{ ds.meta_data.hostname }}" >/etc/hostname
       - echo "net.netfilter.nf_conntrack_max=1048576" >> /etc/sysctl.conf
       useExperimentalRetryJoin: true
    ...
    
  3. 登入控制平面節點並確認其 sysctl.conf 已修改:

    $ capv@workload-1-cn779-pthp5
    [ ~ ]$ sudo cat /etc/sysctl.conf
    ...
    net.ipv4.ip_forward=1
    net.ipv4.tcp_timestamps=1
    net.netfilter.nf_conntrack_max=1048576
    
check-circle-line exclamation-circle-line close-line
Scroll to top icon