Dépannage des ConfigMaps et Secrets Kubernetes avec exemples pratiques

Intro

Cette version française explique Kubernetes ConfigMaps and Secrets troubleshooting with practical examples avec le même objectif pratique que l article source : aider le lecteur à comprendre le contexte, les décisions à prendre et les points à vérifier avant de passer à l action.

Les ConfigMaps et Secrets sont le moyen standard d'injecter de la configuration et des valeurs sensibles dans des Pods Kubernetes. Ce guide montre comment les utiliser via des variables d'environnement et des fichiers montés, comment les mises à jour se propagent aux workloads en cours d'exécution, et comment dépanner en toute sécurité sans divulguer de mots de passe. Vous repartirez avec un workflow reproductible, des exemples pratiques à exécuter, et des correctifs pour les erreurs les plus fréquentes.

Astuce SEO et lisibilité technique : nous conservons des termes clefs du secteur quand ils sont usuels, par exemple Kubernetes ConfigMap, Kubernetes Secret, K8s environment variables, Kubernetes mounted secrets et Kubernetes troubleshooting.

Aperçu du workflow

Concevoir les clés et le périmètre : choisissez des noms de clés explicites et gardez des données petites et ciblées par workload.
Créer les ressources : définissez des ConfigMaps pour les données non sensibles et des Secrets pour les valeurs sensibles.
Raccorder aux Pods : utilisez env/valueFrom pour la configuration au niveau du processus et des volumes pour la configuration basée sur des fichiers.
Valider dans les Pods en cours : listez les variables d'environnement, lisez les fichiers montés et vérifiez les événements.
Planifier les mises à jour : comprenez quand un rollout est nécessaire et quand les volumes se rafraîchissent in situ.
Déclencher des rollouts sûrs : redémarrez les Deployments ou utilisez des annotations de checksum pour déclencher automatiquement un rollout lors de changements.
Surveiller et faire tourner : observez logs/événements et faites une rotation des Secrets avec un risque minimal.

Exemples pratiques

Espace de noms et ressources d'exemple :

kubectl create namespace cfgdemo

kubectl -n cfgdemo create configmap app-config \
  --from-literal=APP_MODE=dev \
  --from-literal=FEATURE_FLAG=true

kubectl -n cfgdemo create secret generic app-secret \
  --from-literal=DB_USER=demo \
  --from-literal=DB_PASSWORD='s3cr3tP@ss'

Deployment utilisant à la fois des variables d'environnement et des fichiers montés :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
  namespace: cfgdemo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: app
  template:
    metadata:
      labels:
        app: app
    spec:
      containers:
      - name: toolbox
        image: busybox:1.36
        command: ["sh","-c","sleep 3600"]
        envFrom:
          - configMapRef:
              name: app-config
          - secretRef:
              name: app-secret
        volumeMounts:
          - name: cm-vol
            mountPath: /etc/app/config
          - name: secret-vol
            mountPath: /var/run/secrets/app
            readOnly: true
      volumes:
        - name: cm-vol
          configMap:
            name: app-config
        - name: secret-vol
          secret:
            secretName: app-secret

Appliquer et vérifier :

kubectl -n cfgdemo apply -f deployment.yaml
kubectl -n cfgdemo rollout status deploy/app

# Vérifier les env sans exposer les secrets
kubectl -n cfgdemo exec deploy/app -- sh -c 'printenv | sort | grep -E "^(APP_MODE|FEATURE_FLAG|DB_USER)="'
# Vérifier que la variable secrète existe sans afficher sa valeur
kubectl -n cfgdemo exec deploy/app -- sh -c '[ -n "$DB_PASSWORD" ] && echo DB_PASSWORD is set'

# Vérifier l'existence des fichiers montés et afficher les tailles plutôt que le contenu
kubectl -n cfgdemo exec deploy/app -- sh -c 'ls -l /etc/app/config; ls -l /var/run/secrets/app; wc -c /var/run/secrets/app/DB_PASSWORD'

