Pluto : détecter les API Kubernetes obsolètes

Version actuelle

Ce guide utilise Pluto v5.22.7 (décembre 2025). Cette version apporte des corrections de vulnérabilités Go et reste compatible avec Kubernetes jusqu’à la v1.32.

Ce guide vous permet de détecter en quelques secondes les API Kubernetes dépréciées dans vos manifests YAML, charts Helm et clusters en production. Vous apprendrez à scanner vos fichiers locaux, analyser vos releases Helm déployées et anticiper les problèmes avant une mise à jour de Kubernetes. Pluto est un outil indispensable pour éviter les échecs de déploiement lors des montées de version.

Ce que vous allez apprendre

• Comprendre pourquoi Kubernetes déprécie certaines API
• Installer Pluto sur Linux, macOS ou Windows
• Scanner des manifests YAML pour détecter les API obsolètes
• Analyser les releases Helm d’un cluster en production
• Cibler une version précise de Kubernetes pour anticiper les migrations
• Intégrer Pluto dans vos pipelines CI/CD

Prérequis : connaissance de base de Kubernetes et des manifests YAML. Un cluster Kubernetes n’est pas obligatoire pour les premiers exemples.

Qu’est-ce que Pluto ?

Pluto est un outil en ligne de commande développé par Fairwinds qui détecte automatiquement les versions d’API Kubernetes dépréciées ou supprimées. Son nom fait référence à la planète naine déclassée du système solaire : tout comme Pluton a perdu son statut de planète, certaines API Kubernetes perdent leur statut de version supportée.

Concrètement, Pluto analyse trois types de sources :

• Fichiers locaux : vos manifests YAML stockés dans un dépôt Git
• Charts Helm : avant de les déployer, pour éviter les mauvaises surprises
• Clusters en production : les releases Helm déjà déployées et les ressources actives

L’outil produit un rapport clair indiquant quelles ressources utilisent des API obsolètes, quand elles ont été dépréciées, quand elles seront supprimées et par quoi les remplacer.

Situation	Sans Pluto	Avec Pluto
Mise à jour K8s	Échec surprise du déploiement	Anticipation des changements nécessaires
Audit des manifests	Recherche manuelle dans les fichiers	Scan automatique en quelques secondes
Pipeline CI/CD	API obsolète déployée en production	Blocage préventif avant le déploiement
Documentation	Consultation du changelog Kubernetes	Rapport détaillé avec versions concernées

Glissez pour voir

Pourquoi Kubernetes déprécie des API ?

Kubernetes évolue rapidement : environ trois versions majeures par an. Cette évolution implique des changements d’API pour améliorer la stabilité, les performances et la sécurité. Comprendre ce cycle vous aide à mieux utiliser Pluto.

Le cycle de vie d’une API Kubernetes

Une API Kubernetes suit généralement ce parcours :

1. Introduction en alpha (v1alpha1)

   L’API est expérimentale, susceptible de changer sans préavis. Elle n’est pas activée par défaut et ne doit pas être utilisée en production.

2. Passage en beta (v1beta1)

   L’API est considérée comme stable mais peut encore évoluer. Kubernetes la garde généralement pendant 9 mois minimum avant dépréciation.

3. Version stable (v1)

   L’API est mature et garantie sur le long terme. Les changements incompatibles sont rares et toujours annoncés longtemps à l’avance.

4. Dépréciation de l’ancienne version

   Kubernetes annonce que l’ancienne API (beta) ne sera plus maintenue. Elle reste fonctionnelle mais génère des avertissements.

5. Suppression définitive

   L’API supprimée n’est plus reconnue par l’API server. Les manifests qui l’utilisent échouent immédiatement.

Exemples historiques marquants

L’histoire de Kubernetes est jalonnée de dépréciations qui ont causé des problèmes à de nombreuses équipes :

Version K8s	API supprimée	Impact
v1.16	extensions/v1beta1 pour Deployment	Des milliers de Deployments cassés
v1.22	networking.k8s.io/v1beta1 pour Ingress	Migration massive vers v1
v1.25	policy/v1beta1 pour PodSecurityPolicy	Remplacement par Pod Security Standards
v1.32	flowcontrol.apiserver.k8s.io/v1beta2	Migration vers v1beta3

Glissez pour voir

C’est lors du passage de la v1.16 que j’ai personnellement découvert l’importance d’un outil comme Pluto. Des centaines de Deployments avaient cessé de fonctionner car ils utilisaient encore extensions/v1beta1 au lieu de apps/v1. Cette expérience m’a convaincu qu’un scan automatique était indispensable.

Installation de Pluto

