Kubernetes ConfigMap

A ConfigMap is a Kubernetes API object whose whole job is to hold configuration data separately from the code that uses it. You define it once, store key-value pairs in it (for example LOG_LEVEL=info or a full nginx.conf file), and then point one or more Pods at it. The container image stays generic and the environment-specific values live in the cluster.

This solves a real problem. Without ConfigMaps you end up baking config into the image, which means a separate image per environment, or you pass dozens of flags at deploy time and lose track of them. With a ConfigMap, the same image runs in dev, staging, and production, and only the ConfigMap differs.

ConfigMaps are for non-sensitive data only. Anyone with read access to the namespace can read them in plain text, and they are not encrypted at rest by default. Passwords, API keys, and TLS certificates belong in a Secret, which has the same shape but is treated as confidential.

There are three ways a Pod reads a ConfigMap. First, as environment variables: you map individual keys to env vars, or pull every key in at once with envFrom. Second, as command-line arguments built from those env vars. Third, mounted as a volume, where each key becomes a file and the value becomes the file contents inside the container.

The mount method matters because of how updates behave. Environment variables are read once when the container starts, so changing the ConfigMap does nothing to a running Pod, you have to restart it. A mounted volume is different: the kubelet periodically syncs the files, and an updated ConfigMap propagates into the volume on its own, typically within about 60 to 90 seconds. Your application still has to notice the changed file and reload, since Kubernetes only updates the bytes on disk.

One sharp edge: if you mount a single key using subPath, that file will not update when the ConfigMap changes. Only full-volume mounts get live updates. ConfigMap data is also stored in etcd and is capped at 1 MiB per object, because etcd is built for small metadata, not large blobs.

Reach for a ConfigMap whenever a value would differ between environments or might need changing without a code release: service endpoints, timeouts, feature flags, log verbosity, or an entire config file like prometheus.yml. It is the standard Kubernetes way to externalize configuration and keep the twelve-factor separation of config from code.

The main trade-off is around updates. A mutable ConfigMap means Kubernetes watches it, which adds a little API server and kubelet load, and live volume updates can surprise an app that does not expect its config file to change underneath it. Setting immutable: true on a ConfigMap blocks all edits (you must delete and recreate to change it) and in return reduces watch load and protects against accidental changes. This is valuable in large clusters with thousands of ConfigMaps.

A common pattern to force a clean rollout is to include the ConfigMap into the Deployment, then change a hash annotation on the Pod template when the ConfigMap changes. That makes Kubernetes do a normal rolling update and restart Pods with the new config, instead of relying on the slow and partial volume sync.

Say you run a web API that reads DATABASE_HOST, CACHE_TTL_SECONDS, and a logging.json file. You create a ConfigMap named api-config with those three keys. In the Deployment you set DATABASE_HOST and CACHE_TTL_SECONDS as env vars from the ConfigMap, and you mount logging.json into /etc/app/ as a volume.

To move from staging to production you do not touch the image at all. You apply a different api-config in the production namespace pointing DATABASE_HOST at the production database. The same container image runs in both places. If you later raise CACHE_TTL_SECONDS, you edit the ConfigMap and trigger a rolling restart so the env var change takes effect, while the logging.json file would refresh on its own through the mounted volume.