Dépannage de la multi-location Kubernetes : guide pratique

Introduction

La multi-location Kubernetes est un modèle puissant, mais elle introduit une classe spécifique de problèmes opérationnels : échecs d'isolation des locataires, contention de ressources due à un « voisin bruyant », mauvaises configurations RBAC (Role-Based Access Control) qui verrouillent les utilisateurs légitimes, et épuisement silencieux des quotas qui bloque les charges de travail sans signal clair. Dépanner ces problèmes exige plus que l'exécution de commandes génériques comme kubectl get pods. Vous avez besoin d'une approche systématique qui relie les symptômes observés à des preuves concrètes, des changements ciblés et une vérification de la récupération.

Ce guide s'adresse aux développeurs, consultants DevOps et équipes techniques de startups qui opèrent des clusters Kubernetes partagés. Il se concentre sur des commandes pratiques, prêtes à être copiées-collées, et des chemins de décision. Chaque section commence par une observation en lecture seule, passe au plus petit changement justifié, puis se termine par une commande de vérification qui confirme le résultat. Vous apprendrez à inspecter les espaces de noms (namespaces), les quotas de ressources, les règles RBAC et les échecs de contrôle d'admission ; comment diagnostiquer les défaillances multi-location les plus courantes ; et comment récupérer sans affecter les autres locataires.

L'objectif est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des valeurs fictives plutôt que des secrets, vérifier le résultat et documenter la procédure de récupération si l'état attendu n'est pas atteint.

Inventaire de la version et de l'environnement

Avant de toucher à quoi que ce soit, vous devez avoir une image précise du cluster, de la version du plan de contrôle et des composants qui implémentent la multi-location. Une incompatibilité entre les versions de l'API Kubernetes et vos fichiers manifestes est une cause fréquente de défaillances silencieuses.

Identifier la version du cluster et les ressources API :

kubectl version --short
kubectl api-resources | grep -E 'namespace|resourcequota|limitrange|role|rolebinding|networkpolicy'

La sortie attendue inclut la version du serveur, par exemple Server Version: v1.28.1, ainsi qu'une liste de ressources API. Si resourcequota ou networkpolicy est absent, votre cluster peut ne pas disposer des contrôleurs requis, ou vous utilisez une distribution gérée qui les expose différemment.

Vérifier les espaces de noms existants et leurs libellés (labels). La multi-location repose souvent sur les libellés des espaces de noms pour l'application des politiques. Un libellé manquant peut silencieusement exclure un locataire d'un quota ou d'une politique réseau.

kubectl get namespaces --show-labels

Exemple de sortie :

NAME              STATUS   AGE   LABELS
team-a            Active   21d   tenant=acme,environment=prod
team-b            Active   21d   tenant=globex,environment=prod
default           Active   90d   <none>

Si un espace de noms censé avoir tenant=acme n'a pas ce libellé, un ResourceQuota basé sur ce sélecteur ne s'appliquera pas. C'est une cause fréquente de problèmes tels que « quota non appliqué » ou « quota appliqué au mauvais espace de noms ».

Vérifier les fonctionnalités activées (feature gates) du serveur API pour la multi-location. Certaines fonctionnalités d'isolation avancées, comme la Pod Security Admission (PSA) ou les espaces de noms hiérarchiques, dépendent des feature gates. La PSA remplace la PodSecurityPolicy et est activée par défaut à partir de Kubernetes 1.25.

kubectl get --raw /metrics | grep apiserver_feature_enabled | grep -E 'PodSecurity|HierarchicalNamespace'

Cela renvoie des métriques telles que apiserver_feature_enabled{name="PodSecurity",stage="stable"} 1. Si la fonctionnalité n'est pas présente ou renvoie 0, la PSA n'est pas active et vous ne pouvez pas compter sur elle pour l'isolation des locataires.

Inventorier les contrôleurs d'admission. De nombreuses politiques multi-location sont appliquées par des webhooks d'admission (par exemple, OPA Gatekeeper, Kyverno, webhooks personnalisés). Un webhook mal configuré peut rejeter toutes les charges de travail des locataires.

kubectl get validatingwebhookconfigurations,mutatingwebhookconfigurations

Recherchez les webhooks avec failurePolicy: Fail. Si le service du webhook est indisponible, chaque requête correspondante échoue. Vous pouvez vérifier l'effet du webhook en le décrivant :

kubectl describe validatingwebhookconfiguration <nom-du-webhook>

