Concepts avancés de Kubectl expliqués avec des exemples pratiques

Introduction

Kubectl est l'outil de ligne de commande principal pour interagir avec les clusters Kubernetes. Si de nombreux ingénieurs connaissent les commandes de base comme kubectl get pods ou kubectl apply -f manifest.yaml, une utilisation avancée exige une compréhension approfondie du fonctionnement de kubectl, de la manière de diagnostiquer les problèmes en toute sécurité et de récupérer après un échec sans causer de perturbations supplémentaires.

Cet article s'adresse aux développeurs, consultants DevOps et équipes techniques de startups qui doivent dépasser les bases. Il relie les mécanismes internes de kubectl, son architecture et les concepts approfondis à des commandes pratiques, des sorties attendues, des signaux d'échec et des décisions de récupération. L'accent est mis sur la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des emplacements réservés plutôt que des secrets, vérifier les résultats et documenter les chemins de récupération.

À la fin de ce guide, vous serez capable de :

• Inventorier votre environnement Kubernetes et inspecter l'état du cluster avec précision.
• Appliquer des modifications de configuration en toute sécurité et les valider avant un déploiement complet.
• Diagnostiquer les pannes courantes des pods, des déploiements et du réseau.
• Récupérer après des états d'échec en utilisant des techniques de retour en arrière et d'inspection.
• Suivre une liste de contrôle opérationnelle reproductible pour une fiabilité au quotidien.

Inventaire des versions et de l'environnement

Avant toute modification sur un cluster Kubernetes, vous devez savoir exactement avec quoi vous travaillez. Un inventaire des versions et de l'environnement identifie le composant concerné, sa plage de versions prises en charge, les prérequis, une méthode d'observation en lecture seule, la plus petite modification justifiée et la commande ou le signal qui vérifie le résultat.

Commencez par vérifier votre version de kubectl et celle du cluster. Des versions incompatibles peuvent entraîner un comportement inattendu de l'API et des fonctionnalités non prises en charge. Exécutez :

kubectl version

La sortie attendue indiquera les versions du client et du serveur, par exemple :

Client Version: v1.29.1
Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3
Server Version: v1.28.3

Si la version du serveur n'apparaît pas, kubectl ne peut pas joindre le cluster ou votre kubeconfig ne contient pas le contexte nécessaire. Vérifiez votre contexte actuel avec :

kubectl config current-context

Cette commande doit renvoyer le nom du contexte que vous comptez utiliser, par exemple prod-cluster-admin. Utiliser le mauvais contexte est une cause fréquente de modifications accidentelles. Confirmez toujours le contexte avant d'exécuter toute commande qui modifie l'état.

Ensuite, inventorier la topologie des nœuds et des pods pour comprendre où s'exécutent vos charges de travail. Pour une observation en lecture seule, utilisez :

kubectl get nodes -o wide
kubectl get pods -A -o wide

La sortie montre les noms des nœuds, leurs rôles, leurs versions, leurs adresses IP internes et externes, et pour les pods, leur espace de noms, leur statut, le nombre de redémarrages, leur âge et le nœud assigné. Par exemple :

NAME       STATUS   ROLES           AGE   VERSION   INTERNAL-IP   EXTERNAL-IP   OS-IMAGE
node-1     Ready    control-plane   12d   v1.28.3   10.0.0.1      <none>        Ubuntu 22.04
node-2     Ready    <none>          12d   v1.28.3   10.0.0.2      <none>        Ubuntu 22.04

Cet inventaire vous aide à identifier des anomalies comme des nœuds en état NotReady, des pods bloqués en Pending ou CrashLoopBackOff, et des problèmes de répartition des ressources.

Pour une analyse plus approfondie d'un pod spécifique, utilisez describe pour afficher les événements, les conditions et les détails de configuration :

kubectl describe pod <nom-du-pod> -n <namespace>

La sortie inclut les événements récents qui pointent souvent directement vers le problème, comme une insuffisance de CPU, des échecs de téléchargement d'image ou des contraintes de planification. Par exemple, un événement pourrait indiquer :

Warning  FailedScheduling  2m (x5 over 10m)  default-scheduler  0/3 nodes are available: 3 Insufficient cpu.

Cela vous dit exactement pourquoi le pod ne fonctionne pas.

N'oubliez pas le principe de séparation entre l'observation et l'intervention. Capturez l'état actuel et les horodatages avant toute modification. Protégez les informations d'identification et les données privées ; ne faites jamais apparaître de secrets dans les journaux ou l'historique des commandes. Utilisez des variables d'environnement ou des références de secrets dans les manifestes plutôt que des valeurs en texte brut.

