In Kubernetes, what does setting `immutable: true` on a ConfigMap or Secret actually do, and why would a team turn it on?

## The field Both `ConfigMap` and `Secret` have a top-level boolean field `immutable`. It defaults to absent/false. You can set it at creation time, or patch it onto an existing mutable object exactly once. After that the object is frozen. ```yaml apiVersion: v1 kind: ConfigMap metadata: name: app-config-7f2c1a data: LOG_LEVEL: info immutable: true ``` ## What exactly is frozen The API server validation rejects any update request that changes `data`, `binaryData` (ConfigMap) or `data`/`stringData` (Secret) on an object where `immutable` is true. It also rejects flipping `immutable` from true back to false or removing the field — the transition is one-way on purpose, otherwise the guarantee would be worthless (you could unfreeze, edit, refreeze). What is *not* frozen: object metadata. Labels, annotations, ownerReferences and finalizers can still be updated, so garbage-collection and tooling annotations keep working. And the object can still be **deleted**. Immutable does not mean permanent — it means "the bytes under this name never change while this name exists". The practical consequence: `kubectl edit configmap app-config` and `kubectl patch` on the data will fail with a validation error such as `field is immutable when immutable is set`. `kubectl apply` fails the same way, because apply is an update. `kubectl replace --force` "works" only because it deletes and recreates the object, which is a different and much more disruptive operation — for a moment the object does not exist, and any Pod that starts in that window fails to mount it. ## Why teams want it — safety A mutable ConfigMap mounted as a volume is a live wire. Edit it and the kubelet will, within a minute or so, rewrite the files inside every Pod that mounts it, on every node, with no rollout, no version record and no rollback other than editing it back. Applications that read config once at startup see nothing; applications that re-read see a change nobody deployed. Environment-variable consumers see nothing until they happen to restart — which means a Pod rescheduled at 3 a.m. silently picks up a config nobody intended to ship. Immutability converts that into an explicit, versioned deployment: a new object name, a new Pod template, a rolling update you can watch, pause and roll back. Config becomes as reviewable as an image tag. ## Why teams want it — scale The kubelet has to keep mounted ConfigMap and Secret contents fresh. With the default change-detection strategy it opens a watch on each object that a Pod on that node references. Across a large cluster this can be tens of thousands of individual watches, all held open by the API server, all costing memory and CPU there. If an object can never change, watching it is pure waste. The kubelet knows the flag and simply fetches the object once and stops. This was the motivating use case for the feature (alpha in 1.19, GA in 1.21) and it is the reason large platforms adopt it broadly rather than for the safety argument alone. ## The cost you accept You trade in-place edit for delete-and-recreate. Every change now produces a new object, which means you need a naming scheme (content hash or explicit version suffix) and a story for cleaning up old objects, or you accumulate garbage in etcd. Tooling that expects to write in place — a controller that renews a TLS certificate into an existing Secret, an operator that syncs from an external secret store — breaks against immutable objects unless it is written to create new ones. Check those integrations before switching a namespace over. ## How it interacts with consumers A Pod referencing an immutable ConfigMap behaves identically to one referencing a mutable one, except that the mounted files will never change for the lifetime of that Pod. `optional: true` still applies for missing objects. Nothing in the Pod spec needs to know about the flag.