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
    

    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