Liaison de rôle Kubernetes : erreurs courantes, correctifs et exemples pratiques

Introduction

La liaison de rôle (Role Binding) Kubernetes est un élément central du système de contrôle d'accès basé sur les rôles (RBAC). Elle relie un rôle, qui définit un ensemble de permissions comme « obtenir des pods » ou « créer des déploiements », à un sujet tel qu'un utilisateur, un groupe ou un compte de service. Cette liaison ne fonctionne que dans un seul espace de noms. Lorsque le rôle ou la liaison est mal configuré, les utilisateurs peuvent voir des erreurs « Forbidden » déroutantes, les applications peuvent ne pas accéder à l'API, ou la sécurité peut être affaiblie par des permissions trop larges. Ce guide passe en revue les messages d'erreur de liaison de rôle les plus courants, montre comment les diagnostiquer avec kubectl, et fournit des correctifs étape par étape avec des exemples YAML pratiques. Vous apprendrez à vérifier l'accès avec kubectl auth can-i, à appliquer les principes du moindre privilège en toute sécurité, et à garder la configuration RBAC de votre cluster propre au fil du temps.

Inventaire de la version et de l'environnement

Avant de modifier toute liaison de rôle, confirmez l'environnement de votre cluster. Exécutez la commande suivante pour vérifier les versions du client et du serveur :

kubectl version --short

La sortie attendue ressemble à :

Client Version: v1.27.3
Server Version: v1.27.3

Le RBAC est stable dans Kubernetes 1.8 et versions ultérieures, mais pour les exemples de ce guide, supposez Kubernetes 1.19 ou plus récent. Le RBAC est activé par défaut dans la plupart des distributions, mais vous pouvez le vérifier en contrôlant les drapeaux du serveur d'API. Si vous avez accès au plan de contrôle, cherchez --authorization-mode=RBAC dans le manifeste du kube-apiserver. Sur les clusters gérés comme GKE, EKS ou AKS, le RBAC est toujours actif.

Vous devez disposer des permissions cluster-admin ou équivalentes pour créer ou modifier des objets Role et RoleBinding. Si vous n'êtes pas sûr, exécutez :

kubectl auth can-i create rolebindings --all-namespaces

Si la sortie est no, demandez l'accès à votre administrateur de cluster.

Identifiez l'espace de noms cible pour votre Role et votre RoleBinding. Listez tous les espaces de noms avec :

kubectl get namespaces

Puis listez les RoleBindings existants dans un espace de noms, par exemple development :

kubectl get rolebindings -n development

Exemple de sortie :

NAME          ROLE               AGE
read-pods     Role/pod-reader    3d2h

Cette étape d'inventaire vous évite de modifier le mauvais objet ou le mauvais espace de noms. Travaillez toujours dans un espace de noms spécifique lorsque vous traitez des RoleBindings, jamais à l'échelle du cluster.

Chemin de configuration sûr

Les modifications de liaison de rôle doivent toujours suivre une approche limitée et fondée sur le moindre privilège. Le processus ci-dessous crée un rôle minimal, le lie à un utilisateur, et vérifie le résultat. Cela peut être fait dans un espace de noms de développement avant de déployer en production.

Étape 1 : Créer un rôle minimal

Un rôle définit les permissions pour les ressources d'un espace de noms. Par exemple, pour autoriser un utilisateur à lister les pods dans l'espace de noms development, créez un fichier nommé pod-reader-role.yaml :

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: development
  name: pod-reader
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "list", "watch"]

Appliquez-le :

kubectl apply -f pod-reader-role.yaml

Vérifiez qu'il a été créé :

kubectl get role pod-reader -n development -o yaml

Étape 2 : Lier le rôle à un sujet

Ensuite, créez un RoleBinding qui accorde le rôle pod-reader à un utilisateur humain nommé jane. Enregistrez le contenu suivant sous read-pods-binding.yaml :

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: read-pods
  namespace: development
