ConfigMap and Secret Volumes

Your application reads its configuration from /etc/app/config.yaml at startup. You want to change the log level without rebuilding the Docker image. Passing the value as an environment variable will not work because the app reads a file, not env vars, and the codebase is not yours to modify. What you need is a way to inject a file into the container that Kubernetes manages for you.

Mounting a ConfigMap as a volume solves this exactly.

How ConfigMap volumes work

When you mount a ConfigMap as a volume, Kubernetes takes every key in the ConfigMap and creates a file for it in the mounted directory. The key becomes the filename and the value becomes the file content. The container sees real files at the mount path; it does not need to know anything about Kubernetes.

Think of it like a shared network folder that Kubernetes populates from a dictionary. Every entry in the dictionary becomes a file on the folder. Your application just reads a file like it always has.

Step 1: create the ConfigMap

Create a ConfigMap with a key named config.yaml:

kubectl create configmap app-config --from-literal=config.yaml="log_level: debug"

Confirm it was created:

kubectl describe configmap app-config

You will see the key config.yaml with its value in the Data section.

Step 2: mount it in a Pod

Now declare the volume referencing the ConfigMap and mount it into the container:

nano config-pod.yaml

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

kubectl apply -f config-pod.yaml

kubectl describe pod config-reader

In the Volumes: section you will see app-config-volume with type ConfigMap and the source ConfigMap name. The Mounts: line confirms /etc/app.

Selective key mounting with items

If your ConfigMap has multiple keys but you only want one of them in the container, or you want to rename the file, use the items field:

# illustrative only
spec:
  volumes:
    - name: app-config-volume
      configMap:
        name: app-config
        items:
          - key: config.yaml
            path: application.yaml

This mounts only the config.yaml key, but the file inside the container is named application.yaml. The container sees /etc/app/application.yaml, not config.yaml.

Why would you rename it? Because the application might expect a specific filename that does not match the key name you chose in the ConfigMap. The items field lets you bridge that gap without changing the ConfigMap structure.

Mounting Secrets as volumes

The pattern for Secrets is identical to ConfigMaps. The difference is that Secret values are base64-encoded in the API, but Kubernetes automatically decodes them when projecting the files. The container reads plain text, not base64.

# illustrative only
spec:
  volumes:
    - name: db-credentials
      secret:
        secretName: my-db-secret
  containers:
    - name: app
      volumeMounts:
        - name: db-credentials
          mountPath: /etc/secrets

Each key in the Secret becomes a file under /etc/secrets. If your Secret has a key password, the container can read it at /etc/secrets/password as plain text.

Live reload: the key advantage over environment variables

When you update a ConfigMap and re-apply it, Kubernetes automatically updates the files mounted from that ConfigMap in running Pods. The update propagates in a few seconds without any Pod restart. Applications that watch their configuration files for changes (many web servers and agents do this) will pick up the new configuration automatically.

This is the main reason to prefer ConfigMap volumes over environment variables for configuration. Environment variables from ConfigMaps are read once at Pod startup and do not change while the Pod is running. A configuration change requires a Pod restart to take effect.

ConfigMap and Secret volumes let you externalize configuration as files that your application reads naturally. The two-step pattern (declare the volume, mount it in the container) keeps the ConfigMap separate from the Pod, so you can update configuration independently of the workload definition.