Probes Kubernetes : liveness, readiness, startup sans faux positifs

Une probe mal configurée peut provoquer plus d'indisponibilité que l'absence de probe. Ce guide vous apprend à choisir la bonne probe, à dimensionner ses paramètres, et à éviter les pièges qui transforment un healthcheck en source de pannes.

Ce que vous allez apprendre

• La différence réelle entre liveness, readiness et startup
• Quand utiliser (et quand éviter) chaque type de probe
• Comment dimensionner les paramètres sans faux positifs
• Les anti-patterns qui causent des redémarrages en boucle
• Comment diagnostiquer une probe qui échoue

Ce que sont les probes Kubernetes

Les probes (sondes) permettent à Kubernetes de surveiller l'état de vos conteneurs et d'agir en conséquence. Par défaut, Kubernetes considère qu'un conteneur est "en marche" tant que son processus principal tourne, même si l'application est bloquée ou incapable de traiter des requêtes.

Les probes comblent ce manque de signal applicatif en donnant au kubelet des indicateurs concrets sur l'état réel de l'application.

Probes = conteneurs

Les probes sont configurées sur les conteneurs, pas sur les Pods. Les effets (redémarrage, retrait du trafic) remontent ensuite au niveau du Pod et du routage par Service.

Les trois types de probes

Kubernetes propose trois types de probes, chacune avec un objectif distinct :

Probe	Question posée	Action si échec
startupProbe	"Le conteneur a-t-il fini de démarrer ?"	Redémarrage du conteneur
livenessProbe	"Le conteneur est-il bloqué et irrécupérable ?"	Redémarrage du conteneur
readinessProbe	"Le conteneur peut-il recevoir du trafic maintenant ?"	Retrait des endpoints du Service

Glissez pour voir

Startup Probe : gérer les démarrages lents

La startupProbe est conçue pour les applications qui ont besoin d'un temps de démarrage important. Tant qu'elle n'a pas réussi, Kubernetes n'exécute pas les autres probes.

Cas d'usage :

• Application Java chargeant de nombreuses dépendances
• Base de données qui charge des données volumineuses en mémoire
• Application legacy avec initialisation complexe

startupProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5
  failureThreshold: 30  # 30 × 5s = 150s max pour démarrer

Liveness Probe : détecter un conteneur bloqué

La livenessProbe vérifie si le conteneur est irrémédiablement bloqué et doit être redémarré. Elle répond à la question : "faut-il tuer ce conteneur ?"

Cas d'usage :

• Deadlock applicatif
• Boucle infinie
• Thread principal suspendu

livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 15
  periodSeconds: 20
  timeoutSeconds: 5
  failureThreshold: 3

Attention

Une livenessProbe trop agressive peut provoquer des redémarrages en boucle (CrashLoopBackOff). Elle doit être plus tolérante que la readinessProbe.

Readiness Probe : contrôler le trafic

La readinessProbe indique si le conteneur peut traiter des requêtes maintenant. Tant qu'elle échoue, le Pod est retiré des endpoints des Services et ne reçoit plus de trafic.

Cas d'usage :

• API qui doit établir une connexion à une base de données
• Application qui charge des fichiers de configuration
• Service qui attend une dépendance externe

readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10
  timeoutSeconds: 3
  failureThreshold: 3

Ordre d'exécution des probes

L'ordre d'exécution n'est pas linéaire. Voici comment Kubernetes les orchestre :

1. Au démarrage du conteneur

   Si une startupProbe est définie, elle prend le contrôle. Les autres probes sont désactivées jusqu'à sa réussite.

2. Après réussite de la startup probe

   La livenessProbe et la readinessProbe s'exécutent en parallèle, chacune selon sa propre logique et ses propres paramètres.

3. En fonctionnement normal

   • La readinessProbe contrôle l'inclusion dans les endpoints
   • La livenessProbe surveille les blocages irréversibles

Indépendance

La readinessProbe n'attend pas le succès de la livenessProbe pour fonctionner. Ce sont deux mécanismes indépendants avec des objectifs différents.

Quand éviter une liveness probe

Une liveness probe n'est pas toujours nécessaire. Kubernetes rappelle que si votre application sait déjà crasher proprement en cas d'erreur, le kubelet appliquera la politique de redémarrage (restartPolicy) sans avoir besoin d'une liveness probe.

