Installer et configurer kubectl pas à pas

Ce guide vous permet d’installer kubectl — l’outil en ligne de commande de Kubernetes — et de vérifier qu’il fonctionne. En 15 minutes, vous saurez installer kubectl, choisir la bonne version, activer l’autocomplétion et tester la connexion à votre cluster. Prérequis : un terminal et un accès internet.

Quickstart : installer kubectl en 2 minutes

Si vous connaissez déjà kubectl et voulez juste l’installer rapidement, copiez le bloc correspondant à votre OS :

Linux

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/
kubectl version --client

macOS

brew install kubectl
kubectl version --client

Windows

choco install kubernetes-cli
kubectl version --client

Puis testez la connexion à votre cluster (si un kubeconfig est déjà en place) :

kubectl cluster-info
kubectl get nodes

Le reste de ce guide détaille chaque étape et les options avancées.

Qu’est-ce que kubectl ?

kubectl (prononcé « koube-control ») est l’outil en ligne de commande officiel de Kubernetes. C’est votre télécommande pour piloter un cluster Kubernetes : déployer des applications, inspecter des ressources, lire des logs, diagnostiquer des problèmes.

Sans kubectl, impossible d’interagir directement avec un cluster depuis votre terminal. Chaque commande kubectl envoie une requête à l’API server du cluster, qui exécute l’action demandée.

Sans kubectl	Avec kubectl
Impossible d’administrer le cluster en CLI	Contrôle total depuis le terminal
Dépendance à une interface web	Automatisation possible via scripts
Pas de visibilité sur les ressources	Inspection détaillée de chaque objet

Glissez pour voir

Prérequis

Avant de commencer, vérifiez que vous disposez de :

• Un terminal fonctionnel (Bash, Zsh, PowerShell ou Fish)
• Un accès internet pour télécharger kubectl
• Les droits administrateur sur votre machine (pour déplacer le binaire dans le PATH)
• Un cluster Kubernetes accessible (optionnel pour l’installation, nécessaire pour la configuration)

Pas encore de cluster ?

Vous pouvez installer kubectl sans cluster. Pour créer un cluster local de test, consultez les guides kind, minikube ou k3d.

Quelle version installer ?

Kubernetes maintient en parallèle les trois dernières versions mineures (actuellement 1.35, 1.34 et 1.33). Pour connaître la version stable la plus récente à tout instant :

curl -L -s https://dl.k8s.io/release/stable.txt
# Résultat au moment de la rédaction : v1.35.2

Version skew policy — règle critique

Selon la politique officielle de compatibilité, kubectl doit être à ±1 version mineure par rapport à l’API server de votre cluster.

Par exemple, si votre API server tourne en 1.34, kubectl est supporté en 1.35, 1.34 ou 1.33. Au-delà, certaines commandes échoueront silencieusement ou produiront des résultats incohérents.

Choisir la bonne version pour votre cluster

Si vous ne connaissez pas la version de votre cluster, vérifiez-la après l’installation :

kubectl version

Résultat attendu :

Client Version: v1.35.2
Server Version: v1.34.4

Ici l’écart est de 1 version mineure (1.35 vs 1.34) — c’est compatible. Si l’écart est supérieur à 1, installez une version compatible avec asdf ou mise :

# Voir la version serveur
kubectl version --output=yaml | grep -A2 serverVersion

# Installer une version compatible (ex: v1.34.x)
mise use -g kubectl@1.34
# ou
asdf install kubectl 1.34.4 && asdf set --home kubectl 1.34.4

Version API server	Versions kubectl supportées
1.35	1.36, 1.35, 1.34
1.34	1.35, 1.34, 1.33
1.33	1.34, 1.33, 1.32

Glissez pour voir

Ce tableau s’applique quelle que soit la version concrète : la règle est toujours « ±1 version mineure par rapport à l’API server ».

Installer kubectl

Choisissez la méthode d’installation correspondant à votre système d’exploitation. Chaque onglet détaille les étapes, la vérification et le dépannage.

Linux

1. Téléchargez le binaire kubectl

   La commande suivante récupère automatiquement la dernière version stable :

   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

   Cette commande interroge l’API Kubernetes pour détecter la version stable la plus récente, puis télécharge le binaire correspondant pour l’architecture amd64.

   Pour une architecture ARM64 (Raspberry Pi, Graviton) :

   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/arm64/kubectl"

2. Validez le binaire (optionnel mais recommandé)

   En production ou sur des machines sensibles, vérifiez l’intégrité du binaire téléchargé :

   # Télécharger le checksum
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl.sha256"
   
   # Vérifier
   echo "$(cat kubectl.sha256)  kubectl" | sha256sum --check

   Résultat attendu : kubectl: OK.

