Dépannage réseau du tableau de bord Kubernetes : guide pratique avec commandes et exemples

Introduction

Le dépannage réseau du tableau de bord Kubernetes (Web UI Dashboard) consiste à passer d'un problème observé à un résultat vérifié. Ce guide aide les opérateurs, les développeurs et les ingénieurs DevOps à diagnostiquer et corriger les problèmes de réseau liés au tableau de bord Kubernetes. Nous nous concentrons sur quatre domaines principaux : la résolution DNS, l'exposition des ports, la connectivité et le dépannage réseau général. Chaque étape comprend des commandes, les résultats attendus, les signaux d'échec et les décisions de récupération.

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 la récupération si l'état attendu n'est pas atteint.

Cet article suppose que vous disposez d'un cluster Kubernetes en cours d'exécution et que kubectl est configuré. Nous utiliserons le tableau de bord Kubernetes comme exemple principal, mais les techniques s'appliquent à toute interface web ou service dans Kubernetes.

Inventaire de la version et de l'environnement

Avant de commencer le dépannage, rassemblez des informations sur votre environnement. Cela évite les erreurs de diagnostic et garantit que vous ciblez le bon composant.

Identifier la version et le déploiement du tableau de bord

Tout d'abord, listez toutes les ressources dans l'espace de noms où le tableau de bord est déployé. Par défaut, le tableau de bord se trouve dans l'espace de noms kubernetes-dashboard. Exécutez :

kubectl get all -n kubernetes-dashboard

La sortie attendue comprend les pods, les services, les déploiements et les replicasets. Par exemple :

NAME                                             READY   STATUS    RESTARTS   AGE
pod/dashboard-metrics-scraper-7c5d7b4f8b-abcde   1/1     Running   0          5d
pod/kubernetes-dashboard-5f7b6c8d9-xyz12         1/1     Running   0          5d

NAME                                TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)         AGE
service/dashboard-metrics-scraper   ClusterIP   10.96.0.10      <none>        8000/TCP        5d
service/kubernetes-dashboard        ClusterIP   10.96.0.11      <none>        443/TCP         5d

NAME                                        READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/dashboard-metrics-scraper   1/1     1            1           5d
deployment.apps/kubernetes-dashboard        1/1     1            1           5d

Vérifiez la version de l'image pour garantir la compatibilité avec votre cluster :

kubectl get deployment kubernetes-dashboard -n kubernetes-dashboard -o jsonpath='{.spec.template.spec.containers[0].image}'

Exemple de sortie : kubernetesui/dashboard:v2.7.0. Vérifiez cette version par rapport à la matrice de compatibilité Kubernetes.

Vérifier les prérequis

