k3d

k3d est un wrapper qui exécute k3s (la distribution Kubernetes légère de Rancher) dans des conteneurs Docker. Maintenu par k3d-io, il crée des clusters opérationnels en quelques secondes avec une empreinte mémoire minimale. k3d est idéal pour le développement quotidien proche de la production quand k3s est utilisé en prod : Traefik est préinstallé, la registry locale s'intègre en une commande, et le load balancer intégré simplifie l'accès HTTP/HTTPS via des port mappings déclaratifs.

Informations essentielles

Origine : k3d-io (ex Rancher Labs)  ·  Licence : MIT  ·  Architectures : x86_64, ARM64

Liens : Site officiel  ·  Documentation  ·  GitHub  ·  Releases

Support : Communauté k3d-io. Projet actif.

Stack par défaut

Prérequis

Installation

# Script officiel (Linux/macOS)
curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash

# Homebrew
brew install k3d

k3d version

Créer et gérer un cluster

# Cluster minimal
k3d cluster create

# Cluster nommé avec agents (workers)
k3d cluster create mycluster --agents 2

# Cluster avec port mapping HTTP/HTTPS via le load balancer
k3d cluster create mycluster \
  --agents 2 \
  --port 8080:80@loadbalancer \
  --port 8443:443@loadbalancer

# Lister les clusters
k3d cluster list

# Arrêter / démarrer
k3d cluster stop mycluster
k3d cluster start mycluster

# Supprimer
k3d cluster delete mycluster

Configuration via fichier

# k3d-config.yaml
apiVersion: k3d.io/v1alpha5
kind: Simple
metadata:
  name: mycluster
servers: 1        # nœuds control-plane (HA possible avec servers: 3)
agents: 2         # nœuds workers
ports:
  - port: 8080:80
    nodeFilters:
      - loadbalancer
  - port: 8443:443
    nodeFilters:
      - loadbalancer
options:
  k3s:
    extraArgs:
      - arg: --disable=traefik    # Désactiver Traefik (pour NGINX par ex.)
        nodeFilters:
          - server:0

k3d cluster create --config k3d-config.yaml

Registry locale

# Créer une registry locale
k3d registry create myregistry.localhost --port 5111

# Créer un cluster qui utilise cette registry
k3d cluster create mycluster \
  --registry-use k3d-myregistry.localhost:5111 \
  --agents 2

# Lister les registries
k3d registry list

# Construire et pousser une image
docker build -t k3d-myregistry.localhost:5111/myimage:tag .
docker push k3d-myregistry.localhost:5111/myimage:tag

# Dans les manifests Kubernetes :
# image: k3d-myregistry.localhost:5111/myimage:tag

Charger des images locales (sans registry)

# Importer une image Docker directement dans le cluster
k3d image import myimage:tag -c mycluster

# Importer plusieurs images
k3d image import image1:tag image2:tag -c mycluster

kubeconfig

# Fusionner dans ~/.kube/config et basculer le contexte
k3d kubeconfig merge mycluster --kubeconfig-switch-context

# Exporter dans un fichier dédié
k3d kubeconfig get mycluster > ~/.kube/k3d-mycluster.yaml

# Contexte kubectl : k3d-<cluster-name>
kubectl config use-context k3d-mycluster
kubectl get nodes

Mise à jour

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

# Homebrew
brew upgrade k3d

Troubleshooting

# Logs d'un nœud (conteneur Docker)
docker logs k3d-mycluster-server-0
docker logs k3d-mycluster-agent-0

# Pods système
kubectl get pods -n kube-system

# Traefik en conflit avec un autre ingress controller
k3d cluster create mycluster --k3s-arg "--disable=traefik@server:0"

# Port déjà utilisé sur l'hôte
# Changer le port hôte : --port 9080:80@loadbalancer

# Contexte kubectl incorrect
kubectl config current-context        # Doit afficher k3d-mycluster
kubectl config use-context k3d-mycluster

# Réinitialiser
k3d cluster delete mycluster
k3d cluster create mycluster --agents 2

Ressources

• Site officiel : https://k3d.io
• Documentation : https://k3d.io/stable/
• GitHub : https://github.com/k3d-io/k3d
• Releases : https://github.com/k3d-io/k3d/releases