Dépannage des Role Bindings Kubernetes : guide pratique avec exemples

Introduction

Quand un développeur signale Error from server (Forbidden): pods is forbidden: User "system:serviceaccount:default:my-app" cannot list resource "pods" in API group "" in the namespace "my-namespace", le problème n'est souvent pas un déploiement manquant, mais un Role Binding Kubernetes défaillant. Le contrôle d'accès basé sur les rôles (RBAC, Role-Based Access Control) de Kubernetes détermine qui peut effectuer quelles actions sur quelles ressources. Un Role Binding relie un utilisateur, un groupe ou un compte de service (ServiceAccount) à un rôle (Role) dans un espace de noms (namespace) spécifique. Lorsque cette liaison est absente, mal configurée ou fait référence au mauvais sujet, les requêtes légitimes échouent avec des erreurs de permission.

Cet article propose une approche pratique, axée sur les commandes, pour le dépannage des Role Bindings Kubernetes. Il s'adresse aux développeurs, ingénieurs DevOps et équipes techniques de startups qui doivent diagnostiquer et corriger rapidement les problèmes RBAC sans compromettre la sécurité. Nous couvrirons l'inventaire des versions et de l'environnement, les chemins de configuration sûrs, la vérification et le diagnostic, les modes de défaillance et la récupération. Chaque section comprend des commandes kubectl concrètes, des exemples réalistes et les sorties attendues pour que vous puissiez suivre et résoudre les problèmes en toute sécurité.

Avant d'apporter toute modification, rappelez-vous les règles de sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, ne jamais mettre de secrets dans les commandes ou les manifestes, vérifier le résultat et documenter comment récupérer si l'état attendu n'est pas atteint.

Inventaire des versions et de l'environnement

Avant de dépanner un Role Binding, vous devez connaître votre version de Kubernetes, la distribution du plan de contrôle et la configuration de votre cluster. Le RBAC est stable depuis Kubernetes 1.8 et est activé par défaut. Certains services Kubernetes gérés, comme Amazon EKS, disposent de couches d'authentification supplémentaires (par exemple, l'intégration AWS IAM) qui affectent la manière dont les utilisateurs sont mappés aux identités Kubernetes. Connaître votre environnement vous évite de chercher au mauvais endroit.

Commencez par des observations en lecture seule pour capturer l'état actuel. Exécutez ces commandes :

kubectl version --short
kubectl cluster-info
kubectl get nodes -o wide

Par exemple, si kubectl version --short affiche Server Version: v1.26.5, vous pouvez supposer que RBAC est disponible. Si vous êtes sur une plateforme gérée comme GKE, vérifiez si l'autorisation héritée est désactivée. Vous pouvez vérifier indirectement les indicateurs du serveur d'API en examinant le pod kube-apiserver si vous y avez accès :

kubectl get pods -n kube-system | grep kube-apiserver
kubectl logs -n kube-system kube-apiserver-control-plane --tail=20 | grep -i authorization

Recherchez des indicateurs comme --authorization-mode=RBAC,Node. Si RBAC n'est pas listé, les Role Bindings peuvent ne pas être appliqués. Cependant, dans la plupart des clusters modernes, RBAC est activé par défaut.

Ensuite, identifiez la ressource exacte, l'espace de noms et le sujet impliqués dans la requête en échec. Demandez au développeur ou inspectez le message d'erreur. Par exemple :

Error from server (Forbidden): deployments.apps is forbidden: User "[email protected]" cannot create resource "deployments" in API group "apps" in the namespace "team-a"

De cela, nous savons :

• Utilisateur : [email protected]
• Verbe : create
• Ressource : deployments
• Groupe d'API : apps
• Espace de noms : team-a

Si l'erreur mentionne un ServiceAccount, notez son nom complet et son espace de noms. Par exemple, un pod fonctionnant avec le ServiceAccount default dans l'espace de noms team-a serait system:serviceaccount:team-a:default.

Vous devez également savoir quels rôles et Role Bindings existent déjà dans l'espace de noms. Exécutez :

kubectl get roles -n team-a
kubectl get rolebindings -n team-a
kubectl get clusterroles | grep -i team-a  # si portée cluster
kubectl get clusterrolebindings | grep -i team-a

Exemple de sortie pour un espace de noms avec une liaison manquante :