La sortie montre les règles et le service. Si le service n'a pas de points de terminaison (endpoints), les requêtes expirent.

Gardez un test local minimal. Avant d'appliquer tout changement à un cluster partagé, reproduisez le problème dans un espace de noms de test dédié. Par exemple :

kubectl create namespace test-tenant-a
kubectl label namespace test-tenant-a tenant=acme
kubectl apply -f test-manifest.yaml -n test-tenant-a
kubectl get pods -n test-tenant-a -o wide

Inspectez les ressources générées et vérifiez le trafic avec kubectl port-forward ou un service ClusterIP avant de passer à un équilibreur de charge cloud ou à un contrôleur d'entrée (ingress).

Chemin de configuration sécurisé

Modifier la configuration dans un cluster multi-locataire peut déclencher des défaillances en cascade. Suivez un chemin qui minimise les risques : récupérer l'état actuel, le sauvegarder, effectuer un changement ciblé, puis vérifier.

Exemple : ajuster un ResourceQuota pour le locataire « acme ».

Étape 1 : Observer l'utilisation actuelle du quota.

kubectl get resourcequota -n team-a
kubectl describe resourcequota compute-quota -n team-a

Exemple de sortie :

Name:            compute-quota
Namespace:       team-a
Resource         Used   Hard
--------         ----   ----
requests.cpu     3      4
requests.memory  6Gi    8Gi
limits.cpu       5      6

Étape 2 : Exporter le quota actuel pour sauvegarde.

kubectl get resourcequota compute-quota -n team-a -o yaml > team-a-quota-backup.yaml

Étape 3 : Effectuer un changement ciblé. Supposons que vous deviez augmenter la limite CPU de 6 à 8 parce que le déploiement d'un locataire est limité (throttled). Modifiez le quota avec kubectl edit ou appliquez un manifeste modifié. Voici un correctif (patch) minimal :

kubectl patch resourcequota compute-quota -n team-a --type='json' -p='[{"op": "replace", "path": "/spec/hard/limits.cpu", "value": "8"}]'

Étape 4 : Vérifier que le changement a pris effet et que les pods existants ne sont pas expulsés.

kubectl get resourcequota compute-quota -n team-a -o yaml | grep limits.cpu
kubectl get pods -n team-a

Si vous voyez des pods en état Evicted ou Pending, l'augmentation du quota peut avoir déclenché une cascade de pods en attente qui dépassent maintenant les limites de mémoire. Revenez en arrière à l'aide de la sauvegarde :

kubectl apply -f team-a-quota-backup.yaml

Principes de changement sécurisé :

• Ne supprimez jamais un quota ou une plage de limites (LimitRange) sans d'abord exporter sa définition actuelle.
• Modifiez un champ à la fois. Si vous devez modifier plusieurs champs, appliquez-les dans des correctifs séparés et vérifiez après chacun.
• Utilisez kubectl diff -f new-manifest.yaml avant d'appliquer pour voir exactement ce qui va changer.
• Pour le contrôle d'accès basé sur les rôles (RBAC), testez les changements avec kubectl auth can-i --as system:serviceaccount:team-a:default pour simuler l'identité du locataire.

Exemple : accorder à un compte de service locataire un accès en lecture seule à son espace de noms.

D'abord, vérifiez les autorisations actuelles :

kubectl auth can-i list pods --as system:serviceaccount:team-a:default -n team-a

Si la sortie est no, créez un Role et un RoleBinding :

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: team-a
  name: pod-reader
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  namespace: team-a
  name: read-pods
subjects:
- kind: ServiceAccount
  name: default
  namespace: team-a
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

Appliquez et vérifiez :

kubectl apply -f rbac-readonly.yaml
kubectl auth can-i list pods --as system:serviceaccount:team-a:default -n team-a

Sortie attendue : yes.

Si la sortie reste no, vérifiez que le RoleBinding existe et que le nom du compte de service correspond exactement. Une erreur courante est une faute de frappe dans l'espace de noms ou le nom du compte de service.

Vérification et diagnostics

Une fois que vous soupçonnez un problème, vous devez collecter des preuves qui pointent vers la cause racine. Les commandes suivantes créent une piste de diagnostic pour les problèmes de multi-location.

Vérifier les échecs de planification (scheduling) des pods. La contention de ressources entre locataires est une cause fréquente.

kubectl get pods -n team-a -o wide
kubectl describe pod <nom-du-pod> -n team-a

Dans la section Events du describe, recherchez des messages comme :

