ConfigMap decouples config from container images

WHY IT EXISTS: Before ConfigMaps, configuration was often baked into container images at build time. This meant changing a database hostname or a logging level required a full image rebuild, push, and redeploy. ConfigMaps were created to separate configuration artifacts from image content so the same immutable image can run in development, staging, and production with different settings without touching the build pipeline.

THE MENTAL MODEL: Think of a ConfigMap as a shared settings file that lives inside the cluster rather than inside the image. It is a flat key-value store or a small file bundle that Kubernetes can project into a pod at runtime. It is not a secret vault and it is not a database; it is a convenience layer for plain text data you want to keep out of your application binary so your image stays generic.

HOW IT WORKS: You create a ConfigMap with literal strings or from files on disk. Kubernetes stores it in etcd. When you define a pod, you reference the ConfigMap in one of two ways. First, as environment variables: each key becomes an env var inside the container. Second, as a volume mount: Kubernetes projects the keys as files into a directory you choose. The kubelet on the node watches the ConfigMap and updates mounted files when the ConfigMap changes, though environment variables are set only at pod startup and never update for the lifetime of the container.

WHEN TO USE IT: Use a ConfigMap for any non-sensitive configuration that varies across environments or tenants. Common examples are service endpoints, feature toggle values, external API URLs, and logging verbosity. It is also useful for small config files like nginx.conf or prometheus.yml that you want to manage declaratively without forking the base image or maintaining separate builds per environment.

WHEN NOT TO USE IT: Do not store passwords, API keys, or tokens in a ConfigMap. The data is base64 encoded when stored in etcd but it is not encrypted by default and is visible to anyone with read access in the namespace. For secrets, use a Kubernetes Secret or an external secret manager. Also avoid storing large files; ConfigMaps are meant for small configuration snippets under roughly one megabyte total, not for data archives or binary blobs.

ONE CANONICAL EXAMPLE: A web application needs to know the URL of a cache service. You create a ConfigMap named cache-config with a key CACHE_URL set to redis://cache:6379. In the deployment manifest, you inject this as an environment variable named CACHE_URL. The application reads it at startup. When you move to production, you change the ConfigMap to point to redis://prod-cache:6379 and redeploy the pods to pick up the new value. The image itself never changes.