subjects:
- kind: User
  name: jane
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

Appliquez et vérifiez :

kubectl apply -f read-pods-binding.yaml
kubectl get rolebinding read-pods -n development -o yaml

La sortie doit montrer le sujet jane et le roleRef pod-reader. Si le sujet est un compte de service, utilisez kind: ServiceAccount et spécifiez l'espace de noms dans le sujet :

subjects:
- kind: ServiceAccount
  name: my-app-sa
  namespace: development

Étape 3 : Tester avec le moindre privilège

N'accordez jamais plus de permissions que nécessaire. Dans l'exemple ci-dessus, jane ne peut que obtenir, lister et surveiller les pods dans l'espace de noms development. Elle ne peut pas créer ou supprimer des pods, et elle n'a accès à aucune autre ressource ni à aucun autre espace de noms. Avant d'appliquer en production, testez dans un espace de noms non productif et confirmez que l'accès est correct.

Vérification et diagnostic

Après avoir créé le Role et le RoleBinding, vérifiez que l'utilisateur dispose des permissions attendues. La commande kubectl auth can-i est le moyen le plus direct de tester l'accès pour un sujet.

Pour vérifier si jane peut lister les pods dans development :

kubectl auth can-i list pods --as jane -n development

Sortie attendue :

yes

Si la sortie est no, vous devez diagnostiquer. Commencez par décrire le RoleBinding :

kubectl describe rolebinding read-pods -n development

Exemple de sortie :

Name:         read-pods
Namespace:    development
Labels:       <none>
Annotations:  <none>
Role:
  Kind:  Role
  Name:  pod-reader
Subjects:
  Kind  Name  Namespace
  ----  ----  ---------
  User  jane

Vérifiez que le sujet jane est correct et que le roleRef pointe vers pod-reader. Les erreurs courantes incluent une faute de frappe dans le nom d'utilisateur, le mauvais type (User au lieu de ServiceAccount), ou un mauvais nom de rôle.

Ensuite, inspectez le Role :

kubectl describe role pod-reader -n development

Confirmez que les verbes et ressources correspondent à votre intention. Par exemple, le Role doit inclure pods sous resources et get, list et watch sous verbs.

Vous pouvez également tester un verbe spécifique, comme create :

kubectl auth can-i create pods --as jane -n development

Sortie attendue :

no

Cela confirme que la configuration du moindre privilège fonctionne comme prévu.

Pour les comptes de service, utilisez --as=system:serviceaccount:development:my-app-sa :

kubectl auth can-i list pods --as=system:serviceaccount:development:my-app-sa -n development

Si vous voyez toujours no, vérifiez les événements Kubernetes dans l'espace de noms :

kubectl get events -n development

Cherchez des messages comme Forbidden ou RBAC denied. Vous pouvez également examiner les journaux d'audit du serveur d'API s'ils sont activés, car ils enregistrent chaque décision d'autorisation.

Modes de défaillance et récupération

Les erreurs de configuration des liaisons de rôle aboutissent généralement à l'un de ces modes de défaillance. Comprendre chacun vous aide à récupérer rapidement.

Erreurs Forbidden

Lorsqu'un utilisateur tente une action qu'il n'est pas autorisé à effectuer, le serveur d'API renvoie une erreur 403 Forbidden. Par exemple :

Error from server (Forbidden): pods is forbidden: User "jane" cannot list resource "pods" in API group "" in the namespace "development"

Cela indique que la liaison n'accorde pas la permission requise ou que le Role ne contient pas le verbe nécessaire. Pour corriger, comparez l'action demandée avec les règles du Role. Si jane doit supprimer des pods, ajoutez delete aux verbes du Role :

verbs: ["get", "list", "watch", "delete"]

Appliquez la modification et vérifiez :

kubectl apply -f pod-reader-role.yaml
kubectl auth can-i delete pods --as jane -n development

Sujet introuvable

