Maîtriser kubectl : cheat sheet interactif

kubectl est l'outil CLI qui parle directement à l'API Server Kubernetes. Chaque commande suit le même schéma : verbe (get, apply, delete) → type (pod, deployment, service) → nom → options (-n, -o, -l). Que ce soit pour inspecter un cluster, déployer une application ou diagnostiquer un incident, kubectl est votre point d'entrée unique.

Ce que vous allez apprendre

• Inspecter un cluster (get, describe, logs, top, events)
• Créer et modifier des ressources (apply, create, patch, edit)
• Déployer et rollback (rollout, scale, set image, autoscale)
• Déboguer des Pods (exec, debug, port-forward, logs --previous)
• Maintenir des nœuds (cordon, drain, taint, uncordon)
• Automatiser dans un pipeline CI/CD (diff, wait, dry-run)

kubectl dans l'écosystème Kubernetes

kubectl est la CLI officielle de Kubernetes, mais d'autres outils le complètent :

Outil	Spécialité	Quand l'utiliser
kubectl	CLI officielle Kubernetes	Toutes les opérations cluster
k9s	TUI interactif	Navigation et debug en temps réel
helm	Gestionnaire de paquets	Installer des applications packagées
kustomize	Overlays YAML	Personnaliser sans templates
stern	Multi-pod log tailing	Suivre les logs de plusieurs Pods
kubectx/kubens	Changement de contexte rapide	Naviguer entre clusters/namespaces

Glissez pour voir

Combinaisons fréquentes :

# kubectl + jq : extraire des données structurées
kubectl get pods -o json | jq '.items[].metadata.name'

# kubectl + stern : logs multi-pods en couleur
stern -n production "web-.*"

# kubectl + kustomize : appliquer des overlays
kubectl apply -k overlays/production/

Comprendre kubectl en 2 min

🧠 Modèle mental — Comment fonctionne kubectl

kubectl = Verbe → Type de ressource → Nom → Options

Points clés

• kubectl envoie des requêtes à l'API Server Kubernetes
• Chaque commande suit le pattern : verbe + type de ressource + nom
• Le contexte (~/.kube/config) définit QUEL cluster tu vises
• Les options -n (namespace) et -o (output) sont partout
• --dry-run=client -o yaml génère un manifeste sans rien créer
• apply est déclaratif (idempotent), create est impératif (erreur si existe)

Règles d'or

1

Toujours vérifier le contexte avant d'agir kubectl config current-context — une commande sur le mauvais cluster peut être catastrophique.

2

Prévisualiser avant d'appliquer en prod kubectl diff -f manifest.yaml montre ce qui va changer, sans rien toucher.

3

Utiliser apply plutôt que create pour la reproductibilité apply est idempotent : relancer la même commande ne casse rien.

Vocabulaire essentiel

get

Lister les ressources (pods, svc, deploy...)

describe

Détails complets + événements d'une ressource

apply -f

Créer ou mettre à jour depuis un fichier YAML

delete

Supprimer une ressource

-n namespace

Cibler un namespace spécifique

-o yaml/json/wide

Changer le format de sortie

📚 Pour aller plus loin — 17 options avancées

explain

Documentation intégrée d'un champ YAML

api-resources

Lister tous les types de ressources disponibles

patch

Modifier un champ sans remplacer toute la ressource

rollout

Gérer les mises à jour progressives (status, undo, restart, history)

drain

Évacuer un nœud avant maintenance

taint/toleration

Contrôler quels Pods vont sur quels nœuds

port-forward

Tunnel local vers un Pod/Service

--dry-run=client

Simuler sans envoyer à l'API Server

jsonpath

Extraire un champ spécifique de la sortie

wait --for=condition

Attendre qu'une ressource atteigne un état

diff -f

Comparer un manifeste avec l'état du cluster

debug

Conteneur éphémère pour déboguer un Pod distroless

auth can-i

Vérifier les droits RBAC d'un utilisateur

--server-side

Apply côté serveur (résout les conflits de champs)

custom-columns

Colonnes personnalisées pour la sortie de get

rollout restart

Redémarrer les Pods d'un Deployment sans downtime

config get-contexts

Lister tous les contextes kubeconfig disponibles

kubectl transforme chaque commande en requête REST vers l'API Server. Le fichier ~/.kube/config (kubeconfig) définit quel cluster, quel utilisateur et quel namespace sont ciblés.

Syntaxe minimale

Toutes les commandes kubectl respectent le même ordre positionnel. Retenir ce squelette évite de chercher dans quel sens écrire les arguments : le verbe vient toujours en premier, les options toujours en dernier. Les crochets signalent les parties facultatives : sans nom, la commande porte sur toutes les ressources du type.

kubectl [VERBE] [TYPE] [NOM] [OPTIONS]

Les 4 parties d'une commande kubectl

