K3s : Kubernetes léger pour edge, IoT et homelab

K3s est une distribution Kubernetes légère (~70 MB) qui intègre dans un seul binaire tous les composants nécessaires : containerd, Flannel, CoreDNS, metrics-server. Conçu pour les environnements edge, IoT et les homelabs, K3s démarre en quelques secondes avec des ressources minimales (512 MB RAM pour un agent).

Ce guide vous montre comment :

• Installer K3s sur un serveur unique ou un cluster multi-node
• Configurer via YAML (config.yaml, registries.yaml)
• Désactiver les composants inutiles (Traefik, ServiceLB)
• Déployer en haute disponibilité avec etcd intégré
• Diagnostiquer les problèmes courants

Version actuelle

Ce guide utilise K3s v1.34.3+k3s1 (channel stable, février 2025). K3s inclut Kubernetes v1.34, containerd v2.1.5, Traefik v3.5.1, etcd v3.6.6.

Ce que vous allez apprendre

• Architecture K3s : binaire unique, composants intégrés, différences avec Kubernetes standard
• Installation rapide : mono-serveur en 30 secondes, multi-node avec agents
• Configuration YAML : config.yaml pour personnaliser, registries.yaml pour les registries privés
• Gestion des add-ons : désactiver Traefik, ServiceLB, local-path selon vos besoins
• Haute disponibilité : cluster HA avec etcd intégré (3+ serveurs)
• Dépannage : commandes de diagnostic et résolution des problèmes courants

Vocabulaire essentiel

Avant de commencer, voici les termes que vous rencontrerez dans ce guide :

Terme	Explication simple
Cluster	Un groupe de machines (physiques ou virtuelles) qui travaillent ensemble pour faire tourner vos applications
Node	Une machine dans le cluster. Peut être un “server” ou un “agent”
Server (K3s)	La machine qui prend les décisions : où lancer les applications, comment les exposer au réseau, etc. C’est le “cerveau” du cluster
Agent (K3s)	Une machine qui exécute les applications. Elle reçoit ses ordres du server. C’est la “force de travail”
Control plane	L’ensemble des composants qui gèrent le cluster (API, scheduler, etc.). Sur K3s, c’est le rôle du “server”
Pod	La plus petite unité dans Kubernetes : un ou plusieurs conteneurs qui tournent ensemble
kubeconfig	Un fichier qui contient les informations de connexion à votre cluster (adresse, certificats, tokens)
Token	Un mot de passe secret qui permet aux agents de rejoindre le cluster

Glissez pour voir

Analogie : cluster de VMs

Imaginez un datacenter avec plusieurs serveurs :

• Le server K3s est l’hyperviseur master : il décide quels workloads lancer et sur quelle machine
• Les agents sont les hyperviseurs workers : ils exécutent les VMs/conteneurs assignés
• Les pods sont les workloads en cours d’exécution
• Le token est la clé SSH/API qui permet aux workers de rejoindre le cluster

Quand choisir K3s

Critère	K3s	Minikube	Kind
Cas d’usage	Edge / IoT / homelab, prod légère	Dev local, apprentissage	CI/CD, tests, clusters jetables
Datastore	SQLite (défaut) ; embedded etcd (HA) ; externe possible	etcd (kubeadm), HA stacked	etcd (kubeadm) dans les control-planes
Multi-node	✅ Natif (server/agent)	✅ --nodes	✅ via config YAML
HA control plane	✅ embedded etcd (min. 3 serveurs)	✅ --ha (min. 3 CP) + kube-vip	✅ multi control-planes (HAProxy)
Ressources	Agent ~275 MiB, Server ~1.6 GiB	2 CPU, 20 GB disque (défaut)	≥6 GB RAM Docker (8 GB conseillé)
GPU	⚠️ À configurer (toolkit + plugin)	✅ --gpus (driver Docker)	⚠️ Pas clé en main
Persistance	✅ Cluster système (systemd)	✅ Profils persistants	⚠️ Plutôt jetable
Installation	Binaire + service (Linux)	VM ou conteneur selon driver	Conteneurs Docker “nodes”

Glissez pour voir

Choisissez K3s si :

