Plugins kubectl en production : une checklist opérationnelle avec exemples pratiques

Introduction

Les plugins kubectl étendent l'outil en ligne de commande Kubernetes avec des sous-commandes personnalisées, permettant aux opérateurs de rationaliser des workflows complexes, d'intégrer des outils internes et d'automatiser des tâches répétitives. En production, cependant, un plugin mal géré peut masquer l'état réel du cluster, introduire des risques de sécurité ou provoquer des comportements inattendus. Cette checklist progresse des symptômes observés vers des résultats vérifiés : identifier la version du plugin installé, comprendre ses dépendances et sa compatibilité, observer le comportement avant de modifier quoi que ce soit, limiter le rayon d'impact et documenter les étapes de récupération.

Ce guide s'adresse aux développeurs, consultants DevOps et équipes techniques de startups qui utilisent déjà kubectl quotidiennement. Il relie les pratiques opérationnelles, les routines de maintenance et les bonnes pratiques à des commandes concrètes, des sorties attendues, des signaux d'échec et des décisions de récupération. L'objectif est la sécurité opérationnelle : observer avant de modifier, protéger les secrets, vérifier les résultats et savoir comment revenir en arrière lorsque l'état attendu n'est pas atteint.

Inventaire des versions et de l'environnement

Avant de s'appuyer sur un plugin kubectl en production, établissez une base de référence connue : quels plugins sont installés, d'où ils proviennent, leurs versions, ainsi que les versions du client kubectl et du serveur du cluster. Un plugin qui fonctionne sur votre ordinateur portable peut se comporter différemment face à un cluster de production avec une version d'API ou une fonctionnalité différente.

Commencez par des commandes de découverte en lecture seule :

kubectl plugin list

Cela liste tous les plugins trouvés dans votre PATH, avec leurs noms d'invocation. Par exemple :

/usr/local/bin/kubectl-view-allocations
/usr/local/bin/kubectl-whoami

Ensuite, confirmez à la fois les versions client et serveur :

kubectl version --output=yaml

La sortie attendue inclut clientVersion et serverVersion avec les chaînes gitVersion, telles que v1.27.3. Si le serveur est nettement plus récent ou plus ancien que le client, les plugins qui s'appuient sur des versions d'API obsolètes peuvent échouer. Par exemple, un plugin qui interroge les objets Ingress extensions/v1beta1 échouera sur Kubernetes 1.22+ où cette API a été supprimée.

Pour les plugins individuels, beaucoup prennent en charge une sous-commande --version ou version. Sinon, inspectez les métadonnées du plugin. Les plugins installés via Krew (le gestionnaire de plugins) peuvent être vérifiés avec :

kubectl krew list

Cette sortie inclut le nom du plugin et sa version, comme view-allocations v0.15.2. Si vous avez installé des plugins manuellement, enregistrez la source d'installation et le hachage de commit dans un runbook ou un dépôt Git.

Capturez l'environnement actuel avant tout changement. Une approche simple consiste à exécuter :

kubectl plugin list > plugin-baseline-$(date +%Y%m%d).txt
kubectl version --output=yaml > cluster-version-baseline.yaml

Stockez ces fichiers pour une comparaison ultérieure. Lorsqu'un plugin commence à mal fonctionner, vous pouvez vérifier si quelque chose dans l'environnement a changé.

Chemin de configuration sûr

La configuration des plugins kubectl se trouve souvent dans le même fichier kubeconfig utilisé par kubectl, mais les plugins peuvent également lire leurs propres fichiers de configuration, variables d'environnement ou indicateurs de ligne de commande. Un chemin de configuration sûr signifie : comprendre d'où proviennent les paramètres, appliquer les modifications de manière non destructive et vérifier avant de passer en production.

Tout d'abord, inspectez les contextes kubeconfig actuels et le contexte courant :

kubectl config get-contexts
kubectl config current-context

Cela confirme sur quel cluster et quel utilisateur vous agissez. De nombreux incidents de production surviennent parce qu'un opérateur a exécuté un plugin sur le mauvais contexte. Vérifiez toujours current-context avant d'exécuter un plugin.

