Dépannage des contrôleurs d'admission extensibles Kubernetes : guide pratique avec commandes et exemples

Introduction

Les contrôleurs d'admission extensibles Kubernetes sont un mécanisme puissant pour appliquer des politiques et modifier des ressources avant leur persistance. Ils permettent aux administrateurs de cluster d'intégrer une logique personnalisée via des webhooks d'admission, mais lorsqu'ils rencontrent des problèmes, ils peuvent bloquer les déploiements, empêcher la création de Pods, ou même dégrader la réactivité du serveur API. Le dépannage de ces contrôleurs exige une approche systématique qui combine la compréhension du flux de contrôle d'admission, la capacité à inspecter les configurations des webhooks, et la compétence à lire les journaux du serveur API. Ce guide fournit des exemples pratiques et des commandes pour diagnostiquer et récupérer des échecs courants.

Un pilote étroit et mesurable est recommandé avant de déployer largement les contrôleurs d'admission, car il permet une inspection locale et réduit les risques. Cela s'aligne avec le principe selon lequel un processus clair réduit les retouches et accélère la production de configurations fiables.

Inventaire de l'environnement et des versions

Avant de dépanner, rassemblez des informations sur le cluster Kubernetes et les contrôleurs d'admission utilisés. Cela inclut la version de Kubernetes, la configuration du serveur API, et les webhooks spécifiques configurés.

Prérequis :

• Accès au cluster avec des permissions suffisantes pour afficher les objets ValidatingWebhookConfiguration et MutatingWebhookConfiguration.
• Capacité à lire les journaux du pod ou du processus kube-apiserver.
• L'outil en ligne de commande kubectl configuré pour le cluster.
• Connaissance des points de terminaison du service webhook et de leur comportement attendu.

Commandes d'inventaire

Exécutez les commandes suivantes pour établir une base de référence :

1. Vérifier la version de Kubernetes :

   kubectl version --short

La sortie attendue inclut les versions client et serveur, par exemple : Server Version: v1.25.3.

1. Lister les configurations des webhooks d'admission :

   kubectl get validatingwebhookconfigurations, mutatingwebhookconfigurations

Cela liste toutes les configurations de webhooks. Notez celles qui échouent ou sont suspectes.

1. Obtenir les détails d'une configuration de webhook spécifique :

   kubectl get validatingwebhookconfiguration <nom> -o yaml

Examinez le tableau webhooks pour chaque webhook : clientConfig, rules, et failurePolicy.

1. Vérifier les pods du serveur API (si vous utilisez des pods statiques ou un plan de contrôle géré) :

   kubectl get pods -n kube-system | grep kube-apiserver

Pour les clusters autogérés, localisez le nom du pod du serveur API pour la récupération des journaux.

Considérations de topologie

• Identifiez si les webhooks pointent vers des services internes au cluster ou des URL externes.
• Pour les services internes, vérifiez que le service existe et possède des endpoints.
• Pour les URL externes, assurez la connectivité réseau depuis le serveur API.

Exemple de tableau d'inventaire :

Cet inventaire établit une base de référence pour le dépannage.

Chemin de configuration sécurisé

Les webhooks d'admission peuvent être dangereux car une mauvaise configuration peut bloquer toute création ou mutation de ressources. Il est important d'adopter un chemin de configuration sécurisé qui limite le rayon d'impact et permet un retour en arrière rapide.

Choix d'implémentation limités

• Utiliser failurePolicy: Ignore lors du déploiement initial : Cela garantit que si le webhook est injoignable, le serveur API ignorera l'échec et autorisera la requête. Une fois la stabilité confirmée, vous pouvez passer à Fail pour une application stricte.

Extrait d'une configuration de webhook :

  failurePolicy: Ignore

• Limiter les règles à des ressources ou namespaces spécifiques : Au lieu d'appliquer le webhook à tout le cluster, utilisez namespaceSelector ou objectSelector pour cibler un namespace de test ou des labels spécifiques.

Exemple :

  namespaceSelector:
    matchLabels:
      admission-webhook: enabled

