API de cluster v1beta1

L'API Cluster v1beta1 vous permet de provisionner un cluster en fonction d'une définition ClusterClass par défaut.

API ClusterClass v1beta1

L'API de cluster Kubernetes est une suite d'outils qui fournit le provisionnement, la mise à niveau et l'exploitation déclaratifs des clusters Kubernetes. ClusterClass est une évolution de l'API du cluster qui vous permet de définir des modèles pour la gestion du cycle de vie des ensembles de clusters. TKG 2 sur le Superviseur prend en charge la classe ClusterClass à l'aide de l'API v1beta1.

TKG 2 sur le Superviseur est fourni avec une définition de ClusterClass par défaut nommée tanzukubernetescluster. La classe ClusterClass tanzukubernetescluster fournit le modèle de création de clusters TKG 2 sur le Superviseur à l'aide de l'API v1beta. La ClusterClass tanzukubernetescluster par défaut est disponible dans tous les espaces de noms d'utilisateur. Pour créer un cluster basé sur cette classe ClusterClass, référencez-le dans la spécification du cluster. Reportez-vous aux exemples v1beta pour obtenir des instructions.

ClusterClass tanzubernerescluster par défaut

La classe ClusterClass de cluster tanzukubernetescluster par défaut est immuable. Elle est fournie ici comme référence.

apiVersion: cluster.x-k8s.io/v1beta1
kind: ClusterClass
metadata:
  name: tanzukubernetescluster
  annotations:
    run.tanzu.vmware.com/resolve-tkr: ""
spec:
  controlPlane:
    metadata:
      annotations:
        run.tanzu.vmware.com/resolve-os-image: os-name=photon
    ref:
      apiVersion: controlplane.cluster.x-k8s.io/v1beta1
      kind: KubeadmControlPlaneTemplate
      name: "tkc-control-plane"
    machineInfrastructure:
      ref:
        kind: VSphereMachineTemplate
        apiVersion: vmware.infrastructure.cluster.x-k8s.io/v1beta1
        name: "tkc-control-plane"
    machineHealthCheck:
      maxUnhealthy: 100%
      nodeStartupTimeout: 2h0m0s
      unhealthyConditions:
        - status: Unknown
          timeout: 5m0s
          type: Ready
        - status: "False"
          timeout: 12m0s
          type: Ready
  infrastructure:
    ref:
      apiVersion: vmware.infrastructure.cluster.x-k8s.io/v1beta1
      kind: VSphereClusterTemplate
      name: "tkc-infrastructure"
  workers:
    machineDeployments:
      - class: node-pool  
        template:
          metadata:
            annotations:
              run.tanzu.vmware.com/resolve-os-image: os-name=photon            
          bootstrap:
            ref:
              kind: KubeadmConfigTemplate
              apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
              name: "tkc-md"
          infrastructure:
            ref:
              kind: VSphereMachineTemplate
              apiVersion: vmware.infrastructure.cluster.x-k8s.io/v1beta1
              name: "tkc-md"
        machineHealthCheck:
          maxUnhealthy: 100%
          nodeStartupTimeout: 2h0m0s
          unhealthyConditions:
            - status: Unknown
              timeout: 5m0s
              type: Ready
            - status: "False"
              timeout: 12m0s
              type: Ready
  variables:
    - name: TKR_DATA
      required: false
      schema:
        openAPIV3Schema:
          type: object
          additionalProperties:
            type: object
            properties:
              kubernetesSpec:
                type: object
                properties:
                  version:
                    type: string
                  imageRepository:
                    type: string
                  etcd:
                    type: object
                    properties:
                      imageTag:
                        type: string
                  coredns:
                    type: object
                    properties:
                      imageTag:
                        type: string
              osImageRef:
                type: object
                properties:
                  name:
                    type: string
              labels:
                type: object
                additionalProperties:
                  type: string
    - name: vmClass
      required: true
      schema:
        openAPIV3Schema:
          type: string
    - name: storageClass
      required: true
      schema:
        openAPIV3Schema:
          type: string
    - name: storageClasses
      required: false
      schema:
        openAPIV3Schema:
          type: array
          items:
            type: string
    - name: defaultStorageClass
      required: false
      schema:
        openAPIV3Schema:
          type: string
    - name: extensionCert
      required: false
      schema:
        openAPIV3Schema:
          type: object
          properties:
            contentSecret:
              type: object
              properties:
                name:
                  type: string
                key:
                  type: string
    - name: clusterEncryptionConfigYaml
      required: false
      schema:
        openAPIV3Schema:
          type: string
    - name: defaultRegistrySecret
      required: false
      schema:
        openAPIV3Schema:
          type: object
          properties:
            namespace:
              type: string
            name:
              type: string
            data:
              type: string
    - name: ntp
      required: false
      schema:
        openAPIV3Schema:
          type: string
    - name: user
      required: false
      schema:
        openAPIV3Schema:
          type: object
          properties:
            passwordSecret:
              type: object
              properties:
                name:
                  type: string
                key:
                  type: string
            sshAuthorizedKey:
              type: string
    - name: nodePoolTaints
      required: false
      schema:
        openAPIV3Schema:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
              effect:
                type: string
              timeAdded:
                type: integer
    - name: nodePoolLabels
      required: false
      schema:
        openAPIV3Schema:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
    - name: proxy
      required: false
      schema:
        openAPIV3Schema:
          type: object
          properties:
            httpProxy:
              type: string
            httpsProxy:
              type: string
            noProxy:
              type: array
              items:
                type: string
    - name: trust
      required: false
      schema:
        openAPIV3Schema:
          type: object
          properties:
            additionalTrustedCAs:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
    - name: controlPlaneVolumes
      required: false
      schema:
        openAPIV3Schema:
          type: array
          items:
            type: object
            properties:
              storageClass:
                type: string
              mountPath:
                type: string
              name:
                type: string
              capacity:
                type: object
                properties:
                  storage:
                    type: string                   
    - name: nodePoolVolumes
      required: false
      schema:
        openAPIV3Schema:
          type: array
          items:
            type: object
            properties:
              storageClass:
                type: string
              mountPath:
                type: string
              name:
                type: string
              capacity:
                type: object
                properties:
                  storage:
                    type: string

