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.36.2+k3s1 (channel stable, juin 2026). K3s embarque Kubernetes v1.36, containerd v2.3.2-k3s2, Traefik v3.7.4, CoreDNS 1.14.4 et metrics-server v0.8.1.

Le stockage par défaut d'un serveur unique est SQLite, pas etcd : le fichier state.db vit dans /var/lib/rancher/k3s/server/db/. etcd n'entre en jeu que pour un cluster en haute disponibilité.

Ce que vous allez apprendre

Le guide suit l'ordre d'un déploiement réel : comprendre ce que contient le binaire, installer un serveur, le configurer par fichier, puis lui rattacher des agents. Les parties haute disponibilité et dépannage visent un cluster destiné à durer, pas une simple maquette.

• 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

Quand choisir K3s

Ces trois distributions ne répondent pas au même besoin : K3s installe un service système sur la machine, Minikube et Kind encapsulent le cluster dans une VM ou des conteneurs Docker. La ligne Persistance tranche la plupart des cas, un cluster jetable de CI n'ayant pas les mêmes exigences qu'un homelab qui doit redémarrer seul après une coupure.

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

Savoir ce que K3s embarque évite deux erreurs classiques : chercher un composant qui n'existe pas comme processus séparé, et réinstaller un add-on déjà présent. Les trois points suivants détaillent le contenu du binaire, les composants activés d'office et ceux que vous pouvez retirer.

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

K3s tolère des machines modestes, mais les chiffres ci-dessous couvrent le control plane et les composants système, pas vos applications. Deux points bloquent le plus souvent une installation multi-node : la mémoire d'un server qui exécute aussi des workloads, et les ports filtrés entre les machines.

Ressources minimales

Ces valeurs permettent à K3s de démarrer et de tenir à vide. Un server consomme davantage dès qu'il héberge des pods applicatifs en plus du control plane, et sur un cluster à trois serveurs l'etcd intégré ajoute sa propre empreinte mémoire tout en réclamant un disque rapide.

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

K3s s'installe sur toute distribution Linux dotée de systemd ou d'OpenRC, le script d'installation détectant lequel est présent pour y déposer son service. Sur les cartes ARM de type Raspberry Pi, les cgroups mémoire doivent être activés dans les paramètres de démarrage du noyau, faute de quoi l'agent échoue au lancement des conteneurs.

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

Ports réseau

Le 6443 est le seul port strictement obligatoire, c'est celui de l'API server auquel se connectent les agents et kubectl. Le 8472/UDP ne sert qu'au réseau Flannel en mode VXLAN, donc uniquement en multi-node, et les 2379-2380 n'apparaissent que sur les serveurs d'un cluster HA avec etcd intégré.

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

   # Télécharger le script officiel, l'inspecter, puis l'exécuter
   curl -sfL https://get.k3s.io -o k3s-install.sh
   less k3s-install.sh
   sh k3s-install.sh

   Décortiquons cette commande

   • curl -sfL https://get.k3s.io -o k3s-install.sh : télécharge le script d'installation dans un fichier
     • -s : mode silencieux (pas de barre de progression)
     • -f : échoue proprement si le serveur renvoie une erreur
     • -L : suit les redirections
     • -o k3s-install.sh : enregistre le script au lieu de le piper directement dans sh
   • less k3s-install.sh : inspectez le script avant de l'exécuter (ne jamais exécuter à l'aveugle un script distant)
   • sh k3s-install.sh : exécute le script une fois relu

   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.36.2+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

Ces chemins n'existent que sur un server : un agent n'a ni kubeconfig ni node-token, il ne conserve que sa configuration locale et ses conteneurs. Le config.yaml est le seul fichier de la liste que K3s ne crée pas, c'est à vous de le déposer avant l'installation.

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 : INSTALL_K3S_EXEC="--disable=traefik" sh k3s-install.sh, le script ayant été téléchargé au préalable
2. Fichier config.yaml : plus propre, versionnable, facile à modifier

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

Créez ce fichier avant de lancer le script d'installation : K3s l'appliquera automatiquement au premier démarrage. Si vous le modifiez ensuite, redémarrez le service avec sudo systemctl restart k3s pour qu'il soit relu.

Profil développement (minimal)