Étape	Question	Exemples	Obligatoire ?
Verbe	Quelle action ?	get, apply, delete, describe	Oui
Type	Sur quel type de ressource ?	pod, deployment, service, node	Oui (sauf commandes globales)
Nom	Quelle ressource précise ?	my-app, web-7d4f8b6c9	Non (toutes si omis)
Options	Quels paramètres ?	-n staging, -o yaml, -l app=web	Non

Glissez pour voir

Verbe, L'action à effectuer. get pour lister, describe pour les détails, apply pour créer/mettre à jour, delete pour supprimer.

Type, Le type de ressource Kubernetes. On peut utiliser les formes courtes : po (pods), svc (services), deploy (deployments), ns (namespaces).

Nom, Cible une ressource précise. Sans nom, la commande s'applique à toutes les ressources du type.

Options, Modifient le comportement : -n (namespace), -o (format), -l (sélecteur de labels), --watch (suivre en temps réel).

Les verbes essentiels

Kubernetes expose des dizaines de verbes, mais une trentaine suffit au quotidien. Le tableau les regroupe par intention plutôt que par ordre alphabétique : c'est la colonne « Catégorie » qui vous sert d'entrée. Les verbes de lecture ne modifient jamais le cluster, vous pouvez les lancer sans crainte en production. Ceux d'écriture et de maintenance de nœuds exigent au contraire une vérification du contexte actif avant chaque exécution.

Catégorie	Verbes	Usage
Lecture	get, describe, logs, top, explain	Inspecter le cluster
Écriture	apply, create, delete, edit, patch, replace	Modifier les ressources
Déploiement	rollout, scale, set, autoscale	Gérer les mises à jour
Debug	exec, debug, port-forward, cp, attach	Diagnostiquer
Nœuds	cordon, uncordon, drain, taint	Maintenance
CI/CD	diff, wait, --dry-run=client	Automatisation

Glissez pour voir

Options incontournables

Ces huit options se combinent entre elles et couvrent la quasi-totalité des besoins. Deux méritent une attention particulière : -n est la première cause de résultat vide (sans elle, kubectl interroge le namespace default), et --dry-run=client est le réflexe qui permet de générer du YAML sans toucher au cluster. Notez la différence entre -l, qui filtre sur les labels posés par vous, et --field-selector, qui filtre sur les champs de l'objet gérés par Kubernetes.

Option	Usage	Exemple
-n namespace	Cibler un namespace	kubectl get pods -n production
-A	Tous les namespaces	kubectl get pods -A
-o yaml/json/wide	Changer le format de sortie	kubectl get svc web -o yaml
-o jsonpath='{...}'	Extraire un champ	kubectl get pod x -o jsonpath='{.status.podIP}'
-l key=value	Filtrer par labels	kubectl get pods -l app=nginx
--dry-run=client	Simuler sans créer	kubectl create deploy x --image=y --dry-run=client -o yaml
-w / --watch	Suivre en temps réel	kubectl get pods -w
--field-selector	Filtrer sur un champ objet	--field-selector=status.phase=Running

Glissez pour voir

Le workflow type en production

Un déploiement manuel sur un cluster de production suit toujours la même séquence de cinq commandes. Son intérêt tient à l'ordre : la vérification du contexte vient avant tout, le diff sert de garde-fou avant l'écriture, et rollout status bloque tant que les nouveaux Pods ne sont pas prêts. Sans cette dernière commande, vous rendez la main alors que le déploiement est encore en cours et vous ne verrez pas un ImagePullBackOff qui arrive dix secondes plus tard.

# 1. Vérifier le contexte
kubectl config current-context

# 2. Prévisualiser les changements
kubectl diff -f deployment.yaml

# 3. Appliquer
kubectl apply -f deployment.yaml

# 4. Suivre le déploiement
kubectl rollout status deployment/web

# 5. Vérifier
kubectl get pods -l app=web -o wide

Erreurs typiques (et solutions)

Quatre messages reviennent en boucle chez les débutants, et aucun n'indique une panne du cluster. Le point commun : kubectl répond exactement à ce qu'on lui a demandé, mais la question portait sur le mauvais cluster, le mauvais namespace ou le mauvais type de ressource. Lisez la colonne « Cause » avant la colonne « Solution », c'est elle qui vous évitera de reproduire l'erreur.

Erreur	Cause	Solution
Connection refused localhost:8080	Kubeconfig absent ou cluster non démarré	Vérifier $KUBECONFIG et le cluster
"get all" ne montre pas les Secrets	all est un alias limité	Lister les types spécifiques
create échoue "already exists"	create est impératif	Utiliser apply (idempotent)
Résultats vides	Mauvais namespace	Ajouter -n NS ou chercher avec -A

Glissez pour voir

Les modèles de commandes courants

Maintenant que vous comprenez la logique de kubectl, voici les patterns prêts à l'emploi pour les opérations les plus fréquentes. Chacun associe une formule générique et un exemple concret à adapter.

Lister les ressources d'un namespace

Obtenir une vue d'ensemble d'un namespace, remplace le réflexe trompeur de get all.

# Formule
kubectl get deploy,rs,po,svc,ing,cm,secret -n <namespace> [-o wide]