Mettre à jour le ConfigMap et observer le comportement :

# Modifier une valeur dans le ConfigMap
kubectl -n cfgdemo patch configmap app-config \
  --type merge -p '{"data":{"APP_MODE":"prod"}}'

# Les fichiers montés depuis le ConfigMap se rafraîchissent bientôt ; vérifier le contenu du fichier
kubectl -n cfgdemo exec deploy/app -- sh -c 'cat /etc/app/config/APP_MODE'

# Les variables d'env ne changent pas dans les Pods existants ; déclencher un rollout pour prendre la nouvelle valeur
kubectl -n cfgdemo rollout restart deploy/app
kubectl -n cfgdemo rollout status deploy/app
kubectl -n cfgdemo exec deploy/app -- sh -c 'echo APP_MODE=$APP_MODE'

Effectuer une rotation d'un Secret en toute sécurité :

# Créer une nouvelle valeur de secret
kubectl -n cfgdemo create secret generic app-secret-v2 \
  --from-literal=DB_USER=demo \
  --from-literal=DB_PASSWORD='n3wS3cr3t' \
  --dry-run=client -o yaml | kubectl apply -f -

# Faire pointer le Deployment vers le nouveau Secret
kubectl -n cfgdemo set env deploy/app --from=secret/app-secret-v2 --keys=DB_USER,DB_PASSWORD --overwrite

# Mettre à jour aussi la référence du volume secret monté
kubectl -n cfgdemo patch deploy app -p '{
  "spec": {"template": {"spec": {"volumes": [
    {"name":"secret-vol","secret":{"secretName":"app-secret-v2"}},
    {"name":"cm-vol","configMap":{"name":"app-config"}}
  ]}}}}'

kubectl -n cfgdemo rollout status deploy/app

Commandes de dépannage sûres

Lister et décrire sans déverser de données sensibles :

kubectl -n cfgdemo get configmap, secret
kubectl -n cfgdemo describe configmap/app-config
kubectl -n cfgdemo describe secret/app-secret

Inspecter le câblage du Pod :

kubectl -n cfgdemo get pod -l app=app
kubectl -n cfgdemo get pod -l app=app -o wide
kubectl -n cfgdemo get pod -l app=app -o yaml | grep -A3 -E 'envFrom:|volumeMounts:|volumes:'

Vérifier env et fichiers dans le conteneur sans divulguer de secrets :

kubectl -n cfgdemo exec deploy/app -- printenv APP_MODE
kubectl -n cfgdemo exec deploy/app -- sh -c 'test -f /var/run/secrets/app/DB_PASSWORD && echo secret file present'

Uniquement si nécessaire, décoder une seule clé dans une session contrôlée :

# ATTENTION : ceci affiche un secret à l'écran
kubectl -n cfgdemo get secret app-secret -o jsonpath='{.data.DB_PASSWORD}' | base64 -d; echo

Vérifier les événements et les logs pour les problèmes de montage ou de permissions :

kubectl -n cfgdemo get events --sort-by=.lastTimestamp | tail -n 20
kubectl -n cfgdemo logs deploy/app

Erreurs courantes et correctifs

Utiliser un ConfigMap pour des données sensibles
Correctif : placez les clés sensibles dans un Secret. Gardez les ConfigMaps pour les réglages non sensibles.

Attendre que les variables d'environnement se mettent à jour sans rollout
Correctif : redémarrez le Deployment après modification de ConfigMaps ou Secrets référencés via env/envFrom.

Attendre des mises à jour instantanées des fichiers montés
Fait : les fichiers montés depuis un ConfigMap/Secret se rafraîchissent peu après. Les applis qui mettent en cache doivent recharger à la détection du changement.

Fautes de frappe entre ressource et spec du Pod
Correctif : recoupez les clés avec kubectl describe et printenv dans le Pod.

Mauvais namespace
Correctif : passez -n <ns> à kubectl ou définissez un namespace par défaut dans le contexte.