Ce profil vise le poste de travail : le kubeconfig devient lisible sans sudo, et les deux composants qui réservent des ports sur l'hôte sont retirés. Désactiver Traefik et ServiceLB libère les ports 80 et 443, souvent déjà occupés par un serveur web local.

/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

Traefik disparaît au profit d'un autre Ingress controller, mais ServiceLB reste en place : c'est lui qui attribue une adresse externe aux Services sans équipement dédié. Les entrées tls-san ajoutent le nom et l'IP au certificat de l'API server, sans quoi kubectl refuse la connexion depuis un autre poste.

/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

La ligne cluster-init: true ne concerne que le premier serveur : elle fait basculer le datastore de SQLite vers l'etcd intégré. Les serveurs suivants rejoignent ce cluster et ne doivent surtout pas la reprendre, sous peine de créer un second cluster indépendant du premier.

/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

K3s ne relit config.yaml qu'au démarrage du service. La vérification se lit à l'envers des habitudes : vous cherchez l'absence des pods traefik et svclb dans kube-system.

# 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 -o k3s-install.sh
   sh k3s-install.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 -o k3s-install.sh
   K3S_URL=https://SERVER_IP:6443 K3S_TOKEN=TOKEN sh k3s-install.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 -o k3s-install.sh
   K3S_URL=https://192.168.1.10:6443 K3S_TOKEN=K10abcd1234::server:xyz789 sh k3s-install.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.36.2+k3s1
   # agent1     Ready    <none>          2m    v1.36.2+k3s1
   # agent2     Ready    <none>          1m    v1.36.2+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

Le bloc mirrors détourne les requêtes vers un autre endpoint sans toucher à vos manifests : les images restent référencées en docker.io/... alors que containerd va les chercher ailleurs. C'est le mécanisme à retenir pour un cache local ou un site sans accès direct à Internet.

/etc/rancher/k3s/registries.yaml

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

Registry privé avec authentification

Deux blocs interviennent, avec des rôles distincts : mirrors indique où aller, configs fournit les identifiants et le certificat CA à présenter. La clé de configs doit reprendre le nom du registry à l'identique, port compris, sinon l'authentification n'est jamais appliquée et le pull échoue en 401.

/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)

Un endpoint en http:// fait transiter les identifiants et les couches d'image en clair sur le réseau. Réservez ce montage à un registry de laboratoire, et gardez insecure_skip_verify pour le seul cas d'un certificat auto-signé en HTTPS.

/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)

La haute disponibilité porte ici sur le control plane, pas sur vos applications : elle garantit que l'API server reste joignable quand une machine tombe. Tout le choix se joue sur le datastore, puisque c'est lui qu'il faut répliquer entre les serveurs.

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 -o k3s-install.sh
   sh k3s-install.sh 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 -o k3s-install.sh
   sh k3s-install.sh 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.

Récupérer le kubeconfig

K3s écrit son fichier de connexion dans /etc/rancher/k3s/k3s.yaml dès l'installation du serveur. C'est lui que kubectl lit pour savoir à quel cluster parler et avec quels certificats client s'authentifier. Son format est celui de n'importe quel cluster Kubernetes, et le champ décisif est server :

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <certificat de l'autorité>
    server: https://127.0.0.1:6443
  name: default
contexts:
- context:
    cluster: default
    user: default
  name: default
current-context: default
kind: Config
users:
- name: default
  user:
    client-certificate-data: <certificat client>
    client-key-data: <clé privée>

Sur le serveur lui-même, exportez la variable KUBECONFIG pour que kubectl trouve ce fichier :

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl get nodes
# Les nodes doivent tous afficher "Ready"

Pour piloter le cluster depuis votre poste, copiez le fichier puis remplacez 127.0.0.1 par l'adresse réelle du serveur. Sans cette substitution, kubectl interrogerait votre propre machine et échouerait :

scp root@192.168.1.10:/etc/rancher/k3s/k3s.yaml ~/.kube/k3s.yaml
sed -i 's|127.0.0.1|192.168.1.10|' ~/.kube/k3s.yaml
export KUBECONFIG=~/.kube/k3s.yaml
kubectl get nodes

Ce fichier contient une clé d'administrateur