Si le sujet n'existe pas, la liaison est inefficace. Pour un type User, Kubernetes ne valide pas l'existence de l'utilisateur car les utilisateurs sont gérés en externe (par exemple, via des certificats x509, OpenID Connect ou des fichiers de jetons statiques). La commande kubectl get users n'existe pas par défaut. Vous devez vous assurer que le nom d'utilisateur correspond exactement. Par exemple, si le CN du certificat de l'utilisateur est [email protected], la liaison doit utiliser cette chaîne exacte.

Pour les sujets ServiceAccount, le compte de service doit exister dans le même espace de noms que le RoleBinding. Vérifiez :

kubectl get serviceaccount my-app-sa -n development

S'il n'existe pas, créez-le :

kubectl create serviceaccount my-app-sa -n development

Non-correspondance d'espace de noms

Les RoleBindings sont limités à un espace de noms. Si vous référencez un Role d'un autre espace de noms, la liaison ne fonctionnera pas. Par exemple, si le Role pod-reader est dans production mais que le RoleBinding est dans development, l'utilisateur n'obtiendra pas l'accès. Assurez-vous toujours que le Role et le RoleBinding sont dans le même espace de noms. Listez les Roles dans un espace de noms pour confirmer :

kubectl get roles -n development

Confusion avec les ressources à l'échelle du cluster

