Un serveur Kubernetes complet peut consommer plus de 4 Go de RAM rien que pour son plan de contrôle. Sur un Raspberry Pi, une passerelle IoT ou une petite instance cloud à 5 euros par mois, ce poids devient vite rédhibitoire. C’est exactement le problème que Rancher Labs (aujourd’hui SUSE) a réglé en 2019 avec K3s, une distribution Kubernetes certifiée CNCF qui tient dans un binaire unique de moins de 100 Mo. En septembre 2026, la version stable est K3s v1.36.4+k3s1, publiée fin août et alignée sur Kubernetes 1.36.4. Ce tutoriel vous montre comment installer, faire évoluer et sécuriser un cluster K3s en douze étapes concrètes, du premier serveur jusqu’à la haute disponibilité et la mise en production, avec un projet complet à la clé et une liste de pièges à éviter.

Qu’est-ce que K3s et pourquoi l’adopter en 2026

K3s est une distribution Kubernetes allégée, maintenue par SUSE et certifiée par la Cloud Native Computing Foundation. Le projet a été conçu pour tourner sur des environnements contraints en ressources : edge computing, objets connectés, intégration continue et clusters de développement. Sa documentation officielle le résume en deux mots : « Lightweight Kubernetes » (« Kubernetes léger »), selon la documentation officielle de K3s. Le dépôt GitHub du projet va plus loin et précise : « Production ready, easy to install, half the memory, all in a binary less than 100 MB » (« prêt pour la production, facile à installer, deux fois moins de mémoire, le tout dans un binaire de moins de 100 Mo »), d’après le dépôt k3s-io/k3s.

Le projet a été annoncé publiquement par Rancher Labs, qui décrivait alors K3s comme « a lightweight, easy to install Kubernetes distribution geared towards resource-constrained environments and low touch operations » (« une distribution Kubernetes légère et facile à installer, pensée pour les environnements contraints en ressources et les opérations à faible intervention »), selon l’annonce originale publiée sur le blog Rancher. Début septembre 2026, le dépôt k3s-io/k3s affiche environ 33 900 étoiles sur GitHub selon les statistiques publiques du projet, ce qui en fait l’une des distributions Kubernetes alternatives les plus suivies de l’écosystème CNCF, aux côtés de k0s et MicroK8s.

Le cas d’usage historique de K3s reste l’edge computing. Une enquête Rancher sur l’adoption de Kubernetes montrait déjà une progression marquée de l’usage en environnement on-premise, passant de 19 % à 31 % des répondants entre 2019 et 2020, avec 62 % des sondés qui déclaraient exploiter K3s spécifiquement sur des sites distants. Ces chiffres, bien qu’anciens, expliquent pourquoi le projet reste aujourd’hui la référence pour qui veut faire tourner un vrai cluster Kubernetes sur un boîtier ARM ou une flotte de capteurs, sans sacrifier la compatibilité avec l’écosystème k8s standard.

La Cloud Native Computing Foundation certifie K3s comme distribution Kubernetes conforme, au même titre que les offres managées des grands fournisseurs cloud, d’après la fiche projet publiée par la CNCF. Cette certification garantit qu’un manifeste écrit pour un cluster kubeadm classique ou pour un service managé s’applique tel quel sur K3s, sans adaptation. C’est cette compatibilité totale, combinée à la légèreté du binaire, qui pousse aussi bien des développeurs solo que des équipes plateforme en entreprise à choisir K3s pour leurs environnements de test, leurs pipelines CI et, de plus en plus, leurs déploiements en périphérie de réseau.

Prérequis techniques : versions et configuration minimale

Avant de démarrer, vérifiez que votre matériel correspond aux seuils publiés par la documentation officielle. K3s tourne sur les architectures x86_64, ARM64 et ARMv7 (armhf), avec un support s390x sur certaines lignes de version, d’après la page des prérequis de K3s. Le tableau ci-dessous résume la configuration minimale par rôle de nœud.

