Créer votre premier cluster Kubernetes local avec k3d ou Kind

Avec k3d ou Kind, vous pouvez créer un cluster Kubernetes local en quelques commandes sur votre poste. Ces outils sont parfaits pour apprendre, tester des manifests et faire des labs sans coût cloud. Dans ce guide, vous allez installer l'outil, créer un cluster, vérifier qu'il fonctionne, puis apprendre à le supprimer ou le recréer proprement.

Ce que vous allez apprendre

Choisir entre k3d et Kind selon vos besoins
Installer l'outil de création de clusters
Créer un cluster Kubernetes fonctionnel
Vérifier que le cluster est opérationnel
Gérer le cycle de vie (stop, start, delete)

Pourquoi un cluster local ?

Avant de déployer en production, vous avez besoin d'un environnement pour apprendre et tester. Un cluster local offre plusieurs avantages :

Avantage	Description
Gratuit	Pas de coûts cloud
Rapide	Création en moins de 2 minutes
Jetable	Supprimez et recréez à volonté
Identique	Mêmes commandes qu'en production

k3d ou Kind : lequel choisir ?

Les deux outils créent des clusters Kubernetes dans Docker, mais avec des philosophies différentes.

k3d est un wrapper autour de k3s, une distribution Kubernetes légère. Il crée des conteneurs Docker qui exécutent k3s.

Kind (Kubernetes IN Docker) a été conçu principalement pour tester Kubernetes lui-même. Il crée des conteneurs Docker qui exécutent un Kubernetes vanilla, souvent utilisé en CI.

Critère	k3d	Kind
Distribution	k3s (léger)	Kubernetes vanilla
Démarrage	Généralement plus rapide	Plus lent au premier lancement
Ressources	Plus léger en général	Plus gourmand
Point d'entrée réseau	Conteneur load balancer inclus	Nécessite MetalLB pour un LB
Cas d'usage principal	Développement local, labs	Tests de conformité, CI

Quel outil pour quel besoin ?

Ce tableau se lit par la ligne qui décrit votre situation, pas par la colonne de l'outil. Rien ne vous engage : les deux outils cohabitent sans conflit sur le même poste, chacun gérant ses propres conteneurs et son propre contexte kubectl. Si vous hésitez, commencez par celui de la ligne qui correspond à votre objectif du moment, vous installerez l'autre le jour où le besoin apparaîtra.

Vous voulez…	Outil conseillé
Démarrer vite sur un poste modeste	k3d
Un environnement Kubernetes standard de test	Kind
Un cluster multi-nœuds léger	k3d
Faire de la CI de validation Kubernetes	Kind ou k3d
Apprendre Kubernetes en local	k3d (recommandé)

Prérequis

Avant de commencer, vous avez besoin de :

