Dépannage réseau des secrets Kubernetes : guide pratique

Introduction

Les secrets Kubernetes sont une primitive essentielle pour stocker des données sensibles telles que les mots de passe, les jetons et les clés. Lorsque les applications ne parviennent pas à accéder aux secrets, la cause première est souvent réseau : le pod ne peut pas joindre l'API Kubernetes, la résolution DNS échoue ou des politiques réseau bloquent le trafic. Ce guide propose une approche pratique, axée sur les commandes, pour dépanner les problèmes réseau liés aux secrets Kubernetes.

Nous couvrirons les diagnostics essentiels : vérifier l'environnement Kubernetes, inspecter les secrets et leurs montages, tester la connectivité DNS et des services, analyser les politiques réseau et récupérer des défaillances courantes. Chaque étape comprend des commandes concrètes, les résultats attendus et les points de décision.

L'objectif est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des variables factices plutôt que des secrets réels, vérifier le résultat et documenter les chemins de récupération. Que vous soyez développeur, ingénieur DevOps ou opérateur de plateforme, vous apprendrez à isoler et résoudre systématiquement les problèmes réseau des secrets.

Inventaire de la version et de l'environnement

Avant de dépanner, établissez une vision claire de votre cluster. Le comportement de Kubernetes varie selon les versions, et la gestion des secrets a évolué (par exemple, les secrets immuables sont GA en v1.21, améliorations du chiffrement KMS). Déterminez vos versions client et serveur :

kubectl version --short

La sortie attendue inclut les versions client et serveur, par exemple :

Client Version: v1.27.3
Kustomize Version: v5.0.1
Server Version: v1.26.5

Notez la version serveur ; elle dicte les fonctionnalités disponibles et les groupes d'API. Si vous gérez plusieurs clusters, confirmez le contexte actuel :

kubectl config current-context

Identifiez les nœuds et leur état :

kubectl get nodes

Recherchez tout nœud en état NotReady, ce qui pourrait indiquer des problèmes réseau affectant les pods. Pour une vue détaillée d'un nœud spécifique :

kubectl describe node <nom-du-nœud>

Vérifiez la section Conditions pour NetworkUnavailable ou KubeletNotReady.

Prérequis pour ce guide :

• Droits d'administrateur de cluster ou RBAC suffisants pour inspecter les secrets, pods, services et politiques réseau.
• kubectl configuré pour accéder au cluster.
• Compréhension de base des concepts réseau de Kubernetes.

Observation en lecture seule d'abord :

Listez tous les pods dans l'espace de noms où l'application s'exécute :

kubectl get pods -o wide

Exemple de sortie :

NAME                              READY   STATUS    RESTARTS   AGE   IP              NODE
my-app-7d9f8c5b6-abcde            0/1     CrashLoopBackOff   5      10m   10.244.1.5      node-1

Si un pod est en CrashLoopBackOff, inspectez ses journaux pour voir s'il signale une erreur lors de la lecture des secrets :

kubectl logs my-app-7d9f8c5b6-abcde --previous

Recherchez des messages comme Error: unable to read secret, connection refused ou timeout. Ceux-ci indiquent des problèmes réseau ou de permissions possibles.

Rayon d'impact et changement minimal :

Lors de tests de modifications, commencez par un seul pod ou déploiement. Utilisez kubectl apply avec un manifeste spécifique, et surveillez l'état du déploiement :

kubectl rollout status deployment/my-app

Si vous devez tester la connectivité localement, utilisez le transfert de port vers un pod sans modifier le réseau du cluster :

kubectl port-forward pod/my-app 8080:8080

Accédez ensuite à http://localhost:8080. Cela évite d'exposer les services en externe.

Chemin de configuration sûr

Les références de secrets mal configurées sont une cause fréquente de défaillance des applications. Cette section décrit une séquence sûre pour vérifier et corriger le montage et la consommation des secrets.

Étape 1 : Inspecter le secret

Tout d'abord, assurez-vous que le secret existe dans le bon espace de noms :

kubectl get secrets -n <espace-de-noms>

Exemple :

