Déployer Kubernetes avec Kubespray

Kubespray déploie des clusters Kubernetes en utilisant Ansible. Ce guide construit un lab KVM reproductible servant de base à des déploiements plus robustes. Contrairement à kubeadm qui nécessite des commandes manuelles sur chaque nœud, Kubespray automatise tout depuis votre poste de travail.

Une mise au point avant de commencer : ce guide déploie un control plane et deux workers, ce qui suffit à apprendre et à expérimenter, pas à tenir la production. Il y manquerait trois control planes derrière un répartiteur de charge, une sauvegarde etcd externalisée et éprouvée, de la supervision, et un filtrage réseau digne de ce nom. Chacun de ces points relève d'une autre leçon du parcours.

Ces deux outils ne s'opposent pas, ils répondent à des moments différents. Pour la CKA, kubeadm reste incontournable : l'examen attend des commandes tapées à la main. Pour un parc d'entreprise, Kubespray automatise exactement ce que kubeadm fait manuellement, et rend l'opération rejouable.

Kubespray vs autres solutions

Kubespray n'est pas une distribution Kubernetes : c'est une collection de playbooks Ansible qui pilotent kubeadm sur chaque nœud. Il se compare donc mal aux distributions allégées comme k3s ou k0s, qui embarquent leur propre binaire et leurs propres choix. Le tableau ci-dessous sert à trancher sur trois critères : la méthode d'installation, la façon dont la haute disponibilité est obtenue, et le degré de liberté laissé sur le plugin réseau.

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

Ce que vous allez apprendre

À la fin de ce guide, vous saurez :

Provisionner des VMs KVM configurées via cloud-init pour un cluster Kubernetes
Préparer l'environnement Kubespray avec les bonnes versions d'Ansible et dépendances
Créer un inventaire personnalisé définissant la topologie du cluster
Déployer un cluster complet avec Calico, containerd et CoreDNS en une seule commande
Valider que tous les composants fonctionnent correctement
Personnaliser les options (CNI, runtime, addons) selon vos besoins

Prérequis

Vérifiez ces points avant de commencer : un manque à ce stade se manifeste bien plus tard, sous la forme d'une erreur qui ne le désigne pas.

Ressources matérielles

Kubespray déploie les mêmes composants que kubeadm mais automatise la configuration. Les besoins sont donc identiques :

Rôle	CPU	RAM (min)	RAM (recommandé)	Disque	Quantité
Control plane	2 vCPU	2 Go	2 Go	20 Go	1 (ou 3+ pour HA)
Worker	2 vCPU	1 Go	2 Go	20 Go	2+
Poste Ansible	1 vCPU	1 Go	1 Go	5 Go	Votre machine locale

Le minimum Kubespray pour les workers est 1 Go, mais ce guide recommande 2 Go pour éviter les problèmes lors du téléchargement parallèle des images.

Logiciels requis

Sur votre poste de travail (machine de contrôle Ansible) :

Python 3.10+ avec pip
Git pour cloner le repository Kubespray
SSH avec une clé configurée (les VMs doivent être accessibles sans mot de passe)

Sur les VMs cibles :

Ubuntu 24.04 ou Rocky Linux 9 (distribution supportée par Kubespray)
Python 3 installé (requis par Ansible)
Accès sudo sans mot de passe pour l'utilisateur SSH
Accès Internet pour télécharger images et binaires (sauf configuration offline dédiée)

Versions validées dans ce guide

Ce guide a été validé avec les versions suivantes :

Composant	Version
Kubespray	v2.30.0
Kubernetes	v1.34.3
Ansible	core 2.17.x+
CNI	Calico 3.30.6 (plugin par défaut)

Un réflexe à prendre avant tout changement de version : lisez le README et les notes de version. Kubespray évolue vite, et la compatibilité entre une de ses versions et une version de Kubernetes n'a rien d'évident. C'est le genre de vérification qui coûte cinq minutes et évite un déploiement à recommencer.

Travaillez toujours sur une release taggée, v2.30.0 par exemple, jamais sur la branche master. Celle-ci porte des changements en cours qui peuvent être incompatibles entre eux, et le projet ne la recommande pas pour un usage stable. Un tag, lui, se rejoue à l'identique dans six mois.

Création des machines virtuelles

