Hub des guides pour maîtriser kubectl de A à Z

kubectl est la CLI officielle de Kubernetes. Chaque commande devient une requête REST vers l’API Server : c’est votre point d’entrée pour inspecter, déployer, déboguer et maintenir les ressources du cluster. Objectif de cette page : vous faire gagner du temps en vous envoyant immédiatement vers le bon guide, puis vous proposer un parcours et une référence rapide.

Pour les plus pressés !

Toutes les commandes kubectl suivent le même schéma :

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

Verbe : get, apply, delete, describe, logs
Type : pod, deployment, service, node, configmap
Nom : optionnel (sans nom = toutes les ressources)
Options : -n, -o, -l, --watch, --dry-run, etc.

Les 10 commandes pour être opérationnel :

# 1) Vérifier où vous êtes
kubectl config current-context

# 2) Voir rapidement l'état
kubectl get pods -A
kubectl get nodes -o wide

# 3) Comprendre un problème (ordre logique)
kubectl describe pod <pod> -n <ns>
kubectl get events -n <ns> --sort-by=.metadata.creationTimestamp
kubectl logs -n <ns> pod/<pod> --since=10m --tail=200

# 4) Déployer sans risque
kubectl diff -f k8s/
kubectl apply -f k8s/

# 5) Suivre un rollout / redémarrer
kubectl rollout status deploy/<name> -n <ns>
kubectl rollout restart deploy/<name> -n <ns>

Pour les commandes avancées, les patterns et les pièges : rendez-vous sur le cheat sheet kubectl.

Choisir ton objectif

Installer et configurer kubectl Installation multi-OS, autocomplétion, alias, kubeconfig

Gérer les contextes et kubeconfig Naviguer entre clusters et namespaces, multi-kubeconfig

Diagnostiquer rapidement get, describe, logs, top : le runbook d'incident

Parcours recommandé

Parcours A — De zéro à autonome (débutant)

Installez kubectl et configurez l’autocomplétion.
Comprenez les contextes et apprenez à naviguer entre clusters.
Maîtrisez le trio get / describe / logs pour diagnostiquer.
Passez au déploiement déclaratif avec apply + diff.

Installation & config Avoir un environnement fonctionnel

Contextes & kubeconfig Naviguer entre clusters

Diagnostic rapide Comprendre l'état du cluster

Déployer (create/apply) Passer au déclaratif

Parcours B — “Je veux de la prod propre” (intermédiaire)

Ajoutez les modifications ciblées (edit/patch/replace).
Maîtrisez le scaling, les rollouts et les rollbacks.
Passez en mode debug avec exec et conteneurs éphémères.
Intégrez kubectl dans vos pipelines CI/CD (diff/wait).

Modifier en prod Changements ciblés et sûrs

Scale & rollout Mises à jour progressives

Debug avancé Diagnostiquer les cas difficiles

CI/CD (diff/wait) Déploiements fiables en pipeline

Référence rapide

Vous voulez une réponse immédiate ? Cette section est faite pour ça.

Syntaxe kubectl — le modèle mental

Verbe : l’action (get, apply, delete, describe, logs…)
Type : la ressource ciblée (pod, deploy, svc, node…)
Nom : optionnel (sans nom = toutes les ressources du type)
Options : -n (namespace), -o (output), -l (label selector), --watch

Exemple : kubectl get pods -n production -l app=web -o wide

→ Cheat sheet complet

Diagnostic — “je fais quoi quand ça marche pas”

Si un Pod ne démarre pas : describe pod → Events → logs --previous
Si un Pod redémarre : get pod (RESTARTS) → logs --previous → describe (OOMKilled ?)
Si un Service ne répond pas : get endpoints → describe svc → labels selector
Si un déploiement bloque : rollout status → get events → pods du ReplicaSet

→ Guide diagnostic

Déploiement — le workflow sûr

“Je prévisualise” : kubectl diff -f manifests/
“Je déploie” : kubectl apply -f manifests/
“Je vérifie” : kubectl rollout status deploy/<name>
“Je rollback” : kubectl rollout undo deploy/<name>
“Je génère” : kubectl create deploy --dry-run=client -o yaml

→ Guide déploiement

Contextes — naviguer entre clusters

