Before learning the solution, it helps to feel the pain that the solution removes.

What is configuration?

Configuration means the small pieces of information that change how a program behaves without changing the program itself. A web shop, for example, needs to know the address of its database, the name of the payment provider it should call, the currency to display, the maximum number of items in a basket, and whether a new checkout page is turned on for customers. None of these facts are the program. They are the surroundings the program lives in.

The same program runs in many surroundings. A developer runs it on a laptop, a tester runs it in a testing area, and real customers use it in production. Each of these places needs different values. The laptop points at a tiny practice database, while production points at a large, protected one.

What goes wrong when settings are baked into the image

A container image is meant to be built once and run many times. If you type the database address directly into the image, you need a different image for every environment. Now the image that your tester approved is not the image that goes to production, because it was rebuilt with different values. You can no longer be sure that what you tested is what you shipped.

There is a second problem. Every tiny change, even switching a log level from quiet to chatty, would demand a new build, a new image upload and a new rollout. That is slow, and in an emergency slow is dangerous.

The idea behind the solution

The cure is to separate what the application is from how it is set up. The image holds the program. A separate object holds the settings. When the container starts, Kubernetes brings the two together. This principle is one of the core ideas of building cloud-friendly applications: store configuration in the environment, not in the code.

A ConfigMap is a named bundle of non-secret settings stored inside the Kubernetes cluster.

The plain definition

A ConfigMap is a Kubernetes object whose job is to hold configuration data as simple key and value pairs. A key is a name, such as the word “log level”, and a value is what that name is set to, such as the word “debug”. A value can also be a whole file, for example the entire text of a web server settings file, stored under a file name.

The name “ConfigMap” is easy to decode. “Config” is short for configuration, and “Map” is the computer-science word for a collection of keys that each point to a value, much like a dictionary where a word points to its meaning.

Why it exists

Kubernetes runs your containers inside small units called Pods. Pods are temporary by nature: they can be created, destroyed and replaced at any moment. If the settings lived inside a Pod, they would vanish along with it. A ConfigMap lives independently of any single Pod, so the same settings survive as Pods come and go, and many Pods can share the same bundle.

Where it is used

ConfigMaps appear almost everywhere in real clusters. Application teams use them for feature switches, service addresses and tuning values. Platform teams use them for tools such as DNS servers, web proxies, monitoring systems and log collectors, all of which need settings files. Even Kubernetes itself uses ConfigMaps internally to hold information for its own components.

To understand a ConfigMap properly, you need a quick picture of the cluster around it.

The main players

A Kubernetes cluster has a control plane, which is the brain that makes decisions, and worker machines called nodes, which are the muscles that run your containers. Several parts cooperate whenever a ConfigMap is created or used. The table of cards below introduces each one in simple words.

flowchart LR
  A["Person or tool"] -->|"create or update"| B["API Server"]
  B -->|"store"| C[("etcd database")]
  B -->|"tell about changes"| D["Kubelet on a node"]
  D -->|"deliver settings"| E["Pod"]
  E --> F["Container reads settings"]
        

Read the picture from left to right. A person, or an automated tool, sends the ConfigMap to the API Server. The API Server saves it in etcd. When a Pod that needs it is placed on a node, the kubelet on that node asks the API Server for the ConfigMap and hands the contents to the container. The container never talks to etcd directly, which keeps the design safe and tidy.

Every ConfigMap is built from a small number of parts. Once you know them, no ConfigMap will look mysterious.

Rules for keys

A key is the name under which a value is stored. Kubernetes is strict about key names: they may only contain letters, numbers, dashes, underscores and dots. This rule exists because keys may later become environment names or file names, and those have their own restrictions. A key that breaks the rule is simply rejected when you try to create the ConfigMap.

Two shapes of value

Values come in two natural shapes, and it helps to recognise both. The first shape is a simple, single-line setting, such as a language code or a timeout number. The second shape is a whole file, where the key is the file name and the value is everything inside the file. Web servers, log shippers and proxy tools typically expect the second shape because they read their settings from a file.

The size limit

A ConfigMap can hold at most about one mebibyte of data in total. This limit exists because the contents live in etcd, and etcd is designed to store small pieces of critical information, not large files. If your settings grow beyond that size, it is a sign that the data belongs somewhere else, such as a storage volume or an external service.

There is more than one road to the same destination. Each road suits a different kind of work.

Creating a ConfigMap means handing its name and its keys and values to the API Server. Kubernetes accepts them in several forms, and the right choice depends on how your team works. The cards below describe the four common approaches in plain language.

Imperative versus declarative

The first three methods are called imperative, which means you give Kubernetes a direct command: “make this now”. The fourth is called declarative, which means you describe the end result you want and let Kubernetes work out how to reach it. Declarative definitions can be saved, reviewed by colleagues, compared over time and reapplied at will.