Kubespray ne provisionne pas l'infrastructure : il prend en charge des machines déjà démarrées et joignables en SSH. Cette étape prépare donc trois VMs KVM avec cloud-init, le mécanisme d'initialisation au premier démarrage des images cloud, qui pose la clé SSH, le compte sudo sans mot de passe et désactive le swap. Les adresses IP sont fixées en statique parce qu'elles seront écrites en dur dans l'inventaire Ansible.

Architecture cible

Nous allons créer un cluster avec 1 control plane et 2 workers sur le réseau libvirt par défaut :

Architecture du lab Kubespray avec Ansible et 3 VMs sur KVM

Préparer l'image cloud Ubuntu 24.04

Téléchargez l'image cloud Ubuntu 24.04 si elle n'est pas déjà présente. Canonical publie à côté des images un fichier SHA256SUMS qui contient l'empreinte de chacune : téléchargez les deux, puis vérifiez l'empreinte avant d'installer l'image dans le pool libvirt. Une image altérée deviendrait le socle de tous vos nœuds.

# Vérifier si l'image existe déjà
ls -lh /var/lib/libvirt/images/ubuntu-24.04-cloud.img

# Télécharger l'image et le fichier de sommes officiel dans un dossier de travail
cd /tmp
curl -LO https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
curl -LO https://cloud-images.ubuntu.com/noble/current/SHA256SUMS

# Vérifier l'empreinte : la sortie doit afficher "OK"
sha256sum --ignore-missing -c SHA256SUMS

# Installer l'image seulement si la vérification a réussi
sudo install -m 0644 noble-server-cloudimg-amd64.img \
  /var/lib/libvirt/images/ubuntu-24.04-cloud.img

L'option --ignore-missing évite que sha256sum échoue sur les autres images listées dans le fichier de sommes et que vous n'avez pas téléchargées. Si la ligne affiche FAILED, ne poursuivez pas : retéléchargez l'image.

Configuration cloud-init

Créez un fichier user-data pour configurer l'utilisateur SSH sur les VMs. Remplacez VOTRE_CLE_SSH_PUBLIQUE par le contenu de votre ~/.ssh/id_ed25519.pub :

#cloud-config
hostname: ${HOSTNAME}
manage_etc_hosts: true
users:
  - name: kube
    sudo: ALL=(ALL) NOPASSWD:ALL
    groups: users, sudo
    shell: /bin/bash
    lock_passwd: true
    ssh_authorized_keys:
      - VOTRE_CLE_SSH_PUBLIQUE

packages:
  - qemu-guest-agent
  - python3

runcmd:
  - swapoff -a
  - sed -i '/swap/d' /etc/fstab
  - systemctl enable qemu-guest-agent

Le swap doit être désactivé, sans quoi le kubelet refuse de fonctionner. swapoff -a s'occupe de la session courante, mais seule la suppression de l'entrée dans /etc/fstab garantit qu'il ne revienne pas au redémarrage suivant. Les deux gestes vont ensemble, oublier le second donne un cluster qui casse à la première maintenance.

Configurer le réseau statique

Créez un fichier network-config pour chaque VM avec son IP statique :

version: 2
ethernets:
  enp1s0:
    dhcp4: false
    addresses:
      - 192.168.122.50/24
    routes:
      - to: default
        via: 192.168.122.1
    nameservers:
      addresses:
        - 192.168.122.1
        - 8.8.8.8

Le nom enp1s0 est celui qu'on rencontre habituellement avec KVM et libvirt, mais il varie selon l'image cloud et l'hyperviseur. Vérifiez celui de votre environnement dans la documentation de l'image, ou démarrez une première fois en DHCP et lisez la sortie d'ip link.

Création des VMs

Quatre étapes, à répéter pour chacune des trois machines. Les disques sont créés en backing file : chaque VM ne stocke que ses différences par rapport à l'image de base, ce qui rend la création quasi instantanée et économise l'espace disque. Ne supprimez donc jamais l'image de base tant que les VMs existent.

Générer les ISOs cloud-init pour chaque VM :

# Pour ks-cp1
cloud-localds ks-cp1-cloud-init.iso user-data-cp1 \
  --network-config network-config-cp1

# Répéter pour ks-worker1 et ks-worker2 avec leurs fichiers respectifs

Créer les disques avec backing file :