ComposantVersion / valeur minimaleRemarque
K3sv1.36.4+k3s1Dernière version stable, embarque Kubernetes 1.36.4
Système d’exploitationLinux 64 bits (Ubuntu 22.04+, Debian 12+, Alpine 3.18+)Noyau avec cgroups v2 activés recommandé
CPU nœud serveur2 cœurs minimum4 cœurs conseillés en production
RAM nœud serveur2 Go minimum4 Go conseillés avec etcd embarqué
CPU nœud agent1 cœur minimum2 cœurs pour des charges applicatives réelles
RAM nœud agent512 Mo minimum1 Go conseillé
kubectl1.34 ou plus récentClient compatible avec Kubernetes 1.36
RéseauPorts 6443/tcp, 8472/udp, 10250/tcp ouvertsEntre le serveur et les agents

Ces seuils, publiés par SUSE, correspondent au strict minimum pour démarrer le service. Un cluster de test sur un Raspberry Pi 4 de 4 Go passera sans souci, mais un cluster de production avec plusieurs dizaines de pods demandera davantage de mémoire, en particulier sur le nœud serveur qui héberge l’API et le datastore.

Côté système d’exploitation, K3s fonctionne sur n’importe quelle distribution Linux moderne dotée d’un noyau récent, y compris des OS orientés conteneurs comme k3OS ou Alpine. Windows n’est supporté qu’en tant que nœud agent, jamais en tant que serveur. Vérifiez également la version de votre client kubectl local : la politique de compatibilité de Kubernetes tolère un écart d’une version mineure avec le serveur, donc un client 1.35 ou 1.36 fonctionnera sans problème face à un serveur K3s 1.36.4, mais un client trop ancien peut refuser certaines commandes.

Architecture K3s : ce qui change face à Kubernetes standard

Un cluster Kubernetes classique installé avec kubeadm assemble plusieurs processus indépendants : kube-apiserver, kube-scheduler, kube-controller-manager, kubelet, kube-proxy et un cluster etcd externe. K3s regroupe tout cela dans un seul binaire et un seul processus par nœud, qu’il s’agisse d’un serveur (plan de contrôle) ou d’un agent (nœud de calcul pur, sans datastore ni plan de contrôle). La communication entre agent et serveur passe par un tunnel proxy inversé, initié depuis l’agent, ce qui simplifie la configuration réseau dans des environnements où les agents sont derrière un NAT.

Deuxième différence majeure : le datastore. Kubernetes standard impose etcd. K3s utilise par défaut SQLite, via une couche de compatibilité appelée Kine qui traduit les appels de l’API etcd vers une base SQL classique. Ce choix convient parfaitement à un cluster à un seul nœud, en développement ou en CI/CD. Pour la haute disponibilité, deux options existent : activer un etcd embarqué avec au moins trois nœuds serveurs, ou brancher un datastore externe (etcd, PostgreSQL, MySQL ou MariaDB) via le paramètre --datastore-endpoint. Enfin, K3s embarque par défaut Flannel comme CNI, Traefik comme contrôleur d’ingress, CoreDNS, metrics-server et local-path-provisioner pour le stockage, un ensemble de composants qu’il faudrait sinon installer séparément sur un cluster kubeadm.

La documentation de référence du projet Kubernetes décrit ce plan de contrôle standard comme un ensemble de composants indépendants coordonnés par l’API server, d’après la vue d’ensemble officielle des concepts Kubernetes. K3s ne remet pas en cause cette architecture : il la compresse. Chaque composant reste présent et fonctionnel, mais packagé dans un seul processus, ce qui réduit le nombre de points de défaillance réseau internes et simplifie considérablement les mises à jour, puisqu’une seule commande systemctl restart k3s suffit à relancer l’ensemble du plan de contrôle sur un nœud donné.

Étape 1 : préparer le système d’exploitation

Sur chaque machine qui rejoindra le cluster, mettez à jour le système et désactivez le swap, une exigence classique pour tout nœud Kubernetes. Vérifiez aussi que le pare-feu local n’empêche pas la communication entre nœuds.

sudo apt update && sudo apt upgrade -y
sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab
sudo ufw allow 6443/tcp
sudo ufw allow 8472/udp
sudo ufw allow 10250/tcp
sudo ufw allow from 10.42.0.0/16
sudo ufw allow from 10.43.0.0/16

