kubectl diff et wait : prévisualiser et synchroniser vos déploiements

Vous êtes sur le point de lancer kubectl apply — mais que va-t-il réellement changer dans le cluster ? Et une fois appliqué, comment savoir que le déploiement est effectivement prêt avant de passer à l’étape suivante ? kubectl diff vous montre exactement les modifications avant de les appliquer. kubectl wait bloque jusqu’à ce qu’une ressource atteigne l’état attendu. Ensemble, ces deux commandes transforment un déploiement manuel en un workflow fiable et automatisable.

Ce que vous allez apprendre

• Prévisualiser les changements d’un manifest avec kubectl diff avant d’appliquer
• Lire une sortie diff et comprendre ce qui va être ajouté, modifié ou supprimé
• Intégrer diff dans un pipeline CI/CD pour bloquer les changements non attendus
• Attendre qu’un pod, deployment, job ou certificat soit prêt avec kubectl wait
• Écrire des scripts de déploiement robustes combinant diff → apply → wait

Quand utiliser chaque commande

Moment	Commande	Ce qu’elle fait
Avant apply — vérifier les changements	kubectl diff -f manifest.yaml	Affiche un diff entre le cluster et le fichier
Après apply — attendre que ce soit prêt	kubectl wait --for=condition=Ready ...	Bloque jusqu’à l’état attendu (ou timeout)
En CI/CD — valider puis synchroniser	diff → apply → wait	Workflow complet et fiable

Glissez pour voir

kubectl diff : que va changer mon apply ?

kubectl diff compare le contenu d’un manifest (fichier YAML) avec l’état actuel de la ressource dans le cluster. La sortie est un diff standard (comme git diff) : les lignes - seront supprimées/remplacées, les lignes + seront ajoutées.

Syntaxe

kubectl diff -f <fichier.yaml> [-n namespace]

Premier exemple

Supposons que vous modifiez l’image d’un Deployment dans votre fichier api-gateway.yaml :

kubectl diff -f api-gateway.yaml

spec:
  containers:
  - name: api-gateway
    image: nginx:1.25
    image: nginx:1.27
    ports:
    - containerPort: 8080

Ce diff vous indique clairement : l’image passera de nginx:1.25 à nginx:1.27. Rien d’autre ne change.

Le code retour compte

kubectl diff retourne un code de sortie exploitable dans les scripts :

• 0 : aucune différence (le cluster est déjà à jour)
• 1 : des différences existent (il y a quelque chose à appliquer)
• > 1 : une erreur s’est produite

kubectl diff -f api-gateway.yaml > /dev/null 2>&1
echo $?  # 0 = rien à faire, 1 = changements détectés

Comparer un dossier de manifests

diff fonctionne aussi avec un dossier entier ou un répertoire Kustomize :

# Tous les manifests d'un dossier
kubectl diff -f ./k8s/prod/

# Avec Kustomize
kubectl diff -k ./overlays/production/

Personnaliser le programme de diff

Par défaut, kubectl diff utilise un diff interne. Vous pouvez le remplacer par un outil plus lisible :

# Utiliser colordiff pour une sortie colorée
export KUBECTL_EXTERNAL_DIFF="colordiff -u"
kubectl diff -f api-gateway.yaml

# Utiliser dyff pour un diff structuré YAML
export KUBECTL_EXTERNAL_DIFF="dyff between --omit-header"
kubectl diff -f api-gateway.yaml

diff côté serveur (server-side)

Par défaut, kubectl diff calcule le diff côté client. Pour une précision maximale (identique à ce que apply fera réellement), utilisez le mode server-side :

kubectl diff -f api-gateway.yaml --server-side

Cela envoie une requête dry-run server-side et compare le résultat avec l’état actuel. Utile quand des webhooks de mutation modifient vos manifests.

Intégrer diff dans un pipeline CI/CD

kubectl diff est un excellent garde-fou dans un pipeline de déploiement :

GitLab CI

diff:
  stage: validate
  script:
    - kubectl diff -f ./k8s/prod/ || true
  # Le || true empêche l'échec du job (exit code 1 = changements)

deploy:
  stage: deploy
  script:
    - kubectl apply -f ./k8s/prod/
    - kubectl wait --for=condition=Available deploy/api-gateway -n prod --timeout=300s
  when: manual  # Validation humaine après review du diff

GitHub Actions

- name: Preview changes
  run: |
    kubectl diff -f ./k8s/prod/ || true

- name: Deploy
  if: github.ref == 'refs/heads/main'
  run: |
    kubectl apply -f ./k8s/prod/
    kubectl wait --for=condition=Available deploy/api-gateway -n prod --timeout=300s