for vm in ks-cp1 ks-worker1 ks-worker2; do
  sudo qemu-img create -f qcow2 \
    -b /var/lib/libvirt/images/ubuntu-24.04-cloud.img \
    -F qcow2 \
    /var/lib/libvirt/images/${vm}.qcow2 20G
done

Créer les VMs avec virt-install :

for vm in ks-cp1 ks-worker1 ks-worker2; do
  sudo virt-install \
    --name ${vm} \
    --memory 2048 \
    --vcpus 2 \
    --disk /var/lib/libvirt/images/${vm}.qcow2 \
    --disk /var/lib/libvirt/images/${vm}-cloud-init.iso,device=cdrom \
    --os-variant ubuntu24.04 \
    --network network=default \
    --graphics none \
    --console pty,target_type=serial \
    --noautoconsole \
    --import
done

Vérifier la connectivité SSH :

for ip in 192.168.122.50 192.168.122.51 192.168.122.52; do
  ssh -o StrictHostKeyChecking=accept-new kube@${ip} hostname
done

Si les trois hostnames s'affichent (ks-cp1, ks-worker1, ks-worker2), vos VMs sont prêtes.

Installation de Kubespray

Kubespray s'installe sur votre poste, pas sur les nœuds : c'est un dépôt Git de playbooks accompagné d'un requirements.txt qui épingle les versions d'Ansible et de ses dépendances Python. Ces versions sont contraignantes, chaque release de Kubespray n'étant testée qu'avec la combinaison qu'elle déclare. Un environnement virtuel Python dédié évite tout conflit avec un Ansible déjà présent sur la machine.

Cloner le repository

Utilisez toujours une version taggée pour la stabilité :

git clone https://github.com/kubernetes-sigs/kubespray.git \
  --depth 1 --branch v2.30.0

cd kubespray

Créer l'environnement Python

Kubespray nécessite des versions spécifiques d'Ansible et de ses dépendances :

# Créer un environnement virtuel isolé
python3 -m venv venv
source venv/bin/activate

# Installer les dépendances
pip install -U pip
pip install -r requirements.txt

# Vérifier Ansible
ansible --version

La sortie doit indiquer ansible [core 2.17.x] ou supérieur pour Kubespray v2.30.0.

Configuration de l'inventaire

L'inventaire est le seul endroit qui décrit la topologie du cluster : quelles machines existent, et quel rôle chacune tient. Kubespray ne déduit rien, il applique strictement les groupes Ansible que vous déclarez, kube_control_plane pour le plan de contrôle, kube_node pour les workers, etcd pour la base de données du cluster. Travaillez toujours sur une copie du template fourni : un git pull écraserait vos modifications faites dans inventory/sample.

Copier le template

Kubespray fournit un inventory sample que vous personnalisez :

cp -r inventory/sample inventory/mycluster

Créer le fichier hosts.yaml

Remplacez le contenu de inventory/mycluster/hosts.yaml par votre topologie :

all:
  hosts:
    ks-cp1:
      ansible_host: 192.168.122.50
      ip: 192.168.122.50
      access_ip: 192.168.122.50
    ks-worker1:
      ansible_host: 192.168.122.51
      ip: 192.168.122.51
      access_ip: 192.168.122.51
    ks-worker2:
      ansible_host: 192.168.122.52
      ip: 192.168.122.52
      access_ip: 192.168.122.52
  children:
    kube_control_plane:
      hosts:
        ks-cp1:
    kube_node:
      hosts:
        ks-worker1:
        ks-worker2:
    etcd:
      hosts:
        ks-cp1:
    k8s_cluster:
      children:
        kube_control_plane:
        kube_node:
    calico_rr:
      hosts: {}

Cinq groupes structurent l'inventaire, et leurs noms sont imposés par Kubespray. kube_control_plane désigne les nœuds qui hébergent l'API server, le scheduler et le controller-manager. kube_node liste les workers, où tournent vos applications. etcd porte les membres de la base, souvent les mêmes machines que le control plane en lab. k8s_cluster est un groupe parent qui réunit les deux premiers, pratique pour les variables communes. Et calico_rr, vide par défaut, ne sert qu'aux très grands clusters qui ont besoin de réflecteurs de route.

Tester la connectivité Ansible

Avant le déploiement, vérifiez que Ansible peut se connecter à tous les nœuds :

ansible all -i inventory/mycluster/hosts.yaml -m ping -u kube

Résultat attendu :

