Managing Application Configuration with Kubernetes ConfigMaps

Previously in this course, we explored injecting environment variables in Kubernetes pods. While simple environment variables work for one-off settings, they quickly become unmanageable as your project grows. This lesson introduces ConfigMaps, the primary Kubernetes mechanism for managing application configuration at scale.

The Problem: Decoupling Configuration from Code

In traditional development, you might bake configuration files directly into your Docker image. This is a common pitfall because it forces you to rebuild the entire image whenever a single setting—like a database URL or a feature flag—changes.

To build portable, production-ready applications, we follow the principle of decoupling. Your container image should be immutable (the same code runs in development, staging, and production), while the configuration injected into the container adapts to the environment. ConfigMaps allow you to store these non-sensitive settings as key-value pairs or entire configuration files outside of your Pod definition.

Understanding the ConfigMap Object

A ConfigMap is a standalone Kubernetes resource. Once created, it exists in the cluster independently of any specific Pod. You can then "mount" or "inject" this data into your Pods, allowing the application to read the settings as if they were local files or environment variables.

Worked Example: Creating and Using a ConfigMap

Let's say our web application needs a specific app-settings.json file. Instead of hardcoding it, we will define it in a ConfigMap.

1. Create the ConfigMap Save the following to app-config.yaml:

YAML
apiVersion: v1
kind: ConfigMap
metadata:
  name: web-app-config
data:
  app-settings.json: |
    {
      "debug": true,
      "theme": "dark",
      "api_endpoint": "https://api.example.com"
    }
  log_level: "info"

Apply it with kubectl apply -f app-config.yaml.

2. Reference the ConfigMap in your Pod You can now update your Pod manifest to use this data. Here, we mount the app-settings.json key as a file inside the container:

YAML
apiVersion: v1
kind: Pod
metadata:
  name: config-demo-pod
spec:
  containers:
  - name: web-server
    image: nginx
    volumeMounts:
    - name: config-volume
      mountPath: /etc/config
  volumes:
  - name: config-volume
    configMap:
      name: web-app-config

When this Pod starts, the file /etc/config/app-settings.json will exist inside the container, populated with the data from our ConfigMap.

Comparison: ConfigMap vs. Environment Variables

Hands-on Exercise

1. Create a ConfigMap named my-app-config containing a key message with the value Hello from Kubernetes!.
2. Create a Pod manifest that uses envFrom to inject the entire ConfigMap into the container as environment variables.
3. Apply both and use kubectl exec to run env inside the pod, verifying that MESSAGE=Hello from Kubernetes! appears in the output.

Common Pitfalls

• ConfigMap Dependency: If a Pod references a non-existent ConfigMap, the Pod will fail to start and stay in a CreateContainerConfigError state. Always create the ConfigMap first.
• Sensitive Data: Never put passwords or API keys in a ConfigMap. ConfigMaps are stored in plain text in etcd and are not encrypted. Use Secrets for sensitive information instead.
• Case Sensitivity: Kubernetes keys in ConfigMaps are case-sensitive. Ensure your application code expects the exact key name you defined.

FAQ

Can I update a ConfigMap while the Pod is running? Yes. If you mount a ConfigMap as a volume, Kubernetes will eventually update the file inside the container. However, your application code must be written to watch for file changes or restart to pick up the new values.

Does changing a ConfigMap restart my Pod? No. Kubernetes does not automatically restart Pods when a ConfigMap is updated. If your application doesn't watch for file changes, you will need to manually delete the Pod to force a restart with the new configuration.

Recap

Decoupling configuration from application code is a cornerstone of modern infrastructure. By using ConfigMaps, we keep our container images generic and portable, pushing environment-specific details into the cluster's management layer.

Up next: We will explore how to diagnose and fix issues when your pods fail to start in Troubleshooting Pod Crashes.