Using ConfigMaps via Environment Variables

The simplest way to consume a ConfigMap in a container is via environment variables. The application reads os.getenv("LOG_LEVEL") and Kubernetes injects the value from the ConfigMap at container startup. No file system access needed, no config parsing library required.

First, create a ConfigMap to work with:

kubectl create configmap app-config \
  --from-literal=LOG_LEVEL=info \
  --from-literal=PORT=8080 \
  --from-literal=REGION=eu-west-1

Injecting a single key

Use env.valueFrom.configMapKeyRef to map one ConfigMap key to one environment variable:

nano env-single.yaml

apiVersion: v1
kind: Pod
metadata:
  name: env-single
spec:
  containers:
    - name: app
      image: busybox:1.36
      command: ['sh', '-c', 'echo LOG_LEVEL=$LOG_LEVEL && sleep 3600']
      env:
        - name: LOG_LEVEL
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: LOG_LEVEL
  restartPolicy: Never

kubectl apply -f env-single.yaml
kubectl logs env-single

The output shows LOG_LEVEL=info. The container received the value from the ConfigMap without it being hardcoded in the Pod spec.

The name field under env is the environment variable name inside the container. It does not have to match the ConfigMap key. You could name the env var APPLICATION_LOG_LEVEL while the ConfigMap key is LOG_LEVEL.

Injecting all keys at once

Use envFrom.configMapRef to inject every key in a ConfigMap as a separate environment variable. This avoids listing each key individually:

nano env-all.yaml

apiVersion: v1
kind: Pod
metadata:
  name: env-all
spec:
  containers:
    - name: app
      image: busybox:1.36
      command: ['sh', '-c', 'env | grep -E "LOG_LEVEL|PORT|REGION"']
      envFrom:
        - configMapRef:
            name: app-config
  restartPolicy: Never

kubectl apply -f env-all.yaml
kubectl logs env-all

All three keys from app-config appear as environment variables. The variable names are taken directly from the ConfigMap keys.

What happens when the ConfigMap is missing

If the ConfigMap referenced by configMapKeyRef does not exist when the Pod starts, the Pod fails to start with an error like Error: configmap "app-config" not found. The container never reaches Running state.

nano env-missing.yaml

apiVersion: v1
kind: Pod
metadata:
  name: env-missing
spec:
  containers:
    - name: app
      image: busybox:1.36
      command: ['sh', '-c', 'echo $MISSING_KEY']
      env:
        - name: MISSING_KEY
          valueFrom:
            configMapKeyRef:
              name: does-not-exist
              key: some-key
  restartPolicy: Never

kubectl apply -f env-missing.yaml
kubectl describe pod env-missing

Look at the Events section. You will see Error: configmap "does-not-exist" not found. To make the reference optional (inject the variable only if the ConfigMap exists), add optional: true to the configMapKeyRef:

configMapKeyRef:
  name: optional-config
  key: some-key
  optional: true

With optional: true, if the ConfigMap or the key does not exist, the environment variable is simply absent and the Pod starts normally.

kubectl delete pod env-single env-all env-missing

Use valueFrom.configMapKeyRef when you need specific keys or want to rename them. Use envFrom.configMapRef when you want the full ConfigMap as-is and the key names are valid env var names. The next lesson covers the second injection method: mounting ConfigMap data as files in a volume.