Workflow complet : diff → apply → verify

1. Prévisualisez les changements

   kubectl diff -f api-gateway.yaml

   Lisez la sortie. Si quelque chose vous surprend, arrêtez-vous là.

2. Appliquez si le diff est conforme

   kubectl apply -f api-gateway.yaml

3. Vérifiez que l’apply a bien fonctionné

   kubectl rollout status deploy/api-gateway -n prod

kubectl wait : attendre qu’une ressource soit prête

kubectl wait bloque l’exécution jusqu’à ce qu’une ressource atteigne une condition donnée, ou jusqu’à expiration du timeout. C’est l’outil de synchronisation de kubectl.

Syntaxe

kubectl wait --for=condition=<condition> <type>/<nom> [-n namespace] --timeout=<durée>

Conditions les plus utilisées

Type de ressource	Condition	Ce que ça attend
Pod	condition=Ready	Le pod a passé ses readiness probes
Deployment	condition=Available	Le nombre de réplicas souhaité est prêt
Job	condition=Complete	Le job s’est terminé avec succès
Job	condition=Failed	Le job a échoué (utile pour détecter les erreurs)
Certificate (Cert-Manager)	condition=Ready	Le certificat TLS a été émis
Pod	delete	Le pod a été supprimé (n’existe plus)

Glissez pour voir

Recettes essentielles

Attendre qu’un Deployment soit prêt

kubectl wait --for=condition=Available deploy/api-gateway -n prod --timeout=120s

deployment.apps/api-gateway condition met

Attendre qu’un pod soit Ready

kubectl wait --for=condition=Ready pod/api-server-7d4b8c -n prod --timeout=60s

Attendre tous les pods d’un label

kubectl wait --for=condition=Ready pods -l app=api-gateway -n prod --timeout=120s

Attendre la fin d’un Job

kubectl wait --for=condition=Complete job/migration-db -n prod --timeout=300s

Attendre la suppression d’un pod

Utile dans les scripts de drain ou de remplacement :

kubectl delete pod api-server-7d4b8c -n prod
kubectl wait --for=delete pod/api-server-7d4b8c -n prod --timeout=60s

Attendre un certificat TLS (Cert-Manager)

kubectl wait --for=condition=Ready certificate/api-tls -n prod --timeout=120s

Timeout et code de sortie

wait retourne un code de sortie exploitable :

Code retour	Signification
0	La condition est atteinte dans le délai
1	Timeout expiré — la condition n’a pas été atteinte

Glissez pour voir

Toujours mettre un timeout

Sans --timeout, kubectl wait attend indéfiniment. Dans un script ou un pipeline, cela peut bloquer toute la chaîne. Mettez toujours un timeout adapté à la ressource attendue.

# ❌ Risque de blocage infini
kubectl wait --for=condition=Ready pod/mon-pod

# ✅ Timeout explicite
kubectl wait --for=condition=Ready pod/mon-pod --timeout=120s

Attendre avec jsonpath (conditions personnalisées)

Pour des conditions non standard, utilisez --for=jsonpath= :

# Attendre que le champ .status.phase soit "Running"
kubectl wait --for=jsonpath='{.status.phase}'=Running pod/mon-pod -n prod --timeout=60s

# Attendre que le nombre de réplicas disponibles soit 3
kubectl wait --for=jsonpath='{.status.availableReplicas}'=3 deploy/api-gateway -n prod --timeout=120s

jsonpath — puissant mais fragile

Les conditions jsonpath nécessitent que le champ et la valeur correspondent exactement (type inclus). Si availableReplicas est un entier 3 mais que vous écrivez "3" (string), ça ne matchera pas. Vérifiez d’abord la valeur réelle :

kubectl get deploy api-gateway -n prod -o jsonpath='{.status.availableReplicas}'

Combiner diff et wait dans un script de déploiement

Voici un script complet qui illustre le workflow sécurisé :

#!/usr/bin/env bash
set -euo pipefail

NAMESPACE="prod"
MANIFEST="./k8s/prod/"
DEPLOY="api-gateway"
TIMEOUT="300s"

echo "=== 1. Prévisualisation des changements ==="
if kubectl diff -f "$MANIFEST" -n "$NAMESPACE" > /dev/null 2>&1; then
  echo "Aucun changement détecté — rien à faire."
  exit 0
fi

kubectl diff -f "$MANIFEST" -n "$NAMESPACE" || true
echo ""

