k0s : déployer un cluster Kubernetes léger et certifié

k0s vous permet de déployer un cluster Kubernetes certifié CNCF en quelques minutes. Un seul binaire, zéro dépendance externe, et un plan de contrôle isolé des workloads par défaut. Ce guide vous accompagne du premier nœud jusqu'à un cluster multi-nœuds prêt à être étendu vers de la haute disponibilité.

Prérequis : 1 à N serveurs Linux (Ubuntu 22.04+), accès SSH avec clé, et kubectl installé sur votre poste.

Version testée

Ce guide a été validé avec k0s v1.35.2+k0s.0 et k0sctl v0.19.4. Les commandes peuvent varier selon votre version, consultez les releases officielles pour les dernières informations.

Ce que vous allez apprendre

• Comprendre l'architecture k0s : contrôleur isolé, binaire unique, par défaut pas de kubelet sur le control plane
• Déployer un cluster avec k0sctl (1 contrôleur + 2 workers)
• Configurer le réseau : kube-router, Calico ou CNI personnalisé
• Gérer le cycle de vie : ajout/retrait de nœuds, mises à jour, sauvegarde/restauration
• Diagnostiquer les problèmes courants : logs, statuts, connectivité

k0s vs autres solutions

Avant de choisir k0s, comparez avec les autres options :

Critère	k0s	k3s	kubeadm	Kubespray	RKE2
Type	Distribution	Distribution	Bootstrap tool	Playbooks Ansible	Distribution
Orientation	Edge, prod, CI	Edge, IoT, dev	Standard upstream	Prod, multi-cloud	Enterprise, sécurité
Installation	k0sctl (YAML)	Script unique	Commandes	Ansible	Script
CNI défaut	kube-router	Flannel	Aucun	Configurable	Canal
HA native	✅ Multi-controller	✅ Multi-server	Manuel	✅ Ansible	✅ Intégrée
Profil CIS	Manuel	Manuel	Manuel	Selon config	✅ Intégré
Cas d'usage	Edge, CI/CD, prod	Edge, IoT, dev	Bare metal, formation	Prod automatisée	Conformité, prod

Glissez pour voir

Attention aux comparaisons

kubeadm et Kubespray ne sont pas des distributions comme k0s/k3s, ce sont des outils de provisioning. kubeadm bootstrap un cluster standard, Kubespray automatise ce processus via Ansible. Les exigences système dépendent fortement de la charge et des composants déployés.

Quand choisir k0s ?

Choisissez k0s si vous voulez :

• Un control plane sans workloads (isolation pure)
• Un déploiement déclaratif avec un seul fichier YAML (k0sctl.yaml)
• Des mises à jour in-place gérées par k0sctl
• Un cluster léger pour l'edge ou le CI/CD

Architecture k0s

k0s adopte une philosophie différente des autres distributions : le control plane est 100% isolé.

Ce que k0s intègre dans son binaire unique

Tous les composants ci-dessous sont embarqués dans l'exécutable : il n'y a rien à installer avec le gestionnaire de paquets, pas même containerd. C'est ce qui rend l'installation reproductible sur des distributions différentes, et c'est aussi ce qui explique la taille du binaire.

Composant	Rôle
kube-apiserver	API Kubernetes
kube-controller-manager	Gestion des contrôleurs
kube-scheduler	Placement des pods
etcd	Base de données clé/valeur
kube-router	CNI par défaut (ou Calico)
containerd	Runtime de conteneurs
CoreDNS	DNS interne du cluster
konnectivity-server	Tunneling control plane ↔ workers

Glissez pour voir

Contrôleur vs Worker

Le schéma ci-dessous oppose les deux rôles : à gauche le contrôleur, qui lance les composants du plan de contrôle comme de simples processus supervisés par k0s ; à droite les workers, seuls à faire tourner kubelet et containerd, donc seuls à exécuter des conteneurs.

Architecture par défaut

Par défaut, le contrôleur k0s n'exécute ni kubelet ni moteur de conteneurs. Tous les composants du control plane tournent comme des processus supervisés, pas comme des pods. CoreDNS, les pods CNI et Metrics Server s'exécutent sur les workers.

Il existe un mode --enable-worker qui permet à un contrôleur de participer également comme worker (avec des taints par défaut). Ce guide n'utilise pas ce mode.

Installation de k0sctl