Warning  FailedScheduling  2m (x5 over 10m)  default-scheduler  0/3 nodes are available: 3 Insufficient cpu, 2 Insufficient memory.

Si vous voyez Insufficient cpu ou Insufficient memory, les demandes de ressources du locataire dépassent ce que le cluster peut fournir compte tenu de l'utilisation des autres locataires. Vérifiez les ressources allouables des nœuds :

kubectl describe nodes | grep -A 5 'Allocated resources'

Cela montre le total des demandes et limites de ressources par nœud. Si les demandes CPU sont à 95 % de l'allouable, aucun nouveau pod locataire ne peut être planifié même si l'utilisation réelle est faible.

Examiner l'application des quotas. Si un pod est rejeté à l'admission, kubectl apply renvoie une erreur comme :

Error from server (Forbidden): error when creating "deployment.yaml": pods "web-7d9f8c" is forbidden: exceeded quota: compute-quota, requested: requests.cpu=2, used: requests.cpu=7, limited: requests.cpu=8

Cela vous indique exactement quel quota est épuisé. Vous pouvez vérifier l'utilisation actuelle avec kubectl describe resourcequota comme ci-dessus.

Inspecter les journaux de refus RBAC. Les journaux d'audit du serveur API Kubernetes enregistrent les requêtes interdites. Si vous avez accès au journal d'audit (souvent dans /var/log/kubernetes/audit.log sur les nœuds du plan de contrôle ou via un service géré), recherchez le compte de service du locataire :

grep 'system:serviceaccount:team-a:default' /var/log/kubernetes/audit.log | grep '"code":403'

La ligne de journal inclut le verbe, la ressource et l'espace de noms. Par exemple, un refus de create deployments dans l'espace de noms team-b indique que le compte de service tente d'agir en dehors de son espace de noms, ce qui constitue une violation de la limite d'isolation des locataires.

Tester l'application des politiques réseau. La multi-location utilise souvent des NetworkPolicies pour isoler les espaces de noms. Si un locataire signale qu'il ne peut pas atteindre un service dans un autre espace de noms, vérifiez les politiques :

kubectl get networkpolicies -A
kubectl describe networkpolicy deny-from-other-namespaces -n team-a

La sortie du describe montre les sélecteurs de pods et les règles d'entrée/sortie. Pour confirmer si une politique bloque le trafic, vous pouvez exécuter un test de connectivité depuis un pod :

kubectl run test-pod --rm -it --image=busybox -n team-b -- sh
# À l'intérieur du pod :
wget -qO- --timeout=2 http://service-in-team-a.team-a.svc.cluster.local

Si la connexion expire, et que la NetworkPolicy dans team-a refuse l'entrée depuis tous les espaces de noms sauf ceux avec un libellé spécifique, alors la politique fonctionne. Si la connexion réussit de manière inattendue, la politique peut être mal configurée ou non appliquée en raison d'un sélecteur de pod manquant.

Vérifier les échecs des webhooks d'admission. Si toutes les requêtes vers un espace de noms échouent soudainement avec un message comme :

Error from server (InternalError): Internal error occurred: failed calling webhook "validate.kyverno.svc"

Alors le service du webhook est injoignable. Vérifiez ses points de terminaison :

kubectl get endpoints -n kyverno

S'il n'y a pas de points de terminaison, les pods du webhook sont en panne. Redémarrez-les et vérifiez avant de réessayer la charge de travail du locataire. Pour débloquer temporairement un espace de noms, vous pouvez ajuster la failurePolicy du webhook à Ignore (non recommandé pour la sécurité en production) ou corriger le service sous-jacent.

Modes de défaillance et récupération

Comprendre les modes de défaillance courants de la multi-location vous prépare à récupérer rapidement et avec un impact minimal.

1. Épuisement du quota provoquant l'échec de création de pod

Symptôme : kubectl apply renvoie une erreur d'interdiction mentionnant exceeded quota.

Cause racine : L'utilisation des ressources du locataire a atteint la limite stricte du ResourceQuota de l'espace de noms.

Récupération :

• Identifiez le quota : kubectl describe resourcequota -n <namespace>.
• Déterminez si le locataire a légitimement besoin de plus de ressources ou s'il a des ressources orphelines consommant le quota (par exemple, des Jobs terminés, des pods expulsés, des PVC inutilisés).
• Nettoyez les ressources orphelines :

kubectl delete pods --field-selector=status.phase=Failed -n <namespace>
kubectl delete jobs --field-selector=status.successful=1 -n <namespace>

