Résoudre les problèmes de création ou de mise à niveau des clusters

Cette page explique comment examiner les problèmes de création et de mise à niveau de clusters dans Google Distributed Cloud (logiciel uniquement) pour VMware.

Si vous avez besoin d'aide supplémentaire, contactez l'assistance Cloud Customer Care.

Problèmes d'installation

Les sections suivantes peuvent vous aider à résoudre les problèmes d'installation de Google Distributed Cloud.

Utiliser le cluster d'amorçage pour déboguer les problèmes

Lors de l'installation, Google Distributed Cloud crée un cluster d'amorçage temporaire. Après une installation réussie, Google Distributed Cloud supprime le cluster d'amorçage, vous laissant ainsi votre cluster d'administrateur et votre cluster d'utilisateur. En règle générale, vous ne devriez avoir aucune raison d'interagir avec le cluster d'amorçage. Toutefois, si vous rencontrez des problèmes lors de l'installation, vous pouvez utiliser les journaux du cluster d'amorçage pour vous aider à résoudre le problème.

Si vous transmettez --cleanup-external-cluster=false à gkectl create cluster, le cluster d'amorçage n'est pas supprimé et vous pouvez l'utiliser pour déboguer les problèmes d'installation.

Examiner les journaux du cluster d'amorçage

1. Recherchez les noms des pods en cours d'exécution dans l'espace de noms kube-system:

   kubectl --kubeconfig /home/ubuntu/.kube/kind-config-gkectl get pods -n kube-system
   

2. Affichez les journaux d'un pod:

   kubectl --kubeconfig /home/ubuntu/.kube/kind-config-gkectl -n kube-system get logs POD_NAME
   

   Remplacez POD_NAME par le nom du pod que vous souhaitez afficher.

3. Pour obtenir les journaux directement à partir du cluster d'amorçage, exécutez la commande suivante lors de la création, de la mise à jour et de la mise à niveau du cluster :

   docker exec -it gkectl-control-plane bash
   

   Cette commande ouvre un terminal dans le conteneur gkectl-control-plane qui s'exécute dans le cluster d'amorçage.

4. Pour inspecter les journaux kubelet et containerd, utilisez les commandes suivantes et recherchez toute erreur ou tout avertissement dans le résultat :

   systemctl status -l kubelet
   journalctl --utc -u kubelet
   systemctl status -l containerd
   journalctl --utc -u containerd
   

Examiner l'instantané du cluster d'amorçage

Si vous tentez de créer ou de mettre à niveau un cluster d'administrateur et que l'opération échoue, Google Distributed Cloud prend un instantané externe du cluster d'amorçage. Cet instantané du cluster d'amorçage est semblable à l'instantané pris en exécutant la commande gkectl diagnose snapshot sur le cluster d'administrateur, mais le processus se déclenche automatiquement. L'instantané du cluster d'amorçage contient des informations de débogage importantes pour le processus de création et de mise à niveau du cluster d'administrateur. Vous pouvez fournir cet instantané à Cloud Customer Care si nécessaire.

L'instantané externe inclut les journaux de pod de la ressource onprem-admin-cluster-controller que vous pouvez afficher pour déboguer les problèmes de création ou de mise à niveau du cluster. Les journaux sont stockés dans un fichier distinct, par exemple:

kubectl_logs_onprem-admin-cluster-controller-6767f6597-nws8g_ \
    --container_onprem-admin-cluster-controller_ \
    --kubeconfig_.home.ubuntu..kube.kind-config-gkectl_\
    --namespace_kube-system

La VM ne démarre pas après le démarrage du plan de contrôle d'administrateur

Si une VM ne démarre pas après le démarrage du plan de contrôle d'administrateur, vous pouvez examiner le problème en inspectant les journaux du pod des contrôleurs d'API Cluster du cluster d'administrateur :

1. Recherchez le nom du pod des contrôleurs d'API Cluster:

   kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG --namespace kube-system \
       get pods | grep clusterapi-controllers
   

