Stage 5 · Platform
Configuration & Secrets Management
ConfigMap Design
Immutable ConfigMaps, rollout triggers, binary data, and application reload patterns.
ConfigMap Overview
ConfigMaps store non-sensitive configuration data as key-value pairs. They can be created from files, directories, or literal values. Pods consume ConfigMaps as environment variables or mounted volumes. ConfigMaps are namespace-scoped.
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
namespace: production
data:
LOG_LEVEL: "info"
DATABASE_HOST: "postgres-service"
DATABASE_PORT: "5432"
config.yaml: |
server:
port: 8080
readTimeout: 30s
writeTimeout: 30s
logging:
level: info
format: json
nginx.conf: |
server {
listen 80;
location / {
proxy_pass http://localhost:8080;
}
}ConfigMap data has two types: simple key-value pairs (LOG_LEVEL) and file-like content (config.yaml). The file content is stored as a string — the application must parse it.
Immutable ConfigMaps
Immutable ConfigMaps cannot be modified after creation. This prevents accidental changes and improves performance — kubelet doesn't re-fetch immutable ConfigMaps. Use immutable ConfigMaps for configuration that changes infrequently.
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config-v1
namespace: production
immutable: true
data:
config.yaml: |
server:
port: 8080
features:
enableNewUI: trueTo update an immutable ConfigMap: create a new ConfigMap with a version suffix, update the Deployment to reference the new ConfigMap, and delete the old one. This provides atomic configuration updates.
Immutable ConfigMaps prevent accidental modifications that could crash running pods. They also reduce API server load — kubelet doesn't watch them for changes. Use them for static configuration like nginx.conf or application config files.
Injection Methods
ConfigMaps can be injected as environment variables or mounted volumes. Environment variables are simple but cannot be updated without restarting. Volumes can be updated without restart (if not immutable) and support subPath mounts.
apiVersion: v1
kind: Pod
metadata:
name: config-demo
spec:
containers:
- name: app
image: my-app:1.0
# Environment variables
envFrom:
- configMapRef:
name: app-config
env:
- name: SPECIFIC_VALUE
valueFrom:
configMapKeyRef:
name: app-config
key: LOG_LEVEL
# Volume mount
volumeMounts:
- name: config-volume
mountPath: /etc/config
readOnly: true
volumes:
- name: config-volume
configMap:
name: app-config
items:
- key: config.yaml
path: config.yaml
- key: nginx.conf
path: nginx.confenvFrom injects all ConfigMap keys as environment variables. env injects a specific key. Volume mount makes files available at /etc/config/config.yaml and /etc/config/nginx.conf.
Application Reload Patterns
When a ConfigMap changes, pods using volume mounts can detect the change. Applications need a reload mechanism: inotify (file watch), periodic reload, or restart on annotation change. Stakater Reloader automates restarts on ConfigMap changes.
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
annotations:
reloader.stakater.com/auto: "true"
spec:
replicas: 3
template:
metadata:
annotations:
config-hash: "placeholder"
spec:
containers:
- name: app
volumeMounts:
- name: config
mountPath: /etc/config
volumes:
- name: config
configMap:
name: app-configStakater Reloader watches ConfigMaps referenced in Deployments. When the ConfigMap changes, it updates the config-hash annotation, triggering a rolling restart. This ensures pods always use the latest configuration.
Binary Data
ConfigMaps support binary data (base64-encoded). Use this for binary files: certificates, keystores, or compiled configuration. The binary data is decoded when mounted as a volume.
apiVersion: v1
kind: ConfigMap
metadata:
name: binary-config
binaryData:
keystore.p12: <base64-encoded-binary>
ca.crt: <base64-encoded-cert>
data:
application.properties: |
server.ssl.key-store=file:/etc/config/keystore.p12
server.ssl.trust-store=file:/etc/config/ca.crtbinaryData stores base64-encoded binary files. When mounted, the files are decoded to their original binary form. Use kubectl create configmap --from-file to create ConfigMaps from binary files.
Design Best Practices
- Separate ConfigMaps per concern — not one giant ConfigMap for everything
- Use immutable ConfigMaps for static configuration
- Version ConfigMaps when changing configuration atomically
- Use Reloader or similar for automatic restarts on ConfigMap changes
- Never store secrets in ConfigMaps — use Secrets or External Secrets
- Set resource requests for pods using ConfigMaps to prevent eviction
ConfigMaps are limited to 1MB in etcd. For larger configuration, split into multiple ConfigMaps or use external storage (S3, Azure Blob). Monitor ConfigMap count per namespace — too many ConfigMaps slow down API server watches.
Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.