NAME                CREATED AT
read-pods          2024-01-15T10:00:00Z

NAME                ROLE                AGE
read-pods-binding   Role/read-pods      2d

Si le Role Binding existe mais que l'utilisateur n'est pas listé comme sujet, c'est votre indice. Nous examinerons cela dans la section suivante.

Comme vérification initiale sûre, utilisez kubectl auth can-i pour tester les permissions sans apporter de modifications :

kubectl auth can-i create deployments -n team-a --as [email protected]

Sortie attendue :

no

Si la sortie est yes, l'utilisateur a la permission et l'erreur peut provenir d'un contexte différent ou d'un autre espace de noms. Si no, passez à l'inspection des définitions du rôle et du Role Binding.

Chemin de configuration sûr

L'objectif de cette section est de réparer un Role Binding cassé avec le plus petit changement qui restaure l'accès prévu. Nous décrirons d'abord l'état final souhaité, puis inspecterons la configuration existante, puis appliquerons un manifeste corrigé.

Définir l'accès prévu

Supposons que l'exigence soit : « L'utilisateur [email protected] doit pouvoir lister et obtenir les pods dans l'espace de noms team-a ». Cela se traduit par un rôle avec les verbes get et list sur les ressources pods, et un Role Binding qui lie Jane à ce rôle.

Inspecter le rôle et le Role Binding actuels

Obtenez le YAML du rôle et du Role Binding existants :

kubectl get role read-pods -n team-a -o yaml
kubectl get rolebinding read-pods-binding -n team-a -o yaml

Exemple de sortie du rôle :

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: read-pods
  namespace: team-a
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "list"]

Exemple de sortie du Role Binding :

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: read-pods-binding
  namespace: team-a
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: read-pods
subjects:
- kind: User
  name: [email protected]
  apiGroup: rbac.authorization.k8s.io

Ici, le rôle est correct, mais le Role Binding n'inclut que [email protected], pas [email protected]. Cela explique l'erreur Forbidden pour Jane.

Réparer le Role Binding

Nous avons deux options : modifier la liaison existante pour ajouter Jane, ou créer une nouvelle liaison. La modification est souvent le plus petit changement, mais si plusieurs équipes partagent le même rôle, une liaison séparée peut être plus propre. Nous allons modifier celle existante.

D'abord, faites une sauvegarde de la liaison actuelle :

kubectl get rolebinding read-pods-binding -n team-a -o yaml > rolebinding-backup.yaml

Ensuite, modifiez directement la liaison :

kubectl edit rolebinding read-pods-binding -n team-a

Dans l'éditeur, ajoutez Jane sous subjects :

subjects:
- kind: User
  name: [email protected]
  apiGroup: rbac.authorization.k8s.io
- kind: User
  name: [email protected]
  apiGroup: rbac.authorization.k8s.io

Enregistrez et quittez. Alternativement, appliquez un fichier manifeste avec le contenu corrigé complet. Pour la traçabilité, vous pouvez préférer appliquer un fichier :

cat <<EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: read-pods-binding
  namespace: team-a
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: read-pods
subjects:
- kind: User
  name: [email protected]
  apiGroup: rbac.authorization.k8s.io
- kind: User
  name: [email protected]
  apiGroup: rbac.authorization.k8s.io
EOF

Sortie attendue :

rolebinding.rbac.authorization.k8s.io/read-pods-binding configured

Vérifier que le changement est localisé

Après l'application, vérifiez que la liaison liste maintenant les deux utilisateurs :

kubectl get rolebinding read-pods-binding -n team-a -o yaml | grep -A5 subjects

La sortie doit montrer Bob et Jane.

Vérifiez ensuite la permission de Jane :

kubectl auth can-i list pods -n team-a --as [email protected]

Attendu :

yes

Et vérifiez que Bob a toujours accès (test de régression) :

kubectl auth can-i list pods -n team-a --as [email protected]

Attendu :

yes

Si Jane obtient toujours no, vérifiez la chaîne utilisateur. Les noms d'utilisateur Kubernetes sont sensibles à la casse et doivent correspondre exactement à ce que le système d'authentification produit. Par exemple, si Jane se connecte via OIDC, l'utilisateur peut être l'e-mail complet ou une revendication sub. Utilisez kubectl auth whoami si disponible, ou consultez les journaux d'audit.

