Kubernetes Cookbook Part 7: ConfigMaps and Secrets Without the Tears

Your container image should be the same in dev, staging, and production. What changes between those places is configuration: log levels, feature flags, database passwords. In this part you learn how Kubernetes keeps that configuration out of your images using ConfigMaps and Secrets, how to feed it to containers as environment variables or files, and — just as important — what Secrets actually protect and what they absolutely do not.

What you need

• A working local cluster and kubectl from Part 1.
• The clinerds-demo Deployment from Part 4 — we will recreate it below with config wired in, so no worries if your cluster is fresh.
• A rough idea of what an environment variable is, and comfort with kubectl apply -f.

Recipe 1: A ConfigMap for app settings

Problem: Your app needs settings like a log level and a greeting, and you refuse to rebuild the image every time one of them changes.

A ConfigMap is a named bag of plain-text key-value pairs that lives in the cluster. Create one:

apiVersion: v1 kind: ConfigMap metadata: name: clinerds-settings data: APP_ENV: "local-dev" LOG_LEVEL: "info" APP_GREETING: "hello from the configmap" 

kubectl apply -f configmap-settings.yaml 

Now update the demo Deployment to inject every key as an environment variable using envFrom:

apiVersion: apps/v1 kind: Deployment metadata: name: clinerds-demo spec: replicas: 1 selector: matchLabels: app: clinerds-demo template: metadata: labels: app: clinerds-demo spec: containers: - name: web image: hashicorp/http-echo args: ["-text=clinerds part 7"] ports: - containerPort: 5678 envFrom: - configMapRef: name: clinerds-settings 

kubectl apply -f deployment-with-config.yaml kubectl rollout status deploy/clinerds-demo 

The http-echo image is a single Go binary with no shell inside, so we cannot kubectl exec in to check. Instead, run a throwaway BusyBox pod with the same envFrom and ask it to print what it got:

apiVersion: v1 kind: Pod metadata: name: printenv-check spec: restartPolicy: Never containers: - name: check image: busybox:1.36 command: ["sh", "-c", "printenv | grep -E 'APP_|LOG_'"] envFrom: - configMapRef: name: clinerds-settings 

kubectl apply -f printenv-check.yaml kubectl logs printenv-check 

APP_ENV=local-dev LOG_LEVEL=info APP_GREETING=hello from the configmap 

How it works: When the kubelet (the agent on each node that starts containers) creates a pod, it reads the ConfigMap from the API server and sets one environment variable per key before the container process starts. envFrom with configMapRef means "every key in this map becomes a variable." The values are plain strings — nothing is hidden, so never put passwords here.

Variations:

• To pull in a single key under a custom name, use valueFrom instead of envFrom: env: [{name: GREETING, valueFrom: {configMapKeyRef: {name: clinerds-settings, key: APP_GREETING}}}].
• Add optional: true under configMapKeyRef if the pod should still start when the key is missing.
• Clean up with kubectl delete pod printenv-check.

Recipe 2: Mount config as files

Problem: Many tools — nginx, Prometheus, your own app — read configuration from files, not environment variables. You want to hand them a whole config file without baking it into the image.

Put the file's contents in a ConfigMap, one key per file:

apiVersion: v1 kind: ConfigMap metadata: name: web-conf data: server.conf: | server { listen 8080; location / { return 200 "served by configmap\n"; } } 

The | after the key means "literal multi-line block" in YAML — everything indented below it becomes one string. Mount it into an nginx pod as a volume:

apiVersion: v1 kind: Pod metadata: name: nginx-with-conf spec: containers: - name: nginx image: nginx:1.27 volumeMounts: - name: conf mountPath: /etc/nginx/conf.d readOnly: true volumes: - name: conf configMap: name: web-conf 

kubectl apply -f configmap-web.yaml kubectl apply -f pod-nginx-conf.yaml kubectl exec nginx-with-conf -- cat /etc/nginx/conf.d/server.conf 

You should see the exact server block from the ConfigMap. Now edit the ConfigMap (kubectl edit configmap web-conf, change the message), wait about a minute, and cat the file again — it changes on its own.

How it works: Each key in the ConfigMap becomes one file inside the mount directory. The kubelet refreshes mounted ConfigMap volumes on a sync loop (by default once a minute, plus a cache TTL), so file-based config propagates to running pods with a delay of up to roughly a minute or two. Environment variables from Recipe 1 are different: they are set once at process start and never change until the container restarts. Mounted files update; env vars do not.

Variations:

• Mount a single key to a single file with items: [{key: server.conf, path: server.conf}] under the configMap volume.
• Set immutable: true on a ConfigMap to freeze it. The API server then rejects edits, which protects you from half-updated pods and lightens the kubelet's watch load. To change it, create a new ConfigMap with a new name and point the pod at it.

Recipe 3: Secrets, done honestly

Problem: Your app needs a database password. A ConfigMap is plaintext for anyone to read, so you reach for a Secret — and you should know exactly what that buys you.

The fastest way to create one:

kubectl create secret generic clinerds-db \ --from-literal=username=app \ --from-literal=password=s3cr3t-pass 

For YAML you can commit (to a private repo, ideally encrypted there), use stringData so you write plain text and let Kubernetes encode it:

apiVersion: v1 kind: Secret metadata: name: clinerds-db-yaml type: Opaque stringData: username: app password: s3cr3t-pass 

