8.12 Kubernetes Pod Configuration Sources

Kubernetes Pod Configuration Sources is the collection of mechanisms Kubernetes provides for injecting configuration data, secrets, and runtime metadata into a Pod's containers without hardcoding those values into container images. These sources decouple application code from the environment it runs in, allowing the same image to be promoted across development, staging, and production clusters while only the surrounding configuration changes.

Core Configuration Objects

ConfigMaps

A ConfigMap stores non-confidential key-value data such as feature flags, connection strings, or full configuration files. ConfigMaps are created independently of Pods and referenced by name, which means a single ConfigMap can be consumed by many Pods and updated without rebuilding container images.

Secrets

A Secret stores sensitive data such as passwords, tokens, and TLS certificates. Structurally, Secrets resemble ConfigMaps but are base64-encoded at rest in the API and can be further protected using encryption at rest, RBAC restrictions, and integration with external secret managers.

Downward API

The Downward API exposes Pod and container metadata that is only known at runtime, such as the Pod's name, namespace, IP address, labels, annotations, and resource requests/limits. This metadata is generated by the kubelet and does not need to be defined in advance by the application author.

Injection Mechanisms

Environment Variables

Configuration values can be injected as environment variables using three approaches:

• env with valueFrom.configMapKeyRef for a single ConfigMap key
• env with valueFrom.secretKeyRef for a single Secret key
• envFrom to import all keys from a ConfigMap or Secret at once, using each key as the variable name

Environment variables are read once at container start; changes to the source ConfigMap or Secret are not reflected until the container is restarted.

Volume Mounts

ConfigMaps and Secrets can also be mounted as files inside a container's filesystem using a configMap or secret volume. Each key becomes a file name, and the corresponding value becomes the file's contents. This approach supports large configuration files and, unlike environment variables, mounted ConfigMap volumes are updated automatically when the source object changes, though the container application must watch the filesystem for changes to pick up the new values.

Projected Volumes

A projected volume combines multiple configuration sources, such as a ConfigMap, a Secret, and Downward API data, into a single directory structure inside the container. This reduces the number of distinct volume definitions needed when a Pod requires configuration from several sources simultaneously.

Ordering and Dependency Considerations

Creation Order

ConfigMaps and Secrets referenced by a Pod must exist before the Pod is scheduled, or the kubelet will report the dependent objects as missing and delay container startup. Kubernetes does not implicitly create these objects on demand.

Optional References

A reference to a ConfigMap or Secret key can be marked optional: true, allowing the Pod to start successfully even if the referenced object or key does not exist. This is useful for configuration that has a sensible default handled by the application itself.

Immutable ConfigMaps and Secrets

Marking a ConfigMap or Secret as immutable prevents further modification of its data. This protects against accidental updates, reduces load on the API server by allowing the kubelet to skip watching the object for changes, and encourages a pattern of creating a new object and rolling out a new Pod revision instead of mutating configuration in place.

Practical Usage Patterns

Layered Configuration

Applications commonly layer configuration sources: a ConfigMap supplies default, non-sensitive settings, a Secret supplies credentials, and the Downward API supplies identity metadata such as the Pod name for logging or service discovery.

Configuration Reload Without Restart

Because mounted ConfigMap and Secret volumes update in place, some applications implement a file watcher that reloads configuration internally when the mounted files change, avoiding a full Pod restart. Applications relying on environment variables cannot use this pattern and require a rollout to pick up new values.

Resource Limits Reflected via Downward API

The Downward API can expose a container's own resource requests and limits as environment variables or files, which lets an application tune its internal behavior, such as thread pool size or memory cache limits, to match the resources actually allocated to it by the scheduler.