k3s.yaml embarque la clé privée d'un compte qui a tous les droits sur le cluster. K3s le crée en 0600, lisible par root seul. L'option --write-kubeconfig-mode 644 l'ouvre à tous les utilisateurs de la machine : commode en lab, à proscrire en production. Ne le versionnez jamais.

Vérifier que tout fonctionne

Dans kube-system, l'état Completed est normal : ce sont les Jobs Helm qui déploient Traefik et les autres add-ons, et qui ne s'exécutent qu'une fois.

# 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

Ce test valide la chaîne complète, du téléchargement de l'image par containerd jusqu'à l'exposition réseau. Le type NodePort attribue un port au hasard entre 30000 et 32767, d'où la lecture obligatoire de kubectl get svc avant le curl.

# 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

Exposer un service avec ServiceLB

Sur un cloud, un Service de type LoadBalancer demande au fournisseur de créer un équilibreur de charge. Sur une machine nue, personne ne répond à cette demande et le service resterait en attente indéfiniment. K3s comble ce vide avec ServiceLB (le composant klipper-lb), activé par défaut.

Le mécanisme est simple : à la création d'un Service LoadBalancer, ServiceLB lance un DaemonSet de pods svclb-* qui réservent le port demandé sur chaque nœud et relaient le trafic vers vos pods.

kubectl create deployment web --image=nginx:alpine
kubectl expose deployment web --type=LoadBalancer --port=8080 --target-port=80 --name=web-lb

kubectl get svc web-lb
# NAME     TYPE           CLUSTER-IP     EXTERNAL-IP                        PORT(S)          AGE
# web-lb   LoadBalancer   10.43.183.85   172.29.0.2,172.29.0.3,172.29.0.4   8080:30642/TCP   4s

La colonne EXTERNAL-IP liste les adresses de tous les nœuds : le service répond sur chacun d'eux, sans équilibreur externe. Les pods qui réalisent ce tour de passe-passe vivent dans kube-system :

kubectl get pods -n kube-system -l svccontroller.k3s.cattle.io/svcname=web-lb
# NAME                          READY   STATUS    NODE
# svclb-web-lb-42d9ba67-67vj2   1/1     Running   server1
# svclb-web-lb-42d9ba67-szcjj   1/1     Running   agent1
# svclb-web-lb-42d9ba67-hkhn6   1/1     Running   agent2

Pourquoi un LoadBalancer sur le port 80 reste bloqué

ServiceLB réserve le port demandé directement sur l'hôte (hostPort). Or Traefik, installé par défaut, occupe déjà les ports 80 et 443 avec ses propres pods svclb-traefik. Un Service LoadBalancer exposé sur le port 80 restera donc en <pending>, ses pods svclb figés en Pending, sans message d'erreur explicite.

Deux issues : exposer sur un autre port (le 8080 ci-dessus), ou utiliser un Ingress Traefik au lieu d'un Service LoadBalancer, ce qui est la voie normale pour du trafic HTTP.

Nettoyer

Supprimer un Deployment n'emporte pas le Service créé séparément : les deux objets sont indépendants, d'où les deux commandes.

kubectl delete deployment nginx web
kubectl delete svc nginx web-lb

Outils intégrés

K3s embarque plusieurs outils accessibles via le binaire.

kubectl

La sous-commande k3s kubectl utilise directement le kubeconfig du serveur : elle fonctionne sans variable KUBECONFIG ni copie dans ~/.kube, à condition de la lancer en root.

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

crictl (runtime)

crictl s'adresse directement à containerd et voit donc des conteneurs que kubectl masque, dont les conteneurs d'infrastructure de chaque pod. C'est l'outil qui reste exploitable quand l'API server ne répond plus.

# 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)

L'option -n k8s.io n'est pas facultative : containerd cloisonne ses données par namespace et toutes les images de Kubernetes vivent dans k8s.io. Sans elle, la liste revient vide.

# 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

Le diagnostic commence par le service systemd, jamais par Kubernetes : si k3s.service n'est pas actif, aucune commande kubectl n'aboutit et le seul message obtenu mentionne un refus de connexion sur le port 6443. Une fois le service confirmé, les événements et l'état des pods de kube-system prennent le relais.

Commandes de diagnostic

