A ConfigMap stores the non-sensitive configuration of an application (variables, files) outside the image. The same image then serves several environments, and you change the configuration without rebuilding it. In this lesson, you deploy an application whose variables APP_MODE and LOG_LEVEL and a configuration file come from a ConfigMap, you prove it from inside the container, then you modify the ConfigMap to see what changes by itself and what stays frozen.
Prerequisites: the demo cluster from First cluster and the lesson Deployments. All commands are typed in the default namespace, in a directory where you can create a file.
What you will learn
- Create a ConfigMap from literal values and from a file
- Inject a ConfigMap into a Pod as environment variables and as a mounted file
- Prove from inside the container what the application receives
- Predict what changes and what stays frozen after a ConfigMap is modified
- Diagnose a Pod blocked by a missing ConfigMap or key
What is a ConfigMap, and when should you prefer a Secret?
A ConfigMap is a Kubernetes object that holds key-value pairs. A value can be short (production) or be the entire content of a file. All values are strings: write "100", not 100, in a manifest.
How do you create a ConfigMap?
Create two ConfigMaps for two uses. The first, app-config, holds two variables; the second, app-fichier, holds the content of a configuration file. The kubectl create configmap command accepts a literal value (--from-literal) or a file (--from-file), whose name becomes the key:
kubectl create configmap app-config --from-literal=APP_MODE=production --from-literal=LOG_LEVEL=infocat > app.properties <<'EOF'mode=productionregion=eu-westEOFkubectl create configmap app-fichier --from-file=app.propertieskubectl get configmap app-config app-fichierkubectl describe configmap app-fichierconfigmap/app-config createdconfigmap/app-fichier createdNAME DATA AGEapp-config 2 0sapp-fichier 1 0sName: app-fichierNamespace: defaultLabels: <none>Annotations: <none>
Data====app.properties:----mode=productionregion=eu-west
BinaryData====
Events: <none>The DATA column counts the keys: 2 for app-config, 1 for app-fichier. The app-fichier ConfigMap has a single key, app.properties, which describe shows with the whole content of the file. To see the object as Kubernetes stores it, that is, the YAML equivalent you would write in a manifest:
kubectl get configmap app-config -o yamlapiVersion: v1data: APP_MODE: production LOG_LEVEL: infokind: ConfigMapmetadata: creationTimestamp: "2026-11-11T07:07:22Z" name: app-config namespace: default resourceVersion: "638" uid: 29d9b00f-bead-4805-893d-e24d9e24803aThe values sit under the data field, and the cluster added the metadata fields (creation date, uid, resourceVersion), which you never write in a manifest. Another field, binaryData, exists for binary data encoded in base64: you will almost never need it.
How do you inject a ConfigMap into a Pod?
A container receives a ConfigMap in two ways. With envFrom, each key becomes an environment variable. With a volume of type configMap, each key becomes a file in a mounted folder. To inject a single key as a variable, the env field with configMapKeyRef also exists.
The app Deployment below uses the first two ways: the variables come from app-config, the file from app-fichier, mounted in /etc/app. It also mounts the same file a second time with subPath, an option that mounts one specific file of the volume instead of the whole folder. You will compare the two mounts below.
kubectl apply -f - <<'EOF'apiVersion: apps/v1kind: Deploymentmetadata: name: appspec: replicas: 1 selector: matchLabels: app: app template: metadata: labels: app: app spec: containers: - name: app image: busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4 command: ["sleep", "3600"] envFrom: - configMapRef: name: app-config volumeMounts: - name: fichier mountPath: /etc/app - name: fichier mountPath: /etc/app-fige/app.properties subPath: app.properties volumes: - name: fichier configMap: name: app-fichierEOFkubectl rollout status deployment/appdeployment.apps/app createdWaiting for deployment "app" rollout to finish: 0 of 1 updated replicas are available...deployment "app" successfully rolled outProve what the application receives by reading from inside the container. The deploy/app notation saves you from looking for the Pod name, which Kubernetes generates:
kubectl exec deploy/app -- printenv APP_MODE LOG_LEVELkubectl exec deploy/app -- ls /etc/appkubectl exec deploy/app -- cat /etc/app/app.propertiesproductioninfoapp.propertiesmode=productionregion=eu-westThe two variables and the file match the content of the ConfigMaps. The application itself does not know where these values come from: it reads an ordinary variable and an ordinary file.
What happens when you modify the ConfigMap?
Modify both ConfigMaps, app-config (the LOG_LEVEL variable) and app-fichier (the file), then immediately read the variable again:
kubectl patch configmap app-config --type merge -p '{"data":{"LOG_LEVEL":"debug"}}'cat > app.properties <<'EOF'mode=maintenanceregion=eu-westEOFkubectl create configmap app-fichier --from-file=app.properties --dry-run=client -o yaml | kubectl apply -f -kubectl exec deploy/app -- printenv LOG_LEVELconfigmap/app-config patchedWarning: resource configmaps/app-fichier is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically.configmap/app-fichier configuredinfoThe ConfigMap changed, but the container still shows info: an environment variable is read when the container starts and never moves afterwards.
The warning Warning: resource configmaps/app-fichier is missing the ... last-applied-configuration annotation is harmless here: app-fichier was created by kubectl create, and kubectl apply adds the missing annotation itself.
The mounted file behaves differently: Kubernetes updates it without a restart, but with a delay, which depends on the synchronization of the kubelet (the agent that runs on each node). The following loop waits for the change instead of betting on a duration, then compares the file mounted as a folder with the one mounted through subPath:
for i in $(seq 1 90); do kubectl exec deploy/app -- cat /etc/app/app.properties | grep -q 'mode=maintenance' && break; sleep 2; donekubectl exec deploy/app -- cat /etc/app/app.propertieskubectl exec deploy/app -- cat /etc/app-fige/app.propertiesmode=maintenanceregion=eu-westmode=productionregion=eu-westThe file mounted as a folder changed, the one mounted with subPath stayed frozen. Remember the result: a ConfigMap volume refreshes by itself; a subPath mount and environment variables never refresh.
For the variables to take the new value, restart the Deployment: it replaces its Pod, and the new one reads the up-to-date ConfigMaps.
kubectl rollout restart deployment/appkubectl rollout status deployment/appkubectl exec deploy/app -- printenv LOG_LEVELkubectl exec deploy/app -- cat /etc/app-fige/app.propertiesdeployment.apps/app restartedWaiting for deployment "app" rollout to finish: 1 old replicas are pending termination...Waiting for deployment "app" rollout to finish: 1 old replicas are pending termination...deployment "app" successfully rolled outdebugmode=maintenanceregion=eu-westAfter the restart, the variable is debug and the subPath file returns mode=maintenance, the new content. The table below summarizes the rule to remember:
| Injection | Updates without a restart? |
|---|---|
Environment variable (env, envFrom) | No, the Pod must be replaced |
| Volume mounted as a folder | Yes, with a delay |
Volume mounted with subPath | No, the Pod must be replaced |
How do you prevent a ConfigMap from being modified?
A ConfigMap marked immutable: true refuses any change to its data. It protects against an accidental modification, and it relieves Kubernetes from watching it for changes. Create one, then try to modify it. The error is intended, and its message says why: the data field is immutable as soon as immutable is set:
kubectl apply -f - <<'EOF'apiVersion: v1kind: ConfigMapmetadata: name: app-config-v1data: APP_MODE: productionimmutable: trueEOFkubectl patch configmap app-config-v1 --type merge -p '{"data":{"APP_MODE":"staging"}}'configmap/app-config-v1 createdThe ConfigMap "app-config-v1" is invalid: data: Forbidden: field is immutable when `immutable` is setTo change the configuration, create a new ConfigMap with a versioned name (app-config-v2), point the Deployment to it, then delete the old one once no Pod uses it anymore.
How do you diagnose a missing ConfigMap?
When the ConfigMap or the key that a Pod references does not exist, the Pod does not start: it stays in CreateContainerConfigError. Trigger it with a Pod that asks for a key absent from app-config:
kubectl apply -f - <<'EOF'apiVersion: v1kind: Podmetadata: name: cassespec: containers: - name: casse image: busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4 command: ["sleep", "3600"] env: - name: APP_MODE valueFrom: configMapKeyRef: name: app-config key: MODE_ABSENTEOFkubectl wait --for=jsonpath='{.status.containerStatuses[0].state.waiting.reason}'=CreateContainerConfigError pod/casse --timeout=60skubectl get pod cassekubectl get pod casse -o jsonpath='{.status.containerStatuses[0].state.waiting.message}'pod/casse createdpod/casse condition metNAME READY STATUS RESTARTS AGEcasse 0/1 CreateContainerConfigError 0 4scouldn't find key MODE_ABSENT in ConfigMap default/app-configThe message couldn't find key MODE_ABSENT in ConfigMap default/app-config says exactly what is missing: the ConfigMap itself, or a specific key in a ConfigMap that exists. Compare it with kubectl describe configmap app-config, which lists the real keys.
For a truly optional configuration, the optional: true field allows Kubernetes to start the Pod without it. The price to pay: a typo in the name no longer produces any error, and the application starts with its default values.
Two other cases occur. The Pod starts but a variable is missing: the reference carries optional: true, or the Pod uses envFrom and the key does not have the expected name, since envFrom creates one variable per key under its exact name. A file does not update: check whether the volume is mounted with subPath.
How do you clean up the cluster?
Clean up what you created: the Deployment, the casse Pod, the three ConfigMaps and the local app.properties file.
kubectl delete deployment appkubectl delete pod cassekubectl delete configmap app-config app-fichier app-config-v1rm app.propertiesdeployment.apps "app" deleted from default namespacepod "casse" deleted from default namespaceconfigmap "app-config" deleted from default namespaceconfigmap "app-fichier" deleted from default namespaceconfigmap "app-config-v1" deleted from default namespacePut it into practice
The guided lab repeats the demonstration of the lesson, with its names and values, in the configuration namespace of a kind cluster that is empty at the start: add -n configuration to your kubectl commands. You create app-config (with APP_MODE=production and LOG_LEVEL=info) and app-fichier (with the app.properties file), then an app Deployment that reads the variables from the first and mounts the second as a folder on /etc/app. You then switch LOG_LEVEL to debug and the file to mode=maintenance, then you make the variables pick up the new value with a kubectl rollout restart. The validation reads the values inside the Pod and rejects a value hard-coded in the Deployment, as well as a Pod deleted by hand instead of the restart.
Key takeaways
- A ConfigMap stores non-sensitive configuration in clear text; sensitive data goes in a Secret.
- All values are strings: write
"100", never100. - A ConfigMap is injected as variables (
env,envFrom) or as files (volume). - Environment variables are never refreshed: only replacing the Pod updates them.
- A ConfigMap volume mounted as a folder refreshes by itself, with a delay.
- A
subPathmount never refreshes. - A missing ConfigMap or key blocks the Pod in
CreateContainerConfigError, andkubectl get pod -o jsonpathgives the message. immutable: trueforbids modification: the new configuration goes through a new ConfigMap with a versioned name.
Test your knowledge
Seven questions on the points that are costly in production: what refreshes by itself, what never refreshes, and what the API refuses.
Knowledge check
Check what you have learned with this interactive quiz
How it works
- The timer starts when you click Start
- Multiple choice, true/false and short answer questions
- You can move between questions
- Detailed results are shown at the end
Starts the quiz and the timer
Review
(0/0)Score by domain
A domain groups several guides and gets several questions, so its score is more reliable than a per-topic score, which often rests on a single question.
Summary
Strengths
No topic passed at 80% on at least two questions yet.
Weak areas
No topic below the pass mark.
Recommended next
Hints before you try again?
Continue the course: Kubernetes Secrets: store sensitive data
A new full quiz with random questions
Work again only on the questions you missed