ConfigMap — Decoupling Config from Container Images
What is a ConfigMap in Simple Terms?
Without ConfigMaps, every environment change (dev, staging, production) requires building a new Docker image. A ConfigMap lets you store config outside the image and inject it at runtime. Change the config, restart the pod — no new image needed.
How ConfigMap Fits Into a Deployment
◈ DIAGRAM
+-----------------------------+| Docker Image | <- baked once, never changes per env+-----------------------------+ | v+-----------------------------+| ConfigMap | <- env-specific values injected here| APP_ENV=production || LOG_LEVEL=info || REDIS_HOST=10.0.1.50 |+-----------------------------+ | v+-----------------------------+| Running Pod | <- sees config as env vars or files+-----------------------------+Creating a ConfigMap
Bash
1# Create from literal values2kubectl create configmap app-config \3 --from-literal=APP_ENV=production \4 --from-literal=LOG_LEVEL=info \5 --from-literal=REDIS_HOST=10.0.1.50 \6 -n production7 8# Create from a config file on disk9kubectl create configmap nginx-config \10 --from-file=nginx.conf \11 -n production12 13# View what was created14kubectl get configmap app-config -n production -o yamlUsing ConfigMap as Environment Variables
YAML
1# deployment.yaml — inject ConfigMap values as env vars2spec:3 containers:4 - name: api-server5 image: registry.razorpay.in/api-server:v2.4.16 envFrom:7 - configMapRef:8 name: app-config # Injects ALL keys as env vars at once9 env:10 - name: DB_HOST # Inject a single key selectively11 valueFrom:12 configMapKeyRef:13 name: app-config14 key: REDIS_HOSTUsing ConfigMap as a Mounted File
YAML
1# Mount nginx.conf from ConfigMap into the container filesystem2spec:3 volumes:4 - name: nginx-config-vol5 configMap:6 name: nginx-config # ConfigMap name to mount7 containers:8 - name: nginx9 image: nginx:1.2510 volumeMounts:11 - name: nginx-config-vol12 mountPath: /etc/nginx/nginx.conf13 subPath: nginx.conf # Mount only this key as a single fileInspecting and Updating ConfigMaps
Bash
1# List all ConfigMaps in a namespace2kubectl get configmaps -n production3 4# View contents of a specific ConfigMap5kubectl describe configmap app-config -n production6 7# Edit a ConfigMap in place8kubectl edit configmap app-config -n production9 10# Delete and recreate (common in CI/CD pipelines)11kubectl delete configmap app-config -n production12kubectl create configmap app-config --from-file=config/ -n production13 14# Force a rolling restart after ConfigMap update15kubectl rollout restart deployment/api-server -n productionTroubleshooting ConfigMap Issues
| Symptom | Likely Cause | Fix |
|---|---|---|
| Env var missing in pod | Wrong key name in configMapKeyRef |
kubectl describe configmap to verify exact key names |
| Old config still in pod | ConfigMap updated but pod not restarted | kubectl rollout restart deployment/<name> |
| Mounted file not updating | Volume mount caches aggressively | Restart pod or use Reloader controller |
| ConfigMap not found | Wrong namespace | Confirm ConfigMap and pod are in same namespace |
Bash
1# Verify env vars are correctly injected inside a running pod2kubectl exec -it <pod-name> -n production -- env | grep APP_ENV3 4# Check what keys exist in a ConfigMap before referencing them5kubectl get configmap app-config -n production -o jsonpath='{.data}' | jq⚠️ Security: Never store passwords, API keys, or tokens in a ConfigMap. ConfigMaps are stored as plain text in etcd and visible to anyone with cluster read access. Use Kubernetes Secrets or an external vault like HashiCorp Vault for sensitive values.
📌 Remember: Updating a ConfigMap does NOT automatically restart pods. Running pods continue using the old values in memory. You must either restart the deployment manually with kubectl rollout restart or use a controller like Reloader to watch ConfigMap changes and trigger rolling restarts automatically.💡 Tip: In Razorpay or Hotstar-scale clusters with dozens of services, manage ConfigMaps through Helmvalues.yamlfiles instead of manually withkubectl create. This keeps config versioned in Git and makes environment promotion (staging -> production) a controlled, auditable process.
🔴 Common Mistake: UsingenvFromto inject all ConfigMap keys globally, then not knowing which keys are available inside the pod. This causes hard-to-debug missing variable errors. Prefer explicitenv.valueFrom.configMapKeyRefentries for critical config values — it makes dependencies visible in the deployment spec.