NAME                  TYPE     DATA   AGE
db-credentials        Opaque   2      5d

Affichez les détails du secret (sans révéler les valeurs sensibles) :

kubectl describe secret db-credentials -n <espace-de-noms>

La sortie inclut les métadonnées et les clés de données, mais pas les valeurs. Vérifiez que les clés attendues sont présentes.

Étape 2 : Vérifier la spécification du pod

Examinez comment le pod référence le secret :

kubectl get pod my-app-7d9f8c5b6-abcde -o yaml

Recherchez les champs envFrom ou env qui utilisent secretKeyRef, ou les volumes de type secret. Exemple :

env:
  - name: DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: db-credentials
        key: password

Si le nom du secret ou la clé est incorrect, le pod ne démarrera pas. Un secret manquant provoque un événement d'erreur.

Étape 3 : Tester l'accessibilité du secret

Vous pouvez tester directement la lecture d'un secret à l'aide d'un pod temporaire. Créez un pod de débogage avec kubectl run :

kubectl run secret-test --rm -it --image=alpine --restart=Never -- sh

Dans le pod, utilisez wget ou curl pour accéder à l'API Kubernetes (nécessite un ServiceAccount et RBAC appropriés). Plus simple : montez le secret et vérifiez le contenu des fichiers :

kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: secret-reader
spec:
  containers:
  - name: alpine
    image: alpine
    command: ["sh", "-c", "ls -l /etc/secrets && cat /etc/secrets/password && sleep 3600"]
    volumeMounts:
    - name: secret-volume
      mountPath: /etc/secrets
  volumes:
  - name: secret-volume
    secret:
      secretName: db-credentials
EOF

Vérifiez les journaux du pod :

kubectl logs secret-reader

Si le montage du volume échoue, les événements afficheront des erreurs. Si le fichier est vide ou manquant, vérifiez que le secret existe et que le pod a accès.

Étape 4 : Appliquer une correction minimale

Après avoir identifié la mauvaise configuration, appliquez un manifeste corrigé. Sauvegardez toujours le déploiement actuel d'abord :

kubectl get deployment my-app -o yaml > my-app-backup.yaml

Modifiez le déploiement (ou appliquez un nouveau YAML) puis :

kubectl apply -f corrected-deployment.yaml
kubectl rollout status deployment/my-app

Surveillez le déploiement ; s'il échoue, annulez avec kubectl rollout undo deployment/my-app.

Considérations de version :

• Dans Kubernetes v1.20+, les secrets Immutable peuvent être créés avec immutable: true pour empêcher toute modification accidentelle. Si un secret est immuable et que vous tentez de le mettre à jour, vous obtiendrez une erreur de validation.
• Les secrets de jeton de ServiceAccount sont automatiquement montés dans les pods sauf si automountServiceAccountToken: false. Si votre application a besoin d'un accès API, assurez-vous que le pod possède un jeton.

Vérification et diagnostics

Cette section se concentre sur des vérifications systématiques du DNS, de la connectivité des services et des politiques réseau qui affectent l'accès aux secrets.

Résolution DNS pour l'API Kubernetes

Les pods utilisent DNS pour résoudre les services et l'API Kubernetes. Vérifiez que le DNS fonctionne dans un pod. Démarrez un pod de débogage :

kubectl run dns-test --rm -it --image=busybox --restart=Never -- nslookup kubernetes.default.svc

Sortie attendue :

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

Name:      kubernetes.default.svc
Address 1: 10.96.0.1 kubernetes.default.svc.cluster.local

Si la résolution échoue, vérifiez les pods CoreDNS :

kubectl get pods -n kube-system -l k8s-app=kube-dns

Tous doivent être Running. Vérifiez les journaux :

kubectl logs -n kube-system -l k8s-app=kube-dns

Connectivité des services

Si votre application utilise un service pour accéder à un backend qui lit des secrets (par exemple, une base de données), testez la connectivité. Obtenez l'IP du service :

kubectl get svc my-db-service

À partir d'un pod de débogage, tentez une connexion :

kubectl run conn-test --rm -it --image=busybox --restart=Never -- wget -O- http://my-db-service:5432