k0sctl est l'outil CLI officiel pour déployer et gérer les clusters k0s. Il se connecte en SSH aux nœuds et automatise l'installation.

Linux

Téléchargez le binaire et le fichier de sommes publié dans la même release, vérifiez, puis seulement ensuite installez dans le PATH.

cd "$(mktemp -d)"
K0SCTL_VERSION=v0.19.4
BASE=https://github.com/k0sproject/k0sctl/releases/download/${K0SCTL_VERSION}

# Binaire + sommes officielles publiées avec la release
curl -sSLf -O "${BASE}/k0sctl-linux-amd64"
curl -sSLf -O "${BASE}/checksums.txt"

# Vérification obligatoire : doit afficher "k0sctl-linux-amd64: OK"
sha256sum --ignore-missing --check checksums.txt

# Installation seulement si la vérification a réussi
sudo install -m 0755 k0sctl-linux-amd64 /usr/local/bin/k0sctl

# Vérifier l'installation
k0sctl version

--ignore-missing évite les erreurs sur les six autres architectures listées dans checksums.txt. Si la sortie affiche FAILED, ne rendez pas le fichier exécutable : le téléchargement est corrompu ou altéré.

macOS

# Avec Homebrew
brew install k0sproject/tap/k0sctl

# Vérifier l'installation
k0sctl version

Windows

# Télécharger depuis GitHub Releases
# https://github.com/k0sproject/k0sctl/releases

# Ou avec Scoop
scoop bucket add k0sproject https://github.com/k0sproject/scoop-k0s.git
scoop install k0sctl

Vérification :

k0sctl version
# k0sctl v0.19.4

Préparer les serveurs

Avant de déployer, préparez vos serveurs Linux.

Configuration minimale

Ces valeurs couvrent le plancher de démarrage, pas une charge applicative. Le contrôleur héberge etcd, très sensible à la latence disque : sur un stockage lent, le cluster démarre mais les élections etcd finissent par échouer sous charge. Comptez large dès que vous dépassez quelques dizaines de pods.

Rôle	RAM min	CPU	Disque
Controller	1 Go	1 vCPU	20 Go
Worker	1 Go	1 vCPU	20 Go

Glissez pour voir

Prérequis sur chaque serveur

1. Système d'exploitation supporté

   Ubuntu 22.04+, Debian 11+, Rocky Linux 8+, ou Amazon Linux 2.

2. Accès SSH avec clé

   # Depuis votre poste de travail
   ssh-copy-id user@ip-du-serveur

3. Utilisateur avec sudo sans mot de passe

   # Sur le serveur
   echo "kube ALL=(ALL) NOPASSWD:ALL" | sudo tee /etc/sudoers.d/kube

4. Ports ouverts

   Port	Usage	Direction
   22	SSH	k0sctl → tous les nœuds
   6443	API Kubernetes	workers → controller
   8132	Konnectivity	workers → controller
   9443	Controller join	controllers → controller
   10250	Kubelet	controller → workers

   Glissez pour voir

   Le CNI ajoute ses propres ports (ex: 8472/UDP pour VXLAN). Consultez la documentation de votre CNI.

Choisissez votre CNI dès le départ

Une fois le cluster initialisé, changer de provider réseau implique un redéploiement complet du cluster. Ce n'est pas un simple paramètre à modifier. Réfléchissez avant de choisir entre kube-router (défaut), Calico, ou un CNI custom.

Premier déploiement avec k0sctl

Le déploiement se fait depuis votre poste, pas depuis les serveurs : k0sctl ouvre les connexions SSH, dépose le binaire k0s sur chaque nœud et enchaîne les phases d'installation. L'opération est idempotente, relancer k0sctl apply sur un cluster déjà en place ne le recrée pas. Trois étapes suffisent : décrire le cluster, l'appliquer, récupérer le kubeconfig.

Créer le fichier k0sctl.yaml

k0sctl utilise un fichier YAML déclaratif pour définir le cluster :

k0sctl.yaml

apiVersion: k0sctl.k0sproject.io/v1beta1
kind: Cluster
metadata:
  name: mon-cluster-k0s
