Kubernetes ConfigMap: A Complete Guide to Managing Configuration in Kubernetes

In Kubernetes, applications mostly require configuration data, like the database URLs, API keys, or feature flags to function properly. But hardcoding this information makes the containers inflexible and also makes it difficult to scale. This is where a Kubernetes ConfigMap comes into play. 

In this guide, we will work through the basics of Kubernetes ConfigMap and how to use it to the best of its capabilities. 

What is a ConfigMap in Kubernetes?

A Kubernetes ConfigMap is an API object to store configuration data in a separate entity from the application code. Therefore, instead of hard-coding values, you can easily insert them into containers and define those values, like database URLs, API keys without secrets, or application settings into the ConfigMap. 

In Kubernetes, applications mostly require configuration data, like the database URLs, API keys, or feature flags to function properly. But hardcoding this information makes the containers inflexible and also makes it difficult to scale. This is where a Kubernetes ConfigMap comes into play. 

By decoupling the configuration from the application images, Kubernetes ConfigMap would make the Kubernetes workloads highly portable and easy to manage across multiple environments. 

Why Use ConfigMaps in Kubernetes?

ConfigMaps in Kubernetes are super useful because they offer a clean and flexible way to manage application configurations without rebuilding or re-deploying containers for each variable. 

Other benefits include: 

• It keeps the application code and configurations separate from each other. 
• You can easily update or swap the configurations without modifying the app. 
• You can use the same containers repeatedly across multiple environments. 
• Ensure that the replicas of a pod use the same centralized configuration data. 
• Manage configuration for large clusters and applications in a standard and declarative manner. 

To summarise, a Kubernetes ConfigMap allows you to maintain cleaner processes for deployment, improve the application portability, and streamline Kubernetes operators. 

How to Create a Kubernetes ConfigMap

Kubernetes provides a simple method to create a ConfigMap depending on how you input the configuration data. You can: 

• Create Kubernetes ConfigMap directly from the key-value pairs. 
• Generate them from the files. 
• Build them from the entire directories. 

Once you generate a Kubernetes ConfigMap is stored in an API server and can be referenced by the pods and other resources. 

Create ConfigMap from Literal Values

You can create a Kubernetes ConfigMap on the spot by using the literal values passed on to the kubectl create configmap command.

Example:

kubectl create configmap app-config \

  –from-literal=APP_MODE=production \

  –from-literal=APP_PORT=8080

This creates a ConfigMap named app-config with two keys:

• APP_MODE → production
• APP_PORT → 8080

To view it:

kubectl get configmap app-config -o yaml

Creating ConfigMap from Files

If you store the configurations in files, you can create a Kubernetes ConfigMap directly from them. The filename becomes the key, and the contents of the file will act as the values. 

Example:

Suppose you have a file named app.properties:

db_url=jdbc:mysql://db-service:3306/mydb

db_user=admin

db_password=securepass

You can create a ConfigMap as follows:

kubectl create configmap db-config –from-file=app.properties

The resulting ConfigMap will have a key app.properties with the file’s contents.

If you want each property inside the file to become its own key, you can specify –from-env-file:

kubectl create configmap db-config –from-env-file=app.properties

This makes db_url, db_user, and db_password individual keys.

Creating ConfigMap from Directories

If you have multiple different configuration files in a single directory, you can convert the entire folder into a ConfigMap. Each file will then become a key for its respective content value. 

Example:

Directory structure:

config/

  app.properties

  logging.properties

  cache.properties

Command:

kubectl create configmap app-config –from-file=config/

This creates a ConfigMap where:

• app.properties → contents of app.properties
• logging.properties → contents of logging.properties
• cache.properties → contents of cache.properties

How to Use Kubernetes ConfigMaps

After you create a Kubernetes ConfigMap, you can add it to your pods so the applications can access the configuration. Kubernetes supports the three main ways to consume ConfigMap. 

