Kubernetes 1.37 active par défaut la migration des versions de stockage et enterre les scripts maison

31 août 2026. Michael Aspinwall, ingénieur chez Google, annonce sur le blog officiel que la migration des versions de stockage (storage version migration, SVM) passe en disponibilité générale dans Kubernetes 1.37. 26 août 2026. La version 1.37, nommée Garhwal, a été publiée quelques jours plus tôt. 26 août 2026. Le billet de blog « Last modified » confirme l’activation par défaut sur tous les clusters. Pourquoi c’est important ? La SVM touche à un problème que toutes les équipes plateforme ont rencontré : comment faire évoluer le schéma de stockage d’une ressource sans casser ce qui est déjà écrit.

Le problème des versions de stockage périmées

Dans Kubernetes, chaque ressource stockée est écrite selon une version de stockage précise, c’est-à-dire une représentation de schéma. Or l’API ne réécrit une ressource que lorsqu’elle est mutée. Conséquence directe : lorsqu’on veut changer la version de stockage, les objets existants restent figés dans leur ancien format tant qu’ils ne sont pas réécrits.

Le cas le plus courant est la promotion d’une CRD. Quand vous faites passer un custom resource de v1alpha1 vers v1, les nouvelles écritures utilisent v1, mais les objets déjà en base restent sérialisés en v1alpha1. Vous ne pouvez pas retirer v1alpha1 de .status.storedVersions ni couper son serving tant que le moindre objet n’a pas été réécrit. La même logique vaut pour le chiffrement au repos et la rotation de clés : les ressources existantes restent chiffrées sous l’ancienne clé jusqu’à leur réécriture active via l’API server.

Jusqu’ici, les administrateurs devaient s’en sortir avec des scripts kubectl get / kubectl replace ou en déployant le composant hors-arbre kube-storage-version-migrator. Des approches « fastidieuses, sujettes à erreur et difficiles à superviser », comme le rappelle le billet officiel.

Comment fonctionne la migration intégrée

Avec 1.37, lancer une migration se résume à créer un objet déclaratif StorageVersionMigration. Le contrôleur StorageVersionMigrator, désormais intégré au plan de contrôle et activé par défaut, surveille ces objets et migre automatiquement les ressources existantes vers la version de stockage par défaut de l’API concernée.

Le manifeste est minimal :

apiVersion: storagemigration.k8s.io/v1
kind: StorageVersionMigration
metadata:
  name: crontabs-migration
spec:
  resource:
    group: example.com
    resource: crontabs

On applique comme n’importe quelle ressource :

kubectl apply -f crontabs-migration.yaml

Suivre et vérifier une migration

Le contrôleur met à jour le statut de l’objet au fil de la migration. On l’inspecte avec :

kubectl get storageversionmigration.storagemigration.k8s.io/crontabs-migration -o yaml

Une migration réussie rapporte une condition Succeeded à True :

status:
  conditions:
  - type: Running
    status: "False"
    lastUpdateTime: "2026-08-02T10:05:00Z"
    reason: StorageVersionMigrationInProgress
  - type: Succeeded
    status: "True"
    lastUpdateTime: "2026-08-02T10:05:00Z"
    reason: StorageVersionMigrationSucceeded

Une fois la condition Succeeded atteinte, toutes les instances de la ressource sont stockées dans la version courante. Pour les CRD, .status.storedVersions doit alors être mis à jour pour ne plus contenir que la version préférée. Si ce n’est pas le cas, c’est que la CRD a été modifiée pendant la migration — il faut alors relancer l’opération avant de déprécier l’ancienne version.

Intégrer la migration dans les manifestes de CRD

Parce que StorageVersionMigration est une API déclarative standard, les auteurs de CRD peuvent déclencher la migration dans le même manifeste que la mise à jour de leur définition. Un seul kubectl apply met alors à jour la CRD et migre les objets existants :

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: crontabs.example.com
spec:
  group: example.com
  # Liste de versions mise à jour, v1 avec storage: true
---
apiVersion: storagemigration.k8s.io/v1
kind: StorageVersionMigration
metadata:
  name: crontabs-migration
spec:
  resource:
    group: example.com
    resource: crontabs

C’est le vrai changement de paradigme : la migration sort du bricolage opérationnel pour devenir un objet de première classe que l’on versionne, que l’on surveille et que l’on livre avec la ressource elle-même.

Ce que ça change pour les équipes plateforme

La promotion en GA ne change pas les métriques collectées, mais elle change ce que l’on a le droit d’attendre du cluster. Trois bénéfices concrets :