# Exemple
kubectl get deploy,rs,po,svc,ing,cm,secret -n production

get all ne montre pas tout (ni ConfigMaps, ni Secrets, ni Ingress, ni PVC). Listez toujours les types explicitement.

Diagnostiquer avec describe

Comprendre pourquoi une ressource est en erreur, événements inclus.

# Formule
kubectl describe <type> <nom> -n <namespace>

# Exemple
kubectl describe pod my-app-7d4f8b6c9-x2k4m -n staging

• describe affiche les détails complets et la section Events, essentielle au diagnostic.

Logs multi-conteneurs

Suivre les logs d'un Pod ou d'un ensemble de Pods.

# Formule
kubectl logs [-f] [-c <conteneur>] [--previous] <pod> -n <ns>

# Exemple
kubectl logs -f -l app=nginx -n production --all-containers

• -f : suivre en temps réel ; --previous : logs du conteneur précédent (après un crash) ; -l : tous les Pods correspondant au label.

Générer un manifeste YAML

Créer un squelette YAML sans toucher au cluster.

# Formule
kubectl create <type> <nom> [options] --dry-run=client -o yaml

# Exemple
kubectl create deployment nginx --image=nginx:1.26 --replicas=3 --dry-run=client -o yaml > deploy.yaml

• --dry-run=client : simule côté client, sans appel à l'API.

Appliquer un manifeste (déclaratif)

Créer ou mettre à jour une ressource de façon idempotente.

# Formule
kubectl apply -f <fichier.yaml> -n <namespace>

# Exemple
kubectl apply -f deployment.yaml -n production

• -f : fichier ou dossier YAML ; -R : récursif ; --prune : supprime les ressources non déclarées.

Extraire un champ avec JSONPath

Récupérer une valeur précise pour du scripting.

# Formule
kubectl get <type> <nom> -o jsonpath='{.spec.field}'

# Exemple
kubectl get pod nginx -o jsonpath='{.status.podIP}'

• jsonpath cible un champ dans la structure de l'objet.

Diff avant apply

Voir ce qui va changer avant d'appliquer.

# Formule
kubectl diff -f <fichier.yaml>

# Exemple
kubectl diff -f deployment.yaml

En production, ne jamais appliquer sans avoir vérifié le diff au préalable.

Rollback d'un déploiement

Revenir à la version précédente après un déploiement raté.

# Formule
kubectl rollout undo deployment/<nom> [--to-revision=N]

# Exemple
kubectl rollout undo deployment/web --to-revision=2

• --to-revision : numéro de révision cible (par défaut, la révision N-1).

Shell dans un conteneur

Inspecter un conteneur en cours d'exécution.

# Formule
kubectl exec -it <pod> -n <ns> [-c <conteneur>] -- <commande>

# Exemple
kubectl exec -it web-7d4f8b6c9-x2k4m -n production -- /bin/sh

Pour les Pods distroless (sans shell), utilisez plutôt kubectl debug.

Maintenance d'un nœud

Préparer un nœud pour une maintenance (upgrade, reboot).

# Formule
kubectl cordon <noeud> && kubectl drain <noeud> --ignore-daemonsets --delete-emptydir-data

# Exemple
kubectl cordon worker-01 && kubectl drain worker-01 --ignore-daemonsets --delete-emptydir-data

--delete-emptydir-data est destructif : il supprime les volumes emptyDir. Vérifiez qu'aucun Pod n'y stocke de données critiques avant de drainer.

Tunnel local vers un Pod ou Service

Accéder à un service sans Ingress ni LoadBalancer.

# Formule
kubectl port-forward <type>/<nom> <local>:<distant> -n <ns>

# Exemple
kubectl port-forward svc/grafana 3000:3000 -n monitoring

• local:distant : port local mappé sur le port du conteneur ou du service.

Attendre une condition (CI/CD)

Bloquer un pipeline jusqu'à ce qu'une ressource soit prête.

# Formule
kubectl wait --for=condition=<cond> <type>/<nom> --timeout=<durée>

# Exemple
kubectl wait --for=condition=Available deployment/web --timeout=120s

• condition : Ready, Available, Complete… ; --timeout : durée maximale.

Vérifier et changer de contexte

Éviter d'exécuter une commande sur le mauvais cluster.

# Formule
kubectl config current-context && kubectl config use-context <ctx>

# Exemple
kubectl config current-context && kubectl config use-context staging-cluster

Pour cibler ponctuellement un contexte sans changer le contexte global : kubectl --context=staging-cluster get pods.

Apply server-side (production)

Appliquer des manifestes en résolvant les conflits de champs côté serveur.

# Formule
kubectl apply -f <fichier> --server-side --force-conflicts

# Exemple
kubectl apply -f k8s/ --server-side --force-conflicts

• --server-side : le serveur gère les field managers ; --force-conflicts : prend possession des champs en conflit.

Vérifier les droits RBAC

Savoir ce qu'un utilisateur ou un ServiceAccount peut faire.