Generated ConfigMaps

Popular packaging tools can create ConfigMaps for you from plain files and can attach a short fingerprint, a hash of the contents, to the name. This is clever because when the content changes, the name changes too, and Pods that use the old name are automatically replaced by Pods that use the new one. You will see why this matters in the chapter on updates.

A ConfigMap does nothing on its own. It only becomes useful when a Pod consumes it.

There are four main ways for a Pod to receive ConfigMap data. Each has its own personality, and choosing wisely will save you from surprises later.

Way 1: As environment values

An environment value is a named setting that is placed into the container’s surroundings at the moment it starts. The program simply asks its surroundings, “what is the value called log level?”, and gets an answer. You can pick individual keys from a ConfigMap and turn each into an environment value, or you can pull in every key at once, optionally adding a common prefix to keep the names organised.

If a key name is not a valid environment name, Kubernetes skips it and records an event, but the Pod still starts. This is a quiet failure that many beginners miss, so it is worth checking events when a value seems to be missing.

Way 2: As command-line options

Some programs expect their settings as options typed after the program name. Kubernetes lets you first place ConfigMap values into environment values and then refer to those values inside the start command. It is a two-step trick, but it works well for programs that cannot read the environment on their own.

Way 3: As files in a mounted folder

Here the ConfigMap is turned into a volume, which is a folder that appears inside the container. Each key becomes a file in that folder, and the value becomes the file’s content. Programs that read settings files, such as web servers and proxies, love this approach because they do not need to know Kubernetes exists. You can choose which keys to expose, rename them, and set the permission level of the files.

Way 4: By asking the API directly

A program running in a Pod can also call the Kubernetes API itself and read the ConfigMap, provided it has permission. This gives the program full control, including the ability to react to changes instantly, but it ties the program to Kubernetes and requires access rights. It is therefore used mainly by platform tools and operators, not by ordinary applications.

flowchart TD
  CM["ConfigMap"] --> ENV["Environment values"]
  CM --> ARG["Command options"]
  CM --> VOL["Mounted files"]
  CM --> API["Direct API read"]
  ENV --> POD["Pod container"]
  ARG --> POD
  VOL --> POD
  API --> POD
        

Now that you know the options, let us look under the bonnet and follow one ConfigMap on its journey.

The journey step by step

sequenceDiagram
  participant U as Person
  participant A as API Server
  participant E as etcd
  participant K as Kubelet
  participant C as Container
  U->>A: Create ConfigMap
  A->>E: Save data
  K->>A: Ask for ConfigMap
  A-->>K: Send data
  K->>C: Provide env values or files
  U->>A: Update ConfigMap later
  A->>E: Save new data
  K->>A: Periodic check
  A-->>K: Send new data
  K->>C: Refresh mounted files
        

How a file refresh stays safe

When the kubelet refreshes mounted files, it does not overwrite them one by one, because a program reading at that exact moment might see half-old and half-new content. Instead, the kubelet writes the new set into a fresh hidden folder and then swaps a single pointer so that the visible file names suddenly refer to the new folder. The swap is a single atomic step, so a reader sees either the complete old version or the complete new version, never a mixture.

This is the chapter that saves beginners from the most confusing surprise in the whole topic.

You edit a ConfigMap and expect your application to behave differently. Sometimes it does, and sometimes nothing happens at all. The difference depends entirely on how the ConfigMap was consumed.

The four update behaviours

How to make applications pick up changes

There are three popular strategies, and teams often combine them.

Sometimes the safest ConfigMap is the one that can never be changed.

What immutable means

A ConfigMap can be marked immutable when it is created. After that, nobody can change its data, not even an administrator, without deleting and recreating it. Only the object itself can be removed. To use new values you create a new ConfigMap with a different name and point your workload at it.

Why teams choose it

As a rule of thumb, immutable ConfigMaps shine in production systems where stability matters more than convenience, while ordinary changeable ConfigMaps are more comfortable in development environments where people tweak settings all day.

A few ground rules decide where a ConfigMap can be used and what happens when things go wrong.

Namespaces are walls

A ConfigMap belongs to one namespace. A Pod can only refer to ConfigMaps in its own namespace. If two teams in different namespaces need the same settings, each needs its own copy. This wall is intentional: it stops one team from accidentally reading or depending on another team’s settings.

What if the ConfigMap is missing?

By default, if a Pod refers to a ConfigMap that does not exist, the container does not start and the Pod reports a configuration error. This is helpful, because it stops an application from launching with no settings at all. However, you can mark a reference as optional. An optional reference lets the container start even when the ConfigMap is absent, which suits genuinely non-essential settings.

What happens when a ConfigMap is deleted?

Deleting a ConfigMap does not stop running containers, because they already received their data. But any new Pod, or any restarted container, that needs the deleted ConfigMap will fail to start. This is why deletions should be planned and why some teams protect important ConfigMaps with strict permissions.

