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

  1. Desde el repositorio de código de Tanzu Framework en Github, descargue y descomprima el paquete zip v0.29.0.

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

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

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

  1. Cree una carpeta custom estructurada de la siguiente manera:

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

  4. Generar la ClusterClass personalizada:

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

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

  1. 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
    
  2. 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"
    
  3. Genere el manifiesto:

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

  1. Realice una copia de custom_cluster.yaml:

    cp custom_cluster.yaml dryrun_cluster.yaml
    
  2. 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 '.'
    
  3. 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.25.7+vmware.1:
    >           kubernetesSpec:
    >             coredns:
    >               imageTag: v1.9.3_vmware.8
    >             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.25.7+vmware.1
    >           labels:
    >             image-type: ova
    >             os-arch: amd64
    >             os-name: photon
    >             os-type: linux
    >             os-version: "3"
    >             ova-version: v1.25.7+vmware.1-tkg.1-efe12079f22627aa1246398eba077476
    >             run.tanzu.vmware.com/os-image: v1.25.7---vmware.1-tkg.1-efe12079f22627aa1246398eba077476
    >             run.tanzu.vmware.com/tkr: v1.25.7---vmware.1-tkg.1-zshippable
    >           osImageRef:
    >             moid: vm-156
    >             template: /dc0/vm/photon-3-kube-v1.25.7+vmware.1-tkg.1-efe12079f22627aa1246398eba077476
    >             version: v1.25.7+vmware.1-tkg.1-efe12079f22627aa1246398eba077476
    
  4. Cree un directorio plan:

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

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

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