ConfigMaps and Secrets: configuration outside the image

A container image should be the same in development, test and production. What changes between environments, such as URLs, feature flags and passwords, belongs in ConfigMaps and Secrets. Both are key-value objects in a namespace, and Pods consume them as environment variables or as files in a mounted volume.

ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: web-config
data:
  LOG_LEVEL: info
  API_URL: http://api.shop.svc.cluster.local
  app.properties: |
    cache.size=256
    feature.search=true

kubectl create configmap web-config --from-literal=LOG_LEVEL=info --from-file=app.properties
kubectl get configmap web-config -o yaml

A ConfigMap cannot exceed 1 MiB. For larger data, use a volume or an external store.

Secret

kubectl create secret generic db-credentials \
  --from-literal=username=appuser \
  --from-literal=password='CHANGE_ME'

In YAML, values under data must be base64-encoded. The stringData field accepts plain text and the API server encodes it for you:

apiVersion: v1
kind: Secret
metadata:
  name: db-credentials
type: Opaque
stringData:
  username: appuser
  password: CHANGE_ME

Individual Secrets are limited to 1 MiB. Other built-in types include kubernetes.io/tls for certificates and kubernetes.io/dockerconfigjson for registry credentials.

Base64 is not encryption

Anyone who can read the Secret object can decode it in one command:

kubectl get secret db-credentials -o jsonpath='{.data.password}' | base64 -d

The Kubernetes documentation warns that Secrets are, by default, stored unencrypted in etcd, and that anyone allowed to create a Pod in a namespace can read every Secret in that namespace by mounting it. To protect them:

• Enable encryption at rest for Secrets on the API server.
• Use RBAC so that only the people and service accounts that need a Secret can get or list it.
• Mount Secrets only into the containers that need them.
• Consider an external secret store provider for high-value credentials.
• Never commit Secret manifests with real values to Git.

Using them in a Pod

spec:
  containers:
  - name: web
    image: registry.example.com/shop/web:1.4.0
    envFrom:
    - configMapRef:
        name: web-config
    env:
    - name: DB_PASSWORD
      valueFrom:
        secretKeyRef:
          name: db-credentials
          key: password
    volumeMounts:
    - name: config
      mountPath: /etc/web
      readOnly: true
  volumes:
  - name: config
    configMap:
      name: web-config

When changes take effect

• Environment variables are read once at container start. After changing a ConfigMap or Secret, restart the workload, for example with kubectl rollout restart deployment/web.
• Files from a mounted ConfigMap or Secret volume are updated automatically after a short delay, because the kubelet refreshes them during its periodic sync. Your application still has to re-read the file.
• A volume mounted with subPath never receives updates.

Setting immutable: true on a ConfigMap or Secret prevents accidental changes and reduces load on the API server. To change an immutable object you delete and recreate it under a new name.

Official documentation

• ConfigMaps
• Secrets