# Formule
kubectl auth can-i <verbe> <type> -n <namespace>

# Exemple
kubectl auth can-i create deployments -n production

Pour tout voir d'un coup : kubectl auth can-i --list -n production.

Déboguer avec les Events

Voir ce qui s'est passé récemment dans un namespace.

# Formule
kubectl get events -n <ns> --sort-by=.metadata.creationTimestamp

# Exemple
kubectl get events -n production --sort-by=.metadata.creationTimestamp | tail -20

• --field-selector reason=Failed filtre directement sur les erreurs.

Redémarrer un Deployment proprement

Relancer tous les Pods sans changer le manifeste (rotation de secrets, refresh).

# Formule
kubectl rollout restart deployment/<nom> -n <ns>

# Exemple
kubectl rollout restart deployment/web -n production && kubectl rollout status deployment/web -n production --timeout=120s

Préférez cela à la suppression des Pods un par un, qui peut provoquer du downtime.

Sortie personnalisée avec custom-columns

Extraire exactement les colonnes dont vous avez besoin.

# Formule
kubectl get <type> -o custom-columns=COL1:.path,COL2:.path

# Exemple
kubectl get pod -o custom-columns=NAME:.metadata.name,IP:.status.podIP,NODE:.spec.nodeName

• custom-columns : liste de paires COLONNE:jsonpath séparées par des virgules.

Les pièges à éviter

Ces erreurs reviennent constamment avec kubectl. Plusieurs peuvent provoquer un incident de production : les connaître est indispensable.

Mauvais contexte actif

Vous lancez kubectl delete deployment web en pensant être sur le cluster de dev.

Symptôme : la ressource est supprimée en production.

Cause : le contexte courant pointe sur le cluster de production.

kubectl config current-context && kubectl delete deployment web

get all ne montre pas tout

kubectl get all

Symptôme : ConfigMaps, Secrets, Ingress, PVC… n'apparaissent pas, vous croyez le namespace vide.

Cause : all est la catégorie de ressources déclarée par l'API Server, pas un joker. Elle regroupe les pods, replicationcontrollers, services, daemonsets, deployments, replicasets, statefulsets, horizontalpodautoscalers, cronjobs et jobs. Pour connaître son contenu exact sur votre cluster : kubectl api-resources -o wide et lisez la colonne CATEGORIES.

kubectl get deploy,rs,po,svc,ing,cm,secret -n NS

create échoue si la ressource existe

kubectl create -f deploy.yaml

Symptôme : Error: already exists quand le script est relancé.

Cause : create est impératif, il refuse de recréer une ressource existante.

kubectl apply -f deploy.yaml

Oubli du namespace

kubectl get pods

Symptôme : aucun résultat, ou les résultats du mauvais namespace.

Cause : sans -n, kubectl utilise le namespace default.

kubectl get pods -n production

--delete-local-data est déprécié

kubectl drain node1 --delete-local-data

Symptôme : avertissement --delete-local-data is deprecated.

Cause : l'option a été renommée dans les versions récentes.

kubectl drain node1 --ignore-daemonsets --delete-emptydir-data

Oubli du -- dans exec

kubectl exec -it pod-name /bin/sh

Symptôme : erreur ou comportement inattendu.

Cause : sans --, kubectl peut interpréter les arguments de la commande comme ses propres options.

kubectl exec -it pod-name -- /bin/sh

Sélecteur de labels mal formé

kubectl get pods -l app=web, env=prod

Symptôme : erreur de parsing ou résultats incorrects.

Cause : les sélecteurs n'acceptent pas d'espace autour de la virgule.

kubectl get pods -l app=web,env=prod

delete --force sans comprendre

kubectl delete pod stuck-pod --force --grace-period=0

Symptôme : le Pod disparaît de l'API, mais le conteneur tourne peut-être encore sur le nœud.

Cause : --force supprime l'objet API immédiatement, sans attendre l'arrêt réel du conteneur. Réservez-le aux nœuds définitivement morts ; sinon, diagnostiquez d'abord.

Supprimer les Pods au lieu de rollout restart

kubectl delete pod -l app=web

Symptôme : downtime potentiel si tous les Pods sont supprimés en même temps.

Cause : delete supprime instantanément, sans rolling update.

kubectl rollout restart deployment/web -n production

Conflit de field managers en server-side apply

kubectl apply -f deploy.yaml --server-side

Symptôme : Apply failed: conflict with "kubectl-client-side-apply"….

Cause : un autre outil (Helm, Argo, kubectl client-side) possède certains champs.

kubectl apply -f deploy.yaml --server-side --force-conflicts

Erreur Forbidden sans diagnostic

Vous recevez Forbidden sans savoir quel droit manque.

Symptôme : Error from server (Forbidden): pods is forbidden.

Cause : le ServiceAccount n'a pas le Role ou ClusterRole nécessaire.

kubectl auth can-i --list -n production

Logs sans --since sur un Pod ancien

kubectl logs pod/web-xxx