2. Affichez les journaux de vsphere-controller-manager. Commencez par spécifier le pod, mais sans le conteneur :

   kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG --namespace kube-system \
       logs POD_NAME
   

   Le résultat vous indique que vous devez spécifier un conteneur et qu'il vous donne les noms des conteneurs du pod. Exemple :

   ... a container name must be specified ...,
   choose one of: [clusterapi-controller-manager vsphere-controller-manager rbac-proxy]
   

3. Choisissez un conteneur et affichez ses journaux:

   kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG --namespace kube-system \
       logs POD_NAME --container CONTAINER_NAME
   

Un nombre suffisant d'adresses IP est alloué, mais la machine ne parvient pas à s'enregistrer auprès du cluster

Ce problème peut survenir en cas de conflit d'adresses IP. Par exemple, une adresse IP que vous avez spécifiée pour une machine est utilisée pour un équilibreur de charge.

Pour résoudre ce problème, mettez à jour le fichier de bloc d'adresses IP du cluster afin que les adresses des machines n'entrent pas en conflit avec les adresses spécifiées dans votre fichier de configuration du cluster ou votre fichier de blocs d'adresses IP Seesaw.

Problèmes de mise à niveau du cluster

Les sections suivantes fournissent des conseils pour résoudre les problèmes que vous pouvez rencontrer lors d'une mise à niveau du cluster.

Effectuer un rollback d'un pool de nœuds après une mise à niveau

Si vous mettez à niveau un cluster d'utilisateurs et que vous constatez ensuite un problème avec les nœuds du cluster, vous pouvez effectuer un rollback et rétablir la version précédente des pools de nœuds sélectionnés.

Le rollback des pools de nœuds sélectionnés est possible pour les pools de nœuds Ubuntu et COS, mais pas pour les pools de nœuds Windows.

La version d'un pool de nœuds peut être identique ou antérieure d'une version mineure à celle du plan de contrôle du cluster d'utilisateur. Par exemple, si le plan de contrôle est en version 1.14, les pools de nœuds peuvent être en version 1.14 ou 1.13.

Afficher les versions de pool de nœuds disponibles

Supposons que vous ayez récemment mis à niveau les nœuds de calcul et le plan de contrôle de votre cluster d'utilisateur de la version 1.13.1-gke.35 à la version 1.14.0, et que vous constatiez un problème avec les nœuds de calcul mis à niveau. Vous décidez donc de restaurer un ou plusieurs pools de nœuds à la version que vous utilisiez auparavant : 1.13.1-gke.35. Avant de pouvoir commencer le rollback, vous devez vérifier que la version précédente est disponible pour le rollback.

Pour afficher les versions disponibles, exécutez la commande suivante :

gkectl version --cluster-name USER_CLUSTER_NAME \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG

La sortie affiche la version actuelle et la version précédente de chaque pool de nœuds. Exemple :

user cluster version: 1.14.0-gke.x

node pools:
- pool-1:
  - version: 1.14.0-gke.x
  - previous version: 1.13.1-gke.35
- pool-2:
  - version: 1.14.0-gke.x
  - previous version: 1.13.1-gke.35

available node pool versions:
- 1.13.1-gke.35
- 1.14.0-gke.x

Effectuer un rollback de la version d'un pool de nœuds

Vous pouvez effectuer le rollback de la version d'un pool de nœuds en procédant un pool de nœuds à la fois, ou effectuer le rollback de plusieurs pools de nœuds en une seule étape.

Pour effectuer le rollback d'une version de pool de nœuds, procédez comme suit :

1. Dans le fichier de configuration de votre cluster d'utilisateur, dans un ou plusieurs pools de nœuds, définissez la valeur de gkeOnPremVersion sur la version précédente. L'exemple suivant montre comment revenir à la version 1.13.1-gke.35 :

   nodePools:
   - name: pool-1
     cpus: 4
     memoryMB: 8192
     replicas: 3
     gkeOnPremVersion: 1.13.1-gke.35
     ...
   