echo "=== 2. Application des changements ==="
kubectl apply -f "$MANIFEST" -n "$NAMESPACE"

echo "=== 3. Attente que le déploiement soit prêt ==="
if kubectl wait --for=condition=Available "deploy/$DEPLOY" \
  -n "$NAMESPACE" --timeout="$TIMEOUT"; then
  echo "✅ Déploiement réussi."
else
  echo "❌ Timeout — le déploiement n'est pas prêt."
  kubectl rollout status "deploy/$DEPLOY" -n "$NAMESPACE"
  exit 1
fi

rollout status vs wait

kubectl rollout status et kubectl wait --for=condition=Available semblent similaires, mais :

• rollout status affiche la progression en temps réel (utile pour un humain)
• wait est silencieux et retourne un code de sortie net (idéal pour les scripts)

Dans un script, utilisez wait pour la logique, et rollout status pour le debug en cas d’échec.

Bonnes pratiques

kubectl diff

• Toujours exécuter diff avant apply — c’est votre filet de sécurité
• Intégrez diff comme première étape de votre pipeline CI/CD
• Utilisez --server-side quand des webhooks de mutation sont en place
• Définissez KUBECTL_EXTERNAL_DIFF pour une sortie lisible (colordiff, dyff)
• En CI, exploitez le code retour (0 = rien à faire, 1 = changements)

kubectl wait

• Toujours mettre un --timeout — jamais d’attente infinie dans un script
• Préférez les selectors (-l app=...) aux noms de pods pour les déploiements multi-réplicas
• Utilisez --for=delete après un kubectl delete pour s’assurer que la ressource a disparu
• Combinez avec set -e dans vos scripts pour arrêter le pipeline en cas de timeout
• Pour des conditions exotiques, utilisez --for=jsonpath= avec vérification préalable du format

Dépannage

Symptôme	Cause probable	Solution
diff ne montre aucun changement	Le manifest est identique à l’état du cluster	Vérifiez que vous avez modifié et sauvegardé le fichier
diff retourne un code > 1	Erreur (manifest invalide, ressource inexistante…)	Vérifiez la syntaxe YAML et que la ressource existe avec kubectl get
Diff montre des champs que vous n’avez pas modifiés	Champs ajoutés par les defaults ou webhooks	C’est normal — utilisez --server-side pour un diff plus précis
diff échoue avec unauthorized	Le ServiceAccount n’a pas le droit de faire un dry-run	Ajoutez les verbes create en dry-run dans le RBAC
wait timeout expiré (code 1)	La ressource n’atteint pas la condition dans le délai	Vérifiez kubectl describe <type>/<nom> pour comprendre pourquoi (events, erreurs)
wait bloque indéfiniment	Pas de --timeout spécifié	Ajoutez --timeout=120s (ou la durée adaptée)
wait échoue : resource not found	La ressource n’existe pas (encore)	Attendez sa création d’abord, ou utilisez kubectl wait après kubectl apply
wait --for=jsonpath ne matche pas	Type de la valeur incorrect (string vs int)	Vérifiez avec kubectl get -o jsonpath='{...}' le format exact
wait avec selector ne retourne rien	Aucun pod ne matche le label	Vérifiez avec kubectl get pods -l <selector> -n <ns>

Glissez pour voir

À retenir

• kubectl diff est votre filet de sécurité : il montre ce qui va changer avant apply — pas après.
• Le code retour de diff est exploitable : 0 = rien à faire, 1 = changements à appliquer, > 1 = erreur.
• kubectl wait bloque jusqu’à une condition (Ready, Available, Complete, delete) — indispensable en CI/CD.
• Mettez toujours un --timeout sur wait — une attente infinie dans un pipeline est une bombe à retardement.
• Utilisez --for=jsonpath= pour des conditions personnalisées sur n’importe quel champ du status.
• Le workflow de base en prod : diff → apply → wait — simple, fiable, scriptable.
• Personnalisez l’affichage du diff avec KUBECTL_EXTERNAL_DIFF (colordiff, dyff).

Prochaines étapes

Créer et déployer avec create et apply Le apply que diff prévisualise — l'approche déclarative complète.

Scale, autoscale et rollout Gérer les mises à jour progressives et les rollbacks après un apply.

Diagnostiquer avec get, describe et logs Comprendre pourquoi un wait timeout — describe et events sont vos alliés.

Explorer l'API Kubernetes Trouver les conditions disponibles sur chaque type de ressource avec explain.

Modifier avec edit, patch et replace Modifier une ressource quand diff révèle un changement inattendu.

×

📖 Voir la documentation →