Kubernetes ConfigMaps - Complete Configuration Management Guide

What are ConfigMaps?

ConfigMap Purpose

Decouple and externalize configuration from container images
Store non-confidential configuration data in key-value pairs
Can be referenced as environment variables in pods
Can be mounted as volumes in containers
Enable configuration changes without rebuilding images

Key Benefits

Configuration Decoupling

Separate configuration from application code

Externalized Config

Manage configuration outside container images

Versatile Usage

Use as env vars or mounted files

Static Configuration Limitation

If you change ConfigMap values, containers will have to be restarted to get the updated values

Creating ConfigMaps

Imperative Way - From Literals

                            kubectl create configmap literal-example \

                              --from-literal="city=Ann Arbor" \

                              --from-literal=state=Michigan

Create ConfigMap directly from command line literals

Imperative Way - From File

                            kubectl create cm [name] \

                              --from-file=myconfig.txt

Create ConfigMap from a single file

Imperative Way - From Directory

                            kubectl create cm [name] \

                              --from-file=config/

Create ConfigMap from all files in a directory

Declarative Way - From YAML

kubectl apply -f [cf.yaml]

Create ConfigMap from YAML manifest file

ConfigMap YAML Definition

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  namespace: default
data:
  # Simple key-value pairs
  city: "Ann Arbor"
  state: "Michigan"
  
  # File-like keys with multi-line values
  config.properties: |
    server.port=8080
    database.url=jdbc:postgresql://localhost:5432/mydb
    logging.level=INFO
    
  # JSON configuration
  app.json: |
    {
      "features": {
        "newUI": true,
        "darkMode": false
      },
      "limits": {
        "maxUsers": 1000
      }
    }

ConfigMaps and Volumes

ConfigMap

state: Michigan
city: Ann Arbor

→

Mount Volume

/etc/config

→

state

Michigan

city

Ann Arbor

Volume Mount Benefits

Solves the static issue: Updates to values are reflected in containers
File-based access: Each key-value pair is seen as a file in the mounted directory
Automatic updates: Changes propagate to mounted volumes
Application compatibility: Works with apps expecting config files

Pod Configuration Example

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

Dynamic Updates

When a ConfigMap is updated, the files in the mounted volume are automatically updated. However, the update time depends on the kubelet sync period (default: 1 minute). Some applications may need to be restarted or sent a signal to reload the configuration.

ConfigMap Usage Patterns

As Environment Variables

apiVersion: v1
kind: Pod
metadata:
  name: env-pod
spec:
  containers:
  - name: test-container
    image: nginx
    env:
    - name: CITY
      valueFrom:
        configMapKeyRef:
          name: app-config
          key: city
    - name: STATE
      valueFrom:
        configMapKeyRef:
          name: app-config
          key: state
    envFrom:
    - configMapRef:
        name: app-config

Use individual keys or all keys from ConfigMap as environment variables

As Volume with Specific Items

apiVersion: v1
kind: Pod
metadata:
  name: specific-volume-pod
spec:
  containers:
  - name: app
    image: nginx
    volumeMounts:
    - name: config-volume
      mountPath: /etc/config
      readOnly: true
  volumes:
  - name: config-volume
    configMap:
      name: app-config
      items:
      - key: config.properties
        path: application.properties
      - key: app.json
        path: config/app.json

Mount specific keys with custom file names and paths

Advanced Volume Configuration

apiVersion: v1
kind: Pod
metadata:
  name: advanced-configmap-pod
spec:
  containers:
  - name: app
    image: nginx
    volumeMounts:
    - name: config-volume
      mountPath: /etc/config
  volumes:
  - name: config-volume
    configMap:
      name: app-config
      defaultMode: 0644  # File permissions
      optional: false    # Pod won't start if ConfigMap doesn't exist

kubectl ConfigMap Commands

List ConfigMaps

kubectl get cm

List all ConfigMaps in the current namespace

Save as YAML

kubectl get cm [name] -o YAML

Export ConfigMap configuration to YAML file

Describe ConfigMap

kubectl describe cm [name]

Get detailed information about a ConfigMap

Delete ConfigMap

                            kubectl delete -f [cf.yaml]

                            kubectl delete cm [name]

Delete using YAML file or ConfigMap name

Complete ConfigMap Example

Application ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: webapp-config
  labels:
    app: webapp
    env: production
data:
  # Environment variables
  APP_NAME: "My Web Application"
  ENVIRONMENT: "production"
  MAX_USERS: "1000"
  
  # Configuration files
  application.properties: |
    server.port=8080
    spring.datasource.url=jdbc:postgresql://db:5432/app
    spring.datasource.username=app_user
    logging.level.com.example=DEBUG
    feature.new-ui.enabled=true
    
  nginx.conf: |
    server {
        listen 80;
        server_name localhost;
        root /usr/share/nginx/html;
        index index.html;
        
        location / {
            try_files $uri $uri/ =404;
        }
    }

Deployment Using ConfigMap

apiVersion: apps/v1
kind: Deployment
metadata:
  name: webapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: webapp
  template:
    metadata:
      labels:
        app: webapp
    spec:
      containers:
      - name: webapp
        image: myapp:latest
        ports:
        - containerPort: 8080
        env:
        - name: APP_NAME
          valueFrom:
            configMapKeyRef:
              name: webapp-config
              key: APP_NAME
        - name: ENVIRONMENT
          valueFrom:
            configMapKeyRef:
              name: webapp-config
              key: ENVIRONMENT
        volumeMounts:
        - name: config-volume
          mountPath: /app/config
        - name: nginx-config
          mountPath: /etc/nginx/conf.d
      volumes:
      - name: config-volume
        configMap:
          name: webapp-config
          items:
          - key: application.properties
            path: application.properties
      - name: nginx-config
        configMap:
          name: webapp-config
          items:
          - key: nginx.conf
            path: default.conf

Configuration Strategy

Environment-specific ConfigMaps: Different ConfigMaps for dev, staging, prod
Modular configuration: Separate ConfigMaps for different components
Version control: Store ConfigMap YAMLs in version control
Secrets separation: Use Secrets for sensitive data

Update Process

Update ConfigMap with kubectl apply -f configmap.yaml
Wait for kubelet to sync (up to 1 minute)
Mounted files will be automatically updated
For environment variables, restart pods
Verify application picks up new configuration

ConfigMap Best Practices

Organization & Structure

Use meaningful names that describe the configuration purpose
Group related configuration items together
Use labels to categorize ConfigMaps by environment or application
Keep ConfigMaps small and focused on specific functionality
Document configuration keys and their purposes

Security & Operations

Never store sensitive data in ConfigMaps (use Secrets instead)
Set appropriate file permissions when mounting as volumes
Use optional: true for non-critical configuration
Implement configuration validation in your application
Monitor ConfigMap usage and changes

When to Use ConfigMaps vs Other Options

Use ConfigMaps For:

Environment variables
Configuration files
Command-line arguments
Non-sensitive data

Use Secrets For:

Passwords
API keys
TLS certificates
Tokens

Consider Alternatives:

External config servers
Feature flags services
Service mesh config
GitOps tools