Gérer les dépréciations d'API Kubernetes

Les API Kubernetes évoluent : certaines versions sont dépréciées puis supprimées lors des mises à jour. Si vos manifests utilisent une API supprimée, vos déploiements échoueront après la mise à jour du cluster. Ce guide vous explique le cycle de vie des API, comment détecter les versions obsolètes, et comment migrer vos ressources avant qu’il ne soit trop tard.

Ce que vous allez apprendre

• Comprendre le cycle de vie des API Kubernetes (alpha → beta → stable)
• Distinguer une API dépréciée (avertissement) d’une API supprimée (erreur)
• Détecter les API obsolètes dans vos fichiers YAML, charts Helm et cluster
• Migrer vos ressources avec kubectl convert et les outils appropriés
• Automatiser la détection dans votre pipeline CI/CD

Prérequis : savoir écrire des manifests Kubernetes et comprendre le versioning sémantique.

Pourquoi les API changent-elles ?

Kubernetes suit un processus rigoureux pour faire évoluer ses API sans casser brutalement les utilisateurs. Chaque nouvelle fonctionnalité passe par plusieurs phases de maturité avant d’être stabilisée — ou abandonnée.

Le cycle de vie d’une API

┌─────────┐     ┌─────────┐     ┌─────────┐     ┌────────────┐     ┌─────────┐
│  Alpha  │ ──▶ │  Beta   │ ──▶ │ Stable  │ ──▶ │ Deprecated │ ──▶ │ Removed │
│ v1alpha1│     │ v1beta1 │     │   v1    │     │    v1      │     │    -    │
└─────────┘     └─────────┘     └─────────┘     └────────────┘     └─────────┘
   Expérimental    Pré-stable      Stable        Obsolète          Supprimé

Phase	Caractéristiques	Durée typique
Alpha (v1alpha1)	Désactivé par défaut, peut changer ou disparaître sans préavis	Variable
Beta (v1beta1)	Activé par défaut, testé mais peut encore évoluer	9+ mois minimum
Stable (v1)	Garanti compatible, pas de changements cassants	Indéfini
Deprecated	Toujours fonctionnel mais marqué obsolète, warnings dans les logs	12+ mois
Removed	Supprimé, les manifests échouent	-

Glissez pour voir

Règle des 12 mois

Kubernetes garantit qu’une API stable reste disponible au moins 12 mois après sa dépréciation. Mais les API beta peuvent être supprimées plus rapidement (9 mois minimum depuis Kubernetes 1.22).

Impact concret sur vos déploiements

Quand une API est supprimée :

kubectl apply -f deployment-old.yaml

error: resource mapping not found for name: "my-app" namespace: ""
from "deployment-old.yaml": no matches for kind "Deployment" in version "extensions/v1beta1"
ensure CRDs are installed first

Votre manifest devient inapplicable. Le cluster ne reconnaît plus cette combinaison apiVersion + kind.

Exemples historiques de suppressions majeures

Ces suppressions ont cassé des milliers de déploiements. Apprenez de l’histoire pour ne pas la répéter.

Kubernetes 1.16 — Le grand nettoyage

Les API extensions/v1beta1 et apps/v1beta1 ont été supprimées après des années de dépréciation :

Ressource	Ancienne API (supprimée)	Nouvelle API
Deployment	extensions/v1beta1	apps/v1
DaemonSet	extensions/v1beta1	apps/v1
ReplicaSet	extensions/v1beta1	apps/v1
StatefulSet	apps/v1beta1	apps/v1

Glissez pour voir

Kubernetes 1.22 — Ingress et autres

Ressource	Ancienne API (supprimée)	Nouvelle API
Ingress	extensions/v1beta1	networking.k8s.io/v1
Ingress	networking.k8s.io/v1beta1	networking.k8s.io/v1
CertificateSigningRequest	certificates.k8s.io/v1beta1	certificates.k8s.io/v1
ValidatingWebhookConfiguration	admissionregistration.k8s.io/v1beta1	admissionregistration.k8s.io/v1

Glissez pour voir

Kubernetes 1.25 — PodSecurityPolicy

Ressource	Ancienne API (supprimée)	Remplacement
PodSecurityPolicy	policy/v1beta1	Pod Security Standards (PSS)
PodDisruptionBudget	policy/v1beta1	policy/v1
EndpointSlice	discovery.k8s.io/v1beta1	discovery.k8s.io/v1