Remplacez le port si nécessaire. Si la connexion est refusée, vérifiez les points de terminaison :

kubectl get endpoints my-db-service

Si les points de terminaison sont vides (<none>), le service n'a pas de pods prêts. Vérifiez que les étiquettes des pods correspondent au sélecteur du service.

Politiques réseau

Les NetworkPolicies peuvent bloquer le trafic vers les pods qui utilisent des secrets. Listez les politiques dans l'espace de noms :

kubectl get networkpolicies -n <espace-de-noms>

Inspectez une politique :

kubectl describe networkpolicy <nom-de-la-politique> -n <espace-de-noms>

Vérifiez si la politique refuse le trafic entrant/sortant vers le pod. Par exemple, une politique peut autoriser uniquement le trafic provenant d'espaces de noms spécifiques. Vous pouvez créer temporairement un pod de test dans le même espace de noms pour voir s'il peut atteindre le service. Sinon, ajustez la politique ou les étiquettes du pod.

Test de consommation de secret de bout en bout

Créez un petit job qui lit un secret et écrit un fichier marqueur pour vérifier. Exemple de YAML de job :

apiVersion: batch/v1
kind: Job
metadata:
  name: secret-consumer-test
spec:
  template:
    spec:
      containers:
      - name: test
        image: alpine
        command: ["sh", "-c", "cat /etc/secret-volume/password && echo success > /tmp/result"]
        volumeMounts:
        - name: secret-volume
          mountPath: /etc/secret-volume
      restartPolicy: Never
      volumes:
      - name: secret-volume
        secret:
          secretName: db-credentials
  backoffLimit: 1

Appliquez et vérifiez les journaux :

kubectl apply -f secret-consumer-test.yaml
kubectl logs job/secret-consumer-test

Si les journaux affichent la valeur du secret attendue (vous pouvez la masquer), le montage du secret fonctionne.

Modes de défaillance et récupération

Modes de défaillance courants liés au réseau des secrets et leurs étapes de récupération.

Défaillance : le pod ne peut pas monter le volume du secret

Symptômes : le pod reste en ContainerCreating avec des événements comme :

Warning  FailedMount  2m (x4 over 5m)  kubelet  MountVolume.SetUp failed for volume "secret-volume" : secret "db-credentials" not found

Diagnostic : secret manquant dans l'espace de noms, ou faute de frappe dans secretName.

Récupération :

1. Vérifiez que le secret existe : kubectl get secrets -n <espace-de-noms>.
2. S'il manque, créez-le ou corrigez la référence.
3. Mettez à jour le pod/déploiement et redéployez.

Défaillance : l'application ne peut pas s'authentifier auprès d'un service externe en utilisant un secret

Symptômes : les journaux de l'application affichent authentication failed ou connection timeout lors de la connexion à une base de données/API.

Diagnostic : le contenu du secret peut être correct, mais le chemin réseau du pod vers le service externe est bloqué (politique de sortie, pare-feu).

Récupération :

1. Testez la connectivité pod vers externe : kubectl run net-test --rm -it --image=busybox -- nc -vz db.example.com 5432.
2. Vérifiez la NetworkPolicy de sortie : kubectl get networkpolicies -n <espace-de-noms> et recherchez les règles de sortie limitant les destinations.
3. Vérifiez la configuration de sortie du cluster (par exemple, NAT cloud, proxy).
4. Ajustez la politique ou la route réseau.

Défaillance : le pod ne peut pas atteindre l'API Kubernetes pour récupérer un secret via une bibliothèque client

Symptômes : les journaux de l'application affichent 403 Forbidden ou connection refused lors de la tentative de lecture d'un secret depuis l'API.

Diagnostic : permissions RBAC insuffisantes, ou politique réseau bloquant l'accès à l'API, ou problème de jeton de ServiceAccount.

Récupération :