Les deux dernières règles ouvrent les plages CIDR par défaut des pods et des services K3s. Si vous changez ces plages à l’installation, adaptez le pare-feu en conséquence. Le swap doit rester désactivé en permanence : le kubelet refuse de démarrer correctement si de la mémoire swap est active, car cela fausse ses calculs de pression mémoire et peut provoquer des évictions de pods imprévisibles. Vérifiez enfin que les modules cgroups v2 sont bien actifs avec cat /sys/fs/cgroup/cgroup.controllers : la plupart des distributions récentes les activent par défaut, mais certaines images minimalistes pour conteneurs ou cartes ARM nécessitent une activation manuelle dans la configuration du noyau.

Étape 2 : installer le nœud serveur K3s

L’installation du premier nœud serveur se fait avec un script officiel, servi depuis get.k3s.io. Ce script détecte l’architecture, télécharge le binaire, crée le service systemd et démarre immédiatement le cluster.

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="v1.36.4+k3s1" \
  sh -s - server \
  --write-kubeconfig-mode 644 \
  --cluster-init

L’option --cluster-init prépare le nœud pour une future haute disponibilité avec etcd embarqué, même si vous démarrez avec un seul serveur. Fixer la variable INSTALL_K3S_VERSION évite qu’un futur redéploiement récupère une version différente sur un autre nœud, une source fréquente d’incompatibilités. Vous pouvez aussi passer des options supplémentaires au binaire via la variable INSTALL_K3S_EXEC, par exemple pour désactiver un composant embarqué dont vous n’avez pas besoin (INSTALL_K3S_EXEC="server --disable servicelb"). Le script d’installation configure automatiquement une unité systemd nommée k3s.service, ce qui signifie que le cluster redémarre tout seul après un reboot du serveur, sans intervention manuelle.

Étape 3 : vérifier le cluster et récupérer le kubeconfig

Une fois le service démarré, K3s installe automatiquement un binaire kubectl et génère un fichier de configuration. Vérifiez l’état du nœud directement sur le serveur.

sudo k3s kubectl get nodes -o wide
sudo cat /etc/rancher/k3s/k3s.yaml

Sortie attendue après une installation réussie :

NAME       STATUS   ROLES                       AGE   VERSION
srv-01     Ready    control-plane,etcd,master   45s   v1.36.4+k3s1

Notez également le contenu du fichier /var/lib/rancher/k3s/server/node-token : ce jeton sera nécessaire pour rattacher des agents au cluster à l’étape suivante. Si la colonne STATUS affiche autre chose que Ready après une minute, consultez les journaux du service avec sudo journalctl -u k3s -f : les erreurs les plus fréquentes à ce stade concernent un port déjà occupé ou un pare-feu qui bloque encore le trafic interne entre le plan de contrôle et le kubelet local.

Étape 4 : ajouter des nœuds agents

Sur chaque machine destinée à exécuter des charges applicatives, installez K3s en mode agent en pointant vers l’adresse IP du serveur et en fournissant le jeton récupéré précédemment.

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="v1.36.4+k3s1" \
  K3S_URL=https://192.168.1.10:6443 \
  K3S_TOKEN="K10a1b2c3d4e5f6::server:abcdef123456" \
  sh -

Répétez l’opération sur autant d’agents que nécessaire. Depuis le serveur, un nouveau kubectl get nodes doit afficher chaque agent avec le rôle vide (aucun rôle de contrôle) et le statut Ready après une trentaine de secondes. Profitez-en pour étiqueter vos agents selon leur rôle physique, par exemple kubectl label node agent-01 zone=atelier-nord, ce qui permettra ensuite de contraindre certains pods à s’exécuter uniquement sur des nœuds précis grâce à un nodeSelector, un réflexe utile dès que le cluster mélange du matériel hétérogène.

Étape 5 : configurer kubectl sur votre poste de travail

Piloter le cluster depuis votre machine locale plutôt que depuis le serveur simplifie le quotidien. Copiez le fichier kubeconfig généré et remplacez l’adresse locale par l’IP publique ou privée du serveur.

scp [email protected]:/etc/rancher/k3s/k3s.yaml ~/.kube/k3s-config
sed -i 's/127.0.0.1/192.168.1.10/' ~/.kube/k3s-config
export KUBECONFIG=~/.kube/k3s-config
kubectl get nodes

