ConfigMap projection: prove when a running process sees a new value

Last updated: 5 Oct 20266 min read

tutorial

A ConfigMap volume can receive updated files after the kubelet observes a change, but that propagation is eventual and depends on its synchronization and cache behavior. A ConfigMap consumed as an environment variable is fixed for the life of the container. A ConfigMap file mounted through subPath does not receive projected updates. Even when the file changes, an application that parsed it once still runs with its earlier in-memory value until it reloads or restarts.

Operational decision

A receipt router reads a routing weight from a mounted configuration file. Update a disposable ConfigMap while observing three timestamps: the API object's resource version, the content visible at the container path, and the router's reported active generation. Use an ordinary directory mount, then repeat with a subPath mount to expose the different behavior. For a process that supports reload, make it reopen the path and validate the complete new document before swapping its active configuration; preserve the previous generation if parsing fails. For an application that cannot reload safely, change the Pod template and perform a controlled rollout instead. Check the value on every replica, not a single Pod. The fragment mounts a directory, which allows the projected file to change; it does not make the application read it again. Keep a per-replica active-generation metric so a partially propagated update is visible during a release.

apiVersion: v1
kind: Pod
metadata:
  name: receipt-router-projection-check
  namespace: checkout
spec:
  containers:
    - name: router
      image: registry.internal/receipt-router:approved-build
      volumeMounts:
        - name: routing
          mountPath: /etc/receipt-routing
          readOnly: true
  volumes:
    - name: routing
      configMap:
        name: receipt-routing-live

Cost and verification

Propagation delay can leave replicas on different routing generations for a period. A forced restart removes that delay but creates rollout and capacity cost. Measure API-to-file delay, file-to-active delay, mixed-generation duration, and failed reloads. Do not use a rapid toggle as a distributed synchronization mechanism; a configuration change that requires atomic global cutover needs a separate coordination contract.

Common Mistakes

Do not assume an environment variable changes when its ConfigMap changes.
Do not use subPath for a file that must receive projected updates.
Do not call projection success an application reload without checking active behavior.

Connected lessons

Practice and check

devops

operations