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 votre objectif

Les quatre onglets ci-dessous ne sont pas une progression : ce sont quatre intentions distinctes, et vous n'avez aucune raison de les parcourir dans l'ordre. Choisissez celui qui décrit ce que vous devez faire aujourd'hui. Si vous hésitez, le premier onglet est le seul qui suppose un cluster jamais touché ; les trois autres partent du principe que kubectl répond déjà et qu'un contexte est configuré.

Je débute

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

Déployer & modifier

Déployer proprement (create/apply) Impératif vs déclaratif, --dry-run, 3-way merge

Modifier en production (edit/patch/replace) Choisir la bonne commande selon le type de changement

Gérer les metadata (label/annotate) Labels, annotations, sélecteurs : organiser et filtrer

Scaler & exposer

Scaler / rollout / rollback Mise à l'échelle, mises à jour progressives, rollbacks

Exposer / accéder (port-forward/proxy) Services, tunnels de dev, accès API Kubernetes

Explorer l'API (api-resources/explain) Découvrir les types, CRDs, doc intégrée champ par champ

Debug & maintenance

Debug avancé (exec/debug) Shell, conteneurs éphémères, distroless, copie de fichiers

Maintenance nœuds (cordon/drain/taint) Workflow de maintenance sans downtime

CI/CD et validation (diff/wait) Prévisualiser les changements, attendre des conditions

Comment utiliser cette page

Lisez d'abord la section Parcours recommandé, puis gardez Référence rapide en bookmark : c'est fait pour revenir vite sur une commande, un piège, ou un choix.

Parcours recommandé

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

L'ordre de ces quatre étapes est délibéré et se lit comme une réduction du risque. Vous commencez par des commandes qui ne modifient rien (installation, lecture de contexte, diagnostic) et vous ne touchez à l'état du cluster qu'à la dernière. La deuxième étape est celle que les débutants sautent le plus souvent, et c'est aussi celle qui cause le plus de dégâts quand elle manque : appliquer un manifeste dans le mauvais contexte est l'erreur la plus banale et la plus coûteuse de Kubernetes.

1. Installez kubectl et configurez l'autocomplétion.

2. Comprenez les contextes et apprenez à naviguer entre clusters.

3. Maîtrisez le trio get / describe / logs pour diagnostiquer.

4. 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)

Ce parcours suppose le A acquis et déplace la question : il ne s'agit plus de savoir taper la commande, mais de savoir laquelle et quand. La quatrième étape est le vrai point d'arrivée : tant que kubectl reste une commande tapée à la main sur un poste, la reproductibilité repose sur la mémoire de l'opérateur. diff et wait sont ce qui transforme les trois premières étapes en déploiement automatisable.

1. Ajoutez les modifications ciblées (edit/patch/replace).

2. Maîtrisez le scaling, les rollouts et les rollbacks.

3. Passez en mode debug avec exec et conteneurs éphémères.

4. 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 web --image=nginx:1.29-alpine --dry-run=client -o yaml (le nom et --image sont obligatoires, sinon required flag(s) "image" not set)

→ 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 --image=busybox (--container ne sert qu'à désigner un conteneur déjà présent dont on change la commande)

→ Guide debug

Les 12 guides kubectl du hub

Ce tableau reprend les mêmes douze guides que les onglets plus haut, mais trié par niveau au lieu de l'être par intention. Servez-vous-en pour évaluer un écart : si vous êtes à l'aise sur les quatre premières lignes et perdu dès la cinquième, vous savez exactement où reprendre. La colonne Niveau évalue la difficulté du guide, pas la fréquence d'usage de la commande : drain est classé avancé alors que vous le taperez peut-être dès votre première maintenance.

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é

Glissez pour voir

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

Glissez pour voir

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

Glissez pour voir

Écosystème : les outils compagnons

Aucun de ces outils ne remplace kubectl : ils s'appuient tous sur le même kubeconfig et la même API Server. Ils se répartissent en trois familles qu'il vaut mieux ne pas confondre. Les outils de navigation (k9s, kubectx, Stern, KDash) vous font gagner des frappes sans rien changer au cluster. Les outils de packaging (Helm, Kustomize) changent la façon dont vous produisez vos manifestes. Les outils d'audit (Kubescape, Polaris, Popeye, Pluto) lisent votre cluster pour vous dire ce qui ne va pas. Commencez par la première famille, elle est sans risque et rentabilise immédiatement.

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

Glissez pour voir

FAQ, Questions fréquentes

Dix réponses courtes aux questions qui reviennent le plus, dont trois qui portent sur des distinctions que la documentation officielle laisse implicites : apply contre create, edit contre patch contre replace, et les formats de sortie -o wide, -o yaml et -o json. Ce sont exactement les points où une mauvaise habitude prise au début coûte cher plus tard, chaque réponse renvoie vers le guide complet correspondant.

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.

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.

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.

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).

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.

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).

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.

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.

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.

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.

×

📖 Voir la documentation →