Containers and Kubernetes · Intermediate · 17 min
How to Configure a Kubernetes App with ConfigMaps and Secrets
By Padding · Updated 15 Nov 2026
Kubernetes 1.37
You will keep settings and credentials out of your container image by passing them to a Kubernetes 1.37 Deployment as environment variables and as mounted files, update them without rebuilding, and learn what a Secret does and does not protect.
On this page
An image should be the same in every environment. What changes between your laptop, a test cluster and production is configuration: a log level, a feature flag, a database address, a password. Baking those into the image means a rebuild for each change, and puts credentials where anyone who can pull the image can read them.
Kubernetes keeps configuration in two objects of its own. A ConfigMap holds non-secret settings. A Secret holds sensitive values. Both are handed to pods when they start, as environment variables or as files. This tutorial uses both, and ends with an honest account of what a Secret protects. It is the last tutorial in the series From Docker to Kubernetes.
Step 1 · Start a cluster
Create a fresh cluster, so that nothing from earlier tutorials interferes:
kind create cluster --name config --image kindest/node:v1.37.0 --wait 120s
kubectl get nodesThe one node, config-control-plane, is Ready.
Step 2 · Create a ConfigMap
A ConfigMap is a set of keys and values. Create one from literal values:
kubectl create configmap app-config \
--from-literal=GREETING="Hello from a ConfigMap" \
--from-literal=LOG_LEVEL=info
kubectl get configmap app-config -o yamlThe YAML output has a data: section with your two keys. You can also build a ConfigMap from a whole file. The file name becomes the key and the contents become the value. Write a page and load it:
cat > index.html <<'HTML'
<h1>Version 1</h1>
HTML
kubectl create configmap site-content --from-file=index.html
kubectl describe configmap site-contentA ConfigMap is limited to 1 MiB in total. Use it for settings and small files, not for data.
Step 3 · Use the ConfigMap in a Deployment
The Deployment below uses the ConfigMaps in both ways:
envFromturns every key ofapp-configinto an environment variable.- A
volumeof typeconfigMapshows the keys ofsite-contentas files in a folder, andvolumeMountsplaces that folder inside the container. Here it replaces Nginx's web root, so Nginx serves yourindex.html.
cat > deployment.yaml <<'YAML'
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
spec:
replicas: 1
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: nginx
image: nginx:1.30-alpine
ports:
- containerPort: 80
envFrom:
- configMapRef:
name: app-config
volumeMounts:
- name: site
mountPath: /usr/share/nginx/html
readOnly: true
volumes:
- name: site
configMap:
name: site-content
YAML
kubectl apply -f deployment.yaml
kubectl rollout status deployment/web --timeout=120sCheck it worked
kubectl exec deployment/web -- printenv GREETING LOG_LEVEL
kubectl exec deployment/web -- wget -qO- http://localhost/The first command prints Hello from a ConfigMap and info. The second prints <h1>Version 1</h1>, the page from the ConfigMap.
Troubleshooting
- The pod is stuck in
ContainerCreatingandkubectl describe podsaysconfigmap "site-content" not found: a pod that mounts or references a ConfigMap waits for it to exist, and must be in the same namespace. Create the ConfigMap, and the pod starts. CreateContainerConfigError: the pod names a ConfigMap or a key that does not exist. Read the Events at the end ofkubectl describe pod <name>.- The page shows Nginx's default files instead of yours: a volume mounted at
/usr/share/nginx/htmlreplaces the folder's contents. If both appear missing, check the file name in the ConfigMap withkubectl describe configmap site-content.
Step 4 · Change a ConfigMap
The two ways of consuming a ConfigMap behave differently when you change it. Files in a mounted volume are updated in place, after a delay. Environment variables are fixed when the container starts and never change while it runs. To update the page, regenerate the ConfigMap from the edited file. The --dry-run=client -o yaml part prints the object instead of creating it, and kubectl apply replaces the existing one:
cat > index.html <<'HTML'
<h1>Version 2</h1>
HTML
kubectl create configmap site-content --from-file=index.html --dry-run=client -o yaml | kubectl apply -f -kubectl prints a warning that the ConfigMap is missing the kubectl.kubernetes.io/last-applied-configuration annotation. That is expected: the object was made with create, not apply, and the warning says that kubectl patches the annotation in by itself. It is harmless here.
The kubelet refreshes mounted ConfigMaps periodically, so the new page can take up to a minute or two to appear. Poll until it does, for up to two minutes:
for i in $(seq 1 24); do
if kubectl exec deployment/web -- wget -qO- http://localhost/ | grep -q "Version 2"; then
echo "page updated after about $((i*5)) seconds"; break
fi
sleep 5
done
kubectl exec deployment/web -- wget -qO- http://localhost/The page now says Version 2, and no pod was restarted. A file mounted with subPath is never updated this way, so avoid subPath for config that changes. Environment variables need a restart. Change a value and roll the pods:
kubectl patch configmap app-config --type merge -p '{"data":{"LOG_LEVEL":"debug"}}'
kubectl exec deployment/web -- printenv LOG_LEVEL
kubectl rollout restart deployment/web
kubectl rollout status deployment/web --timeout=120s
kubectl exec deployment/web -- printenv LOG_LEVELThe first printenv still prints info, and the second, after the restart, prints debug.
Step 5 · Add a Secret
A Secret is created and consumed like a ConfigMap, and its values are stored base64-encoded. Base64 is an encoding, not encryption. Do not type a password into a command, where it lands in your shell history and in the process list. Generate one into a file that only you can read. Create the file private first, then write into it. tr -d '\n' keeps a trailing newline out of the value:
install -m 600 /dev/null db-password.txt
openssl rand -hex 16 | tr -d '\n' >> db-password.txt
kubectl create secret generic db-credentials --from-file=db-password=db-password.txtLook at what Kubernetes stored. The value is encoded, and one command decodes it for anyone who can read the Secret. To avoid printing the real value into your terminal, this prints only its length:
kubectl get secret db-credentials -o jsonpath='{.data.db-password}' | base64 -d | wc -cThe length is 32. Now mount the Secret as files instead of environment variables. Files are the better default: environment variables are inherited by every child process, appear in crash reports and debug dumps, and are easy to log by accident. A file has permissions you can set. Add the mount to the Deployment:
cat > deployment.yaml <<'YAML'
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
spec:
replicas: 1
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: nginx
image: nginx:1.30-alpine
ports:
- containerPort: 80
envFrom:
- configMapRef:
name: app-config
volumeMounts:
- name: site
mountPath: /usr/share/nginx/html
readOnly: true
- name: credentials
mountPath: /etc/secrets
readOnly: true
volumes:
- name: site
configMap:
name: site-content
- name: credentials
secret:
secretName: db-credentials
defaultMode: 0400
YAML
kubectl apply -f deployment.yaml
kubectl rollout status deployment/web --timeout=120sCheck it worked
kubectl exec deployment/web -- ls -lL /etc/secrets/
kubectl exec deployment/web -- sh -c 'wc -c < /etc/secrets/db-password'The listing shows db-password with mode -r-------- (the -L follows the symbolic link that Kubernetes uses for files in a Secret volume, so you see the file itself), and the byte count is 32. If your app runs as a non-root user, mode 0400 (owner read only) is owned by root and the app cannot read it. Set securityContext.fsGroup on the pod to the app's group ID and use defaultMode: 0440. Remember that you can always see the Secret from the command line, so delete the local copy of the password file:
rm db-password.txtWhat a Secret does and does not protect
- It keeps the value out of your image and out of the Deployment YAML, so the YAML can go in Git. Never write a Secret as a YAML file with the real value, whether in
dataas base64 or instringDataas plain text, and commit it. See/tutorials/keep-secrets-out-of-git. - Anyone who can read Secrets in the namespace, through
kubectl get secret -o yaml, can decode them. Limit that with RBAC (role-based access control), and give each app its own service account. - By default the cluster's database, etcd, stores Secrets unencrypted. Managed Kubernetes services usually encrypt etcd. If you run your own cluster, turn on encryption at rest (kubernetes.io/docs/tasks/administer-cluster/encrypt-data/).
- For anything serious, keep the source of truth in a secrets manager and sync it into the cluster with a tool made for that. That is a topic of its own.
Step 6 · Clean up
Delete the cluster, and with it every object you made:
kind delete cluster --name config
rm -f deployment.yaml index.htmlNext steps
- Review the earlier steps of the series from the Dockerfile, in
/tutorials/write-a-dockerfile-for-a-node-app. - Keep credentials out of your repositories:
/tutorials/keep-secrets-out-of-git. - The official guides are at kubernetes.io/docs/concepts/configuration/configmap/ and kubernetes.io/docs/concepts/configuration/secret/.
Related tutorials
- How to Keep Passwords and API Keys Out of GitYou will keep secrets in a git-ignored .env file, commit a safe template instead, stop a commit that contains a key with a pre-commit hook, and learn what to do when a secret has already been committed.
- How to Write a Dockerfile for a Node.js AppYou will write a Dockerfile for a small Express app on Node.js 26, build it into an image, run it as a container on port 3000 as a non-root user, and order the file so rebuilds take seconds.
Need this done for you?
Padding does this work for growing companies, from the first diagnosis to a system that keeps working.
Get new tutorials