Si le plugin utilise sa propre configuration, recherchez les fichiers dans ~/.kube/ ou un répertoire spécifique au plugin. Par exemple, le plugin view-allocations stocke les paramètres par cluster dans ~/.kube/view-allocations.yaml. Effectuez une sauvegarde avant de modifier :

cp ~/.kube/view-allocations.yaml ~/.kube/view-allocations.yaml.bak

Ensuite, modifiez le fichier avec un éditeur de texte et appliquez le plus petit changement nécessaire. Supposons que vous deviez ajuster le type de ressource interrogé de deployments à statefulsets :

resources:
  - deployments
  - statefulsets

Après modification, exécutez le plugin en mode lecture seule s'il est disponible. Par exemple :

kubectl view-allocations --dry-run

Si le plugin ne prend pas en charge le mode dry-run, exécutez-le avec une portée étroite, comme --namespace=staging, avant de le pointer vers la production.

Utilisez des variables d'environnement pour tester les modifications sans modifier le fichier de configuration. De nombreux plugins respectent KUBECONFIG et les remplacements d'espace de noms :

KUBECONFIG=/chemin/vers/test-kubeconfig kubectl my-plugin --namespace=test

Cela isole le changement dans un kubeconfig et un espace de noms de test.

Enfin, vérifiez le résultat. Consultez les journaux ou la sortie pour le comportement attendu. Pour les plugins qui modifient l'état, confirmez le changement avec une commande kubectl en lecture seule. Par exemple, si un plugin crée une ressource, vérifiez avec :

kubectl get statefulsets --namespace=staging

Vérification et diagnostic

La vérification garantit qu'un plugin a fait ce que vous vouliez sans effets secondaires. Le diagnostic vous aide à comprendre ce qu'un plugin a réellement fait lorsque quelque chose ne va pas. Les deux s'appuient sur l'observation de l'état du cluster avant et après l'exécution du plugin.

Avant d'exécuter un plugin, capturez les objets de base pertinents. Par exemple, si le plugin va gérer des Deployments :

kubectl get deployments --namespace=production -o yaml > deployments-before.yaml

Exécutez le plugin :

kubectl my-deployment-plugin --namespace=production

Après exécution, capturez à nouveau les mêmes objets :

kubectl get deployments --namespace=production -o yaml > deployments-after.yaml

Différez les deux fichiers :

diff -u deployments-before.yaml deployments-after.yaml

Cela montre exactement ce qui a changé. Par exemple, le diff peut montrer que le plugin a ajouté une nouvelle annotation ou ajusté le nombre de réplicas.

Si le plugin échoue ou produit une sortie inattendue, inspectez ses journaux. De nombreux plugins écrivent dans stderr. Exécutez avec une verbosité accrue si prise en charge :

kubectl my-plugin --v=6

Cela peut montrer les requêtes API sous-jacentes. Vous pouvez également consulter les journaux d'audit du serveur API si votre cluster les a activés.

Pour vérifier le comportement du plugin sans affecter la production, utilisez un cluster de développement local comme kind ou minikube. Déployez une ressource de test minimale, exécutez le plugin et comparez les résultats :

kind create cluster --name plugin-test
kubectl apply -f test-deployment.yaml
kubectl my-plugin --kubeconfig ~/.kube/kind-config-plugin-test
kubectl get deployments

Cela vous donne un environnement sûr pour reproduire les problèmes.

Modes de défaillance et récupération

Les plugins kubectl peuvent échouer de plusieurs manières : versions incompatibles, dépendances manquantes, mauvaise configuration, changements d'API du cluster ou erreur de l'utilisateur. Reconnaître les modes de défaillance courants vous aide à récupérer rapidement.

Erreur plugin introuvable

error: unknown command "my-plugin" for "kubectl"

Cela signifie que l'exécutable du plugin n'est pas dans votre PATH ou n'a pas le format de nom correct (doit commencer par kubectl-). Récupération : vérifiez kubectl plugin list et assurez-vous que le binaire se trouve dans un répertoire répertorié dans PATH avec les autorisations d'exécution.

Le plugin s'exécute mais renvoie une erreur API

Error from server (NotFound): deployments.extensions "my-app" not found