• Vous déployez sur des serveurs physiques ou VMs (pas de conteneur wrapper)
• Vous avez besoin de haute disponibilité native
• Vos ressources sont limitées (Raspberry Pi, edge)
• Vous voulez un cluster persistant pour un homelab

Architecture K3s

Pourquoi K3s est “léger” ?

Un Kubernetes standard nécessite d’installer séparément de nombreux composants (etcd, kubelet, kube-proxy, un CNI…). K3s simplifie tout ça : un seul fichier de ~70 MB contient tout ce dont vous avez besoin.

Concrètement, quand vous installez K3s :

1. Un seul binaire /usr/local/bin/k3s est téléchargé
2. Ce binaire contient Kubernetes + tous les outils annexes
3. Un service systemd démarre et gère le tout

Composants intégrés

Voici ce que K3s installe automatiquement (vous n’avez rien à faire) :

Composant	Ça sert à quoi ?
containerd	Fait tourner vos conteneurs (comme Docker, mais plus léger)
Flannel	Crée le réseau virtuel pour que vos pods communiquent entre eux
CoreDNS	Permet à vos pods de se trouver par nom (mon-service.default.svc) au lieu d’IP
kube-proxy	Route le trafic réseau vers les bons pods
metrics-server	Collecte les stats CPU/RAM pour kubectl top
Traefik	Ingress controller : expose vos apps sur le réseau externe
ServiceLB	Simule un load balancer cloud pour les services de type LoadBalancer
local-path	Crée des volumes persistants sur le disque local

Glissez pour voir

Pas besoin de tout comprendre maintenant

Si vous débutez, retenez juste que K3s s’occupe de tout. Vous n’avez pas à installer ces composants un par un. Ils fonctionnent “out of the box”.

Add-ons optionnels (désactivables)

Certains composants peuvent être désactivés si vous préférez utiliser des alternatives :

Add-on	Pourquoi le désactiver ?
Traefik	Vous préférez Nginx Ingress, Istio, ou gérez l’ingress autrement
ServiceLB	Vous utilisez MetalLB ou n’avez pas besoin de LoadBalancer
local-path	Vous utilisez un stockage réseau (NFS, Longhorn, Ceph)

Glissez pour voir

Conseil débutant

Gardez les add-ons par défaut pour commencer. Vous pourrez les désactiver plus tard quand vous maîtriserez mieux K3s. Traefik et ServiceLB sont très pratiques pour exposer rapidement vos applications.

Modes de datastore

K3s supporte plusieurs backends pour stocker l’état du cluster :

Mode	Quand l’utiliser	Description
SQLite (kine)	Mono-serveur (défaut)	Simple, fiable, fichier local. Parfait pour apprendre ou un homelab léger
Embedded etcd	HA (3+ serveurs)	Activé avec --cluster-init. Réplication + quorum entre serveurs
Datastore externe	Infra existante	MySQL, PostgreSQL ou etcd externe. Utile si vous avez déjà une DB managée

Glissez pour voir

SQLite n'est pas etcd

Contrairement à une idée reçue, K3s n’utilise pas etcd par défaut. Il utilise SQLite via un adaptateur appelé kine. etcd n’est activé que si vous initialisez un cluster HA avec --cluster-init.

Prérequis

Ressources minimales

Rôle	CPU	RAM	Disque
Server (control plane)	2 cœurs	2 GB	10 GB SSD
Agent (worker)	1 cœur	512 MB	5 GB

Glissez pour voir

Systèmes supportés

• Linux : Ubuntu 20.04+, Debian 11+, RHEL/Rocky 8+, openSUSE
• Architecture : amd64, arm64, armhf (Raspberry Pi)

Ports réseau

Port	Protocole	Fonction	Requis pour
6443	TCP	API Kubernetes	Tous (agents, kubectl)
8472	UDP	Flannel VXLAN	Multi-node
10250	TCP	Kubelet metrics	Monitoring
2379-2380	TCP	etcd	HA (serveurs uniquement)

Glissez pour voir

Installation mono-serveur

L’installation la plus simple : un serveur unique qui fait tourner le control plane et les workloads.

