Kubernetes ConfigMaps Explained

A Kubernetes ConfigMap is an API object used to store non-sensitive configuration data separately from application containers. Instead of hard-coding configuration values into an application or container image, Kubernetes allows Pods to consume those values from a ConfigMap at runtime.

ConfigMaps are useful for application settings, environment-specific values, feature flags, hostnames, ports and configuration files. Separating configuration from application code makes container images easier to reuse and deployments easier to manage.

What Is a ConfigMap?

A ConfigMap is a Kubernetes resource that stores configuration data as key-value pairs or as complete configuration files. A ConfigMap does not execute anything by itself. A Pod, Deployment or another workload must explicitly reference it before an application can consume its values.

Why Use ConfigMaps?

• Keep configuration outside container images.
• Reuse the same image across different environments.
• Change application settings without rebuilding images.
• Provide configuration through environment variables.
• Mount configuration files into containers.
• Keep deployment configuration separate from application code.

Basic ConfigMap Example

A simple ConfigMap can contain several configuration values under the data field. Each key identifies one configuration setting.

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  APP_MODE: production
  API_URL: https://api.example.com
  LOG_LEVEL: info

This example defines three values that an application can consume later. The values are ordinary configuration data and should not contain passwords, private keys or other secrets.

ConfigMap Structure

Using ConfigMaps with Pods

A Pod can consume ConfigMap values in several ways. The most common options are environment variables and mounted configuration files. The appropriate method depends on how the application expects to receive its configuration.

ConfigMap as an Environment Variable

A single ConfigMap key can be exposed as an environment variable using configMapKeyRef. This is useful when an application already reads settings from environment variables.

apiVersion: v1
kind: Pod
metadata:
  name: config-demo
spec:
  containers:
    - name: app
      image: example/app:1.0
      env:
        - name: APP_MODE
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: APP_MODE

The container receives the APP_MODE value from the app-config ConfigMap. The value is therefore controlled by Kubernetes configuration rather than being embedded directly into the Pod definition.

Importing All ConfigMap Values

When an application needs many configuration values, Kubernetes can import the entire ConfigMap into the container environment using envFrom.

containers:
  - name: app
    image: example/app:1.0
    envFrom:
      - configMapRef:
          name: app-config

Each key from the ConfigMap becomes an environment variable inside the container. This reduces repetitive YAML, but it also means that every compatible key in the ConfigMap becomes available to the application.

Mounting a ConfigMap as Files

ConfigMaps can also be mounted as volumes. When mounted this way, each key normally becomes a file and its value becomes the contents of that file.

apiVersion: v1
kind: Pod
metadata:
  name: config-file-demo
spec:
  containers:
    - name: app
      image: example/app:1.0
      volumeMounts:
        - name: config
          mountPath: /etc/app
  volumes:
    - name: config
      configMap:
        name: app-config

For example, a key named APP_MODE can appear as a file named APP_MODE under /etc/app. This approach is especially useful for applications that expect configuration files instead of environment variables.

Storing Configuration Files

A ConfigMap can contain an entire configuration file. Multiline YAML values are commonly used for application configuration, web server configuration and other structured files.

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-settings
data:
  application.yaml: |
    server:
      port: 8080
    logging:
      level: info
    features:
      cache: true

When this ConfigMap is mounted as a volume, application.yaml becomes a file containing the configuration shown in the manifest.

Creating ConfigMaps with kubectl

ConfigMaps can be created directly from the command line. kubectl supports creating them from literal values, individual files and directories.

kubectl create configmap app-config \
  --from-literal=APP_MODE=production \
  --from-literal=LOG_LEVEL=info

A file can also be used as the source of a ConfigMap.

kubectl create configmap app-settings \
  --from-file=application.yaml

Command-line creation is convenient for experiments and quick development tasks. Declarative YAML manifests are usually more suitable for production because they can be reviewed, versioned and deployed consistently.

ConfigMaps with Deployments

ConfigMaps are frequently used together with Deployments. The Deployment defines the Pods, while the ConfigMap provides configuration consumed by those Pods.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web-app
  template:
    metadata:
      labels:
        app: web-app
    spec:
      containers:
        - name: web
          image: example/web:1.0
          envFrom:
            - configMapRef:
                name: app-config

Both Pods created by this Deployment receive the configuration from app-config. The same container image can therefore be deployed to different environments while each environment provides its own configuration.

ConfigMaps and Namespaces

ConfigMaps are namespace-scoped Kubernetes resources. A Pod normally references a ConfigMap from the same namespace, which makes namespaces useful for separating development, staging and production configuration.

