Kubernetes Configuration Guidelines

Kubernetes Configuration Guidelines describe the practices for supplying runtime configuration — environment-specific values, feature flags, connection strings, and other non-secret settings — to workloads using ConfigMap objects and related mechanisms, so that the same container image can run correctly across multiple environments without being rebuilt, and so that configuration changes can be tracked, reviewed, and rolled out independently of application code.

ConfigMap Fundamentals

Externalizing Configuration From Images

Configuration values baked directly into a container image require a rebuild and redeploy for even a trivial change, and make the same image unusable across environments with different settings. ConfigMap objects hold that configuration outside the image, consumed by containers via environment variables, command-line arguments, or mounted files, letting one image be promoted unchanged from development through production.

Consumption Patterns

Environment variable injection (envFrom or individual valueFrom.configMapKeyRef entries) suits simple scalar values read once at process start. Volume-mounted ConfigMaps suit larger configuration (full config files) and, unlike environment variables, can be updated in a running Pod without a restart if the application watches the mounted file for changes — though many applications don't implement that watching, so this benefit depends on the application's own design.

Immutable ConfigMaps

Setting immutable: true on a ConfigMap prevents any further modification to its data, which improves scheduler performance at scale (the kubelet no longer needs to watch it for changes) and eliminates an entire class of incidents caused by an in-place edit to a ConfigMap silently changing behavior for every Pod referencing it without a corresponding rollout.

Structuring Configuration

One ConfigMap Per Logical Concern

Grouping configuration by logical concern (database connection settings, feature flags, logging configuration) rather than a single monolithic ConfigMap per application makes ownership, review, and the blast radius of a change clearer — a change to logging configuration shouldn't require touching the same object that holds database connection settings.

Avoiding Duplication Across Environments

Environment-specific values (a hostname that differs between staging and production) should be isolated into small, environment-specific ConfigMaps or injected via a templating/overlay system (such as Kustomize), keeping the bulk of configuration shared and reducing the chance that an environment-specific override is forgotten when a shared value changes.

Validating Configuration Before Rollout

Because ConfigMaps are opaque key-value data to the Kubernetes API — there is no schema validation of their contents by default — a malformed value (invalid JSON, a typo in a flag name) is only caught when the consuming application fails to start or misbehaves at runtime. CI validation of ConfigMap contents against an expected schema, before they're applied, catches this earlier than production.

Rollout Coordination

ConfigMap Changes Don't Automatically Restart Pods

Updating a ConfigMap does not, by itself, trigger a rollout of Pods consuming it via environment variables — those Pods keep the values they had at creation time until they are recreated for some other reason. This is a frequent source of confusion: an operator updates a ConfigMap expecting immediate effect, but the running Pods remain on the old configuration until an explicit rollout is triggered.

Triggering Rollouts on Configuration Change

A common pattern is to embed a hash of the ConfigMap's contents into a Pod template annotation, so that any change to the ConfigMap's data changes the Pod template itself, triggering a normal rolling update through the same safety mechanisms (readiness gating, maxUnavailable) that apply to an image change — treating configuration changes with the same rollout discipline as code changes.

Distinguishing Configuration From Secrets

ConfigMaps Are Not Encrypted at Rest by Default

ConfigMap data is stored in plaintext in etcd unless the cluster has encryption at rest configured, and is readable by anyone with API access to read ConfigMaps in that namespace. Sensitive values — credentials, tokens, keys — belong in Secret objects, which at minimum signal intent and are handled with tighter default RBAC visibility in many cluster configurations, not in ConfigMaps regardless of convenience.

Consistent Handling at the Application Layer

Because both ConfigMaps and Secrets can be consumed identically (as environment variables or mounted files), application code should be written to treat the two sources uniformly at the consumption layer while the cluster operator maintains the distinction at the storage and access-control layer.

Scale and Size Considerations

Size Limits

A single ConfigMap is limited to 1MiB total size (the etcd object size limit), which is a hard constraint that pushes genuinely large configuration payloads toward being packaged as part of the image, fetched from an external configuration service at startup, or split across multiple ConfigMaps if truly independent.

Avoiding Configuration Sprawl

A cluster accumulating hundreds of loosely-tracked, rarely-reviewed ConfigMaps over time becomes difficult to audit for what's actually in use versus stale. Periodic review — cross-referencing ConfigMaps against the workloads that actually reference them — keeps configuration inventory tractable.

Example Configuration

apiVersion: v1
kind: ConfigMap
metadata:
  name: codartium-api-config
  namespace: codartium
immutable: true
data:
  LOG_LEVEL: "info"
  REQUEST_TIMEOUT_SECONDS: "30"
  FEATURE_NEW_CHECKOUT: "true"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: codartium-api
spec:
  template:
    metadata:
      annotations:
        checksum/config: "a1b2c3d4"
    spec:
      containers:
        - name: codartium-api
          image: registry.example.com/codartium-api@sha256:cd12ef...
          envFrom:
            - configMapRef:
                name: codartium-api-config

Practical Consequences

Disciplined configuration management produces images that are portable across environments without modification, configuration changes that roll out safely through the same mechanisms as code changes, and a clear boundary between ordinary settings and sensitive values. Neglecting these guidelines commonly results in configuration drift between environments that's only discovered when a workload misbehaves in one but not another, silent staleness where Pods keep running on outdated configuration long after an update was believed to have taken effect, or sensitive values leaking into plaintext ConfigMaps that were never intended to hold them.