Voir les contextes : kubectl config get-contexts
Changer : kubectl config use-context <nom>
Namespace par défaut : kubectl config set-context --current --namespace=<ns>
Multi-kubeconfig : export KUBECONFIG=~/.kube/config:~/.kube/staging

→ Guide contextes

Maintenance nœuds — le workflow sans downtime

Bloquer : kubectl cordon <node>
Évacuer : kubectl drain <node> --ignore-daemonsets --delete-emptydir-data
Maintenir : (mise à jour OS, kubelet, etc.)
Remettre : kubectl uncordon <node>

→ Guide maintenance

Debug avancé — conteneurs éphémères

Shell classique : kubectl exec -it pod/<name> -n <ns> -- sh
Distroless/scratch : kubectl debug -it pod/<name> --image=busybox --target=container
Copie de Pod : kubectl debug pod/<name> -it --copy-to=debug-pod --container=debug

→ Guide debug

Les 12 guides kubectl du hub

Guide	Objectif	Niveau
Installation & config	Installer, autocomplete, alias	Débutant
Contextes & kubeconfig	Naviguer entre clusters	Débutant
Diagnostic (get/describe/logs/top)	Comprendre l’état du cluster	Débutant → Intermédiaire
Explorer l’API (api-resources/explain)	Découvrir types et CRDs	Intermédiaire
Déployer (create/apply)	Workflow déclaratif	Intermédiaire
Modifier (edit/patch/replace)	Changements ciblés en prod	Intermédiaire
Labels & annotations	Organiser et filtrer	Intermédiaire
Exposer (expose/port-forward/proxy)	Services et tunnels	Intermédiaire
Scale & rollout	Mise à l’échelle, rollbacks	Intermédiaire → Avancé
Debug (exec/debug)	Conteneurs éphémères, distroless	Avancé
Maintenance nœuds	Drain, cordon, taints	Avancé
CI/CD (diff/wait)	Pipelines fiables	Avancé

Ressources Kubernetes à connaître

Avant d’apprendre 50 commandes, maîtrisez 10 objets. Ce sont eux que vous administrez au quotidien.

Ressources de base (10 objets du quotidien)

Ressource	À comprendre	Commandes kubectl	Pour aller plus loin
Namespace	Isoler environnements/équipes	`get ns`, `-n`, `-A`	Les Namespaces
Pod	Unité d’exécution (1..n conteneurs)	`get po`, `describe po`, `logs`, `exec`	Les Pods
Deployment	Déploiement + rollout/rollback	`get deploy`, `apply`, `rollout`, `scale`	Les Deployments
ReplicaSet	Garantir N réplicas d’un Pod	`get rs`, `describe rs`	Les ReplicaSets
Service	Exposition interne / stable IP	`get svc`, `describe svc`, `expose`	Les Services
Ingress	Exposition HTTP(S) via contrôleur	`get ing`, `describe ing`	Les Ingress
ConfigMap	Configuration non sensible	`get cm`, `describe cm`, `apply`	Les ConfigMaps
Secret	Configuration sensible (RBAC !)	`get secret`, `describe`, `apply`	Les Secrets
Job/CronJob	Exécution batch/planifiée	`get job`, `get cj`, `logs`	Jobs et CronJobs
Node	Capacité et scheduling	`get node`, `describe node`, `cordon`, `drain`	Worker Nodes

Ressources avancées (scaling, sécurité, stockage)

Ressource	Quand l’utiliser	Pour aller plus loin
DaemonSet	Un Pod par nœud (monitoring, logs, réseau)	Les DaemonSets
StatefulSet	Apps avec état (BDD, Kafka, ZooKeeper)	Les StatefulSets
HPA	Auto-scaling horizontal sur CPU/mémoire	HPA
PVC/StorageClass	Stockage persistant	Stockage
NetworkPolicy	Contrôler le trafic réseau entre Pods	NetworkPolicies
RBAC	Contrôle d’accès (Role, ClusterRole, Binding)	RBAC
Probes	Liveness, Readiness, Startup	Les Probes

Écosystème : les outils compagnons

Outils de productivité et sécurité autour de kubectl