Confusion base64 des Secrets lors d'édition YAML à la main
Correctif : préférez kubectl create secret generic ... qui gère l'encodage. Si vous éditez à la main, utilisez echo -n pour éviter les retours à la ligne : echo -n 'value' | base64.

Surprises de permissions de fichiers
Fait : les fichiers Secret sont en lecture seule par défaut. Si votre appli a besoin d'un accès group, définissez fsGroup sur le Pod ou defaultMode sur le volume.

Objets trop volumineux dans ConfigMaps/Secrets
Correctif : restez sous les limites typiques et stockez les gros artefacts ailleurs (p. ex. système de fichiers ou objet monté via volume).

Comportement de déploiement et mises à jour

Les valeurs env et envFrom sont chargées au démarrage du conteneur. Les Pods doivent être redémarrés pour voir les changements.
Les volumes ConfigMap et Secret montés se mettent à jour peu après une modification. L'appli peut néanmoins devoir recharger sa config.
Les Deployments ne redémarrent pas automatiquement sur changement externe. Seuls les changements du template de Pod déclenchent un nouveau ReplicaSet.
Pour forcer un rollout quand la config change, soit :
Redémarrez manuellement : kubectl rollout restart deploy/<name>
Utilisez un pattern d'annotation par checksum pour que toute modification de ConfigMap/Secret modifie le template et déclenche un rollout.

Exemple de checksum (shells Linux) :

CM_SUM=$(kubectl -n cfgdemo get cm app-config -o json | sha256sum | cut -d' ' -f1)
SEC_SUM=$(kubectl -n cfgdemo get secret app-secret -o json | sha256sum | cut -d' ' -f1)

kubectl -n cfgdemo annotate deploy/app \
  config-hash=$CM_SUM secret-hash=$SEC_SUM --overwrite
kubectl -n cfgdemo rollout status deploy/app

Alternative macOS pour la commande de checksum :

CM_SUM=$(kubectl -n cfgdemo get cm app-config -o json | shasum -a 256 | cut -d' ' -f1)
SEC_SUM=$(kubectl -n cfgdemo get secret app-secret -o json | shasum -a 256 | cut -d' ' -f1)

Plan pilote local

Objectif : valider le câblage et le comportement de rollout dans un namespace bac à sable avec un impact minimal.

Portée :

Un namespace (cfgdemo), un ConfigMap, un Secret, un Deployment avec 1 réplique.
Un câblage à la fois par variables d'environnement et par volumes pour comparer les comportements.

Étapes :

Créez les ressources et le Deployment exactement comme dans la section Exemples pratiques.
Vérifiez le câblage initial :

printenv APP_MODE
confirmez la présence et la taille du fichier secret

Changez une clé dans le ConfigMap ; confirmez :

le rafraîchissement du fichier monté
la non‑mise à jour de la valeur env avant redémarrage

Redémarrez le Deployment ; confirmez la mise à jour des env.
Faites une rotation du Secret en changeant le nom référencé puis en roulant.
Ajoutez des annotations de checksum et ré‑appliquez après tout changement de config ; confirmez le rollout automatique.

Critères de sortie :

Vous prouvez en quelques minutes :
Les env nécessitent un redémarrage pour se mettre à jour.
Les fichiers montés se mettent à jour sans rollout.
Un rollout manuel ou par checksum propage les changements de façon prévisible.

Conclusion

Les ConfigMaps et Secrets permettent de séparer la configuration du code tout en protégeant les valeurs sensibles. En pratique, validez à la fois le câblage via env et via volumes, sachez quand un redémarrage est requis, et privilégiez des commandes de dépannage qui évitent l'exposition de secrets. Démarrez avec un petit pilote, observez la propagation des mises à jour, puis adoptez un mode de rollout reproductible comme les annotations par checksum. Avec ces patterns, les équipes modifient la configuration en confiance et résolvent les problèmes rapidement.