ConfigMaps et Secrets Kubernetes : Dépannage avec exemples pratiques

Les ConfigMaps et les Secrets constituent la méthode standard pour injecter la configuration et les valeurs sensibles dans les 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 charges de travail en cours d'exécution, et comment dépanner sans divulguer d'identifiants. Vous découvrirez un flux de travail reproductible, des exemples pratiques exécutables, ainsi que les correctifs aux erreurs fréquentes.

Vue d'ensemble du flux de travail

Concevoir les clés et leur portée : choisir des noms de clés clairs (par exemple APP_MODE, FEATURE_FLAG) et conserver des données réduites et ciblées par charge de travail.
Créer les ressources : définir des ConfigMaps pour les données non sensibles et des Secrets pour les valeurs sensibles.
Brancher dans les Pods : utiliser env/valueFrom pour la configuration au niveau du processus et les volumes pour la configuration basée sur des fichiers.
Valider dans les Pods en cours d'exécution : lister les variables d'environnement, lire les fichiers montés, et consulter les événements.
Planifier les mises à jour : comprendre quand un redéploiement (rollout) est requis et quand les volumes se rafraîchissent sur place (le kubelet synchronise les volumes ConfigMap/Secret environ toutes les 10 secondes).
Déclencher des redéploiements sûrs : redémarrer les Deployments ou utiliser des annotations de checksum pour rouler automatiquement lors des changements.
Surveiller et faire pivoter : suivre les journaux/événements et faire pivoter les Secrets avec un risque minimal.

Exemples pratiques

Créer l'espace de noms et les ressources

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 variables d'environnement sans exposer les secrets
kubectl -n cfgdemo exec deploy/app -- sh -c 'printenv | sort | grep -E "^(APP_MODE|FEATURE_FLAG|DB_USER)="'
# Vérifier l'existence de la variable secrète sans afficher sa valeur
kubectl -n cfgdemo exec deploy/app -- sh -c '[ -n "$DB_PASSWORD" ] && echo DB_PASSWORD est défini'

# Vérifier la présence des fichiers montés et afficher leurs tailles au lieu du 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 la ConfigMap et observer le comportement

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

# Les fichiers montés issus de la ConfigMap se rafraîchissent peu après ; vérifier le contenu du fichier
kubectl -n cfgdemo exec deploy/app -- sh -c 'cat /etc/app/config/APP_MODE'

# Les variables d'environnement ne changent pas dans les Pods existants ; déclencher un rollout pour prendre en compte 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'

Faire pivoter 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 -

# Orienter le Deployment vers le nouveau Secret pour les variables d'environnement
kubectl -n cfgdemo set env deploy/app --from=secret/app-secret-v2 --keys=DB_USER,DB_PASSWORD --overwrite

# Mettre aussi à jour 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écurisées

Lister et décrire sans divulguer les données secrètes :

  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 les variables d'environnement et les fichiers dans le conteneur sans exposer les 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 fichier secret présent'

Uniquement lorsque c'est strictement nécessaire, décoder une seule clé dans une session terminal contrôlée :

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

Consulter les événements et les journaux 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 une ConfigMap pour des données sensibles
Correctif : placer les clés sensibles dans un Secret. Réserver les ConfigMaps aux réglages non sensibles.
S'attendre à ce que les variables d'environnement se mettent à jour sans redéploiement
Correctif : redémarrer le Deployment après avoir modifié les ConfigMaps ou Secrets référencés via env/envFrom.
S'attendre à des mises à jour instantanées des fichiers depuis les volumes
Fait : les fichiers montés issus de ConfigMap et Secret se rafraîchissent peu après la modification (≈10 s). Les applications qui mettent en cache doivent recharger leur configuration.
Erreurs de frappe dans les noms de clés entre la ressource et la spec du Pod
Correctif : croiser les clés avec kubectl describe et printenv à l'intérieur du Pod.
Mauvais espace de noms
Correctif : passer -n à kubectl ou définir un espace de noms par défaut pour le contexte.
Confusion base64 lors de l'écriture de YAML brut
Correctif : privilégier kubectl create secret generic … qui gère l'encodage. Si édition manuelle, utiliser echo -n 'valeur' | base64 pour éviter les sauts de ligne.
Surprises de permissions sur les fichiers
Fait : les fichiers Secret sont en lecture seule par défaut. Si l'application a besoin d'un accès en lecture groupe, définir fsGroup sur le Pod ou defaultMode sur le volume.
Blocs trop volumineux dans les ConfigMaps/Secrets
Correctif : rester sous les limites habituelles (1 MiB) et stocker les gros artefacts ailleurs (système de fichiers ou objet store monté via un volume).

Comportement des rollouts 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 la modification de la ressource. L'application peut tout de même devoir recharger sa configuration.
Les Deployments ne redéploient pas automatiquement lors de changements de ressources externes. Seuls les changements du template de Pod déclenchent un nouveau ReplicaSet.
Pour forcer un rollout quand la configuration change, deux options :
Redémarrer manuellement : kubectl rollout restart deploy/<nom>
Utiliser un patron d'annotation checksum afin que tout changement de ConfigMap/Secret modifie le template du Pod et déclenche un rollout.

Exemple de checksum (shell 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 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 des rollouts dans un espace de noms sandbox avec un rayon d'impact minimal.

Périmètre :

Un espace de noms (cfgdemo), une ConfigMap, un Secret, un Deployment avec 1 replica.
Câblage à la fois via variables d'environnement et volumes pour comparer les comportements.

Étapes :

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

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

Modifier une clé de la ConfigMap ; confirmer :

le fichier monté se rafraîchit
la variable d'environnement ne change pas avant redémarrage

Redémarrer le Deployment ; confirmer la variable d'environnement mise à jour.
Faire pivoter le Secret en changeant le nom du Secret et en redéployant.
Ajouter les annotations checksum et réappliquer après chaque changement de configuration ; confirmer le rollout automatique.

Critères de sortie :

Vous pouvez démontrer en quelques minutes chacun des points suivants :
Les variables d'environnement nécessitent un redémarrage pour se mettre à jour.
Les fichiers montés se mettent à jour sans rollout.
Le redémarrage rollout ou les annotations checksum propagent les changements de façon prévisible.

Conclusion

Les ConfigMaps et les Secrets permettent de séparer la configuration du code tout en protégeant les valeurs sensibles. En pratique, validez à la fois le câblage par variables d'environnement et par volumes, sachez quand un redémarrage est requis, et privilégiez des commandes de dépannage sûres qui évitent d'exposer les secrets. Commencez par un petit pilote, observez comment les mises à jour se propagent, puis adoptez une méthode de rollout reproductible telle que les annotations checksum. Avec ces patterns en place, les équipes peuvent modifier la configuration en toute confiance et résoudre les incidents rapidement.