FR

Applications

Installer Kubernetes avec K3s

Installez K3s sur Debian ou Ubuntu, utilisez kubectl, déployez une première application, ajoutez un nœud et sécurisez les ports du cluster.

8 min de lecture, mis à jour le 18 novembre 2026

Sur cette page

Vos valeurs

Renseignez-les une fois, les commandes du guide se mettent à jour.

K3s est une distribution Kubernetes légère et certifiée, distribuée sous la forme d’un seul binaire. Elle convient bien à un VPS ou à un serveur dédié : elle embarque notamment kubectl, le contrôleur Ingress Traefik, un répartiteur de charge simple et un stockage local.

Ce guide vous accompagne de l’installation à un cluster à deux nœuds, sous Debian 12/13 ou Ubuntu 22.04/24.04 :

  1. installer le nœud serveur ;
  2. utiliser kubectl sans exposer l’API ;
  3. déployer une première application ;
  4. ajouter un nœud agent ;
  5. mettre à jour et sauvegarder le cluster.

Commander un serveur

Pour héberger votre cluster, HostMyServers propose plusieurs offres :

Prérequis

Rôle CPU minimum RAM minimum
Serveur 2 cœurs 2 Go
Agent 1 cœur 512 Mo

Ces valeurs, issues de la documentation K3s, ne comprennent pas les ressources de vos applications.

Il vous faut aussi :

  • un accès SSH avec un utilisateur disposant de sudo ;
  • un nom d’hôte différent sur chaque nœud ;
  • une adresse IP joignable par les autres nœuds, généralement l’adresse IP publique ;
  • le module noyau WireGuard si vos nœuds communiquent par Internet.

Vérifiez la présence de WireGuard sur chaque nœud :

Terminal
sudo modprobe wireguard && lsmod | grep wireguard

Ports

Port Protocole Source Usage
22 TCP Votre poste SSH et tunnel vers l’API
6443 TCP Agents API Kubernetes et superviseur K3s
10250 TCP Tous les nœuds Métriques et API du kubelet
51820 UDP Tous les nœuds Flannel WireGuard en IPv4
51821 UDP Tous les nœuds Flannel WireGuard en IPv6, si utilisé
80, 443 TCP Internet Applications publiées par Traefik

Préparer le serveur

Terminal
sudo apt update
sudo apt upgrade -y
sudo apt install -y curl ufw

La documentation K3s recommande de désactiver UFW, mais un serveur exposé sur Internet doit rester filtré. Si vous conservez UFW, comme ici, les réseaux internes de K3s doivent être autorisés. Remplacez 22 si vous utilisez un autre port SSH :

Terminal
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80,443/tcp
sudo ufw allow from 10.42.0.0/16 to any
sudo ufw allow from 10.43.0.0/16 to any
sudo ufw enable

10.42.0.0/16 est le réseau par défaut des pods et 10.43.0.0/16 celui des services.

Installer le nœud serveur

Préparez la configuration avant l’installation. Le réseau du cluster est ainsi chiffré dès le départ, ce qui permet d’ajouter plus tard un nœud par Internet.

Terminal
sudo mkdir -p /etc/rancher/k3s
sudo nano /etc/rancher/k3s/config.yaml
YAML
node-external-ip: IP_SERVEUR
flannel-backend: wireguard-native
flannel-external-ip: true
tls-san:
  - IP_SERVEUR

Installez ensuite K3s avec le script officiel, qui suit par défaut le canal stable :

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

Vérifiez le service et le nœud. Le passage à l’état Ready peut prendre une minute :

Terminal
sudo systemctl status k3s --no-pager
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl get pods -A

Utiliser kubectl

Le fichier /etc/rancher/k3s/k3s.yaml donne un accès administrateur complet au cluster et n’est lisible que par root. Ne le rendez pas lisible par tous. Créez plutôt une copie personnelle :

Terminal
mkdir -p ~/.kube
install -m 600 /dev/null ~/.kube/config
sudo k3s kubectl config view --raw > ~/.kube/config
echo 'export KUBECONFIG="$HOME/.kube/config"' >> ~/.bashrc
export KUBECONFIG="$HOME/.kube/config"
kubectl get nodes

Administrer le cluster depuis votre poste

