Aller au contenu

Dépannage

Audience: Développeur d'application

Symptômes diagnosticables depuis le côté pod. Pour les problèmes de politique Vault, la configuration du cluster ou les requêtes de métriques, voir operators/monitoring.

Le pod démarre mais ne peut pas se connecter à la base de données

Symptôme Cause probable Quoi vérifier
authentication failed for user "DBUSER" Valeurs par défaut du mode d'annotation utilisées — le nom de la variable d'environnement est DBUSER, pas ce que l'application lit Définir <dbname>.env-key-dbuser et <dbname>.env-key-dbpassword explicitement
role "DBUSER" does not exist Identique au précédent, l'application lit le nom de variable d'environnement par défaut Vérifier que les noms de variables correspondent à ceux attendus par l'application
connection refused Hôte ou port incorrect dans le modèle URI Vérifier <dbname>.template ; s'assurer que le nom d'hôte DB est résolvable depuis l'intérieur du pod
SSL connection required L'application se connecte sans TLS, la DB l'exige Ajouter ?sslmode=require (ou verify-full) à votre modèle URI
Les identifiants fonctionnent mais expirent après quelques heures token_period non défini sur le rôle Vault Demander à votre opérateur de vérifier vault read auth/kubernetes/role/<role> — token_period doit être non nul

L'environnement du pod contient __VDBI_PH_...

Ce placeholder est défini par le webhook en mode NRI et doit être remplacé par le plugin NRI avant le démarrage du processus conteneur.

Si kubectl exec -- env affiche toujours la chaîne placeholder plutôt que des identifiants réels, le plugin NRI n'a pas effectué la substitution.

Causes fréquentes :

  • Pod du DaemonSet du plugin NRI non actif sur le nœud. Vérifier que le DaemonSet dispose d'un pod prêt sur le même nœud que votre pod : 
    kubectl -n vault-db-injector get pods -o wide | grep nri
kubectl get pod myapp -n team-myapp -o wide   # note the NODE
  • Pod planifié sur un nœud où containerd NRI n'est pas activé. L'opérateur doit activer NRI dans la configuration de containerd sur chaque nœud exécutant des charges de travail injectées.
  • Le pod ne porte pas le label correct. Le plugin NRI filtre les pods par le label vault-db-injector: "true" (ou l'équivalent configuré par l'opérateur). Un pod admis sans ce label reçoit des placeholders qui ne sont jamais substitués.

L'opérateur peut vérifier vdbi_nri_unwrap_failures_total{reason} pour voir pourquoi la substitution a échoué. Voir operators/monitoring pour la référence des métriques.

Pod bloqué en ContainerCreating après l'admission

Le plugin NRI s'exécute de façon synchrone lors de la création du conteneur. Si le plugin échoue à résoudre les identifiants, containerd peut bloquer le démarrage du conteneur.

Causes probables :

  • Échec du login Vault lors de la substitution NRI. Le plugin s'authentifie auprès de Vault en utilisant le ServiceAccount du pod. Si le SA n'est lié à aucun rôle Vault, le login est rejeté.
  • ServiceAccount du pod absent de bound_service_account_names du rôle Vault. Demander à votre opérateur de vérifier le rôle Vault : 
    vault read auth/kubernetes/role/<role-name>
    Le nom du SA et le namespace doivent apparaître dans la sortie.
  • Pod admis en dehors du sélecteur de namespace du webhook. Si le pod a été créé dans un namespace non couvert par le webhook, le webhook n'a pas été appelé, aucun placeholder n'a été défini, et le plugin NRI ignore le pod (aucun placeholder à substituer). Le pod devrait démarrer normalement dans ce cas — s'il se bloque, cela n'est pas lié à l'injector.

La métrique vdbi_nri_unwrap_failures_total{reason} est le signal principal pour les échecs de substitution NRI. Voir operators/monitoring pour le catalogue complet des métriques et les règles d'alerte suggérées.

Vérification des annotations définies par le webhook

Après l'admission du pod, inspectez les annotations écrites par le webhook :

kubectl -n team-myapp get pod myapp -o yaml | grep db-creds-injector

Vérifier que :

  • Chaque <dbname>.role est présent et pointe vers le rôle Vault attendu.
  • Chaque <dbname>.uuid est défini (écrit par le webhook lors de l'admission). S'il est absent, le webhook n'a pas traité le pod.
  • Aucune clé d'annotation obsolète ou mal orthographiée n'est présente.

Messages de rejet du webhook

Les événements du pod contiennent souvent le motif de rejet émis par le webhook :

kubectl -n team-myapp describe pod myapp | grep -A10 Events

Un événement FailedCreate ou lié au webhook accompagné d'un message d'erreur Vault indique que l'injector a retourné une réponse non-200 lors de l'admission. Transmettez le texte complet de l'événement à votre opérateur.

EOF / use of closed network connection sporadiques du webhook

Symptôme : une création de pod échoue une fois avec un événement du type

failed calling webhook "vault-db-injector...": Post "https://...:8443/mutate": EOF

ou use of closed network connection, et la nouvelle tentative réussit. Rien n'apparaît dans les logs de l'injector. L'apiserver journalise la même erreur.

Cause : avant la v3.2.9, le serveur HTTP du webhook n'avait pas d'IdleTimeout. Go fermait donc les connexions keep-alive inactives après 10s alors que le client de l'apiserver les conserve 90s. Quand une requête d'admission arrivait sur une connexion que l'injector venait de fermer, l'apiserver échouait.

Correctif : mettre à jour l'injector en v3.2.9 ou ultérieure. Le serveur garde désormais les connexions inactives 120s et ses timeouts de lecture/écriture sont à 30s, le timeoutSeconds maximal d'un webhook côté apiserver. Ces valeurs sont des constantes dans pkg/injector, pas de la configuration : les deux bornes viennent de Kubernetes lui-même et sont identiques sur tout cluster, un paramètre ne pourrait donc que passer en dessous et réintroduire le bug.