Ce document a été traduit à l'aide d'une technologie de traduction automatique. Bien que nous nous efforcions de fournir des traductions exactes, nous ne fournissons aucune garantie quant à l'exhaustivité, l'exactitude ou la fiabilité du contenu traduit. En cas de divergence, la version originale anglaise prévaut et fait foi.

Dépannage des Rancher Turtles

Ce guide fournit des étapes de dépannage pour les Rancher Turtles et les clusters Cluster API (CAPI). Il couvre les problèmes courants et leurs résolutions pour vous aider à maintenir un environnement stable et fonctionnel.

Avant de lire ce guide, vous pouvez d’abord consulter la documentation officielle troubleshooting du projet CAPI.

Comprendre les subtilités des Rancher Turtles et de CAPI est crucial pour un dépannage efficace. Ce guide vise à vous fournir les connaissances nécessaires pour diagnostiquer et résoudre les problèmes de base dans Rancher Turtles et CAPI.

Conditions préalables

Pour dépanner efficacement les Rancher Turtles et les clusters CAPI, vous avez besoin de :

  • Accès à un terminal avec kubectl configuré pour accéder au cluster de gestion Rancher.

  • Le gestionnaire de plugins Krew pour kubectl installé.

  • L’outil en ligne de commande Helm installé.

Vous pouvez installer Krew en suivant les instructions dans le guide d’installation de Krew.

Comment vérifier les journaux

Vous pouvez visualiser les pods suivants et vérifier leurs journaux dans les espaces de noms suivants :

Espace de noms Déploiement Description

cattle-turtles-system

rancher-turtles-controller-manager

Gère l’intégration de Rancher et gère les ressources personnalisées pour Turtles

fleet-addon-system

caapf-controller-manager

Contrôle le cadre du fournisseur d’API de cluster pour les fournisseurs d’infrastructure personnalisés

cattle-capi-system

capi-controller-manager

Contrôleur principal de l’API de cluster qui réconcilie les ressources principales du cluster

rke2-bootstrap-system

rke2-bootstrap-controller-manager

Gère la configuration de démarrage pour les nœuds RKE2

rke2-control-plane-system

rke2-control-plane-controller-manager

Gère l’initialisation et la gestion des composants du plan de contrôle RKE2

*-système

*-controller-manager

Gère l’initialisation et la gestion des composants du fournisseur d’infrastructure

$-bootstrap-system

$-bootstrap-controller-manager

Gère la configuration de démarrage pour les fournisseurs personnalisés

$-control-plane-system

$-control-plane-controller-manager

Gère l’initialisation et la gestion des composants du plan de contrôle des fournisseurs personnalisés

'*' - en fonction du fournisseur d’infrastructure utilisé '$' - en fonction du fournisseur de plan de contrôle/démarrage utilisé, par exemple kubeadm ou rke2

Une façon de surveiller les journaux des pods du plan de contrôle de l’API de cluster est d’utiliser kubectl logs avec le sélecteur d’étiquettes.

kubectl logs -l control-plane=controller-manager -n cattle-turtles-system -f
kubectl logs -l control-plane=controller-manager -n cattle-capi-system -f
kubectl logs -l control-plane=controller-manager -n rke2-bootstrap-system -f
kubectl logs -l control-plane=controller-manager -n rke2-control-plane-system -f

Utiliser kubectl krew pour installer le plugin stern implique des logiciels tiers qui peuvent poser des risques de sécurité dans les environnements de production. Bien que ce soit un outil utile pour la visualisation des journaux, il devrait être principalement utilisé dans des environnements de développement ou de test. Examinez toujours les plugins tiers avant de les installer dans des clusters sensibles ou de production.

La meilleure méthode pour surveiller les journaux de différents pods est d’utiliser la méthode suivante.

kubectl krew install stern

Vous pouvez ensuite suivre les journaux de tous les pods en temps réel.

kubectl stern . -n cattle-turtles-system -n rke2-bootstrap-system -n rke2-control-plane-system -n cattle-capi-system

ou

kubectl stern -A -l control-plane=controller-manager

Comment gérer les Rancher Turtles et les ressources CAPI

Liste des ressources Rancher et Cluster API