spec:
  hosts:
    # Controller (control plane)
    - ssh:
        address: 192.168.122.10
        user: kube
        port: 22
        keyPath: ~/.ssh/id_ed25519
      role: controller

    # Worker 1
    - ssh:
        address: 192.168.122.20
        user: kube
        port: 22
        keyPath: ~/.ssh/id_ed25519
      role: worker

    # Worker 2
    - ssh:
        address: 192.168.122.21
        user: kube
        port: 22
        keyPath: ~/.ssh/id_ed25519
      role: worker

  k0s:
    version: v1.35.2+k0s.0
    config:
      apiVersion: k0s.k0sproject.io/v1beta1
      kind: ClusterConfig
      metadata:
        name: mon-cluster
      spec:
        api:
          address: 192.168.122.10
          sans:
            - 192.168.122.10
        network:
          provider: kuberouter  # ou "calico"
          podCIDR: 10.244.0.0/16
          serviceCIDR: 10.96.0.0/12

Déployer le cluster

k0sctl apply déroule des phases nommées et s'arrête à la première qui échoue, en indiquant le nœud concerné. Comptez environ une minute pour trois nœuds sur un réseau local.

# Appliquer la configuration
k0sctl apply --config k0sctl.yaml

Sortie attendue :

⣿⣿ ...
INFO ==> Running phase: Connect to hosts
INFO [ssh] 192.168.122.10:22: connected
INFO [ssh] 192.168.122.20:22: connected
INFO [ssh] 192.168.122.21:22: connected
INFO ==> Running phase: Detect host operating systems
INFO [ssh] 192.168.122.10:22: is running Ubuntu 24.04.3 LTS
...
INFO ==> Running phase: Initialize the k0s cluster
INFO [ssh] 192.168.122.10:22: installing k0s controller
INFO [ssh] 192.168.122.10:22: waiting for kubernetes api to respond
INFO ==> Running phase: Install workers
...
INFO ==> Finished in 1m5s
INFO k0s cluster version v1.35.2+k0s.0 is now installed

Récupérer le kubeconfig

k0sctl kubeconfig écrit sur la sortie standard, d'où la redirection vers un fichier. Ce fichier contient les certificats d'administration du cluster : traitez-le comme un secret et restreignez ses droits.

# Exporter le kubeconfig
k0sctl kubeconfig --config k0sctl.yaml > kubeconfig

# Utiliser le cluster
export KUBECONFIG=$PWD/kubeconfig
kubectl get nodes -o wide

Sortie attendue :

NAME          STATUS   ROLES    AGE   VERSION       INTERNAL-IP
k0s-worker1   Ready    <none>   37s   v1.35.2+k0s   192.168.122.20
k0s-worker2   Ready    <none>   37s   v1.35.2+k0s   192.168.122.21

Le controller n'apparaît pas comme node

C'est normal avec la configuration par défaut ! k0s n'exécute pas de kubelet sur le controller, donc il n'apparaît pas dans kubectl get nodes. Pour vérifier l'état du controller, utilisez SSH :

ssh kube@192.168.122.10 "sudo k0s status"

Vérifier les composants système

Un kubectl get nodes en Ready ne prouve pas que le cluster est fonctionnel : il reste à confirmer que le réseau des pods et la résolution DNS répondent. Ces deux briques tournent dans le namespace kube-system, sur les workers, puisque le contrôleur n'exécute aucun pod.

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

Vous devriez voir au minimum :

• CoreDNS : résolution DNS interne du cluster
• konnectivity-agent : tunnel entre workers et control plane
• kube-proxy : règles iptables pour les Services
• Pods CNI : kube-router (défaut) ou Calico selon votre configuration

La présence de Metrics Server dépend de votre configuration (voir section "Configuration avancée").

Test de déploiement :

# Créer un pod de test
kubectl run nginx-test --image=nginx:alpine --restart=Never

# Vérifier qu'il tourne
kubectl get pod nginx-test -o wide

# Tester la connectivité
kubectl exec nginx-test -- wget -qO- http://localhost

# Nettoyer
kubectl delete pod nginx-test

Configuration avancée

Deux réglages structurants ne s'improvisent pas après coup : le provider réseau et le provisionnement du stockage. Le premier est figé pour la vie du cluster, le second reste ajoutable à tout moment mais conditionne le fonctionnement des applications à état.

Choisir le CNI (réseau)

k0s supporte trois options de CNI :

CNI	Configuration	Cas d'usage
kube-router	provider: kuberouter	Par défaut, léger, performant
Calico	provider: calico	Network policies avancées, BGP
Custom	provider: custom	Cilium, Weave, Flannel...

Glissez pour voir

Exemple avec Calico :

k0sctl.yaml (extrait)