• Si une augmentation de quota est justifiée, suivez le Chemin de configuration sécurisé pour augmenter la limite par petits incréments et surveillez la capacité des nœuds.
• Vérifiez en essayant de créer un pod de test.

2. Mauvaise configuration RBAC verrouillant un locataire

Symptôme : Un développeur signale des erreurs forbidden lors de l'exécution de commandes kubectl dans son espace de noms, alors qu'elles fonctionnaient auparavant.

Cause racine : Un RoleBinding a été accidentellement supprimé ou modifié, ou une politique à l'échelle du cluster a changé.

Récupération :

• Vérifiez les autorisations actuelles du locataire :

kubectl auth can-i --list --as system:serviceaccount:team-a:default -n team-a

• Recherchez les verbes get, list, create manquants sur les ressources attendues.
• Comparez avec une piste d'audit ou un dépôt GitOps pour trouver ce qui a changé.
• Restaurez le Role et le RoleBinding corrects depuis le contrôle de version :

kubectl apply -f team-a-rbac.yaml

• Vérifiez avec kubectl auth can-i create deployments --as system:serviceaccount:team-a:default -n team-a qui doit renvoyer yes.

3. Voisin bruyant provoquant une dégradation des performances

Symptôme : L'application du locataire A répond lentement, et les pods sont limités (throttled) ou tués par manque de mémoire (OOMKilled).

Cause racine : Un autre locataire sur les mêmes nœuds consomme un excès de CPU ou de mémoire, laissant moins de ressources pour le locataire A. Cela se produit lorsque les demandes (requests) et limites (limits) ne sont pas définies, permettant à un locataire d'utiliser des ressources sans borne.

Récupération :

• Identifiez les pods consommant le plus de ressources à l'échelle du cluster :

kubectl top pods -A --sort-by=cpu
kubectl top pods -A --sort-by=memory

• Pour l'espace de noms fautif, vérifiez si les limites sont définies :

kubectl get pods -n team-b -o json | jq '.items[] | select(.spec.containers[].resources.limits == null) | .metadata.name'

• Si les limites sont manquantes, le locataire doit les ajouter. Comme mesure d'atténuation temporaire, vous pouvez définir un LimitRange pour appliquer des limites par défaut :

apiVersion: v1
kind: LimitRange
metadata:
  name: default-limits
  namespace: team-b
spec:
  limits:
  - default:
      cpu: "1"
      memory: "1Gi"
    defaultRequest:
      cpu: "0.5"
      memory: "512Mi"
    type: Container

Appliquez-le puis redémarrez les pods. Les pods existants ne sont pas mis à jour automatiquement, vous devrez peut-être les supprimer pour qu'ils adoptent les nouvelles valeurs par défaut.

• À long terme, utilisez une combinaison de ResourceQuotas au niveau de l'espace de noms et de LimitRanges au niveau du pod, et envisagez l'affinité de nœuds ou les teintes (taints) pour séparer les locataires si une isolation stricte est nécessaire.

4. Mauvaise configuration de la politique réseau cassant la connectivité

Symptôme : Le locataire A ne peut soudainement plus atteindre un service du locataire B, ou le trafic d'entrée externe est bloqué.

Cause racine : Une NetworkPolicy a été ajoutée ou modifiée et refuse maintenant le trafic de manière non intentionnelle. Erreur courante : une politique avec un sélecteur de pod vide, qui sélectionne tous les pods de l'espace de noms et bloque tout le trafic non explicitement autorisé.

Récupération :

• Listez toutes les NetworkPolicies dans les espaces de noms concernés :

kubectl get networkpolicies -A

• Pour la politique suspecte, affichez ses détails :

kubectl describe networkpolicy <nom-de-la-politique> -n <namespace>

• Si la politique est trop large, modifiez-la pour ajouter le bon sélecteur de pod ou autoriser l'entrée nécessaire depuis des espaces de noms spécifiques. Exemple de politique de refus total d'entrée mais autorisant depuis le même espace de noms et depuis un espace de noms de surveillance :

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny-ingress
  namespace: team-a
spec:
  podSelector: {}
  policyTypes:
  - Ingress
  ingress:
  - from:
    - podSelector: {}
    - namespaceSelector:
        matchLabels:
          purpose: monitoring

• Après application, testez à nouveau la connectivité.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle comme revue opérationnelle quotidienne ou hebdomadaire pour les clusters multi-locataires. Attribuez chaque élément à un seul responsable et révisez au moins mensuellement pour vous assurer qu'elle reste valide.