C'est quoi un cluster mono-serveur ?

Un cluster avec une seule machine qui fait tout : elle prend les décisions (control plane) ET exécute vos applications (workloads). C’est parfait pour :

• Apprendre Kubernetes
• Un homelab
• Des environnements de développement
• Des projets avec peu de trafic

Limitation : si cette machine tombe en panne, tout le cluster est indisponible.

1. Installer K3s avec le script officiel

   curl -sfL https://get.k3s.io | sh -

   Décortiquons cette commande

   • curl -sfL https://get.k3s.io : télécharge le script d’installation depuis le site officiel
     • -s : mode silencieux (pas de barre de progression)
     • -f : échoue proprement si le serveur renvoie une erreur
     • -L : suit les redirections
   • | sh - : exécute le script téléchargé

   Ce que fait le script :

   1. Détecte votre OS et architecture (amd64, arm64…)
   2. Télécharge le binaire K3s (~70 MB)
   3. L’installe dans /usr/local/bin/k3s
   4. Crée un service systemd k3s.service
   5. Génère les certificats et le kubeconfig
   6. Démarre K3s automatiquement

2. Vérifier l’installation

   # Vérifier que le service K3s tourne
   sudo systemctl status k3s
   # ● k3s.service - Lightweight Kubernetes
   #   Active: active (running)   <-- Ce qu'on veut voir

   # Lister les machines du cluster
   sudo k3s kubectl get nodes
   # NAME      STATUS   ROLES           AGE   VERSION
   # master1   Ready    control-plane   30s   v1.34.3+k3s1

   Comment lire cette sortie ?

   • NAME : le nom de la machine (hostname)
   • STATUS : Ready = la machine fonctionne, NotReady = problème
   • ROLES : control-plane = c’est un server K3s
   • AGE : depuis combien de temps le node est dans le cluster
   • VERSION : version de Kubernetes

3. Configurer kubectl pour votre utilisateur

   Par défaut, le kubeconfig est lisible uniquement par root. Pour utiliser kubectl sans sudo :

   # Créer le dossier de config kubectl
   mkdir -p ~/.kube
   
   # Copier le kubeconfig K3s
   sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
   
   # Changer le propriétaire du fichier (pour votre utilisateur)
   sudo chown $(id -u):$(id -g) ~/.kube/config
   
   # Tester : cette commande ne doit plus nécessiter sudo
   kubectl get nodes

   Erreur courante

   Si vous obtenez error: error loading config file "/root/.kube/config": open /root/.kube/config: permission denied, c’est que vous avez oublié de copier le kubeconfig. Refaites les commandes ci-dessus.

Fichiers importants

Chemin	Description
/etc/rancher/k3s/k3s.yaml	Kubeconfig (certificats + token admin)
/etc/rancher/k3s/config.yaml	Configuration K3s (à créer)
/etc/rancher/k3s/registries.yaml	Configuration des registries
/var/lib/rancher/k3s/server/node-token	Token pour joindre des agents
/var/lib/rancher/k3s/server/db/	Base SQLite (datastore)

Glissez pour voir

Configuration avec config.yaml

Au lieu de passer des arguments en ligne de commande, utilisez /etc/rancher/k3s/config.yaml.

Pourquoi utiliser config.yaml ?

Deux façons de configurer K3s :

1. Ligne de commande : curl ... | INSTALL_K3S_EXEC="--disable=traefik" sh -
2. Fichier config.yaml : plus propre, versionnable, facile à modifier

Conseil : utilisez toujours config.yaml sauf pour des tests rapides.

Créer config.yaml AVANT l'installation

Si vous créez config.yaml avant d’exécuter le script d’installation, K3s appliquera automatiquement la configuration. Sinon, redémarrez le service après modification.

Profil développement (minimal)

/etc/rancher/k3s/config.yaml

# Kubeconfig lisible sans sudo
write-kubeconfig-mode: "0644"

# Désactiver les composants non nécessaires
disable:
  - traefik
  - servicelb

Profil homelab

/etc/rancher/k3s/config.yaml

write-kubeconfig-mode: "0644"

# Désactiver Traefik (utiliser Nginx Ingress à la place)
disable:
  - traefik