Outil	Rôle	Lien
Kustomize	Factoriser vos manifestes sans templates	Guide Kustomize
Helm	Gestionnaire de packages Kubernetes	Helm de A à Z
k9s	Interface TUI pour naviguer dans un cluster	Guide k9s
Stern	Logs multi-pods en temps réel avec couleurs	Guide Stern
kubectx/kubens	Changer de contexte/namespace en un mot	Guide kubectx/kubens
Kubie	Alternative à kubectx avec isolation par shell	Guide Kubie
KDash	Dashboard TUI léger pour clusters	Guide KDash
Pluto	Détecter les API Kubernetes dépréciées	Guide Pluto
Sealed Secrets	Chiffrer les Secrets pour GitOps	Guide Sealed Secrets
Kubescape	Audit de sécurité du cluster	Guide Kubescape
Polaris	Bonnes pratiques et validation de manifestes	Guide Polaris
Kube-Score	Analyse statique de manifestes	Guide Kube-Score
Popeye	Scan hygiène de cluster	Guide Popeye
Rancher	Plateforme de gestion multi-clusters	Guide Rancher
Karpenter	Auto-provisioning de nœuds (FinOps)	Guide Karpenter
Cast AI	Optimisation coûts et scaling automatique	Guide Cast AI
Goldilocks	Recommandations de requests/limits	Guide Goldilocks
Ansible k8s	Automatiser Kubernetes via Ansible	Guide Ansible k8s

FAQ — Questions fréquentes

Qu'est-ce que kubectl et à quoi sert-il ?

kubectl est la CLI officielle de Kubernetes. Chaque commande envoie une requête REST à l'API Server du cluster pour créer, lire, modifier ou supprimer des ressources (pods, deployments, services, etc.). C'est l'outil indispensable pour administrer un cluster Kubernetes.

Définition

kubectl est l'interface en ligne de commande officielle de Kubernetes. Chaque commande que vous tapez est traduite en une requête REST vers l'API Server du cluster.

Ce que kubectl permet de faire

Inspecter l'état du cluster (pods, nodes, events)
Déployer des applications (apply, create)
Déboguer les problèmes (describe, logs, exec, debug)
Maintenir le cluster (drain, cordon, taint)
Automatiser via des scripts et pipelines CI/CD

Syntaxe de base

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

Verbe : l'action (get, apply, delete, describe)
Type : la ressource ciblée (pod, deploy, svc, node)
Nom : optionnel (sans nom = toutes les ressources)
Options : -n (namespace), -o (format de sortie), -l (label selector)

Comment installer kubectl ?

kubectl s'installe via le gestionnaire de paquets de votre OS (apt, brew, choco), via curl depuis les releases officielles Kubernetes, ou automatiquement avec des outils comme mise, asdf ou Docker Desktop. Vérifiez l'installation avec kubectl version --client.

Installation selon l'OS

OS	Méthode recommandée
Linux (Debian/Ubuntu)	`sudo apt install kubectl` ou curl binaire
Linux (RHEL/Fedora)	`sudo dnf install kubectl`
macOS	`brew install kubectl`
Windows	`choco install kubernetes-cli` ou `winget install kubectl`

Installation via curl (toutes plateformes)

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/

Vérification

kubectl version --client

Autocomplétion (fortement recommandé)

# Bash
echo 'source <(kubectl completion bash)' >> ~/.bashrc

# Zsh
echo 'source <(kubectl completion zsh)' >> ~/.zshrc

Comment fonctionne le kubeconfig et comment changer de cluster ?

Le fichier kubeconfig (~/.kube/config) contient les contextes (cluster + utilisateur + namespace). Changez de cluster avec kubectl config use-context, listez les contextes avec get-contexts, et définissez un namespace par défaut avec set-context --current --namespace.

Le fichier kubeconfig

Par défaut, kubectl lit ~/.kube/config. Ce fichier contient :

clusters : adresses des API servers
users : identités et méthodes d'authentification
contexts : combinaison cluster + user + namespace par défaut

Commandes essentielles

# Voir le contexte actif
kubectl config current-context

# Lister tous les contextes
kubectl config get-contexts

# Changer de contexte
kubectl config use-context mon-cluster-staging

# Définir un namespace par défaut
kubectl config set-context --current --namespace=production

Multi-kubeconfig

export KUBECONFIG=~/.kube/config:~/.kube/staging:~/.kube/prod

Outils compagnons

kubectx : changer de contexte en un mot (kubectx staging)
kubens : changer de namespace (kubens production)
kubie : isolation par shell (pas de risque de "mauvais contexte")

Quelles sont les commandes kubectl les plus utilisées ?