Si vous gérez plusieurs clusters, fusionnez ce fichier avec votre ~/.kube/config existant à l’aide de kubectl config view --flatten plutôt que de l’écraser. Renommez ensuite le contexte avec kubectl config rename-context default k3s-prod pour éviter de confondre ce cluster K3s avec un cluster Minikube ou AKS déjà présent dans votre configuration locale.

Étape 6 : déployer votre première application

Testons le cluster avec un déploiement simple, comparable à ce que nous avions détaillé dans notre tutoriel de création de cluster Kubernetes avec Minikube, mais ici réparti sur plusieurs nœuds physiques ou virtuels réels.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: demo-web
  template:
    metadata:
      labels:
        app: demo-web
    spec:
      containers:
        - name: nginx
          image: nginx:1.27-alpine
          ports:
            - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: demo-web-svc
spec:
  selector:
    app: demo-web
  ports:
    - port: 80
      targetPort: 80

Appliquez ce manifeste avec kubectl apply -f demo-web.yaml, puis vérifiez la répartition des pods sur vos différents agents avec kubectl get pods -o wide. Le planificateur Kubernetes répartit automatiquement les trois répliques sur les nœuds disponibles pour limiter l’impact d’une panne matérielle isolée. Pour une application réelle, ajoutez systématiquement des sondes readinessProbe et livenessProbe : sans elles, K3s considère un pod comme sain dès que le conteneur démarre, même si l’application interne n’a pas fini son initialisation, ce qui peut envoyer du trafic vers un pod qui n’est pas encore prêt à répondre.

Étape 7 : exposer le service avec Traefik et ServiceLB

K3s déploie Traefik par défaut comme contrôleur d’ingress HTTP/HTTPS, exposé via un service de type LoadBalancer sur les ports 80 et 443. Ce service est pris en charge par ServiceLB (anciennement Klipper LoadBalancer), un mécanisme intégré qui exploite les ports hôtes de chaque nœud pour simuler un équilibreur de charge, sans dépendre d’un fournisseur cloud ni de MetalLB. Créez une ressource Ingress pour router le trafic vers votre application.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-web-ingress
spec:
  rules:
    - host: demo.local
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: demo-web-svc
                port:
                  number: 80

ServiceLB consommant les ports 80 et 443 sur l’ensemble des nœuds, ces ports ne sont plus disponibles pour d’autres services hébergés en HostPort ou NodePort sur le cluster. C’est un point à anticiper si votre infrastructure fait déjà tourner un serveur web sur ces mêmes machines. Pour le HTTPS, installez cert-manager par-dessus le cluster et ajoutez l’annotation cert-manager.io/cluster-issuer sur votre Ingress : Traefik se charge alors de terminer le TLS avec un certificat renouvelé automatiquement, sans configuration manuelle de certificats sur chaque nœud.

Étape 8 : ajouter le stockage persistant

Pour les applications qui doivent conserver des données entre redémarrages, K3s embarque local-path-provisioner, une classe de stockage qui crée des volumes directement sur le disque du nœud hébergeant le pod.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: demo-data
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: local-path
  resources:
    requests:
      storage: 5Gi

Ce mode convient bien à un edge cluster ou un homelab, mais il attache la donnée à un nœud précis : si ce nœud tombe, le volume n’est pas automatiquement répliqué ailleurs. Pour un besoin de réplication réelle, orientez-vous vers Longhorn ou un stockage réseau externe. Notez également que local-path-provisioner utilise par défaut un mode de liaison différé (WaitForFirstConsumer) : le volume physique n’est créé qu’au moment où un pod le réclame réellement, ce qui garantit qu’il apparaît sur le même nœud que le pod plutôt que sur un nœud choisi au hasard.

Étape 9 : sécuriser le cluster

