Before Kubernetes, let us understand the plain idea on a single computer.

A Named Note Pinned to a Program

An environment variable is a simple pair made of a name and a value. The name might be something like LOG_LEVEL and the value might be the word debug. When a program starts, the operating system pins a bundle of these pairs next to it. The program can read any pair by asking for its name. That is all there is to it: a name, a value, and a program that can look them up.

Why Programs Love Them

Programmers use environment variables because they keep settings outside the code. The same program can behave differently in a test setup and in a real customer setup, without changing a single line of the program itself. That idea, keeping configuration separate from code, is one of the most important habits in modern software.

Containers are meant to be identical everywhere, so their differences must come from outside.

One Image, Many Places

A container image is a sealed package holding your application and everything it needs. Teams build the image once, then run the very same image in a developer test area, a staging area, and the real production area. If settings were baked into the image, each place would need its own separate image, and nobody could be sure that what was tested is what actually runs in production.

Kubernetes solves this by letting you describe the settings separately, in the Pod description, and injecting them as environment variables when the container starts. The image never changes. Only the sticky note changes.

A Well-Known Recipe

This approach follows a famous set of guidelines for building cloud applications, often called the twelve-factor method. One of its rules says that anything that changes between environments should live in the environment, not in the code. Kubernetes was designed with that rule in mind, which is why environment variables are so deeply supported.

Eight small terms carry almost the entire story.

Every variable gets its value from exactly one of four kinds of source.

flowchart LR
    A["Plain value in Pod description"] --> E["Container environment"]
    B["ConfigMap key"] --> E
    C["Secret key"] --> E
    D["Pod facts from Downward API"] --> E
    E --> F["Application reads variables at startup"]
        

Sometimes the easiest note is one you write yourself.

How It Works

Inside the description of a container, you list its variables one by one. Each entry has a name and a value. When Kubernetes creates the container, it adds each pair to the environment. The application starts and finds them waiting.

When It Fits

Plain values suit settings that are not sensitive and are unique to one workload: the name of the environment, a mode switch, a timeout, or a flag. They are easy to read during review because everything is in one place.

When many workloads share the same settings, keep them in one shared place.

What a ConfigMap Is

A ConfigMap is a small storage box inside the cluster for non-secret settings. Each item in the box has a key and a value. Examples include the address of an internal service, the default language of an application, or the number of items to show per page.

Pointing at One Key

In the container description, instead of writing a value, you say “take the value from this key of that ConfigMap”. At startup, Kubernetes looks up the key and places its value in the variable. You can even give the variable a different name from the key, which is handy when the application expects a specific variable name.

For passwords and tokens, Kubernetes offers a separate box with extra care around it.

What a Secret Is

A Secret is an object designed to hold sensitive values, like database passwords, access tokens, or private keys. It looks similar to a ConfigMap, but the cluster treats it more carefully. Access to it can be limited with permission rules, and it can be encrypted when stored.

Referencing It Safely

Just as with a ConfigMap, the container says “take this variable’s value from that key of that Secret”. The Pod description contains only the pointer. Someone reading the description sees the name of the Secret, not the password inside.

The Catch with Variables

Once a secret value becomes an environment variable, it lives inside the running process. It can show up in crash reports, in debugging tools, or be inherited by any child program the application starts. This is why many teams prefer to deliver especially sensitive values as files instead, which Chapter 14 explains.

Sometimes a container needs to know who it is and where it lives.

Why a Container Needs to Know

An application may want to include its Pod name in log lines so operators can trace problems. It may need to know its namespace to build a matching address, or its node name to report where it runs. It may even need to know how much memory it was given, so it can size its internal caches sensibly. None of these facts are known when the image is built, because they are decided later by Kubernetes.

Two Kinds of Facts

When a ConfigMap has twenty keys, listing them one by one gets tiring.

Import Everything at Once

The envFrom feature tells Kubernetes: “take every key of this ConfigMap or Secret and turn each into a variable”. The key names become the variable names, and the values become the variable values. One line does the work of twenty.

Adding a Prefix

You can add a prefix that is stuck in front of every imported name. This is very useful when importing from several sources, because it prevents two sources from accidentally using the same variable name.

When two sources define the same name, exactly one value survives.

The Layers

A container’s final environment is built in layers. At the bottom are the defaults baked into the image. On top of that come variables imported in bulk. On top of those come the individually listed variables. When the same name appears in more than one layer, the higher layer wins.

flowchart TD
    A["Image default value"] --> B["envFrom first source"]
    B --> C["envFrom later source"]
    C --> D["Explicit env entry"]
    D --> E["Final value seen by the application"]
        

Kubernetes has a small built-in trick for combining values.

Building One Value from Others

Inside a variable’s value or inside a container’s start command and arguments, you can refer to another variable by wrapping its name in a special reference form. Kubernetes replaces the reference with the actual value before the container starts. This lets you assemble a full address from smaller parts, like a host and a port.

The Rules That Trip People Up