Vérification et diagnostic

Après avoir réparé le Role Binding, vous devez vérifier que le changement fonctionne dans la charge de travail réelle et pas seulement avec kubectl auth can-i. Cette section couvre les méthodes de vérification et comment diagnostiquer les problèmes restants.

Tester avec une requête réelle

Demandez à l'utilisateur de tenter l'opération originale. Si Jane essaie de lister les pods :

kubectl get pods -n team-a --as [email protected]

Elle devrait maintenant voir les pods. Si elle utilisait un outil ou une application, vérifiez les journaux de l'application pour l'erreur d'autorisation. L'erreur ne devrait plus apparaître.

Vérifier les journaux d'audit du serveur d'API

Si la permission est toujours refusée, les journaux d'audit peuvent vous dire exactement pourquoi. Les journaux d'audit Kubernetes enregistrent chaque requête API avec l'utilisateur, le verbe, la ressource et la décision. Si votre cluster a l'audit activé (courant dans les clusters gérés comme GKE, EKS avec CloudTrail, ou sur site avec une politique d'audit), recherchez la requête de l'utilisateur.

Par exemple, sur un cluster autogéré, les journaux d'audit sont écrits dans un fichier ou vers un webhook. Vous pouvez les inspecter avec grep :

grep '[email protected]' /var/log/kubernetes/audit.log | tail -5

Recherchez une ligne avec "decision":"forbid" et inspectez les champs "requestURI", "verb" et "resource". Cela aide à identifier si la requête touche un groupe d'API différent ou s'il y a un refus à l'échelle du cluster.

Utiliser kubectl auth reconcile

Si vous gérez le RBAC via des manifestes et souhaitez vous assurer que l'état en direct correspond à vos fichiers, utilisez kubectl auth reconcile. Cette commande met à jour les rôles et les liaisons pour correspondre aux fichiers d'entrée, en ajoutant les sujets et règles manquants sans rien supprimer qui ne soit pas dans le fichier.

kubectl auth reconcile -f rolebinding.yaml

Sortie attendue :

rolebinding.rbac.authorization.k8s.io/read-pods-binding reconciled

C'est plus sûr que kubectl apply pour le RBAC car cela ne supprime pas les permissions qui auraient pu être ajoutées manuellement ou par d'autres contrôleurs.

Diagnostiquer les erreurs de configuration courantes

De nombreux problèmes de Role Binding proviennent d'erreurs subtiles. Voici les plus courantes et comment les détecter :

1. Mauvais type de sujet : Si vous avez l'intention d'accorder l'accès à un ServiceAccount mais utilisez kind: User avec le nom du ServiceAccount, la liaison ne fonctionnera pas. Les ServiceAccounts doivent être référencés comme kind: ServiceAccount. Vérifiez les sujets de la liaison.

   kubectl get rolebinding my-binding -o yaml | grep -A5 subjects

Pour un ServiceAccount, le sujet doit ressembler à :

   - kind: ServiceAccount
     name: my-app
     namespace: team-a

L'espace de noms est facultatif si le ServiceAccount est dans le même espace de noms que la liaison, mais c'est une bonne pratique de le spécifier.

1. Mauvais type de rôle : Un RoleBinding ne peut référencer qu'un rôle dans le même espace de noms. Si vous avez besoin de permissions à l'échelle du cluster, vous devez utiliser un ClusterRoleBinding ou référencer un ClusterRole dans un RoleBinding (pour accorder un accès limité à un espace de noms à un rôle de cluster). Si vous voyez une erreur comme « role.rbac.authorization.k8s.io "my-cluster-role" not found », c'est peut-être parce que vous avez utilisé un RoleBinding mais que le rôle est un ClusterRole. Vérifiez avec kubectl get clusterrole my-cluster-role.

1. Incohérence de groupe d'API : Les ressources du groupe principal (comme les pods, les services) ont un groupe d'API vide. Dans une règle de rôle, vous devez spécifier apiGroups: [""] pour les ressources principales. Pour les ressources apps, utilisez apiGroups: ["apps"]. Une erreur courante est d'omettre apiGroups ou d'utiliser ["*"] incorrectement. Vérifiez les règles de votre rôle par rapport au groupe d'API de la ressource en utilisant kubectl api-resources.

   kubectl api-resources --namespaced=true | grep deployments

La sortie montre que deployments est dans le groupe apps.

1. Incohérence de nom de sujet pour les groupes : Si vous liez à un groupe, le nom du groupe doit correspondre exactement à ce que le fournisseur d'authentification renvoie. Utilisez kubectl auth can-i --as-group pour tester l'appartenance à un groupe.

   kubectl auth can-i list pods -n team-a --as-group developers

Si no, le groupe peut être nommé différemment (par exemple, devs contre developers).

Modes de défaillance et récupération

Même avec des changements prudents, les choses peuvent mal tourner. Cette section couvre les modes de défaillance courants lors du dépannage d'un Role Binding et comment récupérer en toute sécurité.

Mode de défaillance 1 : Vous avez supprimé trop de permissions

Scénario : En modifiant un RoleBinding, vous supprimez accidentellement un sujet qui était nécessaire, provoquant l'échec d'une autre application.

Détection : Les pods de l'application commencent à journaliser des erreurs Forbidden, ou un déploiement échoue avec FailedCreate en raison de permissions insuffisantes.

Récupération : Restaurez le RoleBinding à partir de la sauvegarde que vous avez faite avant la modification.

kubectl apply -f rolebinding-backup.yaml

Vérifiez que le sujet est de retour :

kubectl get rolebinding read-pods-binding -o yaml | grep -A5 subjects

Puis réappliquez le changement prévu avec soin, en utilisant peut-être kubectl auth reconcile au lieu de edit pour éviter les suppressions accidentelles.

Mode de défaillance 2 : Vous avez appliqué un RoleBinding au mauvais espace de noms

Scénario : Vous avez créé un RoleBinding dans l'espace de noms default au lieu de team-a.

Détection : L'utilisateur obtient toujours Forbidden même si kubectl auth can-i -n team-a --as jane dit yes ? En fait, kubectl auth can-i dirait no si la liaison est dans le mauvais espace de noms, car la vérification est limitée à l'espace de noms. Mais parfois la confusion surgit lorsque l'utilisateur est dans un contexte différent.

Récupération : Supprimez la liaison incorrecte et créez-la dans le bon espace de noms.

kubectl delete rolebinding read-pods-binding -n default
kubectl create rolebinding read-pods-binding --role=read-pods [email protected] -n team-a

Vérifiez avec kubectl auth can-i -n team-a.

Mode de défaillance 3 : Le RoleBinding référence un rôle ou un ServiceAccount inexistant

Scénario : Le RoleBinding a été créé, mais le rôle qu'il référence a été supprimé ou n'a jamais existé. Ou le ServiceAccount référencé dans le sujet n'existe pas.

Détection : La liaison est acceptée, mais les permissions ne sont pas accordées. kubectl describe rolebinding peut montrer un événement ou un statut ? En fait, les RoleBindings n'ont pas de statut. Vous détecteriez cela en vérifiant que le rôle existe :

kubectl get role read-pods -n team-a

Si NotFound, créez d'abord le rôle. Pour les sujets ServiceAccount, vérifiez :

kubectl get serviceaccount my-app -n team-a

Si manquant, créez-le.

Récupération : Créez le rôle ou le ServiceAccount manquant, ou corrigez le RoleBinding pour référencer un existant.

Mode de défaillance 4 : Permission refusée en raison de l'agrégation de ClusterRoleBinding

Scénario : Vous utilisez des ClusterRoles agrégés, où un ClusterRole a une aggregationRule qui combine d'autres ClusterRoles en fonction d'étiquettes. Si les étiquettes sont erronées, les permissions agrégées sont incomplètes.

Détection : kubectl auth can-i --list pour l'utilisateur montre des permissions manquantes, et kubectl get clusterrole <aggregated-role> -o yaml montre une section rules vide.

Récupération : Vérifiez les étiquettes sur les ClusterRoles sources et assurez-vous qu'elles correspondent aux aggregationRule.clusterRoleSelectors. Corrigez les étiquettes si nécessaire.

Principes généraux de récupération

• Gardez toujours une sauvegarde de tout objet RBAC avant de le modifier.
• Préférez kubectl auth reconcile à kubectl apply lorsque vous souhaitez fusionner les changements sans supprimer les permissions existantes.
• Utilisez abondamment kubectl auth can-i pour tester avant et après.
• Documentez la matrice d'accès prévue et gardez-la sous contrôle de version. Utilisez des outils GitOps comme Flux ou ArgoCD pour gérer le RBAC de manière déclarative, ce qui fournit une piste d'audit et un retour en arrière facile.

Liste de contrôle des opérations

Utilisez cette liste pour vous assurer d'avoir couvert tous les aspects lors du dépannage d'un problème de Role Binding Kubernetes. Elle résume les étapes et les commandes des sections précédentes.

1. Identifier la requête en échec

• Obtenez le message d'erreur exact.
• Notez l'utilisateur/serviceaccount, le verbe, la ressource, le groupe d'API et l'espace de noms.
• Exemple : kubectl get pods -n team-a --as jane renvoie Forbidden.

1. Inventorier l'environnement

• Vérifiez la version de Kubernetes : kubectl version --short
• Confirmez que RBAC est activé : vérifiez les indicateurs kube-apiserver ou la documentation du cluster.
• Listez les rôles et Role Bindings existants dans l'espace de noms : kubectl get roles,rolebindings -n team-a

1. Tester la permission avec kubectl auth can-i

• kubectl auth can-i <verb> <resource> -n <namespace> --as <user>
• Si yes, le problème peut être le contexte ou le côté client ; si no, inspectez le RBAC.

1. Inspecter le YAML du rôle et du Role Binding

• kubectl get role <role> -n <namespace> -o yaml
• kubectl get rolebinding <binding> -n <namespace> -o yaml
• Vérifiez que roleRef référence le bon rôle/ClusterRole.
• Vérifiez que subjects inclut le bon utilisateur, groupe ou ServiceAccount avec le bon kind et name.

1. Vérifier les erreurs courantes

• Incohérence de groupe d'API (principal vs apps).
• Confusion de type de sujet (User vs ServiceAccount).
• Utilisation de Role vs ClusterRole.
• Portée de l'espace de noms.

1. Apporter la plus petite correction

• Sauvegardez l'objet : kubectl get rolebinding <name> -o yaml > backup.yaml
• Modifiez ou appliquez un manifeste corrigé.
• Préférez kubectl auth reconcile -f corrected.yaml pour éviter les suppressions involontaires.

1. Vérifier la correction

• Utilisez à nouveau kubectl auth can-i avec l'utilisateur.
• Demandez à l'utilisateur de tester l'opération réelle.
• Vérifiez les journaux d'application pour qu'il n'y ait plus d'erreurs Forbidden.

1. Documenter et automatiser

• Stockez les manifestes RBAC sous contrôle de version.
• Utilisez CI/CD ou GitOps pour appliquer les changements avec revue.
• Mettez en place une alerte pour les erreurs Forbidden à taux élevé si possible (par exemple, via la surveillance des journaux d'audit).

Conclusion

Le dépannage des Role Bindings Kubernetes devient simple lorsque vous l'abordez méthodiquement : identifiez l'échec de permission exact, inspectez les objets RBAC existants, apportez un changement minimal et réversible, et vérifiez avec kubectl auth can-i et des requêtes réelles. Inventoriez toujours votre environnement d'abord, car les clusters gérés et les intégrations d'authentification personnalisées peuvent introduire des couches supplémentaires. Utilisez des pratiques sûres comme la sauvegarde des manifestes et l'utilisation de kubectl auth reconcile pour éviter les dommages collatéraux.

Les exemples de ce guide ont couvert les scénarios les plus courants : sujets manquants, mauvais types de sujets, incohérences de groupes d'API et confusion d'espaces de noms. En appliquant la liste de contrôle des opérations, vous pouvez résoudre rapidement les problèmes de permission et éviter qu'ils ne se reproduisent grâce à un RBAC sous contrôle de version et à des flux de travail GitOps.

Comme prochaine étape, choisissez une vérification à faible risque de cet article—par exemple, exécuter kubectl auth can-i list pods -n team-a --as <votre-utilisateur>—et enregistrez l'état actuel avant d'apporter tout changement. Ensuite, corrigez les lacunes de permission et confirmez la sortie attendue. Rappelez-vous : un flux de travail fiable rend les échecs visibles, protège les valeurs sensibles, limite les changements à la ressource prévue et définit la vérification de récupération avant qu'un incident ne force la décision.