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	Écart autorisé face à kube-apiserver
kube-apiserver	composant de référence. En HA, les instances se mettent à jour une par une.
kubelet	jamais plus récent, jusqu'à trois versions mineures plus ancien
kube-proxy	jamais plus récent, jusqu'à trois versions mineures plus ancien
kube-controller-manager / kube-scheduler	jamais plus récents, jusqu'à une version mineure plus anciens
kubectl	une version mineure d'écart, plus récente ou plus ancienne

Glissez pour voir

Deux points de cette table expliquent à eux seuls la stratégie d'upgrade. Le premier est l'asymétrie : un kubelet peut prendre du retard, jamais de l'avance. Le second est la taille de la fenêtre, trois versions pour les nœuds contre une seule pour kubectl. C'est ce qui rend possible la mise à jour en deux temps, et un kubelet en retard sur son API server est une situation supportée, pas une anomalie à corriger dans l'heure.

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 tolérance d'écart de version autorise à mettre à jour le control plane en premier, puis les workers progressivement, même sur un cluster de nombreux nœuds. Consultez toujours la version skew policy officielle pour les fenêtres de compatibilité exactes, avant de commencer.

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

Un upgrade de cluster ne se défait pas : la seule marche arrière est une restauration d'etcd, avec la perte de tout ce qui a changé depuis la sauvegarde. Les trois vérifications ci-dessous ne sont donc pas des formalités, ce sont les seules choses qui vous resteront si l'opération se passe mal.

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 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, avec etcdutl et non etcdctl : ce dernier affiche l'aide et sort en 0 sans rien vérifier, ce qui donne une sauvegarde réputée bonne sans qu'elle ait été lue.

etcdutl snapshot status /tmp/etcd-backup-pre-upgrade.db --write-out=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

Lisez les notes de version pour les suppressions d'API, et pas seulement pour les nouveautés. C'est le point qui casse des déploiements sans prévenir : un manifeste qui référence une version d'API retirée est refusé après l'upgrade, alors qu'il fonctionnait la veille. L'outil kubent ou kubectl-convert permet de repérer ces références avant de basculer.

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

Cette étape ne modifie rien : elle interroge le cluster et affiche les versions atteignables ainsi que les composants qui seront touchés. C'est aussi le moment où kubeadm signale les incompatibilités qu'il détecte, avant que quoi que ce soit ne soit engagé.

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 des composants qu'il gère : 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, aucune charge applicative n'y tourne, grâce au taint NoSchedule posé sur ces nœuds. Ailleurs, traitez-le comme n'importe quel nœud hébergeant des Pods.

Autres control planes

Pour les control planes supplémentaires d'un cluster en haute disponibilité, la procédure est la même à un détail près : c'est kubeadm upgrade node qu'on lance, pas 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.

Les deux sous-commandes ne font pas le même travail et ne s'emploient pas au même endroit. kubeadm upgrade apply ne se lance qu'une fois, sur le premier nœud du control plane : c'est lui qui décide de la version cible et met à jour les composants du plan de contrôle. kubeadm upgrade node se lance ensuite sur chacun des autres nœuds, control plane comme workers, et se contente d'aligner la configuration locale sur la décision déjà prise.

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 provoque 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:1.28@sha256:146adea4768b83c607d0bdfa4188464e3da6e0a3ad4475db1d1d8f64f27c29cc --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

Les trois situations ci-dessous se classent par gravité croissante, et la réponse n'est pas la même. Un upgrade apply qui refuse de démarrer n'a rien cassé ; un kubelet qui ne repart pas laisse un nœud hors service ; une restauration d'etcd fait perdre tout ce qui a changé depuis la sauvegarde. Essayez toujours dans cet ordre.

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 :

etcdutl 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

Ces symptômes se rencontrent pendant l'opération, au moment où le cluster est dans un état intermédiaire. Les avoir lus à froid vaut mieux que de les découvrir avec un nœud à moitié mis à jour et une fenêtre de maintenance qui se referme.

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.

Contrôle de connaissances

Sept questions sur ce qui ne se rattrape pas : les chiffres exacts de la tolérance d'écart de version, l'ordre imposé qui en découle, et le fait qu'une montée de version ne se défait pas.

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

Démarrer le quiz

Lance le quiz et démarre le chronomètre

Pour aller plus loin

• Garantir la disponibilité applicative : Les PodDisruptionBudgets qui empêchent une montée de version de couper le service.
• SRE et exploitation Kubernetes : Le budget d'erreur qui aide à choisir la fenêtre de mise à jour.
• Routine d'exploitation : Le suivi régulier des versions et des dépréciations entre deux montées de version.

×

📖 Voir la documentation →