Contrôleurs d'admission Kubernetes : commandes, exemples et opérations quotidiennes

Introduction

Les contrôleurs d'admission dans Kubernetes agissent comme des gardiens pour les requêtes API, les interceptant après l'authentification et l'autorisation mais avant la persistance. Ils appliquent des politiques, valident les ressources et modifient les objets. Cet article fournit une référence pratique en ligne de commande pour les développeurs, les consultants DevOps et les équipes techniques de startups travaillant avec les contrôleurs d'admission.

Vous apprendrez à inspecter les contrôleurs activés, tester les configurations, diagnostiquer les échecs et récupérer des problèmes courants. En suivant les exemples, vous passerez de l'observation d'un problème à la vérification d'une correction avec des commandes claires et des sorties attendues.

L'objectif est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés au lieu de secrets, vérifier le résultat et documenter les étapes de récupération.

Inventaire de la version et de l'environnement

Avant d'interagir avec les contrôleurs d'admission, rassemblez les détails de l'environnement. Exécutez ces commandes en lecture seule pour comprendre l'état actuel de votre cluster.

Vérifier la version du cluster

kubectl version --short

La sortie attendue inclut les versions client et serveur (par exemple, Server Version: v1.28.2). Le comportement des contrôleurs d'admission peut varier selon la version, notez donc la version du serveur.

Lister les contrôleurs d'admission activés Les contrôleurs d'admission sont configurés dans les drapeaux du serveur API. Sur les nœuds du plan de contrôle, vérifiez le processus kube-apiserver :

ps aux | grep kube-apiserver

Recherchez le drapeau --enable-admission-plugins. Il liste les contrôleurs activés dans l'ordre, par exemple, --enable-admission-plugins=NamespaceLifecycle,LimitRanger,ServiceAccount,ResourceQuota,ValidatingAdmissionWebhook,MutatingAdmissionWebhook.

Alternativement, sur les clusters gérés (EKS, GKE, AKS), vous n'aurez peut-être pas d'accès direct. Inspectez plutôt la configuration du cluster via la CLI du fournisseur cloud ou la console web.

Lister les configurations d'admission actuelles Si vous utilisez ValidatingWebhookConfiguration ou MutatingWebhookConfiguration :

kubectl get validatingwebhookconfigurations
kubectl get mutatingwebhookconfigurations

Exemple de sortie :

NAME                                   WEBHOOKS   AGE
pod-policy.example.com                 1          5d

Inspecter les détails

kubectl describe validatingwebhookconfiguration pod-policy.example.com

Recherchez les champs Rules, NamespaceSelector et FailurePolicy.

Prérequis

kubectl installé et configuré avec les autorisations d'administrateur de cluster ou de visualisation des configurations de webhook.
Accès aux journaux du plan de contrôle si vous déboguez des contrôleurs intégrés.
Dans les clusters gérés, autorisations pour utiliser les commandes du fournisseur (par exemple, aws eks describe-cluster).

Question rapide 1 sur 2

Selon les passages de référence, à quels types de requêtes API les contrôleurs d'admission s'appliquent-ils ?

La référence [1] indique que les contrôleurs d'admission s'appliquent aux requêtes qui créent, suppriment ou modifient des objets. Ils peuvent également bloquer les verbes personnalisés, mais pas les lectures.

Chemin de configuration sûr

Apporter des modifications aux contrôleurs d'admission peut affecter le comportement à l'échelle du cluster. Suivez un chemin prudent pour minimiser les risques.

Étape 1 : Observer la configuration actuelle Capturez toujours l'état existant avant toute modification :

kubectl get validatingwebhookconfiguration pod-policy.example.com -o yaml > /tmp/original-webhook.yaml

Cette sauvegarde peut être restaurée plus tard si nécessaire.

Étape 2 : Tester dans un espace de noms de développement Créez un espace de noms de test s'il n'existe pas :

kubectl create namespace admission-test

Appliquez un manifeste de pod d'exemple pour voir s'il passe l'admission :

cat <<EOF | kubectl apply -n admission-test -f -
apiVersion: v1
kind: Pod
metadata:
  name: test-pod
spec:
  containers:
  - name: nginx
    image: nginx:latest
EOF

Si l'admission rejette, vous verrez une erreur comme :

Error from server (Forbidden): error when creating "STDIN": admission webhook "pod-policy.example.com" denied the request: Pod must have label 'team'

Cela vous indique que la politique est active et ce qu'elle exige.

Étape 3 : Modifier la configuration avec un changement minimal Exemple : Mettez à jour la politique d'échec d'un webhook de Fail à Ignore pour tester le comportement sans bloquer toutes les requêtes. Modifiez la ressource :

kubectl edit validatingwebhookconfiguration pod-policy.example.com

