Résoudre les problèmes liés à la création ou à la mise à niveau d'un cluster

Cette page vous explique comment examiner les problèmes de création et de mise à niveau de clusters dans Google Distributed Cloud.

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 liés à l'installation de Google Distributed Cloud.

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

Lors de l'installation, GKE sur VMware crée un cluster d'amorçage temporaire. Après une installation réussie, GKE sur VMware supprime le cluster d'amorçage, vous laissant 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 les résoudre à l'aide des journaux du cluster d'amorçage.

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, la mise à jour et 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 les erreurs ou les avertissements 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 cette 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 onprem-admin-cluster-controller que vous pouvez consulter 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 administrateur

Si une VM ne démarre pas après le démarrage du plan de contrôle administrateur, vous pouvez examiner le problème en inspectant les journaux du pod des contrôleurs d'API Cluster dans le 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 pas de 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 de cluster ou dans votre fichier de bloc d'adresses IP Seesaw.

Problèmes de mise à niveau du cluster

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

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

Si vous mettez à niveau un cluster d'utilisateur, puis que vous découvrez un problème avec les nœuds du cluster, vous pouvez effectuer un rollback des pools de nœuds sélectionnés vers la version précédente.

Le rollback des pools de nœuds sélectionnés est compatible avec 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 à la version du plan de contrôle du cluster d'utilisateur, ou à une version mineure antérieure. Par exemple, si le plan de contrôle est de la version 1.14, les pools de nœuds peuvent être de 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 vers la version 1.14.0, et que vous découvriez un problème avec les nœuds de calcul mis à niveau. Vous décidez donc d'effectuer le rollback d'un ou de plusieurs pools de nœuds vers la version que vous exécutiez précédemment : 1.13.1-gke.35. Avant de 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

Le résultat affiche la version actuelle et la version précédente pour 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 du pool de nœuds

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

Pour effectuer un rollback de la version d'un 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 gkeOnPremVersion sur la version précédente. L'exemple suivant vous montre comment effectuer un rollback vers 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 un rollback des pools de nœuds :

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

3. Vérifiez que le rollback a bien été effectué:

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

   Le résultat suivant montre que pool-1 a fait l'objet d'un rollback vers 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 la mise à niveau vers une nouvelle version du 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 effectuez un rollback vers une version précédente et souhaitez passer à une version qui inclut un correctif.

Pour passer à une nouvelle version, procédez comme suit:

1. Apportez 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 1.14.1-gke.x.

   2. Pour chaque pool de nœuds, supprimez le champ gkeOnPremVersion ou définissez-le sur la 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 se présentent comme dans 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 affichez 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'indicateur --skip-diagnose-cluster à gkectl upgrade.

Le processus de mise à niveau est bloqué

En arrière-plan, Google Distributed Cloud utilise la commande Kubernetes drain lors d'une mise à niveau. Cette procédure drain peut être bloquée par un déploiement avec une seule instance répliquée pour laquelle un PodDisruptionBudget (PDB) a été 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 obtenir une analyse plus détaillée de l'état des objets machine, exécutez la commande 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 PDB et supprimez-le du cluster avant de tenter la mise à niveau. Vous pourrez ensuite ajouter à nouveau le PDB une fois la mise à niveau terminée.

Supprimez 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 en mode silencieux lors de la mise à niveau. Ces modifications ne prennent donc pas effet pendant et après la mise à niveau.

Lors de la mise à niveau des clusters d'utilisateur vers la version 1.28 ou une version ultérieure, nous validons toutes les modifications apportées dans le fichier de configuration et renvoyons une erreur pour les modifications non compatibles, au lieu de simplement les ignorer. Cette fonctionnalité n'est disponible que pour les clusters d'utilisateur. Lors de la mise à niveau des clusters d'administrateur, les modifications apportées à la plupart des champs sont ignorées en mode silencieux et ne prennent pas effet après la mise à niveau.

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

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, plusieurs solutions s'offrent à vous:

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

Déboguer les problèmes F5 BIG-IP avec le fichier kubeconfig interne

Après une installation, GKE sur VMware génère un fichier kubeconfig nommé internal-cluster-kubeconfig-debug dans le répertoire d'accueil de votre poste de travail 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 F5 BIG-IP.

Déboguer les problèmes avec 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 recréer un fichier kubeconfig de cluster d'utilisateur dans les situations suivantes:

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

Exécutez la commande suivante pour recréer le fichier kubeconfig du cluster d'utilisateur:

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG get secrets -n admin \
  -o jsonpath='{.data.admin\.conf}' | base64 -d  > USER_CLUSTER_KUBECONFIG

Remplacez les éléments suivants :

• USER_CLUSTER_KUBECONFIG: nom du nouveau fichier kubeconfig pour votre cluster d'utilisateur.
• ADMIN_CLUSTER_KUBECONFIG: chemin d'accès au fichier kubeconfig pour votre cluster d'administrateur.

Étapes suivantes

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