Symptôme : défilement interminable de logs anciens, terminal bloqué.

Cause : par défaut, logs affiche tout l'historique disponible.

kubectl logs pod/web-xxx --since=10m --tail=200

Travaux pratiques

Ce lab vous fait manipuler kubectl sur une application de test déployée dans un namespace dédié. Comptez 20 minutes. Il suppose un cluster Kubernetes accessible (kind, minikube, k3s, k3d…).

Préparer le terrain

Le script suivant déploie une application web, une application qui crashe (pour le debug) et un ConfigMap :

# Créer le namespace de lab
kubectl create namespace kubectl-lab

# Déployer une application de test
kubectl -n kubectl-lab create deployment web --image=nginx:1.25 --replicas=2
kubectl -n kubectl-lab expose deployment web --port=80 --target-port=80

# Déployer une app qui crashe (pour le debug)
kubectl -n kubectl-lab run crashloop --image=busybox -- /bin/sh -c "exit 1"

# Ajouter des labels
kubectl -n kubectl-lab label deployment web env=staging tier=frontend

# Créer un ConfigMap
kubectl -n kubectl-lab create configmap app-config --from-literal=ENV=staging --from-literal=LOG_LEVEL=info

kubectl -n kubectl-lab get all

Pour tout nettoyer à la fin : kubectl delete namespace kubectl-lab.

Les 8 étapes du lab

Chaque étape se lit en trois temps : la commande, ce que vous devez voir, puis l'option qui explique le résultat. Enchaînez-les dans l'ordre, car les étapes 5 à 8 travaillent sur le Deployment web créé juste avant. Si une sortie diffère de ce qui est décrit, relancez kubectl get pods -n kubectl-lab : la plupart des écarts viennent d'un Pod pas encore Running.

1. Lister les Pods du namespace, kubectl get pods -n kubectl-lab. Vous voyez 2 pods web-xxx en Running et 1 pod crashloop. Son statut alterne entre Error (le conteneur vient de se terminer) et CrashLoopBackOff (le kubelet attend avant la prochaine tentative), avec un compteur RESTARTS qui grimpe.

2. Inspecter le Pod en erreur, kubectl describe pod crashloop -n kubectl-lab. La section Events se termine par un événement Warning BackOff : Back-off restarting failed container crashloop. La commande kubectl logs crashloop -n kubectl-lab --previous ne renvoie rien ici, car exit 1 n'écrit aucune ligne sur la sortie standard. C'est un résultat normal, pas une erreur : sur une vraie application, ce sont ces logs du conteneur précédent qui portent la stack trace du crash.

3. Sortie en format large, kubectl get pods -n kubectl-lab -o wide. -o wide ajoute les colonnes IP et NODE.

4. Générer un manifeste YAML, kubectl create deployment redis --image=redis:7 --dry-run=client -o yaml. Le manifeste s'affiche sans rien créer dans le cluster.

5. Scaler le déploiement, kubectl scale deployment web --replicas=4 -n kubectl-lab. Vérifiez avec kubectl get pods -n kubectl-lab -l app=web.

6. Mettre à jour l'image, kubectl set image deployment/web nginx=nginx:1.26 -n kubectl-lab. Suivez le rollout : kubectl rollout status deployment/web -n kubectl-lab.

7. Port-forward vers le service, kubectl port-forward svc/web 8080:80 -n kubectl-lab. Un tunnel local est ouvert sur 127.0.0.1:8080.

8. Exécuter une commande dans un Pod, kubectl exec -it deployment/web -n kubectl-lab -- /bin/sh. Vous obtenez un shell interactif dans le conteneur nginx.

Exercices progressifs

Ces exercices vont de l'inspection de base au pipeline CI/CD complet. Lisez l'énoncé, cherchez la commande, puis dépliez la solution.

Niveau fondations

Exercice 1, Lister les Pods en erreur. Affichez tous les Pods du cluster qui ne sont pas en état Running ou Succeeded.

Indice : --field-selector sur status.phase.

Voir la solution

kubectl get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded

--field-selector filtre côté serveur ; -A cherche dans tous les namespaces.

Exercice 2, Trouver l'IP d'un Pod. Récupérez uniquement l'adresse IP du Pod nginx dans le namespace default.

Indice : -o jsonpath avec .status.podIP.

Voir la solution

kubectl get pod nginx -o jsonpath='{.status.podIP}'

jsonpath extrait un champ précis de la structure JSON de l'objet.

Exercice 3, Générer un manifeste Service. Générez un manifeste YAML pour exposer le deployment api sur le port 8080, sans le créer.

Indice : --dry-run=client -o yaml.

Voir la solution

kubectl expose deployment api --port=8080 --dry-run=client -o yaml

--dry-run=client simule, -o yaml formate. Redirigez vers un fichier avec > svc.yaml.

Exercice 4, Vérifier le contexte et changer de namespace. Affichez le contexte courant, puis changez le namespace par défaut vers staging.

Indice : config current-context puis config set-context.

Voir la solution