spec:
  k0s:
    config:
      spec:
        network:
          provider: calico
          calico:
            mode: vxlan  # ou "ipip", "bird"

Configurer le storage

Ce guide ne configure pas de StorageClass. k0s supporte le standard CSI, ce qui permet d'installer n'importe quel provisioner selon votre environnement :

# Exemple : local-path-provisioner (pour le développement)
kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/master/deploy/local-path-storage.yaml

Ajouter un nœud worker

L'ajout ne se fait pas par une commande de join : on déclare le nœud dans k0sctl.yaml et on réapplique. k0sctl compare l'état décrit à l'état réel, ne touche pas aux nœuds déjà installés et provisionne uniquement le nouveau. Le serveur doit remplir les mêmes prérequis que les autres, SSH par clé et sudo sans mot de passe.

1. Éditer k0sctl.yaml

   Ajoutez le nouveau worker dans la section hosts :

   - ssh:
       address: 192.168.122.22
       user: kube
       keyPath: ~/.ssh/id_ed25519
     role: worker

2. Appliquer la modification

   k0sctl apply --config k0sctl.yaml

   k0sctl détecte automatiquement le nouveau nœud et l'ajoute au cluster.

3. Vérifier

   kubectl get nodes
   # Le nouveau worker apparaît en quelques secondes

Retirer un nœud worker

Cette procédure concerne un worker. Pour retirer un contrôleur en cluster HA, consultez la documentation officielle sur le quorum etcd.

1. Drainer le nœud

   kubectl drain k0s-worker2 --ignore-daemonsets --delete-emptydir-data

2. Supprimer de k0sctl.yaml

   Retirez l'entrée du worker de la section hosts.

3. Appliquer

   k0sctl apply --config k0sctl.yaml

4. Nettoyer sur le serveur (optionnel)

   ssh kube@192.168.122.21 "sudo k0s reset"

Mettre à jour le cluster

k0sctl gère les mises à jour in-place :

Avant de mettre à jour

1. Sauvegardez le cluster (voir section backup)
2. Vérifiez les release notes de la version cible
3. En production, testez d'abord sur un cluster de staging

1. Modifier la version dans k0sctl.yaml

   spec:
     k0s:
       version: v1.35.3+k0s.0  # Nouvelle version

2. Appliquer la mise à jour

   k0sctl apply --config k0sctl.yaml

   k0sctl met à jour les nœuds un par un (rolling update).

Compatibilité des versions

k0s suit le versionnement de Kubernetes. Mettez toujours à jour d'une version mineure à la fois (ex: 1.34 → 1.35, pas 1.33 → 1.35).

Sauvegarde et restauration

La sauvegarde k0s porte sur l'état du plan de contrôle : contenu d'etcd, certificats et configuration du cluster. Elle ne contient ni les images ni les données des volumes persistants, qui relèvent d'une sauvegarde applicative distincte. Une restauration remet le cluster dans l'état de la sauvegarde, les objets créés depuis disparaissent.

Sauvegarder etcd

La commande produit une archive unique à l'emplacement indiqué et doit tourner sur le contrôleur, avec les droits root. Sortez ensuite l'archive du serveur : une sauvegarde restée sur la machine qu'elle protège ne sert à rien.

# Sur le controller
ssh kube@192.168.122.10 "sudo k0s backup --save-path /tmp/k0s-backup.tar.gz"

# Récupérer le backup
scp kube@192.168.122.10:/tmp/k0s-backup.tar.gz .

Restaurer depuis un backup

Pour un cluster simple (1 controller) :

# Sur le controller
sudo k0s stop
sudo k0s restore /path/to/k0s-backup.tar.gz
sudo k0s start

Restauration en cluster HA ou avec adresse externe

Si vous utilisez externalAddress (load balancer) ou un cluster multi-controllers :

• L'adresse externe doit rester identique entre backup et restore (les workers s'y connectent)
• En HA, k0sctl propose k0sctl apply --restore-from pour une restauration pilotée
• Consultez la documentation officielle pour ces scénarios avancés

Dépannage

La plupart des incidents k0s viennent de la couche en dessous de Kubernetes : SSH, pare-feu, ou service k0s arrêté. Le réflexe est donc de vérifier l'état du service sur le nœud avant de chercher dans kubectl, d'autant que le contrôleur n'apparaît pas dans kubectl get nodes.

Problèmes courants

Ces cinq symptômes couvrent l'essentiel des échecs de déploiement rencontrés sur un cluster neuf.

