Kubernetes ConfigMaps and Secrets: envFrom, Volume Mounts, and Immutability
Environment variables never update, mounted files do (after a minute), and subPath mounts never do. Plus the Secret types, the missing-key failures, and where credentials leak.

Quick Summary
ConfigMaps hold non-secret configuration; Secrets hold data that should be handled more carefully. Both are namespaced API objects of key-value pairs, both can be mounted as files or injected as environment variables, and both are limited to 1 MiB because their content lives in etcd. The difference is intent plus a little enforcement: Secrets are base64-encoded (which is encoding, not encryption), can be restricted through RBAC, are mounted from memory-backed volumes, and are encrypted at rest only if the cluster's EncryptionConfiguration says so.
There are three ways to consume either object, and they behave differently at runtime. env.valueFrom injects one key and is never updated after the container starts. envFrom injects all keys (optionally with a prefix) and has the same limitation. A volume mount creates one file per key and is updated eventually — on the order of a minute, after the kubelet's sync and the API server's watch cache catch up — except when mounted with subPath, which is not updated at all.
immutable: true freezes an object: no updates, less API server and kubelet load, and the only way to change it is to create a new one and point the workload at it. This guide covers the three consumption forms, the update semantics that trip people up, Secret types and their expected keys, the ImagePullBackOff-class failures a missing key causes, and the practices that keep credentials out of kubectl describe output.
Basic Syntax & Core Signatures
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
data:
LOG_LEVEL: info
app.yaml: |
server:
port: 8080
binaryData:
logo.png: iVBORw0KGgoAAAANSUhEUg... # base64
immutable: trueapiVersion: v1
kind: Secret
metadata:
name: app-secret
type: Opaque
stringData: # plaintext here; merged into data by the API server
DATABASE_URL: postgres://app:s3cret@db:5432/app
data: # base64 in manifests and in `kubectl get -o yaml`
API_KEY: c2VjcmV0LWtleQ==
immutable: true# Consumption: single keys as env
env:
- name: LOG_LEVEL
valueFrom:
configMapKeyRef: { name: app-config, key: LOG_LEVEL }
- name: DATABASE_URL
valueFrom:
secretKeyRef: { name: app-secret, key: DATABASE_URL, optional: false }
# All keys from both objects
envFrom:
- configMapRef: { name: app-config, optional: false }
- secretRef: { name: app-secret }
- configMapRef: { name: app-config-extra, prefix: EXTRA_ }
# Mount as files: one file per key, whole object
volumes:
- name: config
configMap: { name: app-config, defaultMode: 0444 }
- name: secrets
secret: { secretName: app-secret, defaultMode: 0400 }
volumeMounts:
- { name: config, mountPath: /etc/app, readOnly: true }
# One key as one file, custom path, custom mode
volumes:
- name: tls
secret:
secretName: api-tls
items:
- key: tls.crt
path: server.crt
mode: 0400# Create without writing YAML
kubectl create configmap app-config --from-file=./config --from-literal=LOG_LEVEL=info
kubectl create secret generic app-secret --from-literal=DATABASE_URL='postgres://...'
kubectl create secret docker-registry regcred --docker-server=ghcr.io \
--docker-username=bot --docker-password="$TOKEN"
# Inspect (base64) and decode individual keys
kubectl get secret app-secret -o jsonpath='{.data.API_KEY}' | base64 -d; echo
kubectl describe secret app-secret # keys and sizes only, no values
# After changing a ConfigMap, env vars do not follow: restart deliberately
kubectl rollout restart deployment/apiKey Comparison Table
| Consumption | Updates at runtime | Failure if key missing | Notes |
|---|---|---|---|
env.valueFrom | No | Pod stuck CreateContainerConfigError unless optional: true | One key |
envFrom | No | Pod starts without it if optional: true | Invalid keys skipped with an event |
| Volume mount | Yes, after ~1 minute | Pod stuck mounting, unless optional: true | One file per key |
Volume with subPath | No | Same | Known limitation: not watched |
| Projected volume | Yes, like a mount | Same | Combine ConfigMap, Secret, downward API, SA token |
| Secret type | Required keys | Used for |
|---|---|---|
Opaque | Any | General credentials |
kubernetes.io/tls | tls.crt, tls.key | Ingress TLS |
kubernetes.io/dockerconfigjson | .dockerconfigjson | imagePullSecrets |
kubernetes.io/basic-auth | username, password | Basic auth conventions |
kubernetes.io/ssh-auth | ssh-privatekey | Git over SSH |
kubernetes.io/service-account-token | (managed) | Long-lived SA tokens (legacy) |
| Command | Effect |
|---|---|
kubectl get cm | List ConfigMaps |
kubectl describe cm app-config | Keys and values in plaintext |
kubectl get secret -o jsonpath='{.data.K}' | base64 -d | Decode one value |
kubectl create cm --from-file=dir/ | One key per file in the directory |
kubectl get cm app-config -o yaml | Full manifest with data |
Practical Edge Cases & Deep Dives
1. CreateContainerConfigError: a missing key with no optional
$ kubectl get pod api-1
NAME READY STATUS RESTARTS AGE
api-1 0/1 CreateContainerConfigError 0 3m
$ kubectl describe pod api-1 | grep -A2 'Error:'
Error: couldn't find key DATABASE_URL in Secret default/app-secretThe pod is scheduled and the kubelet refuses to create the container, so there is nothing to exec into and no application log. Either the key is spelled differently (DATABASE_URL versus database_url), the Secret is in another namespace, or the Secret exists but envFrom and valueFrom disagree about which object holds it. optional: true converts this into a start-without-it situation, which is right for genuinely optional tuning values and wrong for required credentials — a pod starting without its database URL fails later and less clearly.
2. Changing a ConfigMap does not change a running pod's environment
$ kubectl edit cm app-config # LOG_LEVEL: debug
$ kubectl exec deploy/api -- printenv LOG_LEVEL
info # unchangedEnvironment variables are set when the container process is created. The API server's new value exists, the pod's spec still references the object, and nothing in between reconciles them. The options are a rollout (kubectl rollout restart, which recreates pods with the new environment) or a mounted file, which the kubelet does refresh. This is the main reason the "mount config as a file and reload on SIGHUP" pattern survives: a file-mounted ConfigMap updates within roughly a minute (kubelet sync period plus API cache propagation), and the application decides when to re-read it.
kubectl get cm app-config -o jsonpath='{.data.LOG_LEVEL}'
kubectl exec deploy/api -- cat /etc/app/LOG_LEVEL3. subPath mounts never update, and the Helm trap
volumeMounts:
- name: config
mountPath: /etc/app/app.yaml
subPath: app.yaml # mounts one file, and it will NOT be refreshedsubPath exists because mounting a whole directory over an existing one hides the image's contents (and mounting over /etc breaks DNS). But a subPath mount is resolved once at container start; the projected-volume update mechanism does not reach it. The trade-off is explicit: subPath for files that must sit at a precise path and rarely change (a TLS certificate that triggers a restart anyway), a plain mount for configuration that must reload.
A related trap: mounting a ConfigMap at /etc/nginx/conf.d hides whatever nginx's image already had there; the mount replaces the directory. Use items to control file names, or mount at a different path and include the files from the image's own config.
4. Secret values in the place you did not expect
$ kubectl describe pod api-1 | grep -i env
DATABASE_URL: <set to the key 'DATABASE_URL' in secret 'app-secret'> # safe
$ kubectl get secret app-secret -o yaml # base64, readable by anyone with get secrets
$ kubectl exec deploy/api -- cat /proc/1/environ | tr '\0' '\n' | grep DATABASE
DATABASE_URL=postgres://app:s3cret@db:5432/app # plaintext in the process environmentdescribe protects secret values but not config values, and every process that receives a secret as an environment variable exposes it to ps e, /proc/<pid>/environ, crash dumps, and child processes that inherit it. A mounted file has narrower exposure (mode-controlled, memory-backed) but is still readable inside the container. The real protections are RBAC (get/list on Secrets is effectively read-all), encryption at rest in etcd, and not storing long-lived credentials in Kubernetes objects at all — external secret operators, sealed secrets, or workload identity are the durable answers.
5. envFrom and keys that are not valid variable names
$ kubectl describe pod api-1 | grep -i event -A3
Warning InvalidVariableNames ... Skipped invalid env names: app.yaml, log-levelenvFrom injects every key as a variable, and a key such as app.yaml or log-level is not a legal shell identifier, so it is silently skipped and an event is emitted. envFrom also does not let you rename keys; prefix only prepends. When the object mixes configuration files and variables, split it: one ConfigMap for variables consumed by envFrom, one for files consumed by a mount.
6. Immutability as an operational tool
$ kubectl patch cm app-config -p '{"data":{"LOG_LEVEL":"debug"}}'
The ConfigMap "app-config" is immutable: you may only edit labels and annotationsimmutable: true prevents accidental edits to objects that pods depend on, and reduces the kubelet's watch load on clusters with thousands of them. The workflow becomes versioned: create app-config-v2, update the Deployment's reference, roll out, and delete the old one when no pod uses it. That matches how a reviewed configuration change should work, and it makes a rollback a one-line reference change instead of an in-place edit nobody recorded.
Common Runtime & Configuration Mistakes
| Symptom | Cause | Fix |
|---|---|---|
CreateContainerConfigError | Missing key without optional | Create the key or the object; check the namespace |
| Pod starts without a required value | optional: true used too broadly | Remove optional for required values |
| Changed ConfigMap has no effect on env | Env is fixed at container start | kubectl rollout restart |
| Mounted file not updated | subPath mount | Use a whole-volume mount |
| Mounted file updates but app ignores it | App reads config once | Reload on SIGHUP or watch the file |
| Environment variable missing with no error | Invalid key name in envFrom | Rename the key; check InvalidVariableNames events |
ImagePullBackOff on a private registry | No imagePullSecrets, or wrong Secret type | kubectl create secret docker-registry, reference it |
| TLS Secret rejected | Not type kubernetes.io/tls, or keys misnamed | tls.crt/tls.key, correct type |
| Secret appears garbled | Base64 is not encryption; value double-encoded | base64 -d, or stringData on create |
| ConfigMap apply rejected | Over 1 MiB | Split it, or mount a real volume |
Secret visible in kubectl get pods -o yaml? | It is a reference, not a value | Values only appear with get secret |
| Cannot patch an object at all | immutable: true | Create a new versioned object |
ConfigMaps and Secrets are configuration delivery, not configuration management: they carry values to pods through a channel with precise update rules (env never, file eventually, subPath never), and their security properties come from the cluster around them — RBAC on Secrets, encryption at rest, and the discipline of keeping long-lived credentials out of etcd entirely.
Try matching browser tools
All toolsSmall utilities that fit Kubernetes work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Kubernetes guides
All Kubernetes guideskubectl Output: jsonpath, custom-columns, and the Debugging Commands Worth Knowing
jsonpath for one value in a script, custom-columns for tables people read, and kubectl debug when the container has no shell. Includes the three quoting layers that break jsonpath.
Kubernetes Namespaces, ResourceQuotas, and LimitRanges
A namespace is only a boundary when quota and limit range make it one. Aggregate caps, per-pod defaults, the admission errors they produce, and namespaces stuck Terminating.
Kubernetes StatefulSets: Ordinal Identities, Headless Services, and PVC Lifecycle
Why each StatefulSet pod keeps a name, a DNS record, and its own PVC; how OrderedReady gates startup on readiness; and how partition-based updates canary a single quorum member.
Kubernetes securityContext, Capabilities, and Pod Security Standards
The five fields that remove most container escapes, which of them only exist at container level, and how the restricted profile enforces the same settings at admission.
More in Kubernetes
All Kubernetes guidesThe guides filed next to this one in Kubernetes, in library order.