Immutable Secrets & ConfigMaps: Write-Once Configuration

WHY IT EXISTS: By default, Kubernetes constantly checks for updates to Secrets and ConfigMaps used by running Pods. In a large cluster with thousands of Pods mounting the same configuration, this creates significant, constant load on the API server. Immutable objects solve this by telling Kubernetes "this will never change," eliminating the need for polling.

THE MENTAL MODEL: Think of immutable configuration as being like a versioned container image, such as myapp:1.2.0. You don't change the image at that tag; you build a new image, myapp:1.2.1, and deploy new containers. Similarly, you set immutable: true on a ConfigMap, and to update it, you create a new one (my-config-v2) and roll out new Pods that reference it.

HOW IT WORKS: You add the field immutable: true to a Secret or ConfigMap manifest before creating it. Once the object is created, the Kubernetes API server will reject any requests that try to change the data or stringData fields. The immutable field itself also cannot be changed. The only way to alter the configuration is to delete the object entirely and create a new one.

WHEN TO USE IT: Use this feature when configuration is stable and unlikely to change during a deployment's lifecycle. It's especially valuable in large-scale environments to improve cluster performance by reducing API server load. It also helps enforce a strict GitOps workflow, where configuration changes are explicit, versioned, and rolled out safely.

WHEN NOT TO USE IT: Avoid using this for configuration that you expect to update live, such as feature flags or dynamic settings that are changed without a full application redeployment. If you need to patch a ConfigMap and have running Pods pick up the change automatically, you must not make it immutable.

ONE CANONICAL EXAMPLE: A Secret containing the TLS certificate and private key for a web server. These credentials are typically generated once per release cycle. Making the Secret immutable prevents accidental modification and reduces the performance overhead of every web server Pod watching for changes to a file that will not change.