Creazione di una ClusterClass

Questo argomento spiega come creare una definizione di risorsa ClusterClass personalizzata che è possibile utilizzare come base per la creazione di cluster del carico di lavoro basati sulla classe con un cluster di gestione autonomo Tanzu Kubernetes Grid (TKG). Per basare un cluster su una ClusterClass, impostare il valore di spec.topology.class sul nome di ClusterClass.

Questa procedura non si applica a TKG con un supervisore vSphere with Tanzu.

Importante
La creazione di definizioni di risorse ClusterClass personalizzate è riservata agli utenti avanzati. VMware non garantisce la funzionalità dei cluster di carichi di lavoro basati su oggetti ClusterClass arbitrari. Per creare cluster del carico di lavoro utilizzando la risorsa ClusterClass predefinita, eseguire le procedure indicate in Passaggi per la distribuzione del cluster.

Requisiti

Per creare una definizione ClusterClass, sono necessari i seguenti strumenti installati in locale:


Strumento	Versione
clusterctl	v1.2.0
ytt	0.42.0
jq	1.5-1
yq	v4.30.5

Opzioni: Overlay e specifica di un nuovo oggetto

Per creare una nuova ClusterClass, VMware consiglia di iniziare con un oggetto ClusterClass predefinito esistente il cui collegamento è disponibile in Origine dell'oggetto ClusterClass e quindi modificarlo con un overlay ytt. Quando viene pubblicata una nuova versione dell'oggetto ClusterClass predefinito, è possibile applicare l'overlay alla nuova versione per implementare le stesse personalizzazioni. La procedura seguente descrive questo metodo di creazione di un oggetto ClusterClass personalizzato.

Per scrivere un nuovo oggetto ClusterClass da zero, seguire le istruzioni di Scrittura di una ClusterClass nella documentazione di Cluster API.

Creazione di un oggetto ClusterClass personalizzato

Per creare una definizione di oggetto ClusterClass personalizzato in base a una ClusterClass esistente definita nel repository Tanzu Framework, eseguire i passaggi seguenti:

Recupero dell'origine dell'oggetto ClusterClass

Dal repository di codice Tanzu Framework su GitHub, scaricare e decomprimere il bundle zip v0.28.1.
- URL: https://github.com/vmware-tanzu/tanzu-framework/archive/refs/tags/v0.28.1.zip
In base all'infrastruttura di destinazione, eseguire cd nella sottodirectory package del repository:
- AWS: packages/tkg-clusterclass-aws
- Azure: packages/tkg-clusterclass-azure
- vSphere: packages/tkg-clusterclass-vsphere

Copiare la cartella bundle nell'area di lavoro. Tale cartella ha la struttura seguente:

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

Generazione del manifesto ClusterClass di base

