Observer la santé d'un cluster Kubernetes en 5 commandes

Cinq commandes kubectl suffisent pour savoir si un cluster Kubernetes est sain. Ce guide vous montre comment vérifier l’état des nœuds, détecter les pressions sur les ressources, lire la consommation CPU/mémoire et interpréter les événements système. Vous pourrez ainsi repérer un problème avant qu’il n’affecte vos applications.

Ce que vous allez apprendre

• Vérifier que tous les nœuds sont Ready et interpréter les conditions
• Lire les ressources allouées vs capacité d’un nœud
• Installer metrics-server pour activer kubectl top
• Surveiller la consommation CPU/mémoire en temps réel
• Analyser les événements pour repérer les anomalies

Prérequis

• Un cluster Kubernetes fonctionnel (v1.28+)
• kubectl configuré et connecté au cluster
• Des droits de lecture sur les nœuds, pods, événements et métriques du cluster
• Connaissances de base sur les Pods et les nœuds Kubernetes

Comment Kubernetes surveille la santé des nœuds

Le kubelet (l’agent qui tourne sur chaque nœud) met à jour l’état du nœud et renouvelle régulièrement un objet Lease dans le namespace kube-node-lease. Si le plan de contrôle ne reçoit plus ces signaux, il peut marquer le nœud comme injoignable (Ready: Unknown) au bout d’environ 40 secondes par défaut, puis attendre 5 minutes avant de lancer la première éviction des pods du nœud.

Concrètement, le kubelet met à jour deux choses :

• Le statut du nœud (.status.conditions) : plusieurs conditions qui signalent les pressions sur les ressources, notamment Ready, MemoryPressure, DiskPressure, PIDPressure et, selon le contexte, NetworkUnavailable
• Un objet Lease dans kube-node-lease : un “je suis vivant” léger qui sert de heartbeat rapide

Quand une condition passe à True (sauf Ready qui doit rester True), le nœud signale un problème. Quand Ready passe à Unknown, le plan de contrôle a perdu le contact.

Condition	État sain	Ce que cela indique si anormal
Ready	True	False = kubelet ou nœud défaillant ; Unknown = nœud injoignable
MemoryPressure	False	Mémoire disponible sous les seuils d’éviction
DiskPressure	False	Pression sur nodefs, imagefs ou les inodes selon la config du kubelet
PIDPressure	False	Manque de PID disponibles
NetworkUnavailable	False	Réseau du nœud non prêt selon le provider/CNI

Glissez pour voir

Analogie simple

Les conditions d’un nœud fonctionnent comme les voyants d’un tableau de bord de voiture. Quand tout va bien, seul le voyant “moteur OK” (Ready) est allumé. Si un voyant de pression apparaît, il faut agir avant la panne. Retenez que la détection d’un nœud injoignable prend environ 40 secondes, mais l’éviction des pods ne commence que 5 minutes plus tard.

Étape 1 : vérifier l’état des nœuds

La première commande à lancer est kubectl get nodes. Elle donne une vue d’ensemble rapide de tous les nœuds du cluster :

kubectl get nodes

Résultat attendu — Tous les nœuds doivent afficher Ready dans la colonne STATUS :

NAME         STATUS   ROLES           AGE   VERSION
ks-cp1       Ready    control-plane   41h   v1.34.3
ks-worker1   Ready    <none>          41h   v1.34.3
ks-worker2   Ready    <none>          41h   v1.34.3

Pour obtenir plus de détails (IP, runtime, OS), ajoutez -o wide :

kubectl get nodes -o wide

Status dans la sortie	Signification	Action
Ready	Le nœud fonctionne normalement	Aucune
NotReady	Le kubelet ne répond pas	Vérifier le kubelet et le réseau du nœud
SchedulingDisabled	Le nœud est en mode cordon	Normal si maintenance planifiée

Glissez pour voir

NotReady ne signifie pas nœud éteint

Un nœud NotReady peut avoir un kubelet qui plante, un problème réseau, ou un disque plein. Utilisez kubectl describe node (étape suivante) pour trouver la cause.

Étape 2 : inspecter les conditions d’un nœud

Pour comprendre pourquoi un nœud est dans un état donné, utilisez kubectl describe node :

kubectl describe node ks-worker1

La section Conditions est la plus importante. Voici à quoi elle ressemble sur un nœud sain :

Conditions:
  Type                 Status  Reason                       Message
  ----                 ------  ------                       -------
  NetworkUnavailable   False   CalicoIsUp                   Calico is running on this node
  MemoryPressure       False   KubeletHasSufficientMemory   kubelet has sufficient memory available
  DiskPressure         False   KubeletHasNoDiskPressure     kubelet has no disk pressure
  PIDPressure          False   KubeletHasSufficientPID      kubelet has sufficient PID available
  Ready                True    KubeletReady                 kubelet is posting ready status