Pluto est disponible sous forme de binaire autonome pour Linux, macOS et Windows. L’installation prend moins d’une minute quelle que soit la méthode choisie.

Linux

La méthode la plus simple utilise le téléchargement direct du binaire :

# Télécharger la dernière version
wget https://github.com/FairwindsOps/pluto/releases/download/v5.22.7/pluto_5.22.7_linux_amd64.tar.gz

# Extraire l'archive
tar -xzf pluto_5.22.7_linux_amd64.tar.gz

# Installer le binaire
sudo install pluto /usr/local/bin/

# Vérifier l'installation
pluto version

Résultat attendu :

Version:5.22.7 Commit:d3b74eba1b1a24e614b6daef9c613d5203c2b234

Pour les processeurs ARM (Raspberry Pi, Mac M1 sous Linux), utilisez pluto_5.22.7_linux_arm64.tar.gz.

macOS

Avec Homebrew, l’installation se fait en une commande :

# Installation via Homebrew
brew install FairwindsOps/tap/pluto

# Vérifier l'installation
pluto version

Si vous préférez le binaire direct, téléchargez pluto_5.22.7_darwin_arm64.tar.gz (Mac Apple Silicon) ou pluto_5.22.7_darwin_amd64.tar.gz (Mac Intel).

Windows

Avec Scoop, gestionnaire de paquets pour Windows :

# Installation via Scoop
scoop install pluto

# Vérifier l'installation
pluto version

Vous pouvez aussi télécharger pluto_5.22.7_windows_amd64.zip depuis la page des releases et ajouter le dossier à votre PATH.

asdf

Si vous utilisez asdf-vm pour gérer vos versions d’outils :

# Ajouter le plugin Pluto
asdf plugin add pluto

# Lister les versions disponibles
asdf list-all pluto

# Installer la dernière version
asdf install pluto 5.22.7

# Définir comme version par défaut
asdf global pluto 5.22.7

# Vérifier
pluto version

Cette méthode permet de gérer facilement plusieurs versions de Pluto sur une même machine.

Docker

Pour une utilisation ponctuelle ou dans un pipeline CI :

# Exécuter Pluto via Docker
docker run --rm -v $(pwd):/workdir \
  us-docker.pkg.dev/fairwinds-ops/oss/pluto:v5.22.7 \
  detect-files -d /workdir/manifests

L’image Docker est signée avec cosign. Vous pouvez vérifier la signature :

cosign verify us-docker.pkg.dev/fairwinds-ops/oss/pluto:v5 \
  --key https://artifacts.fairwinds.com/cosign-p256.pub

Premier scan de fichiers

Commençons par l’usage le plus courant : scanner un répertoire contenant des manifests YAML. C’est le cas typique d’un dépôt Git Infrastructure-as-Code.

Créer des fichiers de test

Pour illustrer les exemples, créons quelques manifests avec des API dépréciées :

# Créer un répertoire de test
mkdir -p /tmp/pluto-demo/manifests

# Créer un Ingress avec une ancienne API (dépréciée en v1.19, supprimée en v1.22)
cat > /tmp/pluto-demo/manifests/ingress.yaml << 'EOF'
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: mon-application
  namespace: production
spec:
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        backend:
          serviceName: app-service
          servicePort: 80
EOF

# Créer un Deployment avec une très ancienne API (dépréciée en v1.9, supprimée en v1.16)
cat > /tmp/pluto-demo/manifests/deployment.yaml << 'EOF'
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: ancien-deployment
  namespace: production
spec:
  replicas: 3
  template:
    metadata:
      labels:
        app: legacy
    spec:
      containers:
      - name: app
        image: nginx:1.27
EOF

Ces fichiers représentent un cas réel : des manifests créés il y a quelques années et jamais mis à jour.

Lancer le scan

La commande detect-files analyse tous les fichiers YAML d’un répertoire :

pluto detect-files -d /tmp/pluto-demo/manifests/

Résultat :

NAME               KIND         VERSION                     REPLACEMENT            REMOVED   DEPRECATED   REPL AVAIL
ancien-deployment  Deployment   extensions/v1beta1          apps/v1                true      true         true
mon-application    Ingress      networking.k8s.io/v1beta1   networking.k8s.io/v1   true      true         true

Le tableau indique clairement :

• NAME : le nom de la ressource concernée
• KIND : le type de ressource Kubernetes
• VERSION : l’API actuellement utilisée (obsolète)
• REPLACEMENT : l’API à utiliser à la place
• REMOVED : true si l’API a déjà été supprimée
• DEPRECATED : true si l’API est dépréciée
• REPL AVAIL : true si le remplacement est disponible dans la version cible