Trois vulnérabilités récentes rappellent pourquoi le durcissement ne doit pas être une option. La CVE-2025-46599 touchait des versions 1.32 de K3s antérieures à 1.32.4-rc1+k3s1, où le port kubelet en lecture seule 10255 pouvait rester exposé sans authentification. La CVE-2026-54250 concernait une traversée de répertoire dans le mécanisme de décompression des instantanés etcd, corrigée avant les versions 1.35.3+k3s1, 1.34.6+k3s1 et 1.33.10+k3s1. Plus critique encore, la CVE-2025-62878, notée 10 sur l’échelle CVSS, affectait toutes les versions de Rancher Local Path Provisioner antérieures à la 0.0.34, soit le composant de stockage par défaut de chaque cluster K3s. Un attaquant authentifié pouvait exploiter cette faille pour lire, écrire ou supprimer des répertoires arbitraires sur l’hôte, en injectant des séquences de traversée de chemin dans le modèle de chemin de la StorageClass, ce qui en faisait un vecteur direct vers le système de fichiers du nœud hébergeant le cluster. Ces failles illustrent l’intérêt d’une approche de durcissement comparable à celle que nous détaillions pour la gestion des secrets Kubernetes : activez le chiffrement au repos des secrets, limitez les rôles RBAC au strict nécessaire, et planifiez une mise à jour rapide dès qu’un correctif de sécurité sort.

sudo k3s kubectl create secret generic db-credentials \
  --from-literal=username=admin \
  --from-literal=password='ChangeMe123!' \
  --dry-run=client -o yaml | kubectl apply -f -

Pensez aussi à restreindre l’accès réseau au port 6443 de l’API server aux seules adresses IP de confiance, en particulier si le serveur est exposé sur une IP publique. Complétez avec un rôle RBAC restreint plutôt que d’accorder cluster-admin par défaut à chaque compte de service applicatif : un pod compromis avec des droits d’administrateur complets peut lire tous les secrets du cluster, alors qu’un rôle limité au namespace applicatif contient l’incident à ce seul périmètre. Avant de déployer une image en production, scannez-la pour repérer les vulnérabilités connues dans ses dépendances système, une pratique que nous détaillions dans notre tutoriel sur le scanner de conteneurs Trivy, parfaitement utilisable en amont d’un déploiement K3s pour bloquer une image vulnérable avant qu’elle n’atteigne le cluster.

Étape 10 : activer la haute disponibilité avec etcd embarqué

Un cluster à un seul serveur reste un point de défaillance unique. Pour passer en haute disponibilité, ajoutez au moins deux serveurs supplémentaires qui rejoignent le premier avec etcd embarqué, ce qui porte le total à trois nœuds serveurs et garantit le quorum.

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="v1.36.4+k3s1" \
  sh -s - server \
  --server https://192.168.1.10:6443 \
  --token "K10a1b2c3d4e5f6::server:abcdef123456"

Avec trois serveurs, le cluster tolère la perte d’un nœud sans interruption de service. En dessous de trois, toute panne d’un serveur casse le quorum etcd et rend l’API indisponible en écriture. La règle à retenir est celle du quorum classique d’un cluster distribué : il faut un nombre impair de serveurs, calculé sur la formule 2n+1, pour tolérer la perte de n nœuds simultanément. Trois serveurs tolèrent une panne, cinq en tolèrent deux, mais un nombre pair de serveurs n’apporte aucune garantie supplémentaire par rapport au nombre impair immédiatement inférieur. Testez le basculement en coupant volontairement un serveur non-leader et en vérifiant que kubectl get nodes continue de répondre normalement depuis les deux serveurs restants.

Étape 11 : sauvegarder et superviser le cluster

K3s intègre un mécanisme de sauvegarde automatique de son datastore etcd embarqué, à planifier avec l’option --etcd-snapshot-schedule-cron. Ces instantanés doivent être copiés hors du serveur, sur un stockage objet ou un second site, pour survivre à une panne matérielle complète.

sudo k3s etcd-snapshot save --name backup-manuel
sudo k3s etcd-snapshot ls
sudo k3s server --cluster-reset \
  --cluster-reset-restore-path=/var/lib/rancher/k3s/server/db/snapshots/backup-manuel

La dernière commande ne doit être exécutée qu’en cas de reconstruction totale du cluster, serveur par serveur, jamais sur un cluster sain. Côté supervision, les métriques exposées par metrics-server suffisent pour un tableau de bord basique, mais une exploitation en production gagnera à s’appuyer sur une pile Prometheus/Grafana externe, à l’image de ce que nous recommandions pour le contrôle réseau zero trust avec Cilium sur Kubernetes, une approche qui reste compatible avec un cluster K3s.

Étape 12 : désinstaller ou migrer proprement