• Dépréciation de version sûre : on retire v1alpha1 sans risquer de casser des objets encore stockés dans l’ancien schéma.
• Rotation de clés réelle : le chiffrement au repos ne reste pas un vœu pieux, puisque la migration force la réécriture sous la nouvelle clé.
• Fin des scripts artisanaux : plus besoin de maintenir des boucles get/replace ni de déployer kube-storage-version-migrator.

Le billet invite à remonter les retours sur le canal #sig-api-machinery du Slack Kubernetes — un signe que la fonctionnalité, bien que stable, reste en phase d’adoption active.

Pourquoi la migration intégrée a mis si longtemps

Le besoin ne date pas d’hier. La migration des versions de stockage était en alpha depuis plusieurs releases, portée par le SIG API Machinery, et les équipes s’appuyaient sur kube-storage-version-migrator, un composant hors-arbre maintenu à part. La difficulté n’est pas d’écrire un objet de plus dans etcd — c’est de le faire sans casser la cohérence que Kubernetes garantit à son API.

Quand un contrôleur réécrit massivement des objets, il traverse chaque ressource stockée, la décode dans son ancienne version, puis la ré-encode dans la nouvelle. Cette réécriture doit être idempotente, résumable après une interruption et observable — trois propriétés que les scripts get/replace ne garantissaient jamais. Une panne au milieu d’une migration manuelle laissait des objets à moitié migrés, sans que personne ne le sache. Le contrôleur intégré apporte exactement ces garanties : un statut par objet, des conditions normalisées et une progression interrogeable à tout moment.

Adoption et précautions

La graduation en GA ne dispense pas de méthode. Quatre points méritent l’attention des opérateurs :

• Une migration à la fois : le contrôleur traite les objets séquentiellement ; lancer plusieurs StorageVersionMigration en parallèle sur le même groupe de ressources brouille le statut et peut saturer l’API server sur les très gros parcs.
• Vérifier .status.storedVersions après coup : si la CRD a été modifiée pendant la migration, le statut ne sera pas mis à jour et il faudra relancer — c’est un cas prévu, pas une panne.
• Ne pas couper l’ancienne version trop tôt : tant que la condition Succeeded n’est pas True, retirer v1alpha1 du serving casse les objets qui n’ont pas encore été réécrits.
• Traiter la migration comme du code : un objet StorageVersionMigration se versionne, se review et se livre avec la CRD, pas à la main en urgence.

Le bénéfice le plus concret reste, au fond, la rotation de clés. Le chiffrement au repos d’etcd ne protège que les données écrites après son activation ; sans migration, des objets peuvent rester chiffrés sous une clé compromise pendant des mois. Le StorageVersionMigration force leur réécriture sous la nouvelle clé — et transforme une opération de sécurité autrefois incertaine en un geste déclaratif et vérifiable.

Un exemple concret : retirer v1alpha1 sans casser la production

Prenons une CRD servie en v1alpha1 depuis l’origine, que l’on veut promouvoir en v1. Avant 1.37, la séquence sûre était manuelle et fragile : basculer la version de stockage sur v1, puis dérouler une boucle kubectl get/kubectl replace sur chaque objet pour forcer la re-sérialisation, vérifier le résultat à l’œil, et seulement ensuite retirer v1alpha1 de .status.storedVersions. Sauter une étape, c’est laisser des objets bloqués dans une version que l’API server ne sert plus — cause classique d’erreurs de décodage et de « resource not found » pendant les montées de version.

Avec le contrôleur intégré, la séquence se réduit à deux gestes déclaratifs. On met à jour la CRD pour que v1 devienne la version de stockage, puis on applique un StorageVersionMigration ciblant cette ressource. Le contrôleur réécrit, expose la progression dans le statut de l’objet et passe Succeeded à True quand tout est en v1. Alors seulement on retire l’ancienne version. Ce qui était une soirée de scripts et de vérification manuelle devient un manifeste reviewé et un statut que l’on peut asserter — la différence entre une migration que l’on espère réussie et une migration que l’on peut prouver.

Verdict

Si vous opérez un cluster en 1.37, remplacez vos scripts de migration par le contrôleur intégré : créez un StorageVersionMigration pour chaque CRD dont vous promouvez la version, et intégrez-le au manifeste de la CRD. C’est moins de code à maintenir et un statut observable de bout en bout.

Si vous êtes auteur de CRD, bundlez systématiquement l’objet StorageVersionMigration avec vos montées de version. La migration devient un artefact livré, pas une opération manuelle que l’on oublie — et c’est précisément ce qui manquait pour que la dépréciation d’anciennes versions cesse d’être une source d’incidents silencieux.

Références

• Kubernetes v1.37: Storage Version Migration Enabled by Default — Kubernetes Blog, 31 août 2026
• Migrate Kubernetes Objects Using Storage Version Migration — Documentation Kubernetes