8.9 Kubernetes Container Environment

Kubernetes Container Environment is the complete set of environment variables a container's process actually sees at startup, assembled from a combination of literal values, references to ConfigMaps and Secrets, Downward API field references, and bulk imports, each source following defined precedence and resolution rules that determine the final, merged environment a container inherits.

Sources of Environment Variables

Literal Values in env

The simplest source is a literal value specified directly within an env entry, a plain string assigned to the named variable with no external reference or lookup required, resolved immediately and identically regardless of any other cluster state.

valueFrom References

An env entry can instead use valueFrom to pull its value dynamically from a configMapKeyRef, a specific key within a ConfigMap; a secretKeyRef, a specific key within a Secret; a fieldRef, a Downward API field from the Pod's own metadata or spec; or a resourceFieldRef, a container's own resource request or limit value.

Bulk Import via envFrom

The envFrom field imports every key from a referenced ConfigMap or Secret as environment variables in one step, optionally prefixing each imported key name to avoid collisions, offering a more concise alternative to individually listing many env entries when an entire ConfigMap or Secret's contents should become environment variables.

Resolution Order and Precedence

env Entries Take Precedence Over envFrom

When a variable name is defined both through an individual env entry and through a bulk envFrom import, the individually specified env entry takes precedence, meaning explicit, one-off overrides can selectively supersede a bulk-imported value without needing to restructure the entire envFrom source.

Order Within Multiple envFrom Sources

If multiple envFrom sources define the same key, whichever source appears later in the envFrom list wins, following a straightforward last-one-wins resolution order among the bulk-imported sources themselves, before any individual env entries are layered on top.

Order Within env Itself

Similarly, if the env list itself somehow contains duplicate variable names, the entry appearing later in the list takes precedence, though well-authored manifests generally avoid intentionally relying on this behavior since it can be a source of confusion during review.

Referencing Other Environment Variables

The $(VAR_NAME) Substitution Within Values

A literal value field can reference another already-defined environment variable using the same $(VAR_NAME) syntax used in command and args, allowing one variable's value to be composed from another, such as building a full connection string from separately defined host and port variables.

Ordering Dependency for Variable References

Because this substitution resolves variables in the order they are defined, a variable referencing another variable must have that referenced variable defined earlier in the env list, since Kubernetes does not perform a full dependency-graph resolution across arbitrarily ordered entries.

Handling Missing References

The optional Field for ConfigMap and Secret References

Both configMapKeyRef and secretKeyRef support an optional field; when set to true, a missing ConfigMap, Secret, or specific key within either simply results in that environment variable being omitted rather than causing the container to fail to start, useful for genuinely optional configuration that a container should tolerate the absence of.

Default Failure Behavior

Without optional set, a missing referenced ConfigMap, Secret, or key causes the container to fail to start entirely, remaining in a waiting state until the missing dependency becomes available, a fail-fast behavior appropriate for genuinely required configuration.

Prefix Handling in envFrom

Avoiding Naming Collisions

The optional prefix field on an envFrom entry prepends a specified string to every imported key name, useful when bulk-importing from a ConfigMap or Secret whose key names might otherwise collide with variables from another source, giving manifest authors a way to namespace bulk-imported variables without needing to rename keys within the source ConfigMap or Secret itself.

Runtime Immutability of the Assembled Environment

Fixed at Container Start

Once a container's environment is assembled and the process launched, it remains fixed for that container's lifetime; changes to a referenced ConfigMap or Secret after the container has started do not propagate into its already-running environment variables, a container restart being required to pick up updated values.