Kubernetes quietly adds some variables you never asked for.

The Old Way of Finding Services

When a Pod starts, Kubernetes looks at the Services that already exist in the same namespace and adds variables describing each one: its address and its port. The variable names are built from the Service name, in capital letters with underscores. This was one of the earliest ways for applications to discover each other.

The Ordering Problem

There is a big catch. These variables are created only for Services that exist at the moment the Pod starts. If a Service is created afterwards, existing Pods never receive its variables. That forces teams to create Services before the Pods that need them, which is fragile and easy to forget.

This single fact explains most surprises about environment variables in Kubernetes.

The Snapshot Moment

Variables are collected just before a container starts, and then frozen. The values are copied into the new process. From that moment, the process holds its own private copy. If the source ConfigMap or Secret is edited later, the running container is not told and its copy does not change.

sequenceDiagram
    participant U as You
    participant K as Kubelet
    participant A as API Server
    participant C as Container
    U->>A: Create Pod with variable sources
    K->>A: Read Pod description
    K->>A: Fetch ConfigMap and Secret values
    A-->>K: Return current values
    K->>C: Start process with a frozen copy
    Note over C: Values never change while it runs
    U->>A: Edit the ConfigMap later
    Note over C: Running container still holds the old copy
    U->>A: Trigger a rollout
    K->>C: Start a new container with fresh values
        

How Teams Handle Changes

To apply a changed setting, teams trigger a rolling restart, which replaces Pods gradually so the application stays available. Many teams make the ConfigMap name include a fingerprint of its contents, so any content change produces a new name, which automatically changes the Pod description and starts a rollout. Some teams also run small controllers that watch for changes and restart the affected workloads.

Kubernetes offers other ways to deliver settings, and each has its place.

Most variable problems fall into a handful of familiar shapes.

A Calm Debugging Path

Environment variables are convenient, and convenience deserves careful handling.

Practical Protections

Keep sensitive values in Secrets, never as plain values in the Pod description. Restrict who can read Secrets and who can enter running containers, using role-based permissions. Turn on encryption at rest for Secrets. Reference only the specific keys a container needs instead of importing entire Secrets. Prefer mounting truly sensitive values as files with tight permissions. Consider external secret managers that fetch values from a dedicated vault. Finally, make sure applications never print their whole environment, and scrub logs of anything that looks like a credential.

You cannot fix what you cannot see, and configuration problems are often invisible until they hurt.

What to Watch

Configuration mistakes usually announce themselves through the Pod’s lifecycle rather than through application metrics. The most useful signals are container start failures, repeated restarts, and events mentioning missing or skipped configuration. Alerts on Pods stuck in a waiting state because of configuration errors catch many problems minutes after a deployment.

Logging with Care

Have applications log which configuration profile they loaded, but never the values of sensitive settings. A safe habit is to log the names of settings and whether they were found, without printing the values. That gives operators enough to diagnose a problem while keeping secrets out of log storage.

Auditing Changes

Who changed a ConfigMap, and when? Cluster audit logs can answer this, and storing configuration in version control gives a reviewable history. Because a small change to a shared ConfigMap can affect many workloads after their next restart, treat those changes with the same care as code changes.

Good habits keep configuration boring, and boring is exactly what you want.

A short checklist that prevents most variable trouble before it starts.

Here is how variables quietly power everyday cluster designs.

Per container. Each container in a Pod has its own list, and one container never automatically sees another container’s variables.

Not in a supported way. Variables are fixed when the container starts. To apply a change, replace the Pod, usually through a rolling restart of its parent workload.

By default the container will not start, and the Pod shows a configuration error. If the reference is marked optional, the container starts and the variable is simply absent.

The Kubernetes setting wins. Values supplied in the Pod description override defaults baked into the image.

They are handled with more care, with tighter access options and encryption possibilities. But once the value becomes a variable, it lives in the process and can leak through logs or child programs, so extra caution is still needed.

No. Variable references to ConfigMaps and Secrets must point to objects in the Pod’s own namespace.

Keys whose names are not valid variable names are skipped during a bulk import. The container still starts, and an event in the Pod’s history records the skipped keys.

Yes, the operating system limits how much data can be passed to a new process, and very large environments can cause start failures. Keep variables small and move bulky data into mounted files.

Use variables for small, simple, stable settings. Prefer files for larger configuration, for certificates, for sensitive values, or when you want updates to arrive without restarting.

Rarely. DNS names are more flexible and always current. The automatic variables depend on Service creation order and are fixed at start, so most teams rely on DNS and may switch the variables off.

Environment variables are the small card of local details that Kubernetes hands to each container at startup. They let a single, well-tested image behave correctly in many different places. Values can be written directly, pulled from a ConfigMap, pulled from a Secret, or filled in from facts about the Pod itself. Bulk imports save effort, a clear order of precedence decides which value wins, and everything is frozen at the moment the container starts. With careful handling of secrets, a habit of rolling out after every change, and clear names, this humble feature becomes one of the most reliable tools in the cluster.