Glissez pour voir

PodSecurityPolicy

La suppression de PSP est spéciale : il n’y a pas de migration directe. Vous devez reconfigurer complètement la sécurité avec Pod Security Standards ou un admission controller externe (OPA Gatekeeper, Kyverno).

Détecter les API obsolètes

Méthode 1 : kubectl avec warnings

Depuis Kubernetes 1.19, kubectl affiche des warnings pour les API dépréciées :

kubectl apply -f old-ingress.yaml

Warning: extensions/v1beta1 Ingress is deprecated in v1.14+, unavailable in v1.22+;
use networking.k8s.io/v1 Ingress
ingress.extensions/my-ingress created

Limitation : Vous ne voyez le warning qu’au moment de l’apply. Pas pratique pour auditer tous vos manifests.

Méthode 2 : API resources du cluster

Listez les versions d’API supportées par votre cluster :

# Toutes les API disponibles
kubectl api-versions

# Vérifier si une API existe
kubectl api-versions | grep networking.k8s.io

Pour voir quelle version est préférée pour une ressource :

kubectl api-resources | grep -i ingress

Méthode 3 : Audit avec Pluto

Pluto est un outil CLI dédié à la détection des API obsolètes.

1. Installer Pluto

   macOS

   brew install FairwindsOps/tap/pluto

   Linux

   curl -L https://github.com/FairwindsOps/pluto/releases/latest/download/pluto_linux_amd64.tar.gz | tar xz
   sudo mv pluto /usr/local/bin/

2. Scanner un répertoire de manifests

   pluto detect-files -d ./manifests/

   Sortie :

   NAME        KIND      VERSION              REPLACEMENT                 REMOVED   DEPRECATED
   my-ingress  Ingress   extensions/v1beta1   networking.k8s.io/v1        true      true
   my-psp      PSP       policy/v1beta1       N/A (Pod Security Standards) true     true

3. Scanner les releases Helm déployées

   pluto detect-helm -owide

4. Cibler une version Kubernetes spécifique

   Utile pour anticiper une mise à jour :

   pluto detect-files -d ./manifests/ --target-versions k8s=v1.29.0

Méthode 4 : kubent (Kube No Trouble)

kubent analyse votre cluster en temps réel :

# Installation
sh -c "$(curl -sSL https://git.io/install-kubent)"

# Scanner le cluster
kubent

>>> Deprecated APIs removed in 1.25 <<<
-----------------------------------------
KIND                NAMESPACE     NAME            API_VERSION
PodSecurityPolicy   <cluster>     restricted      policy/v1beta1

Migrer vers les nouvelles API

Méthode 1 : kubectl convert

Le plugin kubectl convert transforme les manifests vers une nouvelle API :

1. Installer le plugin

   # Télécharger
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl-convert"
   
   # Rendre exécutable et déplacer
   chmod +x kubectl-convert
   sudo mv kubectl-convert /usr/local/bin/

2. Convertir un manifest

   kubectl convert -f old-ingress.yaml --output-version networking.k8s.io/v1 > new-ingress.yaml

3. Vérifier le résultat

   Le fichier converti peut nécessiter des ajustements manuels. Par exemple, l’Ingress v1 exige le champ pathType :

   # Avant (v1beta1) - pas de pathType
   - path: /api
   
   # Après (v1) - pathType obligatoire
   - path: /api
     pathType: Prefix  # ou Exact, ImplementationSpecific

Limitations de kubectl convert

kubectl convert ne fonctionne que pour les migrations entre versions d’une même ressource. Pour les changements structurels majeurs (comme PSP → Pod Security Standards), une réécriture manuelle est nécessaire.

Méthode 2 : Migration manuelle

Pour les migrations complexes, suivez ce processus :

1. Sauvegarder la ressource actuelle

   kubectl get ingress my-ingress -o yaml > backup-ingress.yaml

2. Consulter la documentation de migration

   Kubernetes publie des guides de migration pour chaque version majeure :

   • Deprecated API Migration Guide

