Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français

Kubernetes ConfigMaps: manage your application configuration

By updated

Improve this page

Logo Kubernetes

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:

Terminal window
kubectl create configmap app-config --from-literal=APP_MODE=production --from-literal=LOG_LEVEL=info
cat > app.properties <<'EOF'
mode=production
region=eu-west
EOF
kubectl create configmap app-fichier --from-file=app.properties
kubectl get configmap app-config app-fichier
kubectl describe configmap app-fichier
configmap/app-config created
configmap/app-fichier created
NAME DATA AGE
app-config 2 0s
app-fichier 1 0s
Name: app-fichier
Namespace: default
Labels: <none>
Annotations: <none>
Data
====
app.properties:
----
mode=production
region=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:

Terminal window
kubectl get configmap app-config -o yaml
apiVersion: v1
data:
APP_MODE: production
LOG_LEVEL: info
kind: ConfigMap
metadata:
creationTimestamp: "2026-11-11T07:07:22Z"
name: app-config
namespace: default
resourceVersion: "638"
uid: 29d9b00f-bead-4805-893d-e24d9e24803a

The 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.

Terminal window
kubectl apply -f - <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
name: app
spec:
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-fichier
EOF
kubectl rollout status deployment/app
deployment.apps/app created
Waiting for deployment "app" rollout to finish: 0 of 1 updated replicas are available...
deployment "app" successfully rolled out

Prove 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:

Terminal window
kubectl exec deploy/app -- printenv APP_MODE LOG_LEVEL
kubectl exec deploy/app -- ls /etc/app
kubectl exec deploy/app -- cat /etc/app/app.properties
production
info
app.properties
mode=production
region=eu-west

The 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:

Terminal window
kubectl patch configmap app-config --type merge -p '{"data":{"LOG_LEVEL":"debug"}}'
cat > app.properties <<'EOF'
mode=maintenance
region=eu-west
EOF
kubectl create configmap app-fichier --from-file=app.properties --dry-run=client -o yaml | kubectl apply -f -
kubectl exec deploy/app -- printenv LOG_LEVEL
configmap/app-config patched
Warning: 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 configured
info

The 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:

Terminal window
for i in $(seq 1 90); do kubectl exec deploy/app -- cat /etc/app/app.properties | grep -q 'mode=maintenance' && break; sleep 2; done
kubectl exec deploy/app -- cat /etc/app/app.properties
kubectl exec deploy/app -- cat /etc/app-fige/app.properties
mode=maintenance
region=eu-west
mode=production
region=eu-west

The 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.

Terminal window
kubectl rollout restart deployment/app
kubectl rollout status deployment/app
kubectl exec deploy/app -- printenv LOG_LEVEL
kubectl exec deploy/app -- cat /etc/app-fige/app.properties
deployment.apps/app restarted
Waiting 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 out
debug
mode=maintenance
region=eu-west

After the restart, the variable is debug and the subPath file returns mode=maintenance, the new content. The table below summarizes the rule to remember:

InjectionUpdates without a restart?
Environment variable (env, envFrom)No, the Pod must be replaced
Volume mounted as a folderYes, with a delay
Volume mounted with subPathNo, 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:

Terminal window
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config-v1
data:
APP_MODE: production
immutable: true
EOF
kubectl patch configmap app-config-v1 --type merge -p '{"data":{"APP_MODE":"staging"}}'
configmap/app-config-v1 created
The ConfigMap "app-config-v1" is invalid: data: Forbidden: field is immutable when `immutable` is set

To 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:

Terminal window
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
name: casse
spec:
containers:
- name: casse
image: busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4
command: ["sleep", "3600"]
env:
- name: APP_MODE
valueFrom:
configMapKeyRef:
name: app-config
key: MODE_ABSENT
EOF
kubectl wait --for=jsonpath='{.status.containerStatuses[0].state.waiting.reason}'=CreateContainerConfigError pod/casse --timeout=60s
kubectl get pod casse
kubectl get pod casse -o jsonpath='{.status.containerStatuses[0].state.waiting.message}'
pod/casse created
pod/casse condition met
NAME READY STATUS RESTARTS AGE
casse 0/1 CreateContainerConfigError 0 4s
couldn't find key MODE_ABSENT in ConfigMap default/app-config

The 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.

Terminal window
kubectl delete deployment app
kubectl delete pod casse
kubectl delete configmap app-config app-fichier app-config-v1
rm app.properties
deployment.apps "app" deleted from default namespace
pod "casse" deleted from default namespace
configmap "app-config" deleted from default namespace
configmap "app-fichier" deleted from default namespace
configmap "app-config-v1" deleted from default namespace

Put 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

  1. A ConfigMap stores non-sensitive configuration in clear text; sensitive data goes in a Secret.
  2. All values are strings: write "100", never 100.
  3. A ConfigMap is injected as variables (env, envFrom) or as files (volume).
  4. Environment variables are never refreshed: only replacing the Pod updates them.
  5. A ConfigMap volume mounted as a folder refreshes by itself, with a delay.
  6. A subPath mount never refreshes.
  7. A missing ConfigMap or key blocks the Pod in CreateContainerConfigError, and kubectl get pod -o jsonpath gives the message.
  8. immutable: true forbids 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

7 questions
5 min
80% to pass

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