What Is a ConfigMap?

Think of a ConfigMap as a central place where your application settings—like database connection strings, API keys (non-sensitive ones), and environment variables—are stored. Instead of hardcoding these values inside your container, your application can fetch them dynamically from a ConfigMap at runtime.

Why Use a ConfigMap?

Managing configuration separately from code is a core principle of the Twelve-Factor App methodology. Here’s why ConfigMaps are useful:

  • Decouples configuration from the application – This makes it easier to update settings without redeploying containers.
  • Enables portability – The same container image can run in different environments by using different ConfigMaps.
  • Simplifies management – Centralized configuration makes it easier to track and update settings across multiple services.
  • Improves security (to some extent) – Unlike Secrets (which are designed for sensitive data), ConfigMaps prevent storing credentials in application code.

How Does a ConfigMap Work?

A ConfigMap can store configuration data as:

  • Key-value pairs (similar to environment variables).
  • File contents (used as mounted volumes).
  • Command-line arguments (passed at runtime).

Once created, ConfigMaps can be referenced by pods using environment variables, volume mounts, or command-line arguments.

Basic Example: Creating a ConfigMap

A simple ConfigMap storing database configuration settings:

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  DATABASE_URL: "postgres://db.example.com:5432"
  LOG_LEVEL: "debug"

After creating the ConfigMap with kubectl apply -f configmap.yaml, applications can consume it.

Using a ConfigMap in a Pod

A pod can reference the ConfigMap via environment variables:

apiVersion: v1
kind: Pod
metadata:
  name: example-pod
spec:
  containers:
  - name: my-app
    image: my-app-image
    env:
    - name: DATABASE_URL
      valueFrom:
        configMapKeyRef:
          name: app-config
          key: DATABASE_URL

Or as a mounted file:

apiVersion: v1
kind: Pod
metadata:
  name: example-pod
spec:
  containers:
  - name: my-app
    image: my-app-image
    volumeMounts:
    - name: config-volume
      mountPath: "/etc/config"
  volumes:
  - name: config-volume
    configMap:
      name: app-config

Now, the application can read /etc/config/DATABASE_URL like a regular file.

Common Challenges with ConfigMaps

1. ConfigMap Updates and Rolling Deployments

ConfigMaps are not automatically updated in running pods. If a ConfigMap is modified, the associated pod won’t automatically detect the changes unless:

  • The pod is restarted manually.
  • The application reloads configurations dynamically.
  • A Kubernetes rollout is triggered (kubectl rollout restart deployment <name>).

2. Size Limitations

  • A ConfigMap cannot exceed 1MB in size.
  • Large configurations should be stored in external configuration services or split across multiple ConfigMaps.

3. Security Considerations

  • ConfigMaps are not encrypted by default – Avoid storing sensitive data (like passwords or tokens). Use Kubernetes Secrets for that.
  • Anyone with access to a ConfigMap can read its contents. Apply RBAC (Role-Based Access Control) to limit access.

Best Practices for Using ConfigMaps

  • Keep ConfigMaps immutable – Instead of modifying a ConfigMap, create a new one and update your deployment to use the latest version.
  • Use namespaces for separation – Avoid conflicts by keeping ConfigMaps scoped to specific namespaces.
  • Avoid storing secrets – Use Secrets for sensitive data.
  • Apply labels and annotations – Helps with organization and tracking changes.
  • Automate updates – If your application requires real-time config changes, implement a mechanism to watch for updates.

Popular Tools for Managing ConfigMaps

  • Helm – Uses templates to manage ConfigMaps dynamically.
  • Kustomize – Helps customize Kubernetes configurations, including ConfigMaps.
  • External Secrets Operator – Syncs ConfigMaps and Secrets from external stores like AWS Secrets Manager.

Further Reading