Dépanner les Kubernetes Jobs et CronJobs avec des exemples pratiques

Intro

Cette version française explique Kubernetes Jobs and CronJobs troubleshooting with practical examples avec le même objectif pratique que l article source : aider le lecteur à comprendre le contexte, les décisions à prendre et les points à vérifier avant de passer à l action.

Les Kubernetes Jobs exécutent des charges de travail courtes jusqu'à leur achèvement. Les Kubernetes CronJobs planifient ces Jobs à intervalles réguliers. Quand l'un des deux échoue, vous avez besoin d'un processus reproductible pour trouver vite la cause. Ce guide montre comment fonctionnent les retries et Kubernetes backoffLimit, où repérer les Pods en échec, comment lire les logs et événements, et comment dépanner en toute sécurité dans des clusters proches de la production. Vous trouverez aussi des manifestes et des commandes prêts à l'emploi.

Vue d'ensemble du workflow

Suivez ce chemin pour diagnostiquer la plupart des problèmes de Job et de CronJob :

1. Observer le contrôleur

• kubectl get job, kubectl get cronjob -o wide
• Notez les champs de statut : succeeded, failed, active, last schedule, suspend, concurrencyPolicy

1. Retrouver les Pods

• Pour un Job : kubectl get pods -l job-name=<job>
• Pour une exécution de CronJob : listez les Jobs avec ownerReferences ou un motif de nom, puis listez leurs Pods

1. Décrire pour lire événements et raisons

• kubectl describe job/<name>
• kubectl describe pod/<pod> (cherchez Reason/Message comme ImagePullBackOff, OOMKilled, Error, FailedScheduling)

1. Lire les logs

• kubectl logs <pod> [-c <container>]
• Si le container a crashé, ajoutez --previous
• Pour tous les Pods d'un Job : kubectl logs -l job-name=<job> --all-containers=true

1. Vérifier les écueils de spec

• Jobs : backoffLimit, activeDeadlineSeconds, parallelism, completions, restartPolicy
• CronJobs : schedule, startingDeadlineSeconds, concurrencyPolicy, suspend, history limits

1. Agir prudemment

• Mettre en pause un CronJob : kubectl patch cronjob/<name> -p '{"spec":{"suspend":true}}'
• Reproduire via un Job ad hoc depuis un CronJob : kubectl create job --from=cronjob/<cron> <tmp-job>
• Avancer avec un petit changement, surveiller événements et logs, puis réactiver

Ce flux couvre la majorité des cas de K8s job troubleshooting tout en évitant les effets de bord en production.

Jobs vs CronJobs en pratique

Les Jobs orchestrent des Pods jusqu'à atteindre le nombre de complétions souhaité. Les CronJobs créent des Jobs selon un horaire. Les différences clés pour le dépannage :

• Jobs : concentrez-vous sur le cycle de vie des Pods, les codes de sortie, Kubernetes backoffLimit et la pression de ressources.
• CronJobs : ajoutez l'évaluation du schedule, concurrencyPolicy, les exécutions manquées (startingDeadlineSeconds) et le nettoyage d'historique. Dans la pratique, on dépanne d'abord le Job engendré, puis on revient au CronJob si la planification pose problème.

Dépanner un Job en échec

1. Confirmer l'état

kubectl get job <name> -o wide

Regardez Succeeded, Failed, Active.

1. Vérifier les Pods

kubectl get pods -l job-name=<name>

S'il n'y en a aucun : vérifiez FailedScheduling ou les quotas avec kubectl describe job et kubectl describe pour les événements.

1. Inspecter événements et statut

kubectl describe pod <pod>

Signaux courants :

• ImagePullBackOff : image incorrecte ou secret de pull manquant.
• ErrImagePull : problème de registre ou d'authentification.
• OOMKilled : limite mémoire trop basse pour le processus.
• Error/Completed : vérifiez exitCode dans le status du container.

1. Lire les logs

kubectl logs <pod> --all-containers=true

Si le container redémarre dans le même Pod (restartPolicy : OnFailure), utilisez --previous.

1. Comprendre retries et backoffLimit

• backoffLimit : nombre maximal de retries de Pod avant que le Job soit marqué Failed. Exemple : backoffLimit: 2 autorise deux retries après le premier échec (3 tentatives au total).
• activeDeadlineSeconds : limite de temps dure pour le Job ; au-delà, le Job échoue.

1. Pistes de correction

• Erreurs d'image : corriger le tag ou ajouter imagePullSecrets.
• Pression de ressources : augmenter les limites mémoire/CPU ou optimiser la charge.
• Code de sortie non nul : gérer les erreurs dans l'app, ajouter des retries ou ajuster les entrées.
• Jobs lents : étendre activeDeadlineSeconds ou réduire parallelism pour soulager la pression.

Dépanner un CronJob en échec

1. Lister les CronJobs

kubectl get cronjob -o wide

Vérifiez SCHEDULE, SUSPEND, ACTIVE, LAST SCHEDULE.

1. Crée-t-il des Jobs ?

Si ACTIVE reste à 0 et LAST SCHEDULE ne bouge pas, le contrôleur peut être bloqué ou des filtres de planification s'appliquent. Inspectez :

• suspend : à true, aucune exécution ne sera créée.
• startingDeadlineSeconds : les exécutions manquées dont l'ancienneté dépasse ce délai sont ignorées.
• concurrencyPolicy : Forbid empêche un nouveau run si le précédent est encore actif ; Replace annule le run actif.