1. As environment variables.
2. As command-line arguments.
3. As mounted configuration files (volumes).

Using ConfigMaps as Environment Variables

You can load the values from a specific ConfigMap into a container based environment variable. 

Example:

apiVersion: v1

kind: Pod

metadata:

  name: env-pod

spec:

  containers:

  – name: myapp

    image: nginx

    envFrom:

    – configMapRef:

        name: app-config

In this example, all key-value pairs in app-config are injected as environment variables.

If you only want specific keys:

env:

  – name: APP_MODE

    valueFrom:

      configMapKeyRef:

        name: app-config

        key: APP_MODE

Using ConfigMaps as Command-Line Arguments

Kubernetes ConfigMaps can also be used to pass as command-line arguments to containers. 

Example:

apiVersion: v1

kind: Pod

metadata:

  name: args-pod

spec:

  containers:

  – name: myapp

    image: busybox

    command: [“printenv”]

    args: [“APP_MODE=$(APP_MODE)”, “APP_PORT=$(APP_PORT)”]

    envFrom:

    – configMapRef:

        name: app-config

Here, the pod runs with arguments derived from the app-config ConfigMap.

Using ConfigMaps as Kubernetes Volume Mounts

You can mount a Kubernetes ConfigMap as a volume inside a pod, making each file a key as its corresponding value. 

Example:

apiVersion: v1

kind: Pod

metadata:

  name: volume-pod

spec:

  containers:

  – name: myapp

    image: busybox

    command: [“/bin/sh”, “-c”, “cat /etc/config/APP_MODE”]

    volumeMounts:

    – name: config-volume

      mountPath: /etc/config

  volumes:

  – name: config-volume

    configMap:

      name: app-config

In this case:

• Each key in app-config becomes a file under /etc/config/.
• The value of the key is stored inside the file.

This is especially useful for applications that expect configuration in file format.

Updating and Managing ConfigMaps in Kubernetes

Once a new Kubernetes ConfigMap is created, you might need to update or manage it as your application requirements evolve. 

• Edit an existing ConfigMap: 

kubectl edit configmap app-config

This opens the ConfigMap in your default editor so you can update keys and values.

• Replace a ConfigMap from a file:

kubectl create configmap app-config –from-file=app.properties -o yaml –dry-run=client | kubectl apply -f –

• Delete a ConfigMap:

kubectl delete configmap app-config

Kubernetes ConfigMaps vs Secrets

Kubernetes ConfigMap Vs Kubernetes Secrets are pretty similar when it comes to configuration storage, but they both serve different purposes. 

Feature	ConfigMap	Secret
Use Case	Non-sensitive configuration (app settings, ports, URLs)	Sensitive data (passwords, API keys, tokens)
Encoding	Plain text	Base64 encoded
Security	Not encrypted by default	More secure, can be encrypted at rest
Access	Mounted as files, env vars, or args	Mounted as files, env vars, or args
Best Practice	Use for general configuration	Use for confidential data only

Common Errors and Troubleshooting with ConfigMaps

Error	Cause	Solution
configmap not found	The ConfigMap name is misspelled or not created.	Verify with kubectl, get configmaps and correct the reference.
Pod not receiving values	ConfigMap not properly referenced in Pod spec.	Check envFrom, env, or volumeMounts sections for typos.
Stale values after update	Pods don’t auto-refresh updated ConfigMaps.	Restart the pods or perform a rolling update.
Mount path conflicts	ConfigMap mounted at an invalid directory path.	Ensure the mountPath is valid and writable.
Large ConfigMap error	ConfigMap exceeds the size limit (1 MB).	Split data into multiple ConfigMaps or use a persistent volume.

Conclusion

Kubernetes ConfigMaps are a powerful method to separate the configuration from application data, which makes the workloads portable, scalable, and easier to manage. Pair them with Secrets for sensitive data or use them on their own with operators to significantly improve the flexibility.

FAQs