Les commandes kubectl les plus utilisées sont get (lister les ressources), describe (détails et events), logs (journaux), apply (déployer), delete (supprimer), exec (entrer dans un conteneur), rollout (gérer les mises à jour) et diff (prévisualiser les changements).

Les 10 commandes du quotidien

Commande	Rôle
`kubectl get`	Lister les ressources (pods, deploy, svc…)
`kubectl describe`	Détails + Events d'une ressource
`kubectl logs`	Journaux d'un conteneur
`kubectl apply -f`	Déployer de manière déclarative
`kubectl delete`	Supprimer une ressource
`kubectl exec -it`	Ouvrir un shell dans un conteneur
`kubectl rollout`	Status, restart, undo d'un deployment
`kubectl diff -f`	Prévisualiser les changements avant apply
`kubectl top`	Consommation CPU/mémoire (pods, nodes)
`kubectl config`	Gérer contextes et kubeconfig

Exemple de workflow diagnostic

# 1) Vue d'ensemble
kubectl get deploy,rs,po,svc -n production

# 2) Détails d'un pod en erreur
kubectl describe pod <pod> -n production

# 3) Logs récents
kubectl logs -n production pod/<pod> --since=10m --tail=200

Quelle est la différence entre kubectl apply et kubectl create ?

kubectl create est impératif (crée une ressource, échoue si elle existe déjà). kubectl apply est déclaratif (crée ou met à jour selon l'état souhaité, avec 3-way merge). En production, apply est la norme car il permet les mises à jour incrémentales et le suivi GitOps.

Comparaison

Aspect	`kubectl create`	`kubectl apply`
Mode	Impératif	Déclaratif
Si la ressource existe	Erreur	Mise à jour (3-way merge)
Historique	Non	Oui (annotation `last-applied-configuration`)
Usage recommandé	Prototypage, scripts one-shot	Production, GitOps, CI/CD

Workflow recommandé

# 1) Générer un manifeste
kubectl create deploy web --image=nginx --dry-run=client -o yaml > deploy.yaml

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

# 3) Appliquer
kubectl apply -f deploy.yaml

Règle simple

Prototypage : create (rapide, one-shot)
Production : apply (idempotent, traçable, compatible GitOps)

Comment diagnostiquer un pod qui ne démarre pas ?

Pour diagnostiquer un pod en erreur, suivez cet ordre : kubectl get pod (voir le STATUS), kubectl describe pod (lire les Events), kubectl logs --previous (voir les logs du crash). Les causes fréquentes sont ImagePullBackOff, CrashLoopBackOff, OOMKilled et Pending (manque de ressources).

Workflow de diagnostic (ordre fixe)

# 1) Identifier le problème
kubectl get pod <pod> -n <ns>

# 2) Lire les Events
kubectl describe pod <pod> -n <ns>

# 3) Voir les logs (y compris du crash précédent)
kubectl logs <pod> -n <ns> --previous --tail=100

# 4) Events du namespace triés
kubectl get events -n <ns> --sort-by=.metadata.creationTimestamp

Causes fréquentes

Status	Cause probable	Action
ImagePullBackOff	Image introuvable ou auth registry	Vérifier image, imagePullSecrets
CrashLoopBackOff	L'app crash au démarrage	`logs --previous`, variables d'env
OOMKilled	Dépassement de la limite mémoire	Augmenter `limits.memory`
Pending	Pas de nœud disponible	`describe pod` → Events (taints, resources)
CreateContainerError	ConfigMap/Secret manquant	Vérifier que les refs existent

Debug avancé (distroless)

kubectl debug -it pod/<pod> -n <ns> --image=busybox --target=<container>

Quelle est la différence entre kubectl edit, patch et replace ?

kubectl edit ouvre la ressource dans un éditeur pour modification interactive. kubectl patch applique un changement ciblé en JSON/YAML (idéal pour scripts). kubectl replace remplace entièrement la ressource (destructif). En production, patch est le plus sûr pour les modifications ciblées.

Comparaison

Commande	Usage	Risque	Scriptable
`kubectl edit`	Modification interactive	Moyen	Non
`kubectl patch`	Changement ciblé (1-2 champs)	Faible	Oui
`kubectl replace`	Remplacement complet	Élevé	Oui

Exemples

# edit — ouvre dans $EDITOR
kubectl edit deploy/web -n production

# patch — changer l'image sans toucher au reste
kubectl patch deploy/web -n production \
  -p '{"spec":{"template":{"spec":{"containers":[{"name":"web","image":"nginx:1.27"}]}}}}'

# replace — remplacement total (attention !)
kubectl replace -f deploy.yaml

Quelle commande choisir ?

Urgence en prod : edit (rapide, visuel)
Script / CI : patch (ciblé, idempotent)
Remplacement complet : replace (destructif, dernière option)

Comment faire une maintenance de nœud sans downtime ?

Le workflow de maintenance sans downtime est : cordon (bloquer le scheduling), drain (évacuer les pods), maintenance (mise à jour OS/kubelet), uncordon (remettre en service). Utilisez --ignore-daemonsets et --delete-emptydir-data avec drain. Vérifiez les PodDisruptionBudgets avant de commencer.

Workflow complet

# 1) Bloquer — plus de nouveaux pods sur ce nœud
kubectl cordon <node>

# 2) Évacuer — déplacer les pods existants
kubectl drain <node> --ignore-daemonsets --delete-emptydir-data

# 3) Maintenir — mise à jour OS, kubelet, etc.

# 4) Remettre en service
kubectl uncordon <node>

# 5) Vérifier
kubectl get nodes
kubectl get pods -A -o wide | grep <node>

Points d'attention

PodDisruptionBudget (PDB) : drain respecte les PDB. Si minAvailable bloque, drain attend
--delete-emptydir-data : supprime les données emptyDir (destructif mais nécessaire)
--ignore-daemonsets : les DaemonSets restent (normal, ils tournent partout)
Vérifiez avant : kubectl get pdb -A pour anticiper les blocages

Comment utiliser kubectl dans un pipeline CI/CD ?

Dans un pipeline CI/CD, utilisez kubectl diff pour prévisualiser, apply --dry-run=server pour valider, apply pour déployer, et wait pour attendre qu'une condition soit remplie (rollout terminé, pod ready). Ajoutez toujours un timeout et un rollback automatique en cas d'échec.

Workflow CI/CD recommandé

# 1) Valider la syntaxe
kubectl apply -f manifests/ --dry-run=server

# 2) Prévisualiser les changements
kubectl diff -f manifests/

# 3) Appliquer
kubectl apply -f manifests/

# 4) Attendre le rollout
kubectl rollout status deploy/<name> -n <ns> --timeout=300s

# 5) Vérifier les pods
kubectl wait --for=condition=Ready pod -l app=<name> -n <ns> --timeout=120s

Rollback automatique

# En cas d'échec du rollout
if ! kubectl rollout status deploy/<name> --timeout=300s; then
  kubectl rollout undo deploy/<name>
  exit 1
fi

Bonnes pratiques

Toujours utiliser --dry-run=server (pas client) pour valider côté API
Fixer un --timeout sur rollout status et wait
Ne jamais utiliser kubectl edit dans un pipeline
Préférer apply à create pour l'idempotence

Quelle différence entre les options -o wide, -o yaml et -o json de kubectl ?

L'option -o wide ajoute des colonnes supplémentaires (IP, node) à la sortie tabulaire. -o yaml et -o json affichent la ressource complète dans le format correspondant, utile pour le debug ou le scripting. -o jsonpath permet d'extraire des champs spécifiques avec des expressions.

Formats de sortie

Option	Usage	Exemple
(défaut)	Tableau résumé	`kubectl get pods`
`-o wide`	Tableau + colonnes supplémentaires (IP, node)	`kubectl get pods -o wide`
`-o yaml`	Ressource complète en YAML	`kubectl get deploy/web -o yaml`
`-o json`	Ressource complète en JSON	`kubectl get pod/web -o json`
`-o jsonpath`	Extraction ciblée de champs	Voir exemples ci-dessous
`-o name`	Juste le type/nom	`kubectl get pods -o name`

Exemples jsonpath

# IP d'un pod
kubectl get pod web -o jsonpath='{.status.podIP}'

# Image de chaque pod
kubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[0].image}{"\n"}{end}'

# Noms de tous les nodes
kubectl get nodes -o jsonpath='{.items[*].metadata.name}'

Conseil pratique

Debug rapide : -o wide (garder le format tableau lisible)
Scripting : -o jsonpath (extraire exactement ce qu'il faut)
Comprendre la ressource : -o yaml (voir tous les champs)