How to Mount a ConfigMap in a Pod
A ConfigMap holds your app's config data, but it doesn't appear inside the container until you wire it in with two YAML blocks - volumes on the pod spec and volumeMounts on the container. Miss either block and the file simply isn't there.
Why the file isn't in the container
A ConfigMap existing in the namespace is not enough. Kubernetes only writes its
keys to the container's filesystem when the Deployment (or Pod) spec explicitly
mounts it. Without the mount, cat /etc/config/app.conf fails with
No such file or directory, and a container that tries to read that file at
startup will crash-loop.
Check whether the mount is wired in:
kubectl describe pod -l app=worker # look for "Mounts" under the container
kubectl logs -l app=worker --previous # read the crash reason
The two-block pattern
Mounting a ConfigMap always takes exactly two blocks - one on the pod spec
(volumes) and one on the container (volumeMounts):
apiVersion: apps/v1
kind: Deployment
metadata:
name: worker
spec:
template:
spec:
containers:
- name: worker
image: busybox:1.36
command: ["sh", "-c", "cat /etc/config/app.conf && sleep 3600"]
volumeMounts:
- name: config # must match the volumes[].name below
mountPath: /etc/config # directory inside the container
volumes:
- name: config
configMap:
name: app-config # the ConfigMap that must exist in the namespace
kubectl apply -f deployment.yaml followed by kubectl rollout status deploy/worker
confirms the pod reaches Running and the file is readable.
Useful variations
Mount a single key as a file - use subPath when you only need one key and
don't want it to replace an entire directory:
volumeMounts:
- name: config
mountPath: /etc/app/app.conf # full file path, not a directory
subPath: app.conf # the key name inside the ConfigMap
Read-only mount - add readOnly: true on the volumeMount so the container
can't accidentally overwrite its own config:
volumeMounts:
- name: config
mountPath: /etc/config
readOnly: true
Live reload - ConfigMap changes propagate to mounted files automatically (kubelet syncs every ~60 s). The app still needs to re-read the file; a process that only reads config at startup won't see the update without a restart.
Secrets use the same pattern
The identical two-block structure mounts Secrets, downward-API volumes, and
EmptyDir volumes - the only difference is the volume source (secret:, downwardAPI:,
emptyDir:). Learning the ConfigMap pattern covers all of them.
Want to try it hands-on? HeyDevJob gives you this exact setup in a live cloud workspace in your browser - edit it, run it, and see it work. Free, nothing to install.
Try it in a workspace →What you'll practice
- Adding volumes + volumeMounts blocks to wire a ConfigMap into a pod
- Using kubectl describe and kubectl logs to diagnose a missing mount
- Mounting a single ConfigMap key with subPath and locking mounts read-only
FAQ
How do I mount a ConfigMap as a file in a Kubernetes pod?
Add a volumes block to the pod spec referencing the ConfigMap name, then add a volumeMounts block on the container pointing to the directory where the files should appear. Both blocks are required - one alone does nothing.
Why is my ConfigMap not showing up inside the container?
The ConfigMap exists in the namespace but isn't mounted. You must add a volumes entry (specifying configMap.name) and a volumeMounts entry (specifying mountPath) to the Deployment spec, then apply it. Run kubectl describe pod to confirm the mount appears under the container's Mounts section.
How do I mount a single ConfigMap key as a file without replacing a directory?
Use subPath - set mountPath to the full target file path (e.g. /etc/app/app.conf) and set subPath to the key name. This places just that key at that path without hiding other files in the same directory.
Keep learning
Learn it by doing. Open this in a live cloud workspace, make the change yourself, and keep a record of the work you can share.
Open the workspace →