Erstellen einer ClusterClass

In diesem Thema wird erläutert, wie Sie eine eigene benutzerdefinierte ClusterClass-Ressourcendefinition erstellen, die Sie als Grundlage zum Erstellen klassenbasierter Arbeitslastcluster mit einem eigenständigen TKG-Verwaltungscluster (Tanzu Kubernetes Grid) verwenden können. Um einen Cluster in einer ClusterClass zu begründen, legen Sie seine spec.topology.class auf den ClusterClass-Namen fest.

Dieses Verfahren gilt nicht für TKG mit einem vSphere with Tanzu Supervisor.

Wichtig
Das Verfahren zum Erstellen benutzerdefinierter ClusterClass-Ressourcendefinitionen ist für fortgeschrittene Benutzer vorgesehen. VMware übernimmt keine Garantie für die Funktionalität von Arbeitslastclustern, die auf beliebigen ClusterClass-Objekten basieren. Zum Erstellen von Arbeitslastclustern mithilfe der Standardressource ClusterClass führen Sie die Verfahren in Schritte für die Clusterbereitstellung durch.

Anforderungen

Um eine ClusterClass-Definition zu erstellen, müssen die folgenden Tools lokal installiert sein:


Tool	Version
clusterctl	v1.2.0
ytt	0.42.0
jq	1.5-1
yq	v4.30.5

Optionen: Overlay im Vergleich zu neuer Objektspezifikation

Um eine neue ClusterClass zu erstellen, empfiehlt VMware, mit einem vorhandenen ClusterClass-Standardobjekt zu beginnen, das unter ClusterClass-Objektquelle verknüpft ist, und es dann mit einem ytt-Overlay zu ändern. Wenn eine neue Version des ClusterClass-Standardobjekts veröffentlicht wird, können Sie das Overlay auf die neue Version anwenden, um dieselben Anpassungen zu implementieren. In der folgenden Prozedur wird diese Methode zum Erstellen eines benutzerdefinierten ClusterClass-Objekts beschrieben.

Um ein neues ClusterClass-Objekt von Grund auf zu schreiben, befolgen Sie die Anleitung zum Schreiben einer ClusterClass in der Dokumentation zur Cluster-API.

Erstellen eines benutzerdefinierten ClusterClass-Objekts

Um eine benutzerdefinierte ClusterClass-Objektdefinition basierend auf einer vorhandenen ClusterClass zu erstellen, die im Tanzu Framework-Repository definiert ist, gehen Sie wie folgt vor:

Abrufen der ClusterClass-Objektquelle

Laden Sie das ZIP-Paket v0.29.0 aus dem Tanzu Framework-Code-Repository auf Github herunter und entpacken Sie es.
- URL: https://github.com/vmware-tanzu/tanzu-framework/archive/refs/tags/v0.29.0.zip
Ändern Sie je nach Ihrer Zielinfrastruktur das Verzeichnis mit cd in das Unterverzeichnis package:
- AWS: packages/tkg-clusterclass-aws
- Azure: packages/tkg-clusterclass-azure
- vSphere: packages/tkg-clusterclass-vsphere

Kopieren Sie den Ordner bundle in Ihren Arbeitsbereich. Er hat die folgende Struktur:

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

Generieren eines ClusterClass-Basismanifests

Erfassen Sie Ihre Infrastruktureinstellungen wie folgt in einer Wertedatei, je nachdem, ob Sie bereits einen eigenständigen Verwaltungscluster bereitgestellt haben:
- Verwaltungscluster bereitgestellt Führen Sie Folgendes aus, um default-values.yaml zu generieren:
```
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
```
- Kein eigenständiger Verwaltungscluster:
  1. Kopieren Sie im Verzeichnis bundle die Datei values.yaml in eine neue Datei, default_values.yaml:
```
cp bundle/config/values.yaml default_values.yaml
```
  1. Bearbeiten Sie default_values.yaml und füllen Sie die Variableneinstellungen entsprechend Ihrer Infrastruktur aus, z. B.:
```
VSPHERE_DATACENTER: /dc0
VSPHERE_DATASTORE: /dc0/datastore/sharedVmfs-0
VSPHERE_FOLDER: /dc0/vm
```
  Informationen zu infrastrukturspezifischen Variablen finden Sie in der Referenz für die Variablen der Konfigurationsdatei.
Generieren Sie Ihr ClusterClass-Basismanifest aus der Wertedatei:
```
ytt -f bundle -f default_values.yaml > default_cc.yaml
```

Anpassen des ClusterClass-Manifests

Um das ClusterClass-Manifest anzupassen, erstellen Sie zusammen mit dem Manifest ytt-Overlaydateien. Das folgende Beispiel zeigt, wie Sie einen Linux-Kernelparameter in der ClusterClass-Definition ändern.

Erstellen Sie wie folgt einen custom-Ordner:

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

Bearbeiten Sie , beispielsweise, um als Variable hinzuzufügen und einen Patch dafür zu definieren, der den Wert für den Kernelparameter für Knoten der Steuerungsebene hinzufügt.custom/overlays/kernels.yamlnfConntrackMaxnet.netfilter.nf_conntrack_max

Dieses Overlay hängt einen Befehl an das Feld preKubeadmCommands an, um die Konfiguration in sysctl.conf zu schreiben. Damit die Einstellung wirksam wird, können Sie den Befehl sysctl -p anhängen, um diese Änderung zu übernehmen.

#@ 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