Acquisire le impostazioni dell'infrastruttura in un file di valori come indicato di seguito, a seconda che sia già stato distribuito o meno un cluster di gestione autonomo:
- Cluster di gestione distribuito Eseguire il comando seguente per generare 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
```
- Nessun cluster di gestione autonomo:
  1. Nella directory bundle copiare values.yaml in un nuovo file, default_values.yaml:
```
cp bundle/config/values.yaml default_values.yaml
```
  1. Modificare default_values.yaml e inserire le impostazioni delle variabili in base all'infrastruttura in uso, ad esempio:
```
VSPHERE_DATACENTER: /dc0
VSPHERE_DATASTORE: /dc0/datastore/sharedVmfs-0
VSPHERE_FOLDER: /dc0/vm
```
  Per informazioni sulle variabili specifiche dell'infrastruttura, vedere Informazioni di riferimento sulle variabili del file di configurazione.
Generare il manifesto ClusterClass di base dal file dei valori:
```
ytt -f bundle -f default_values.yaml > default_cc.yaml
```

Personalizzazione del manifesto ClusterClass

Per personalizzare il manifesto ClusterClass, creare file di overlay ytt insieme al manifesto. L'esempio seguente illustra come modificare un parametro del kernel Linux nella definizione di ClusterClass.

Creare una cartella custom con la struttura seguente:

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

Modificare custom/overlays/kernels.yaml, ad esempio per aggiungere nfConntrackMax come variabile e definire una patch per tale variabile che aggiunga al suo valore il parametro kernel net.netfilter.nf_conntrack_max per i nodi del piano di controllo.

Questo overlay aggiunge un comando al campo preKubeadmCommands per scrivere la configurazione in sysctl.conf. Per rendere effettiva l'impostazione, è possibile aggiungere il comando sysctl -p per applicare questa modifica.

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

Poiché le definizioni di ClusterClass predefinite non sono modificabili, creare o modificare l'overlay custom/values.yaml per modificare il nome della ClusterClass personalizzata e di tutti i relativi modelli aggiungendo -extended e una versione, ad esempio:
```
#@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
```
In cui CC-VERSION è il nome della versione della classe del cluster, ad esempio VSPHERE_CLUSTER_CLASS_VERSION.

Generare la ClusterClass personalizzata:

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

(Facoltativo) Verificare ad esempio la differenza tra la ClusterClass predefinita e quella personalizzata per controllare che tutti i nomi abbiano il suffisso -extended e che le nuove variabili e patch JSON vengano aggiunte.

$ 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

Installazione di ClusterClass nel cluster di gestione

Per consentire al cluster di gestione di utilizzare la ClusterClass personalizzata, installarla come segue:

Applicare il manifesto ClusterClass, ad esempio:

$ 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

Controllare se la ClusterClass personalizzata è stata propagata nello spazio dei nomi predefinito, ad esempio:

$ 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

Generazione di un manifesto del cluster del carico di lavoro personalizzato

Creare un nuovo cluster del carico di lavoro basato sulla ClusterClass personalizzata nel modo seguente:

Eseguire tanzu cluster create con l'opzione --dry-run per generare un manifesto del cluster:
```
tanzu cluster create --file workload-1.yaml --dry-run > default_cluster.yaml
```
Creare un overlay ytt o modificare il manifesto del cluster direttamente per eseguire i passaggi seguenti:
- Sostituire il valore di topology.class con il nome della ClusterClass predefinita
- Aggiungere le variabili personalizzate al blocco variables, con un valore predefinito
Come per la modifica delle specifiche degli oggetti ClusterClass, l'utilizzo di un overlay come indicato di seguito consente di applicare automaticamente le modifiche ai nuovi oggetti ogni volta che viene rilasciata una nuova versione del cluster upstream:
```
#@ 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"
```

Generare il manifesto:

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

(Facoltativo) Come per la ClusterClass precedente, è possibile eseguire diff per confrontare il manifesto della classe del cluster personalizzata con un cluster predefinito basato sulla classe, ad esempio:

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

(Facoltativo) Test controllato della creazione del cluster

Questa procedura facoltativa illustra le risorse che la ClusterClass personalizzata genererà e gestirà.

Creare una copia di custom_cluster.yaml:

cp custom_cluster.yaml dryrun_cluster.yaml

Copiare la variabile TKR_DATA dal cluster di gestione:

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

Aggiungere manualmente l'output precedente in .spec.topology.variables in dryrun_cluster.yaml, ad esempio come illustrato in questo output 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

Creare una directory plan:
```
mkdir plan
```

Eseguire il test controllato della creazione del cluster, ad esempio:

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

Verranno generati i file seguenti e la configurazione del kernel sarà disponibile in 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

È consigliabile confrontare le risorse come illustrato in precedenza ogni volta che si apportano modifiche alla ClusterClass personalizzata.

Creazione di un cluster personalizzato

Creare un cluster del carico di lavoro personalizzato in base al manifesto personalizzato generato in precedenza, come indicato di seguito.

Applicare il manifesto del cluster della classe personalizzata generato in precedenza, ad esempio:

$ 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

Attenzione
Non applicare dryrun_cluster.yaml, utilizzato per generare il manifesto, perché la variabile TKR_DATA verrà inserita da un webhook TKG.

Controllare le proprietà degli oggetti creati. Ad esempio, con la modifica del kernel precedente, recuperare l'oggetto KubeadmControlPlane e verificare che la configurazione del kernel sia impostata:

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

Accedere a un nodo del piano di controllo e verificare che il valore di sysctl.conf sia stato modificato:

$ 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