Ces commandes suivent cet ordre : état du service, état du cluster, puis événements récents. journalctl -u k3s -f est la seule à parler en cas de configuration invalide, puisque K3s refuse alors de démarrer et n'expose aucune API pour le signaler.

# 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

Ces symptômes se rangent en trois familles : le service qui ne tourne pas, un agent qui n'arrive pas à s'authentifier, et un composant interne encore indisponible. Face à un agent qui ne rejoint pas le cluster, vérifiez dans cet ordre le token, l'adresse du serveur, puis l'ouverture du port 6443.

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

Redémarrer ou arrêter K3s

K3s tourne comme un service systemd, installé sous le nom k3s sur un serveur et k3s-agent sur un agent. Redémarrer le service relit la configuration (config.yaml) sans toucher à vos manifestes ni aux données du cluster :

# Sur un serveur
sudo systemctl restart k3s

# Sur un agent
sudo systemctl restart k3s-agent

# Suivre le démarrage et repérer une erreur de configuration
sudo journalctl -u k3s -f

Quand le service refuse de s'arrêter, ou que des conteneurs restent accrochés après un stop, le script k3s-killall.sh fait le ménage : il arrête K3s, tue tous les conteneurs qu'il gérait et nettoie les règles réseau. Il ne désinstalle rien et ne supprime aucune donnée, le cluster repart tel quel au prochain démarrage.

sudo /usr/local/bin/k3s-killall.sh
sudo systemctl start k3s

Réinitialiser K3s

Ces scripts sont générés à l'installation et diffèrent selon le rôle de la machine. Ils suppriment le binaire, le service et les données du cluster, base SQLite comprise : sans sauvegarde préalable, rien n'est récupérable.

# 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 (script téléchargé puis exécuté)
curl -sfL https://get.k3s.io -o k3s-install.sh
sh k3s-install.sh

Sauvegarder etcd (cluster HA)

Ces commandes ne valent que pour un cluster en HA : un serveur unique stocke son état dans SQLite et ne répond pas à etcd-snapshot. La restauration se fait service arrêté, avec --cluster-reset, ce qui reconstruit le cluster à partir du seul nœud restauré.

# 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

Trois angles ressortent d'un cluster K3s exploité dans la durée : limiter l'exposition de l'API server, prévoir la panne d'un serveur, et empêcher un pod de saturer son nœud. Ces points supposent un cluster déjà fonctionnel, ils s'ajoutent à l'installation et ne la remplacent pas.

Sécurité

L'exposition du port 6443 est le point critique : qui l'atteint avec le kubeconfig admin contrôle tout le cluster. Le node-token mérite le même traitement qu'un mot de passe, puisqu'il suffit à rattacher une machine et donc à faire exécuter des pods sur votre cluster.

• 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

La règle du nombre impair de serveurs découle du quorum etcd décrit plus haut. La sauvegarde reste l'élément le plus souvent oublié : sans snapshot, la perte du quorum impose de reconstruire le cluster et de réappliquer tous les manifests à la main.

• 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

Sans requests, le scheduler ignore ce que consomment vos pods et remplit les nœuds jusqu'à l'éviction. Sur un cluster K3s où le server exécute aussi des workloads, une application gourmande emporte le control plane avec elle.

• 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

Ces sept points couvrent le trajet de l'installation à l'exploitation. Le plus contre-intuitif reste le datastore : par défaut, K3s écrit dans SQLite, et seul --cluster-init fait apparaître etcd.

1. K3s = Kubernetes complet dans un binaire de ~70 MB, idéal pour edge/IoT/homelab
2. Installation par script officiel téléchargé puis inspecté (curl -sfL https://get.k3s.io -o k3s-install.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

Le cluster tourne, le travail se déplace vers ce qu'on y déploie. Les deux premiers liens traitent des objets Kubernetes et de leur packaging avec Helm ; Minikube et Kind viennent ensuite, à retenir pour un poste de développement ou une chaîne de CI, pas pour un cluster durable.

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

La documentation officielle fait référence pour la liste complète des options de config.yaml, qui s'enrichit à chaque version mineure. Les releases GitHub indiquent la version de Kubernetes embarquée dans chaque build et les correctifs de sécurité appliqués au binaire.

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

×

📖 Voir la documentation →