# Ajouter des SAN pour accès distant
tls-san:
  - "k3s.homelab.local"
  - "192.168.1.100"

# Limiter les ressources
kubelet-arg:
  - "max-pods=50"

Profil production HA

/etc/rancher/k3s/config.yaml

write-kubeconfig-mode: "0644"

# Initialiser le cluster HA (premier serveur uniquement)
cluster-init: true

# SAN pour le load balancer
tls-san:
  - "k3s-api.example.com"
  - "10.0.0.10"

# Désactiver les add-ons par défaut
disable:
  - traefik
  - servicelb
  - local-path-provisioner

# Configurer etcd
etcd-expose-metrics: true

Appliquer la configuration

# Si K3s est déjà installé, redémarrer le service
sudo systemctl restart k3s

# Vérifier les composants désactivés
sudo k3s kubectl get pods -n kube-system
# Traefik et ServiceLB ne doivent pas apparaître

Installation multi-node

Un cluster K3s se compose de servers (control plane) et agents (workers).

Pourquoi plusieurs machines ?

Avantages d’un cluster multi-node :

• Résilience : si un agent tombe, les autres prennent le relais
• Capacité : plus de ressources CPU/RAM pour vos applications
• Réalisme : environnement proche de la production

Schéma classique :

• 1 server (control plane) : prend les décisions
• 2+ agents (workers) : exécutent les applications

1. Sur le premier serveur : installer K3s

   curl -sfL https://get.k3s.io | sh -

2. Récupérer le token pour joindre les agents

   sudo cat /var/lib/rancher/k3s/server/node-token
   # K10xxx::server:xxx

   C'est quoi ce token ?

   Le token est un secret partagé qui permet aux agents de prouver qu’ils ont le droit de rejoindre le cluster. Sans ce token, une machine ne peut pas s’ajouter.

   Gardez-le secret ! Quiconque possède ce token peut ajouter des machines à votre cluster.

3. Sur chaque agent : joindre le cluster

   Connectez-vous en SSH sur la machine qui sera agent, puis :

   curl -sfL https://get.k3s.io | K3S_URL=https://SERVER_IP:6443 K3S_TOKEN=TOKEN sh -

   Remplacez :

   • SERVER_IP : l’adresse IP du serveur K3s (ex: 192.168.1.10)
   • TOKEN : le token récupéré à l’étape 2

   Exemple concret :

   curl -sfL https://get.k3s.io | K3S_URL=https://192.168.1.10:6443 K3S_TOKEN=K10abcd1234::server:xyz789 sh -

4. Vérifier le cluster

   # Sur le serveur
   sudo k3s kubectl get nodes
   # NAME       STATUS   ROLES           AGE   VERSION
   # server1    Ready    control-plane   5m    v1.34.3+k3s1
   # agent1     Ready    <none>          2m    v1.34.3+k3s1
   # agent2     Ready    <none>          1m    v1.34.3+k3s1

Labelliser les agents

Par défaut, les agents n’ont pas de rôle affiché. Ajoutez un label :

kubectl label node agent1 node-role.kubernetes.io/worker=worker
kubectl label node agent2 node-role.kubernetes.io/worker=worker

Configuration des registries

Le fichier /etc/rancher/k3s/registries.yaml configure l’accès aux registries de conteneurs.

Miroir Docker Hub

/etc/rancher/k3s/registries.yaml

mirrors:
  docker.io:
    endpoint:
      - "https://registry.local:5000"

Registry privé avec authentification

/etc/rancher/k3s/registries.yaml

mirrors:
  "registry.example.com":
    endpoint:
      - "https://registry.example.com"

configs:
  "registry.example.com":
    auth:
      username: "user"
      password: "password"
    tls:
      # Certificat CA personnalisé
      ca_file: "/etc/certs/ca.crt"
      # Ou désactiver la vérification TLS (non recommandé)
      # insecure_skip_verify: true

Registry insecure (HTTP)

/etc/rancher/k3s/registries.yaml

mirrors:
  "registry.local:5000":
    endpoint:
      - "http://registry.local:5000"

