Une API Kubernetes dépréciée continue de fonctionner normalement pendant une période annoncée à l’avance, généralement au moins un an ou trois versions mineures pour une API stable (v1), avant d’être définitivement retirée. Un manifeste qui référence une apiVersion déjà retirée ne dégrade rien progressivement : kubectl apply échoue immédiatement avec une erreur explicite, souvent au pire moment, lors d’une montée de version de cluster planifiée depuis des semaines.

Le rythme réel des dépréciations

Kubernetes garantit qu’une API stable (v1) reste disponible au moins 12 mois ou 3 versions mineures après l’annonce officielle de sa dépréciation, la plus longue des deux durées primant. Une API en version beta bénéficie d’une garantie plus courte (9 mois ou 3 versions mineures). Cette politique donne une fenêtre de migration réelle, mais seulement à condition de suivre les annonces de dépréciation, pas au moment où l’API a déjà disparu.

# Le message d'erreur au moment du retrait effectif,
# jamais un avertissement progressif avant coup
kubectl apply -f old-manifest.yaml
# error: resource mapping not found for name: "my-ingress"
# no matches for kind "Ingress" in version "networking.k8s.io/v1beta1"

Des retraits déjà survenus, pas seulement théoriques

extensions/v1beta1 et apps/v1beta1 ont disparu en 1.16 ; networking.k8s.io/v1beta1 pour Ingress en 1.22 ; policy/v1beta1 pour PodSecurityPolicy en 1.25 (retiré avec la fonctionnalité elle-même, remplacée par Pod Security Standards). Chaque montée de version majeure de cluster est l’occasion réelle où d’anciens manifestes, écrits des années plus tôt et jamais revisités, cessent brutalement de fonctionner.

Détecter avant l’upgrade, pas pendant

pluto, un outil dédié à cette détection, scanne un dépôt de manifestes ou un cluster en cours d’exécution pour repérer toute apiVersion dépréciée ou déjà retirée dans la version cible.

# Détecte les apiVersion dépréciées avant l'upgrade,
# pas au moment où l'apply échoue en pleine montée de version
pluto detect-files -d ./manifests

Exécuter cette détection avant toute planification de montée de version transforme un échec de dernière minute en correction anticipée, une étape aussi routinière que la vérification des breaking changes du changelog de version, mais bien plus souvent oubliée.

Convertir plutôt que réécrire à la main

kubectl convert (un plugin distinct, à installer séparément) traduit automatiquement un manifeste écrit dans une ancienne apiVersion vers son équivalent dans la version cible, quand la structure le permet.

# Conversion automatique vers la nouvelle apiVersion,
# plutôt qu'une réécriture manuelle champ par champ
kubectl convert -f old-manifest.yaml --output-version apps/v1

Cette conversion automatique ne couvre pas tous les cas : certains changements de version d’API modifient la structure ou le comportement par défaut d’un champ, ce qui exige une relecture manuelle même après conversion, pas une confiance aveugle dans l’outil.

À retenir

Une API Kubernetes dépréciée reste garantie fonctionnelle pendant une durée annoncée (12 mois ou 3 versions mineures pour une API stable), mais son retrait effectif casse immédiatement tout manifeste qui la référence encore, sans dégradation progressive préalable. pluto détecte ces dépendances avant une montée de version planifiée, plutôt que de découvrir le problème au moment de l’apply qui échoue ; kubectl convert automatise une partie de la migration, sans dispenser d’une relecture manuelle. Vérifier systématiquement les apiVersion utilisées avant toute montée de version majeure fait partie des réflexes qui distinguent une migration Kubernetes planifiée d’un upgrade qui casse en production sans avertissement.