kubectl config current-context && kubectl config set-context --current --namespace=staging

current-context montre le cluster actif ; set-context --current modifie le namespace par défaut sans changer de cluster.

Niveau composition

Exercice 5, Diff avant apply. Comparez un fichier deploy.yaml modifié avec l'état actuel du cluster.

Indice : kubectl diff.

Voir la solution

kubectl diff -f deploy.yaml

diff compare le manifeste local avec l'état du cluster. Code de sortie 0 = pas de différence, 1 = changements.

Exercice 6, Rollback d'un déploiement. Revenez à la révision 3 du deployment web et vérifiez que le rollback est terminé.

Indice : rollout undo puis rollout status.

Voir la solution

kubectl rollout undo deployment/web --to-revision=3 && kubectl rollout status deployment/web

--to-revision=N cible une version précise. Sans cette option, on revient à la révision N-1.

Exercice 7, Vérifier les droits RBAC. Vérifiez si vous pouvez créer des Deployments dans production, puis listez tous vos droits dans ce namespace.

Indice : auth can-i et --list.

Voir la solution

kubectl auth can-i create deployments -n production && kubectl auth can-i --list -n production

auth can-i vérifie un droit précis ; --list donne la vue complète.

Exercice 8, Rollout restart et suivi. Redémarrez le Deployment api dans staging et attendez la fin du rolling restart.

Indice : rollout restart puis rollout status.

Voir la solution

kubectl rollout restart deployment/api -n staging && kubectl rollout status deployment/api -n staging --timeout=120s

rollout restart relance les Pods progressivement ; rollout status bloque jusqu'à la fin.

Exercice 9, Custom-columns pour un rapport. Affichez les Pods du namespace prod avec 3 colonnes : NOM, IP, NŒUD.

Indice : -o custom-columns avec .metadata.name, .status.podIP, .spec.nodeName.

Voir la solution

kubectl get pods -n prod -o custom-columns=NOM:.metadata.name,IP:.status.podIP,NOEUD:.spec.nodeName

custom-columns définit exactement les colonnes voulues à partir de chemins JSONPath.

Niveau industrialisation

Exercice 10, Debug d'un Pod distroless. Attachez un conteneur éphémère busybox à un Pod api qui n'a pas de shell.

Indice : kubectl debug avec --image.

Voir la solution

kubectl debug -it api --image=busybox --target=api -- /bin/sh

debug crée un conteneur éphémère dans le Pod ; --target partage le namespace PID.

Exercice 11, Drain d'un nœud pour maintenance. Préparez le nœud worker-02 pour un reboot : empêchez le scheduling et évacuez les Pods.

Indice : cordon puis drain avec les options DaemonSets et emptyDir.

Voir la solution

kubectl cordon worker-02 && kubectl drain worker-02 --ignore-daemonsets --delete-emptydir-data --timeout=120s

cordon empêche les nouveaux Pods ; drain évacue les existants ; --timeout évite de bloquer indéfiniment.

Exercice 12, Pipeline CI/CD complet. Écrivez une séquence qui compare le manifeste, l'applique, puis attend que le deployment soit prêt.

Indice : diff, apply, puis wait --for=condition.

Voir la solution

kubectl diff -f deploy.yaml && kubectl apply -f deploy.yaml && kubectl wait --for=condition=Available deployment/web --timeout=120s

diff vérifie, apply applique, wait bloque jusqu'à ce que le deployment soit disponible.

Dépannage

Quand une commande kubectl échoue, ces méthodes de diagnostic et ces erreurs fréquentes couvrent la grande majorité des cas.

Méthodes de diagnostic

Ces six commandes forment une séquence d'investigation qui va du plus général au plus précis. Lancez-les dans cet ordre : tant que vous n'avez pas confirmé le contexte et le namespace, tout le reste peut porter sur le mauvais cluster. Les Events viennent ensuite parce qu'ils datent les incidents, ce que kubectl get pods ne fait pas. kubectl top exige un metrics-server installé dans le cluster, sinon la commande renvoie Metrics API not available.

# Vérifier le contexte et le namespace actifs
kubectl config current-context

# Événements récents triés par date
kubectl get events --sort-by=.metadata.creationTimestamp -n <namespace> | tail -20

# Repérer les Pods qui ne tournent pas
kubectl get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded

# Logs du conteneur précédent (après un crash)
kubectl logs <pod> --previous -c <conteneur>

# Consommation CPU/mémoire
kubectl top pods -n <namespace> --sort-by=memory && kubectl top nodes

# Vérifier les droits RBAC
kubectl auth can-i --list -n <namespace>

Erreurs fréquentes

Le message d'erreur de kubectl indique où la requête a échoué, pas pourquoi. Repérez d'abord son émetteur : un message qui commence par Error from server vient de l'API Server (le cluster répond mais refuse ou ne trouve rien), alors qu'un connection refused signale que la requête n'est jamais partie. Les états ImagePullBackOff et CrashLoopBackOff sont d'une autre nature : l'objet a bien été créé, c'est le kubelet du nœud qui bute sur l'exécution du conteneur.