3. Adapter le manifest

   Exemple pour Ingress v1beta1 → v1 :

   # Avant
   apiVersion: networking.k8s.io/v1beta1
   kind: Ingress
   metadata:
     name: my-ingress
   spec:
     rules:
     - host: example.com
       http:
         paths:
         - path: /api
           backend:
             serviceName: api-service
             servicePort: 80
   
   # Après
   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: my-ingress
   spec:
     rules:
     - host: example.com
       http:
         paths:
         - path: /api
           pathType: Prefix  # NOUVEAU: obligatoire
           backend:
             service:        # NOUVEAU: structure imbriquée
               name: api-service
               port:
                 number: 80

4. Appliquer et valider

   kubectl apply -f new-ingress.yaml
   kubectl describe ingress my-ingress

Automatiser la détection en CI/CD

GitHub Actions avec Pluto

.github/workflows/api-deprecation.yaml

name: Check Kubernetes API deprecations

on:
  pull_request:
    paths:
      - 'manifests/**'
      - 'charts/**'

jobs:
  pluto:
    runs-on: ubuntu-latest
    permissions: {}

    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          persist-credentials: false

      - name: Install Pluto
        run: |
          curl -L https://github.com/FairwindsOps/pluto/releases/latest/download/pluto_linux_amd64.tar.gz | tar xz
          sudo mv pluto /usr/local/bin/

      - name: Check manifests
        run: pluto detect-files -d ./manifests/ --target-versions k8s=v1.30.0

      - name: Check Helm charts
        run: |
          for chart in ./charts/*/; do
            helm template test "$chart" | pluto detect -
          done

Codes de sortie Pluto

Utilisez les codes de sortie pour bloquer ou avertir :

Code	Signification	Action CI/CD
0	Aucune API obsolète	✅ Continuer
2	API dépréciées trouvées	⚠️ Warning (optionnel)
3	API supprimées trouvées	❌ Bloquer le merge

Glissez pour voir

- name: Check and fail on removed APIs
  run: |
    pluto detect-files -d ./manifests/ --target-versions k8s=v1.30.0
    EXIT_CODE=$?
    if [ $EXIT_CODE -eq 3 ]; then
      echo "::error::Removed APIs detected! Migration required."
      exit 1
    fi

GitLab CI

.gitlab-ci.yml

api-deprecation-check:
  stage: validate
  image: alpine:latest
  before_script:
    - apk add --no-cache curl tar
    - curl -L https://github.com/FairwindsOps/pluto/releases/latest/download/pluto_linux_amd64.tar.gz | tar xz
    - mv pluto /usr/local/bin/
  script:
    - pluto detect-files -d ./manifests/ --target-versions k8s=v1.30.0 -o markdown > deprecation-report.md
  artifacts:
    paths:
      - deprecation-report.md
    when: always
  allow_failure: false

Bonnes pratiques

Avant une mise à jour de cluster

1. Scanner tous les manifests avec Pluto ou kubent
2. Cibler la version cible : --target-versions k8s=v1.X.0
3. Migrer et tester en environnement staging
4. Mettre à jour les charts Helm si vous en utilisez
5. Mettre à jour le cluster seulement après migration

Maintenance continue

Fréquence	Action
À chaque PR	Scanner les manifests modifiés
Mensuel	Scanner tout le repo avec la version K8s actuelle + 2
Avant upgrade	Rapport complet sur la version cible

Glissez pour voir

Référence de compatibilité

Consultez toujours la documentation officielle :

• API Deprecation Policy
• Deprecated API Migration Guide
• Version Skew Policy

À retenir

• Les API Kubernetes suivent un cycle : alpha → beta → stable → deprecated → removed
• Une API dépréciée fonctionne encore (avec warnings), une API supprimée casse vos déploiements
• Kubernetes garantit 12 mois minimum entre dépréciation et suppression pour les API stables
• Utilisez Pluto ou kubent pour détecter les API obsolètes dans vos manifests et votre cluster
• kubectl convert migre les manifests simples, mais les changements structurels nécessitent une réécriture manuelle
• Automatisez la détection dans votre CI/CD pour bloquer les PR avec des API supprimées
• Scannez avant chaque upgrade de cluster avec la version cible

Testez vos Connaissances

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

10 questions

8 min.

70% 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

Prochaines étapes

Écrire des manifests Kubernetes Maîtriser la syntaxe YAML des ressources Kubernetes

Détecter les API obsolètes avec Pluto Guide complet de l'outil Pluto

Troubleshooting Kubernetes Déboguer les erreurs courantes

Architecture Kubernetes Comprendre les composants du cluster

×

📖 Voir la documentation →