Situations où la liveness est inutile ou dangereuse

Le point commun de ces quatre cas : la probe apporte un risque de redémarrage sans apporter d'information que Kubernetes n'a pas déjà. Le dernier est le plus coûteux, une base de données ou une file de messages redémarrée par erreur pouvant perdre des données non répliquées.

Situation	Pourquoi éviter la liveness
L'application crashe d'elle-même en cas de panne	Le restartPolicy suffit
Le check est coûteux ou instable	Risque de faux positifs
Le check dépend d'un service externe	Un problème externe provoquera des redémarrages
L'application est stateful et sensible aux redémarrages	Perte de données ou d'état

Glissez pour voir

Règle de base

La liveness probe doit tester l'état interne du conteneur, pas ses dépendances externes. Pour les dépendances, utilisez une readinessProbe.

Différencier liveness et readiness

C'est l'erreur la plus fréquente : utiliser le même endpoint pour les deux probes sans réflexion.

Ce que chaque probe doit vérifier

La distinction tient à la conséquence de l'échec, pas à la nature du test. Un échec de readiness coupe le trafic et se répare tout seul dès que la dépendance revient ; un échec de liveness détruit le conteneur. La readiness peut donc se permettre d'être exigeante, la liveness doit rester au strict minimum vérifiable localement.

Probe	Question	Ce qu'elle doit tester
readinessProbe	"Puis-je traiter une requête maintenant ?"	État fonctionnel complet (base de données connectée, cache chargé, dépendances OK)
livenessProbe	"Suis-je irrémédiablement bloqué ?"	État interne minimal (processus vivant, pas de deadlock)

Glissez pour voir

Exemple concret

Deux différences à repérer dans le bloc ci-dessous : les chemins ne sont pas les mêmes (/ready contre /healthz), et la liveness tourne deux fois moins souvent avec un failureThreshold plus élevé. Elle tolère ainsi 100 secondes de dysfonctionnement avant de redémarrer, là où la readiness coupe le trafic au bout de 30 secondes.

# Readiness : vérifie que l'API peut vraiment répondre
readinessProbe:
  httpGet:
    path: /ready  # Teste la connexion DB, le cache, etc.
    port: 8080
  periodSeconds: 10
  failureThreshold: 3

# Liveness : vérifie seulement que le processus n'est pas bloqué
livenessProbe:
  httpGet:
    path: /healthz  # Check léger, local, rapide
    port: 8080
  periodSeconds: 20
  failureThreshold: 5  # Plus tolérant que readiness

Anti-pattern

Ne testez jamais une dépendance externe (base de données, API tierce) dans une livenessProbe. Si cette dépendance devient indisponible, tous vos Pods redémarreront en boucle.

Méthodes de vérification

Kubernetes propose quatre méthodes pour vérifier l'état d'un conteneur :

HTTPGet

Effectue une requête HTTP sur un chemin spécifié. Réussit si le code de réponse est entre 200 et 399.

livenessProbe:
  httpGet:
    path: /healthz
    port: http  # Utilise un port nommé
  periodSeconds: 10

Cas d'usage : Applications web, API REST.

TCPSocket

Tente d'établir une connexion TCP sur le port spécifié. Réussit si le port est ouvert.

readinessProbe:
  tcpSocket:
    port: 3306
  periodSeconds: 10

Cas d'usage : Bases de données, services TCP (MySQL, Redis, PostgreSQL).

Exec (Commande)

Exécute une commande dans le conteneur. Réussit si le code de retour est 0.

startupProbe:
  exec:
    command:
    - cat
    - /app/ready
  periodSeconds: 5

Cas d'usage : Vérifications personnalisées, présence d'un fichier.

Coût d'une probe exec

Une commande exec est plus coûteuse qu'un check HTTP en termes de CPU et mémoire. Évitez les scripts complexes ou les appels à des outils lourds.

gRPC

Teste directement un service gRPC via le protocole standard de health checking. Disponible nativement depuis Kubernetes v1.23.

readinessProbe:
  grpc:
    port: 50051
    service: myapp.v1.Health
  periodSeconds: 10

Cas d'usage : Services exposant une interface gRPC.

Prérequis gRPC