Chemin de configuration sûr

Appliquer des modifications de configuration à un cluster de production est l'une des opérations les plus dangereuses. L'essentiel est de suivre un chemin de configuration sûr qui minimise les risques et assure la récupérabilité. Cela signifie appliquer les modifications de manière contrôlée, les valider avant un déploiement complet et disposer d'un plan de retour en arrière.

Avant d'appliquer un manifeste, effectuez un essai à blanc pour voir ce qui changerait sans modifier réellement le cluster :

kubectl apply -f manifest.yaml --dry-run=client

Cet essai à blanc côté client valide la syntaxe et montre les ressources qui seraient créées ou mises à jour. Pour une validation côté serveur, utilisez --dry-run=server. C'est crucial lorsque vous travaillez avec des contrôleurs d'admission ou une validation de schéma qui peuvent rejeter certains champs.

Si vous modifiez un déploiement existant, utilisez la commande diff pour voir un diff unifié entre l'état actuel et le manifeste proposé :

kubectl diff -f manifest.yaml

La sortie montrera les ajouts, suppressions et modifications dans un format de diff familier. Par exemple :

--- /tmp/LIVE-123/deployment.yaml
+++ /tmp/MERGED-456/deployment.yaml
@@ -12,7 +12,7 @@
         image: myapp:1.0
-        image: myapp:1.0
+        image: myapp:1.1

Cela vous permet de passer en revue les modifications avant qu'elles ne soient appliquées.

Lorsque vous êtes prêt à appliquer, appuyez-vous sur l'historique des révisions du déploiement. Par exemple, pour mettre à jour l'image d'un déploiement :

kubectl set image deployment/myapp myapp=myapp:1.1

Vérifiez ensuite l'état du déploiement :

kubectl rollout status deployment/myapp

Sortie attendue en cas de succès :

deployment "myapp" successfully rolled out

Si le déploiement échoue, vous pouvez inspecter l'historique des révisions :

kubectl rollout history deployment/myapp

Cette commande liste les révisions avec les causes des modifications (si elles sont enregistrées). Pour revenir à une révision précédente :

kubectl rollout undo deployment/myapp --to-revision=2

Vérifiez toujours que le retour en arrière a réussi avec kubectl rollout status.

Pour de petits tests locaux, gardez le rayon d'impact minimal. Utilisez un espace de noms dédié pour les tests et nettoyez ensuite. Appliquez un manifeste à la fois et inspectez les ressources générées. Utilisez kubectl port-forward pour tester la connectivité localement avant d'exposer les services via un équilibreur de charge ou un contrôleur d'entrée. Par exemple :

kubectl port-forward svc/my-service 8080:80

Cela redirige le port local 8080 vers le port 80 du service, ce qui vous permet de tester l'application sans l'ouvrir sur Internet.

Vérification et diagnostic

La vérification et le diagnostic sont au cœur de l'utilisation avancée de kubectl. Lorsque quelque chose ne va pas, votre capacité à identifier et résoudre rapidement le problème dépend d'une inspection systématique et de l'interprétation des sorties.

Commencez par les bases : vérifiez l'état des pods et les journaux. Pour un pod en boucle de crash, obtenez son état actuel :

kubectl get pods

Si le pod est en CrashLoopBackOff ou Error, l'étape suivante est de consulter ses journaux. Pour l'instance actuelle :

kubectl logs <nom-du-pod>

Si le pod a planté et redémarré, vous aurez peut-être besoin des journaux de l'instance précédente pour voir l'erreur qui a causé le crash :

kubectl logs <nom-du-pod> --previous

Par exemple, une application Python peut enregistrer une trace qui révèle une dépendance manquante ou une erreur de configuration. Les journaux indiqueront l'erreur exacte, telle que :

ModuleNotFoundError: No module named 'requests'

Cela vous indique que l'image du conteneur ne contient pas un paquet requis.

Utilisez describe pour obtenir les événements et les conditions qui peuvent expliquer l'état du pod. Recherchez des événements comme FailedScheduling, FailedMount ou BackOff. La sortie inclut également les résultats des sondes de préparation et de vivacité, ce qui peut indiquer pourquoi un pod ne reçoit pas de trafic.

Pour les problèmes de réseau, vérifiez les points de terminaison du service et la connectivité. Vérifiez qu'un service a des points de terminaison :

kubectl get endpoints <nom-du-service> -n <namespace>

