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.

Lab vs Production

Ce guide déploie un cluster 1 control plane + 2 workers suffisant pour apprendre et expérimenter. Pour un environnement de production, il faudrait ajouter :

• 3 control planes avec load balancer devant l’API server
• Backup etcd externalisé et testé
• Monitoring et alerting
• Sécurité réseau (NetworkPolicies, firewall)

Kubespray vs kubeadm

Pour la CKA, kubeadm reste indispensable car l’examen attend des commandes manuelles. Kubespray est préférable pour les déploiements automatisés en entreprise.

Kubespray vs autres solutions

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

Glissez pour voir

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

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

Glissez pour voir

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.

RAM critique

Kubespray télécharge les binaires et images sur chaque nœud en parallèle. Avec moins de 2 Go de RAM par VM, vous risquez des échecs OOM (Out Of Memory) pendant le déploiement.

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)

Préconditions souvent oubliées

• Forwarding IPv4 doit être autorisé sur les nœuds (net.ipv4.ip_forward = 1)
• Kubespray ne gère pas vos firewalls — en lab, désactivez-les ou ouvrez les ports requis avant le déploiement
• En environnement proxy ou offline, préparez explicitement les registries miroirs et variables proxy

Versions validées dans ce guide

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

Composant	Version
Kubespray	v2.26.0
Kubernetes	v1.30.4
Ansible	core 2.16.x
CNI	Calico (plugin par défaut)

Glissez pour voir

Vérifiez toujours les versions

Consultez le README et les release notes avant de changer de version. Le projet Kubespray évolue rapidement et la compatibilité entre versions n’est pas toujours triviale.

Utiliser une release taggée

Utilisez toujours une release taggée (v2.26.0) plutôt que la branche master. La branche master peut contenir des changements incompatibles et n’est pas recommandée pour les environnements qui doivent rester stables.

Création des machines virtuelles

Architecture cible

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

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 :

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

# Si absente, télécharger
sudo curl -L -o /var/lib/libvirt/images/ubuntu-24.04-cloud.img \
  https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img

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 :

user-data

#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

Désactivation du swap obligatoire

Le swap doit être désactivé pour que kubelet fonctionne. Les commandes swapoff -a et la suppression de l’entrée dans /etc/fstab garantissent que le swap reste désactivé après un reboot.

Configurer le réseau statique

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

network-config (exemple pour ks-cp1)

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

Nom de l'interface réseau

Le nom enp1s0 est courant avec KVM/libvirt, mais peut varier selon l’image cloud et l’hyperviseur. Vérifiez le nom d’interface attendu dans votre image ou utilisez ip link après un premier boot en DHCP.

Création des VMs

1. 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

2. 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

3. 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

4. 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

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.26.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.16.x] pour Kubespray v2.26.0.

Configuration de l’inventaire

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 :

inventory/mycluster/hosts.yaml

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: {}

Structure de l'inventaire

• kube_control_plane : nœuds hébergeant l’API server, scheduler, controller-manager
• kube_node : nœuds workers où tournent les pods applicatifs
• etcd : nœuds hébergeant etcd (souvent colocalisés avec control_plane en lab)
• k8s_cluster : groupe parent incluant control plane + workers
• calico_rr : route reflectors Calico (vide par défaut, utilisé pour les grands clusters)

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

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

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

# Nom DNS du cluster
cluster_name: cluster.local

Ce qui mérite un guide dédié

Changement de CNI ou runtime

Changer le plugin réseau (Calico → Cilium) ou le runtime (containerd → cri-o) n’est pas un simple toggle. Chaque option a ses propres variables, prérequis et comportements. Par exemple, Cilium nécessite des paramètres spécifiques pour k8sServiceHost et k8sServicePort.

Pour ce lab, gardez les valeurs par défaut (Calico + containerd). Consultez la documentation Kubespray dédiée si vous avez besoin d’un CNI différent.

Options de référence

Variable	Fichier	Valeur par défaut	Description
kube_version	k8s-cluster.yml	v1.30.4	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

Glissez pour voir

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

Options utiles

• -v : mode verbose (plus de détails)
• -vvv : mode très verbose (débogage)
• --limit ks-worker2 : exécuter sur un nœud spécifique seulement
• --tags download : exécuter uniquement les tâches de téléchargement

Progression attendue

Le playbook exécute plusieurs phases :

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

Exemple de sortie finale

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

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

Modification de l'adresse API

Le kubeconfig par défaut pointe vers 127.0.0.1:6443. Vous devez remplacer cette adresse par l’IP du control plane (192.168.122.50) pour accéder au cluster depuis votre poste.

Vérifier les nœuds

kubectl get nodes -o wide

Sortie attendue :

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

Les trois nœuds doivent être Ready.

Vérifier les pods système

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)

Glissez pour voir

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:alpine

# 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.36 --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).

Netchecker pour validation complète

Kubespray propose Netchecker, un addon qui vérifie en continu la connectivité inter-pods et la résolution DNS. Pour l’activer, définissez deploy_netchecker: true dans vos variables avant le déploiement.

Dépannage

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”

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

Ajouter un worker

1. Provisionner la nouvelle VM avec cloud-init
2. Ajouter l’entrée dans hosts.yaml sous kube_node
3. 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.

Ne pas seulement kubectl delete

Un simple kubectl drain + kubectl delete node ne nettoie pas les composants Kubernetes installés sur la VM. Utilisez toujours le playbook remove-node.yml pour une suppression propre.

Mettre à jour Kubernetes

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

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

Règles d'upgrade critiques

Version skew Kubernetes : saut de 1 version mineure maximum (ex: 1.29 → 1.30). Pour passer de 1.28 à 1.30, faites deux upgrades successifs.

Version skew Kubespray : ne sautez pas directement d’une vieille release Kubespray à la dernière. La documentation officielle indique explicitement que c’est unsupported. Vérifiez le chemin d’upgrade recommandé dans les release notes avant toute mise à jour.

Nettoyage du cluster

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 :

• Arrête et supprime tous les conteneurs
• Supprime les binaires Kubernetes
• Nettoie les règles iptables
• 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é

Prochaines étapes

Comprendre le control plane Architecture des composants master

Backup et restore Sauvegarde etcd et restauration de cluster

Troubleshooting Kubernetes Diagnostic et résolution des problèmes

×

📖 Voir la documentation →