建立 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 物件來源

從 Github 上的 Tanzu Framework 程式碼存放庫中，下載並解壓縮 v0.28.1 zip 服務包。
- URL：https://github.com/vmware-tanzu/tanzu-framework/archive/refs/tags/v0.28.1.zip
根據您的目標基礎結構，將 cd 複製到存放庫的 package 子目錄：
- AWS：packages/tkg-clusterclass-aws
- Azure：packages/tkg-clusterclass-azure
- vSphere：packages/tkg-clusterclass-vsphere

將 bundle 資料夾複製到工作區。它具有下列結構：

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

產生基本 ClusterClass 資訊清單

根據是否已部署獨立管理叢集，在值檔案中擷取基礎結構設定，如下所示：
- 已部署管理叢集執行以下命令以產生 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
```
  有關基礎結構特定的變數，請參閱組態檔變數參考。

透過值檔案產生基本 ClusterClass 資訊清單：

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

自訂 ClusterClass 資訊清單

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

建立 custom 資料夾，結構如下所示：

$ tree custom
 custom
 |-- overlays
 |   -- kernels.yaml
 -- values.yaml

例如，編輯 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

預設 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。

產生自訂 ClusterClass：

ytt -f bundle -f default_values.yaml -f custom > custom_cc.yaml

(選用) 檢查預設 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，請依照以下方式安裝該叢集：

套用 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

檢查自訂 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 為基礎建立新的工作負載叢集，如下所示：

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

tanzu cluster create --file workload-1.yaml --dry-run > default_cluster.yaml

建立 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"
```

產生資訊清單：

ytt -f default_cluster.yaml -f cluster_overlay.yaml > custom_cluster.yaml

(選用) 與上方的 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 將產生和管理的資源。

製作 custom_cluster.yaml 的複本：

cp custom_cluster.yaml dryrun_cluster.yaml

從管理叢集複製變數 TKR_DATA：

kubectl get cluster mgmt -n tkg-system -o jsonpath='{.spec.topology.variables}' | jq -r '.[] | select(.name == "TKR_DATA")' | yq -p json '.'

手動將以上輸出附加到 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

建立 plan 目錄：
```
mkdir plan
```

試執行建立叢集，例如：

$ 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"

您應該會看到產生的以下檔案，並在 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 進行變更時，都應如上所述比較資源。

建立自訂叢集

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

套用上述產生的自訂類別叢集資訊清單，例如：

$ 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 注入。

檢查建立的物件內容。例如，對於上述核心修改，請擷取 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
...

登入控制平面節點並確認其 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