Comment lire ce tableau :

• Ready: True = le kubelet fonctionne et accepte des pods
• MemoryPressure: False = la mémoire est suffisante
• DiskPressure: False = assez d’espace disque
• PIDPressure: False = nombre de processus dans les limites

Vérifier les ressources allouées

Plus bas dans la sortie de describe node, la section Allocated resources montre la consommation cumulée des pods sur ce nœud :

Allocated resources:
  Resource           Requests        Limits
  --------           --------        ------
  cpu                455m (32%)      7 (500%)
  memory             432730Ki (38%)  4501513472 (390%)

Les Requests représentent ce que les pods ont réservé. Les Limits sont le maximum qu’ils peuvent utiliser. Quand les Requests dépassent 80 % de la capacité, le nœud risque de ne plus pouvoir planifier de nouveaux pods.

Overcommit ≠ problème

Des Limits supérieures à 100 % (overcommit) sont normales — cela signifie que les pods pourraient utiliser plus que la capacité si tous consomment simultanément. En pratique, la consommation réelle est souvent bien inférieure aux Limits.

Étape 3 : vérifier la santé du plan de contrôle

Le plan de contrôle (API server, scheduler, controller-manager, etcd) est le cerveau du cluster. L’API server expose deux endpoints de santé dédiés.

Endpoints /readyz et /livez

Depuis Kubernetes v1.16, deux endpoints remplacent l’ancien /healthz :

• /livez : le processus API server est-il vivant ?
• /readyz : l’API server est-il prêt à servir des requêtes ?

kubectl get --raw='/readyz?verbose' | head -20

Chaque ligne [+] confirme un sous-système fonctionnel :

[+]ping ok
[+]log ok
[+]etcd ok
[+]poststarthook/start-apiserver-admission-initializer ok
[+]poststarthook/generic-apiserver-start-informers ok
...

Si une ligne affiche [-], le sous-système correspondant est en échec.

Pour vérifier également la liveness :

kubectl get --raw='/livez?verbose' | head -20

Vérifier les pods du plan de contrôle

Pour voir concrètement si les composants du plan de contrôle tournent :

kubectl get pods -n kube-system -o wide

Vérifiez que les pods etcd, kube-apiserver, kube-controller-manager et kube-scheduler sont en état Running avec RESTARTS à 0.

Anciennes commandes dépréciées

/healthz (déprécié depuis v1.16) et kubectl get componentstatuses (déprécié depuis v1.19) existent encore dans certains clusters mais ne sont plus fiables. Préférez /readyz, /livez et l’inspection directe des pods kube-system.

Étape 4 : surveiller la consommation avec metrics-server

La commande kubectl top affiche la consommation CPU et mémoire en temps réel. Elle nécessite metrics-server, un composant qui collecte les métriques depuis chaque kubelet et alimente la Metrics API utilisée notamment par les autoscalers (HPA/VPA).

Prérequis : metrics-server

Si kubectl top nodes retourne error: Metrics API not available, metrics-server n’est pas installé. Consultez l’encadré ci-dessous pour l’installer, ou suivez un guide dédié.

Installer metrics-server (lab uniquement)

Déplier les étapes d’installation

1. Téléchargez le manifeste officiel :

   kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

2. Sur un cluster sans certificat TLS (comme un lab), ajoutez le flag --kubelet-insecure-tls :

   kubectl -n kube-system patch deployment metrics-server --type=json \
     -p='[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--kubelet-insecure-tls"}]'

3. Attendez que metrics-server soit prêt :

   kubectl -n kube-system rollout status deployment/metrics-server --timeout=90s

4. Vérifiez que l’API Metrics est disponible :

   kubectl get apiservices | grep metrics

   Résultat attendu :

   v1beta1.metrics.k8s.io   kube-system/metrics-server   True    59s

--kubelet-insecure-tls = lab uniquement

Ce flag désactive la vérification des certificats kubelet. Ne l’utilisez jamais en production. En production, configurez des certificats TLS valides pour les kubelets.

Lire la consommation des nœuds

Une fois metrics-server installé, la commande kubectl top nodes affiche la consommation réelle :

kubectl top nodes

NAME         CPU(cores)   CPU(%)   MEMORY(bytes)   MEMORY(%)
ks-cp1       131m         9%       1129Mi          102%
ks-worker1   72m          5%       833Mi           75%
ks-worker2   74m          5%       935Mi           85%

Comment interpréter :

• CPU(cores) : consommation instantanée en millicores (1000m = 1 CPU)
• CPU% : pourcentage par rapport à la capacité allocatable
• MEMORY(bytes) : mémoire réellement utilisée (working set)
• MEMORY% : pourcentage de la mémoire allocatable