Variables ClusterClass pour personnaliser un cluster

Vous personnalisez un cluster en fonction de la classe de cluster ClusterClass tanzukubernetescluster à l'aide de variables. Les variables sont définies à l'aide de paires nom-valeurs. La syntaxe doit être conforme au openAPIV3Schema.

Deux variables sont requises pour provisionner un cluster à l'aide de l'API v1beta1 :

Classe de VM
Classe de stockage

Des variables supplémentaires sont disponibles pour personnaliser un cluster, telles que :

Proxy
Certificats TLS
Clés SSH

Le tableau suivant répertorie toutes les variables disponibles avec la ClusterClass tanzukubernetescluster par défaut.

clusterEncryptionConfigYaml

Utilisez la variable clusterEncryptionConfigYaml pour configurer le chiffrement du cluster.

clusterEncryptionConfigYaml

Chaîne qui est un fichier YAML fournissant des détails de configuration de chiffrement.

Vous pouvez configurer le chiffrement des données dans la base de données etcd à l'aide du module kube-apiserver Encryption Configuration. Reportez-vous à la section Encrypting Secret Data at Rest dans la documentation Kubernetes.

...
    variables:
    #clusterEncryptionConfigYaml specifies the base64 encoded 
    #EncryptionConfiguration YAML
    #the YAML contains a base64 encryption configuration for the cluster identity
    #the key is generated randomly
    - name: clusterEncryptionConfigYaml
      value: string which is name of the EncryptionConfiguration YAML

controlPlaneVolumes

Utilisez la variable controlPlaneVolumes pour configurer des volumes persistants pour les nœuds de plan de contrôle.

controlPlaneVolumes

Groupe facultatif d'objets, chacun d'eux incluant name, storageClass et mountPath, chacun d'eux étant des chaînes, ainsi qu'un objet capacity facultatif qui inclut une chaîne storage.

...
    variables:
      #controlPlaneVolumes is an optional set of PVCs to create and
      #attach to each node; use for high-churn components like etcd
      - name: controlPlaneVolumes
        value: |
          #name of the PVC to be used as the suffix (node.name)
          - name: etcd
            #mountPath is the directory where the volume device is mounted
            #takes the form /dir/path
            mountPath: /var/lib/etcd
            #storageClass is the storage class to use for the PVC
            storageClass: tkg2-storage-profile
            #capacity is the PVC storage capacity
            capacity:
              #storage sets the capacity for the disk volume
              #if not specified defaults to storageClass capacity
              storage: 4Gi

defaultRegistrySecret

Utilisez la variable defaultRegistrySecret pour configurer un registre de conteneur par défaut pour le cluster.

defaultRegistrySecret

Objet qui inclut une clé publique, un nom de certificat et un espace de noms pour un registre de conteneur par défaut.

