Lesson 4 of 11 · 9 min · Core objects

ConfigMaps and Secrets

Covers: Kubernetes 1.34 (k3s), kubectl 1.34. Updated 13 Nov 2026. Part of the DevOps Engineer roadmap.

What you will learn

  • Why configuration lives outside the image
  • Creating ConfigMaps and Secrets
  • Injecting them as environment variables or files
  • Update behaviour: what changes live and what needs a restart
  • The truth about Secret security, and how to improve it

In simple words

The same image should run in testing and in production. Only the settings should differ: which database, which password. So settings are kept outside the image and handed to the container when it starts. ConfigMaps hold ordinary settings, and Secrets hold sensitive ones.

Words to know

  • ConfigMap: an object that stores ordinary settings as names and values.
  • Secret: an object for sensitive values such as passwords. It is only lightly protected by default.
  • Environment variable: a named value that a program reads when it starts.
  • Mount: making a ConfigMap or Secret appear as files inside the container.

One image, many environments

An image should be the same in development, staging and production (build once, deploy many). What differs is configuration: database host, log level, feature settings, credentials. Kubernetes keeps it in two object kinds, separate from the image and from the Deployment:

  • ConfigMap: non-sensitive configuration (key-value pairs or whole files).
  • Secret: sensitive data (passwords, tokens, keys, TLS certificates).

Both are namespaced and consumed by Pods.

Creating them

kubectl create configmap app-config --from-literal=APP_ENV=prod --from-literal=LOG_LEVEL=info
kubectl create secret generic db-secret --from-literal=password='s3cr3t-pw'
kubectl create configmap nginx-conf --from-file=nginx.conf       # a whole file as a key

or as YAML (data: for text, binaryData: for binary). For Secrets you can write stringData: (plain text, converted for you) or data: (base64).

Reading the Secret back shows how it is stored:

kubectl get secret db-secret -o jsonpath='{.data.password}'            # czNjcjN0LXB3
kubectl get secret db-secret -o jsonpath='{.data.password}' | base64 -d   # s3cr3t-pw

base64 is an encoding, not encryption. Anyone who can read the Secret object can decode it in one command. Secrets are not secure by themselves; they are a separate object so that you can give different access to them and avoid putting credentials in images and Deployments. See the last section.

Using them in a Pod

Two ways, and we used both in one Pod:

apiVersion: v1
kind: Pod
metadata: {name: cfg}
spec:
  containers:
    - name: app
      image: busybox:1.36
      envFrom:
        - configMapRef: {name: app-config}          # every key becomes an env var
      env:
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef: {name: db-secret, key: password}   # one key as one variable
      volumeMounts:
        - {name: sec, mountPath: /etc/secret, readOnly: true}
  volumes:
    - name: sec
      secret: {secretName: db-secret}               # each key becomes a file

The container's log (it printed its environment and the mounted directory):

APP_ENV=prod
DB_PASSWORD=s3cr3t-pw
LOG_LEVEL=info
---
password            <- the file name is the key
s3cr3t-pw           <- the file content

Environment variables or files?

  • Env vars are simple, but are visible to every process in the container, show up in kubectl describe/exec output more easily, can leak in crash dumps and logs, and never update while the Pod runs.
  • Mounted files can be restricted by file mode, are not printed by accident, and are updated automatically (with a delay of up to about a minute) when the ConfigMap or Secret changes, if the application re-reads the file. Use files for secrets and for config files, env vars for simple settings.
  • Mounting with subPath disables automatic updates for that file.

Updates

We changed the ConfigMap after the Pod started:

kubectl patch configmap app-config -p '{"data":{"LOG_LEVEL":"debug"}}'
kubectl exec cfg -- sh -c 'echo LOG_LEVEL=$LOG_LEVEL'
LOG_LEVEL=info          <- the running Pod still has the old value

Environment variables are fixed at container start. To apply a changed ConfigMap or Secret that is consumed as env vars, restart the Pods: kubectl rollout restart deployment/web. A pattern that makes this automatic: put a hash of the config in a Pod-template annotation (Helm does this with checksum/config), so a config change changes the template and triggers a rolling update. For file mounts, either have the app watch the file or restart.

Make configuration immutable where possible (immutable: true): protects against accidental edits and reduces API server load; to change, create a new ConfigMap with a new name and roll the Deployment to it.