Les utilisateurs demandent souvent comment ils peuvent gérer de longues listes de différents CRD créés par CAPI et Rancher. Voici quelques idées sur la façon de les gérer.

  1. Listez toutes les informations d’identification liées à CAPI et à Rancher.

    kubectl api-resources | grep 'cattle.io\|cluster.x-k8s.io'

  2. Découvrez la ressource. Vous pouvez obtenir une explication complète de ce qu’elle fait ou des options de configuration disponibles.

    kubectl api-resources | grep clusterclass
kubectl explain clusterclass.cluster.x-k8s.io

  3. Vous recevrez ensuite une description de chaque champ et section de configuration.

    kubectl explain clusterclass.spec
kubectl explain clusterclass.spec.controlPlane
kubectl explain clusterclasses.spec.controlPlane.machineInfrastructure

Liste des objets existants des ressources Rancher et Cluster API

L’erreur la plus courante est d’utiliser l’espace de noms default dans Kubernetes pour votre travail. Cela rend votre configuration vraiment désordonnée et difficile à gérer et à dépanner. Nous recommandons fortement d’utiliser des espaces de noms séparés pour déployer et créer des clusters en aval CAPI et d’éviter d’utiliser les espaces de noms système de Kubernetes, tels que default et kube-*.

Lors de l’application de modèles avec kubectl, spécifiez toujours -n <NAMESPACE> pour provisionner des ressources dans un emplacement connu. Vous pouvez basculer entre les espaces de noms dans KUBECONFIG avec cette commande :

kubectl config view
kubectl config set-context --current --namespace <NAMESPACE>

Avec des espaces de noms séparés, vous pouvez facilement gérer les ressources en suivant cette méthode.

Utiliser kubectl krew pour installer le plugin lineage implique des logiciels tiers qui peuvent poser des risques de sécurité dans les environnements de production. Bien que ce soit un outil utile pour la visualisation des journaux, il devrait être principalement utilisé dans des environnements de développement ou de test. Examinez toujours les plugins tiers avant de les installer dans des clusters sensibles ou de production.

  1. Installez les plugins get-all et lineage en utilisant krew pour kubectl.

    kubectl krew install lineage
kubectl krew install get-all

  2. Ensuite, listez toutes les ressources existantes dans l’espace de noms, par exemple capi-clusters, où votre configuration de cluster en aval est déployée.

    kubectl get-all -n capi-clusters

    Exemple de sortie :

    NAME                                                                                      NAMESPACE      AGE
configmap/kube-root-ca.crt                                                                capi-clusters  23h
secret/cluster1-shim                                                                     capi-clusters  32s
serviceaccount/default                                                                    capi-clusters  23h
rke2config.bootstrap.cluster.x-k8s.io/cluster1-mp-0-dm59p                                capi-clusters  32s
rke2config.bootstrap.cluster.x-k8s.io/cluster1-mp-1-gv6kh                                capi-clusters  32s
rke2configtemplate.bootstrap.cluster.x-k8s.io/cluster1-pool0                             capi-clusters  33s
rke2configtemplate.bootstrap.cluster.x-k8s.io/cluster1-pool1                             capi-clusters  33s
clusterclass.cluster.x-k8s.io/clusterclass1                                               capi-clusters  33s
cluster.cluster.x-k8s.io/cluster1                                                        capi-clusters  32s
machinepool.cluster.x-k8s.io/cluster1-mp-0-d4fdv                                         capi-clusters  32s
machinepool.cluster.x-k8s.io/cluster1-mp-1-l86kv                                         capi-clusters  32s
clustergroup.fleet.cattle.io/clusterclass1                                                capi-clusters  33s
azureclusteridentity.infrastructure.cluster.x-k8s.io/cluster-identity                     capi-clusters  33s
azuremanagedcluster.infrastructure.cluster.x-k8s.io/cluster1-l2cs6                       capi-clusters  32s
azuremanagedclustertemplate.infrastructure.cluster.x-k8s.io/cluster                     capi-clusters  33s
azuremanagedcontrolplane.infrastructure.cluster.x-k8s.io/cluster1-rv8v4                  capi-clusters  32s
azuremanagedcontrolplanetemplate.infrastructure.cluster.x-k8s.io/cluster1-control-plane  capi-clusters  33s
azuremanagedmachinepool.infrastructure.cluster.x-k8s.io/cluster1-mp-0-78tck              capi-clusters  32s
azuremanagedmachinepool.infrastructure.cluster.x-k8s.io/cluster1-mp-1-zdscw              capi-clusters  32s
azuremanagedmachinepooltemplate.infrastructure.cluster.x-k8s.io/cluster1-pool0           capi-clusters  33s
azuremanagedmachinepooltemplate.infrastructure.cluster.x-k8s.io/cluster1-pool1           capi-clusters  33s

  3. Vous pouvez ensuite vérifier la relation entre toutes les ressources d’objet.

    kubectl lineage -n capi-clusters cluster.cluster.x-k8s.io/cluster1

    Sortie :

    Sortie