Symptôme	Cause probable	Solution
connection refused sur 6443	k0s controller pas démarré	ssh controller "sudo k0s status"
Worker ne rejoint pas	Token expiré ou port bloqué	Vérifier firewall, régénérer token
Pods en Pending	Pas de worker disponible	kubectl get nodes, ajouter un worker
CoreDNS en CrashLoop	Réseau CNI pas prêt	kubectl logs -n kube-system coredns-xxx
k0sctl apply timeout	SSH lent ou serveur surchargé	Augmenter timeout : --request-timeout 10m

Glissez pour voir

Commandes de diagnostic

Toutes ces commandes s'exécutent sur le nœud, pas via l'API : elles restent utiles quand l'apiserver ne répond plus. k0s status est le point de départ, il indique si le service tourne et dans quel rôle.

# État du cluster (depuis le controller)
ssh kube@192.168.122.10 "sudo k0s status"

# Identifier les unités systemd k0s
ssh kube@192.168.122.10 "systemctl list-units | grep k0s"

# Logs du controller (nom d'unité à adapter selon votre installation)
ssh kube@192.168.122.10 "sudo journalctl -u 'k0s*' -f"

# État de etcd
ssh kube@192.168.122.10 "sudo k0s etcd member-list"

# Vérifier la connectivité API
curl -k https://192.168.122.10:6443/healthz

Reset complet d'un nœud

Si un nœud est dans un état incohérent :

ssh kube@192.168.122.20 "sudo k0s stop && sudo k0s reset && sudo reboot"

Puis relancez k0sctl apply.

Aperçu de la haute disponibilité (HA)

k0s supporte la haute disponibilité avec plusieurs controllers. Voici un aperçu, la mise en œuvre complète dépasse le cadre de ce guide.

Principes

La haute disponibilité de k0s repose entièrement sur le quorum etcd : un cluster à deux contrôleurs ne survit à aucune panne, puisqu'il faut la majorité stricte des membres pour élire un leader. Il faut aussi une adresse unique et stable pour l'API, sinon les workers restent attachés au contrôleur qui les a enregistrés.

• Minimum 3 controllers pour le quorum etcd (2n+1)
• Load balancer devant les controllers sur le port 6443
• externalAddress dans la config k0s pointe vers le load balancer

k0sctl.yaml (HA) : extrait

spec:
  hosts:
    - ssh:
        address: 192.168.122.10
      role: controller
    - ssh:
        address: 192.168.122.11
      role: controller
    - ssh:
        address: 192.168.122.12
      role: controller
    # ... workers

  k0s:
    config:
      spec:
        api:
          externalAddress: 192.168.122.100  # IP du load balancer

Options de load balancing

k0s propose plusieurs approches :

Option	Description
Load balancer externe	HAProxy, keepalived, cloud LB
NLLB (Node-local LB)	Load balancing côté workers
CPLB	Control Plane Load Balancing intégré

Glissez pour voir

Consultez la documentation HA officielle pour une mise en œuvre complète.

À retenir

1. k0s = binaire unique : tout Kubernetes intégré (apiserver, etcd, containerd, CNI)
2. Control plane isolé par défaut : pas de kubelet ni runtime sur le controller (sauf mode --enable-worker)
3. k0sctl : outil déclaratif pour déployer/gérer via SSH
4. Un fichier, un cluster : k0sctl.yaml décrit l'infrastructure complète
5. Mises à jour simples : changez la version dans le YAML, k0sctl fait le rolling update
6. CNI flexible mais définitif : kube-router (défaut), Calico, ou custom, à choisir dès le départ
7. Exigences modestes : 1 vCPU / 1 Go RAM comme base minimale recommandée
8. Certifié CNCF : 100% compatible avec l'écosystème Kubernetes

Pour aller plus loin

• Opérer Kubernetes : Le parcours d'exploitation à suivre une fois le cluster en service.
• CIS Benchmark : L'audit de conformité à passer avant d'ouvrir le cluster à des équipes.
• RBAC Kubernetes : Le contrôle d'accès à poser avant les premiers utilisateurs.

Ressources officielles

• Documentation k0s : docs.k0sproject.io
• GitHub k0s : github.com/k0sproject/k0s
• GitHub k0sctl : github.com/k0sproject/k0sctl
• Releases : github.com/k0sproject/k0s/releases

×

📖 Voir la documentation →