Créer une ClusterClass

Cette rubrique explique comment créer votre propre définition de ressource ClusterClass personnalisée, que vous pouvez utiliser comme base pour la création de clusters de charge de travail basés sur une classe avec un cluster de gestion autonome Tanzu Kubernetes Grid (TKG). Pour baser un cluster sur une ClusterClass, définissez sa spec.topology.class sur le nom ClusterClass.

Cette procédure ne s'applique pas à TKG avec un superviseur vSphere with Tanzu.

Important

La création de définitions de ressources ClusterClass personnalisées est destinée aux utilisateurs avancés. VMware ne garantit pas la fonctionnalité des clusters de charge de travail basés sur des objets ClusterClass arbitraires. Pour créer des clusters de charge de travail à l'aide de la ressource ClusterClass par défaut, suivez les procédures décrites dans la section Étapes du déploiement d'un cluster.

Configuration requise

Pour créer une définition de ClusterClass, les outils suivants doivent être installés localement :
Outil Version
clusterctl v1.2.0
ytt 0.42.0
jq 1.5-1
yq v4.30.5

Options : Superposition par rapport à Nouvelle spécification d'objet

Pour créer une ClusterClass, VMware recommande de commencer par un objet ClusterClass par défaut existant lié sous Source d'objet ClusterClass, puis de le modifier avec une superposition ytt. Lorsqu'une nouvelle version de l'objet ClusterClass par défaut est publiée, vous pouvez ensuite appliquer la superposition à la nouvelle version, afin de mettre en œuvre les mêmes personnalisations. La procédure ci-dessous décrit cette méthode de création d'un objet ClusterClass personnalisé.

Pour écrire en partant de zéro un nouvel objet ClusterClass, suivez les instructions de la section Writing a ClusterClass dans la documentation de l'API de cluster.

Créer un objet ClusterClass personnalisé

Pour créer une définition d'objet ClusterClass personnalisée basée sur une ClusterClass existante définie dans le référentiel Tanzu Framework, procédez comme suit :

Récupérer la source de l'objet ClusterClass

  1. Dans le référentiel de code Tanzu Framework sur Github, téléchargez et décompressez le bundle zip v0.28.1.

  2. En fonction de votre infrastructure cible, cd dans le sous-répertoire package du référentiel :

    • AWS : packages/tkg-clusterclass-aws
    • Azure : packages/tkg-clusterclass-azure
    • vSphere : packages/tkg-clusterclass-vsphere

  3. Copiez le dossier bundle dans votre espace de travail. Sa structure est la suivante :

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

Générer votre manifeste ClusterClass de base

  1. Capturez les paramètres d'infrastructure dans un fichier de valeurs comme suit, selon que vous avez déjà déployé ou non un cluster de gestion autonome :

    • Cluster de gestion déployé Exécutez ce qui suit pour générer 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

    • Aucun cluster de gestion :

      1. Dans le répertoire bundle, copiez values.yaml dans un nouveau fichier, default_values.yaml :
      cp bundle/config/values.yaml default_values.yaml
      1. Modifiez default_values.yaml et renseignez les paramètres variables en fonction de votre infrastructure, par exemple :
      VSPHERE_DATACENTER: /dc0
VSPHERE_DATASTORE: /dc0/datastore/sharedVmfs-0
VSPHERE_FOLDER: /dc0/vm

      Reportez-vous à la section Référence de variable de fichier de configuration pour connaître les variables spécifiques à l'infrastructure.

  2. Générez votre manifeste ClusterClass de base à partir du fichier de valeurs :

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

Personnaliser votre manifeste ClusterClass