Interpréter les résultats

Dans notre exemple, les deux ressources sont marquées REMOVED: true. Cela signifie que ces manifests ne fonctionneront pas sur un cluster Kubernetes récent (v1.22+).

Pour corriger ces fichiers, il faut remplacer l’API par celle indiquée dans la colonne REPLACEMENT :

• extensions/v1beta1 → apps/v1 pour le Deployment
• networking.k8s.io/v1beta1 → networking.k8s.io/v1 pour l’Ingress

Attention aux changements de structure

Le changement d’apiVersion peut nécessiter des modifications de structure du manifest. Par exemple, l’Ingress v1 utilise pathType qui n’existait pas en v1beta1. Consultez la documentation officielle de migration Kubernetes.

Formats de sortie

Pluto propose plusieurs formats de sortie adaptés à différents usages : affichage terminal, intégration dans des scripts ou génération de rapports.

Sortie détaillée (wide)

Le format wide ajoute des colonnes avec les numéros de version précis :

pluto detect-files -d /tmp/pluto-demo/manifests/ -o wide

Résultat :

NAME               NAMESPACE   KIND         VERSION                     REPLACEMENT            DEPRECATED   DEPRECATED IN   REMOVED   REMOVED IN   REPL AVAIL   REPL AVAIL IN
ancien-deployment  production  Deployment   extensions/v1beta1          apps/v1                true         v1.9.0          true      v1.16.0      true         v1.9.0
mon-application    production  Ingress      networking.k8s.io/v1beta1   networking.k8s.io/v1   true         v1.19.0         true      v1.22.0      true         v1.19.0

Ce format montre exactement dans quelle version de Kubernetes chaque API a été dépréciée (DEPRECATED IN) et supprimée (REMOVED IN). Très utile pour planifier une migration.

Sortie JSON

Le format JSON est idéal pour l’intégration dans des scripts ou des outils d’analyse :

pluto detect-files -d /tmp/pluto-demo/manifests/ -o json | jq .

Résultat :

{
  "items": [
    {
      "name": "ancien-deployment",
      "filePath": "/tmp/pluto-demo/manifests/deployment.yaml",
      "namespace": "production",
      "api": {
        "version": "extensions/v1beta1",
        "kind": "Deployment",
        "deprecated-in": "v1.9.0",
        "removed-in": "v1.16.0",
        "replacement-api": "apps/v1",
        "replacement-available-in": "v1.9.0",
        "component": "k8s"
      },
      "deprecated": true,
      "removed": true,
      "replacementAvailable": true
    }
  ],
  "target-versions": {
    "k8s": "v1.25.0"
  }
}

La sortie JSON inclut le chemin du fichier (filePath), ce qui permet d’automatiser les corrections.

Autres formats disponibles

Format	Option	Usage
Normal	-o normal	Affichage par défaut, compact
Wide	-o wide	Toutes les colonnes avec versions
JSON	-o json	Intégration scripts, API
YAML	-o yaml	Format Kubernetes natif
CSV	-o csv	Export tableur, rapports
Markdown	-o markdown	Documentation, issues Git

Glissez pour voir

Exemple de sortie Markdown pour un rapport GitLab/GitHub :

pluto detect-files -d /tmp/pluto-demo/manifests/ -o markdown

| NAME               | NAMESPACE  | KIND       | VERSION              | REPLACEMENT          | DEPRECATED | REMOVED |
|--------------------|------------|------------|----------------------|----------------------|------------|---------|
| ancien-deployment  | production | Deployment | extensions/v1beta1   | apps/v1              | true       | true    |
| mon-application    | production | Ingress    | networking.k8s.io/v1beta1 | networking.k8s.io/v1 | true  | true    |

Cibler une version Kubernetes

Par défaut, Pluto considère Kubernetes v1.25.0 comme version cible. Pour planifier une mise à jour vers une version spécifique, utilisez l’option --target-versions.

Anticiper une migration

Imaginons que vous préparez une migration de v1.20 vers v1.25. Pour voir ce qui sera problématique :

pluto detect-files -d /tmp/pluto-demo/manifests/ --target-versions k8s=v1.21.0

Avec la cible v1.21.0, l’Ingress n’est pas encore supprimé (suppression en v1.22), donc seul le Deployment apparaît comme REMOVED: true.

Planifier sur le long terme

Pour voir toutes les API dépréciées en vue de Kubernetes v1.32 :

pluto detect-files -d /tmp/pluto-demo/manifests/ --target-versions k8s=v1.32.0