Cela peut se produire lorsque le groupe d'API est obsolète ou que l'objet se trouve dans un espace de noms différent. Récupération : mettez à jour le plugin si une version plus récente prend en charge les API actuelles, ou spécifiez l'espace de noms et la version d'API corrects.

Le plugin se bloque ou expire

Cela peut indiquer des problèmes de réseau, une connectivité de cluster manquante ou un bogue du plugin. Récupération : utilisez timeout pour éviter les blocages indéfinis :

timeout 30s kubectl my-plugin

Ensuite, enquêtez sur la connectivité réseau et les journaux du plugin.

Le plugin modifie le mauvais cluster

Cela se produit lorsque le contexte kubeconfig est incorrect. Récupération : arrêtez immédiatement l'opération si possible, puis inspectez l'état du cluster et revenez en arrière en utilisant les étapes de rollback documentées. Pour éviter cela, vérifiez toujours le contexte actuel avant d'exécuter un plugin, en particulier avec des opérations qui modifient l'état.

Documentez les étapes de récupération pour chaque plugin. Par exemple, si un plugin met à l'échelle un déploiement, enregistrez la commande pour rétablir le nombre de réplicas :

kubectl scale deployment my-app --replicas=3

Stockez cela dans un runbook accessible à l'équipe.

Checklist opérationnelle

Utilisez cette checklist avant et après l'utilisation de plugins kubectl en production. Attribuez un responsable pour chaque élément et réexaminez la checklist mensuellement ou après toute mise à niveau du cluster.

Vérifier la version et la compatibilité du plugin

Commande : kubectl plugin list et kubectl version
Responsable : Ingénieur plateforme (par ex., Sarah Chen)
Fréquence : Mensuelle et avant les mises à niveau du cluster
Attendu : versions des plugins adaptées à la version du cluster, aucun avertissement d'API obsolète.

Confirmer le contexte kubeconfig actuel

Commande : kubectl config current-context
Responsable : Opérateur de service
Fréquence : À chaque fois avant d'exécuter un plugin
Attendu : le contexte correspond à l'environnement prévu (par ex., prod-us-east-1).

Sauvegarder la configuration pertinente

Commande : cp config.yaml config.yaml.bak (spécifique au plugin)
Responsable : Opérateur de service
Fréquence : Avant tout changement de configuration
Attendu : fichier de sauvegarde horodaté et stocké.

Tester le plugin en non-production d'abord

Commande : exécuter le plugin sur un cluster staging ou kind local
Responsable : Développeur effectuant le changement
Fréquence : Avant utilisation en production
Attendu : la sortie du plugin correspond au comportement attendu, aucune erreur.

Utiliser le moindre privilège et des commandes limitées

Commande : --namespace=<cible> et --dry-run si pris en charge
Responsable : Ingénieur plateforme (définit les RBAC pour les comptes de service du plugin)
Fréquence : À chaque invocation du plugin
Attendu : le plugin ne peut pas accéder à des espaces de noms ou ressources non prévus.

Enregistrer l'état avant et après

Commande : kubectl get <ressource> -o yaml > avant.yaml et apres.yaml
Responsable : Opérateur de service
Fréquence : Pour toute opération modifiant l'état
Attendu : le diff ne montre que les changements prévus.

Vérifier le succès avec des commandes indépendantes

Commande : kubectl rollout status deployment/<nom> ou kubectl get pods
Responsable : Opérateur de service
Fréquence : Après l'exécution du plugin
Attendu : le déploiement se termine, les pods sont en état Running.

Documenter les étapes de récupération

Commande : écrire les commandes de rollback dans le runbook
Responsable : Mainteneur du plugin (par ex., Alex Rivera)
Fréquence : Lors de la première introduction du plugin et après les changements
Attendu : runbook mis à jour, équipe notifiée.

Pièges courants et comment les éviter

Même les opérateurs expérimentés commettent des erreurs avec les plugins kubectl. Voici les pièges les plus courants, pourquoi ils surviennent et comment les éviter ou s'en remettre.

Piège 1 : Supposer que la version du plugin correspond à la version du cluster

Pourquoi cela arrive : Les auteurs de plugins peuvent ne pas mettre à jour pour les nouvelles versions de l'API Kubernetes, ou les utilisateurs installent une ancienne version.

