Crear un ClusterClass

En este tema se explica cómo crear su propia definición de recursos ClusterClass personalizada que puede utilizar como base para crear clústeres de carga de trabajo basados en clases con un clúster de administración independiente de Tanzu Kubernetes Grid (TKG). Para basar un clúster en un ClusterClass, establezca su spec.topology.class en el nombre ClusterClass.

Este procedimiento no se aplica a TKG con un supervisor de vSphere with Tanzu.

Importante
La creación de definiciones de recursos ClusterClass personalizadas es para usuarios avanzados. VMware no garantiza la funcionalidad de los clústeres de carga de trabajo basados en objetos ClusterClass arbitrarios. Para crear clústeres de carga de trabajo mediante el recurso ClusterClass predeterminado, siga los procedimientos descritos en Pasos para la implementación del clúster.

Requisitos

Para crear una definición de ClusterClass, necesita instalar las siguientes herramientas de forma local:


Herramienta	Versión
clusterctl	v1.2.0
ytt	0.42.0
jq	1.5-1
yq	v4.30.5

Opciones: Superposición frente a nueva especificación de objeto

Para crear un nuevo ClusterClass, VMware recomienda comenzar con un objeto ClusterClass predeterminado existente vinculado en Fuente de objeto ClusterClass y, a continuación, modificarlo con una superposición ytt. Cuando se publica una nueva versión del objeto ClusterClass predeterminado, puede aplicar la superposición a la nueva versión para implementar las mismas personalizaciones. El siguiente procedimiento describe este método para crear un objeto ClusterClass personalizado.

Para escribir un nuevo objeto ClusterClass desde nada, siga Escribir un objeto ClusterClass en la documentación de la API del clúster.

Crear un objeto ClusterClass personalizado

Para crear una definición de objeto ClusterClass personalizada basada en un ClusterClass existente definido en el repositorio de Tanzu Framework, haga lo siguiente:

Recuperar origen del objeto ClusterClass

Desde el repositorio de código de Tanzu Framework en Github, descargue y descomprima el paquete zip v0.28.1.
- URL: https://github.com/vmware-tanzu/tanzu-framework/archive/refs/tags/v0.28.1.zip
En función de la infraestructura de destino, cd en el subdirectorio package del repositorio:
- AWS: packages/tkg-clusterclass-aws
- Azure: packages/tkg-clusterclass-azure
- vSphere: packages/tkg-clusterclass-vsphere

Copie la carpeta bundle en el área de trabajo. Tiene la siguiente estructura:

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

Genere el manifiesto base de ClusterClass