Changez failurePolicy: Fail en failurePolicy: Ignore, enregistrez et quittez. Le serveur API mettra à jour la configuration.

Étape 4 : Vérifier le changement Exécutez à nouveau le pod de test et vérifiez s'il est créé (si la politique est passée) ou toujours rejeté (si la politique est toujours active).

kubectl apply -n admission-test -f test-pod.yaml
kubectl get pods -n admission-test

Si le pod est créé, le changement a pris effet. Surveillez les journaux du serveur API pour les erreurs d'appel webhook si quelque chose ne va pas.

Étape 5 : Nettoyer les ressources de test

kubectl delete namespace admission-test

Supprimez toujours les artefacts de test.

Vérification et diagnostic

Après les modifications, vérifiez que les contrôleurs d'admission fonctionnent comme prévu. Utilisez ces commandes pour vérifier l'état et résoudre les problèmes.

Vérifier la santé du serveur API Les contrôleurs d'admission font partie du serveur API. Si le serveur API est en mauvaise santé, les requêtes d'admission échouent. Sur un nœud du plan de contrôle, vérifiez le pod du serveur API (si vous utilisez des pods statiques) :

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

Ou vérifiez le processus :

curl -k https://localhost:6443/healthz?verbose

La sortie attendue inclut ok pour toutes les vérifications, y compris admission le cas échéant.

Afficher les journaux des contrôleurs d'admission Les journaux du serveur API contiennent les décisions d'admission et les erreurs potentielles. Accédez aux journaux en utilisant journalctl sur les nœuds du plan de contrôle :

journalctl -u kube-apiserver -f | grep admission

Pour les clusters gérés, utilisez les services de journaux du fournisseur cloud (par exemple, CloudWatch pour EKS).

Tester avec une requête connue comme mauvaise Créez un pod qui viole une politique pour voir le rejet :

kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: bad-pod
  namespace: default
spec:
  containers:
  - name: nginx
    image: nginx
EOF

Si une politique exige des étiquettes, la sortie montrera le message de refus du webhook. Cela confirme l'application.

Inspecter les configurations des webhooks Assurez-vous que les points de terminaison du service webhook sont accessibles :

kubectl get endpoints -n webhook-namespace

S'il n'y a pas de points de terminaison, le service webhook peut ne pas fonctionner. Vérifiez les pods :

kubectl get pods -n webhook-namespace

Si le service webhook est en panne et que failurePolicy est Fail, toutes les requêtes correspondantes seront rejetées. Passez à Ignore ou corrigez le service.

Utiliser dry-run pour tester sans persistance Kubernetes prend en charge dry-run pour certaines ressources. Par exemple :

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

Cela envoie la requête à travers l'admission sans persistance, montrant si elle serait acceptée. Utile pour tester les politiques.

Modes de défaillance et récupération

Les contrôleurs d'admission peuvent échouer, provoquant le rejet ou le blocage des requêtes API. Reconnaissez ces modes et récupérez rapidement.

Mode de défaillance 1 : Service webhook indisponible Si le service d'un webhook de validation est en panne et que failurePolicy est Fail, les requêtes correspondant à ses règles seront rejetées avec une erreur :

Error from server (InternalError): error when creating "pod.yaml": Internal error occurred: failed calling webhook "pod-policy.example.com": Post "https://webhook-service.webhook-namespace.svc:443/validate?timeout=10s": dial tcp 10.0.0.5:443: connect: connection refused

Récupération : Soit restaurez le service webhook, soit définissez temporairement failurePolicy à Ignore :

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

Ensuite, corrigez le service et restaurez Fail.

Mode de défaillance 2 : Délai d'attente du webhook Les appels webhook ont un délai d'attente (par défaut 10 secondes). Si le webhook prend trop de temps, les requêtes échouent. Vérifiez les journaux du webhook pour un traitement lent et augmentez le délai dans la configuration du webhook si nécessaire :

webhooks:
- name: pod-policy.example.com
  timeoutSeconds: 30

Appliquez avec kubectl edit. Faites également évoluer les répliques du webhook pour gérer la charge.

Mode de défaillance 3 : Règles de webhook mal configurées Si les règles du webhook correspondent à des ressources inattendues, cela peut bloquer des opérations non liées. Par exemple, une règle correspondant à tous les pods dans tous les espaces de noms. Ajustez namespaceSelector ou les règles pour limiter la portée. Utilisez des étiquettes ou des sélecteurs d'espace de noms pour cibler uniquement les objets prévus.

Récupération après une mauvaise configuration Si une nouvelle configuration de contrôleur d'admission casse le cluster (par exemple, toutes les créations de pods échouent), revenez à la configuration précédente :

kubectl apply -f /tmp/original-webhook.yaml