3. Rendez le fichier exécutable et déplacez-le

   chmod +x kubectl
   sudo mv kubectl /usr/local/bin/

4. Vérifiez l’installation

   kubectl version --client

   Résultat attendu : Client Version: v1.35.x (la version stable courante).

   Si ça ne marche pas : vérifiez que /usr/local/bin est bien dans votre variable $PATH avec echo $PATH.

macOS (Homebrew)

1. Installez kubectl avec Homebrew

   Homebrew est le gestionnaire de paquets standard sur macOS. Il gère automatiquement l’architecture (Intel x86_64 ou Apple Silicon ARM64) :

   brew install kubectl

   Homebrew installe aussi Kustomize, un outil de personnalisation des ressources Kubernetes. Tout est expliqué dans le guide Kustomize.

2. Vérifiez l’installation

   kubectl version --client

   Résultat attendu :

   Client Version: v1.35.x
   Kustomize Version: v5.x.x

   Si ça ne marche pas : exécutez brew doctor pour diagnostiquer d’éventuels problèmes Homebrew.

Binaire officiel sans Homebrew

Si vous préférez le binaire officiel (environnement air-gapped, contrôle de version strict), la procédure est similaire à Linux. Adaptez l’URL selon votre architecture :

# Apple Silicon (M1/M2/M3/M4)
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl"

# Intel
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"

chmod +x kubectl && sudo mv kubectl /usr/local/bin/

Windows

1. Installez kubectl avec Chocolatey ou winget

   Ouvrez un terminal PowerShell en administrateur :

   # Option 1 : Chocolatey
   choco install kubernetes-cli
   
   # Option 2 : winget (Windows Package Manager)
   winget install Kubernetes.kubectl

   winget est préinstallé sur Windows 10/11 récents et souvent privilégié en entreprise. Chocolatey reste une alternative fiable.

2. Vérifiez l’installation

   kubectl version --client

   Résultat attendu : une ligne affichant la version client.

   Si ça ne marche pas : fermez et rouvrez votre terminal PowerShell pour que le PATH soit rechargé. Vous pouvez vérifier avec where.exe kubectl.

asdf / mise

asdf et mise permettent de gérer plusieurs versions d’outils en parallèle. C’est la meilleure option si vous travaillez sur des clusters utilisant des versions différentes de Kubernetes.

1. Ajoutez le plugin et installez kubectl

   # Avec mise (recommandé)
   mise use -g kubectl@latest
   
   # Avec asdf
   asdf plugin add kubectl
   asdf install kubectl latest
   asdf set --home kubectl latest

2. Installer une version spécifique (skew policy)

   Si votre cluster tourne en v1.34 :

   # Avec mise
   mise use kubectl@1.34
   
   # Avec asdf
   asdf install kubectl 1.34.4
   asdf set kubectl 1.34.4

3. Vérifiez l’installation

   kubectl version --client

Pourquoi asdf ou mise ?

Ces outils permettent d’installer une version précise de kubectl par projet. Si un cluster tourne en v1.33 et un autre en v1.35, vous basculez entre les versions automatiquement selon le répertoire de travail.

Comprendre la syntaxe de kubectl

Avant de configurer kubectl, il est utile de comprendre sa syntaxe. Chaque commande suit le même schéma :

kubectl [commande] [TYPE] [NOM] [flags]

Élément	Rôle	Exemples
commande	L’opération à effectuer	get, create, delete, describe
TYPE	Le type de ressource Kubernetes	pod, service, deployment
NOM	Le nom de la ressource (sensible à la casse)	mon-app, nginx
flags	Options supplémentaires	-n default, -o yaml

Glissez pour voir

Par exemple, pour lister tous les pods du namespace production :

kubectl get pods -n production

Options globales utiles

Ces options fonctionnent avec toutes les commandes kubectl :

Option	Description
-n <namespace>	Exécuter la commande dans un namespace spécifique
--context=<nom>	Utiliser un contexte particulier sans modifier la config globale
--kubeconfig=<fichier>	Pointer vers un fichier kubeconfig personnalisé
-o <format>	Format de sortie : json, yaml, wide, name
--v=<niveau>	Mode verbeux pour le debug (--v=6 pour les requêtes HTTP)

Glissez pour voir

Rappel express

Tapez kubectl options dans votre terminal pour afficher la liste complète des options globales à tout moment.

Activer l’autocomplétion

L’autocomplétion vous fait gagner un temps considérable : tapez le début d’une commande ou d’un nom de ressource, puis appuyez sur Tab pour compléter automatiquement. Elle suggère les noms de pods, services, namespaces, etc.

Bash

Le paquet bash-completion est requis. Installez-le d’abord si ce n’est pas fait :

# Debian / Ubuntu
sudo apt install bash-completion

# RHEL / Rocky / Alma
sudo yum install bash-completion