Si vous activez le registre Harbor sur le Superviseur, la variable defaultRegistrySecret spécifie le certificat du service de registre que le cluster approuve. Le secret du certificat est étiqueté avec managed-by: vmware-vRegistry. Lors de la création du cluster, un certificat de registre par défaut est injecté dans la variable defaultRegistrySecret. Après la création du cluster, vous gérez la rotation des certificats ou toute mise à jour en mettant à jour manuellement la variable.

...
    variables:
    - name: defaultRegistrySecret
      value:
        #data holds the base64 encoded data.ca\.crt content
        #data.ca\.crt is already encoded, so raw cert data is encoded twice
        data: LS0tLS1CRUdJTiBDRVJU...S0tRU5EIENFUlRJRklDQVRFL
        #name specifies the name of the registry cert secret 
        name: harbor-ca-key-pair
        #namespace specifies the ns of the registry cert secret
        namespace: svc-harbor-domain-c9

defaultStorageClass

Utilisez la variable defaultStorageClass pour configurer une classe de stockage par défaut pour le cluster.

defaultStorageClass

Chaîne qui identifie la classe de stockage à utiliser comme classe de stockage par défaut, souvent requise par certaines applications telles que les graphiques Helm et les modules Tanzu.

...
    variables:
    - name: defaultStorageClass
      value: tkg2-storage-profile

extensionCert

Utilisez la variable extensionCert pour configurer un certificat TLS.

extensionCert

Objet contenant un objet contentSecret contenant des chaînes name et key. contentSecret fait référence à un objet secret Kubernetes créé pour un certificat TLS.

...
    variables:
    #extensionCert specifies the cert and key for Extensions Controller
    #self-signed issuer and certificates must be created in advance
    - name: extensionCert
      value: 
        contentSecret:
          #name specifies the name of secret
          name: string
          #key specifies the content of tls\.crt in the secret's data map
          key: string

nodePoolLabels

Utilisez la variable nodePoolLabels pour configurer des étiquettes pour les nœuds worker.

nodePoolLabels: Groupe d'un ou de plusieurs objets, chaque objet contenant une paire clé/valeur, ces deux éléments étant des chaînes.; Les étiquettes vous permettent d'organiser les objets système en fonction de vos besoins pour faciliter les requêtes et les rapports. Pour plus d'informations sur l'utilisation, reportez-vous à la documentation sur les étiquettes de Kubernetes.

nodePoolTaints

Utilisez la variable nodePoolTaints pour appliquer des rejets aux nœuds worker.

nodePoolTaints: Groupe d'objets, chaque objet contient un taint qui s'applique aux nœuds worker.; Chaque objet taint inclut une key (chaîne), une value (chaîne) et un effect (chaîne). Le système remplit le champ timeAdded lors de la création ou de la mise à jour.

nodePoolVolumes

Utilisez la variable nodePoolVolumes pour spécifier des volumes persistants pour les nœuds de cluster.

nodePoolVolumes

Groupe facultatif d'objets, chacun d'eux incluant name, storageClass et mountPath, chacun d'eux étant des chaînes, ainsi qu'un objet capacity facultatif qui inclut une chaîne storage.

...
    variables:
      #nodePoolVolumes is an optional set of PVCs to create and
      #attach to each node; use for high-churn components like containerd
      - name: nodePoolVolumes
        value: |
          #name of the PVC to be used as the suffix (node.name)
          - name: etcd
            #mountPath is the directory where the volume device is mounted
            #takes the form /dir/path
            mountPath: /var/lib/containerd
            #storageClass is the storage class to use for the PVC
            storageClass: tkg2-storage-profile
            #capacity is the PVC storage capacity
            capacity:
              #storage sets the capacity for the disk volume
              #if not specified defaults to storageClass capacity
              storage: 4Gi

ntp

Utilisez la variable ntp pour configurer un serveur NTP pour le cluster.

ntp

Chaîne qui est le nom de domaine complet ou l'adresse IP d'un serveur NTP.

La variable NTP spécifie le nom de domaine du serveur NTP, comme indiqué dans l’exemple. Le serveur NTP est injecté dans la variable de cluster lors de la création du cluster. Après la création du cluster, vous gérez la rotation des noms de serveur ou toute mise à jour en mettant à jour manuellement la variable du cluster.

...
    variables:
    - name: ntp
      value: time1.vmware.com

proxy

Utilisez la variable proxy pour configurer un serveur proxy pour le cluster.

proxy

Objet avec des paramètres faisant référence à un serveur proxy pour les connexions de cluster sortantes.