Les probes gRPC nécessitent que votre service implémente le protocole standard de health checking gRPC. Elles ne remplacent pas automatiquement un endpoint HTTP si ce protocole n'est pas implémenté.

Headers HTTP personnalisés

Pour les probes HTTP, vous pouvez ajouter des en-têtes personnalisés :

readinessProbe:
  httpGet:
    path: /ready
    port: 8080
    httpHeaders:
    - name: X-Probe-Type
      value: readiness

Cas d'usage :

• Distinguer les types de checks côté application
• Satisfaire un reverse proxy interne
• Ajouter des métadonnées pour l'observabilité

Ne pas utiliser pour l'authentification

N'utilisez pas les headers HTTP pour transporter des secrets (clés API, tokens). Préférez un endpoint de santé interne, simple et non authentifié.

Récapitulatif des méthodes

Le choix se fait d'abord sur ce que l'application expose. HTTPGet reste le défaut quand un endpoint de santé existe, TCPSocket convient aux services sans interface HTTP, et Exec ne se justifie que faute d'alternative : chaque exécution crée un processus dans le conteneur, à la fréquence de periodSeconds, sur tous les Pods.

Méthode	Protocole	Cas d'usage	Coût
HTTPGet	HTTP(S)	Applications web, API	Faible
TCPSocket	TCP	Bases de données, services TCP	Très faible
Exec	Commande	Vérifications personnalisées	Élevé
gRPC	gRPC	Services gRPC	Faible

Glissez pour voir

Paramètres de configuration

Les six paramètres ci-dessous s'appliquent aux trois types de probes et à toutes les méthodes de vérification. Leurs valeurs par défaut sont conservatrices et souvent inadaptées : timeoutSeconds à 1 seconde, en particulier, provoque des faux positifs dès que le conteneur subit une pointe de charge. Retenez la formule qui gouverne le délai avant action : initialDelaySeconds + (failureThreshold × periodSeconds).

Tous les paramètres disponibles

Ce tableau sert de référence à relire au moment de dimensionner. successThreshold est le seul paramètre qui ne vaille que pour la readiness : pour la liveness et la startup, Kubernetes impose la valeur 1.

Paramètre	Défaut	Description
initialDelaySeconds	0	Délai avant la première exécution
periodSeconds	10	Intervalle entre chaque check
timeoutSeconds	1	Durée maximale d'un check
failureThreshold	3	Nombre d'échecs avant action
successThreshold	1	Nombre de succès pour revenir OK (readiness uniquement)
terminationGracePeriodSeconds	aucun	Délai de grâce spécifique à la probe

Glissez pour voir

Utiliser des ports nommés

Pour une meilleure lisibilité, référencez les ports par leur nom :

spec:
  containers:
  - name: app
    image: myapp:1.0
    ports:
    - name: http
      containerPort: 8080
    - name: metrics
      containerPort: 9090
    livenessProbe:
      httpGet:
        path: /healthz
        port: http  # Référence le port nommé
    readinessProbe:
      httpGet:
        path: /ready
        port: http

Dimensionner ses probes

Les valeurs des paramètres ne se devinent pas : elles se déduisent du comportement mesuré de l'application. La démarche part donc du temps de démarrage réel, puis règle chaque probe par rapport à cette mesure. La règle qui structure tout le reste : la liveness doit toujours être plus tolérante que la readiness, faute de quoi le conteneur est redémarré avant même d'avoir été retiré du trafic.

Méthodologie

Quatre étapes, dans cet ordre. Les inverser conduit à dimensionner la startup probe sur une intuition plutôt que sur une mesure.

1. Mesurer le temps de démarrage réel

   Lancez votre application et mesurez le temps jusqu'à ce qu'elle soit prête. Ajoutez une marge de 20-30%.

2. Définir la startup probe

   failureThreshold × periodSeconds doit être supérieur au temps de démarrage maximal.

3. Configurer la readiness probe

   Plus réactive que la liveness. periodSeconds court (5-10s), failureThreshold modéré (3).

4. Configurer la liveness probe

   Plus tolérante que la readiness. periodSeconds plus long (15-30s), failureThreshold plus élevé (5+).

Tableau de dimensionnement