ks-cp1 | SUCCESS => { "ping": "pong" }
ks-worker1 | SUCCESS => { "ping": "pong" }
ks-worker2 | SUCCESS => { "ping": "pong" }

Personnalisation (optionnel)

Avant de déployer, vous pouvez ajuster les paramètres dans inventory/mycluster/group_vars/.

Ce que vous pouvez changer sans risque

Toutes les variables de Kubespray ne se valent pas. Celles qui suivent s'ajustent sans conséquence structurelle, parce qu'elles ne changent ni le plugin réseau ni le runtime : c'est le terrain sûr pour une première personnalisation.

Éditez inventory/mycluster/group_vars/k8s_cluster/k8s-cluster.yml :

# Version Kubernetes (dans la plage supportée par votre release Kubespray)
kube_version: v1.34.3

# Nom DNS du cluster
cluster_name: cluster.local

Ce qui mérite un guide dédié

Deux variables ressemblent à de simples choix dans une liste mais engagent en réalité toute l'architecture du cluster : le plugin réseau (kube_network_plugin) et le runtime de conteneurs (container_manager). Les modifier après un premier déploiement impose une réinstallation complète.

Attention à une illusion de simplicité : passer de Calico à Cilium, ou de containerd à CRI-O, n'est pas un simple interrupteur. Chaque option traîne ses propres variables, prérequis et comportements ; Cilium, par exemple, réclame des valeurs précises pour k8sServiceHost et k8sServicePort. Pour ce lab, gardez les valeurs par défaut, Calico et containerd, et consultez la documentation dédiée avant d'en changer sur un vrai cluster.

Options de référence

Ces sept variables sont celles que l'on consulte le plus souvent. Les deux dernières méritent une attention particulière : les plages d'adresses des pods et des services doivent rester disjointes du réseau de vos VMs, faute de quoi le routage devient imprévisible. Les valeurs par défaut conviennent au réseau libvirt 192.168.122.0/24 utilisé ici.

Variable	Fichier	Valeur par défaut	Description
`kube_version`	k8s-cluster.yml	v1.34.3	Version Kubernetes
`kube_network_plugin`	k8s-cluster.yml	calico	CNI, garder par défaut en lab
`container_manager`	k8s-cluster.yml	containerd	Runtime, containerd est le standard actuel
`kube_proxy_mode`	k8s-cluster.yml	ipvs	Mode kube-proxy (iptables, ipvs)
`cluster_name`	k8s-cluster.yml	cluster.local	Nom DNS du cluster
`kube_pods_subnet`	k8s-cluster.yml	10.233.64.0/18	CIDR des pods
`kube_service_addresses`	k8s-cluster.yml	10.233.0.0/18	CIDR des services

Déploiement du cluster

Le déploiement s'effectue avec le playbook cluster.yml. Comptez 10-20 minutes selon votre connexion Internet (téléchargement des images) :

ansible-playbook -i inventory/mycluster/hosts.yaml cluster.yml \
  -u kube -b --become-user=root

Quatre options d'ansible-playbook méritent d'être connues avant le premier déploiement. -v et -vvv augmentent le niveau de détail, le second étant réservé au débogage tant il est bavard. --limit ks-worker2 restreint l'exécution à un nœud, ce qui évite de tout rejouer pour corriger une seule machine. Et --tags download ne joue que les tâches de téléchargement, utile pour préparer un environnement à bande passante limitée.

Progression attendue

Un déploiement Kubespray n'affiche aucune barre de progression, et son silence apparent inquiète la première fois. Les repères ci-dessous donnent l'ordre de grandeur : tant que les tâches défilent, même lentement, le déploiement avance.

Le playbook exécute plusieurs phases :

Préparation : configuration système, désactivation swap, modules kernel
Téléchargement : binaires (kubectl, kubeadm, kubelet) et images conteneurs
etcd : installation et configuration du cluster etcd
Control plane : initialisation avec kubeadm, certificats
Workers : jointure au cluster
Réseau : déploiement de Calico (ou CNI choisi)
Addons : CoreDNS, metrics-server (si activé)

Exemple de sortie finale

Ansible termine par un récapitulatif par hôte. Le compteur skipped élevé est normal : Kubespray couvre de nombreuses distributions et options, et saute toutes les tâches qui ne correspondent pas à votre configuration.