Le tunnel SSH évite d’ouvrir le port 6443 à votre poste. Installez kubectl sur votre machine, puis copiez la configuration :

Terminal
mkdir -p ~/.kube
scp VOTRE_USER@IP_SERVEUR:.kube/config ~/.kube/k3s-hms
chmod 600 ~/.kube/k3s-hms
ssh -N -L 6443:127.0.0.1:6443 VOTRE_USER@IP_SERVEUR

Laissez ce tunnel ouvert et, dans un autre terminal :

Terminal
export KUBECONFIG=~/.kube/k3s-hms
kubectl get nodes

K3s renouvelle les certificats de son fichier d’administration à chaque démarrage. Si votre copie cesse de fonctionner, recopiez-la.

Déployer une première application

Créez un manifeste :

Terminal
nano demo.yaml
YAML
apiVersion: v1
kind: Namespace
metadata:
  name: demo
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: nginx
          image: nginx:stable-alpine
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: 50m
              memory: 32Mi
            limits:
              memory: 128Mi
---
apiVersion: v1
kind: Service
metadata:
  name: web
  namespace: demo
spec:
  selector:
    app: web
  ports:
    - port: 80
      targetPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
  namespace: demo
spec:
  ingressClassName: traefik
  rules:
    - host: demo.votre-domaine.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80

Appliquez-le et suivez le déploiement :

Terminal
kubectl apply -f demo.yaml
kubectl -n demo rollout status deployment/web
kubectl -n demo get pods,svc,ingress

Testez l’application depuis votre poste, même si le DNS n’est pas encore configuré :

Terminal
curl -H 'Host: demo.votre-domaine.com' http://IP_SERVEUR/

Vous devez obtenir la page d’accueil de Nginx.

Supprimez l’exemple lorsque vous n’en avez plus besoin :

Terminal
kubectl delete namespace demo

Ajouter un nœud agent

Dans cette section, IP_AGENT désigne l’adresse IP du nouveau nœud.

Ouvrir les flux entre les nœuds

Sur le serveur :

Terminal
sudo ufw allow from IP_AGENT to any port 6443 proto tcp
sudo ufw allow from IP_AGENT to any port 10250 proto tcp
sudo ufw allow from IP_AGENT to any port 51820 proto udp

Sur l’agent :

Terminal
sudo apt update
sudo apt install -y curl ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80,443/tcp
sudo ufw allow from 10.42.0.0/16 to any
sudo ufw allow from 10.43.0.0/16 to any
sudo ufw allow from IP_SERVEUR to any port 10250 proto tcp
sudo ufw allow from IP_SERVEUR to any port 51820 proto udp
sudo ufw enable

Les ports 80 et 443 sont nécessaires sur l’agent, car Traefik peut être publié sur chaque nœud. Avec plus de deux nœuds, ouvrez les ports 10250/TCP et 51820/UDP entre tous les nœuds.

Joindre le cluster

Sur le serveur, affichez le jeton :

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

Sur l’agent, déclarez son adresse externe, puis lancez l’installation. La commande read attend que vous colliez le jeton, sans l’afficher ni l’enregistrer dans l’historique :

Terminal
sudo mkdir -p /etc/rancher/k3s
echo 'node-external-ip: IP_AGENT' | sudo tee /etc/rancher/k3s/config.yaml
read -rs K3S_TOKEN
curl -sfL https://get.k3s.io | K3S_URL=https://IP_SERVEUR:6443 K3S_TOKEN="$K3S_TOKEN" sh -
unset K3S_TOKEN
sudo systemctl status k3s-agent --no-pager

Sur le serveur, le nouveau nœud doit apparaître à l’état Ready :

Terminal
kubectl get nodes -o wide

Mettre à jour K3s

Sauvegardez d’abord le cluster et lisez les notes de version. Mettez à jour les serveurs d’abord, un par un, puis les agents, sans sauter de version mineure de Kubernetes.

Sur le serveur, relancez le script. La configuration de config.yaml est conservée :

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

Sur chaque agent, repassez les mêmes variables :

Terminal
read -rs K3S_TOKEN
curl -sfL https://get.k3s.io | K3S_URL=https://IP_SERVEUR:6443 K3S_TOKEN="$K3S_TOKEN" sh -
unset K3S_TOKEN