Cette commande révèle les API qui seront supprimées dans les prochaines versions, vous donnant le temps de planifier les migrations.

Cibler plusieurs composants

Pluto connaît les dépréciations de plusieurs écosystèmes : Kubernetes (k8s), Istio, cert-manager. Pour cibler plusieurs composants :

pluto detect-files -d /tmp/pluto-demo/manifests/ \
  --target-versions k8s=v1.28.0,cert-manager=v1.6.0,istio=v1.15.0

Scanner un cluster en production

Au-delà des fichiers locaux, Pluto peut analyser directement un cluster Kubernetes pour détecter les API obsolètes déjà déployées.

Analyser les releases Helm

Si vous utilisez Helm pour déployer vos applications, Pluto peut scanner toutes les releases :

# Scanner toutes les releases Helm
pluto detect-helm -o wide

# Scanner uniquement un namespace
pluto detect-helm -n mon-namespace -o wide

Cette commande analyse les secrets Helm stockés dans le cluster et détecte les manifests utilisant des API obsolètes.

Connexion au cluster

Pluto utilise votre kubeconfig par défaut (~/.kube/config). Pour cibler un contexte spécifique :

pluto detect-helm --kube-context production-cluster

Analyser les ressources Kubernetes

Pour scanner les ressources actuellement déployées dans le cluster (pas seulement Helm) :

pluto detect-api-resources -o wide

Cette commande utilise l’annotation kubectl.kubernetes.io/last-applied-configuration pour retrouver l’API utilisée lors de la création. Attention : cette méthode n’est pas toujours fiable si les ressources ont été modifiées avec kubectl patch.

Scan complet du cluster

Pour combiner les détections Helm et API resources :

pluto detect-all-in-cluster -o wide

Cette commande donne une vue complète de toutes les API obsolètes présentes dans votre cluster, quelle que soit leur méthode de déploiement.

Valider un chart Helm avant déploiement

Avant de déployer un chart Helm, vous pouvez vérifier qu’il n’utilise pas d’API obsolètes :

# Générer les manifests et les analyser
helm template mon-chart ./chart-directory | pluto detect -

Le tiret (-) indique à Pluto de lire depuis l’entrée standard (stdin). Cette technique fonctionne avec n’importe quelle commande qui génère des manifests YAML.

Pour un chart depuis un repository Helm :

helm template ingress-nginx ingress-nginx/ingress-nginx | pluto detect -

Intégration CI/CD

Pluto est conçu pour s’intégrer dans les pipelines CI/CD. Ses codes de sortie permettent d’automatiser les décisions de déploiement.

Codes de sortie

Code	Signification	Action recommandée
0	Aucune API obsolète détectée	Continuer le pipeline
1	Erreur d’exécution	Vérifier les logs
2	API dépréciée trouvée	Avertissement, planifier migration
3	API supprimée trouvée	Bloquer le déploiement
4	Remplacement non disponible	Vérifier la version cible

Glissez pour voir

Exemple GitLab CI

Voici un job GitLab CI qui bloque le déploiement si des API supprimées sont détectées :

check-deprecated-apis:
  stage: validate
  image: us-docker.pkg.dev/fairwinds-ops/oss/pluto:v5.22.7
  script:
    - pluto detect-files -d manifests/ --target-versions k8s=v1.28.0
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  allow_failure: false

Pour autoriser les dépréciations mais bloquer uniquement les suppressions :

check-deprecated-apis:
  stage: validate
  script:
    - pluto detect-files -d manifests/ --ignore-deprecations
  allow_failure: false

GitHub Action

Fairwinds fournit une GitHub Action officielle :

- name: Download Pluto
  uses: FairwindsOps/pluto/github-action@master

- name: Check for deprecated APIs
  run: pluto detect-files -d ./manifests --target-versions k8s=v1.28.0

Options pour les pipelines

Pour personnaliser le comportement dans un contexte CI :

Option	Description
--ignore-deprecations	Ne pas échouer sur les API dépréciées (code 2)
--ignore-removals	Ne pas échouer sur les API supprimées (code 3)
--only-show-removed	Afficher uniquement les API supprimées
--no-headers	Supprimer les en-têtes pour faciliter le parsing

Glissez pour voir

Lister les versions connues

Pluto maintient une base de données interne de toutes les API Kubernetes et leurs cycles de dépréciation. Pour la consulter :

pluto list-versions

Cette commande affiche toutes les API connues, leur date de dépréciation et de suppression. Utile pour comprendre ce que Pluto peut détecter.

Pour filtrer sur un composant spécifique :

pluto list-versions --components k8s | grep Ingress