configs:
  "registry.local:5000":
    tls:
      insecure_skip_verify: true

Redémarrer après modification

Le fichier registries.yaml est lu au démarrage. Redémarrez K3s après toute modification :

sudo systemctl restart k3s  # Sur les serveurs
sudo systemctl restart k3s-agent  # Sur les agents

Haute disponibilité (HA)

C'est quoi la haute disponibilité ?

Haute disponibilité (HA) = votre cluster continue de fonctionner même si une machine tombe en panne.

Avec un seul server K3s, si cette machine s’arrête, tout le cluster est inaccessible. Avec 3 servers en HA, si l’un tombe, les deux autres prennent le relais.

Quand utiliser la HA ?

• Production avec des utilisateurs réels
• Applications critiques qui ne doivent pas s’arrêter
• Homelab “sérieux” où vous voulez de la résilience

Pas besoin de HA si :

• Vous apprenez Kubernetes
• C’est un environnement de développement
• Vous acceptez des interruptions occasionnelles

K3s supporte deux modes HA :

Mode	Description	Quand l’utiliser
etcd intégré	etcd sur chaque serveur K3s	Simplicité, pas de dépendance externe
Base externe	MySQL, PostgreSQL, etcd externe	Infrastructure existante

Glissez pour voir

HA avec etcd intégré

Nécessite 3 serveurs minimum (nombre impair pour le quorum).

Pourquoi 3 et pas 2 ?

etcd utilise un système de vote (consensus Raft). Pour qu’une décision soit prise, il faut une majorité de serveurs d’accord.

• Avec 2 serveurs : si 1 tombe, il reste 1/2 = pas de majorité → cluster bloqué
• Avec 3 serveurs : si 1 tombe, il reste 2/3 = majorité → cluster OK
• Avec 4 serveurs : si 1 tombe, il reste 3/4 = majorité, mais si 2 tombent, 2/4 = pas de majorité

Règle : utilisez toujours un nombre impair (3, 5, 7).

1. Premier serveur : initialiser le cluster

   curl -sfL https://get.k3s.io | sh -s - server \
     --cluster-init \
     --tls-san=lb.example.com

   L’option --cluster-init active etcd intégré.

2. Récupérer le token

   sudo cat /var/lib/rancher/k3s/server/node-token

3. Serveurs 2 et 3 : joindre comme serveurs

   curl -sfL https://get.k3s.io | sh -s - server \
     --server https://SERVER1_IP:6443 \
     --token TOKEN \
     --tls-san=lb.example.com

4. Vérifier le cluster

   sudo k3s kubectl get nodes
   # Tous les serveurs doivent avoir le rôle control-plane
   
   # Vérifier etcd
   sudo k3s etcdctl member list

Load balancer recommandé

En production, placez un load balancer (HAProxy, Nginx, cloud LB) devant les serveurs K3s. Les agents et clients se connectent au LB, pas directement aux serveurs.

Premiers pas après installation

Votre cluster K3s est installé. Voici comment vérifier qu’il fonctionne et déployer votre première application.

Vérifier que tout fonctionne

# 1. Vos nodes sont-ils prêts ?
kubectl get nodes
# Tous doivent être "Ready"

# 2. Les pods système tournent-ils ?
kubectl get pods -n kube-system
# Tous doivent être "Running" ou "Completed"

# 3. Les services système sont-ils OK ?
kubectl get svc -n kube-system

Déployer une application de test

# Créer un déploiement nginx
kubectl create deployment nginx --image=nginx

# Vérifier que le pod tourne
kubectl get pods
# NAME                    READY   STATUS    RESTARTS   AGE
# nginx-xxx               1/1     Running   0          30s

# Exposer l'application
kubectl expose deployment nginx --port=80 --type=NodePort

# Trouver le port attribué
kubectl get svc nginx
# NAME    TYPE       CLUSTER-IP     EXTERNAL-IP   PORT(S)        AGE
# nginx   NodePort   10.43.xxx.xx   <none>        80:3xxxx/TCP   10s

# Tester (remplacez 3xxxx par le port affiché)
curl http://localhost:3xxxx

Nettoyer

kubectl delete deployment nginx
kubectl delete svc nginx

