What Are Immutable ConfigMaps and Secrets?

Detailed Answer

Immutable ConfigMaps and Secrets (stable since Kubernetes 1.21) are configuration objects that cannot be modified after creation. This provides both safety and performance benefits.

Making a ConfigMap Immutable

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config-v1
data:
  DATABASE_HOST: "postgres.prod.svc.cluster.local"
  LOG_LEVEL: "warn"
  CACHE_TTL: "300"
immutable: true

Once created, any attempt to modify the data fails:

kubectl edit configmap app-config-v1
# Error: ConfigMap "app-config-v1" is immutable

kubectl patch configmap app-config-v1 -p '{"data":{"LOG_LEVEL":"debug"}}'
# Error: ConfigMap "app-config-v1" is immutable

Performance Benefits

In large clusters, the kubelet on every node watches every ConfigMap and Secret referenced by its Pods. This creates significant API server load:

Without immutable:
  1000 nodes × 10 ConfigMaps each = 10,000 active watches on the API server
  Each watch consumes API server memory and network resources

With immutable:
  Kubelet does not watch immutable ConfigMaps
  10,000 watches → 0 watches (for immutable objects)

For clusters with hundreds of nodes, this can meaningfully reduce API server CPU and memory usage.

Safety Benefits

Immutable ConfigMaps prevent:

• Accidental changes to production configuration via kubectl edit
• Unauthorized modifications by users with broad RBAC permissions
• Configuration drift where some Pods see updated values while others do not

Update Workflow

Since immutable ConfigMaps cannot be modified, use a versioned naming strategy:

# Version 1
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config-v1
data:
  LOG_LEVEL: "warn"
immutable: true
---
# Version 2 (with updated values)
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config-v2
data:
  LOG_LEVEL: "debug"
immutable: true

Update the Deployment to reference the new ConfigMap:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
spec:
  template:
    spec:
      containers:
        - name: app
          image: myapp:v2
          envFrom:
            - configMapRef:
                name: app-config-v2    # Updated reference
          resources:
            requests:
              cpu: "250m"
              memory: "256Mi"

This triggers a rolling update, ensuring all Pods consistently use the new configuration.

Content-Hash Naming Pattern

Many tools (Helm, Kustomize) automate this with content-based hashing:

# Kustomize appends a hash suffix
kubectl kustomize .
# ConfigMap: app-config-7hf28m9g   (hash based on contents)

# kustomization.yaml
configMapGenerator:
  - name: app-config
    literals:
      - LOG_LEVEL=warn
    options:
      immutable: true

When the data changes, the hash changes, creating a new ConfigMap name. The Deployment template is automatically updated to reference the new name.

Immutable Secrets

The same immutable: true field works for Secrets:

apiVersion: v1
kind: Secret
metadata:
  name: db-credentials-v1
type: Opaque
data:
  password: c2VjcmV0MTIz
immutable: true

When to Use Immutable

| Scenario | Use Immutable? | |---|---| | Production configuration | Yes — prevents accidental changes | | Large clusters (100+ nodes) | Yes — reduces API server load | | Configuration that changes frequently | Consider it — versioned updates are explicit | | Development environments | Optional — mutability is more convenient | | Shared configuration across many Pods | Yes — greatest performance benefit |

One-Way Toggle

Setting immutable: true on an existing mutable ConfigMap is allowed:

kubectl patch configmap app-config -p '{"immutable":true}'

But you cannot set it back to false:

kubectl patch configmap app-config -p '{"immutable":false}'
# Error: field "immutable" is immutable

To regain mutability, delete and recreate the ConfigMap.