Si vous devez accorder l'accès à des ressources à l'échelle du cluster comme les nœuds, les volumes persistants ou les espaces de noms, un RoleBinding ne fonctionnera pas car les Roles ne peuvent pas accorder de permissions sur des ressources à l'échelle du cluster. Vous devez utiliser un ClusterRole et un ClusterRoleBinding. Par exemple, pour permettre à jane de lister les nœuds (une ressource à l'échelle du cluster), créez un ClusterRole et un ClusterRoleBinding :

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: node-reader
rules:
- apiGroups: [""]
  resources: ["nodes"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: read-nodes
subjects:
- kind: User
  name: jane
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: node-reader
  apiGroup: rbac.authorization.k8s.io

Étapes de récupération

Lorsqu'une modification casse l'accès, revenez en arrière immédiatement. Supprimez la liaison erronée :

kubectl delete rolebinding read-pods -n development

Puis réappliquez le YAML corrigé. Vérifiez toujours après la réapplication avec kubectl auth can-i. Si vous vous enfermez accidentellement hors d'un espace de noms, utilisez un compte cluster-admin pour examiner et corriger les liaisons. Kubernetes dispose d'un ClusterRoleBinding cluster-admin intégré qui accorde un accès complet au cluster ; si vous y avez accès, vous pouvez toujours récupérer.

Conservez les configurations RBAC fonctionnelles dans un système de contrôle de version. Cela vous permet de restaurer rapidement un état connu et fonctionnel. Dans un dépôt Git, stockez les fichiers YAML pour chaque Role et RoleBinding, et utilisez un pipeline CI/CD pour appliquer les modifications après examen.

Pièges courants et comment les éviter

Même les administrateurs Kubernetes expérimentés commettent des erreurs avec les liaisons de rôle. Cette section couvre les pièges les plus fréquents, pourquoi ils surviennent et comment les prévenir ou s'en remettre.

Permissions trop larges

De nombreuses équipes accordent les verbes ou les ressources par commodité. Par exemple :

rules:
- apiGroups: ["*"]
  resources: ["*"]
  verbs: ["*"]

Cela accorde au sujet un accès complet à toutes les ressources de l'espace de noms, violant le moindre privilège. Si un attaquant compromet un compte de service avec un tel Role, il peut causer des dégâts importants. Pour éviter cela, commencez par des permissions spécifiques et n'ajoutez que ce qui est nécessaire. Utilisez kubectl auth can-i --list pour voir toutes les permissions d'un sujet et révisez régulièrement.

Utiliser un RoleBinding pour un accès à l'échelle du cluster

Comme mentionné précédemment, les RoleBindings ne peuvent pas accorder de permissions à l'échelle du cluster. Une erreur courante est d'essayer d'accorder l'accès aux nœuds ou aux volumes persistants en utilisant un Role. Cela ne fonctionnera pas et peut produire des erreurs déroutantes. Utilisez toujours un ClusterRoleBinding pour les ressources à l'échelle du cluster.

Ignorer les groupes d'API

Le champ apiGroups est souvent négligé. Pour les ressources de base comme les pods, les services et les configmaps, le groupe d'API est vide (""). Pour d'autres ressources comme les déploiements, le groupe d'API est apps, et pour les ingresses, c'est networking.k8s.io. Si vous définissez le mauvais groupe d'API, les permissions ne s'appliqueront pas. Par exemple, pour permettre la gestion des déploiements, le Role doit inclure :

rules:
- apiGroups: ["apps"]
  resources: ["deployments"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]

Vérifiez le bon groupe d'API avec :

kubectl api-resources | grep deployment

Sortie :

deployments    apps/v1    true    Deployment

Oublier l'espace de noms dans le sujet

Pour les sujets de compte de service, vous devez spécifier l'espace de noms même s'il est le même que celui du RoleBinding. Si l'espace de noms est omis, la liaison ne fonctionnera pas. Incluez toujours namespace sous subjects pour les comptes de service.

Ne pas tester après les modifications

Après avoir modifié un Role ou un RoleBinding, certains administrateurs supposent que cela fonctionne et passent à autre chose. Plus tard, les utilisateurs signalent des problèmes d'accès. Testez toujours avec kubectl auth can-i du point de vue du sujet concerné. Pour un utilisateur nommé jane, exécutez :

kubectl auth can-i list pods --as jane -n development

Si le résultat est inattendu, révisez le YAML et corrigez avant de continuer.

Supprimer un Role mais pas le RoleBinding

Si vous supprimez un Role qui est référencé par un RoleBinding, la liaison reste mais pointe vers un Role inexistant. Les utilisateurs perdront soudainement l'accès sans erreur claire. Vérifiez toujours les RoleBindings orphelins après avoir supprimé un Role :

kubectl get rolebindings -n development

Si le Role d'un RoleBinding est manquant, la colonne ROLE dans kubectl get rolebindings affichera <none>. Supprimez la liaison orpheline ou créez un nouveau Role avec le même nom.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle pour maintenir un RBAC sain dans votre cluster. Attribuez un responsable unique pour chaque élément et révisez-les selon un calendrier défini.

Parcourez cette liste de contrôle après chaque changement RBAC et au moins trimestriellement. Automatisez ce que vous pouvez. Par exemple, utilisez un script pour lister tous les RoleBindings et signaler ceux avec des permissions génériques :

kubectl get rolebindings --all-namespaces -o json | jq '.items[] | {namespace: .metadata.namespace, name: .metadata.name, role: .roleRef.name}'

Envisagez des moteurs de politiques comme OPA Gatekeeper ou Kyverno pour appliquer automatiquement des garde-fous RBAC.

Conclusion

Les erreurs de liaison de rôle Kubernetes résultent généralement de petites erreurs de configuration : un nom de sujet erroné, un groupe d'API incorrect, une non-correspondance d'espace de noms, ou un verbe oublié. En comprenant comment les objets Role et RoleBinding fonctionnent ensemble, vous pouvez diagnostiquer et corriger ces problèmes rapidement. Utilisez kubectl auth can-i pour vérifier l'accès du point de vue de l'utilisateur, suivez les principes du moindre privilège, et conservez un enregistrement versionné de votre configuration RBAC. Avec les exemples pratiques et la liste de contrôle de ce guide, vous pouvez maintenir un cluster sécurisé et fonctionnel. Commencez par auditer un espace de noms aujourd'hui : listez ses RoleBindings, examinez les Roles et testez quelques permissions. Une hygiène RBAC cohérente préviendra la plupart des problèmes d'accès avant qu'ils n'affectent vos applications.