Capture la configuración de la infraestructura en un archivo de valores de la siguiente manera, en función de si ya implementó un clúster de administración independiente:
- Clúster de administración implementado Ejecute lo siguiente para generar 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
```
- Clúster de administración no independiente:
  1. En el directorio bundle, copie values.yaml en un nuevo archivo, default_values.yaml:
```
cp bundle/config/values.yaml default_values.yaml
```
  1. Edite default_values.yaml y rellene la configuración de las variables según su infraestructura, por ejemplo:
```
VSPHERE_DATACENTER: /dc0
VSPHERE_DATASTORE: /dc0/datastore/sharedVmfs-0
VSPHERE_FOLDER: /dc0/vm
```
  Consulte la Referencia de variables del archivo de configuración para ver las variables específicas de la infraestructura.
Genere el manifiesto base de ClusterClass a partir del archivo de valores:
```
ytt -f bundle -f default_values.yaml > default_cc.yaml
```

Personalizar el manifiesto de ClusterClass

Para personalizar el manifiesto de ClusterClass, cree archivos de superposición ytt junto con el manifiesto. El siguiente ejemplo muestra cómo modificar un parámetro de kernel de Linux en la definición ClusterClass.

Cree una carpeta custom estructurada de la siguiente manera:

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

Edite custom/overlays/kernels.yaml, por ejemplo, para agregar nfConntrackMax como variable y defina una revisión para ella que agregue su valor el parámetro de kernel net.netfilter.nf_conntrack_max para los nodos del plano de control.

Esta superposición anexa un comando al campo preKubeadmCommands, para escribir la configuración en sysctl.conf. Para que ese ajuste surta efecto, puede anexar el comando sysctl -p para aplicar este cambio.

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

Las definiciones de ClusterClass predeterminadas son inmutables, por lo que cree o edite la superposición custom/values.yaml para cambiar el nombre de la ClusterClass personalizada y todas sus plantillas agregando -extended y una versión, por ejemplo:
```
#@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
```
Donde CC-VERSION es el nombre de la versión de la clase de clúster, por ejemplo, VSPHERE_CLUSTER_CLASS_VERSION.

Generar la ClusterClass personalizada:

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

(Opcional) Compruebe la diferencia entre el ClusterClass predeterminado y el personalizado para confirmar que todos los nombres tienen el sufijo -extended y se agregaron las nuevas variables y revisiones JSON, por ejemplo.

$ 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

Instalar ClusterClass en el clúster de administración

Para permitir que el clúster de administración utilice la ClusterClass personalizada, instálelo de la siguiente manera:

Aplique el manifiesto de ClusterClass, por ejemplo:

$ 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

Compruebe si la ClusterClass personalizada se propagó al espacio de nombres predeterminado, por ejemplo:

$ 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

Generar manifiesto de clúster de carga de trabajo personalizado

Cree un nuevo clúster de carga de trabajo en función de su ClusterClass personalizada de la siguiente manera:

Ejecute tanzu cluster create con la opción --dry-run para generar un manifiesto del clúster:
```
tanzu cluster create --file workload-1.yaml --dry-run > default_cluster.yaml
```
Cree una superposición de ytt o edite el manifiesto del clúster directamente para hacer lo siguiente:
- Reemplace el valor topology.class con el nombre de la ClusterClass personalizada
- Añada las variables personalizadas al bloque variables, con un valor predeterminado
Al igual que con la modificación de especificaciones de objetos ClusterClass, el uso de una superposición de la siguiente manera permite aplicar automáticamente los cambios a los objetos nuevos cada vez que hay una nueva versión de clúster ascendente:
```
#@ 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"
```

Genere el manifiesto:

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

(Opcional) Al igual que con la ClusterClass anterior, puede ejecutar diff para comparar el manifiesto del clúster de clase personalizada con un clúster basado en clases predeterminado, por ejemplo:

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

(Opcional) Crear clúster de simulacro

Este procedimiento opcional muestra los recursos que generará y administrará su ClusterClass personalizado.

Realice una copia de custom_cluster.yaml:

cp custom_cluster.yaml dryrun_cluster.yaml

Copie la variable TKR_DATA del clúster de administración:

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

Anexe manualmente la salida anterior a .spec.topology.variables en el dryrun_cluster.yaml, por ejemplo, como se muestra en estos resultados de 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

Cree un directorio plan:
```
mkdir plan
```

Simulacro de creación del clúster, por ejemplo:

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

Debería ver los siguientes archivos generados y encontrar la configuración del kernel en 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

Debe comparar los recursos como se indica anteriormente cada vez que realice cambios en la ClusterClass personalizada.

Crear un clúster personalizado

Cree un clúster de carga de trabajo personalizado basado en el manifiesto personalizado generado anteriormente de la siguiente manera.

Aplique el manifiesto del clúster de clase personalizada generado anteriormente, por ejemplo:

$ 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

Precaución
No utilice aplicar dryrun_cluster.yaml, que se utilizó para generar el manifiesto, ya que un webhook de TKG inyectará la variable TKR_DATA.

Compruebe las propiedades del objeto creado. Por ejemplo, con la modificación del kernel anterior, recupere el objeto KubeadmControlPlane y confirme que la configuración del kernel está establecida:

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

Inicie sesión en un nodo de plano de control y confirme que su sysctl.conf se haya modificado:

$ 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