Pièges courants

Évitez ces erreurs qui apparaissent fréquemment dans les opérations multi-location Kubernetes.

1. Appliquer des changements sans exporter l'état actuel

Pourquoi cela arrive : Les opérateurs sous pression pour résoudre un problème sautent l'étape de sauvegarde.

Conséquence : Si le changement est erroné, il n'y a pas de moyen facile de revenir en arrière ; le problème s'aggrave et affecte plus de locataires.

Comment éviter et récupérer : Exécutez toujours kubectl get <ressource> -o yaml > backup.yaml avant de modifier. Si vous oubliez, vérifiez si la ressource est dans un dépôt GitOps ou si le cluster a une piste d'audit. Pour une récupération immédiate, si vous connaissez les valeurs précédentes, réappliquez-les manuellement.

2. Utiliser cluster-admin pour les opérations locataires

Pourquoi cela arrive : Il est pratique d'utiliser un kubeconfig cluster-admin pour toutes les tâches.

Conséquence : Une commande erronée peut affecter tous les locataires ; les limites de sécurité sont violées.

Comment éviter : Utilisez des comptes de service par espace de noms avec des rôles limités pour les opérations de routine. Par exemple, créez un Role tenant-admin qui permet toutes les actions dans un espace de noms mais pas entre les espaces de noms. Utilisez kubectl --as pour simuler l'identité du locataire avant d'accorder des autorisations.

3. Ignorer LimitRange et se fier uniquement à ResourceQuota

Pourquoi cela arrive : Les équipes pensent qu'un quota d'espace de noms suffit à empêcher la surconsommation.

Conséquence : Un seul pod sans limites peut consommer tout le CPU dans le quota de l'espace de noms, affamant les autres pods du même espace de noms.

Comment éviter : Définissez toujours à la fois ResourceQuota (limites agrégées) et LimitRange (défaut et maximum par pod). Exemple :

apiVersion: v1
kind: LimitRange
metadata:
  name: pod-limits
  namespace: team-a
spec:
  limits:
  - max:
      cpu: "2"
      memory: "4Gi"
    min:
      cpu: "100m"
      memory: "128Mi"
    default:
      cpu: "500m"
      memory: "512Mi"
    defaultRequest:
      cpu: "250m"
      memory: "256Mi"
    type: Pod

4. NetworkPolicies trop larges

Pourquoi cela arrive : Les opérateurs écrivent une politique qui autorise toute entrée depuis n'importe quel espace de noms parce qu'ils ne sont pas sûrs des exigences exactes de trafic.

Conséquence : L'isolation des locataires est rompue ; tout pod du cluster peut accéder aux services de l'espace de noms.

Comment éviter : Commencez par une politique de refus par défaut et autorisez explicitement uniquement les sources requises. Utilisez kubectl describe networkpolicy pour vérifier les sélecteurs. Testez avec un pod sonde depuis un autre espace de noms pour confirmer le refus.

5. Ne pas surveiller l'utilisation des quotas

Pourquoi cela arrive : Les quotas sont définis une fois puis oubliés.

Conséquence : Les locataires atteignent les limites strictes de manière inattendue, provoquant des pannes de production.

Comment éviter : Mettez en place des alertes sur l'utilisation des quotas. Par exemple, utilisez Prometheus et alertez lorsque kube_resourcequota{type="used"} / kube_resourcequota{type="hard"} > 0.8. Révisez l'utilisation des quotas chaque semaine et ajustez en fonction des tendances.

Conclusion

Dépanner efficacement la multi-location Kubernetes exige une approche disciplinée : connaître votre environnement, effectuer des changements incrémentaux sûrs, collecter des preuves tangibles et se préparer aux défaillances courantes. Les commandes et playbooks de ce guide vous donnent un point de départ, mais vous devez les adapter à la configuration et aux politiques spécifiques de votre cluster.

Comme prochaine étape, choisissez une vérification à faible risque dans la Liste de contrôle opérationnelle, enregistrez l'état actuel, exécutez la vérification documentée, comparez le résultat avec le signal attendu et examinez les dépendances telles que Namespace, Resource Quota et RBAC. Attribuez un responsable et définissez une cadence de revue.

Un flux de travail technique fiable rend les défaillances 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. Adoptez ces habitudes dès maintenant, et votre cluster multi-locataire restera stable, sécurisé et équitable pour tous les locataires.