Docker installé et fonctionnel (docker ps doit fonctionner)
kubectl installé (guide d'installation)
~2 Go de RAM disponible

Vérifiez que Docker fonctionne :

docker ps

Si la commande retourne une liste (même vide), Docker est prêt.

Installer k3d ou Kind

Les deux outils s'installent de la même façon : un binaire à déposer dans votre PATH, aucune configuration, aucun service à démarrer. Choisissez l'onglet de l'outil retenu, vous n'avez pas besoin d'installer les deux pour suivre la suite du guide.

k3d (recommandé)
Kind

Installation de k3d

k3d se distribue sous la forme d'un binaire unique, sans dépendance. Le projet publie à côté de chaque version un fichier checksums.txt : télécharger le binaire, comparer son empreinte à celle publiée, puis l'installer garantit que vous exécutez bien ce que le projet a produit. Le chemin _dist/ présent dans le fichier de sommes doit être retiré pour que sha256sum retrouve le fichier local, d'où le sed de la commande.

K3D_VERSION=v5.8.3
BASE="https://github.com/k3d-io/k3d/releases/download/${K3D_VERSION}"

curl -sSLO "${BASE}/k3d-linux-amd64"
curl -sSL "${BASE}/checksums.txt" \
  | grep '_dist/k3d-linux-amd64$' \
  | sed 's#_dist/##' \
  | sha256sum --check -

sudo install -m 0755 k3d-linux-amd64 /usr/local/bin/k3d

La vérification doit afficher k3d-linux-amd64: OK. Si elle affiche FAILED, supprimez le fichier téléchargé et recommencez, ne l'installez pas.

Vérifiez l'installation :

k3d version

k3d version v5.8.3
k3s version v1.31.5-k3s1 (default)

Installation de Kind

Même principe que pour k3d : un binaire unique, accompagné cette fois d'un fichier d'empreinte par plateforme (kind-linux-amd64.sha256sum). Le nom inscrit dans ce fichier correspond au nom d'origine du binaire, il faut donc conserver ce nom pendant la vérification et ne le renommer qu'au moment de l'installation.

KIND_VERSION=v0.31.0
BASE="https://github.com/kubernetes-sigs/kind/releases/download/${KIND_VERSION}"

curl -sSLO "${BASE}/kind-linux-amd64"
curl -sSL "${BASE}/kind-linux-amd64.sha256sum" | sha256sum --check -

sudo install -m 0755 kind-linux-amd64 /usr/local/bin/kind

La sortie attendue est kind-linux-amd64: OK.

Alternatives : brew install kind (macOS/Linux) ou go install sigs.k8s.io/kind@latest (Go installé).

Vérifiez l'installation :

kind version

kind v0.31.0 go1.25.5 linux/amd64

Créer votre premier cluster

La création télécharge une image de conteneur au premier lancement, comptez quelques centaines de mégaoctets et une connexion réseau active. Un point commun aux deux outils : à la fin de la commande, votre kubectl pointe automatiquement sur le nouveau cluster, sans aucune manipulation de kubeconfig de votre part.

k3d
Kind

Créer un cluster k3d

Une seule commande suffit, et le nom que vous donnez (monapp) sert de préfixe à tout ce qui sera créé : réseau Docker, conteneurs, contexte kubectl. Les chiffres entre crochets dans la sortie sont le temps écoulé en secondes depuis le début, ils permettent de voir quelle étape prend du temps. Sur un poste où les images sont déjà présentes, le total tourne autour de la dizaine de secondes.

k3d cluster create monapp

INFO[0000] Prep: Network
INFO[0000] Created network 'k3d-monapp'
INFO[0000] Created image volume k3d-monapp-images
INFO[0001] Creating node 'k3d-monapp-server-0'
INFO[0001] Creating LoadBalancer 'k3d-monapp-serverlb'
INFO[0001] Starting cluster 'monapp'
INFO[0004] Starting node 'k3d-monapp-server-0'
INFO[0004] Starting helpers...
INFO[0012] Cluster 'monapp' created successfully!
INFO[0012] You can now use it like this:
kubectl cluster-info

La dernière ligne n'est pas une commande exécutée automatiquement : c'est une suggestion. Le contexte kubectl est en revanche déjà basculé sur ce nouveau cluster, vérifiez-le à l'étape suivante avant de lancer quoi que ce soit.

Créer un cluster Kind

Kind affiche une liste de cases cochées au lieu d'un journal horodaté. La première ligne, Ensuring node image, est celle qui prend le plus de temps au premier lancement : elle télécharge l'image kindest/node, plusieurs centaines de mégaoctets, qui contient un Kubernetes complet. Les lancements suivants réutilisent cette image et démarrent en quelques dizaines de secondes.

kind create cluster --name monapp

Creating cluster "monapp" ...
 ✓ Ensuring node image (kindest/node:v1.32.0)
 ✓ Preparing nodes
 ✓ Writing configuration
 ✓ Starting control-plane
 ✓ Installing CNI
 ✓ Installing StorageClass
Set kubectl context to "kind-monapp"

Ce que l'outil a créé

Comprendre ce qui vient d'être créé aide à démystifier Kubernetes.

k3d
Kind

Avec k3d, vous avez maintenant :

Rien de tout cela n'est magique : chaque élément du tableau est un objet Docker que vous pouvez lister, inspecter ou supprimer à la main. La conséquence pratique est importante pour la suite : un cluster k3d ne survit pas à la suppression de ses conteneurs. Si vous faites le ménage dans Docker avec un docker system prune, vous détruisez le cluster sans passer par k3d.

Élément créé	Description
Conteneur serveur	Un conteneur Docker (`k3d-monapp-server-0`) qui exécute k3s avec le rôle control plane
Conteneur load balancer	Un point d'entrée (`k3d-monapp-serverlb`) pour simplifier l'exposition des ports locaux
Réseau Docker	Un réseau `k3d-monapp` pour la communication entre conteneurs
Volume d'images	Un volume Docker pour stocker les images de conteneurs du cluster
Contexte kubectl	Configuré automatiquement pour pointer vers ce cluster

docker ps --filter "name=k3d-monapp"

Avec Kind, vous avez maintenant :

La liste est plus courte que celle de k3d, et la différence tient au point d'entrée réseau : Kind ne crée pas de conteneur load balancer. Pour exposer un service de type LoadBalancer, il vous faudra ajouter un composant comme MetalLB, alors que k3d fournit ce rôle dès la création du cluster.

Élément créé	Description
Conteneur nœud	Un conteneur Docker (`monapp-control-plane`) qui exécute Kubernetes vanilla
Réseau Docker	Un réseau `kind` pour la communication
Contexte kubectl	Configuré automatiquement pour pointer vers ce cluster

docker ps --filter "name=monapp"

Vérifier que le cluster fonctionne

Une fois le cluster créé, vérifiez qu'il est opérationnel :

Vérifiez le contexte kubectl
Fenêtre de terminal
```
kubectl config current-context
```
Résultat k3d
```
k3d-monapp
```
Affichez les informations du cluster
Fenêtre de terminal
```
kubectl cluster-info
```
Résultat
```
Kubernetes control plane is running at https://0.0.0.0:37625
CoreDNS is running at https://0.0.0.0:37625/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
Metrics-server is running at https://0.0.0.0:37625/api/v1/namespaces/kube-system/services/https:metrics-server:https/proxy
```
Le numéro de port est tiré au hasard à la création du cluster, le vôtre sera différent. Ce qui compte est que la commande réponde : si elle affiche The connection to the server ... was refused, le cluster n'est pas démarré ou le contexte pointe ailleurs.

Listez les nœuds

kubectl get nodes

NAME                  STATUS   ROLES                  AGE   VERSION
k3d-monapp-server-0   Ready    control-plane,master   1m    v1.31.5+k3s1

Vérifiez les pods du cluster

kubectl get pods -A

Cette commande montre que Kubernetes tourne déjà avec ses propres composants (DNS, proxy réseau, etc.) répartis dans plusieurs namespaces :

NAMESPACE     NAME                                      READY   STATUS      RESTARTS   AGE
kube-system   coredns-ccb96694c-6qgn6                   1/1     Running     0          26s
kube-system   helm-install-traefik-crd-cnrn6            0/1     Completed   0          26s
kube-system   helm-install-traefik-v927w                0/1     Completed   1          26s
kube-system   local-path-provisioner-5cf85fd84d-ls4xz   1/1     Running     0          26s
kube-system   metrics-server-5985cbc9d7-b8zvp           1/1     Running     0          26s
kube-system   svclb-traefik-6319d9ca-5x5hq              2/2     Running     0          8s
kube-system   traefik-5d45fc8cc9-q58sx                  1/1     Running     0          8s

Tous les pods doivent être en Running ou Completed. Les deux lignes helm-install-traefik sont des jobs d'installation : ils tournent une fois, installent l'Ingress Controller livré avec k3s, puis passent en Completed avec 0/1 prêt. C'est le comportement normal d'un job terminé, pas un échec. Le suffixe aléatoire des noms de pods sera différent chez vous.

Gérer le cycle de vie du cluster

Lister les clusters

Chaque outil ne connaît que ses propres clusters : k3d cluster list ignore un cluster Kind, et inversement. La sortie de k3d indique en plus le rapport nœuds démarrés sur nœuds attendus (1/1), ce qui permet de repérer d'un coup d'oeil un cluster partiellement arrêté.

k3d
Kind

k3d cluster list

NAME      SERVERS   AGENTS   LOADBALANCER
monapp    1/1       0/0      true

kind get clusters

monapp

Arrêter un cluster (économiser les ressources)

Arrêter un cluster stoppe ses conteneurs sans détruire leur contenu : vos déploiements, vos ConfigMaps et vos volumes sont toujours là au redémarrage. C'est le geste à faire en fin de journée sur un poste où plusieurs clusters cohabitent, chacun consommant de la mémoire en permanence.

k3d
Kind

k3d cluster stop monapp

k3d cluster start monapp

Supprimer un cluster

La suppression est définitive et ne demande aucune confirmation. Tout ce qui vivait dans le cluster disparaît, y compris les données stockées dans les volumes. Sur un cluster d'apprentissage c'est sans conséquence, mais prenez l'habitude de vérifier le nom : k3d cluster delete accepte n'importe quel cluster existant sans vous demander si c'est bien celui-là.

k3d
Kind

k3d cluster delete monapp

INFO[0000] Deleting cluster 'monapp'
INFO[0001] Deleting cluster network 'k3d-monapp'
INFO[0001] Deleting 1 attached volumes...
INFO[0001] Removing cluster details from default kubeconfig...
INFO[0001] Removing standalone kubeconfig file (if there is one)...
INFO[0001] Successfully deleted cluster monapp!

kind delete cluster --name monapp

La suppression :

Arrête tous les conteneurs Docker du cluster
Supprime le réseau Docker associé
Retire le contexte de kubectl

Ce que vous n'avez pas besoin de comprendre tout de suite

Pour utiliser un cluster local, vous n'avez pas besoin de maîtriser :

Concept	Pourquoi l'ignorer pour l'instant
etcd	La base de données interne de Kubernetes, gérée automatiquement
CNI	Le plugin réseau, préconfiguré par k3d/Kind
CSI	Le stockage, un stockage local est inclus
Scheduler	Le composant qui place les pods, fonctionne tout seul
Admission controllers	Des contrôles avancés, pas utiles pour débuter

Pour le moment, vous avez juste besoin d'un cluster qui répond à kubectl.

Cluster multi-nœuds et gestion des contextes

Cluster multi-nœuds

Un cluster à un seul nœud suffit pour déployer une application, mais il masque tout ce qui relève de la répartition : le scheduler n'a pas de choix à faire, les contraintes de placement n'ont aucun effet visible, et une panne de nœud ne peut pas être simulée. Ajouter deux workers change cela sans coûter beaucoup de mémoire, chaque nœud n'étant qu'un conteneur supplémentaire.

k3d
Kind

k3d cluster create demo --servers 1 --agents 2

Option	Signification
`--servers 1`	1 nœud control plane
`--agents 2`	2 nœuds workers

kubectl get nodes

Pour Kind, créez un fichier de configuration :

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
  - role: worker
  - role: worker

kind create cluster --name demo --config kind-config.yaml

Changer de cluster (si plusieurs)

kubectl ne parle qu'à un seul cluster à la fois, celui désigné par le contexte courant. Créer un nouveau cluster bascule automatiquement ce contexte, ce qui explique la mésaventure classique : vous déployez sur le dernier cluster créé en croyant travailler sur le précédent. Prenez le réflexe de vérifier avant chaque session.

kubectl config get-contexts

kubectl config use-context k3d-monapp

Switched to context "k3d-monapp".

Dépannage

Le cluster ne démarre pas

Les trois causes ci-dessous se situent toutes en dehors de Kubernetes : le démon Docker, les ports de l'hôte, la mémoire disponible. Avant de chercher du côté du cluster, exécutez docker ps : si cette commande échoue, aucune des étapes de ce guide ne peut fonctionner.

Symptôme	Cause probable	Solution
"Cannot connect to Docker"	Docker non démarré	Vérifiez que Docker Desktop ou le service Docker est démarré selon votre système
"Port already in use"	Le port d'API choisi est occupé	Arrêtez l'autre service ou utilisez `--api-port` pour changer de port
"Insufficient memory"	Pas assez de RAM	Libérez de la mémoire ou réduisez le nombre de nœuds

kubectl ne trouve pas le cluster

Le fichier ~/.kube/config peut avoir été écrasé, par exemple par un outil cloud qui le régénère, ou par une copie manuelle. Commencez par lister les contextes connus : si celui de votre cluster a disparu, kubectl ne saura pas où se connecter même si les conteneurs tournent toujours.

kubectl config get-contexts

Si le contexte n'apparaît pas, la solution la plus simple est de recréer le cluster :

k3d cluster delete monapp
k3d cluster create monapp

Les pods système restent en Pending

Un pod en Pending n'a pas encore été placé sur un nœud : le problème est en amont du conteneur, donc kubectl logs ne renvoie rien d'utile. Les événements sont la bonne source, ils indiquent explicitement pourquoi le scheduler n'a trouvé aucun nœud acceptable.

kubectl get events -A --sort-by='.lastTimestamp' | head -20

Cause fréquente : ressources insuffisantes. Solution : arrêtez d'autres applications gourmandes ou réduisez le nombre de nœuds du cluster.

Récapitulatif des commandes

Une différence de vocabulaire mérite d'être notée avant de passer d'un outil à l'autre : k3d place systématiquement le nom du cluster en argument positionnel, Kind attend l'option --name. Oublier ce détail avec Kind agit sur le cluster par défaut, appelé kind, et non sur le vôtre.

Action	k3d	Kind
Créer	`k3d cluster create nom`	`kind create cluster --name nom`
Lister	`k3d cluster list`	`kind get clusters`
Arrêter	`k3d cluster stop nom`	Non supporté
Démarrer	`k3d cluster start nom`	Non supporté
Supprimer	`k3d cluster delete nom`	`kind delete cluster --name nom`

À retenir

k3d et Kind créent des clusters locaux pour apprendre, tester et faire de la CI, pas pour la production
k3d est recommandé pour débuter : plus léger, plus rapide, inclut un point d'entrée réseau
Kind est utile pour les tests de conformité et la CI sur un Kubernetes vanilla
Un cluster local est jetable : si vous le cassez, supprimez-le et recréez-le
kubectl est configuré automatiquement après la création du cluster
kubectl get pods -A montre tous les pods dans tous les namespaces, utile pour vérifier l'état du cluster
Arrêter vs supprimer : arrêter préserve vos déploiements (k3d seulement), supprimer libère tout

Pour aller plus loin

Architecture Kubernetes : Ce que contiennent réellement les conteneurs que k3d ou Kind viennent de démarrer.
Les Pods : La première ressource à créer sur le cluster que vous venez d'obtenir.
Contrôle des connaissances : Vérifier que les fondamentaux sont acquis avant d'attaquer les ressources Kubernetes.