• kubectl est installé et peut se connecter au cluster.
• Le tableau de bord est installé (sinon, consultez le guide d'installation officiel).
• Vous disposez des autorisations RBAC suffisantes pour afficher les ressources dans l'espace de noms kubernetes-dashboard.

Observation en lecture seule

Commencez toujours par des commandes en lecture seule pour éviter de modifier l'état. Exemples :

kubectl get pods -n kubernetes-dashboard -o wide
kubectl describe pod <nom-du-pod> -n kubernetes-dashboard
kubectl logs <nom-du-pod> -n kubernetes-dashboard --previous
kubectl rollout status deployment/kubernetes-dashboard -n kubernetes-dashboard

Ces commandes révèlent l'état des pods, les événements et les journaux sans effectuer de modifications.

Changement minimal justifié

Une fois que vous comprenez le problème, appliquez le changement minimal. Par exemple, si le pod du tableau de bord est en boucle de crash en raison d'un secret manquant, créez uniquement ce secret.

Commande de vérification

Après tout changement, vérifiez le résultat. Par exemple, après avoir corrigé une configuration, exécutez :

kubectl rollout status deployment/kubernetes-dashboard -n kubernetes-dashboard

Résultat attendu : deployment "kubernetes-dashboard" successfully rolled out.

Chemin de configuration sécurisé

La configuration du réseau du tableau de bord Kubernetes nécessite des étapes prudentes pour éviter d'exposer l'interface involontairement ou de rompre l'accès.

Service du tableau de bord par défaut

Le service du tableau de bord est de type ClusterIP par défaut, ce qui signifie qu'il n'est accessible qu'à l'intérieur du cluster. Pour y accéder de l'extérieur, plusieurs options s'offrent à vous :

• kubectl proxy
• kubectl port-forward
• Service NodePort
• Service LoadBalancer (cloud)
• Ingress

Nous allons explorer chaque méthode en mettant l'accent sur le dépannage.

Méthode 1 : kubectl proxy

C'est la méthode la plus simple et la plus sécurisée pour un accès local. Elle exécute un serveur proxy entre votre machine locale et le serveur d'API Kubernetes, gérant l'authentification.

kubectl proxy

Par défaut, il écoute sur 127.0.0.1:8001. Accédez ensuite au tableau de bord à l'adresse :

http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/

Vous serez invité à saisir un jeton ou un kubeconfig. Pour le dépannage, si le proxy échoue, vérifiez que kubectl peut joindre le cluster :

kubectl cluster-info

Méthode 2 : kubectl port-forward

La redirection de port mappe un port local vers un port du pod du tableau de bord directement. Elle ne nécessite pas d'exposer le service en externe.

kubectl port-forward -n kubernetes-dashboard service/kubernetes-dashboard 8443:443

Cette commande transfère le port local 8443 vers le port 443 du service. Accédez via https://localhost:8443.

Dépannage : si vous obtenez une connexion refusée, vérifiez que le service existe et que le pod est en cours d'exécution :

kubectl get svc -n kubernetes-dashboard kubernetes-dashboard
kubectl get pods -n kubernetes-dashboard -l k8s-app=kubernetes-dashboard

Méthode 3 : Service NodePort

Vous pouvez modifier le service pour le type NodePort, qui expose le service sur un port statique sur l'IP de chaque nœud.

kubectl patch svc kubernetes-dashboard -n kubernetes-dashboard -p '{"spec":{"type":"NodePort"}}'

Ensuite, trouvez le port attribué :

kubectl get svc kubernetes-dashboard -n kubernetes-dashboard -o jsonpath='{.spec.ports[0].nodePort}'

Exemple de sortie : 32323. Accédez via https://<ip-du-nœud>:32323.

Considération de sécurité : NodePort expose le tableau de bord sur tous les nœuds. Utilisez des règles de pare-feu pour restreindre l'accès.

Méthode 4 : Ingress

Pour la production, utilisez un Ingress avec TLS. Voici un exemple de manifeste Ingress :

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: dashboard-ingress
  namespace: kubernetes-dashboard
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - dashboard.example.com
    secretName: dashboard-tls
  rules:
  - host: dashboard.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: kubernetes-dashboard
            port:
              number: 443

Appliquez avec kubectl apply -f ingress.yaml. Vérifiez ensuite :

kubectl get ingress -n kubernetes-dashboard

Dépannage de l'Ingress : vérifiez que le contrôleur Ingress est en cours d'exécution, que le service backend est joignable et que le secret TLS est valide.

Vérification et diagnostics

Après avoir configuré l'accès, vérifiez que le tableau de bord est joignable et fonctionnel. Cette section couvre les problèmes courants et les commandes de diagnostic.

Tests de connectivité

Résolution DNS

Tout d'abord, assurez-vous que le service du tableau de bord peut être résolu via DNS à l'intérieur du cluster. Depuis un pod dans le cluster (par exemple, un pod de débogage), exécutez :

kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup kubernetes-dashboard.kubernetes-dashboard.svc.cluster.local

Sortie attendue :

Server:    10.96.0.10
Address 1: 10.96.0.10 kube-dns.kube-system.svc.cluster.local

Name:      kubernetes-dashboard.kubernetes-dashboard.svc.cluster.local
Address 1: 10.96.0.11 kubernetes-dashboard.kubernetes-dashboard.svc.cluster.local

Si la résolution échoue, vérifiez les pods CoreDNS et leurs journaux.

Vérification des ports

Vérifiez que le pod du tableau de bord écoute sur le port attendu (8443 par défaut). Exécutez la commande suivante dans le pod :

kubectl exec -n kubernetes-dashboard <pod-du-tableau-de-bord> -- netstat -tulpn | grep 8443

Si netstat n'est pas disponible, utilisez ss ou vérifiez les ports exposés du conteneur :

kubectl get pod <pod-du-tableau-de-bord> -n kubernetes-dashboard -o jsonpath='{.spec.containers[0].ports}'

Sortie : [{"containerPort":8443,"protocol":"TCP"}]

Points de terminaison du service

Vérifiez que le service possède des points de terminaison pointant vers les IP des pods :

kubectl get endpoints kubernetes-dashboard -n kubernetes-dashboard

Résultat attendu : NAME: kubernetes-dashboard, ENDPOINTS: 10.244.1.5:8443 (l'IP de votre pod). Si les points de terminaison sont vides, le sélecteur du service ne correspond à aucun pod.

Pare-feu et politiques réseau

Vérifiez si une politique réseau bloque le trafic vers le tableau de bord :

kubectl get networkpolicies -n kubernetes-dashboard

Si des politiques existent, inspectez-les avec kubectl describe networkpolicy <nom> -n kubernetes-dashboard.

Problèmes spécifiques au tableau de bord

Erreurs d'authentification

Le tableau de bord nécessite un jeton ou un kubeconfig pour la connexion. Si vous voyez des erreurs d'authentification, créez un compte de service avec les autorisations appropriées et obtenez son jeton :

kubectl create serviceaccount dashboard-admin -n kubernetes-dashboard
kubectl create clusterrolebinding dashboard-admin --clusterrole=cluster-admin --serviceaccount=kubernetes-dashboard:dashboard-admin
kubectl create token dashboard-admin -n kubernetes-dashboard

Utilisez le jeton pour vous connecter.

Erreurs CSRF

Si vous voyez une « erreur de jeton CSRF » lors de l'utilisation du transfert de port, assurez-vous d'accéder au tableau de bord via la bonne URL et de ne pas mélanger HTTP/HTTPS.

Page blanche ou problèmes de chargement

Vérifiez les journaux du pod du tableau de bord :

kubectl logs -n kubernetes-dashboard <pod-du-tableau-de-bord>

Recherchez des erreurs liées au collecteur de métriques, à la connectivité du serveur d'API ou à des secrets manquants.

Modes de défaillance et récupération

Dans cette section, nous décrivons les scénarios de défaillance courants, leurs symptômes, leur diagnostic et les étapes de récupération.

Scénario 1 : Pod du tableau de bord en CrashLoopBackOff

Symptôme : Le statut du pod est CrashLoopBackOff.

Diagnostic :

kubectl get pods -n kubernetes-dashboard
kubectl describe pod <nom-du-pod> -n kubernetes-dashboard
kubectl logs <nom-du-pod> -n kubernetes-dashboard --previous

Exemple d'erreur dans les journaux : Error: unable to load TLS certificates: open /certs/tls.crt: no such file or directory.

Cause : Secret TLS kubernetes-dashboard-certs manquant.

Récupération : Créez le secret avec un certificat auto-signé. Le tableau de bord peut le générer s'il est omis dans certaines versions, mais il est préférable d'en fournir un. Pour les tests, vous pouvez créer :

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=kubernetes-dashboard"
kubectl create secret tls kubernetes-dashboard-certs --key tls.key --cert tls.crt -n kubernetes-dashboard

Ensuite, redémarrez le déploiement :

kubectl rollout restart deployment kubernetes-dashboard -n kubernetes-dashboard

Vérifiez le statut du déploiement.

Scénario 2 : Service du tableau de bord inaccessible de l'extérieur

Symptôme : Le navigateur expire lors de l'accès à l'IP NodePort ou LoadBalancer.

Diagnostic :

• Vérifiez le type et les ports du service : kubectl get svc -n kubernetes-dashboard.
• Vérifiez les points de terminaison : kubectl get endpoints -n kubernetes-dashboard.
• Vérifiez les règles de pare-feu des nœuds et les groupes de sécurité.
• Pour un LoadBalancer, assurez-vous que l'IP externe est attribuée et non en attente.

Récupération (pour NodePort) : Assurez-vous que le pare-feu du nœud autorise le port NodePort. Par exemple, sur AWS, ajoutez une règle entrante au groupe de sécurité pour le port 32323. Vous pouvez aussi utiliser kubectl port-forward comme mesure temporaire.

Scénario 3 : L'Ingress renvoie 503 ou 502

Symptôme : L'accès via Ingress donne 503 Service Unavailable.

Diagnostic :

• Vérifiez la ressource Ingress : kubectl describe ingress dashboard-ingress -n kubernetes-dashboard.
• Vérifiez les journaux du contrôleur Ingress (par exemple, nginx-ingress-controller dans l'espace de noms ingress-nginx).
• Vérifiez que le service backend est opérationnel et que les points de terminaison existent.

Cause possible : Le contrôleur Ingress ne peut pas joindre le service du tableau de bord car il attend du HTTP mais le tableau de bord utilise HTTPS. Vous avez besoin de l'annotation backend-protocol: HTTPS (comme dans notre exemple).

Récupération : Mettez à jour l'annotation de l'Ingress et réappliquez.

Scénario 4 : Le tableau de bord affiche « Aucune ressource trouvée » ou les données ne se chargent pas

Symptôme : Les métriques ou les ressources ne s'affichent pas.

Diagnostic :

• Vérifiez le pod du collecteur de métriques : kubectl get pods -n kubernetes-dashboard -l k8s-app=dashboard-metrics-scraper.
• Vérifiez ses journaux : kubectl logs -n kubernetes-dashboard <pod-du-collecteur-de-métriques>.
• Assurez-vous que le tableau de bord peut joindre le service du collecteur de métriques : dashboard-metrics-scraper:8000.

Récupération : Redémarrez le déploiement du collecteur de métriques si nécessaire : kubectl rollout restart deployment dashboard-metrics-scraper -n kubernetes-dashboard.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle pour dépanner systématiquement les problèmes réseau du tableau de bord. Chaque élément comprend une commande et le résultat attendu.

Commencez toujours par des étapes en lecture seule, puis passez aux modifications si nécessaire. Documentez chaque changement et sa vérification.

Conclusion

Le dépannage réseau du tableau de bord Kubernetes nécessite une approche systématique. En suivant les méthodes décrites dans ce guide, vous pouvez diagnostiquer et résoudre les problèmes liés au DNS, aux ports, à la connectivité et à la configuration. N'oubliez pas d'observer d'abord, d'apporter des modifications minimales, de vérifier les résultats et d'avoir un plan de récupération. Utilisez la liste de contrôle opérationnelle pour rester organisé. Pour en savoir plus, consultez la documentation officielle du tableau de bord Kubernetes et la documentation de votre fournisseur de réseau de cluster.