Guide complet : installer un cluster Kubernetes multi-nœuds avec kubeadm

Ce guide complet vous accompagne pour installer cluster Kubernetes kubeadm sur une infrastructure multi-nœuds. La procédure couvre Ubuntu 22.04/24.04 et utilise containerd comme runtime. Selon la documentation officielle Kubernetes v1.31, kubeadm reste l'outil recommandé pour les déploiements production auto-hébergés.

TL;DR : Ce guide détaille l'installation complète d'un cluster Kubernetes 3 nœuds (1 control plane + 2 workers) avec kubeadm, containerd et Calico CNI. Temps estimé : 45-60 minutes. Prérequis : 3 VMs Ubuntu avec 2 CPU et 4GB RAM minimum.

La configuration cluster Kubernetes multi-noeuds est au cœur de la formation LFS458 Administration Kubernetes.

Quels prérequis pour installer cluster Kubernetes kubeadm ?

Avant de commencer, vérifiez que votre infrastructure respecte les exigences minimales.

Configuration matérielle

Composant	Control Plane	Worker Node
CPU	2 cores minimum	1 core minimum
RAM	4 GB minimum	2 GB minimum
Disque	50 GB SSD	30 GB SSD
Réseau	Connectivité entre nodes	Connectivité entre nodes

Configuration réseau

# Vérifier la connectivité entre nodes
ping -c 3 <control-plane-ip>
ping -c 3 <worker1-ip>
ping -c 3 <worker2-ip>

Les ports suivants doivent être ouverts :

Control Plane :

6443 : API server
2379-2380 : etcd
10250 : kubelet
10259 : scheduler
10257 : controller-manager

Workers :

10250 : kubelet
30000-32767 : NodePort Services

À retenir : Les exigences minimales sont pour des tests. En production, doublez ces valeurs et utilisez des disques SSD rapides pour etcd.

Comment préparer les nodes pour installer cluster Kubernetes kubeadm ?

Cette section couvre la préparation de chaque node. Exécutez ces commandes sur TOUS les nodes (control plane et workers).

Désactiver le swap

Kubernetes requiert que le swap soit désactivé :

# Désactiver le swap immédiatement
sudo swapoff -a

# Désactiver le swap au redémarrage
sudo sed -i '/ swap / s/^/#/' /etc/fstab

# Vérifier
free -h

Configurer les modules kernel

# Charger les modules nécessaires
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

sudo modprobe overlay
sudo modprobe br_netfilter

# Vérifier le chargement
lsmod | grep br_netfilter
lsmod | grep overlay

Configurer les paramètres sysctl

# Configurer le forwarding et iptables
cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

# Appliquer les paramètres
sudo sysctl --system

# Vérifier
sysctl net.bridge.bridge-nf-call-iptables
sysctl net.ipv4.ip_forward

Configurer le hostname

Chaque node doit avoir un hostname unique :

# Sur le control plane
sudo hostnamectl set-hostname control-plane

# Sur worker 1
sudo hostnamectl set-hostname worker-1

# Sur worker 2
sudo hostnamectl set-hostname worker-2

Ajoutez les entrées dans /etc/hosts sur tous les nodes :

cat <<EOF | sudo tee -a /etc/hosts
192.168.1.10 control-plane
192.168.1.11 worker-1
192.168.1.12 worker-2
EOF

Comment installer containerd comme runtime ?

containerd est le runtime de conteneurs recommandé pour Kubernetes. Exécutez sur TOUS les nodes.

Installation de containerd

# Installer les dépendances
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

# Ajouter le repository Docker (contient containerd)
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Installer containerd
sudo apt-get update
sudo apt-get install -y containerd.io

Configurer containerd

# Générer la configuration par défaut
sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml

# Activer SystemdCgroup
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml

# Redémarrer containerd
sudo systemctl restart containerd
sudo systemctl enable containerd

# Vérifier le statut
sudo systemctl status containerd

À retenir : L'option SystemdCgroup = true est critique. Sans elle, les pods rencontrent des problèmes de stabilité avec les cgroups v2.

Comment installer kubeadm, kubelet et kubectl ?

Les outils Kubernetes s'installent depuis le repository officiel. Exécutez sur TOUS les nodes.

Ajouter le repository Kubernetes

# Installer les dépendances
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl gpg

# Ajouter la clé GPG
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.31/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

# Ajouter le repository
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.31/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

Installer les packages

# Installer kubeadm, kubelet, kubectl
sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl

# Empêcher les mises à jour automatiques
sudo apt-mark hold kubelet kubeadm kubectl

# Vérifier les versions
kubeadm version
kubectl version --client
kubelet --version

Comment initialiser le control plane ?

L'initialisation du control plane se fait uniquement sur le node control-plane.

Exécuter kubeadm init

# Initialiser le cluster
sudo kubeadm init \
  --pod-network-cidr=10.244.0.0/16 \
  --kubernetes-version=v1.31.0 \
  --control-plane-endpoint=control-plane:6443

# Conserver la commande kubeadm join affichée !

Le paramètre --pod-network-cidr doit correspondre au CNI que vous installerez (ici Calico/Flannel).

Configurer kubectl

# Configurer l'accès kubectl pour l'utilisateur courant
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

# Vérifier la connexion
kubectl cluster-info
kubectl get nodes

Le node control-plane apparaît en status NotReady : c'est normal, le CNI n'est pas encore installé.