Ou, si le serveur API ne démarre pas en raison d'un drapeau de plugin d'admission invalide, modifiez le manifeste kube-apiserver sur le nœud du plan de contrôle (/etc/kubernetes/manifests/kube-apiserver.yaml) et redémarrez kubelet. Pour les clusters gérés, contactez le support du fournisseur.

Question rapide 2 sur 2

Parmi les types de contrôleurs d'admission suivants, lesquels peuvent modifier les données d'une ressource en cours d'admission ?

La référence [1] explique que les contrôleurs de mutation peuvent modifier les données de la ressource en cours de modification, tandis que les contrôleurs de validation ne le peuvent pas.

Liste de contrôle des opérations

Utilisez cette liste de contrôle pour vérifier régulièrement la santé des contrôleurs d'admission et la conformité aux politiques.

[ ] Quotidien : Vérifiez la santé du serveur API (kubectl get --raw='/healthz?verbose').
[ ] Hebdomadaire : Examinez les configurations des webhooks pour détecter des changements inattendus (kubectl get validatingwebhookconfigurations,mutatingwebhookconfigurations -o yaml | diff - previous-config/).
[ ] Mensuel : Auditez les journaux d'admission pour les requêtes refusées qui pourraient indiquer une mauvaise configuration de politique ou des tentatives d'attaque. Utilisez les services de journaux cloud ou les journaux du serveur API.
[ ] Avant tout changement : Sauvegardez les configurations de webhook actuelles et testez dans un espace de noms sandbox.
[ ] Après tout changement : Vérifiez que les requêtes conformes et non conformes se comportent comme prévu (dry-run ou pod de test).

Attribuez un seul propriétaire pour les politiques des contrôleurs d'admission, par exemple, « Responsable de l'ingénierie de plateforme », chargé d'examiner les changements et de s'assurer que la documentation est à jour. Réexaminez la liste de contrôle tous les trimestres pour l'ajuster aux nouvelles politiques ou aux changements de cluster.

Pièges courants

Voici les erreurs fréquentes lors de la gestion des contrôleurs d'admission et comment les éviter.

Piège 1 : Définir failurePolicy à Fail sans un webhook fiable

Pourquoi : Si le service webhook est en panne, toutes les requêtes API correspondantes échouent, provoquant des pannes.
Éviter : Utilisez failurePolicy=Ignore pour les politiques non critiques ou assurez une haute disponibilité du service webhook.
Récupérer : Patchez failurePolicy à Ignore temporairement et corrigez le service.

Piège 2 : Règles de webhook trop larges

Pourquoi : Les règles correspondent à toutes les ressources ou espaces de noms, interférant avec les opérations système.
Éviter : Utilisez des sélecteurs d'espace de noms ou des étiquettes d'objet pour limiter la portée. Par exemple, ne correspondre qu'aux pods avec l'étiquette app: myapp.
Récupérer : Modifiez les règles pour réduire la portée.

Piège 3 : Ignorer les paramètres de délai d'attente

Pourquoi : Le délai par défaut de 10 secondes peut être trop court pour des webhooks complexes, provoquant des échecs intermittents.
Éviter : Définissez timeoutSeconds de manière appropriée après des tests de charge du webhook.
Récupérer : Augmentez le délai dans la configuration du webhook.

Piège 4 : Ne pas tester dans un espace de noms de développement

Pourquoi : Appliquer un nouveau webhook directement en production peut casser les charges de travail existantes si la politique les rejette.
Éviter : Testez toujours dans un espace de noms séparé avec un sous-ensemble de ressources avant de déployer à l'échelle du cluster.
Récupérer : Revenez en arrière sur la configuration du webhook si la production est affectée.

Piège 5 : Oublier de mettre à jour les certificats du webhook

Pourquoi : Les webhooks utilisent souvent TLS. Les certificats expirés font que le serveur API rejette les appels webhook.
Éviter : Utilisez cert-manager ou un renouvellement automatisé et surveillez les dates d'expiration.
Récupérer : Mettez à jour le certificat et redémarrez les pods du webhook.

Conclusion

La gestion des contrôleurs d'admission Kubernetes nécessite une observation attentive, des changements précis et des procédures de récupération robustes. En utilisant les commandes et les exemples de cet article, vous pouvez inspecter les contrôleurs activés, tester les politiques, diagnostiquer les échecs et récupérer des problèmes courants.

Comme prochaine étape, choisissez une vérification à faible risque : inspectez les configurations de webhook de votre cluster, sauvegardez-les et testez une politique dans un espace de noms de développement. Enregistrez l'état actuel, exécutez les vérifications documentées et comparez les résultats avec le comportement attendu. Examinez les dépendances telles que les espaces de noms et les rôles pour vous assurer que les politiques sont correctement définies.

Un flux de travail opérationnel fiable rend les échecs visibles, protège les valeurs sensibles, limite les changements aux ressources prévues et définit la récupération avant qu'un incident ne force une décision.