Comment activer le mode débogage pour SUSE® Rancher Prime Cluster API et les fournisseurs CAPI

  • SUSE® Rancher Prime Cluster API - Pour activer le mode débogage pour SUSE® Rancher Prime Cluster API, vous devez appliquer un correctif au configmap cattle-system/rancher-config comme suit :

    kubectl patch configmap -n cattle-system rancher-config --type merge --patch '{"data":{"rancher-turtles": "managerArguments:\n  - --v=5\n"}}'

    (5 est équivalent à DEBUG)

    Cela entraîne le redémarrage du pod Turtles, afin d’utiliser la nouvelle configuration.

  • Fournisseurs CAPI - Modifiez les ressources CAPIProvider pour les fournisseurs où l’augmentation du niveau de journalisation est nécessaire. Changez pour votre niveau désiré :

    CAPIProvider.Spec.Manager.Verbosity=5

    (5 est équivalent à DEBUG)

Comment collecter des informations à partir de Rancher Turtles et CAPI

crust-gather est un projet créé par les développeurs CAPI spécifiquement conçu pour rassembler des journaux et des états de ressources des environnements CAPI. C’est un outil sûr et officiel qui peut être utilisé dans tout type d’environnement (production, test ou développement) pour collecter des informations de diagnostic complètes pour le dépannage.

Vous pouvez l’installer via les instructions suivantes :

kubectl krew install crust-gather

kubectl crust-gather --help

Alternativement, il peut être installé de manière autonome via le script install.sh :

curl -sSfL https://github.com/crust-gather/crust-gather/raw/main/install.sh | sh

crust-gather --help

Vous pouvez spécifier une liste de filtres pour collecter des données. Par défaut, il prend un instantané complet du cluster. Les données sont stockées dans le répertoire crust-gather par défaut. Crust-gather accepte une configuration de filtre prédéfinie pour Rancher ou le cluster enfant. Voir ci-dessous pour des configurations d’exemple.

Exemple de configuration de filtre YAML pour le fichier child-crust-gather.yaml :

filters:
  - include_kind:
    - Node
    - Namespace
    - CustomResourceDefinition
  - include_group:
    - management.cattle.io/.*
    - provisioning.cattle.io/.*
  - include_namespace:
    - cattle.*
    - fleet.*
    - kube-system
settings:
  insecure_skip_tls_verify: true
  secrets_file: secrets.txt

Exemple de configuration de filtre YAML pour le fichier rancher-crust-gather.yaml :

filters:
  - include_group:
    - .*cluster.x-k8s.io/.*
    - turtles-capi.cattle.io/.*
  - include_kind:
    - CustomResourceDefinition
    - Node
    - Namespace
  - include_group:
    - management.cattle.io/.*
    - provisioning.cattle.io/.*
  - include_namespace:
    - cattle-turtles-system
    - capi-.*
    - cattle.*
    - fleet.*
    - c-.*
    - rke2.*
    - cert-manager
    - kube-system
settings:
  insecure_skip_tls_verify: true
  secrets_file: secrets.txt

Assurez-vous que le kubeconfig pointe vers le bon cluster, puis exécutez la commande ci-dessous :

kubectl crust-gather collect-from-config -c config.yaml

Utilisation via des drapeaux réguliers :

kubectl crust-gather collect --include-namespace cattle-turtles-system --include-namespace capi-* --include-namespace cattle* --include-namespace c-* --include-namespace=<any-capi-cluster-namespace> --kubeconfig=<KUBECONFIG>

Vous pouvez spécifier un fichier contenant des secrets ou des variables d’environnement avec des chaînes de secrets à exclure.

Par exemple :

kubectl crust-gather collect -s ENV_WITH_SECRET --secrets-file=secrets.txt

Ou exclure toutes les ressources secrètes de la collecte :

kubectl crust-gather collect --exclude-kind Secret

