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.
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 :
- installer le nœud serveur ;
- utiliser
kubectlsans exposer l’API ; - déployer une première application ;
- ajouter un nœud agent ;
- 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 :
sudo modprobe wireguard && lsmod | grep wireguardPorts
| 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
sudo apt update
sudo apt upgrade -y
sudo apt install -y curl ufwLa 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 :
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 enable10.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.
sudo mkdir -p /etc/rancher/k3s
sudo nano /etc/rancher/k3s/config.yamlnode-external-ip: IP_SERVEUR
flannel-backend: wireguard-native
flannel-external-ip: true
tls-san:
- IP_SERVEURInstallez ensuite K3s avec le script officiel, qui suit par défaut le canal stable :
curl -sfL https://get.k3s.io | sh -Vérifiez le service et le nœud. Le passage à l’état Ready peut prendre une minute :
sudo systemctl status k3s --no-pager
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl get pods -AUtiliser 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 :
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 nodesAdministrer 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 :
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_SERVEURLaissez ce tunnel ouvert et, dans un autre terminal :
export KUBECONFIG=~/.kube/k3s-hms
kubectl get nodesK3s 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 :
nano demo.yamlapiVersion: 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: 80Appliquez-le et suivez le déploiement :
kubectl apply -f demo.yaml
kubectl -n demo rollout status deployment/web
kubectl -n demo get pods,svc,ingressTestez l’application depuis votre poste, même si le DNS n’est pas encore configuré :
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 :
kubectl delete namespace demoAjouter 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 :
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 udpSur l’agent :
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 enableLes 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 :
sudo cat /var/lib/rancher/k3s/server/node-tokenSur 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 :
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-pagerSur le serveur, le nouveau nœud doit apparaître à l’état Ready :
kubectl get nodes -o wideMettre à 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 :
curl -sfL https://get.k3s.io | sh -Sur chaque agent, repassez les mêmes variables :
read -rs K3S_TOKEN
curl -sfL https://get.k3s.io | K3S_URL=https://IP_SERVEUR:6443 K3S_TOKEN="$K3S_TOKEN" sh -
unset K3S_TOKENSi votre cluster a plusieurs versions mineures de retard, montez par étapes avec le canal correspondant, par exemple :
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.
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.gzLes 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 :
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 nodesEn 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
sudo journalctl -u k3s -n 80 --no-pager
sudo k3s check-configSi 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
sudo journalctl -u k3s-agent -n 80 --no-pager
curl -vk -m 5 https://IP_SERVEUR:6443/pingconnection refusedou délai dépassé : vérifiez UFW et l’adresse deK3S_URL.tokeninvalide : copiez à nouveau le contenu denode-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 aveckubectl delete node NOM_DU_NOEUD.
Un nœud reste à l’état NotReady
kubectl describe node NOM_DU_NOEUD
ip link show flannel-wgVé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
kubectl -n demo describe pod NOM_DU_POD
kubectl -n demo logs NOM_DU_PODPending 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
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
/usr/local/bin/k3s-uninstall.shSur un agent :
/usr/local/bin/k3s-agent-uninstall.shPour 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.