Comment éviter : Avant d'utiliser un plugin, consultez sa documentation pour les versions Kubernetes prises en charge. Utilisez kubectl plugin list et comparez avec la version du cluster. Exécutez un test rapide en dry-run ou sur un cluster de staging.

Récupération : Si un plugin échoue en raison d'une dépréciation d'API, mettez à jour le plugin ou trouvez une alternative. Si aucune mise à jour n'est disponible, envisagez de forker le plugin ou d'utiliser les commandes natives kubectl comme solution de contournement.

Piège 2 : Exécuter des plugins avec le mauvais contexte kubeconfig

Pourquoi cela arrive : Contextes multiples dans kubeconfig, et le contexte actuel n'est pas réinitialisé après avoir changé de tâche.

Comment éviter : Exécutez toujours kubectl config current-context avant un plugin. Utilisez des noms de contexte qui identifient clairement l'environnement (par ex., prod-aws, dev-minikube). Envisagez d'utiliser des outils comme kubectx pour changer de contexte visuellement.

Récupération : Si un plugin agit sur le mauvais cluster, exécutez immédiatement kubectl get events --sort-by=.metadata.creationTimestamp pour voir l'activité récente. Ensuite, annulez les modifications en utilisant le yaml stocké ou le runbook.

Piège 3 : Ne pas sauvegarder avant un plugin qui modifie l'état

Pourquoi cela arrive : Les opérateurs font confiance au plugin ou sont pressés.

Comment éviter : Prenez l'habitude de sauvegarder : kubectl get <ressource> -o yaml > backup.yaml avant d'exécuter le plugin. Stockez les sauvegardes dans un contrôle de version si possible.

Récupération : Appliquez la sauvegarde avec kubectl apply -f backup.yaml ou utilisez le rollback propre au plugin s'il est disponible.

Piège 4 : Utiliser des plugins sans vérifier leur posture de sécurité

Pourquoi cela arrive : Les plugins peuvent être installés à partir de sources non fiables ou nécessiter des autorisations RBAC larges.

Comment éviter : Installez uniquement des plugins provenant de sources fiables (par ex., l'index Krew ou le dépôt de votre organisation). Examinez le code source si possible. Exécutez le plugin avec un compte de service dédié avec le moindre privilège.

Récupération : Révoquez immédiatement les autorisations si un plugin est compromis. Auditez ce qu'il a fait via les journaux d'audit de l'API et annulez les modifications.

Piège 5 : Ignorer la sortie du plugin et supposer le succès

Pourquoi cela arrive : Les opérateurs peuvent exécuter le plugin et passer à autre chose sans vérifier le résultat.

Comment éviter : Après avoir exécuté un plugin, vérifiez avec des commandes kubectl indépendantes. Par exemple, si un plugin prétend mettre à l'échelle un déploiement, vérifiez kubectl get deployment my-app -o jsonpath='{.spec.replicas}' pour confirmer le nombre.

Récupération : Si la vérification échoue, arrêtez-vous et diagnostiquez avant de continuer. Utilisez kubectl describe et les journaux pour comprendre l'écart.

Conclusion

Une approche prête pour la production des plugins kubectl ne consiste pas à mémoriser des commandes ; il s'agit d'appliquer une checklist opérationnelle disciplinée. L'inventaire des versions et de l'environnement, la configuration sûre, la vérification et la planification de la récupération transforment un outil pratique en un élément fiable de votre workflow Kubernetes.

Commencez petit : choisissez un plugin que vous utilisez en production et appliquez les trois premiers éléments de la checklist dès aujourd'hui. Capturez sa version, testez-le dans un espace de noms de staging et confirmez votre contexte kubeconfig. Documentez les étapes et partagez-les avec votre équipe. À mesure que vous gagnez en confiance, étendez la checklist à d'autres plugins et intégrez-la dans votre processus de gestion des changements.

En fin de compte, les plugins kubectl devraient rendre vos opérations Kubernetes plus sûres, pas plus risquées. En observant avant de modifier, en limitant la portée, en vérifiant les résultats et en préparant des chemins de récupération, vous pouvez exploiter la puissance des plugins tout en gardant le contrôle.