Ajouter des versions personnalisées

Si vous utilisez des CRD (Custom Resource Definitions) qui ont leurs propres cycles de dépréciation, vous pouvez les ajouter à Pluto.

Créez un fichier YAML avec vos versions personnalisées :

custom-versions.yaml

target-versions:
  mycompany: v2.0.0

deprecated-versions:
  - version: mycompany.io/v1alpha1
    kind: MyCustomResource
    deprecated-in: v1.5.0
    removed-in: v2.0.0
    replacement-api: mycompany.io/v1
    component: mycompany

Puis utilisez-le avec l’option -f :

pluto detect-files -d manifests/ -f custom-versions.yaml

Dépannage

Problèmes courants et solutions

Problème	Cause probable	Solution
”No deprecated APIs found” mais kubectl montre l’ancienne version	kubectl affiche toujours la version par défaut	Pluto a raison, kubectl convertit l’API automatiquement
Pluto détecte toujours l’ancienne API après mise à jour	Anciennes révisions Helm encore présentes	Supprimer les anciens secrets Helm : kubectl delete secret sh.helm.release.v1.release-name.vX
Code de sortie 1 sans message	Erreur de connexion au cluster	Vérifier kubeconfig et contexte avec kubectl cluster-info

Glissez pour voir

Limites de la détection in-cluster

La détection via detect-api-resources repose sur l’annotation kubectl.kubernetes.io/last-applied-configuration. Cette méthode a des limites :

• Les ressources modifiées avec kubectl patch perdent l’annotation
• Les ressources créées par des opérateurs peuvent ne pas avoir l’annotation
• Certaines ressources très anciennes n’ont jamais eu cette annotation

Pour une détection fiable, préférez detect-helm si vous utilisez Helm, ou scannez vos fichiers sources avec detect-files.

Bonnes pratiques

Intégration dans le workflow de développement

1. Scannez à chaque commit

   Ajoutez Pluto dans votre pipeline CI pour détecter les problèmes au plus tôt. Un développeur préférera corriger une API obsolète avant de merger plutôt qu’en urgence lors d’une mise à niveau de cluster.

2. Ciblez la prochaine version

   Configurez votre pipeline pour cibler la prochaine version de Kubernetes que vous prévoyez d’adopter. Cela donne le temps à l’équipe de planifier les migrations.

3. Bloquez uniquement les suppressions

   Utilisez --ignore-deprecations pour avertir sans bloquer sur les dépréciations. Ne bloquez le pipeline que pour les API déjà supprimées (REMOVED: true).

4. Documentez les migrations

   Quand Pluto détecte une API obsolète, créez une issue ou un ticket de dette technique. La sortie Markdown facilite la documentation.

Éviter l’accumulation de dette technique

Le plus grand risque avec les API dépréciées est l’accumulation : quelques manifests obsolètes deviennent des dizaines, puis des centaines. Pour l’éviter :

• Intégrez Pluto dès les premières lignes de code d’un projet
• Traitez les avertissements de dépréciation comme des bugs à corriger
• Planifiez des sprints de mise à jour d’API régulièrement

À retenir

• Pluto détecte les API Kubernetes dépréciées dans vos fichiers YAML, charts Helm et clusters en production
• Version actuelle : v5.22.7 (décembre 2025), compatible jusqu’à Kubernetes v1.32
• La commande detect-files scanne les fichiers locaux, detect-helm les releases Helm, detect-api-resources le cluster
• Utilisez --target-versions k8s=vX.Y.Z pour cibler une version spécifique de Kubernetes
• Les codes de sortie (2 = déprécié, 3 = supprimé) permettent l’automatisation CI/CD
• Le format -o wide montre les versions exactes de dépréciation et suppression
• Intégrez Pluto dans votre pipeline pour éviter l’accumulation de dette technique
• Les API supprimées (REMOVED: true) casseront immédiatement vos déploiements

Prochaines étapes

Helm : gestionnaire de packages Kubernetes Maîtrisez Helm pour déployer vos applications Kubernetes

Popeye : scanner la santé d'un cluster Auditez votre cluster Kubernetes et détectez les problèmes de configuration

Polaris : bonnes pratiques Kubernetes Auditez vos manifests selon les best practices Kubernetes

Écrire des manifests Kubernetes Apprenez les bases des manifests YAML pour Kubernetes

Ressources

• Documentation officielle : pluto.docs.fairwinds.com
• Repository GitHub : github.com/FairwindsOps/pluto
• Guide de dépréciation Kubernetes : kubernetes.io/docs/reference/using-api/deprecation-guide

×

📖 Voir la documentation →