La sortie doit lister les adresses IP des pods et les ports. Si la liste est vide, le sélecteur du service ne correspond à aucun pod. Vérifiez le sélecteur dans la définition du service et les libellés des pods.

Testez la connectivité depuis l'intérieur du cluster à l'aide d'un pod de débogage temporaire :

kubectl run -it --rm debug --image=busybox -- sh

Dans le pod de débogage, vous pouvez utiliser wget ou nc pour tester le DNS et les ports internes du service. Par exemple :

wget -O- http://my-service.namespace.svc.cluster.local:8080/health

Cela vous permet de tester le service sans quitter le cluster.

Pour des diagnostics plus approfondis, utilisez kubectl exec pour exécuter des commandes dans un conteneur en cours d'exécution. Par exemple, pour vérifier les variables d'environnement ou les fichiers :

kubectl exec -it <nom-du-pod> -- env
kubectl exec -it <nom-du-pod> -- ls /app

Cela peut révéler des erreurs de configuration, des fichiers manquants ou des chemins incorrects.

Comparez toujours le comportement attendu avec le comportement réel. Par exemple, si un déploiement est censé avoir 3 répliques mais que seulement 2 sont en cours d'exécution, utilisez kubectl describe deployment pour voir pourquoi la troisième réplique n'est pas créée. Recherchez des événements concernant les limites de quota ou les ressources insuffisantes.

Modes de défaillance et récupération

Les charges de travail Kubernetes échouent de manière prévisible, et les utilisateurs avancés de kubectl doivent connaître les modes de défaillance courants et savoir comment s'en remettre. Cette section décrit plusieurs scénarios avec des étapes de récupération concrètes.

CrashLoopBackOff

Un pod démarre et plante à plusieurs reprises. Le nombre de redémarrages dans kubectl get pods augmente, et le statut devient CrashLoopBackOff.

Pourquoi cela arrive : l'application se termine avec un code non nul, souvent à cause d'une mauvaise configuration, de dépendances manquantes ou de sondes de démarrage en échec.

Étapes de récupération :

1. Consultez les journaux de l'instance précédente : kubectl logs <pod> --previous.
2. Décrivez le pod pour voir les événements : kubectl describe pod <pod>.
3. Si l'erreur est due à une mauvaise configuration, corrigez la ConfigMap ou le Secret et mettez à jour le pod.
4. Si l'image est incorrecte, mettez à jour le déploiement avec la bonne étiquette d'image.

ImagePullBackOff

Un pod ne peut pas télécharger son image de conteneur. Le statut est ImagePullBackOff ou ErrImagePull.

Pourquoi cela arrive : nom ou étiquette d'image incorrect, informations d'identification de registre manquantes ou problèmes de réseau.

Étapes de récupération :

1. Vérifiez le nom de l'image dans la spécification du pod : kubectl get pod <pod> -o jsonpath='{.spec.containers[*].image}'.
2. Vérifiez que l'image existe dans le registre et que vous avez la permission de la télécharger.
3. Si vous utilisez un registre privé, assurez-vous que le secret de téléchargement d'image est correctement configuré.
4. Consultez les événements avec kubectl describe pod pour obtenir des messages d'erreur détaillés.

Pods en attente (Pending)

Un pod est bloqué en Pending parce qu'il ne peut pas être planifié.

Pourquoi cela arrive : ressources insuffisantes, sélecteurs de nœuds ou affinités impossibles à satisfaire, ou teintures qui repoussent le pod.

Étapes de récupération :

1. Exécutez kubectl describe pod <pod> et regardez la section Événements. Elle vous dira pourquoi la planification a échoué, par exemple 0/3 nodes are available: 3 Insufficient memory.
2. Si les ressources sont en cause, ajustez les demandes de ressources du pod ou ajoutez des nœuds.
3. Si les sélecteurs ou les teintures posent problème, modifiez la spécification du pod ou les teintures des nœuds en conséquence.

Échec de déploiement (Failed Rollout)

Une mise à jour de déploiement entraîne l'échec des nouveaux pods ou leur non-préparation, ce qui bloque le déploiement.

Pourquoi cela arrive : la nouvelle image contient des bogues, la sonde de préparation échoue ou les limites de ressources sont trop basses.

Étapes de récupération :

1. Vérifiez l'état du déploiement : kubectl rollout status deployment/<nom>.
2. Obtenez l'historique de déploiement : kubectl rollout history deployment/<nom>.
3. Inspectez les journaux et les événements des pods en échec.
4. Si la nouvelle version est défaillante, revenez immédiatement en arrière : kubectl rollout undo deployment/<nom>.
5. Vérifiez que les anciens pods sont de retour et que le déploiement est terminé.

