How to Use Kubernetes ConfigMaps and Secrets

In this tutorial, you'll learn about How to Use Kubernetes ConfigMaps and Secrets. We cover key concepts, practical examples, and best practices.

The Problem

Your application needs configuration values (API URLs, database passwords) injected at runtime, but hardcoding them in the deployment is insecure and inflexible. ConfigMaps handle non-sensitive configuration like environment names and URLs, while Secrets handle sensitive data like passwords, API tokens, and SSH keys. Both can be injected as environment variables, mounted as files, or passed to pods through the command line. Without them, you'd need to rebuild container images for every configuration change or store secrets in version control, both of which are bad practices.

Quick Fix

1. Create a ConfigMap from literal values

kubectl create configmap app-config \
  --from-literal=APP_ENV=production \
  --from-literal=API_URL=https://api.example.com

2. Create a ConfigMap from a file

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

The file's content becomes a key-value pair where the key is the filename.

3. Create a Secret from literal values

kubectl create secret generic db-secret \
  --from-literal=DB_USER=admin \
  --from-literal=DB_PASSWORD='P@ssw0rd!'

Values are base64-encoded automatically. View them:

kubectl get secret db-secret -o yaml

To decode:

kubectl get secret db-secret -o jsonpath='{.data.DB_PASSWORD}' | base64 --decode

4. Create a Secret from a file

kubectl create secret generic ssl-secret --from-file=tls.crt --from-file=tls.key

5. Inject ConfigMap as environment variables

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      containers:
        - name: app
          image: my-app:latest
          envFrom:
            - configMapRef:
                name: app-config
            - secretRef:
                name: db-secret

6. Inject specific Secret values as env vars

env:
  - name: DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: db-secret
        key: DB_PASSWORD

7. Mount ConfigMap as a volume

spec:
  containers:
    - name: app
      volumeMounts:
        - name: config
          mountPath: /etc/config
  volumes:
    - name: config
      configMap:
        name: app-config

8. Update ConfigMaps and Secrets without restarting pods

# Update a ConfigMap
kubectl create configmap app-config --from-literal=API_URL=https://new-api.example.com -o yaml --dry-run=client | kubectl apply -f -

# For mounted ConfigMaps, pods pick up changes automatically (may take minutes)
# For environment variables, you must restart the pod
kubectl rollout restart deployment my-app

Use kubectl describe for Detailed Diagnostics

kubectl describe pod <pod-name>
# Events:
#   Type     Reason     Age   From     Message
#   ----     ------     ----  ----     -------
#   Warning  BackOff    5m    kubelet  Back-off restarting failed container

The Events section at the bottom of kubectl describe output is the most valuable diagnostic tool. It shows a chronological log of scheduling failures, image pull errors, and container crashes.

Prevention

• Use kubectl create secret rather than manually base64-encoding values — it's error-prone
• Never commit raw Secret YAML to version control — use SealedSecrets, External Secrets Operator, or SOPS
• Update ConfigMaps and Secrets before rolling out deployments that reference them
• Use descriptive names: frontend-config, db-secret-prod, not config1, secret2
• Store ConfigMaps in version control alongside your deployment manifests for repeatable deployments
• Use kubectl diff -f configmap.yaml before applying to review changes and avoid accidental updates