• Définir timeoutSeconds de manière appropriée : La valeur par défaut est de 10 secondes ; ajustez selon la latence du webhook.
• Utiliser sideEffects: None si le webhook n'a pas d'effets secondaires : Cela est requis pour le support du dry-run et aide aux tests.
• Tester d'abord dans un cluster non productif : Déployez toujours le webhook dans un environnement de préproduction.

Procédure de modification de configuration

Pour modifier une configuration de webhook en toute sécurité, utilisez kubectl edit ou appliquez un fichier YAML avec contrôle de version.

Exemple de mise à jour de failurePolicy à Ignore pour un webhook de validation :

kubectl patch validatingwebhookconfiguration pod-policy.example.com --type='json' -p='[{"op": "replace", "path": "/webhooks/0/failurePolicy", "value": "Ignore"}]'

Sortie attendue : validatingwebhookconfiguration.admissionregistration.k8s.io/pod-policy.example.com patched.

Conservez toujours une sauvegarde de la configuration originale pour un retour en arrière.

Vérification et diagnostics

Lors du dépannage, vous devez vérifier que le webhook est appelé, que le point de terminaison répond correctement, et que le serveur API se comporte comme prévu.

Vérifications observables

Récupérez les journaux du pod kube-apiserver. Sur un cluster géré, vous devrez peut-être utiliser la journalisation du fournisseur cloud.

1. Vérifier les journaux du serveur API pour les erreurs de webhook :

   kubectl logs -n kube-system kube-apiserver-<nom-du-nœud> | grep -i webhook

Recherchez les lignes contenant failed calling webhook, webhook timeout, ou x509: certificate signed by unknown authority.

Exemple d'extrait de journal :

   E0201 12:34:56.789012 1 dispatcher.go:167] failed calling webhook "pod-policy.example.com": Post "https://webhook-service.webhook.svc:443/validate?timeout=10s": dial tcp 10.0.0.1:443: connect: connection refused

Cela indique que le service webhook est injoignable.

Depuis l'intérieur du cluster, utilisez un pod avec curl pour envoyer une requête d'examen d'admission.

1. Tester directement le point de terminaison du webhook :

   kubectl run curl-test --image=curlimages/curl -i --tty --rm -- sh
   curl -k -X POST https://webhook-service.webhook.svc:443/validate -H "Content-Type: application/json" -d '{"apiVersion":"admission.k8s.io/v1","kind":"AdmissionReview","request":{"uid":"test"}}'

Vérifiez la réponse ; elle doit être un AdmissionReview valide avec un champ allowed.

Utilisez kubectl apply --dry-run=server pour tester si une ressource serait admise sans la créer réellement.

1. Vérifier la configuration du webhook avec dry-run :

   kubectl apply -f pod.yaml --dry-run=server

Si le webhook bloque la requête, vous verrez une erreur comme denied by admission webhook.

Les webhooks doivent utiliser HTTPS. Si le serveur API ne peut pas vérifier le certificat du serveur, les requêtes échouent. Recherchez les erreurs de certificat dans les journaux. Assurez-vous que le bundle CA dans la configuration du webhook correspond au certificat de service.

1. Vérifier les certificats :

Certains webhooks génèrent des événements sur les ressources qu'ils affectent.

1. Utiliser kubectl describe pour les événements :

Résultats attendus

• Les journaux du serveur API montrent des appels de webhook réussis avec des réponses HTTP 200.
• Le test direct du point de terminaison renvoie une réponse AdmissionReview avec "allowed": true ou un patch approprié.
• Le dry-run de ressources valides réussit ; les ressources invalides sont rejetées avec un message clair.

Modes de défaillance et récupération

Les modes de défaillance courants incluent l'indisponibilité du service webhook, les problèmes de certificat, le délai d'attente, et les règles mal configurées causant un blocage involontaire. La récupération exige une action rapide pour restaurer la fonctionnalité du cluster.

Mode de défaillance 1 : Service webhook arrêté ou injoignable