K3s installe des scripts de désinstallation dédiés, séparés pour le rôle serveur et le rôle agent, ce qui évite de laisser des processus orphelins ou des règles iptables résiduelles.

# Sur un nœud serveur
sudo /usr/local/bin/k3s-uninstall.sh

# Sur un nœud agent
sudo /usr/local/bin/k3s-agent-uninstall.sh

Si votre objectif est une migration vers un cluster kubeadm classique ou vers un service managé comme AKS sur Azure, exportez vos manifestes avec kubectl get all --all-namespaces -o yaml avant de désinstaller, afin de rejouer la configuration sur la nouvelle plateforme. Gardez à l’esprit que les ressources qui dépendent d’un contrôleur spécifique à K3s, comme les volumes local-path ou les services ServiceLB, ne se recréent pas automatiquement à l’identique ailleurs : prévoyez de les remplacer par l’équivalent natif de la plateforme cible avant de rejouer les manifestes.

K3s face à k0s et MicroK8s : quel choix pour l’edge computing

K3s n’est pas la seule distribution Kubernetes légère du marché. k0s, porté par Mirantis, et MicroK8s, porté par Canonical, ciblent des besoins proches avec des choix techniques différents.

CritèreK3sk0sMicroK8s
ÉditeurSUSE / RancherMirantisCanonical
PackagingBinaire uniqueBinaire uniquePaquet snap
Datastore par défautSQLite (via Kine)SQLite (mono-nœud)dqlite
Datastore HAetcd embarqué ou externeetcd embarqué ou externedqlite intégré
Support ARMv7 (32 bits)OuiOuiNon
Ingress par défautTraefikAucun (au choix)Nginx (addon)
Certification CNCFOuiOuiOui

En pratique, k0s se distingue par une empreinte mémoire légèrement inférieure et une absence de composants imposés, ce qui séduit les équipes qui veulent choisir chaque brique elles-mêmes. MicroK8s profite du modèle snap de Canonical pour des mises à jour atomiques, au prix d’une empreinte disque plus lourde et de l’absence de support ARM 32 bits. K3s reste le choix le plus documenté et le plus répandu sur Raspberry Pi et cartes ARM, avec un écosystème de tutoriels et une intégration native à Rancher pour la gestion multi-cluster, comme le détaille la documentation de Rancher Manager pour piloter plusieurs clusters K3s depuis une seule interface. Si votre priorité absolue est l’empreinte mémoire la plus basse possible sur du matériel très contraint, testez k0s en parallèle avant de choisir. Si vous exploitez déjà une infrastructure Ubuntu standardisée avec des mises à jour automatisées via snap, MicroK8s s’intègre plus naturellement dans vos outils existants.

Pièges courants à éviter

  • Ports fermés entre nœuds : oublier d’ouvrir 6443/tcp, 8472/udp ou 10250/tcp bloque silencieusement la jonction des agents.
  • Versions dépareillées : installer un agent avec une version K3s différente du serveur crée des incompatibilités d’API difficiles à diagnostiquer. Fixez toujours INSTALL_K3S_VERSION.
  • SQLite en production critique : garder le datastore SQLite mono-nœud pour une charge de production sensible revient à accepter un point de défaillance unique sans le savoir.
  • Jeton de cluster partagé : réutiliser le même K3S_TOKEN entre plusieurs clusters distincts expose chacun d’eux si l’un des jetons fuite.
  • Oublier la sauvegarde etcd : sans planification de --etcd-snapshot-schedule-cron et sans copie hors site, une panne disque du serveur peut effacer tout l’état du cluster.
  • Ports 80/443 monopolisés : ServiceLB réserve ces ports sur tous les nœuds, ce qui entre en conflit avec un serveur web déjà installé sur la même machine.
  • Ignorer les correctifs de sécurité : les CVE touchant K3s et Local Path Provisioner sont corrigées rapidement, mais seulement si vous mettez à jour.
  • Nombre pair de serveurs en haute disponibilité : passer de un à deux serveurs n’apporte aucune tolérance de panne supplémentaire, puisque le quorum etcd exige un nombre impair de nœuds pour trancher en cas de désaccord.

Dépannage : problèmes fréquents et solutions

