Kubernetes Workload Pod Template Handling

Kubernetes Workload Pod Template Handling is the set of rules governing how a workload controller uses the embedded template field in its spec to stamp out Pod objects, and how it detects and reacts when that template changes. The Pod template is the single source of truth a controller consults every time it needs to create a new Pod, and the way controllers treat template changes differently, some triggering immediate rollout, others requiring manual replacement, is a key point of divergence between controller types.

Anatomy of a Pod Template

Embedded PodSpec With Metadata

A Pod template consists of metadata (primarily labels, which must be a superset of the controller's selector) and a full spec, identical in structure to a standalone Pod's spec, describing containers, volumes, and scheduling constraints.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: template-handling-example
spec:
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: app
          image: registry.example.com/app:1.0.0

Selector-Label Consistency Requirement

The API server validates that template.metadata.labels includes every key-value pair in spec.selector.matchLabels. A template whose labels do not satisfy the selector is rejected outright, since a controller that could not find its own created Pods through its selector would immediately begin creating duplicates.

Instantiation: Stamping Out Pods

Copy, Not Reference

When a controller creates a Pod, it copies the template's spec into a new Pod object rather than the new Pod referencing the template indirectly. This means each Pod is a fully independent object from creation onward; later changes to the controller's template have no retroactive effect on Pods already created from an earlier version.

kubectl get pod template-handling-example-abc123 -o yaml

Detecting Template Changes

Hash-Based Change Detection

Controllers commonly compute a hash of the Pod template (or a normalized subset of it) and store it as a label on generated objects, allowing a cheap equality check to determine whether the current template matches what a given batch of Pods was created from, without deep-comparing entire specs on every reconciliation pass.

metadata:
  labels:
    pod-template-hash: 7d4b9c8f6d

Divergent Reactions to Template Changes by Controller

Deployment: Automatic Rolling Update

A Deployment reacts to a template change by creating a new ReplicaSet stamped with the updated template hash and gradually scaling it up while scaling the old ReplicaSet down, according to its configured update strategy.

spec:
  strategy:
    type: RollingUpdate

StatefulSet: In-Place Sequential Replacement

A StatefulSet reacts to a template change by replacing existing Pods one at a time, in reverse ordinal order by default, preserving each Pod's name and associated storage while applying the new template.

DaemonSet: Rolling Node-by-Node Update

A DaemonSet reacts similarly to a Deployment but scoped per node, replacing the Pod on each node with a new one matching the updated template, respecting maxUnavailable to bound how many nodes are without a running Pod simultaneously.

Job: No Reaction At All

A Job's Pod template is effectively immutable in practice; most fields cannot be changed after creation, and Jobs have no update mechanism analogous to a rollout, since a Job represents a single, bounded unit of work rather than an ongoing desired state.

Template Handling Diagram

Understanding which pattern a given controller follows is essential before making a change to a Pod template in production, since the operational impact ranges from a fully automated, gradual rollout to a change that silently has no effect on already-running Pods at all.