1. Inspecter le dernier Job engendré

kubectl get jobs --sort-by=.metadata.creationTimestamp

Prenez le Job le plus récent appartenant au CronJob et dépannez-le comme n'importe quel Job (événements, Pods, logs). Cherchez un CronJob failed pod pour remonter aux causes.

1. Opérations sûres

• Pause temporaire : kubectl patch cronjob/<name> -p '{"spec":{"suspend":true}}'
• Tester des changements via un Job one-off : kubectl create job --from=cronjob/<name> <tmp-job>
• Reprendre après validation : kubectl patch cronjob/<name> -p '{"spec":{"suspend":false}}'

Exemples pratiques

Exemple 1 : un Job qui échoue deux fois puis réussit

apiVersion: batch/v1
kind: Job
metadata:
  name: demo-backoff
spec:
  backoffLimit: 2
  template:
    spec:
      restartPolicy: OnFailure
      containers:
      - name: worker
        image: bash:5
        command: ["bash", "-lc", "if [ ! -f /tmp/ok ]; then echo first or second fail; touch /tmp/ok; exit 1; else echo success; fi"]

À observer :

• Le premier Pod sort avec 1 ; le contrôleur retente jusqu'à backoffLimit.
• La deuxième tentative échoue aussi ; la troisième réussit et affiche « success ».
• kubectl describe job/demo-backoff montre les Failed qui montent avant Succeeded.

Exemple 2 : CronJob bloqué par concurrencyPolicy=Forbid

apiVersion: batch/v1
kind: CronJob
metadata:
  name: report-job
spec:
  schedule: "*/5 * * * *"
  concurrencyPolicy: Forbid
  successfulJobsHistoryLimit: 2
  failedJobsHistoryLimit: 2
  jobTemplate:
    spec:
      backoffLimit: 1
      template:
        spec:
          restartPolicy: OnFailure
          containers:
          - name: reporter
            image: bash:5
            command: ["bash", "-lc", "echo starting; sleep 400; echo done"]

Pourquoi il ne s'exécute pas toutes les 5 minutes :

• Chaque run dure environ 6,6 minutes (400s). Avec Forbid, le déclenchement à 5 minutes qui arrive pendant un run actif est ignoré. LAST SCHEDULE peut ne pas avancer à chaque tick.
• Options de correction : mettre concurrencyPolicy: Allow, réduire le temps d'exécution, ou augmenter l'intervalle.

Exemple 3 : ImagePullBackOff dans un Job

apiVersion: batch/v1
kind: Job
metadata:
  name: bad-image
spec:
  template:
    spec:
      restartPolicy: OnFailure
      containers:
      - name: c
        image: example.com/private/app: does-not-exist

Dépannage :

• kubectl describe pod montre ErrImagePull/ImagePullBackOff.
• Corrigez le tag ou configurez imagePullSecrets et l'URL de registre.

Exemple 4 : OOMKilled dans un Job

apiVersion: batch/v1
kind: Job
metadata:
  name: mem-tight
spec:
  template:
    spec:
      restartPolicy: OnFailure
      containers:
      - name: c
        image: python:3.11
        resources:
          requests: { memory: "64Mi", cpu: "100m" }
          limits:   { memory: "64Mi", cpu: "200m" }
        command: ["python", "-c", "a='x'*200_000_000; print(len(a))"]

Dépannage :

• kubectl describe pod indique OOMKilled dans le last state.
• Augmentez la limite mémoire (par exemple 256Mi) ou réduisez l'usage mémoire du programme.

Plan pilote local

Démarrez petit et mesurable :

1. Choisir un Job avec un critère de succès clair

• Exemple : transformer un petit fichier d'entrée et écrire un checksum.
• Définissez « fini » comme exit code 0 et présence d'une ligne de sortie.

1. Faciliter l'inspection

• Ajoutez des logs structurés et un message final de succès.
• Réglez backoffLimit à 1 et activeDeadlineSeconds à une borne sûre.

1. Valider dans un cluster local

• Appliquez le Job, surveillez événements et logs de bout en bout.
• Relevez la durée d'exécution et l'usage des ressources.

1. L'envelopper dans un CronJob (optionnel)

• Choisissez d'abord une planification prudente (par ex. chaque heure).
• Mettez concurrencyPolicy à Forbid tant que l'idempotence n'est pas prouvée.

1. Étendre graduellement

• Augmentez la taille d'entrée, puis le parallelism.
• Ajoutez des alertes sur les échecs de Job et les schedules manqués.

Ce plan réduit le risque et accélère la boucle de feedback, tout en gardant une posture sûre pour le Kubernetes debugging. Si votre environnement utilise aussi des Kubernetes Deployments pour des workers, isolez les tests des Jobs/CronJobs afin d'éviter les effets croisés.

Conclusion

Les Jobs et CronJobs échouent pour des raisons compréhensibles : images invalides, pression de ressources, codes de sortie non nuls ou règles de planification non adaptées. Le chemin le plus rapide reste constant : vérifier l'état du contrôleur, trouver les Pods, lire les événements, inspecter les logs et valider les champs backoffLimit, activeDeadlineSeconds, schedule et concurrencyPolicy. Utilisez la suspension et des Jobs ad hoc pour tester en sécurité, puis avancez par petites étapes. Gardez des exécutions courtes, des sorties claires et des critères de succès évidents - c'est ainsi que vous dépannez avec confiance.