Lire la consommation des pods

kubectl top pods -A --sort-by=cpu | head -15

Cette commande trie tous les pods par consommation CPU décroissante. Très utile pour identifier rapidement un pod qui consomme trop.

Pour un namespace spécifique :

kubectl top pods -n kube-system

Délai après création d'un Pod

Les métriques peuvent mettre quelques minutes à apparaître après la création d’un pod. C’est normal : la pipeline de métriques a besoin de temps pour collecter les premières données.

kubectl top ≠ monitoring complet

kubectl top donne un instantané. Les métriques ne sont pas historisées. Pour du monitoring avec alertes et graphiques, déployez une stack complète (Prometheus + Grafana par exemple).

Étape 5 : lire les événements du cluster

Les événements Kubernetes enregistrent ce qui se passe dans le cluster : créations, erreurs de scheduling, redémarrages, évictions. C’est la boîte noire du cluster.

Depuis Kubernetes v1.26, la sous-commande kubectl events offre un affichage plus lisible avec des options de filtrage natives. Pour voir les warnings récents :

kubectl events -A --types=Warning

La commande classique kubectl get events reste disponible pour des filtrages plus fins via --field-selector :

kubectl get events -A --sort-by=.metadata.creationTimestamp | tail -20

Type event	Exemples	Signification
Normal	Pulling, Created, Started	Opérations normales du kubelet
Warning	FailedScheduling, BackOff, Unhealthy	Quelque chose ne fonctionne pas

Glissez pour voir

Événements courants à surveiller

Événement	Cause probable	Action
FailedScheduling	Pas assez de ressources sur les nœuds	Vérifier kubectl describe node, libérer des ressources
BackOff / CrashLoopBackOff	Le conteneur plante en boucle	Vérifier les logs : kubectl logs <pod>
FailedMount	Volume non disponible	Vérifier le PVC et le StorageClass
Unhealthy	La probe a échoué	Vérifier la configuration des probes
Evicted	Nœud sous pression (mémoire/disque)	Vérifier les conditions du nœud

Glissez pour voir

Filtrage avancé avec kubectl events

Vous pouvez aussi filtrer par ressource spécifique :

kubectl events -A --for=node/ks-worker1
kubectl events -n default --for=pod/mon-pod

Récapitulatif : les 5 commandes essentielles

#	Commande	Ce qu’elle vérifie
1	kubectl get nodes	Tous les nœuds sont Ready
2	kubectl describe node <nom>	Conditions détaillées et ressources allouées
3	kubectl get --raw='/readyz?verbose'	Santé du plan de contrôle
4	kubectl top nodes / kubectl top pods	Consommation CPU/mémoire en temps réel
5	kubectl events -A --types=Warning	Anomalies récentes dans le cluster

Glissez pour voir

Dépannage

Symptôme	Cause probable	Solution
Nœud NotReady	Kubelet arrêté ou réseau coupé	Se connecter au nœud, vérifier systemctl status kubelet
MemoryPressure: True	Mémoire insuffisante	Identifier les pods gourmands avec kubectl top pods, augmenter la mémoire ou réduire les loads
DiskPressure: True	Disque plein (images, logs)	Nettoyer les images inutilisées : crictl rmi --prune
kubectl top renvoie “Metrics API not available”	metrics-server absent	Installer metrics-server (voir étape 4)
/readyz affiche [-]etcd	etcd indisponible	Vérifier l’état du pod etcd : kubectl logs -n kube-system etcd-<nom>
Beaucoup d’événements Evicted	Nœud sous pression prolongée	Ajouter des nœuds ou réduire la charge de travail

Glissez pour voir

À retenir

• kubectl get nodes est votre premier réflexe : tous les nœuds doivent être Ready
• Les 5 conditions d’un nœud (Ready, MemoryPressure, DiskPressure, PIDPressure, NetworkUnavailable) résument sa santé
• kubectl describe node révèle les ressources allouées vs la capacité — surveillez le ratio Requests/Allocatable
• metrics-server est indispensable pour kubectl top — il n’est pas installé par défaut sur tous les clusters
• Les événements Warning sont votre système d’alerte natif : consultez-les régulièrement
• Ces commandes donnent un instantané — pour du monitoring continu, déployez Prometheus + Grafana

Prochaines étapes

Diagnostiquer un CrashLoopBackOff Méthodologie complète pour identifier et résoudre les redémarrages en boucle.

Configurer les Probes Évitez les faux positifs avec des liveness, readiness et startup probes bien dimensionnées.

Architecture Kubernetes Comprenez le rôle de chaque composant du plan de contrôle et des nœuds.

×

📖 Voir la documentation →