Connexion au service refusée

Les applications ne peuvent pas se connecter à un service, ou le service ne route pas correctement le trafic.

Pourquoi cela arrive : le sélecteur du service ne correspond pas aux pods, le port cible est incorrect ou les politiques réseau bloquent le trafic.

Étapes de récupération :

1. Vérifiez que le service a des points de terminaison : kubectl get endpoints <service>. Si la liste est vide, le sélecteur est incorrect.
2. Vérifiez que le port cible dans la définition du service correspond au port du conteneur.
3. Testez à partir d'un pod de débogage comme décrit précédemment.
4. Vérifiez les politiques réseau qui pourraient bloquer le trafic entrant ou sortant.

Dans tous les scénarios de récupération, documentez l'incident et les mesures prises. Cela aide à constituer une base de connaissances pour les problèmes futurs et à améliorer la liste de contrôle opérationnelle.

Liste de contrôle opérationnelle

Une liste de contrôle opérationnelle cohérente aide à prévenir les erreurs et garantit que les tâches de routine sont effectuées en toute sécurité et de manière complète. Voici une liste de contrôle pratique pour les opérations kubectl courantes, avec des commandes spécifiques et des étapes de vérification.

Avant toute modification

• [ ] Confirmez le contexte actuel : kubectl config current-context
• [ ] Vérifiez la compatibilité des versions du cluster : kubectl version
• [ ] Prenez note de l'état actuel : kubectl get all -n <namespace> -o wide > etat-avant.txt
• [ ] Assurez-vous d'avoir une sauvegarde ou de pouvoir annuler la modification.

Application des modifications

• [ ] Utilisez un essai à blanc : kubectl apply -f manifest.yaml --dry-run=client
• [ ] Examinez le diff : kubectl diff -f manifest.yaml
• [ ] Appliquez la modification : kubectl apply -f manifest.yaml
• [ ] Surveillez le déploiement : kubectl rollout status deployment/<nom>
• [ ] Vérifiez la santé des pods : kubectl get pods -n <namespace>
• [ ] Si vous utilisez un Job, vérifiez son achèvement : kubectl get job <nom-du-job>

Vérification après modification

• [ ] Confirmez que les pods sont en cours d'exécution : kubectl get pods
• [ ] Vérifiez les journaux pour détecter des erreurs : kubectl logs <pod>
• [ ] Testez les points de terminaison du service : kubectl get endpoints <service>
• [ ] Exécutez des tests de fumée au niveau de l'application.

Plan de retour en arrière