What goes where

Data Object
log level, feature options, URLs, hostnames ConfigMap
nginx.conf, application properties files ConfigMap (as file)
passwords, API tokens, private keys Secret
TLS certificate and key Secret of type kubernetes.io/tls (kubectl create secret tls)
registry credentials for private images Secret of type kubernetes.io/dockerconfigjson (imagePullSecrets)

Limits: an object holds at most about 1 MiB. Big files do not belong in ConfigMaps.

Securing Secrets properly

By default Secrets are stored unencrypted in etcd (just base64) and readable by anyone with RBAC permission to get Secrets in that namespace. To do better:

  1. RBAC: grant get/list/watch secrets only to the few accounts that need it. Remember that list returns values, and that anyone who can create a Pod in a namespace can mount any Secret there.
  2. Encryption at rest for etcd (an API server setting; managed services offer it, often with KMS keys).
  3. External secret stores: keep the real secrets in AWS Secrets Manager, HashiCorp Vault, Google Secret Manager or Azure Key Vault and sync them into the cluster with the External Secrets Operator or mount them with the Secrets Store CSI driver. The cluster object is then a short-lived copy, and rotation and audit happen centrally.
  4. GitOps-safe encryption: if manifests live in Git, store only encrypted forms (Sealed Secrets, SOPS). Never commit plain Secret YAML or base64 text: it is not hidden.
  5. Use cloud IAM for service-to-service access (IRSA on EKS, Workload Identity) so Pods get short-lived tokens and need no static keys at all.
  6. Do not log environment variables; prefer file mounts; keep Secrets out of image layers (Docker lesson).

Common mistakes

  • Believing base64 hides the data, or committing Secret manifests to Git.
  • Expecting env vars to update when a ConfigMap changes.
  • Huge ConfigMaps or binary data in them.
  • Referencing a ConfigMap or Secret that does not exist: the Pod sticks in CreateContainerConfigError (look at kubectl describe pod).
  • One giant Secret shared by every app, with no least privilege.
  • subPath mounts that never refresh.
  • Using the default service account token and permissive RBAC.

Try it yourself

  1. Create a ConfigMap and a Secret and a Pod that uses both as environment variables and as files; read the output from kubectl logs.
  2. Change the ConfigMap and show which consumers see the change without restarting. Then use kubectl rollout restart.
  3. Decode a Secret with base64 -d. Who in your cluster can run that command?
  4. Reference a missing ConfigMap key and read the error in kubectl describe pod.

Check yourself

Is a Kubernetes Secret encrypted?

By default only base64-encoded, and stored unencrypted in etcd. Protect it with RBAC, encryption at rest, and ideally an external secrets manager.

Why do environment variables from a ConfigMap not change when you edit the ConfigMap?

Env vars are set when the container starts. You must restart the Pods (for example kubectl rollout restart) to pick up new values. Mounted files update automatically after a delay.

How do you give an application a configuration file without rebuilding the image?

Put the file in a ConfigMap and mount it as a volume at the path the application reads.

How can a team keep secrets in a Git repository safely?

Only in encrypted form (Sealed Secrets, SOPS), or reference an external secrets manager (External Secrets, CSI driver) so no secret values are committed.

Interview questions

How do you manage configuration across dev, staging and production in Kubernetes?

Same image everywhere; environment-specific ConfigMaps and Secrets (often via Kustomize overlays or Helm values per environment), stored in Git, with secrets from a secrets manager.

What happens if a Pod references a Secret that doesn't exist?

The Pod stays in ContainerCreating / CreateContainerConfigError and events show the missing Secret; it starts once the Secret exists (for required references).

ConfigMap as env vars or as volume?

Env vars for a handful of simple settings; volumes for files, larger configs and secrets, because files can be permission-restricted and update without a restart.

Summary

  • ConfigMaps hold non-sensitive configuration, Secrets sensitive data; both keep config out of images.
  • Inject as env vars (fixed at start) or files (refresh automatically); restart Pods to apply env changes.
  • Secrets are base64, not encrypted: use RBAC, encryption at rest and external secret stores; never commit plain Secrets.
  • Prefer immutable config objects and file mounts for secrets.

Going deeper

See how much of this you can explain

A free mock interview asks you new questions on Kubernetes for DevOps Engineer and scores every answer, with what to fix.