The built-in certificate ConfigMap

In every namespace Kubernetes automatically places a ConfigMap that holds the cluster’s root certificate authority bundle. Applications use it to verify that they are truly talking to the real Kubernetes API. It is a nice everyday example of the platform itself using ConfigMaps to share non-secret information.

Choosing the right container for your data is as important as writing the data itself.

Kubernetes offers several places to keep information. New learners often mix them up, so here is a clear comparison.

Mixed content

Many real applications need both. A database client, for example, needs the database host name, which is fine in a ConfigMap, and the database password, which must go in a Secret. Kubernetes allows a single Pod to use both at once, so keep each kind of data in its proper home.

Because ConfigMaps look harmless, they are easy to neglect. A few careful habits close most of the risk.

Control who can read and write

Kubernetes uses role-based access control, often shortened to RBAC, to decide who may do what. Reading a ConfigMap and changing a ConfigMap are separate permissions. Give people and programs the smallest permission that lets them do their job. A monitoring tool may need to read one ConfigMap, but it almost never needs to edit it.

Remember that settings can be sensitive in aggregate

Even without passwords, a ConfigMap can reveal internal service addresses, naming conventions and feature plans. An attacker who reads it learns the map of your internal network. Treat ConfigMaps as internal documents, not public ones.

Guard against dangerous changes

A wrongly edited ConfigMap can take down an entire application, because it changes behaviour for every Pod that uses it. Limit write access, require review for changes, and consider immutable ConfigMaps for critical settings.

When something feels wrong, know where to look.

ConfigMaps are quiet objects. They do not run, so they do not produce logs of their own. Problems show up in the Pods that use them, and in the events that Kubernetes records. Here are the most common symptoms and what they usually mean.

What to measure

Although there is no dedicated ConfigMap dashboard, healthy teams keep an eye on a few related signals: the number of ConfigMaps per namespace, how often they change, the restart counts of Pods after a change, and application error rates immediately following a configuration update. A sudden spike in errors right after a ConfigMap change is a strong hint that the change caused the trouble.

Experienced teams repeat a handful of habits that keep configuration tidy and safe.

flowchart LR
  G["Git repository"] --> R["Review and approval"]
  R --> T["Deployment tool"]
  T --> N["New ConfigMap with versioned name"]
  N --> W["Workload updated"]
  W --> P["Pods roll gradually"]
        

The picture above shows the pattern most professional teams follow. Settings live in a repository, a colleague reviews the change, an automated tool creates a new versioned ConfigMap, and the workload is updated so Pods replace themselves gradually. If anything looks wrong, going back is as simple as pointing at the previous version.

These mistakes appear again and again in real clusters. Learn to recognise them early.

A short checklist of good habits, in the order you are likely to need them.

See how ordinary teams and popular tools rely on ConfigMaps every day.

Every tool has strengths and limits. Knowing both keeps your expectations realistic.

Quick answers to the questions beginners ask most often.

No. Both hold small key and value pairs, but a ConfigMap is for ordinary settings while a Secret is designed for confidential data and can receive extra protection.

Not directly. A Pod can only use ConfigMaps in its own namespace, so you need a copy in each namespace, ideally created by an automated tool so the copies stay identical.

The most common reasons are that the value was used as an environment value, that the file was mounted with a sub-path, or that the application reads its settings only at start-up.

Typically up to about a minute or slightly more, because the kubelet checks periodically and also caches results. It is not instant.

Yes. A Pod can pull in as many ConfigMaps as it needs, using any mix of environment values and mounted files.

They keep running with the data they already received. New or restarted Pods that require the ConfigMap will fail to start until it exists again, unless the reference was marked optional.

Not necessarily. They are excellent for production stability and performance, but they add a little friction to everyday changes, so many teams use them only for important or widely shared settings.

Yes. The file name becomes the key and the file content becomes the value, and it can be mounted back as a real file inside the container.

Only if the application cannot reload by itself or if the setting reaches it through environment values or command options. Applications that watch their mounted files can reload without a restart.

Yes, that is a typical use, as long as you restrict who can read the ConfigMap and remember that such information is still internal and should not be exposed publicly.

You started this guide with a simple picture: a cake tin that never changes and a recipe card that can be swapped at will. A ConfigMap is that recipe card for your applications. It lets you build a container image once and run it everywhere with different behaviour, by holding non-confidential settings as keys and values inside the cluster. You learned how the API Server, etcd and kubelet cooperate to deliver those settings, the four ways a Pod can receive them, and the crucial difference between values that refresh and values that do not. You also saw how immutable ConfigMaps add safety, how Secrets protect what ConfigMaps must never hold, and how professional teams use version control and gradual rollouts to change settings without drama.