A Practical Guide to Kubernetes ConfigMaps for App Configuration

In modern containerized applications, separating configuration from application code is a crucial best practice. Kubernetes ConfigMaps provides a powerful solution to this challenge by offering a way to store and manage configuration data separately from your application containers. This separation makes applications more portable, maintainable, and easier to deploy across different environments.

>> You may be interested in: Top 9 Best DevOps Deployment Tools for Businesses

What is a ConfigMap?

A ConfigMap is a Kubernetes API object that stores non-sensitive configuration data in key-value pairs. It acts as a configuration container that can be consumed by pods and other Kubernetes resources. Think of it as an external configuration file that your applications can reference.

Unlike Kubernetes Secrets, ConfigMaps are not encrypted, making them suitable for storing application settings, environment variables, and configuration files—but not sensitive data like passwords or API keys.

Look through this quick comparison to help you understand when to use ConfigMaps vs. Secrets.

Why Use ConfigMaps?

Configuration Separation

• Keeps configuration separate from application code.

• Enables configuration changes without rebuilding container images.

• Follows the “Configuration as Code” principle, so configurations are versioned and managed efficiently.

Flexibility

• Supports multiple formats: key-value pairs, properties files, JSON, YAML, etc..

• Can be consumed in various ways (environment variables, files).

• Easy to update and manage multiple instances without restarting the application.

Environment Management

• Simplifies managing configurations across different environments.

• Enables consistent configuration across multiple pods.

• Facilitates DevOps practices by automating configuration management.

>> Read more: Top 10 Configuration Management Tools For Developers

How to Create Kubernetes ConfigMaps?

There are several ways to create a ConfigMap:

• Creating from Literal Values: Useful for small configurations that can be directly passed in the command line.

kubectl create configmap app-config --from-literal=APP_COLOR=blue --from-literal=APP_MODE=production

• Creating from a File: Ideal for storing configuration files such as .env or .properties.

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

• Creating from a YAML Definition: Recommended for declarative management and version control.

YAML Definition:

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  APP_COLOR: blue
  APP_MODE: production

Command Line:

kubectl apply -f configmap.yaml

Best Practices for Kubernetes ConfigMaps

Naming and Organization

• Use consistent naming conventions.

• Include environment/component information.

• Organize ConfigMaps by component or function.

• Use meaningful labels for better organization.

Example:

# Use clear, descriptive names
apiVersion: v1
kind: ConfigMap
metadata:
	name: frontend-config # Clear purpose
	namespace: my-application # Specific namespace
	labels: # Proper labeling
		app: frontend
		environment: production

Data Management

• Keep ConfigMaps small to avoid large memory footprints.

• Use appropriate data formats (YAML, JSON, or properties files).

• Document configuration parameters to ensure easy maintenance.

• Store ConfigMap YAML definitions in version control for better traceability.

apiVersion: v1
kind: ConfigMap
metadata:
	name: app-config
data:
	database.properties: |
		db.host=mysql.example.com
		db.port=3306
		db.name=myapp
	app-settings.json: |
	{
		"cache.enabled": true,
		"max.connections": 100
	}

Security Considerations

• Never store sensitive data in ConfigMaps; use Secrets instead.

• Implement RBAC (Role-Based Access Control) when retrieving ConfigMaps.

• Regularly audit ConfigMap contents to detect outdated or incorrect configurations.

Update Strategy

• To ensure application pods detect configuration changes, use checksums to trigger rolling updates:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    metadata:
      annotations:
        checksum/config: $(kubectl get cm app-config -o yaml | sha256sum)

Monitoring and Maintenance

• Monitor ConfigMap usage to avoid unnecessary resource consumption.

• Implement backup strategies for disaster recovery.

• Clean up unused ConfigMaps to prevent outdated configurations from affecting deployments.

Version Control and CI/CD

• Treat configuration as application code.

• Use environment-specific configurations.

• Implement CI/CD pipelines for ConfigMap updates.

Common Use Cases with Examples

Environment Variables

This is a commonly used pattern. We inject the ConfigMap contents via environment variables so that the application can use them.

This is useful for:

• Application settings (e.g., themes, API modes).
• Feature toggles (e.g., enabling/disabling specific functionalities).
• Database or API endpoints (e.g., setting DB_HOST or API_URL).

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 2
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: myapp
        image: nginx:latest
        env:
        - name: APP_COLOR
	        valueFrom:
	        	configMapKeyRef:
	        		name: app-config
	        		key: APP_COLOR
	  	envFrom:
	  	- configMapRef:
	  		name: app-config

Volume Mounts

Some applications do not support environment variables and instead need configurations as files (e.g., config.json, .env, .properties). In such cases, Kubernetes allows you to mount a ConfigMap as a file inside a pod.

This is useful for:

• Configuration-driven applications (e.g., Nginx, Spring Boot).
• Complex settings stored in structured files (YAML, JSON, XML).
• Dynamic configurations that applications need to read as files.

Example:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 2
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: myapp
        image: nginx:latest
        volumeMounts:
        - name: config-volume
	        mountPath: /etc/config
	        readOnly: true
	     volumes:
	     - name: config-volume
	     	 configMap:
	     		 name: app-config

Troubleshooting Common ConfigMap Issues

Conclusion

This introduction provides a foundation for understanding Kubernetes ConfigMaps and their role in container orchestration.

Remember that ConfigMaps are designed for non-sensitive configuration data. Do not store sensitive data like passwords, API keys, etc. Instead, use Kubernetes Secrets to handle sensitive information securely.