PLAY RECAP *********************************************************************
ks-cp1         : ok=624  changed=135  unreachable=0  failed=0  skipped=1090
ks-worker1     : ok=413  changed=82   unreachable=0  failed=0  skipped=640
ks-worker2     : ok=413  changed=82   unreachable=0  failed=0  skipped=636

failed=0 sur tous les nœuds indique un déploiement réussi.

Validation du cluster

Un failed=0 signifie que les playbooks se sont exécutés, pas que le cluster fonctionne. La validation se fait en quatre temps, du plus structurel au plus applicatif : récupérer le kubeconfig, vérifier que les nœuds sont Ready, contrôler les pods système, puis déployer une application de test. Les nœuds ne passent Ready qu'une fois le plugin réseau opérationnel : c'est le signal que le CNI a bien démarré.

Récupérer le kubeconfig

Le fichier kubeconfig se trouve sur le control plane. Récupérez-le sur votre poste :

# Méthode simple avec scp (recommandée)
ssh kube@192.168.122.50 "sudo cat /etc/kubernetes/admin.conf" > ~/.kube/kubespray-config

# Remplacer l'adresse localhost par l'IP du control plane
sed -i 's/127.0.0.1/192.168.122.50/g' ~/.kube/kubespray-config

# Configurer kubectl
export KUBECONFIG=~/.kube/kubespray-config

Le kubeconfig produit par Kubespray pointe sur 127.0.0.1:6443, ce qui a du sens depuis le control plane et aucun depuis votre poste. Remplacez cette adresse par celle du control plane, 192.168.122.50 dans ce lab, faute de quoi kubectl tentera de joindre votre propre machine et échouera sur un refus de connexion.

Vérifier les nœuds

L'option -o wide ajoute trois colonnes déterminantes : l'IP interne, qui doit correspondre à celle de l'inventaire, l'image système et le runtime effectivement utilisé. Un nœud en NotReady juste après le déploiement pointe presque toujours vers le plugin réseau.

kubectl get nodes -o wide

Sortie attendue :

NAME         STATUS   ROLES           AGE   VERSION   INTERNAL-IP      OS-IMAGE             RUNTIME
ks-cp1       Ready    control-plane   19m   v1.34.3   192.168.122.50   Ubuntu 24.04.3 LTS   containerd://2.2.1
ks-worker1   Ready    <none>          19m   v1.34.3   192.168.122.51   Ubuntu 24.04.3 LTS   containerd://2.2.1
ks-worker2   Ready    <none>          19m   v1.34.3   192.168.122.52   Ubuntu 24.04.3 LTS   containerd://2.2.1

Les trois nœuds doivent être Ready.

Vérifier les pods système

Tous les composants d'infrastructure tournent dans le namespace kube-system. Le tableau qui suit liste ce que Kubespray installe avec les valeurs par défaut de ce guide, y compris deux ajouts qui lui sont propres : nodelocaldns, un cache DNS local sur chaque nœud, et nginx-proxy, qui relaie les appels à l'API server depuis les workers.

kubectl get pods -A

Tous les pods doivent être Running :

Namespace	Pods attendus
kube-system	calico-node (3), calico-kube-controllers
kube-system	coredns (2), dns-autoscaler
kube-system	kube-apiserver, kube-controller-manager, kube-scheduler
kube-system	kube-proxy (3), nodelocaldns (3)
kube-system	nginx-proxy (workers uniquement)

Test de déploiement applicatif

Validez que vous pouvez déployer une application :

# Créer un déploiement nginx
kubectl create deployment nginx --image=nginx:1.30@sha256:d5792f71a9496b833bc08ea834a758c46e2b6a6306c10f4be926f38a656cdc1c

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

# Attendre que le pod soit prêt
kubectl wait --for=condition=Ready pod -l app=nginx --timeout=60s

# Vérifier
kubectl get pods,svc

Résultat attendu :

NAME                         READY   STATUS    RESTARTS   AGE
pod/nginx-6f564d4fd9-xxxxx   1/1     Running   0          30s

NAME                 TYPE        CLUSTER-IP      PORT(S)        AGE
service/kubernetes   ClusterIP   10.233.0.1      443/TCP        20m
service/nginx        NodePort    10.233.33.101   80:30965/TCP   10s

Le service nginx est accessible sur http://<IP_WORKER>:30965.

Nettoyez après le test :

kubectl delete deployment nginx
kubectl delete svc nginx

Test DNS et connectivité inter-pods