Erreur	Cause probable	Solution
The connection to the server localhost:8080 was refused	Kubeconfig absent, cluster non démarré, ou KUBECONFIG incorrect	Configurer KUBECONFIG ou démarrer le cluster, vérifier avec kubectl cluster-info
Error from server (Forbidden)	Droits RBAC manquants, mauvais namespace, ou token expiré	Vérifier avec kubectl auth can-i --list, demander les droits à l'admin
Error from server (NotFound)	Ressource inexistante ou mauvais namespace	Chercher avec -A, ou préciser le bon -n <namespace>
ErrImagePull / ImagePullBackOff	Image inexistante, registry privé sans secret, ou réseau	Corriger l'image/tag, ajouter imagePullSecrets, vérifier la connectivité
CrashLoopBackOff	Application qui crashe, liveness probe trop stricte, ou OOMKilled	kubectl logs <pod> --previous, ajuster les probes ou les limites de ressources

Glissez pour voir

Aide-mémoire kubectl

À garder sous la main : la cheat sheet complète, regroupée par usage, contexte, syntaxe, commandes, filtres, déploiement, RBAC et debug.

Contexte et cluster

Ces commandes ne touchent pas au cluster : elles lisent et modifient votre fichier ~/.kube/config en local. La distinction compte quand vous travaillez à plusieurs sur le même poste, ou quand un pipeline exporte un KUBECONFIG temporaire. config use-context change le cluster actif pour toutes vos commandes suivantes, alors que --context sur une commande unique ne modifie rien de façon durable : préférez le second en production.

Syntaxe	Signification	Exemple
config get-contexts	Lister tous les contextes	kubectl config get-contexts
config use-context CTX	Changer de cluster actif	kubectl config use-context staging
config current-context	Savoir sur quel cluster on est	kubectl config current-context
config set-context --current --namespace=NS	Namespace par défaut	kubectl config set-context --current --namespace=prod
cluster-info	URL de l'API Server et services	kubectl cluster-info
version	Version client et serveur	kubectl version

Glissez pour voir

Syntaxe et options globales

Ces options s'ajoutent à n'importe quelle commande, quel que soit le verbe. Les trois variantes de -o répondent à des besoins distincts : wide pour lire à l'écran, yaml pour repartir d'un manifeste existant, jsonpath et custom-columns pour alimenter un script. Retenez que --kubeconfig court-circuite complètement la variable KUBECONFIG : c'est l'option à utiliser dans un job CI où le fichier est déposé dans un répertoire temporaire.

Syntaxe	Signification	Exemple
kubectl [verbe] [type] [nom] [options]	Format général	kubectl get pods -n production
-n NS	Cibler un namespace	-n kube-system
-A / --all-namespaces	Tous les namespaces	kubectl get pods -A
-o yaml/json/wide/name	Format de sortie	-o wide
-o jsonpath='{...}'	Extraire un champ	-o jsonpath='{.status.podIP}'
-o custom-columns=COL:.path	Colonnes personnalisées	-o custom-columns=NAME:.metadata.name
--context CTX	Cibler un contexte sans changer	kubectl --context=prod get pods
--kubeconfig FILE	Config alternative	kubectl --kubeconfig=/tmp/admin.conf get nodes

Glissez pour voir

Commandes de lecture et d'écriture

La frontière à garder en tête sépare les commandes déclaratives des commandes impératives. apply part d'un fichier versionné et peut être rejoué à l'infini ; create, edit et patch modifient l'état vivant du cluster sans trace dans Git. Le duo api-resources et explain est le plus sous-utilisé du tableau : il donne la documentation des champs YAML directement depuis l'API Server, donc toujours à la version de votre cluster.

Syntaxe	Signification	Exemple
get TYPE [-o wide]	Lister les ressources	kubectl get deploy,svc,pods -n prod
describe TYPE NOM	Détails complets et events	kubectl describe pod my-app -n prod
api-resources	Lister les types disponibles	kubectl api-resources --verbs=list
explain TYPE.champ --recursive	Documentation intégrée	kubectl explain deploy.spec --recursive
top pod -n NS	CPU/mémoire des Pods	kubectl top pod -n prod --sort-by=memory
apply -f FICHIER	Créer/maj déclaratif (idempotent)	kubectl apply -f deploy.yaml
create TYPE NOM	Créer impératif	kubectl create ns staging
delete TYPE NOM	Supprimer une ressource	kubectl delete pod my-pod
edit TYPE NOM	Éditer dans $EDITOR	kubectl edit deploy web -n prod
patch TYPE NOM -p JSON	Modifier un champ ciblé	kubectl patch deploy web -p '{"spec":{"replicas":5}}'

Glissez pour voir

Logs et filtres

Sur un Pod qui tourne depuis des jours, kubectl logs sans filtre déverse tout l'historique conservé par le runtime. Combinez systématiquement --since et --tail pour borner la sortie. Côté sélection, -l s'applique aux labels que vous posez, --field-selector aux champs de l'objet et il filtre côté serveur, ce qui allège la réponse de l'API sur un gros cluster.

