Mettre à jour un cluster Kubernetes sans interruption

Pour mettre à jour un cluster Kubernetes, respectez toujours le même ordre : control plane d’abord, workers ensuite, un nœud à la fois. Ce guide détaille la stratégie d’upgrade, la version skew policy qui définit les écarts de version autorisés entre composants, et le workflow complet avec kubeadm upgrade — de la planification à la vérification post-upgrade.

Ce que vous allez apprendre

• Comprendre la version skew policy : quels écarts de version sont autorisés
• Suivre l’ordre correct de mise à jour des composants
• Exécuter un upgrade complet avec kubeadm : plan, apply, drain, uncordon
• Mettre à jour les worker nodes un par un sans interruption
• Vérifier le cluster après l’upgrade et gérer les cas d’échec

Prérequis

• Un cluster Kubernetes fonctionnel déployé avec kubeadm (v1.28+)
• kubectl configuré avec des droits cluster-admin
• Accès SSH root (ou sudo) à tous les nœuds du cluster
• Avoir suivi les guides :
  • Observer la santé du cluster
  • Préparer une maintenance
  • Gérer les nœuds
• Connaissances de base sur kubeadm

Pourquoi la mise à jour est critique

Kubernetes publie trois versions mineures par an (environ tous les 4 mois). Le projet maintient les trois dernières versions mineures, avec environ un an de support de patch pour les versions 1.19 et suivantes.

Rester sur une version obsolète expose votre cluster à :

• Des vulnérabilités non corrigées (CVE)
• L’incompatibilité avec les nouvelles versions des outils (Helm, Istio, opérateurs)
• La perte du support technique des fournisseurs cloud

La bonne stratégie : mettre à jour une version mineure à la fois (par exemple 1.33 → 1.34, puis 1.34 → 1.35). Sauter des versions n’est pas supporté par kubeadm.

Une version à la fois

kubeadm ne supporte l’upgrade que d’une seule version mineure à la fois. Pour passer de la 1.32 à la 1.34, vous devez d’abord upgrader en 1.33, puis en 1.34. Chaque étape suit le même workflow.

Comprendre la version skew policy

La version skew policy définit les écarts de version autorisés entre les composants Kubernetes. C’est la règle fondamentale à connaître avant tout upgrade.

Règles principales

Composant	Principe
kube-apiserver	Composant de référence pour la compatibilité. En HA, les instances doivent rester dans la fenêtre définie par la skew policy.
kubelet	Peut rester temporairement plusieurs versions mineures derrière l’API server selon la skew policy.
kube-controller-manager / kube-scheduler	Doivent rester proches des versions des API servers pendant la transition.
kubectl	Doit rester dans la fenêtre de compatibilité officielle ; en pratique, gardez-le aligné ou très proche de la version du cluster.
kube-proxy	Suivre la skew policy officielle ; ne pas supposer qu’il suit simplement le kubelet.

Glissez pour voir

Dans un control plane HA, les instances de kube-apiserver doivent être mises à jour une par une en limitant l’écart de version entre elles. Les autres composants doivent rester compatibles avec l’instance la plus ancienne et la plus récente pendant la transition.

En pratique

La skew policy permet de mettre à jour le control plane en premier, puis les workers progressivement — même sur un cluster avec beaucoup de nœuds. Consultez toujours la version skew policy officielle pour les fenêtres de compatibilité exactes avant un upgrade.

Ordre de mise à jour avec kubeadm

Avec kubeadm, la mise à jour commence par le control plane via kubeadm upgrade apply, qui gère les composants du plan de contrôle (API server, controller-manager, scheduler) ainsi que etcd et les addons lorsqu’ils sont administrés par kubeadm. Si etcd est géré séparément, sa stratégie de compatibilité doit être vérifiée à part.

Ensuite, les workers sont mis à jour un par un avec kubeadm upgrade node, suivi de la mise à jour de kubelet.

Enfin, mettez à jour kubectl sur vos postes d’administration.

Avant l’upgrade : préparation

Vérifier l’état du cluster

Assurez-vous que le cluster est sain avant de commencer :

kubectl get nodes
kubectl get pods -A | grep -v Running | grep -v Completed

Tous les nœuds doivent être Ready. Aucun pod critique ne doit être en erreur.

Sauvegarder etcd

Une sauvegarde etcd est indispensable avant un upgrade. En cas de problème, elle permet de restaurer le cluster dans son état précédent.

ETCDCTL_API=3 etcdctl snapshot save /tmp/etcd-backup-pre-upgrade.db \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key

Vérification :

ETCDCTL_API=3 etcdctl snapshot status /tmp/etcd-backup-pre-upgrade.db --write-table

Pour un guide complet sur la sauvegarde, consultez Backup et restauration de cluster.

