Kubernetes ConfigMap Live Reload Prompt

You are a senior Kubernetes engineer who has debugged "I updated the ConfigMap but the app didn't pick it up" countless times. You know the env vs mount difference, the kubelet sync interval, and how immutable ConfigMaps simplify scale.

I will provide:
- The ConfigMap and how it's consumed (env vars, volume mount, projected)
- The symptom (app didn't reload, partial reload, mount stale)
- Pod spec showing consumption

Your job:

1. **Consumption modes and reload behavior**:
   - **env vars (`valueFrom.configMapKeyRef`)** — captured at pod start; NEVER updates
   - **volume mount (`configMap` volume)** — kubelet syncs every ~60s by default; symlink swap
   - **subPath mount** — DOES NOT auto-update (kernel mount-point bind)
   - **projected volume** — same as configMap volume sync
2. **For "app didn't reload"**:
   - Most apps don't watch their own config files
   - They re-read on SIGHUP or restart
   - Solution: app supports config reload OR restart pod on change
3. **For volume mount with subPath**:
   - Single-file mount via subPath breaks the symlink swap
   - File stays as it was at pod start
   - Use full directory mount + symlink in app
4. **For projected volumes (multi-source)**:
   - Combines ConfigMap + Secret + downward API + serviceAccountToken
   - All updated by same kubelet sync
5. **For immutable ConfigMaps** (1.21+):
   - `immutable: true` prevents updates → faster kubelet
   - Force "new" config by creating new ConfigMap with version suffix
6. **For automated pod restart on change**:
   - Stakater Reloader: annotation triggers rolling restart
   - Manual: bump a Deployment annotation (e.g., `configHash`) to trigger rollout
7. **For kubelet sync interval**:
   - Configurable via `--sync-frequency`
   - Default 60s for ConfigMap/Secret volumes
8. **For multi-replica updates**:
   - Volume sync is per-pod; replicas update at slightly different times
   - For ordered updates: rolling restart with managed deployment

Mark DESTRUCTIVE: editing ConfigMap with `immutable: true` (fails; recreate required), running `kubectl rollout restart` repeatedly without addressing root cause.

---

ConfigMap consumption: [env / volume mount / projected / subPath]
Symptom: [DESCRIBE]
Pod spec excerpt:
```yaml
[PASTE]
```

Why this prompt works

ConfigMap live reload has subtle rules that frustrate teams: env vars don’t update, subPath blocks updates, apps don’t reload by themselves. This prompt walks the rules.

How to use it

1. Identify consumption mode first.
2. For “didn’t reload”, check app behavior — most apps need restart.
3. For automated, use Reloader or annotation pattern.
4. For atomicity, projected volumes.

Useful commands

# Inventory
kubectl get configmap -A
kubectl describe configmap <name>
kubectl get cm <name> -o yaml

# Find pods consuming
kubectl get pods -o json | jq -r '
    .items[] | . as $p |
    (.spec.containers[].env // [])[] | select(.valueFrom.configMapKeyRef.name) |
    "\($p.metadata.namespace)/\($p.metadata.name) env: \(.valueFrom.configMapKeyRef.name)"
'

kubectl get pods -o json | jq -r '
    .items[] | . as $p |
    (.spec.volumes // [])[] | select(.configMap.name) |
    "\($p.metadata.namespace)/\($p.metadata.name) volume: \(.configMap.name)"
'

# Force restart on ConfigMap change
kubectl rollout restart deploy <deployment>

# Check kubelet sync interval (on a node)
sudo ps -ef | grep kubelet | grep sync-frequency

# Check what's mounted in pod
kubectl exec <pod> -- ls -la /etc/config/

# Verify content
kubectl exec <pod> -- cat /etc/config/app.yaml

Patterns

Volume mount with live update

apiVersion: v1
kind: Pod
metadata:
  name: web
spec:
  containers:
  - name: app
    image: myapp
    volumeMounts:
    - name: config
      mountPath: /etc/config       # Mount the whole directory; DON'T use subPath
  volumes:
  - name: config
    configMap:
      name: web-config

The app reads from /etc/config/; kubelet syncs ~60s. App must reload on file change OR use SIGHUP.

Reloader annotation (auto restart on change)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  annotations:
    configmap.reloader.stakater.com/reload: "web-config,db-config"
    secret.reloader.stakater.com/reload: "web-secrets"
spec:
  template:
    spec:
      containers:
      - name: app
        image: myapp

Install Stakater Reloader; it watches and triggers rollouts.

Version-pinned (immutable)

apiVersion: v1
kind: ConfigMap
metadata:
  name: web-config-v3
immutable: true
data:
  app.yaml: |
    log_level: info
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  template:
    spec:
      containers:
      - name: app
        envFrom:
        - configMapRef:
            name: web-config-v3     # bump to v4 to deploy new config

Manual rolling restart via annotation hash

spec:
  template:
    metadata:
      annotations:
        configHash: ${CONFIG_HASH}   # Set in CI/CD to MD5 of config content

When CONFIG_HASH changes, deployment rolls.

Common findings this catches

• env var reference, expected live reload → impossible; switch to volume mount + app reload.
• subPath mount of single file → no live update; switch to directory mount.
• App reads config once at start → needs SIGHUP handler or restart on change.
• Slow propagation (>2 min) → kubelet sync-frequency too high; OR app not reading.
• Reloader missing annotation → silent no-op.
• Immutable ConfigMap edit attempt → rejected; create new version.
• Multi-replica update timing — each pod syncs independently; brief inconsistency.

When to escalate

• App doesn’t support config reload — engage app team for SIGHUP or restart pattern.
• Reloader causing restart storms — audit which ConfigMaps trigger it.
• Critical config that needs atomic update across replicas — use immutable + deploy.