Die Definitionen für eine standardmäßige ClusterClass sind unveränderlich. Erstellen oder bearbeiten Sie daher das custom/values.yaml-Overlay, um den Namen Ihrer benutzerdefinierten ClusterClass und aller zugehörigen Vorlagen zu ändern, indem Sie -extended und eine Version hinzufügen, z. B.:
```
#@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
```
Dabei ist CC-VERSION der Name der Clusterklassenversion, z. B. VSPHERE_CLUSTER_CLASS_VERSION.

Generieren Sie die benutzerdefinierte ClusterClass:

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

(Optional) Vergleichen Sie die standardmäßige ClusterClass mit der benutzerdefinierten ClusterClass, um zu überprüfen, ob alle Namen das Suffix -extended enthalten und die neuen Variablen und JSON-Patches hinzugefügt wurden, z. B.:

$ 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

Installieren der ClusterClass im Verwaltungscluster

Damit der Verwaltungscluster die benutzerdefinierte ClusterClass verwenden kann, installieren Sie sie wie folgt:

Wenden Sie das ClusterClass-Manifest an, z. B.:

$ 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

Überprüfen Sie, ob die benutzerdefinierte ClusterClass an den Standard-Namespace propagiert wurde, z. B.:

$ 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

Generieren eines benutzerdefinierten Arbeitslastcluster-Manifests

Erstellen Sie einen neuen Arbeitslastcluster auf der Grundlage der benutzerdefinierten ClusterClass wie folgt:

Führen Sie tanzu cluster create mit der Option --dry-run aus, um ein Cluster-Manifest zu generieren:
```
tanzu cluster create --file workload-1.yaml --dry-run > default_cluster.yaml
```
Erstellen Sie ein ytt-Overlay oder bearbeiten Sie das Cluster-Manifest direkt, um Folgendes durchzuführen:
- Ersetzen Sie den Wert topology.class durch den Namen der benutzerdefinierten ClusterClass.
- Fügen Sie die benutzerdefinierten Variablen mit einem Standardwert zum Block variables hinzu.
Wie beim Ändern von ClusterClass-Objektspezifikationen können Sie mithilfe eines Overlays wie folgt die Änderungen automatisch auf neue Objekte anwenden, wenn eine neue Upstream-Clusterversion vorhanden ist:
```
#@ 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"
```

Generieren Sie das Manifest:

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

(Optional) Wie bei der obigen ClusterClass können Sie diff ausführen, um das Manifest des Clusters mit benutzerdefinierter Klasse mit einem klassenbasierten Standardcluster zu vergleichen, z. B.:

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

(Optional) Erstellen von Testlaufclustern

Diese optionale Prozedur zeigt Ihnen die Ressourcen, die die benutzerdefinierte ClusterClass generiert und verwaltet.

Erstellen Sie eine Kopie von custom_cluster.yaml:
```
cp custom_cluster.yaml dryrun_cluster.yaml
```

Kopieren Sie die Variable TKR_DATA aus dem Verwaltungscluster:

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

Hängen Sie die obige Ausgabe manuell an .spec.topology.variables in der dryrun_cluster.yaml an, z. B. wie in dieser Ausgabe von diff dargestellt:

$ diff custom_cluster.yaml dryrun_cluster.yaml
186a187,214
>     - name: TKR_DATA
>       value:
>         v1.25.7+vmware.1:
>           kubernetesSpec:
>             coredns:
>               imageTag: v1.9.3_vmware.8
>             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.25.7+vmware.1
>           labels:
>             image-type: ova
>             os-arch: amd64
>             os-name: photon
>             os-type: linux
>             os-version: "3"
>             ova-version: v1.25.7+vmware.1-tkg.1-efe12079f22627aa1246398eba077476
>             run.tanzu.vmware.com/os-image: v1.25.7---vmware.1-tkg.1-efe12079f22627aa1246398eba077476
>             run.tanzu.vmware.com/tkr: v1.25.7---vmware.1-tkg.1-zshippable
>           osImageRef:
>             moid: vm-156
>             template: /dc0/vm/photon-3-kube-v1.25.7+vmware.1-tkg.1-efe12079f22627aa1246398eba077476
>             version: v1.25.7+vmware.1-tkg.1-efe12079f22627aa1246398eba077476

Erstellen Sie das Verzeichnis plan:
```
mkdir plan
```

Führen Sie einen Testlauf zum Erstellen des Clusters aus, z. B.:

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

Sie sollten die folgenden generierten Dateien sehen und die Kernelkonfiguration in KubeadmControlPlane_default_workload-1-2zmql.yaml finden.

$ 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

Sie sollten Ressourcen wie oben beschrieben vergleichen, wenn Sie Änderungen an der benutzerdefinierten ClusterClass vornehmen.

Erstellen eines benutzerdefinierten Clusters

Erstellen Sie einen benutzerdefinierten Arbeitslastcluster wie folgt basierend auf dem oben erzeugten benutzerdefinierten Manifest.

Wenden Sie das oben erzeugte Cluster-Manifest der benutzerdefinierten Klasse an, z. B.:

$ 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

Vorsicht
Verwenden Sie nicht apply dryrun_cluster.yaml, das zum Generieren des Manifests verwendet wurde, da die Variable TKR_DATA von einem TKG-Webhook injiziert wird.

Überprüfen Sie die Eigenschaften des erstellten Objekts. Rufen Sie beispielsweise mit der obigen Kernel-Änderung das Objekt KubeadmControlPlane ab und bestätigen Sie, dass die Kernel-Konfiguration festgelegt ist:

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

Melden Sie sich bei Knoten der Steuerungsebene an und bestätigen Sie, dass die sysctl.conf geändert wurde:

$ 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