Le test nginx valide peu de choses. Pour vérifier la résolution DNS et la connectivité inter-pods :

# Lancer un pod de test
kubectl run dnstest --image=busybox:1.37@sha256:9db7b59979c38555a39def84a31fb98b5296952f9e3afd4f6f11f05b07adfab0 --rm -it --restart=Never -- \
  nslookup kubernetes.default.svc.cluster.local

Résultat attendu : une adresse IP dans le range 10.233.0.x (service ClusterIP).

Kubespray propose un module de validation continue, Netchecker, qui vérifie en permanence la connectivité entre Pods et la résolution DNS. Il s'active avec deploy_netchecker: true dans les variables, avant le déploiement. C'est une option utile sur un cluster dont le réseau doit être surveillé de près.

Dépannage

Les échecs de déploiement Kubespray se répartissent en deux familles distinctes. Ceux qui surviennent avant la première tâche relèvent d'Ansible et de l'accès SSH ; ceux qui surviennent en cours de route relèvent du cluster lui-même. Le message d'Ansible indique toujours la tâche exacte qui a échoué et sur quel hôte : c'est le point de départ du diagnostic.

Le déploiement échoue avec "UNREACHABLE"

Ansible ne peut pas se connecter aux VMs :

# Vérifier la connectivité SSH
ssh -v kube@192.168.122.50

# Vérifier que la clé est autorisée
ssh kube@192.168.122.50 "cat ~/.ssh/authorized_keys"

# Vérifier que Python est installé
ansible all -i inventory/mycluster/hosts.yaml -m raw -a "which python3" -u kube

Erreur "Unable to connect to the server"

C'est l'erreur la plus fréquente après un déploiement pourtant réussi, et elle n'a rien à voir avec le cluster : elle vient du kubeconfig, qui pointe encore sur une adresse inaccessible depuis votre poste.

kubectl ne peut pas joindre l'API server :

# Vérifier que l'adresse est correcte dans kubeconfig
grep server ~/.kube/kubespray-config

# Tester la connectivité réseau
nc -zv 192.168.122.50 6443

# Vérifier que l'API server tourne
ssh kube@192.168.122.50 "sudo crictl ps | grep kube-apiserver"

Pods bloqués en "Pending"

Généralement un problème de ressources ou de taints :

# Décrire le pod pour voir les événements
kubectl describe pod <pod-name>

# Vérifier les ressources disponibles
kubectl describe nodes | grep -A5 "Allocated resources"

# Vérifier les taints
kubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints

Relancer un déploiement partiel

Si le déploiement a échoué à mi-chemin, relancez simplement la même commande. Ansible est idempotent et reprendra où il s'est arrêté :

ansible-playbook -i inventory/mycluster/hosts.yaml cluster.yml \
  -u kube -b --become-user=root

Opérations courantes

Une fois le cluster en place, Kubespray reste le point d'entrée pour le faire évoluer : chaque opération a son playbook dédié, et aucune ne doit être menée à la main sur les nœuds. La règle qui vaut pour les trois opérations ci-dessous : mettez toujours à jour hosts.yaml avant de lancer le playbook, l'inventaire étant la source de vérité de tout le reste.

Ajouter un worker

Le playbook scale.yml n'agit que sur les nœuds absents du cluster : il est donc sûr à relancer. L'option --limit restreint l'exécution à la nouvelle machine et évite de retoucher aux nœuds existants.

Provisionner la nouvelle VM avec cloud-init
Ajouter l'entrée dans hosts.yaml sous kube_node
Exécuter le playbook scale.yml :

ansible-playbook -i inventory/mycluster/hosts.yaml scale.yml \
  -u kube -b --become-user=root --limit=nouveau-worker

Supprimer un nœud

Kubespray fournit un playbook dédié pour la suppression propre :

# Méthode recommandée : playbook remove-node
ansible-playbook -i inventory/mycluster/hosts.yaml remove-node.yml \
  -u kube -b --become-user=root \
  -e "node=ks-worker2"

Ce playbook effectue automatiquement le drain, la suppression des composants Kubernetes sur le nœud et le nettoyage. Après exécution, retirez manuellement le nœud de votre fichier hosts.yaml.

Mettre à jour Kubernetes