Lire les notes de version

Avant chaque upgrade, consultez les notes de version officielles Kubernetes. Vérifiez :

• Les breaking changes et APIs dépréciées
• Les nouvelles fonctionnalités qui passent en GA (stable)
• Les prérequis spécifiques à la version

APIs dépréciées

Kubernetes supprime régulièrement des versions d’API. Avant un upgrade, vérifiez que vos manifests n’utilisent pas d’APIs supprimées dans la version cible. L’outil kubectl convert ou pluto peut identifier ces incompatibilités.

Upgrade du control plane (kubeadm)

L’upgrade se fait sur le premier nœud control plane d’abord, puis sur les éventuels autres nœuds control plane.

Premier control plane

Étape 1 : mettre à jour kubeadm

Sur le nœud control plane, mettez à jour le paquet kubeadm vers la version cible :

# Ubuntu / Debian
sudo apt-mark unhold kubeadm
sudo apt-get update && sudo apt-get install -y kubeadm=1.35.0-1.1
sudo apt-mark hold kubeadm

Vérification :

kubeadm version

Étape 2 : planifier l’upgrade

sudo kubeadm upgrade plan

Cette commande affiche :

• La version actuelle du cluster
• La version cible disponible
• Les composants qui seront mis à jour
• Les éventuels avertissements (APIs dépréciées, etc.)

Lisez attentivement la sortie avant de continuer.

Étape 3 : appliquer l’upgrade

sudo kubeadm upgrade apply v1.35.0

kubeadm upgrade apply met à jour les composants du control plane sur le nœud ciblé et applique, selon la configuration du cluster, les mises à jour planifiées des composants gérés comme CoreDNS, kube-proxy et etcd.

Étape 4 : mettre à jour kubelet et kubectl

# Drainer le nœud
kubectl drain ks-cp1 --ignore-daemonsets

# Mettre à jour les paquets
sudo apt-mark unhold kubelet kubectl
sudo apt-get update && sudo apt-get install -y kubelet=1.35.0-1.1 kubectl=1.35.0-1.1
sudo apt-mark hold kubelet kubectl

# Redémarrer kubelet
sudo systemctl daemon-reload
sudo systemctl restart kubelet

# Remettre le nœud en service
kubectl uncordon ks-cp1

Le drain d’un nœud control plane dépend de votre architecture. Dans beaucoup de clusters, les workloads applicatifs n’y tournent pas (taint NoSchedule du control plane). Dans d’autres environnements, traitez ce nœud comme tout autre nœud hébergeant des Pods.

Autres control planes

Pour les nœuds control plane supplémentaires (si votre cluster est en HA), la procédure est similaire mais utilise kubeadm upgrade node au lieu de kubeadm upgrade apply :

# Sur le nœud CP supplémentaire :
sudo apt-mark unhold kubeadm
sudo apt-get update && sudo apt-get install -y kubeadm=1.35.0-1.1
sudo apt-mark hold kubeadm

sudo kubeadm upgrade node

Puis mettez à jour kubelet/kubectl et redémarrez comme pour le premier nœud.

kubeadm upgrade apply vs node

kubeadm upgrade apply met à jour le control plane complet (API server, controller-manager, scheduler, etcd, CoreDNS). Il ne doit être exécuté que sur le premier nœud control plane. Les autres nœuds CP utilisent kubeadm upgrade node qui met à jour uniquement la configuration kubelet locale.

Upgrade des worker nodes

Les workers se mettent à jour un par un pour éviter toute interruption de service. Pour chaque worker, le workflow est identique.

1. Mettre à jour kubeadm sur le worker :

   sudo apt-mark unhold kubeadm
   sudo apt-get update && sudo apt-get install -y kubeadm=1.35.0-1.1
   sudo apt-mark hold kubeadm

2. Appliquer la configuration :

   sudo kubeadm upgrade node

3. Drainer le worker (depuis un poste d’administration) :

   kubectl drain ks-worker1 --ignore-daemonsets --delete-emptydir-data

4. Mettre à jour kubelet et kubectl :

   sudo apt-mark unhold kubelet kubectl
   sudo apt-get update && sudo apt-get install -y kubelet=1.35.0-1.1 kubectl=1.35.0-1.1
   sudo apt-mark hold kubelet kubectl
   
   sudo systemctl daemon-reload
   sudo systemctl restart kubelet

5. Remettre le worker en service :

   kubectl uncordon ks-worker1

6. Vérifier avant de passer au worker suivant :

   kubectl get nodes
   kubectl get pods -A -o wide | grep ks-worker1

Un nœud à la fois

Ne drainez jamais plusieurs workers en même temps. Si vos applications n’ont pas assez de réplicas, retirer deux nœuds simultanément peut provoquer une interruption de service. Attendez que chaque nœud soit Ready avant de passer au suivant.