Installer le CNI (Calico)

# Installer Calico
kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.27.0/manifests/calico.yaml

# Vérifier l'installation
kubectl get pods -n kube-system | grep calico
kubectl get nodes

Après quelques minutes, le control plane passe en status Ready.

À retenir : Le CNI est indispensable pour la communication entre pods. Sans CNI, aucun pod applicatif ne peut démarrer correctement.

Comment joindre les workers au cluster ?

L'ajout des workers utilise la commande générée lors de l'init. Exécutez sur chaque worker node.

Récupérer la commande join

Si vous avez perdu la commande, régénérez-la depuis le control plane :

# Sur le control plane
kubeadm token create --print-join-command

Joindre les workers

# Sur worker-1 et worker-2
sudo kubeadm join control-plane:6443 \
  --token <token> \
  --discovery-token-ca-cert-hash sha256:<hash>

Vérifier le cluster

Depuis le control plane :

kubectl get nodes -o wide

Output attendu :

NAME            STATUS   ROLES           VERSION   INTERNAL-IP     OS-IMAGE
control-plane   Ready    control-plane   v1.31.0   192.168.1.10    Ubuntu 22.04
worker-1        Ready    <none>          v1.31.0   192.168.1.11    Ubuntu 22.04
worker-2        Ready    <none>          v1.31.0   192.168.1.12    Ubuntu 22.04

Comment valider l'installation du cluster ?

Vérifiez que tous les composants fonctionnent correctement.

Vérifier les pods système

kubectl get pods -n kube-system

Tous les pods doivent être en status Running :

NAME                                       READY   STATUS    RESTARTS   AGE
calico-kube-controllers-xxx                1/1     Running   0          5m
calico-node-xxx                            1/1     Running   0          5m
coredns-xxx                                1/1     Running   0          10m
etcd-control-plane                         1/1     Running   0          10m
kube-apiserver-control-plane               1/1     Running   0          10m
kube-controller-manager-control-plane      1/1     Running   0          10m
kube-proxy-xxx                             1/1     Running   0          10m
kube-scheduler-control-plane               1/1     Running   0          10m

Déployer une application de test

# Créer un déploiement
kubectl create deployment nginx --image=nginx:1.27

# Exposer le service
kubectl expose deployment nginx --port=80 --type=NodePort

# Vérifier
kubectl get pods -o wide
kubectl get svc nginx

Tester la connectivité

# Récupérer le NodePort
NODE_PORT=$(kubectl get svc nginx -o jsonpath='{.spec.ports[0].nodePort}')

# Tester depuis l'extérieur
curl http://worker-1:$NODE_PORT
curl http://worker-2:$NODE_PORT

À retenir : Un test de bout en bout (déploiement + service + accès externe) valide que votre cluster est opérationnel.

Comment résoudre les problèmes courants ?

Voici les erreurs fréquentes et leurs solutions.

Erreur : Node NotReady

# Diagnostic
kubectl describe node <node-name>
journalctl -u kubelet -f

# Causes communes :
# - CNI non installé
# - kubelet crashé
# - Problème réseau

Erreur : Pods en Pending

# Vérifier les events
kubectl describe pod <pod-name>

# Causes communes :
# - Pas assez de ressources
# - Taints sur les nodes
# - Affinity non satisfaite

Erreur : kubeadm init échoue

# Reset et réessayer
sudo kubeadm reset
sudo rm -rf /etc/cni/net.d
sudo iptables -F && sudo iptables -t nat -F

Pour plus de solutions, consultez la page Résoudre les 10 problèmes les plus courants sur un.

Quelles bonnes pratiques pour un cluster production ?

Ce guide couvre une installation basique. Pour la production, ajoutez :

Haute disponibilité

3 control plane nodes minimum
Load balancer devant l'API server
etcd en mode HA (stacked ou external)

Sécurité

Network Policies pour segmenter le trafic
Pod Security Admission pour restreindre les pods
RBAC configuré finement

Consultez nos pages régionales pour des formations en présentiel :

Monitoring

Prometheus pour les métriques
Grafana pour la visualisation
Alertmanager pour les alertes

Backup

# Backup etcd quotidien
0 2 * * * /usr/local/bin/etcd-backup.sh /backups/etcd-$(date +\%Y\%m\%d).db

Passez à l'action : approfondissez vos compétences

Vous avez installé votre premier cluster multi-nœuds. Voici les prochaines étapes.

Continuez votre apprentissage

Administration cluster Kubernetes : tous les guides et ressources
Aide-mémoire kubectl : commandes essentielles pour : référence rapide

Préparez la certification CKA

La ingénieur infrastructure formation LFS458 Administration Kubernetes couvre ces compétences et bien plus :

Installation avancée avec kubeadm
Gestion d'etcd et haute disponibilité
Networking et troubleshooting

Découvrez la formation LFS458 Administration Kubernetes et consultez les prochaines dates sur le calendrier des formations.

Parcours recommandés selon votre profil :

Débutant : Kubernetes les fondamentaux (1 jour)
Administrateur : LFS458 Administration Kubernetes (4 jours, préparation CKA)
Développeur : LFD459 Kubernetes pour développeurs (3 jours, préparation CKAD)
Sécurité : LFS460 Sécurité Kubernetes (4 jours, préparation CKS)

Pour un conseil personnalisé ou une session intra-entreprise, contactez nos conseillers.

Points clés