2. Mettez à jour le cluster pour effectuer le rollback du ou des pools de nœuds :

   gkectl update cluster --config USER_CLUSTER_CONFIG \
       --kubeconfig ADMIN_CLUSTER_KUBECONFIG
   

3. Vérifiez que le rollback a bien fonctionné :

   gkectl version --cluster-name USER_CLUSTER_NAME \
       --kubeconfig ADMIN_CLUSTER_KUBECONFIG
   

   La sortie suivante montre que pool-1 a été rétabli à la version 1.13.1-gke.35.

   user cluster version: 1.14.0-gke.x
   
   node pools:
   - pool-1:
     - version: 1.13.1-gke.35
     - previous version: 1.14.0-gke.x
   - pool-2:
     - version: 1.14.0-gke.x
     - previous version: 1.13.1-gke.35
   
   available node pool versions:
   - 1.13.1-gke.35
   - 1.14.0-gke.x
   

Effectuer une mise à niveau vers une nouvelle version de correctif

Vous pouvez mettre à niveau tous les pools de nœuds et le plan de contrôle vers une nouvelle version de correctif. Cela peut être utile si vous êtes revenu à une version précédente et que vous souhaitez passer à une version qui inclut un correctif.

Pour effectuer la mise à niveau vers une nouvelle version, procédez comme suit :

1. Effectuez les modifications suivantes dans le fichier de configuration de votre cluster d'utilisateur :

   1. Définissez la valeur de gkeOnPremVersion sur une nouvelle version de correctif. Cet exemple utilise la version 1.14.1-gke.x.

   2. Pour chaque pool de nœuds, supprimez le champ gkeOnPremVersion ou définissez-le sur une chaîne vide. Lorsqu'aucune version n'est spécifiée pour un pool de nœuds, la version du pool de nœuds est définie par défaut sur la version spécifiée pour le cluster.

      Ces modifications ressemblent à l'exemple suivant :

      gkeOnPremVersion: 1.14.1-gke.x
      
      nodePools:
      -   name: pool-1
        cpus: 4
        memoryMB: 8192
        replicas: 3
        gkeOnPremVersion: ""
      -   name: pool-2
        cpus: 8
        memoryMB: 8192
        replicas: 2
        gkeOnPremVersion: ""
      

2. Exécutez gkectl prepare et gkectl upgrade cluster comme décrit dans la section Mettre à niveau Google Distributed Cloud.