Les paramètres proxy requis sont httpProxy, httpsProxy et noProxy. Les trois champs sont requis si vous incluez la variable proxy dans la définition du cluster.

Les champs httpProxy et httpsProxy prennent des valeurs de chaînes faisant référence à l'URI d'un serveur proxy configuré pour gérer les connexions HTTP et HTTPS sortantes à partir du cluster TKG. Vous pouvez vous connecter au serveur proxy à l'aide de HTTP. Les connexions HTTPS ne sont pas prises en charge.

Le champ noProxy est un groupe de chaînes. Procurez-vous les valeurs de noProxy dans le réseau de charge de travail du Superviseur. Vous devez inclure dans le champ noProxy les sous-réseaux Réseau d'espace de noms, Entrée et Sortie.

Vous n'avez pas besoin d'inclure le sous-réseau Services dans le champ noProxy. Le cluster TKG n’interagit pas avec ce sous-réseau.

Vous n'avez pas besoin d'inclure les éléments clusterNetwork.services.cidrBlocks et clusterNetwork.pods.cidrBlocks dans le champ noProxy. Ces points de terminaison ne sont automatiquement mis en proxy pour vous.

Vous n'avez pas besoin d'inclure les éléments localhost et 127.0.0.1 dans le champ noProxy. Ces points de terminaison ne sont automatiquement mis en proxy pour vous.

...
    variables:
    #proxy specifies a proxy server to be used for the cluster
    #if omitted no proxy is configured
    - name: proxy
      value:
        #httpProxy is the proxy URI for HTTP connections
        #to endpoints outside the cluster
        httpProxy: http://<user>:<pwd>@<ip>:<port>
        #httpsProxy is the proxy URL for HTTPS connections 
        #to endpoints outside the cluster
        httpsProxy: http://<user>:<pwd>@<ip>:<port>
        #noProxy is the list of destination domain names, domains, 
        #IP addresses, and other network CIDRs to exclude from proxying
        #must include Supervisor Pod, Egress, Ingress CIDRs
        noProxy: [array of strings, comma-separated]

storageClass

Utilisez la variable storageClass pour configurer une classe de stockage pour le cluster.

storageClass

Chaîne qui est le nom d'un profil de stockage vSphere attribué à l' Espace de noms vSphere dans lequel le cluster TKG est provisionné.

...
    variables:
    - name: storageClass
      value: tkg2-storage-profile

Utilisez la commande suivante pour répertorier les classes de stockage disponibles :

kubectl describe namespace VSPHERE-NAMESPACE-NAME

Ou, si vous disposez de privilèges d'administrateur vSphere :

kubectl describe storageclasses

storageClasses

Utilisez la variable storageClasses pour configurer un tableau de classes de stockage pour le cluster.

storageClasses

Groupe d'une ou de plusieurs chaînes, chaque chaîne étant le nom d'un profil de stockage vSphere attribué à l' Espace de noms vSphere dans lequel le cluster TKG est provisionné.

...
    variables:
    - name: storageClasses
      value: [tkg2-storage-profile, tkg2-storage-profile-latebinding]

Utilisez la commande suivante pour répertorier les classes de stockage disponibles :

kubectl describe namespace VSPHERE-NAMESPACE-NAME

Ou, si vous disposez de privilèges d'administrateur vSphere :

kubectl describe storageclasses

TKR_DATA

Utilisez la variable TKR_DATA pour spécifier les informations TKR.

TKR_DATA: Objet que vous utilisez pour spécifier la version de TKR et d'autres informations.; version est une chaîne au format du nom de TKR qui doit être utilisée par les nœuds de cluster.; Seuls les TKR qui ne disposent pas de l'étiquette legacy-tkr sont compatibles avec TKG 2. Reportez-vous à la section Utilisation de versions de Tanzu Kubernetes avec les clusters TKG 2 sur le Superviseur.; Le système d'exploitation par défaut est PhotonOS. Utilisez des annotations pour spécifier la TKR Ubuntu.

trust

Utilisez la variable trust pour spécifier un ou plusieurs certificats d'autorité de certification approuvés pour le cluster.

trust

Objet permettant d'ajouter des certificats TLS au cluster : autorités de certification supplémentaires ou certificats de fin.

La valeur est additionalTrustedCAs, qui est un groupe de chaînes. Chaque chaîne est le nom du secret Kubernetes qui contient le contenu du certificat approuvé supplémentaire dans la chaîne codée en base64 au format PEM.

Pour configurer une variable trust :