Vérifications post-upgrade

Après avoir mis à jour tous les nœuds, vérifiez l’ensemble du cluster :

Versions des nœuds

kubectl get nodes

Tous les nœuds doivent afficher la même version :

NAME         STATUS   ROLES           AGE   VERSION
ks-cp1       Ready    control-plane   43h   v1.35.0
ks-worker1   Ready    worker          43h   v1.35.0
ks-worker2   Ready    worker          43h   v1.35.0

Pods système

kubectl get pods -n kube-system

Tous les pods du plan de contrôle doivent être Running.

Santé du plan de contrôle

Vérifiez la santé des composants via l’endpoint readyz de l’API server :

kubectl get --raw='/readyz?verbose' | grep '\[-\]\|\[\+\]'

Test fonctionnel rapide

Créez un pod de test pour valider que le cluster fonctionne :

kubectl run test-upgrade --image=nginx --restart=Never
kubectl get pod test-upgrade -w

Attendez que le pod passe en Running, puis nettoyez :

kubectl delete pod test-upgrade

Gérer un échec d’upgrade

kubeadm upgrade apply échoue

Si kubeadm upgrade apply échoue en cours de route, vous pouvez relancer la même commande en toute sécurité : elle est idempotente. Si le problème persiste, consultez les logs :

sudo journalctl -u kubelet -f
sudo crictl ps -a

Restaurer depuis la sauvegarde etcd

En dernier recours, si le cluster est dans un état incohérent après un upgrade raté, restaurez la sauvegarde etcd :

ETCDCTL_API=3 etcdctl snapshot restore /tmp/etcd-backup-pre-upgrade.db \
  --data-dir=/var/lib/etcd-restore

Puis remplacez le répertoire de données etcd et redémarrez les services. Consultez le guide Backup et restauration pour la procédure complète.

kubelet ne démarre pas après l’upgrade

Si le kubelet ne démarre pas sur un nœud après la mise à jour :

sudo journalctl -u kubelet -f --no-pager | tail -50

Causes fréquentes :

• Incompatibilité de version : vérifiez que les versions installées respectent la version skew policy et l’ordre d’upgrade recommandé par kubeadm
• Configuration obsolète : kubeadm upgrade node n’a pas été exécuté avant la mise à jour du kubelet
• Certificats : les certificats ont expiré (renouvelez avec kubeadm certs renew all)

Dépannage

Symptôme	Cause probable	Solution
kubeadm upgrade plan ne trouve pas la version	Repository apt/yum non mis à jour	apt-get update puis réessayer
Upgrade bloqué depuis 10+ minutes	Pull d’images lent ou timeout réseau	Vérifier la connectivité et pré-pull les images : kubeadm config images pull
Nœud reste en NotReady après upgrade	kubelet pas redémarré ou mauvaise version	systemctl restart kubelet ; vérifier kubelet --version
Pods en Pending après drain	Pas assez de ressources sur les nœuds restants	Vérifier les requests/limits ; uncordon d’abord puis re-drain
CoreDNS ne fonctionne plus	ConfigMap CoreDNS personnalisé écrasé	Restaurer la config depuis le backup ; vérifier kubectl -n kube-system get cm coredns
API server inaccessible après upgrade	Certificats expirés ou port occupé	sudo crictl logs <container-id> du conteneur kube-apiserver

Glissez pour voir

À retenir

• Mettez à jour une version mineure à la fois : 1.33 → 1.34, jamais 1.33 → 1.35 directement.
• L’ordre est strict : control plane d’abord (kubeadm upgrade apply), workers ensuite (kubeadm upgrade node), un nœud à la fois.
• La version skew policy définit les fenêtres de compatibilité entre composants. Consultez-la systématiquement avant un upgrade.
• Sauvegardez etcd avant chaque upgrade. C’est votre filet de sécurité.
• Lisez les notes de version pour anticiper les breaking changes et APIs supprimées.
• kubeadm upgrade apply est idempotent : en cas d’échec, relancez la même commande.
• Vérifiez le cluster après chaque nœud : kubectl get nodes, pods système, test fonctionnel.

Prochaines étapes

Sauvegarder et restaurer un cluster Backup etcd, restauration et plan de reprise

Préparer une maintenance de cluster Workflow cordon → drain → uncordon avec PDB

Gérer les nœuds au quotidien Labels, taints, rôles et remplacement de nœud

Observer la santé du cluster 5 commandes pour vérifier nœuds, pods et ressources

kubeadm Installation et gestion de cluster avec kubeadm

Hub Opérer Kubernetes Tous les guides d'exploitation au quotidien

×

📖 Voir la documentation →