Kubernetes

Kubernetes ConfigMaps and Secrets: Config Without Rebuilds

Intermediate
14 minutes
Updated October 2026

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

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: true freezes 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 sha256sum of the config; kustomize does it with configMapGenerator name 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, Spring refresh, 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/watch on secrets is 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.
  • imagePullSecrets is 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:

ToolHow it worksWhen to use
External Secrets OperatorSyncs from Vault/AWS SM/Azure KV into Kubernetes SecretsMost common — secret lives in the cloud, K8s sees the synced Secret
Sealed Secrets (Bitnami)Encrypts the Secret YAML so only the cluster can decrypt itGitOps-friendly — the encrypted blob is safe to commit
SOPSEncrypts values inside YAML/JSON with age/KMS keysWorks with any GitOps tool, not just secrets
CSI Secrets StoreMounts secrets from an external provider as volumesWhen 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.

Written & Reviewed by Yasir Masood, CloudOpsGuide Editor

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.