1. Vérifiez RBAC : kubectl auth can-i get secrets --as=system:serviceaccount:<espace-de-noms>:<nom-sa> -n <espace-de-noms>.
2. Si interdit, créez un Role/RoleBinding accordant get sur les secrets.
3. Testez la connectivité à l'API : depuis un pod de débogage, curl -k https://kubernetes.default.svc/api/v1/namespaces/<espace-de-noms>/secrets avec un jeton approprié.
4. Si la connexion est refusée, vérifiez la politique réseau autorisant la sortie vers l'API Kubernetes (port 443).

Défaillance : problèmes de résolution DNS entraînant l'échec de la résolution des noms de service

Symptômes : les journaux de l'application affichent unknown host pour les services, mais les connexions basées sur IP fonctionnent.

Diagnostic : problèmes CoreDNS ou dnsPolicy mal configurée.

Récupération :

1. Vérifiez les pods CoreDNS : kubectl get pods -n kube-system -l k8s-app=kube-dns.
2. En cas d'erreur, inspectez les journaux et redémarrez si nécessaire.
3. Vérifiez la dnsPolicy du pod : la valeur par défaut est ClusterFirst. Si Default ou None, passez à ClusterFirst.
4. Testez le DNS depuis le pod comme décrit précédemment.

Mesures préventives

• Utilisez des secrets immutable pour les données statiques afin d'éviter les mises à jour accidentelles.
• Appliquez des NetworkPolicies à moindre privilège, mais assurez-vous qu'elles autorisent les entrées/sorties nécessaires.
• Surveillez les événements pour les échecs liés aux secrets : kubectl get events --all-namespaces --field-selector reason=FailedMount.
• Testez régulièrement la consommation des secrets en CI/CD.

Liste de contrôle des opérations

Utilisez cette liste comme référence rapide pour dépanner les problèmes réseau des secrets Kubernetes.

1. Inventaire de l'environnement

• [ ] kubectl version --short enregistré.
• [ ] Contexte et espace de noms actuels identifiés.
• [ ] État des nœuds normal (kubectl get nodes).

1. Inspecter le secret et le pod

• [ ] Le secret existe : kubectl get secrets -n <ns>.
• [ ] Les clés du secret correspondent aux références du pod (kubectl describe secret et YAML du pod).
• [ ] Le statut du pod n'est ni ContainerCreating ni CrashLoopBackOff.

1. Tester les chemins réseau

• [ ] La résolution DNS fonctionne : nslookup kubernetes.default.svc dans un pod de débogage.
• [ ] Les points de terminaison du service sont peuplés : kubectl get endpoints.
• [ ] Les politiques réseau autorisent le trafic requis (kubectl describe networkpolicy).

1. Vérifier la consommation du secret

• [ ] Exécuter un job/pod de test qui monte le secret et imprime un marqueur.
• [ ] Vérifier les journaux de l'application pour une authentification réussie.

1. Appliquer des changements minimaux

• [ ] Sauvegarder les manifestes actuels.
• [ ] Appliquer un changement à la fois.
• [ ] Surveiller le déploiement et annuler si nécessaire.

1. Documenter et alerter

• [ ] Enregistrer la cause première et la correction dans le runbook.
• [ ] Configurer des alertes pour les échecs de montage de secret (par exemple, avec kubewatch ou des contrôleurs personnalisés).

Conclusion

Le dépannage réseau des secrets Kubernetes nécessite une approche méthodique qui sépare l'observation de l'intervention. En suivant l'inventaire de version, le chemin de configuration sûr, les diagnostics de vérification et les procédures de récupération décrites ici, vous pouvez rapidement identifier si les problèmes proviennent du DNS, des politiques réseau, de la connectivité des services ou de références de secret mal configurées.

N'oubliez pas de toujours protéger les valeurs sensibles, de minimiser le rayon d'impact et de vérifier chaque changement. Les commandes et exemples fournis sont conçus pour être sûrs et efficaces dans des clusters réels. À mesure que Kubernetes évolue, maintenez vos connaissances à jour et adaptez ces pratiques aux nouvelles fonctionnalités et améliorations de sécurité.

Commencez par les étapes de vérification à faible risque de la liste de contrôle des opérations, et construisez un manuel de réponse aux incidents robuste pour votre équipe.