Pour personnaliser votre manifeste ClusterClass, créez des fichiers de superposition ytt avec le manifeste. L'exemple suivant montre comment modifier un paramètre de noyau Linux dans la définition clusterClass.

  1. Créez un dossier custom structuré comme suit :

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

  2. Modifiez custom/overlays/kernels.yaml, par exemple, pour ajouter nfConntrackMax en tant que variable et définir un correctif pour cet élément qui ajoute sa valeur au paramètre de noyau net.netfilter.nf_conntrack_max pour les nœuds de plan de contrôle.

    Cette superposition ajoute une commande au champ preKubeadmCommands, pour écrire la configuration dans sysctl.conf. Pour que le paramètre prenne effet, vous pouvez ajouter la commande sysctl -p pour appliquer cette modification.

    #@ 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. Les définitions ClusterClass par défaut sont immuables. Par conséquent, créez ou modifiez la superposition custom/values.yaml pour modifier le nom de votre ClusterClass personnalisée et de tous ses modèles en ajoutant -extended et une version, par exemple :

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

    Où CC-VERSION est le nom de la version de la classe de cluster, par exemple VSPHERE_CLUSTER_CLASS_VERSION.

  4. Générez la ClusterClass personnalisée :

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

  5. (Facultatif) Vérifiez la différence entre la ClusterClass par défaut et votre classe personnalisée, pour vous assurer que tous les noms ont le suffixe -extended et que vos nouvelles variables et correctifs JSON sont ajoutés, par exemple.

    $ 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

Installer la ClusterClass dans le cluster de gestion

Pour permettre à votre cluster de gestion d'utiliser votre ClusterClass personnalisée, installez-la comme suit :

  1. Appliquez le manifeste ClusterClass, par exemple :

    $ 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. Vérifiez si la ClusterClass personnalisée s'est propagée à l'espace de noms par défaut, par exemple :

    $ 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

Générer un manifeste de cluster de charge de travail personnalisé

Créez un cluster de charge de travail basé sur votre ClusterClass personnalisée comme suit :

  1. Exécutez tanzu cluster create avec l'option --dry-run pour générer un manifeste de cluster :

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

  2. Créez une superposition ytt ou modifiez directement le manifeste du cluster pour effectuer les opérations suivantes :

    • Remplacez la valeur topology.class par le nom de votre ClusterClass personnalisée.
    • Ajoutez vos variables personnalisées au bloc variables, avec une valeur par défaut.

    Comme pour la modification des spécifications d'objets ClusterClass, l'utilisation d'une superposition comme suit vous permet d'appliquer automatiquement les modifications aux nouveaux objets à chaque nouvelle version de cluster en amont :

    #@ 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. Générez le manifeste :

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

  4. (Facultatif) Comme avec la ClusterClass ci-dessus, vous pouvez exécuter diff pour comparer votre manifeste de cluster de classe personnalisée avec un cluster basé sur une classe par défaut, par exemple :

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

(Facultatif) Exécution de test de création de cluster

Cette procédure facultative affiche les ressources que va générer et gérer votre ClusterClass personnalisée.

  1. Faites une copie du fichier custom_cluster.yaml :

    cp custom_cluster.yaml dryrun_cluster.yaml

  2. Copiez la variable TKR_DATA à partir du cluster de gestion :

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

  3. Ajoutez manuellement la sortie ci-dessus à .spec.topology.variables dans le fichier dryrun_cluster.yaml, par exemple, comme indiqué dans cette sortie 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. Créez un répertoire plan :

    mkdir plan

  5. Exécution de test lors de la création du cluster, par exemple :

    $ 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. Vous devez voir les fichiers suivants générés et trouver la configuration du noyau dans 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

    Vous devez comparer les ressources comme ci-dessus chaque fois que vous apportez des modifications à votre ClusterClass personnalisée.

Créer un cluster personnalisé

Créez un cluster de charge de travail personnalisé basé sur le manifeste personnalisé généré ci-dessus comme suit.

  1. Appliquez le manifeste du cluster de classe personnalisé généré ci-dessus, par exemple :

    $ 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
    Attention :

    N'utilisez pas dryrun_cluster.yaml, qui a été utilisé pour générer le manifeste, car la variable TKR_DATA sera injectée par un Webhook TKG.

  2. Vérifiez les propriétés de l'objet créé. Par exemple, avec la modification du noyau ci-dessus, récupérez l'objet KubeadmControlPlane et confirmez que la configuration du noyau est définie :

    $ 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. Connectez-vous à un nœud de plan de contrôle et confirmez que son sysctl.conf est modifié :

    $ 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