upgrade-cluster.yml traite les nœuds un par un en les drainant au préalable, ce qui permet de garder le service disponible si vos applications ont plusieurs réplicas. Comptez nettement plus de temps que le déploiement initial, et lisez l'encadré ci-dessous avant de choisir la version cible : les sauts autorisés sont limités.

Modifier kube_version dans group_vars/k8s_cluster/k8s-cluster.yml
Exécuter le playbook upgrade-cluster.yml :

ansible-playbook -i inventory/mycluster/hosts.yaml upgrade-cluster.yml \
  -u kube -b --become-user=root

Nettoyage du cluster

Kubespray ayant installé des composants sur chaque machine, il faut le laisser les retirer lui-même : supprimer les VM ou les nœuds côté Kubernetes ne suffit pas, et laisse des services actifs derrière soi. Les playbooks dédiés font ce travail proprement.

Pour supprimer complètement Kubernetes des nœuds :

ansible-playbook -i inventory/mycluster/hosts.yaml reset.yml \
  -u kube -b --become-user=root

Ce playbook défait l'installation sur les machines, sans les détruire. Il enchaîne quatre nettoyages, et aucun n'est réversible :

Arrête et supprime tous les conteneurs
Supprime les binaires Kubernetes
Nettoie les règles iptables posées par le cluster
Supprime les fichiers de configuration

Pour supprimer aussi les VMs :

for vm in ks-cp1 ks-worker1 ks-worker2; do
  sudo virsh destroy ${vm}
  sudo virsh undefine ${vm} --remove-all-storage
done

À retenir

Kubespray industrialise le déploiement de clusters Kubernetes :

Infrastructure as Code : votre cluster est défini dans des fichiers YAML versionnables
Reproductibilité : le même inventory produit le même cluster à chaque exécution
Automatisation : upgrades, scaling, suppression de nœuds via playbooks dédiés
Base solide : ce lab constitue un socle pour des déploiements plus robustes

Ce guide vous a permis de déployer un lab reproductible. Pour passer en production, il faut encore :

3 control planes + load balancer devant l'API server
Backup etcd externalisé et testé régulièrement
Monitoring, alerting et logs centralisés
Sécurité réseau (NetworkPolicies, firewall configuré)
Plan de reprise d'activité (PRA) documenté

Contrôle de connaissances

Sept questions sur ce qui fait la spécificité de Kubespray et sur les préconditions qui font échouer un déploiement : le swap, le routage IPv4 et la mémoire des nœuds.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

7 questions

5 min.

80% requis

Informations

Le chronomètre démarre au clic sur Démarrer
Questions à choix multiples, vrai/faux et réponses courtes
Vous pouvez naviguer entre les questions
Les résultats détaillés sont affichés à la fin

Pour aller plus loin

Backup et Restore : La sauvegarde d'etcd sur un cluster déployé par Kubespray.
Troubleshooting cluster : Le diagnostic d'un cluster dont un playbook s'est interrompu en cours de route.
Mettre à jour un cluster : La montée de version, opération que Kubespray automatise mais ne dispense pas de préparer.

Déployer Kubernetes avec Kubespray

Kubespray vs autres solutions

Ce que vous allez apprendre

Prérequis

Ressources matérielles

Logiciels requis

Versions validées dans ce guide

Création des machines virtuelles

Architecture cible

Préparer l'image cloud Ubuntu 24.04

Configuration cloud-init

Configurer le réseau statique

Création des VMs

Installation de Kubespray

Cloner le repository

Créer l'environnement Python

Configuration de l'inventaire

Copier le template

Créer le fichier hosts.yaml

Tester la connectivité Ansible

Personnalisation (optionnel)

Ce que vous pouvez changer sans risque

Ce qui mérite un guide dédié

Options de référence

Déploiement du cluster

Progression attendue

Exemple de sortie finale

Validation du cluster

Récupérer le kubeconfig

Vérifier les nœuds

Vérifier les pods système

Test de déploiement applicatif

Test DNS et connectivité inter-pods

Dépannage

Le déploiement échoue avec "UNREACHABLE"

Erreur "Unable to connect to the server"

Pods bloqués en "Pending"

Relancer un déploiement partiel

Opérations courantes

Ajouter un worker

Supprimer un nœud

Mettre à jour Kubernetes

Nettoyage du cluster

À retenir

Contrôle de connaissances

Contrôle de connaissances

Informations

Profil de compétences

Quoi faire maintenant

Pour aller plus loin