Configuration

Configuration mechanisms within Kubernetes.

Kubernetes provides ways to separate configuration from code. This is a common practice that aligns with DevOps as a practice, and with cloud native architecture.

If you have a container image that allows separate configuration, you can deploy the same application code in different contexts. For example, you can run tests against the built image, and then run that exact same image in a production context. Doing that gives you better confidence in your testing, compared with if you deployed the application one way for tests and a different way in production.

If you wanted to learn about configuring the kubectl command line tool, read configure access to multiple clusters.

Kubernetes configuration-related APIs

Kubernetes provides two main API kinds that you can use to store configuration, ready for a Pod (or other component) to load and use: ConfigMap, and Secret.

The special-use CertificateSigningRequest and ClusterTrustBundle API kinds also hold configuration data that's relevant to some specific cases, such as TLS configuration.

All of these mechanisms can be shared across multiple Pods. You typically don't have to write the configuration out once per Pod, and you should design applications where possible so that they can work with shared configuration.

To learn about using configuration in your applications, read inject data into applications.

ConfigMaps

A ConfigMap is an API object used to store non-confidential data in key-value pairs. Pods can consume ConfigMaps as environment variables, command-line arguments, or as configuration files in a volume.

A ConfigMap allows you to decouple environment-specific configuration from your container images, so that your applications are easily portable.

Secrets

A Secret is an object that contains an amount of confidential data, such as a password, a token, or a key.

Secrets are similar to ConfigMaps but are specifically intended to hold confidential data. Read the page about Secrets to learn about the benefits (and limitations) around information security and Secrets.

Configuration via sidecar containers or init containers

You can also use an init container or a sidecar container to provide configuration to your workload.

This is useful if you already have some means, outside of Kubernetes, to store configuration or security keys or other information that your containers must use, and that shouldn't be stored in container images.

Sidecar container helper

A sidecar configuration helper runs in the same Pod as the application container, so each Pod has its own sidecar. A typical configuration sidecar fetches configuration data over the Pod network, and then writes it into a volume that is mounted into both containers.

There are many variations on this basic pattern, that still have a helper container writing configuration for the app container to consume.

Init container helper

Pods can have init containers that start before the main application. Unlike sidecars, init containers complete before the Pod's main (application) containers start up, so the configuration only gets set once.

You have two main options for configuration using init containers:

Configuration via the filesystem

With this option, the init container fetches configuration and writes the configuration to a file, or several files, typically to a Pod-local volume.

Configuration via environment variables

FEATURE STATE: Kubernetes v1.34 [alpha] (enabled by default: false)

This is done using a local volume, but only the init container mounts that volume. The kubelet then reads from that volume before starting the app container.

Read Define Environment Variable Values Using An Init Container to learn more.

Cluster configuration

Depending on the role you have, you may also need to configure your cluster. To learn more about that, read cluster administration and look through the list of cluster administration tasks.

What's next

The following links are all relevant to the overall idea of configuration and Kubernetes:

and you can review the list of configuration file formats in the reference section.

Within this section of the documentation, you can read about:

Last modified September 18, 2025 at 8:55 AM PST: Tweak wording (aa8b486847)