Introduction
Les autorisations et le réseau dans Kubernetes sont profondément liés. Même avec des règles RBAC correctes, une requête peut échouer si le chemin réseau entre les composants est rompu. Les problèmes courants incluent les échecs de résolution DNS, les ports bloqués, un routage mal configuré ou des règles de pare-feu qui abandonnent silencieusement le trafic. Ce guide propose une approche structurée de dépannage avec des exemples de commandes pratiques, des sorties attendues et des étapes de diagnostic sûres. Vous apprendrez à vérifier la connectivité, à identifier les défaillances réseau liées aux autorisations et à rétablir le service sans suppositions.
À la fin, vous disposerez d'une liste de vérification reproductible pour dépanner les problèmes de réseau liés aux autorisations Kubernetes dans vos propres clusters. Nous couvrons l'inventaire des versions, la configuration sûre, la vérification, les modes de défaillance et la récupération, avec des commandes concrètes et des tableaux pour référence rapide.
Inventaire des versions et de l'environnement
Avant de commencer le dépannage, établissez l'environnement exact. Exécutez ces commandes sur un nœud du plan de contrôle ou via kubectl avec un accès cluster-admin. Notez la version du serveur Kubernetes, le plugin réseau, l'adresse IP du service DNS et le point de terminaison du serveur API.
# Version de Kubernetes
kubectl version --short
# Sortie attendue (exemple) :
# Client Version: v1.28.2
# Server Version: v1.28.2
# Point de terminaison du serveur API
kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}'
# Sortie attendue :
# https://192.168.1.100:6443
# Adresse IP du service DNS (généralement l'IP du cluster de kube-dns ou CoreDNS)
kubectl get svc -n kube-system -l k8s-app=kube-dns
# Sortie attendue (exemple) :
# NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
# kube-dns ClusterIP 10.96.0.10 <none> 53/UDP,53/TCP 10d
# Pods du plugin réseau (exemple pour Calico)
kubectl get pods -n kube-system -l k8s-app=calico-node
# Sortie attendue :
# NAME READY STATUS RESTARTS AGE
# calico-node-xxxxx 1/1 Running 0 10d
Hypothèses de topologie : un cluster standard avec un nœud de plan de contrôle et plusieurs nœuds de travail, utilisant CoreDNS pour le DNS du cluster et un plugin CNI tel que Calico, Flannel ou Cilium. Des pare-feu peuvent exister entre les nœuds et entre les clients et le serveur API.
Prérequis pour le dépannage :
- kubectl configuré avec les permissions appropriées (au moins un accès en lecture aux ressources et la possibilité d'exécuter exec dans kube-system).
- Utilitaires réseau : curl, dig ou nslookup, nc ou telnet, traceroute, ip, iptables (sur les nœuds).
- Accès aux shells des nœuds (via SSH ou kubectl debug node).
Documentez les éléments suivants dans un tableau pour garder une trace :
| Composant | Version / Adresse | Notes |
|---|---|---|
| Serveur API Kubernetes | https://192.168.1.100:6443 | Vérifier avec kubectl cluster-info |
| IP du service CoreDNS | 10.96.0.10 | ClusterIP du service kube-dns |
| Plugin CNI | Calico v3.26.1 | Vérifier avec kubectl get pods -n kube-system |
| Plage CIDR des nœuds | 10.244.0.0/16 | Depuis la configuration CNI |
Chemin de configuration sûr
Lorsque des modifications sont nécessaires, commencez par la plus petite mise à jour de configuration réversible. Pour le réseau des autorisations, les ajustements courants incluent :
- Mise à jour des rôles RBAC pour autoriser les recherches DNS (si vous utilisez des comptes de service personnalisés).
- Ajustement des drapeaux du serveur API pour les modes d'autorisation ou les paramètres réseau.
- Modification des politiques réseau CNI qui peuvent bloquer les ports requis.
- Ajout de règles de pare-feu pour le trafic nœud-à-nœud et pod-vers-serveur API.
Exemple : Ajout d'une permission RBAC manquante pour la résolution DNS
Le compte de service d'un pod peut manquer de la permission de créer des EndpointSlices ou des Services, provoquant des échecs intermittents de résolution DNS. Pour vérifier les permissions actuelles :
kubectl auth can-i list endpointslices --as=system:serviceaccount:default:my-app
# Sortie attendue si refusé :
# no
Si le compte de service en a besoin, créez un Role et un RoleBinding limités à l'espace de noms nécessaire :
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
namespace: default
name: app-dns-reader
rules:
- apiGroups: ["discovery.k8s.io"]
resources: ["endpointslices"]
verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
namespace: default
name: app-dns-reader-binding
subjects:
- kind: ServiceAccount
name: my-app
namespace: default
roleRef:
kind: Role
name: app-dns-reader
apiGroup: rbac.authorization.k8s.io
Appliquez avec :
kubectl apply -f rbac-dns.yaml
# Sortie attendue :
# role.rbac.authorization.k8s.io/app-dns-reader created
# rolebinding.rbac.authorization.k8s.io/app-dns-reader-binding created
Vérifiez maintenant la permission :
kubectl auth can-i list endpointslices --as=system:serviceaccount:default:my-app
# Sortie attendue :
# yes
Si le problème est une politique réseau bloquant le trafic DNS, définissez une politique limitée aux pods nécessaires :
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: allow-dns
namespace: default
spec:
podSelector:
matchLabels:
app: my-app
policyTypes:
- Egress
egress:
- to:
- namespaceSelector: {}
ports:
- protocol: UDP
port: 53
- protocol: TCP
port: 53
Appliquez et vérifiez avec kubectl get networkpolicy.
Pratique sûre : testez toujours les modifications dans un espace de noms hors production ou un cluster de test d'abord. Utilisez kubectl diff -f <fichier> pour prévisualiser les modifications avant de les appliquer.
Vérification et diagnostics
Cette section fournit des commandes étape par étape pour vérifier chaque couche de la pile réseau des autorisations. Commencez du côté client et avancez vers le serveur API.
1. Connectivité au serveur API
Depuis un nœud ou une station de travail, testez la connectivité TCP vers le serveur API :
nc -zv 192.168.1.100 6443
# Sortie attendue :
# Connection to 192.168.1.100 6443 port [tcp/*] succeeded!
Si cela échoue, vérifiez les règles de pare-feu entre la source et le serveur API. Vérifiez également que le serveur API écoute :
# Sur le nœud du plan de contrôle
ss -tlnp | grep 6443
# Sortie attendue :
# LISTEN 0 4096 *:6443 *:* users:(("kube-apiserver",pid=1234,fd=7))
2. Résolution DNS
Vérifiez la résolution DNS depuis un pod. Créez un pod temporaire si nécessaire :
kubectl run -it --rm dnsutils --image=infoblox/dnstools:latest --restart=Never -- /bin/sh
# À l'intérieur du pod :
nslookup kubernetes.default.svc.cluster.local
# Sortie attendue (exemple) :
# Server: 10.96.0.10
# Address: 10.96.0.10#53
#
# Name: kubernetes.default.svc.cluster.local
# Address: 10.96.0.1
Si l'adresse n'est pas l'IP de service attendue ou si la recherche expire, examinez CoreDNS. Vérifiez les pods CoreDNS et les journaux :
kubectl get pods -n kube-system -l k8s-app=kube-dns
kubectl logs -n kube-system -l k8s-app=kube-dns --tail=20
3. Routage des services
Vérifiez qu'un Service route vers ses endpoints. Pour un service nommé my-svc dans l'espace de noms default :
kubectl get svc my-svc -n default -o wide
# Sortie attendue :
# NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE SELECTOR
# my-svc ClusterIP 10.96.100.10 <none> 80/TCP 1h app=my-app
kubectl get endpoints my-svc -n default
# Sortie attendue :
# NAME ENDPOINTS AGE
# my-svc 10.244.1.2:8080 1h
Si les endpoints sont vides, le sélecteur de service peut ne correspondre à aucun pod, ou les pods ne sont pas prêts. Vérifiez les pods :
kubectl get pods -n default -l app=my-app
4. Vérification de la décision d'autorisation
Utilisez kubectl auth can-i pour tester des permissions spécifiques sans faire de requêtes réelles :
kubectl auth can-i create deployments --as=system:serviceaccount:default:my-app -n default
# Sortie attendue :
# yes (ou no)
Pour une vérification plus approfondie, utilisez kubectl auth reconcile pour voir les différences, mais soyez prudent car cela peut modifier les RBAC.
Pour voir les règles RBAC réelles d'un utilisateur ou d'un compte de service, utilisez kubectl get rolebindings et inspectez :
kubectl get rolebinding -n default -o yaml | grep -A 10 subjects
5. Vérification des politiques réseau
Vérifiez si des NetworkPolicies bloquent le trafic. Listez les politiques dans l'espace de noms :
kubectl get networkpolicies -n default
Pour un pod spécifique, vérifiez quelles politiques s'appliquent :
kubectl describe networkpolicy -n default <nom-de-la-politique>
Vérifiez également si le plugin CNI applique les politiques réseau (par exemple, Calico utilise calicoctl pour le dépannage). Pour Calico :
calicoctl get networkpolicy -n default
6. Journaux et audit
Activez la journalisation d'audit du serveur API pour capturer les décisions d'autorisation. Dans le manifeste du serveur API, ajoutez la politique d'audit et le backend de journalisation. Ensuite, vérifiez les journaux pour les entrées interdites ou non autorisées :
grep -i forbidden /var/log/kubernetes/audit.log | tail -5
Si vous utilisez kubeadm, les journaux d'audit peuvent se trouver dans /var/log/kubernetes/audit/.
Modes de défaillance et récupération
Modes de défaillance courants et leurs étapes de récupération :
1. Permissions RBAC manquantes
Symptôme : les appels API renvoient 403 Forbidden malgré une connectivité réseau correcte.
Diagnostic :
kubectl auth can-i --list --as=system:serviceaccount:default:my-app -n default
Récupération : appliquez le Role ou ClusterRole manquant avec les règles appropriées. Documentez les modifications dans un fichier YAML sous contrôle de version.
2. Échec de résolution DNS
Symptôme : les pods ne peuvent pas résoudre les noms de service internes (nslookup renvoie "server can't find ..." ou expire).
Diagnostic : vérifiez l'état et les journaux des pods CoreDNS :
kubectl logs -n kube-system -l k8s-app=kube-dns --tail=50
# Recherchez des erreurs comme "plugin/errors: 2 ... SERVFAIL"
Testez également le DNS depuis un pod en utilisant directement l'IP du cluster :
kubectl run -it --rm dnsutils --image=infoblox/dnstools:latest -- nslookup kubernetes.default 10.96.0.10
Récupération : si CoreDNS est en panne, redémarrez le déploiement. Si la configuration est corrompue, restaurez à partir d'une sauvegarde. Vérifiez la ConfigMap CoreDNS :
kubectl get configmap coredns -n kube-system -o yaml
3. Blocage par une politique réseau
Symptôme : le pod A ne peut pas atteindre le pod B ou un service, même si le DNS résout et que les endpoints existent.
Diagnostic : décrivez les politiques réseau dans l'espace de noms et vérifiez les sélecteurs correspondants qui peuvent s'appliquer involontairement.
Récupération : supprimez temporairement ou modifiez la politique réseau pour autoriser le trafic, après avoir confirmé que la politique est la cause. Par exemple :
kubectl delete networkpolicy deny-all -n default
Si la suppression rétablit la connectivité, recréez la politique avec des règles correctes.
4. Mauvaise configuration du point de terminaison du serveur API
Symptôme : les commandes kubectl se bloquent ou renvoient "connection refused" depuis les nœuds ou les pods.
Diagnostic : vérifiez le service et les endpoints du serveur API :
kubectl get svc kubernetes -n default
kubectl get endpoints kubernetes -n default
Récupération : assurez-vous que le pod du serveur API fonctionne et que le sélecteur de service correspond. Si l'IP de l'endpoint est incorrecte, redémarrez kube-apiserver.
5. Pare-feu qui abandonne le trafic
Symptôme : les ports sont ouverts localement mais les connexions expirent entre les nœuds.
Diagnostic : utilisez telnet ou nc d'un nœud à un autre sur les ports requis (par exemple, 6443 pour le serveur API, 10250 pour le kubelet, 8472 pour Flannel VXLAN).
Récupération : ajoutez des règles de pare-feu pour autoriser les ports nécessaires en fonction de votre CNI et des exigences Kubernetes. Documentez les modifications dans l'infrastructure en tant que code.
Pièges courants et comment les éviter
Voici les erreurs courantes commises lors du dépannage du réseau des autorisations Kubernetes, avec les raisons et comment les éviter ou s'en remettre.
Une erreur 401 Unauthorized est souvent interprétée à tort comme un problème RBAC, mais cela signifie en réalité que l'authentification a échoué (par exemple, jeton expiré, certificat invalide). Utilisez kubectl auth can-i pour tester l'autorisation seulement après avoir confirmé que l'authentification fonctionne. Consultez les journaux du serveur API pour les erreurs d'authentification.
- Ignorer la distinction entre authentification et autorisation
Exécuter kubectl auth can-i en tant qu'administrateur du cluster renvoie toujours oui et masque le vrai problème. Utilisez toujours --as ou --as-group pour usurper l'utilisateur ou le compte de service réel. Par exemple, kubectl auth can-i list pods --as=system:serviceaccount:default:my-app.
- Tester depuis le mauvais contexte
De nombreuses vérifications d'autorisation impliquent des comptes de service qui doivent résoudre les noms de service. Si CoreDNS échoue, l'authentification et l'autorisation peuvent sembler cassées car le serveur API ne peut pas valider les jetons ou le client ne peut pas l'atteindre. Testez toujours le DNS tôt dans le processus de dépannage.
- Négliger le DNS comme dépendance
Certains plugins CNI nécessitent l'activation explicite de l'application des politiques réseau. Si les politiques sont définies mais non appliquées, elles ne causeront pas de problèmes ; inversement, si vous pensez qu'elles ne sont pas appliquées mais qu'elles le sont, le trafic peut être bloqué de manière inattendue. Vérifiez le support des politiques réseau de votre plugin CNI et consultez ses journaux.
- Supposer que les politiques réseau ne sont pas activées
Dans la panique, supprimer des politiques réseau ou modifier des règles RBAC globalement peut causer plus de dégâts. Testez toujours les changements dans un environnement de préproduction, utilisez kubectl diff pour prévisualiser et sauvegardez les configurations actuelles avant d'appliquer.
- Faire des changements larges et irréversibles
Les journaux d'audit fournissent la raison exacte des décisions d'autorisation. Sans eux, vous risquez de deviner faux. Activez la journalisation d'audit si ce n'est pas déjà fait et examinez les journaux pour la requête spécifique qui a échoué.
- Ne pas vérifier les journaux d'audit du serveur API
Le kubelet a son propre mode d'autorisation (par exemple, AlwaysAllow, Webhook). Si le serveur API utilise RBAC mais que le kubelet utilise AlwaysAllow, il peut accepter des requêtes non autorisées. Vérifiez la configuration du kubelet avec ps aux | grep kubelet ou systemctl status kubelet pour les drapeaux.
- Ignorer le mode d'autorisation du kubelet
Le trafic pod-à-pod, pod-vers-service et externe-vers-service peut emprunter différents chemins réseau (par exemple, iptables, IPVS, eBPF). Un problème de connectivité peut n'affecter qu'un seul chemin. Testez chaque chemin séparément pour isoler le problème.
- Supposer que tout le trafic utilise le même chemin réseau
Liste de vérification des opérations
Utilisez cette liste de vérification lors du dépannage du réseau des autorisations Kubernetes. Chaque élément comprend une commande ou une action concrète, et nous recommandons d'attribuer un propriétaire et une fréquence de révision pour les problèmes récurrents.
- [ ] Confirmer les versions de Kubernetes et du CNI (
kubectl version, journaux des pods CNI). Propriétaire : ingénieur plateforme (ex. Priya Shah). Révision : avant chaque session de dépannage. - [ ] Vérifier l'accessibilité du serveur API (
nc -zv <api-server-ip> 6443). Propriétaire : administrateur réseau. Révision : selon les besoins. - [ ] Tester la résolution DNS depuis un pod (
nslookup kubernetes.default). Propriétaire : développeur de garde. Révision : lors des problèmes de connectivité des pods. - [ ] Vérifier les pods et journaux CoreDNS (
kubectl logs -n kube-system -l k8s-app=kube-dns). Propriétaire : opérateur de cluster. Révision : lorsque le DNS échoue. - [ ] Vérifier que les endpoints des services ne sont pas vides (
kubectl get endpoints <svc>). Propriétaire : propriétaire de l'application. Révision : lorsque le routage des services est suspect. - [ ] Tester l'autorisation en tant qu'utilisateur affecté (
kubectl auth can-i --as=...). Propriétaire : ingénieur sécurité. Révision : lorsque l'accès est refusé. - [ ] Lister et inspecter les NetworkPolicies dans l'espace de noms (
kubectl get networkpolicies). Propriétaire : administrateur réseau. Révision : lorsque le trafic est bloqué. - [ ] Examiner les journaux d'audit du serveur API pour les requêtes interdites. Propriétaire : ingénieur sécurité. Révision : mensuellement ou après des incidents.
- [ ] Vérifier les règles de pare-feu des nœuds pour les ports requis (6443, 10250, ports CNI). Propriétaire : ingénieur infrastructure. Révision : trimestriellement ou après des changements réseau.
- [ ] Documenter les conclusions et toute modification de configuration effectuée. Propriétaire : commandant d'incident. Révision : après chaque incident.
Répétez ces étapes de manière structurée, en passant de la connectivité réseau aux décisions d'autorisation. Conservez un journal des commandes exécutées et de leurs sorties pour l'examen post-incident.
Conclusion
Les problèmes de réseau liés aux autorisations Kubernetes peuvent être complexes, mais une approche systématique permet d'isoler rapidement la cause première. Commencez par inventorier votre environnement, puis vérifiez la connectivité, le DNS, le routage des services et les décisions d'autorisation dans l'ordre. Utilisez des modifications de configuration sûres et limitées et testez toujours d'abord dans un environnement hors production. Les étapes de diagnostic et de récupération fournies ici vous donnent des commandes concrètes et des sorties attendues pour résoudre les problèmes courants. En suivant la liste de vérification des opérations, en évitant les pièges courants et en attribuant une propriété claire, vous pouvez réduire les temps d'arrêt et prévenir les récidives. Continuez à construire sur cette base en activant la journalisation d'audit et en surveillant les politiques réseau pour détecter les problèmes avant qu'ils n'affectent les utilisateurs.