Kubernetes ConfigMaps and Secrets: Config Without Rebuilds
Hardcoded config in images means rebuilding for every environment — and secrets baked into images are a breach waiting to be pushed to a registry. Kubernetes splits the answer into two objects: ConfigMaps for config, Secrets for credentials. Same mechanics, different sensitivity — and different rules for handling them.
Table of Contents
- ConfigMaps: environment-specific settings
- Secrets: same shape, sensitive payload
- Injecting into pods: env vars
- Injecting as files: volume mounts
- What happens on update
- Reloading config without restarts
- Security realities of Secrets
- Secrets in Git: the GitOps approach
- Sizing rule and common errors
ConfigMaps: environment-specific settings
ConfigMaps hold non-sensitive key-value config — feature flags, log levels, endpoints, whole config files. Three ways to create them:
kubectl create configmap app-config \
--from-literal=LOG_LEVEL=debug \
--from-literal=FEATURE_X=on
kubectl create configmap nginx-conf \
--from-file=nginx.conf # whole file becomes one key
kubectl create configmap app-env \
--from-env-file=.env # KEY=val per line
--from-file is the underused one — it lifts an entire nginx.conf or application.properties into a ConfigMap, which then mounts as a file your app reads normally. The pattern: one image for all environments, the ConfigMap carries the differences.
Secrets: same shape, sensitive payload
Secrets hold credentials — passwords, tokens, TLS keys, registry pull creds. Kubernetes offers typed factories for the common cases:
kubectl create secret generic db-creds \
--from-literal=username=app \
--from-literal=password='Sup3r!Secret'
# TLS certs — validates cert/key pair structure
kubectl create secret tls site-tls \
--cert=tls.crt --key=tls.key
# registry pull credentials — what imagePullSecrets references
kubectl create secret docker-registry reg-cred \
--docker-server=ghcr.io \
--docker-username=me \
--docker-password=token
In YAML, values are base64-encoded — encoding, not encryption:
apiVersion: v1
kind: Secret
metadata:
name: db-creds
type: Opaque
stringData: # write plain values; API server encodes them
password: Sup3r!Secret
stringData saves you the manual echo -n ... | base64 round-trip — use it everywhere you'd otherwise paste encoded blobs.
Injecting into pods: env vars
env:
- name: DB_PASSWORD
valueFrom:
secretKeyRef:
name: db-creds
key: password
- name: LOG_LEVEL
valueFrom:
configMapKeyRef:
name: app-config
key: LOG_LEVEL
# or pull in the whole object at once — every key becomes an env var
envFrom:
- secretRef: { name: db-creds }
- configMapRef: { name: app-config }
envFrom is convenient but implicit — every key lands in the environment, including ones you didn't mean to expose. Prefer explicit valueFrom entries for secrets so the pod spec documents exactly which credential the app gets.
Injecting as files: volume mounts
volumes:
- name: config
configMap:
name: nginx-conf
- name: creds
secret:
secretName: db-creds
defaultMode: 0400 # read-only for owner only
containers:
- volumeMounts:
- { name: config, mountPath: /etc/nginx }
- { name: creds, mountPath: /etc/secrets, readOnly: true }
Each key becomes a file in the mount directory — db-creds/password lands at /etc/secrets/password. defaultMode sets the Unix permission bits; 0400 keeps creds readable by the app user only.
What happens on update
This behavior asymmetry catches everyone eventually:
- Volume mounts auto-update. When the ConfigMap/Secret object changes, kubelet refreshes the mounted files within a minute (sync period + cache TTL). Apps that watch the file see new config with no restart.
- Env vars never update. They're set at container start. Changing the object does nothing until the pod restarts — which is why teams annotate Deployments with a config hash to force rollouts on config changes.
- Immutable objects never update.
immutable: truefreezes the object entirely — updates require a new object and new pod spec. In exchange you get protection from accidental edits and a real reduction in API-server load.
Reloading config without restarts
The env-var/volume asymmetry creates a real operational problem: you updated the ConfigMap, volume mounts refreshed, but the app needs a restart to see new env vars. Three solutions:
- Hash-triggered rollouts — annotate the Deployment's pod template with a hash of the ConfigMap. When the ConfigMap changes, the hash changes, the template changes, and Kubernetes rolls the pods. Helm does this with
sha256sumof the config; kustomize does it withconfigMapGeneratorname suffixes. - Reloader sidecar — stakater/Reloader watches ConfigMaps/Secrets and automatically rolls Deployments when they change. Add it as a Helm chart and it handles the restart without code changes.
- App-level config reload — the app itself watches a mounted file or polls an endpoint. More work, but zero-downtime config changes for apps that support it (nginx
reload, Springrefresh, custom logic).
The hash pattern is the most common because it's declarative — the rollout is a consequence of the manifest change, not a side effect.
Security realities of Secrets
- Base64 is not encryption. Anyone with API read access sees plaintext — restrict Secret reads with RBAC (
get/list/watchonsecretsis the permission that matters). - Enable encryption at rest — the API server can encrypt etcd contents (EncryptionConfiguration or KMS providers). Without it, every Secret is plaintext in etcd.
- Secrets in git? Never plain YAML. Sealed Secrets, External Secrets Operator, or SOPS — pick one. GitOps workflows pair naturally with External Secrets pulling from Vault or AWS Secrets Manager.
- Prefer volume mounts over env vars for secrets — env vars leak into
kubectl describe pod, crash dumps,/proc/*/environ, and child processes. imagePullSecretsis how private registries work: attach the docker-registry secret to the pod spec (or better, to the ServiceAccount) and pulls authenticate automatically.
Secrets in Git: the GitOps approach
Plain Kubernetes Secrets in git is a breach waiting for a git log. The practical alternatives:
| Tool | How it works | When to use |
|---|---|---|
| External Secrets Operator | Syncs from Vault/AWS SM/Azure KV into Kubernetes Secrets | Most common — secret lives in the cloud, K8s sees the synced Secret |
| Sealed Secrets (Bitnami) | Encrypts the Secret YAML so only the cluster can decrypt it | GitOps-friendly — the encrypted blob is safe to commit |
| SOPS | Encrypts values inside YAML/JSON with age/KMS keys | Works with any GitOps tool, not just secrets |
| CSI Secrets Store | Mounts secrets from an external provider as volumes | When secrets must never live in etcd at all |
External Secrets is the most common choice — apps see native Kubernetes Secrets (no code changes), the source of truth stays in Vault or the cloud provider's managed store, and rotation happens in one place. Sealed Secrets is simpler if you don't want to run an external store — encrypt once, commit to git, the controller decrypts it into a real Secret inside the cluster.
Sizing rule and common errors
Both objects cap at ~1 MiB — they're for configuration, not data. Big files belong in volumes or object storage, fetched at startup.
Common failures: CreateContainerConfigError on pod startup usually means a referenced ConfigMap/Secret key doesn't exist (check kubectl describe pod events). And a pod that can see a Secret's name but gets permission denied on read is an RBAC problem, not a YAML problem.
The pattern that scales: ConfigMaps for anything you'd tweak per environment, Secrets for anything you wouldn't print in a log line, and an external secret manager the moment compliance asks where your credentials live.
Related Articles
Our tutorials and troubleshooting runbooks are written by a DevOps practitioner with hands-on experience operating Kubernetes, Terraform, CI/CD pipelines, and Linux infrastructure in production. Commands, manifests, and configurations are verified against current tooling releases. Learn more about our editorial process or report a correction or outdated flag.