Syntaxe	Signification	Exemple
logs POD -f	Suivre en temps réel	kubectl logs deploy/web -f -n prod
logs --since=DURÉE	Filtrer par ancienneté	kubectl logs deploy/web --since=10m
logs --tail=N	N dernières lignes	kubectl logs pod/web-xxx --tail=200
logs --previous	Logs du conteneur crashé	kubectl logs pod/web-xxx --previous
-l key=value	Sélecteur de labels	-l app=nginx,env=prod
--field-selector CHAMP=VAL	Filtre sur les champs de l'objet	--field-selector=status.phase=Running
--sort-by=.CHEMIN	Trier la sortie	--sort-by=.metadata.creationTimestamp

Glissez pour voir

Déploiement

Toutes ces commandes modifient l'état du cluster sans passer par vos fichiers YAML : la dérive de configuration est le risque principal. Reportez ensuite le changement dans le manifeste versionné, sinon le prochain apply annulera votre scale ou votre set image. rollout status est la seule commande bloquante du tableau, c'est elle qui rend une mise à jour scriptable dans un pipeline.

Syntaxe	Signification	Exemple
scale --replicas=N	Changer le nombre de réplicas	kubectl scale deploy web --replicas=5
set image DEPLOY CONT=IMG	Mettre à jour une image	kubectl set image deploy/web nginx=nginx:1.26
rollout restart	Redémarrer sans changer le YAML	kubectl rollout restart deploy/web
rollout status [--timeout]	Suivre un déploiement	kubectl rollout status deploy/web --timeout=120s
rollout undo [--to-revision=N]	Rollback	kubectl rollout undo deploy/web --to-revision=3
rollout history	Historique des révisions	kubectl rollout history deploy/web
autoscale --min --max --cpu	Créer un HPA	kubectl autoscale deploy web --min=2 --max=10 --cpu-percent=80

Glissez pour voir

CI/CD, RBAC et accès

Ce dernier bloc regroupe ce qui sert dans un pipeline et ce qui sert en astreinte. Côté automatisation, --dry-run=client, diff et wait renvoient des codes de sortie exploitables dans un script : diff sort en 1 quand il détecte une différence, wait en 1 au dépassement du --timeout. Côté investigation, auth can-i --list répond en une commande à la question « pourquoi ce ServiceAccount reçoit-il un Forbidden », et debug reste le seul moyen d'inspecter une image distroless dépourvue de shell.

Syntaxe	Signification	Exemple
--dry-run=client -o yaml	Générer du YAML sans créer	kubectl create deploy x --image=y --dry-run=client -o yaml
diff -f FICHIER	Comparer avec le cluster	kubectl diff -f manifest.yaml
apply --server-side --force-conflicts	Apply server-side (production)	kubectl apply -f k8s/ --server-side --force-conflicts
wait --for=condition=COND	Attendre un état (CI/CD)	kubectl wait --for=condition=Ready pod/x --timeout=60s
auth can-i VERBE TYPE -n NS	Vérifier un droit	kubectl auth can-i create pods -n production
auth can-i --list -n NS	Tous mes droits dans un namespace	kubectl auth can-i --list -n production
exec -it POD -- CMD	Shell dans un conteneur	kubectl exec -it pod/web -- /bin/sh
debug -it POD --image=IMG	Conteneur éphémère (distroless)	kubectl debug -it pod/api --image=busybox --target=api
port-forward TYPE/NOM LOCAL:DIST	Tunnel local	kubectl port-forward svc/web 8080:80 -n prod
cordon / drain NOEUD	Maintenance d'un nœud	kubectl drain worker-01 --ignore-daemonsets --delete-emptydir-data

Glissez pour voir

Checklist de maîtrise

Vous maîtrisez kubectl quand vous pouvez cocher chacun de ces points sans hésiter :

• Je sais naviguer entre contextes et namespaces.
• Je sais inspecter avec get, describe et logs.
• Je sais extraire des données avec jsonpath et custom-columns.
• Je sais générer des manifestes avec --dry-run=client.
• Je sais utiliser diff avant apply.
• Je sais gérer les rollouts (status, undo, restart, history).
• Je sais déboguer avec exec et debug.
• Je sais préparer un nœud pour maintenance.
• Je sais automatiser avec wait et diff dans un pipeline.
• Je sais diagnostiquer les erreurs courantes (ImagePull, CrashLoop, Forbidden).
• Je sais vérifier les droits RBAC avec auth can-i.
• Je sais utiliser les Events et top pour le debug day-2.

D'autres ressources pour aller plus loin

Hub kubectl Tous les guides kubectl : installation, déploiement, debug, maintenance, plugins

Kubectl : guide d'installation et configuration Comment installer kubectl, choisir la bonne version, configurer le kubeconfig et tester la connexion à votre cluster.

×

📖 Voir la documentation →