Ce tableau rassemble les incidents les plus fréquemment rencontrés lors des premières semaines d’exploitation d’un cluster K3s, qu’il s’agisse d’un déploiement solo sur Raspberry Pi ou d’un cluster multi-serveurs en production. La majorité de ces symptômes se règlent en moins de cinq minutes une fois la cause identifiée.

SymptômeCause probableSolution
Nœud agent reste NotReadyCNI Flannel non initialisé ou port 8472/udp bloquéVérifier le pare-feu et relancer systemctl restart k3s-agent
“connection refused” sur le port 6443Service k3s non démarré ou pare-feu bloquantContrôler systemctl status k3s et l’ouverture du port
Traefik ne démarre pasPort 80 ou 443 déjà utilisé par un autre serviceLibérer le port ou désactiver Traefik avec --disable traefik
Pods en CrashLoopBackOffMémoire insuffisante sur l’agentAugmenter la RAM ou définir des limites de ressources plus basses
kubectl : “server refused connection”kubeconfig pointant vers 127.0.0.1 depuis un poste distantRemplacer l’IP locale par l’IP réelle du serveur
Agent ne rejoint pas le clusterJeton K3S_TOKEN invalide ou expiréRégénérer le jeton depuis /var/lib/rancher/k3s/server/node-token
PVC reste en Pendinglocal-path-provisioner non déployé ou désactivéVérifier le pod dans le namespace kube-system
Résolution DNS interne en échecPod CoreDNS non démarréRedémarrer le déploiement coredns dans kube-system
Quorum etcd perdu après redémarrageMoins de trois serveurs actifs simultanémentRestaurer un troisième serveur ou repartir d’un instantané etcd
Certificats internes expirésCertificats K3s valides un an, non renouvelésRedémarrer le service k3s, qui renouvelle les certificats au démarrage

Si un symptôme persiste après ces vérifications, consultez systématiquement les journaux détaillés avec sudo journalctl -u k3s -u k3s-agent --since "10 min ago" avant d’envisager une réinstallation complète : la grande majorité des blocages proviennent d’une règle réseau manquante plutôt que d’une corruption du cluster.

Astuces avancées pour la production

Une fois le cluster stable, plusieurs ajustements améliorent sa tenue en production. Remplacez Flannel par Cilium si vous avez besoin de politiques réseau granulaires ou d’observabilité eBPF, en désactivant le CNI par défaut avec --flannel-backend=none --disable-network-policy à l’installation. Migrez le datastore de SQLite vers PostgreSQL dès que le cluster dépasse une poignée de nœuds actifs, via --datastore-endpoint, pour éviter les verrous d’écriture propres à SQLite sous forte charge. Pour les environnements air-gapped, K3s propose des archives d’images et un mode d’installation hors ligne complet, utile pour les sites industriels sans accès internet direct. Enfin, associez le cluster à un contrôleur GitOps comme Flux ou Argo CD pour synchroniser automatiquement les manifestes stockés dans un dépôt Git, une pratique qui réduit les dérives de configuration entre plusieurs clusters K3s déployés sur des sites distincts.

Sur un cluster partagé par plusieurs équipes ou plusieurs clients, imposez des ResourceQuota et des LimitRange par namespace dès la mise en service, plutôt qu’en réaction à un incident de surconsommation. Un seul pod mal configuré, sans limite de mémoire définie, peut saturer un agent entier et provoquer l’éviction de tous les autres pods qui y tournaient. Enfin, si votre cluster tourne sur du matériel ARM en extérieur ou dans un environnement industriel, surveillez la température des cartes : un throttling thermique du CPU dégrade silencieusement les performances du plan de contrôle bien avant qu’une alerte Kubernetes classique ne se déclenche.

Projet complet : cluster K3s à trois nœuds pour une API web