Puis activez l’autocomplétion kubectl :

# Activer pour la session courante
source <(kubectl completion bash)

# Activer de façon permanente
echo "source <(kubectl completion bash)" >> ~/.bashrc

Zsh

Zsh nécessite que le système de complétion soit initialisé. Ajoutez ces lignes dans votre ~/.zshrc avant la ligne de complétion kubectl (si compinit n’est pas déjà appelé) :

# Initialiser le système de complétion Zsh (si pas déjà fait)
autoload -Uz compinit && compinit

# Activer la complétion kubectl
source <(kubectl completion zsh)

Pour rendre permanent :

echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
echo 'source <(kubectl completion zsh)' >> ~/.zshrc

Fish

# Activer de façon permanente
kubectl completion fish > ~/.config/fish/completions/kubectl.fish

PowerShell

# Activer pour la session courante
kubectl completion powershell | Out-String | Invoke-Expression

# Activer de façon permanente
kubectl completion powershell >> $PROFILE

Vérification : redémarrez votre shell, tapez kubectl get puis appuyez sur Tab. Une liste de types de ressources doit s’afficher (pods, services, deployments…).

Si l’autocomplétion ne fonctionne pas :

• Bash : vérifiez que bash-completion est installé et que ~/.bashrc est bien sourcé
• Zsh : vérifiez que compinit est appelé dans votre ~/.zshrc avant la ligne kubectl
• Tous : rechargez le shell avec exec $SHELL après modification du fichier de config

Vérifier la connexion au cluster

Après l’installation, testez la connexion à votre cluster (si un kubeconfig est déjà en place) :

# Tester la connexion
kubectl cluster-info

# Vérifier le contexte actif
kubectl config current-context

# Vérifier vos permissions
kubectl auth can-i get pods

Résultat attendu pour cluster-info : l’URL de l’API server et du CoreDNS s’affichent. Si vous voyez une erreur, vérifiez que votre cluster est démarré et que le fichier kubeconfig (~/.kube/config) pointe vers la bonne adresse.

Kubeconfig, contextes et multi-cluster

Le fichier kubeconfig est le fichier de configuration central de kubectl : il contient vos clusters, identités et contextes. Sa structure, l’import de kubeconfigs reçus, la gestion multi-cluster et la sécurité sont couverts en détail dans le guide Kubeconfig et contextes Kubernetes.

Dépannage

Symptôme	Commande de diagnostic	Cause probable	Correctif
command not found: kubectl	command -v kubectl (Linux/macOS) ou where.exe kubectl (Windows)	kubectl n’est pas dans le PATH	Déplacez le binaire dans /usr/local/bin/ ou ajoutez son répertoire au PATH
The connection to the server was refused	kubectl config view (vérifier l’URL du serveur)	Cluster non démarré ou mauvaise URL	Vérifiez que le cluster tourne, corrigez l’URL dans le kubeconfig
error: You must be logged in	kubectl auth can-i get pods	Token expiré ou invalide, problème RBAC	Renouvelez vos identifiants ou régénérez le kubeconfig
certificate signed by unknown authority	kubectl config view --raw (vérifier le chemin CA)	Certificat CA manquant, proxy d’entreprise ou MITM	Vérifiez le chemin certificate-authority ; en entreprise, ajoutez le CA corporate
L’autocomplétion ne fonctionne pas	type _init_completion (Bash)	bash-completion non installé ou compinit absent (Zsh)	Installez bash-completion ; sous Zsh, ajoutez autoload -Uz compinit && compinit
error: context "xxx" does not exist	kubectl config get-contexts	Contexte mal nommé ou fichier kubeconfig incorrect	Listez les contextes disponibles et vérifiez KUBECONFIG

Glissez pour voir

À retenir

• kubectl est l’outil CLI officiel pour administrer les clusters Kubernetes — il communique avec l’API server du cluster.
• La version skew policy impose que kubectl soit à ±1 version mineure de l’API server — vérifiez avec kubectl version.
• L’installation se fait en quelques minutes sur Linux, macOS ou Windows. Validez le checksum du binaire en environnement sensible.
• L’autocomplétion fait gagner un temps considérable — activez-la dès l’installation (Bash nécessite bash-completion, Zsh nécessite compinit).
• Pour la configuration du kubeconfig, la gestion des contextes et le travail multi-cluster, consultez le guide dédié : Kubeconfig et contextes Kubernetes.

Prochaines étapes

Gérer les contextes kubectl Basculer entre clusters et namespaces avec les contextes Kubernetes

Diagnostiquer avec kubectl Runbook de diagnostic : get, describe, logs et top en situation d'incident

Créer et appliquer des ressources Déployer vos premières ressources avec kubectl create et apply

×

📖 Voir la documentation →