Si votre cluster a plusieurs versions mineures de retard, montez par étapes avec le canal correspondant, par exemple :

Terminal
curl -sfL https://get.k3s.io | INSTALL_K3S_CHANNEL=v1.36 sh -

Contrôlez ensuite les versions avec kubectl get nodes.

Sauvegarder et restaurer

Avec SQLite, sauvegardez la base et le jeton du serveur : sans ce jeton, la sauvegarde est inutilisable. L’arrêt de K3s garantit une copie cohérente et n’arrête pas les conteneurs déjà lancés.

Terminal
sudo systemctl stop k3s
sudo tar -czpf "/root/k3s-$(date +%F).tar.gz" /var/lib/rancher/k3s/server/db /var/lib/rancher/k3s/server/token /etc/rancher/k3s/config.yaml
sudo systemctl start k3s
sudo chmod 600 /root/k3s-*.tar.gz

Les volumes créés par le stockage local se trouvent dans /var/lib/rancher/k3s/storage. Sauvegardez-les aussi, idéalement avec les outils propres à chaque application, par exemple un export de base de données. Conservez également vos manifestes dans un dépôt Git privé.

Pour restaurer la base sur le serveur :

Terminal
sudo systemctl stop k3s
sudo rm -rf /var/lib/rancher/k3s/server/db
sudo tar -xzpf /root/k3s-AAAA-MM-JJ.tar.gz -C /
sudo systemctl start k3s
kubectl get nodes

En cas de problème

Unable to read /etc/rancher/k3s/k3s.yaml

Votre utilisateur n’a pas accès au fichier d’administration. Reprenez la section Utiliser kubectl et vérifiez echo $KUBECONFIG. Évitez de rendre ce fichier lisible par tous avec --write-kubeconfig-mode 644.

Le service k3s ne démarre pas

Terminal
sudo journalctl -u k3s -n 80 --no-pager
sudo k3s check-config

Si les journaux évoquent WireGuard, vérifiez sudo modprobe wireguard. Lorsque le module est indisponible sur un cluster à un seul nœud, retirez flannel-backend et flannel-external-ip de config.yaml avant une nouvelle installation. Ne remplacez pas WireGuard par VXLAN entre des nœuds reliés par Internet.

L’agent ne rejoint pas le cluster

Terminal
sudo journalctl -u k3s-agent -n 80 --no-pager
curl -vk -m 5 https://IP_SERVEUR:6443/ping
  • connection refused ou délai dépassé : vérifiez UFW et l’adresse de K3S_URL.
  • token invalide : copiez à nouveau le contenu de node-token.
  • Node password rejected, duplicate hostname : un autre nœud porte le même nom, ou ce nœud a déjà été inscrit. Changez le nom d’hôte, ou supprimez l’ancien nœud avec kubectl delete node NOM_DU_NOEUD.

Un nœud reste à l’état NotReady

Terminal
kubectl describe node NOM_DU_NOEUD
ip link show flannel-wg

Vérifiez les ports 10250/TCP et 51820/UDP entre les nœuds, ainsi que les valeurs node-external-ip.

Un pod reste en Pending ou ImagePullBackOff

Terminal
kubectl -n demo describe pod NOM_DU_POD
kubectl -n demo logs NOM_DU_POD

Pending signale souvent un manque de CPU ou de mémoire. ImagePullBackOff indique un nom d’image incorrect, un accès refusé au registre ou une limite de téléchargement.

L’Ingress renvoie 404 ou les ports 80/443 ne répondent pas

Terminal
kubectl -n kube-system get pods,svc | grep -E 'traefik|svclb'
sudo ss -tlnp | grep -E ':(80|443)\b'

Un 404 indique généralement que l’en-tête Host ne correspond pas au champ host de l’Ingress. Si les pods svclb restent en Pending, un service du système, comme Nginx ou Apache, occupe probablement déjà les ports 80 et 443.

Désinstaller K3s

Terminal
/usr/local/bin/k3s-uninstall.sh

Sur un agent :

Terminal
/usr/local/bin/k3s-agent-uninstall.sh

Pour aller plus loin

Pour stocker vos images de conteneurs, consultez le guide Installer Harbor. Pour automatiser la préparation de vos nœuds, consultez Automatiser ses serveurs avec Ansible.

Références