Ces valeurs sont des points de départ à ajuster après mesure, pas des constantes. Vérifiez à chaque ligne que le produit failureThreshold × periodSeconds couvre bien le délai que vous acceptez : 12 × 5 s laisse 60 secondes de démarrage, au-delà le conteneur est redémarré.

Situation	Probe recommandée	Configuration suggérée
Démarrage en 45s	startupProbe	periodSeconds: 5, failureThreshold: 12
API rapide, dépendante d'une DB	readinessProbe	periodSeconds: 10, failureThreshold: 3
Process susceptible de deadlock	livenessProbe	periodSeconds: 20, failureThreshold: 5
Service sensible aux pics de charge	Toutes	timeoutSeconds: 5, failureThreshold: 5

Glissez pour voir

Exemple complet

Ce Deployment combine les trois probes sur un même conteneur, cas le plus courant en production. Notez que les trois blocs se placent au niveau du conteneur, pas du Pod, et que la startup probe couvre 150 secondes de démarrage pendant lesquelles les deux autres restent inertes.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
      - name: api
        image: myapi:1.0
        ports:
        - name: http
          containerPort: 8080
        # Startup : pour les démarrages lents
        startupProbe:
          httpGet:
            path: /healthz
            port: http
          initialDelaySeconds: 5
          periodSeconds: 5
          failureThreshold: 30  # 150s max pour démarrer
        # Liveness : détection des blocages
        livenessProbe:
          httpGet:
            path: /healthz
            port: http
          periodSeconds: 20
          timeoutSeconds: 5
          failureThreshold: 5
        # Readiness : contrôle du trafic
        readinessProbe:
          httpGet:
            path: /ready
            port: http
          periodSeconds: 10
          timeoutSeconds: 3
          failureThreshold: 3
          successThreshold: 1

Anti-patterns à éviter

Ces configurations passent la revue de code et le déploiement sans alerte : elles ne se manifestent qu'en production, souvent au pire moment, quand la charge augmente ou qu'une dépendance ralentit. Les repérer dans un manifeste existant est le meilleur retour sur investissement de ce guide.

Les erreurs qui provoquent des pannes

Les trois premières lignes du tableau expliquent la majorité des incidents liés aux probes. Elles partagent le même effet : la probe échoue alors que l'application va bien, et le redémarrage aggrave la situation au lieu de la corriger.

Anti-pattern	Conséquence	Solution
Liveness qui teste une DB externe	Cascade de redémarrages si la DB est lente	Tester uniquement l'état interne
periodSeconds trop court	Charge CPU, faux positifs	Minimum 10s pour liveness
timeoutSeconds de 1s par défaut	Faux positifs sous charge	Augmenter à 3-5s
Probe exec avec script lourd	Consommation excessive de ressources	Préférer HTTPGet
Même endpoint pour liveness et readiness	Pas de distinction entre "bloqué" et "pas prêt"	Endpoints différents
Oublier startupProbe sur une appli lente	Redémarrages pendant le démarrage	Ajouter une startup probe
Headers HTTP avec secrets	Exposition de credentials	Endpoint non authentifié

Glissez pour voir

La règle d'or

Un seul critère permet de trancher devant une configuration douteuse : demandez-vous ce qui se passe si la probe se trompe. Si la réponse est « le service tombe », la probe est trop stricte, quel que soit le bien-fondé du test qu'elle effectue.

Une probe ne doit pas devenir elle-même la cause de l'instabilité qu'elle cherche à détecter.

Lien avec les Services

Quand une readinessProbe échoue, Kubernetes retire le Pod des endpoints du Service. Le Pod existe toujours, mais ne reçoit plus de trafic.

Observer les endpoints

La liste des endpoints est la preuve directe de l'effet d'une readiness probe : un Pod absent de cette liste ne reçoit aucune requête, même s'il apparaît en Running.

# Voir les endpoints d'un Service
kubectl get endpoints mon-service

# Résultat quand un Pod n'est pas ready
NAME          ENDPOINTS                           AGE
mon-service   10.244.0.5:8080,10.244.0.6:8080    1h
# Le Pod avec IP 10.244.0.7 n'apparaît plus car il n'est pas Ready

Observer la condition Ready

Côté Pod, la même information se lit dans la colonne READY, qui compte les conteneurs prêts sur le total. Attention à ne pas la confondre avec STATUS : un Pod peut rester Running indéfiniment tout en étant 0/1.