metadata:
  name: app-config
  namespace: production

Keeping configuration in the appropriate namespace reduces the risk of accidentally using configuration intended for another environment.

ConfigMap Data and binaryData

The data field is intended for text configuration. Kubernetes also provides binaryData for binary content represented using base64 encoding.

ConfigMaps vs Secrets

ConfigMaps and Secrets are both Kubernetes resources used to provide configuration to applications, but they are intended for different types of data. ConfigMaps are designed for non-sensitive configuration, while Secrets are intended for sensitive values.

Updating a ConfigMap

ConfigMaps can be updated after they are created. However, the effect of an update depends on how the application consumes the configuration.

kubectl edit configmap app-config

If a ConfigMap value is exposed as an environment variable, changing the ConfigMap does not change the environment variable inside an already running container. The Pod normally needs to be recreated before the new environment value is available.

When a ConfigMap is mounted as a volume, Kubernetes can update the mounted files after the ConfigMap changes. However, the application may still need to reload the file before the new configuration takes effect.

Immutable ConfigMaps

Kubernetes supports immutable ConfigMaps. After a ConfigMap is marked immutable, its data cannot be changed. This can be useful when configuration is versioned and replaced instead of modified in place.

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
immutable: true
data:
  APP_MODE: production
  LOG_LEVEL: info

Immutable configuration can reduce accidental changes and make deployments easier to reason about because a particular ConfigMap remains unchanged throughout its lifetime.

Environment-Specific Configuration

One of the main advantages of ConfigMaps is the ability to use the same application image across multiple environments while changing only deployment configuration.

This pattern keeps environment-specific settings outside the container image. The application artifact can remain identical while Kubernetes supplies the appropriate configuration for each environment.

ConfigMap Naming Best Practices

Clear naming becomes important as a cluster grows and applications begin to use many configuration resources. ConfigMap names should make their purpose and ownership easy to understand.

• Use descriptive names.
• Associate configuration with an application when appropriate.
• Keep naming conventions consistent.
• Avoid unnecessary abbreviations.
• Use versioned names for immutable configuration when useful.

metadata:
  name: payments-api-config

Choosing ConfigMap Keys

Configuration keys should follow a predictable naming convention. Environment-variable-style configuration commonly uses uppercase letters and underscores, while keys inside application configuration files may follow the conventions of the application itself.

Common ConfigMap Use Cases

• Application environment settings.
• API endpoint configuration.
• Feature flags.
• Logging configuration.
• Web server configuration.
• Runtime behavior settings.
• Environment-specific application options.
• Non-sensitive service addresses and ports.

ConfigMaps and Container Images

A useful containerization pattern is to keep configuration outside the image whenever the value changes between environments. Building separate images only because an API URL or logging level changed creates unnecessary duplication.

With ConfigMaps, the same image can be promoted from development to staging and then to production while Kubernetes supplies the appropriate configuration at deployment time.

Common Mistakes

• Storing passwords or API keys in ConfigMaps.
• Assuming ConfigMap changes automatically restart Pods.
• Using unclear configuration names.
• Referencing a ConfigMap from the wrong namespace.
• Using ConfigMaps as a general-purpose data store.
• Editing production configuration without version control.
• Importing every configuration key when only a few are required.

Best Practices

• Store only non-sensitive configuration in ConfigMaps.
• Keep declarative ConfigMap manifests under version control.
• Use descriptive names and predictable keys.
• Use environment variables for simple application settings.
• Mount ConfigMaps as files when applications require configuration files.
• Separate configuration by environment or namespace.
• Consider immutable ConfigMaps for versioned configuration.
• Use controlled rollouts when configuration changes require application restarts.
• Validate configuration before deploying it.

Frequently Asked Questions

Helpful Kubernetes Tools

A Kubernetes ConfigMap Generator creates ConfigMap manifests from configuration values, a Kubernetes YAML Generator helps build Kubernetes resource definitions, an Environment Variable Generator creates environment-variable configurations, a YAML Formatter formats manifests for easier review, and a YAML Validator checks Kubernetes YAML for syntax and structural problems.

Conclusion

Kubernetes ConfigMaps provide a practical way to separate non-sensitive application configuration from container images and application code. They can expose values through environment variables, mount configuration files into containers and support different settings across development, staging and production environments. Understanding how ConfigMaps interact with Pods, Deployments, namespaces and configuration updates helps developers build cleaner and more maintainable Kubernetes workloads. Sensitive information should be handled with Secrets or a dedicated secret-management solution instead.