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

  1. Dal repository di codice Tanzu Framework su GitHub, scaricare e decomprimere il bundle zip v0.28.1.

  2. 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
  3. 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

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

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

  1. Creare una cartella custom con la struttura seguente:

    $ tree custom
     custom
     |-- overlays
     |   -- kernels.yaml
     -- values.yaml
    
  2. 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
    
  3. 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.

  4. Generare la ClusterClass personalizzata:

    ytt -f bundle -f default_values.yaml -f custom > custom_cc.yaml
    
  5. (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:

  1. 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
    
  2. 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:

  1. 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
    
  2. 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"
    
  3. Generare il manifesto:

    ytt -f default_cluster.yaml -f cluster_overlay.yaml > custom_cluster.yaml
    
  4. (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à.

  1. Creare una copia di custom_cluster.yaml:

    cp custom_cluster.yaml dryrun_cluster.yaml
    
  2. 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 '.'
    
  3. 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
    
  4. Creare una directory plan:

    mkdir plan
    
  5. 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"
    
  6. 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.

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

  2. 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
    ...
    
  3. 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
    
check-circle-line exclamation-circle-line close-line
Scroll to top icon