Required configuration keys: fail startup before accepting traffic

Last updated: 1 Oct 20266 min read

tutorial

A Pod that references a required ConfigMap or Secret key cannot start its container when the object or key is absent. Marking the reference optional changes that failure mode into an absent value, which may be worse if the application falls back to an unsafe default. An envFrom source also deserves inspection: keys that cannot become valid environment variable names can be skipped while the Pod continues starting.

Operational decision

A claims service needs an immutable policy generation and a signing key identifier. Use explicit key references instead of sweeping an entire object into the process environment. Create both resources before the rollout, verify their names and keys in the target namespace, and use an init or application startup check to validate syntax and compatibility. The fragment shows a required non-secret key; the signing material should be a separate Secret reference scoped to the component that needs it. Exercise three failure cases in a disposable namespace: missing object, misspelled key, and syntactically invalid policy. The first two should stop container creation; the last needs an application validation failure before readiness. Inspect Pod events and startup logs without printing secret values. Only mark a key optional after defining an explicit safe fallback and a test for that absence. Promote the new Pod only when it reports the expected configuration generation and passes a user-path check.

apiVersion: v1
kind: Pod
metadata:
  name: claims-policy-check
  namespace: checkout
spec:
  containers:
    - name: policy-check
      image: registry.internal/claims-policy:approved-build
      env:
        - name: POLICY_GENERATION
          valueFrom:
            configMapKeyRef:
              name: claims-policy-r47
              key: generation
              optional: false

Cost and verification

Failing startup early spends rollout time and capacity but prevents a process from serving with guessed configuration. Measure missing-reference events, startup validation failures, time to rollback, and the number of Pods that accepted traffic on an unexpected generation. Explicit references add manifest maintenance; they also make the runtime contract reviewable. A healthy readiness probe is meaningful only if it checks the validated configuration actually used by the request path.

Common Mistakes

Do not use optional true to hide an unplanned missing key.
Do not assume envFrom imported every key merely because the container started.
Do not print secret contents while diagnosing a configuration startup error.

Connected lessons

Practice and check

devops

operations