Pour valider l’ensemble des étapes précédentes, voici l’architecture d’un projet réaliste : un serveur K3s et deux agents, hébergeant une API web avec base de données persistante et exposition HTTPS.

  1. Provisionnez trois machines (ou VM) : srv-01 en serveur, agent-01 et agent-02 en agents, selon les étapes 1 à 4.
  2. Installez local-path-provisioner (par défaut) et créez un PVC de 5 Gi pour la base de données applicative.
  3. Déployez un pod PostgreSQL avec ce volume monté, protégé par un Secret Kubernetes pour les identifiants.
  4. Déployez trois répliques de l’API applicative, connectées à PostgreSQL via une variable d’environnement issue du Secret.
  5. Exposez l’API via un Ingress Traefik, avec un certificat TLS géré par cert-manager pour le HTTPS.
  6. Planifiez une sauvegarde etcd quotidienne et copiez les instantanés vers un stockage objet externe.
  7. Ajoutez des ResourceQuota sur le namespace applicatif pour éviter qu’une fuite mémoire côté API ne fasse tomber les autres services du cluster.
  8. Documentez la procédure de restauration en la testant une fois sur un cluster de rechange, avant d’en avoir réellement besoin en urgence.

Ce montage tient sur trois Raspberry Pi 4 de 4 Go ou sur trois petites instances cloud, pour un coût mensuel très inférieur à un cluster managé équivalent, tout en restant 100 % compatible avec les manifestes Kubernetes standards.

apiVersion: v1
kind: ResourceQuota
metadata:
  name: api-quota
  namespace: demo-api
spec:
  hard:
    requests.cpu: "2"
    requests.memory: 2Gi
    limits.cpu: "4"
    limits.memory: 4Gi

Une fois ces six briques en place, le cluster répond aux critères d’un déploiement de petite production : redondance du plan de contrôle, données persistantes, chiffrement en transit, sauvegardes régulières et garde-fous de consommation par équipe. C’est exactement l’ossature que l’on retrouve derrière la plupart des déploiements K3s en environnement industriel ou associatif, où le budget matériel reste limité mais où la fiabilité du service ne peut pas être négociée.

Foire aux questions

K3s est-il compatible avec tous les manifestes Kubernetes standards ?
Oui. K3s est certifié conforme par la CNCF, ce qui garantit la compatibilité avec l’API Kubernetes classique, y compris Helm, comme nous le montrions dans notre tutoriel de déploiement avec Helm.

Peut-on faire tourner K3s sur un Raspberry Pi ?
Oui, à condition d’utiliser un modèle avec un processeur 64 bits (Pi 4 ou Pi 5) et un noyau 64 bits, avec 2 Go de RAM au minimum pour un nœud serveur.

Faut-il forcément passer par etcd pour la haute disponibilité ?
Non. K3s accepte aussi un datastore externe (PostgreSQL, MySQL, MariaDB ou etcd externe) via --datastore-endpoint, une option souvent plus simple à superviser que trois nœuds etcd embarqués.

K3s est-il adapté à un usage en entreprise, hors edge ?
Oui. De nombreuses équipes l’utilisent pour des clusters de développement, des pipelines d’intégration continue ou des environnements de test, avant même de l’envisager pour la production.

Comment migrer d’un cluster Minikube vers K3s ?
Exportez vos manifestes avec kubectl get all -o yaml depuis Minikube, puis appliquez-les tels quels sur le cluster K3s : l’API étant identique, aucune conversion n’est nécessaire.

Peut-on désactiver Traefik au profit d’un autre ingress ?
Oui, en ajoutant --disable traefik lors de l’installation du serveur, puis en déployant Nginx Ingress ou tout autre contrôleur compatible.

Quelle est la fréquence de sortie des mises à jour de sécurité de K3s ?
Le projet suit de près les releases de Kubernetes amont et publie des correctifs dans un délai de quelques jours à quelques semaines après la divulgation d’une CVE, comme l’ont montré les correctifs 2025-2026 sur le kubelet et le composant Local Path Provisioner.

K3s convient-il pour un cluster multi-sites réparti sur plusieurs villes ?
C’est possible avec un datastore externe et une latence réseau maîtrisée entre sites, mais un etcd embarqué réparti sur des sites distants reste risqué : privilégiez un serveur par site avec une base de données externe centralisée si la latence dépasse quelques dizaines de millisecondes.

Quelle différence entre K3s et K3d ?
K3d n’est pas une distribution Kubernetes à part entière : c’est un outil qui fait tourner des nœuds K3s à l’intérieur de conteneurs Docker, pratique pour simuler un cluster multi-nœuds complet sur une seule machine de développement sans provisionner de vraies machines virtuelles.