• Symptôme : Les journaux du serveur API montrent connection refused ou timeout ; toutes les requêtes vers les ressources affectées échouent si failurePolicy: Fail.
• Récupération :

1. Définir temporairement failurePolicy: Ignore pour débloquer les requêtes :

     kubectl patch validatingwebhookconfiguration <nom> --type='json' -p='[{"op": "replace", "path": "/webhooks/0/failurePolicy", "value": "Ignore"}]'

1. Corriger le service sous-jacent (redémarrer les pods, corriger le sélecteur de service).
2. Une fois le service sain, revenir à Fail si nécessaire.

Mode de défaillance 2 : Problèmes de certificat

• Symptôme : Les journaux montrent x509: certificate signed by unknown authority ou tls: failed to verify certificate.
• Récupération :
• Mettre à jour le champ caBundle dans la configuration du webhook avec le certificat CA correct.
• S'assurer que le serveur webhook utilise un certificat valide pour son nom DNS de service.
• Utiliser un outil de gestion de certificats comme cert-manager pour automatiser.

Mode de défaillance 3 : Délai d'attente du webhook

• Symptôme : Les journaux montrent context deadline exceeded ou timeout.
• Récupération :
• Augmenter timeoutSeconds dans la configuration du webhook (maximum 30).
• Optimiser le traitement du webhook.

Mode de défaillance 4 : Webhook bloquant toutes les ressources en raison de règles larges

• Symptôme : Même les ressources non liées sont refusées.
• Récupération :
• Réduire les règles ou utiliser namespaceSelector pour limiter la portée.
• Si critique, supprimer temporairement la configuration du webhook :

    kubectl delete validatingwebhookconfiguration <nom>

Cela supprime entièrement le webhook ; assurez-vous de pouvoir le recréer plus tard.

Stratégies de retour en arrière

• Maintenir des sauvegardes versionnées des configurations de webhooks.
• Utiliser GitOps pour suivre les changements et permettre un retour rapide.
• Tester les procédures de retour en arrière en préproduction.

Vérifications de récupération : Après la récupération, vérifiez que la création de ressources réussit et que le webhook fonctionne comme prévu pour les ressources ciblées.

Liste de contrôle des opérations

Utilisez cette liste de contrôle pour les opérations continues et la revue des contrôleurs d'admission :

• [ ] Surveiller régulièrement les journaux du serveur API pour les erreurs de webhook.
• [ ] S'assurer que les services webhook ont une haute disponibilité et des limites de ressources appropriées.
• [ ] Renouveler les certificats avant leur expiration.
• [ ] Revoir les configurations des webhooks pour le moindre privilège et la portée.
• [ ] Tester le comportement des webhooks en préproduction avant les changements.
• [ ] Documenter les politiques d'échec et les procédures de retour en arrière.
• [ ] Définir des alertes pour les taux d'échec des webhooks.
• [ ] Effectuer des tests de chaos périodiques pour valider la résilience.

Exemple de requête de surveillance (si vous utilisez Prometheus) :

rate(apiserver_admission_webhook_admission_duration_seconds_count{name="pod-policy.example.com"}[5m]) > 0

Cette liste de contrôle garantit un fonctionnement fiable et une récupération rapide.

Conclusion

Le dépannage des contrôleurs d'admission extensibles Kubernetes exige une approche méthodique : inventorier l'environnement, configurer en toute sécurité avec des politiques d'échec et une portée limitée, vérifier via les journaux et les dry-runs, et récupérer des défaillances avec des actions de retour en arrière rapides. En suivant les étapes pratiques et la liste de contrôle de ce guide, les équipes peuvent minimiser les temps d'arrêt et maintenir la stabilité du cluster. Commencez par un pilote étroit et mesurable puis élargissez progressivement, en gardant toujours en place l'observabilité et les plans de retour en arrière. Les prochaines étapes vérifiées après avoir résolu les problèmes immédiats sont de mettre en œuvre la surveillance, d'automatiser la gestion des certificats et de documenter les procédures opérationnelles.