Comment nettoyer les Rancher Turtles et les ressources CAPI

Parfois, le nettoyage de votre infrastructure peut échouer et cela peut entraîner des ressources en attente. Dans cette situation, vous devez supprimer les ressources manuellement.

Gardez à l’esprit que la suppression manuelle des finalizers nécessite un nettoyage manuel des ressources provisionnées par le fournisseur d’infrastructure.

export NAMESPACE=capi-clusters

for RESOURCE in `kubectl get-all -n $NAMESPACE -o name | grep 'cattle.io\|cluster.x-k8s.io'`;
do
        echo "Patching $RESOURCE in namespace $NAMESPACE";
        kubectl patch $RESOURCE -n $NAMESPACE -p '{"metadata":{"finalizers":[]}}' --type=merge;
        kubectl delete $RESOURCE -n $NAMESPACE;
done

Comment désinstaller Rancher Turtles et le projet CAPI

Pour désinstaller Rancher Turtles et les composants CAPI de votre cluster de gestion, suivez ces étapes dans l’ordre :

  1. Tout d’abord, supprimez tous les clusters en aval créés avec CAPI. Pour chaque cluster :

    kubectl delete -n capi-clusters cluster.cluster.x-k8s.io cluster1

    Remplacez capi-clusters par l’espace de noms où vos clusters sont déployés et cluster1 par le nom de votre cluster. Attendez que chaque cluster soit complètement supprimé avant de passer à l’étape suivante.

  2. Désinstallez le chart Helm de Rancher Turtles :

    helm uninstall -n cattle-turtles-system rancher-turtles

  3. Supprimez toutes les configurations de webhook qui pourraient avoir été créées par les fournisseurs CAPI :

    # List all webhook configurations
kubectl get validatingwebhookconfigurations.admissionregistration.k8s.io

# Delete provider-specific webhooks (examples)
kubectl delete validatingwebhookconfigurations.admissionregistration.k8s.io azureserviceoperator-validating-webhook-configuration
kubectl delete validatingwebhookconfigurations.admissionregistration.k8s.io capz-validating-webhook-configuration
kubectl delete validatingwebhookconfigurations.admissionregistration.k8s.io capi-validating-webhook-configuration
kubectl delete validatingwebhookconfigurations.admissionregistration.k8s.io rke2-webhook-configuration

# Also check and delete mutating webhooks if present
kubectl get mutatingwebhookconfigurations
kubectl delete mutatingwebhookconfigurations [webhook-name]

  4. Nettoyez tous les espaces de noms et ressources restants. Les espaces de noms suivants peuvent rester après la désinstallation :

    • cattle-turtles-system

    • rke2-bootstrap-system

    • rke2-control-plane-system

    • capi-system

    • capz-system (ou d’autres espaces de noms spécifiques au fournisseur comme capv-system, capa-system, etc.)

    • capi-clusters (ou d’autres espaces de noms où vous avez déployé des clusters)

      Pour supprimer ces espaces de noms :

      # First remove any finalizers that might be blocking deletion
for NS in cattle-turtles-system rke2-bootstrap-system rke2-control-plane-system capi-system capz-system capi-clusters; do
  kubectl get namespace $NS -o json | jq '.spec.finalizers = []' | kubectl replace --raw "/api/v1/namespaces/$NS/finalize" -f -
done

# Then delete the namespaces
kubectl delete namespace cattle-turtles-system rke2-bootstrap-system rke2-control-plane-system capi-system capz-system capi-clusters

  5. Enfin, supprimez les CRD liés à Cluster API et Rancher Turtles :

    # Delete all Cluster API and Rancher Turtles CRDs
kubectl get crds | grep 'cluster.x-k8s.io\|turtles-capi.cattle.io' | awk '{print $1}' | xargs kubectl delete crd

# Or manually delete them one by one
kubectl delete crd clusters.cluster.x-k8s.io
kubectl delete crd clusterclasses.cluster.x-k8s.io
kubectl delete crd machines.cluster.x-k8s.io
kubectl delete crd machinepools.cluster.x-k8s.io
kubectl delete crd providers.turtles-capi.cattle.io
kubectl delete crd clusterconfigs.turtles-capi.cattle.io
# ... and other related CRDs

    Assurez-vous que tous les clusters sont complètement supprimés avant de retirer ces CRD, sinon vous risquez de laisser des ressources cloud orphelines.