Chapter 21 of 47 · Configuration and resources

Immutable configuration and config templates

A ConfigMap you can edit at any time is handy, and dangerous. One quick edit changes production with no review, no history, and no easy way back. This chapter shows two habits that make config as safe as code: never edit config, release a new version of it, and, for big config files, keep one template and fill in only the parts that differ.

The problem with editing live config

Imagine changing the recipe card in a busy kitchen while cooks are using it. Some dishes follow the old card, some the new one, and nobody remembers what the old card said.

immutable: true

One line locks a ConfigMap or Secret. After it is created, its data can never be changed:

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config-v1
immutable: true
data:
  LOG_LEVEL: info
  MAX_UPLOAD_MB: "10"

$ kubectl edit configmap app-config-v1
error: configmaps "app-config-v1" is invalid: data: Forbidden: field is immutable when `immutable` is set

• Safer: no accidental live edits.
• Lighter: the kubelet stops watching it for changes, which helps clusters with thousands of ConfigMaps.
• One way only: you cannot switch immutable back off. To change values, create a new ConfigMap (or delete and recreate this one).

Versioned names

Give each version its own name, and point the Deployment at the version it should use:

Let a tool name the versions

Renaming by hand is easy to forget. Kustomize, built into kubectl, generates the ConfigMap and adds a short hash of its content to the name. Change any value and the name changes, so the Deployment rolls automatically:

# kustomization.yaml
resources:
  - posts-depl.yaml
configMapGenerator:
  - name: app-config
    literals:
      - LOG_LEVEL=info
      - MAX_UPLOAD_MB=10

$ kubectl apply -k .
configmap/app-config-5g2h7mt9kc created
deployment.apps/posts-depl configured

Helm users get the same effect with a checksum/config annotation on the Pod template: a hash of the config file, so any config change alters the template and triggers a rollout.

Config inside an image

Another way to make config versioned and unchangeable: package the config files into their own small container image, such as posts-config:prod-2026-10. An init container copies them into a shared emptyDir (chapter 30) before the app starts.

initContainers:
  - name: config
    image: registry.example.com/posts-config:prod-2026-10
    command: ["cp", "-r", "/config/.", "/etc/app/"]
    volumeMounts: [{ name: app-config, mountPath: /etc/app }]
containers:
  - name: posts
    image: micro-posts:1.0
    volumeMounts: [{ name: app-config, mountPath: /etc/app }]
volumes:
  - name: app-config
    emptyDir: {}

When it is worth it: config bigger than a ConfigMap's 1 MiB limit, or when you want config to go through the same registry, scanning and promotion steps as your images. Otherwise immutable ConfigMaps are simpler.

Configuration templates

Sometimes a config file is long, but only a few lines differ between dev and production. Copying the whole file per environment means three files that slowly drift apart. Instead, keep one template with placeholders, and fill them in when the Pod starts:

# ConfigMap posts-proxy-template, key default.conf.template
server {
  listen 8080;
  client_max_body_size ${MAX_UPLOAD_MB}m;
  location / {
    proxy_pass http://${UPSTREAM_HOST}:4000;
  }
}

containers:
  - name: proxy
    image: nginx:1.27
    env:
      - name: MAX_UPLOAD_MB
        value: "10"
      - name: UPSTREAM_HOST
        value: posts-srv
    volumeMounts:
      - name: templates
        mountPath: /etc/nginx/templates      # nginx fills these in at startup
volumes:
  - name: templates
    configMap:
      name: posts-proxy-template

$ kubectl exec deployment/posts-proxy -- cat /etc/nginx/conf.d/default.conf
server {
  listen 8080;
  client_max_body_size 10m;
  location / {
    proxy_pass http://posts-srv:4000;
  }
}

Which approach?

Recap

• Editing live config causes drift between Pods and makes rollback impossible.
• immutable: true locks a ConfigMap or Secret for good and lightens the kubelet's work.
• Versioned names (-v2, or a Kustomize hash) turn a config change into a normal rolling update with real rollback.
• Config images carry big or tightly controlled config, copied in by an init container.
• Templates keep one file and fill in per-environment values at startup.

Quick check