kubectl get pods -o wide

NAME      READY   STATUS    RESTARTS   AGE   IP
api-1     1/1     Running   0          1h    10.244.0.5
api-2     1/1     Running   0          1h    10.244.0.6
api-3     0/1     Running   0          1h    10.244.0.7  # Pas ready

La colonne READY montre 0/1 quand la readiness probe échoue.

Diagnostiquer une probe qui échoue

Une probe en échec laisse deux traces distinctes : des événements Unhealthy côté Kubernetes, qui indiquent quelle probe a échoué et avec quel message, et les logs applicatifs, qui disent pourquoi. Il faut les deux pour conclure, car le message du kubelet se limite au code de retour observé.

Étapes de diagnostic

Suivez cet ordre : il part de l'information la moins coûteuse à obtenir et se termine par le test manuel, qui seul permet de reproduire exactement ce que fait le kubelet.

1. Vérifier l'état du Pod

   kubectl get pod mon-pod -o wide
   kubectl describe pod mon-pod

   Cherchez les événements Unhealthy avec le type de probe concerné.

2. Lire les logs du conteneur

   kubectl logs mon-pod
   kubectl logs mon-pod --previous  # Si le conteneur a redémarré

3. Tester la probe manuellement

   kubectl exec mon-pod -- curl -v http://localhost:8080/healthz
   kubectl exec mon-pod -- cat /app/ready

4. Vérifier les événements du cluster

   kubectl get events --sort-by=.lastTimestamp | grep mon-pod

Messages d'erreur courants

Le message du kubelet nomme toujours la probe concernée en tête de ligne, ce qui indique immédiatement quel bloc du manifeste examiner. connection refused signifie que rien n'écoute sur le port ; un code HTTP signifie au contraire que l'application a répondu, mais mal.

Message	Cause probable	Solution
Liveness probe failed: connection refused	Application pas encore démarrée	Ajouter startupProbe ou augmenter initialDelaySeconds
Readiness probe failed: HTTP 503	Dépendance non disponible	Vérifier les connexions externes
Liveness probe failed: context deadline exceeded	Timeout trop court	Augmenter timeoutSeconds
Back-off restarting failed container	Probe en échec répété	Vérifier les logs avec --previous

Glissez pour voir

Exemple de sortie describe

La sortie ci-dessous montre le déroulé complet d'un redémarrage déclenché par une liveness probe. Les trois Unhealthy correspondent au failureThreshold atteint, et l'événement Killing qui suit confirme que c'est bien la probe, et non un plantage de l'application, qui a provoqué l'arrêt.

kubectl describe pod api-broken

Events:
  Type     Reason     Age   Message
  ----     ------     ----  -------
  Warning  Unhealthy  30s   Liveness probe failed: HTTP probe failed with statuscode: 503
  Warning  Unhealthy  20s   Liveness probe failed: HTTP probe failed with statuscode: 503
  Warning  Unhealthy  10s   Liveness probe failed: HTTP probe failed with statuscode: 503
  Normal   Killing    10s   Container api failed liveness probe, will be restarted

Contrôle de connaissances

Sept questions pour vérifier l'essentiel : rôle de chaque probe, ordre d'exécution, valeurs par défaut et anti-patterns. Elles ne portent que sur ce qui est expliqué dans cette page.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

7 questions

5 min.

80% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

1. startupProbe désactive les autres probes jusqu'à sa réussite
2. livenessProbe teste l'état interne, jamais les dépendances externes
3. readinessProbe contrôle l'inclusion dans les endpoints du Service
4. Une liveness trop agressive provoque des CrashLoopBackOff
5. timeoutSeconds à 1s par défaut est souvent trop court
6. Utilisez des endpoints différents pour liveness et readiness
7. Les probes sont configurées sur les conteneurs, pas les Pods
8. Sans startup probe, une appli lente redémarre pendant son init
9. Les probes exec sont plus coûteuses que HTTPGet
10. kubectl describe pod montre les événements Unhealthy

Pour aller plus loin

• Horizontal Pod Autoscaler : L'autoscaling, qui ignore les Pods non Ready dans son calcul de charge.
• Disponibilité applicative : Les garanties de disponibilité construites sur ces signaux de santé.

×

📖 Voir la documentation →