3. Vérifiez la nouvelle version du cluster et consultez les versions disponibles pour le rollback :

   gkectl version --cluster-name USER_CLUSTER_NAME \
       --kubeconfig ADMIN_CLUSTER_KUBECONFIG
   

   Le résultat ressemble à ce qui suit :

    user cluster version: 1.14.1-gke.y
   
    node pools:
    - pool-1:
      - version: 1.14.1-gke.y
      - previous version: 1.13.1-gke.35
    - pool-2:
      - version: 1.14.1-gke.y
      - previous version: 1.13.1-gke.35
   
    available node pool versions:
    - 1.13.1-gke.35
    - 1.14.0-gke.x
    - 1.14.1-gke.y
    ```
   

Les vérifications d'état sont exécutées automatiquement en cas d'échec de la mise à niveau du cluster.

Si vous tentez de mettre à niveau un cluster d'administrateur ou d'utilisateur et que cette opération échoue, Google Distributed Cloud exécute automatiquement la commande gkectl diagnose cluster sur le cluster.

Pour ignorer le diagnostic automatique, transmettez l'option --skip-diagnose-cluster à gkectl upgrade.

Le processus de mise à niveau est bloqué

Lors d'une mise à niveau, Google Distributed Cloud utilise la commande Kubernetes drain en arrière-plan. Cette procédure drain peut être bloquée par un déploiement si une seule instance répliquée bénéficie d'un PodDisruptionBudget (PDB) créé avec minAvailable: 1.

À partir de la version 1.13 de Google Distributed Cloud, vous pouvez vérifier les échecs via les événements de pod Kubernetes.

1. Recherchez les noms des machines:

   kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get machines --all-namespaces
   

2. Recherchez les erreurs à l'aide de la commande kubectl describe machine:

   kubectl --kubeconfig USER_CLUSTER_KUBECONFIG describe machine MACHINE_NAME
   

   Le résultat ressemble à ce qui suit :

   Events:
     Type     Reason              Age    From                Message
     ----     ------              ----   ----                -------
     Warning  PodEvictionTooLong  3m49s  machine-controller  Waiting too long(12m10.284294321s) for pod(default/test-deployment-669b85c4cc-z8pz7) eviction.
   

3. Facultatif : Pour une analyse plus détaillée de l'état des objets machine, exécutez gkectl diagnose cluster.

   Le résultat ressemble à ce qui suit :

   ...
   Checking machineset...SUCCESS
   Checking machine objects...FAILURE
       Reason: 1 machine objects error(s).
       Unhealthy Resources:
       Pod test-deployment-669b85c4cc-7zjpq: Pod cannot be evicted successfully. There is 1 related PDB.
   ...
   Checking all poddisruptionbudgets...FAILURE
       Reason: 1 pod disruption budget error(s).
       Unhealthy Resources:
       PodDisruptionBudget test-pdb: default/test-pdb might be configured incorrectly, the total replicas(3) should be larger than spec.MinAvailable(3).
   ...
   Some validation results were FAILURE or UNKNOWN. Check report above.
   

Pour résoudre ce problème, enregistrez le budget d'interruption de pod (PDB) et supprimez-le du cluster avant d'effectuer la mise à niveau. Vous pourrez ensuite rajouter le PDB une fois la mise à niveau terminée.

Supprimer les modifications non compatibles pour débloquer la mise à niveau

Lorsque vous mettez à niveau des clusters vers la version 1.16 ou une version antérieure, les modifications apportées à la plupart des champs sont ignorées de manière silencieuse lors de la mise à niveau. Autrement dit, ces modifications n'entrent pas en vigueur pendant et après la mise à niveau.

Lorsque vous mettez à niveau des clusters d'utilisateur vers la version 1.28 ou une version ultérieure, nous validons toutes les modifications apportées au fichier de configuration et renvoyons une erreur pour les modifications non compatibles au lieu de les ignorer. Cette fonctionnalité est réservée aux clusters d'utilisateur. Lors de la mise à niveau des clusters d'administrateur, les modifications apportées à la plupart des champs sont ignorées et n'entrent pas en vigueur après la mise à niveau.

Par exemple, si vous essayez de désactiver la réparation automatique des nœuds lors de la mise à niveau d'un cluster d'utilisateur vers la version 1.28, la mise à niveau échoue et le message d'erreur suivant s'affiche :

failed to generate desired create config: failed to generate desired OnPremUserCluster from seed config: failed to apply validating webhook to OnPremUserCluster: the following changes on immutable fields are forbidden during upgrade: (diff: -before, +after):
   v1alpha1.OnPremUserClusterSpec{
    ... // 20 identical fields
    UsageMetering:         nil,
    CloudAuditLogging:     &{ProjectID: "syllogi-partner-testing", ClusterLocation: "us-central1", ServiceAccountKey: &{KubernetesSecret: &{Name: "user-cluster-creds", KeyName: "cloud-audit-logging-service-account-key"}}},
-   AutoRepair:            &v1alpha1.AutoRepairConfig{Enabled: true},
+   AutoRepair:            &v1alpha1.AutoRepairConfig{},
    CARotation:            &{Generated: &{CAVersion: 1}},
    KSASigningKeyRotation: &{Generated: &{KSASigningKeyVersion: 1}},
    ... // 8 identical fields
  }

Pour contourner cette erreur, vous pouvez utiliser les solutions de contournement suivantes :

• Annulez la modification que vous avez tenté d'apporter, puis relancez la mise à niveau. Par exemple, dans le scénario précédent, vous pouvez annuler les modifications apportées à la configuration AutoRepair, puis exécuter à nouveau gkectl upgrade.
• Vous pouvez également générer des fichiers de configuration correspondant à l'état actuel du cluster en exécutant gkectl get-config, en mettant à jour les champs gkeOnPremVersion pour le cluster et les pools de nœuds dans le fichier de configuration, puis en réexécutant gkectl upgrade.

Déboguer les problèmes liés à F5 BIG-IP à l'aide du fichier kubeconfig interne

Après une installation, Google Distributed Cloud génère un fichier kubeconfig nommé internal-cluster-kubeconfig-debug dans le répertoire d'accueil de votre poste de travail d'administrateur. Ce fichier kubeconfig est identique au fichier kubeconfig de votre cluster d'administrateur, sauf qu'il pointe directement vers le nœud de plan de contrôle du cluster d'administrateur, où s'exécute le serveur d'API Kubernetes. Vous pouvez utiliser le fichier internal-cluster-kubeconfig-debug pour résoudre les problèmes liés à F5 BIG-IP.

Déboguer les problèmes liés à vSphere

Vous pouvez utiliser govc pour examiner les problèmes liés à vSphere. Par exemple, vous pouvez confirmer les autorisations et l'accès de vos comptes utilisateur vCenter, et collecter les journaux vSphere.

Recréer le fichier kubeconfig manquant du cluster d'utilisateur

Vous pouvez avoir besoin de recréer un fichier kubeconfig de cluster d'utilisateur dans les situations suivantes :

• Si vous tentez de créer un cluster d'utilisateur et que l'opération de création échoue mais que vous souhaitez obtenir le fichier kubeconfig de cluster d'utilisateur.
• Si le fichier kubeconfig de cluster d'utilisateur est manquant, par exemple après sa suppression.

Pour générer un nouveau fichier kubeconfig pour votre cluster d'utilisateur, procédez comme suit :

1. Définissez des variables d'environnement :

   Commencez par définir les variables d'environnement suivantes avec les valeurs appropriées :

   USER_CONTROLPLANEVIP=USER_CONTROLPLANEVIP
   USER_CLUSTER_NAME=USER_CLUSTER_NAME
   ADMIN_CLUSTER_KUBECONFIG=PATH_TO_ADMIN_KUBECONFIG
   KUBECONFIG_SECRET_NAME=$(kubectl --kubeconfig $ADMIN_CLUSTER_KUBECONFIG get secrets -n $USER_CLUSTER_NAME | grep ^admin | cut -d' ' -f1 | head -n 1)
   

   Remplacez les éléments suivants :

   • ADMIN_CLUSTER_KUBECONFIG : chemin d'accès au fichier kubeconfig pour votre cluster d'administrateur.
   • USER_CONTROLPLANEVIP : controlPlaneVIP du cluster d'utilisateur. Vous pouvez récupérer cette valeur dans le fichier manifeste du cluster d'utilisateur.

2. Générez le fichier Kubeconfig :

   Exécutez la commande suivante pour créer le nouveau fichier kubeconfig :

   kubectl --kubeconfig $ADMIN_CLUSTER_KUBECONFIG get secrets $KUBECONFIG_SECRET_NAME \
    -n $USER_CLUSTER_NAME -o jsonpath='{.data.admin\.conf}'  | base64 -d | \
    sed -r "s/ kube-apiserver.*local\./${USER_CONTROLPLANEVIP}/" \
    > USER_CLUSTER_KUBECONFIG
   

   Remplacez :

   • USER_CLUSTER_KUBECONFIG : nom du nouveau fichier kubeconfig pour votre cluster d'utilisateur.

Étape suivante

• Si vous avez besoin d'une aide supplémentaire, contactez Cloud Customer Care.