Créez un fichier YAML de définition de secret Kubernetes avec le contenu suivant.
```
apiVersion: v1
data:
  additional-ca-1: TFMwdExTMUNSGlSzZ3Jaa...VVNVWkpRMEMwdExTMHRDZz09
kind: Secret
metadata:
  name: cluster01-user-trusted-ca-secret
  namespace: tkg2-cluster-ns
type: Opaque
```
Le contenu de la carte de données du secret est un nom défini par l'utilisateur pour le certificat ( additional-ca-1), dont la valeur est un certificat doublement codé en base64.
Note : Un double codage base64 est requis. Si le contenu de la valeur de la carte de données n'est pas doublement codé en base64, le fichier PEM qui en résulte ne peut pas être traité.

Nommez le secret CLUSTER-NAME-user-trusted-ca-secret, où CLUSTER-NAME est le nom du cluster. Ce secret doit être créé dans le même Espace de noms vSphere que le cluster.
Créez le secret Kubernetes à l'aide de kubectl -f apply additional-ca-1.yaml.

Vérifiez la création du secret.

kubeclt get secret -n tkg2-cluster-ns cluster01-user-trusted-ca-secret
NAME                                             TYPE     DATA   AGE
cluster01-user-trusted-ca-secret                   Opaque   12     2d22h

Incluez la variable trust dans la spécification de cluster qui fait référence à la valeur name de la carte de données pour le secret, qui est additional-ca-1 dans cet exemple.

spec:
  clusterNetwork:
    pods:
      cidrBlocks:
      - 193.0.0.0/16
    serviceDomain: cluster.local
    services:
      cidrBlocks:
      - 198.201.0.0/16
  topology:
    class: tanzukubernetescluster
    controlPlane:
      metadata: {}
      replicas: 3
    variables:
    - name: storageClass
      value: tkg2-storage-profile
    - name: trust
      value:
        additionalTrustedCAs:
        - name: additional-ca-1

utilisateur

Utilisez la variable user pour spécifier les informations d'identification de l'utilisateur du cluster.

utilisateur

Objet qui inclut un objet passwordSecret avec des chaînes de nom et de clé et une chaîne sshAuthorizedKey. Vous pouvez utiliser cette variable pour ajouter la clé SSH d'un utilisateur aux nœuds de cluster pour l'accès SSH distant.

La variable Utilisateur spécifie les informations d'identification de connexion SSH, notamment le mot de passe et les clés autorisées. Le nom d'utilisateur par défaut est vmware-system-user. Le mot de passe doit être haché et stocké dans un secret dans le même espace de noms que celui dans lequel le cluster est provisionné. L'objet passwordSecret fait référence à ce secret. Par exemple, sous Linux, vous pouvez générer un hachage sécurisé à l'aide de mkpasswd --method=SHA-512 --rounds=4096. Pour plus d'informations, reportez-vous à la section Including users and groups.

...
    variables:
    #user specifies an authorized user and credentials
    - name: user
      value:
        #passwordSecret is an object that contains a Kubernetes secret and key
        passwordSecret:
          #name specifies the secret name
          name: string
          #key specifies the key value pair in the secret's data map
          key: string
        sshAuthorizedKey: string that is the base64-encoded public key

vmClass

Utilisez la variable vmClass pour configurer la classe de machine virtuelle pour les nœuds du cluster.

vmClass

Chaîne requise qui se mappe au nom d'une classe de machine virtuelle liée à l' Espace de noms vSphere dans lequel le cluster TKG est provisionné.

vmClass est le nom de la classe VirtualMachineClass qui décrit les paramètres de matériel virtuel à utiliser pour les nœuds de cluster. VirtualMachineClass contrôle le CPU et la mémoire disponibles pour le nœud, ainsi que les demandes et limites sur ces ressources. Reportez-vous à la section Utilisation de classes de machines virtuelles avec des clusters TKG 2 sur le Superviseur.

Vous pouvez uniquement utiliser des classes de machine virtuelle qui sont liées à l' Espace de noms vSphere dans lequel le cluster TKG est en cours de provisionnement. Utilisez la commande kubectl get virtualmachineclassbinding pour répertorier les classes liées.

Vous pouvez définir la variable vmClass à différentes portées afin de pouvoir utiliser différentes classes de machine virtuelle pour les nœuds de plan de contrôle et les nœuds worker de pool de nœuds.

Par exemple, ici, une variable vmClass en ligne overrides la variable vmClass principale pour cette topologie de déploiement de machines spécifique.

...
    workers:
      machineDeployments:
      - class: tkg-worker
        name: compute
        replicas: 3
        variables:
          overrides:
          - name: vmClass
            value: guaranteed-large