Outils intégrés

K3s embarque plusieurs outils accessibles via le binaire.

kubectl

sudo k3s kubectl get pods -A
# Équivalent à kubectl avec le kubeconfig K3s

crictl (runtime)

# Lister les images
sudo k3s crictl images

# Lister les conteneurs
sudo k3s crictl ps

# Logs d'un conteneur
sudo k3s crictl logs CONTAINER_ID

ctr (containerd)

# Lister les images dans le namespace k8s.io
sudo k3s ctr -n k8s.io images list

check-config

Vérifier que le système supporte K3s :

sudo k3s check-config

Dépannage

Commandes de diagnostic

# Status du service
sudo systemctl status k3s
sudo journalctl -u k3s -f  # Logs en temps réel

# État du cluster
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl get pods -A

# Événements récents
sudo k3s kubectl get events --sort-by='.lastTimestamp' -A

# Vérifier les composants système
sudo k3s kubectl get pods -n kube-system

Problèmes courants

Symptôme	Cause probable	Solution
connection refused :6443	K3s pas démarré	sudo systemctl start k3s
Agent ne rejoint pas	Token invalide/expiré	Vérifier le token, l’IP et le port 6443
Pods en Pending	Pas de node schedulable	Vérifier les taints/tolerations
DNS ne résout pas	CoreDNS pas ready	kubectl rollout restart deployment/coredns -n kube-system
ImagePullBackOff	Registry inaccessible	Vérifier registries.yaml
Certificat expiré	TLS-SAN manquant	Regénérer avec --tls-san

Glissez pour voir

Réinitialiser K3s

# Désinstallation complète (server)
sudo /usr/local/bin/k3s-uninstall.sh

# Désinstallation complète (agent)
sudo /usr/local/bin/k3s-agent-uninstall.sh

# Réinstaller
curl -sfL https://get.k3s.io | sh -

Sauvegarder etcd (cluster HA)

# Snapshot manuel
sudo k3s etcd-snapshot save --name backup-$(date +%Y%m%d)

# Lister les snapshots
sudo k3s etcd-snapshot list

# Restaurer (arrêter K3s d'abord)
sudo systemctl stop k3s
sudo k3s server --cluster-reset --cluster-reset-restore-path=/path/to/snapshot

Bonnes pratiques

Sécurité

• Ne jamais exposer le port 6443 sur Internet sans authentification
• Rotation des tokens : regénérer périodiquement le node-token
• Network policies : restreindre le trafic inter-pods
• RBAC : créer des ServiceAccounts dédiés, pas de cluster-admin

Production

• 3 serveurs minimum pour la HA (etcd nécessite un quorum)
• Load balancer devant les API servers
• Monitoring : Prometheus + Grafana
• Sauvegardes etcd automatisées (cron)
• TLS-SAN : inclure toutes les IPs/DNS possibles

Ressources

• Définir les requests/limits sur tous les pods
• Surveiller avec kubectl top nodes et kubectl top pods
• Éviter les serveurs surchargés : séparer control plane et workloads si possible

À retenir

1. K3s = Kubernetes complet dans un binaire de ~70 MB, idéal pour edge/IoT/homelab
2. Installation en une ligne : curl -sfL https://get.k3s.io | sh -
3. config.yaml pour personnaliser : --disable, --tls-san, options kubelet
4. registries.yaml pour les registries privés et miroirs
5. HA native avec --cluster-init (etcd intégré, 3+ serveurs)
6. Outils intégrés : k3s kubectl, k3s crictl, k3s check-config
7. Désactiver les add-ons inutiles : Traefik, ServiceLB, local-path

Prochaines étapes

Kubernetes : les fondamentaux Comprendre les concepts pods, services, deployments

Helm : gestionnaire de packages Déployer des applications avec des charts

Minikube : Kubernetes local Alternative pour le développement local

Kind : clusters de test Kubernetes dans Docker pour CI/CD

Ressources

• Documentation officielle : docs.k3s.io
• Releases GitHub : github.com/k3s-io/k3s/releases
• Rancher (SUSE) : rancher.com/docs/k3s

×

📖 Voir la documentation →