Here is the part nobody tells beginners loudly enough: base64 is encoding, not encryption. If you kubectl get secret clinerds-db -o yaml, you will see c2NjcjN0LXBhc3M= — anyone can turn that back into the password with one base64 -d. Secrets exist to keep casual accidents from leaking credentials (no more passwords in kubectl describe output or printed env dumps), not to stop a determined reader.

Consume it both ways in one check pod:

apiVersion: v1 kind: Pod metadata: name: secret-check spec: restartPolicy: Never containers: - name: check image: busybox:1.36 command: ["sh", "-c", "echo env-user=$DB_USER; ls -l /etc/db; cat /etc/db/password"] env: - name: DB_USER valueFrom: secretKeyRef: name: clinerds-db key: username volumeMounts: - name: db-secret mountPath: /etc/db readOnly: true volumes: - name: db-secret secret: secretName: clinerds-db defaultMode: 0400 

kubectl apply -f pod-secret-check.yaml kubectl logs secret-check 

env-user=app -r-------- 1 root root 11 Sep 18 09:01 password s3cr3t-pass 

How it works: secretKeyRef injects one key as one environment variable, decoded for you. The volume form writes each key as a file, and defaultMode: 0400 sets the file permissions to read-only for the owner only — the tightest sensible setting. Same rule as ConfigMaps: env vars are frozen at start, mounted files refresh on the kubelet sync loop. Clean up with kubectl delete pod secret-check.

Recipe 4: Roll pods when config changes

Problem: You edited the ConfigMap from Recipe 1, but your app still shows the old greeting. Nothing restarted — because nothing is supposed to.

kubectl edit configmap clinerds-settings # change APP_GREETING kubectl get pods -l app=clinerds-demo 

Note the pod's AGE — it did not budge. Kubernetes deliberately does not restart pods when configuration changes; the Deployment only reacts to changes in its own pod template. So tell it the template "changed" by triggering a rollout:

kubectl rollout restart deploy/clinerds-demo kubectl rollout status deploy/clinerds-demo kubectl get pods -l app=clinerds-demo 

NAME READY STATUS RESTARTS AGE clinerds-demo-6df8d9f7c9-x2vkm 1/1 Running 0 8s clinerds-demo-77b9c5f4b5-qj4nt 1/1 Terminating 0 14m 

A fresh pod starts, picks up the new env values, and the old one drains. Zero downtime, since the rollout respects your replica count.

How it works: rollout restart adds a timestamp annotation (kubectl.kubernetes.io/restartedAt) to the pod template. To the Deployment controller that is a template change, so it performs a normal rolling update — new pod first, old pod second.

Variations:

• Helm charts automate this with a checksum annotation. In the template: annotations: {checksum/config: "{{ include (print $.Template.BasePath \"/configmap.yaml\") . | sha256sum }}"}. Any edit to the ConfigMap changes the hash, which changes the template, which triggers a rollout. Same trick, no manual command.
• If your app can reload config itself (many read mounted files on a signal), Recipe 2's auto-updating volume may save you the restart entirely.

Recipe 5: The honest limits of Secrets

Problem: You now assume Secrets are safe. Let us check that assumption before it costs you.

kubectl get secret clinerds-db -o jsonpath='{.data.password}' | base64 -d 

s3cr3t-pass 

One command, full password. Two hard facts follow. First, anyone whose account can get secrets in that namespace can do exactly what you just did — Secrets are access-controlled, not concealed. Second, by default the API server stores Secrets in etcd (the cluster's database) as plain base64, so anyone who reads an etcd backup or snapshot reads every Secret in the cluster.

How it works: A Secret is "private" only because of RBAC (Role-Based Access Control, the permission system we cover in Part 10) and, if you enable it, encryption at rest. The first decides who may ask the API server for a Secret; the second decides what an etcd file on disk contains.

Variations:

• Turn on encryption at rest by giving the API server an EncryptionConfiguration with an aescbc or secretbox provider — see the official docs on encrypting secret data at rest. On kind this means extra flags at cluster creation; on managed clusters it is often a checkbox backed by a KMS (Key Management Service).
• For real environments, keep secrets in an external manager — HashiCorp Vault, AWS Secrets Manager — and sync them in with a controller like External Secrets Operator. The cluster then holds references, not the master copy.
• Grant Secret access to the smallest set of service accounts possible, and prefer mounted files over env vars: env values leak into crash dumps and kubectl describe pod output more easily.

ConfigMap vs Secret: what is the actual difference?

People search "ConfigMap vs Secret" expecting a trick answer. There is not one: both store configuration as key-value pairs, and both are delivered to your pod the same way. The difference is intent and handling, not magic encryption.

So when do you choose which? If losing the value would not hurt you, it is a ConfigMap. If leaking the value means rotating credentials, it is a Secret. The recipes above show why: Secrets get separate RBAC treatment, can be encrypted at rest with an EncryptionConfiguration, and can be synced from an external manager like Vault — none of which you need for a log level.

The one rule that never changes: do not put passwords in a ConfigMap just because it is easier to read. Everyone with get configmap access in that namespace can read it too.

Where to go next

Configuration is sorted, but config files and Secrets vanish when a pod does — your database cannot live like that. In Part 8: Storage we give pods disks that survive restarts with Volumes, PersistentVolumeClaims, and StorageClasses. For the full reference on everything you mounted today, the official ConfigMap documentation is the canonical source. The whole series lives at /series/kubernetes-cookbook.