• [ ] Identifiez la révision précédente : kubectl rollout history deployment/<nom>
• [ ] Déterminez la commande de retour en arrière : kubectl rollout undo deployment/<nom>
• [ ] Documentez le temps de retour en arrière attendu et la personne responsable (par exemple, l'ingénieur de garde).

Pour chaque décision ou modification majeure, attribuez un seul propriétaire responsable, pas un groupe. Par exemple, le propriétaire du déploiement est [Priya Shah, responsable de l'ingénierie]. Elle est responsable de l'approbation des modifications en production et de s'assurer que les procédures de retour en arrière sont testées. La décision d'appliquer une modification doit être revue mensuellement lors de l'examen des opérations de l'équipe, ou immédiatement après un déploiement en échec.

Pièges courants et comment les éviter

Même les utilisateurs expérimentés de kubectl tombent dans des pièges qui peuvent provoquer des interruptions ou des pertes de temps. Voici quelques pièges courants, pourquoi ils surviennent et comment les éviter ou s'en remettre.

Travailler dans le mauvais contexte

Pourquoi cela arrive : vous pouvez avoir plusieurs clusters ou espaces de noms, et votre contexte kubeconfig n'est pas celui que vous pensez. Cela peut conduire à appliquer des modifications à la production au lieu de la préproduction.

Comment éviter : exécutez toujours kubectl config current-context avant toute commande qui modifie l'état. Utilisez des outils comme kubectx et kubens pour changer explicitement de contexte et d'espace de noms. Envisagez d'utiliser des invites de shell ou des schémas de couleurs de terminal différents selon les environnements.

Comment récupérer : si vous avez accidentellement modifié le mauvais cluster, revenez immédiatement en arrière avec kubectl rollout undo si possible, ou restaurez à partir des sauvegardes. Documentez l'incident et revoyez vos pratiques de gestion des contextes.

Appliquer des manifestes sans révision

Pourquoi cela arrive : vous faites confiance au manifeste et l'appliquez directement, mais il peut contenir des modifications non intentionnelles dues à une faute de frappe ou à un conflit de fusion.

Comment éviter : utilisez toujours kubectl diff pour examiner les modifications avant de les appliquer. Utilisez --dry-run=server pour détecter les erreurs de validation côté serveur. Pour les modifications critiques, demandez à un collègue de réviser le manifeste.

Comment récupérer : si la modification était mauvaise et a provoqué un échec de déploiement, utilisez kubectl rollout undo ou réappliquez le manifeste précédent. Conservez les manifestes dans un système de contrôle de version pour pouvoir revenir à un état connu et fonctionnel.

Supprimer des ressources avec le mauvais sélecteur

Pourquoi cela arrive : vous utilisez kubectl delete -f ou kubectl delete pod --all sans vérifier le sélecteur, supprimant accidentellement plus que prévu.

Comment éviter : utilisez les libellés et les sélecteurs avec précaution. Avant de supprimer, listez ce qui serait supprimé avec kubectl get <ressource> -l <sélecteur>. Par exemple, kubectl get pods -l app=myapp montre uniquement les pods avec ce libellé.

Comment récupérer : si vous avez supprimé des pods qui font partie d'un ReplicaSet, ils peuvent être recréés automatiquement. Sinon, vous devrez peut-être appliquer à nouveau le manifeste du déploiement pour les recréer. Pour les ensembles avec état, assurez-vous que les données ne sont pas perdues ; utilisez des instantanés de volume si disponibles.

Ignorer le cycle de vie des pods et les sondes

Pourquoi cela arrive : vous configurez un déploiement sans sondes de préparation et de vivacité appropriées, de sorte que le service route le trafic vers des pods qui ne sont pas prêts, ou le pod est tué prématurément.

Comment éviter : définissez des sondes appropriées dans la spécification de votre pod. Par exemple, une sonde de préparation qui vérifie un point de terminaison HTTP :

readinessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10

Une sonde de vivacité qui vérifie une commande :

livenessProbe:
  exec:
    command:
    - cat
    - /tmp/healthy
  initialDelaySeconds: 5
  periodSeconds: 10

Comment récupérer : si un pod est bloqué en Running mais pas Ready, vérifiez la configuration de la sonde de préparation. Si un pod est redémarré fréquemment, vérifiez la sonde de vivacité ; elle est peut-être trop agressive.

Négliger les limites de ressources

Pourquoi cela arrive : vous ne définissez pas de demandes et de limites de ressources, ce qui permet aux pods de consommer trop de CPU ou de mémoire, privant les autres pods et entraînant une instabilité des nœuds.

Comment éviter : définissez toujours des demandes et des limites de ressources pour vos conteneurs. Par exemple :

resources:
  requests:
    memory: "64Mi"
    cpu: "250m"
  limits:
    memory: "128Mi"
    cpu: "500m"

Utilisez des quotas de ressources et des plages de limites au niveau de l'espace de noms pour les faire respecter.

Comment récupérer : si un pod est tué pour dépassement de mémoire (OOMKilled), vérifiez sa limite de mémoire. Ajustez la limite ou optimisez l'utilisation de la mémoire de l'application. Utilisez kubectl top pods pour voir la consommation réelle des ressources.

Conclusion

Les concepts avancés de kubectl sont essentiels pour des opérations Kubernetes sûres et efficaces. En suivant les principes d'observation avant intervention, de limitation du rayon d'impact, de vérification des résultats et de documentation de la récupération, vous pouvez éviter les pièges courants et maintenir un cluster fiable.

Cet article a fourni des commandes pratiques et des exemples pour l'inventaire des versions, la configuration sûre, la vérification, le diagnostic, la récupération après échec et une liste de contrôle opérationnelle. Ces techniques ne sont utiles que si chaque recommandation est limitée à une version, observable et réversible lorsque c'est possible. Copier une commande sans vérifier les prérequis et la sortie attendue n'est pas une procédure d'exploitation.

Comme prochaine étape, choisissez une vérification à faible risque dans ce guide, enregistrez l'état actuel de votre cluster, exécutez la vérification documentée, comparez le résultat avec le signal attendu et passez en revue les dépendances telles que les espaces de noms, les pods et les déploiements.

Un flux de travail technique fiable rend les échecs visibles, protège les valeurs sensibles, limite les modifications à la ressource prévue et définit la vérification de la récupération avant qu'un incident ne force la décision. En intégrant ces pratiques dans votre travail quotidien, vous construirez un environnement Kubernetes robuste et résilient.