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 ?

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.

Installation de k3d

Méthode rapide (script officiel) :

curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash

Vérifiez l’installation :

k3d version

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

Installation de Kind

Téléchargement du binaire (Linux amd64) :

curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.31.0/kind-linux-amd64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind

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

k3d
Kind

Créer un cluster k3d

Une seule commande suffit :

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[0016] Cluster 'monapp' created successfully!
INFO[0016] You can now use it like this:
kubectl cluster-info

En quelques secondes (variable selon votre machine), vous avez un cluster fonctionnel.

Créer un cluster Kind

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 :

É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 :

É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

kubectl cluster-info

Kubernetes control plane is running at https://0.0.0.0:xxxxx
CoreDNS is running at https://0.0.0.0:xxxxx/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

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-xxxxx                             1/1     Running   0          2m
kube-system   local-path-provisioner-xxxxx              1/1     Running   0          2m
kube-system   metrics-server-xxxxx                      1/1     Running   0          2m

Tous les pods doivent être en Running ou Completed.

Gérer le cycle de vie du cluster

Lister les clusters

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)

k3d
Kind

k3d cluster stop monapp

k3d cluster start monapp

Supprimer un cluster

k3d
Kind

k3d cluster delete monapp

INFO[0000] Deleting cluster 'monapp'
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.

Aller plus loin

Cluster multi-nœuds

Pour simuler un environnement plus réaliste avec plusieurs machines :

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)

Si vous avez plusieurs clusters, changez de contexte :

kubectl config get-contexts

kubectl config use-context k3d-monapp

Switched to context "k3d-monapp".

Dépannage

Le cluster ne démarre pas

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

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

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

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

Prochaines étapes

Votre cluster est prêt. Passez au déploiement de votre première application :

Votre premier déploiement Déployez une application et exposez-la sur le réseau

Les concepts clés Revoir le vocabulaire : Pod, Deployment, Service

kubectl en détail Maîtrisez les commandes essentielles