Workload controllers

The handful of "I want N copies of this Pod" objects: Deployment, ReplicaSet, StatefulSet, DaemonSet, Job, CronJob. They are all built on the same controller framework patterns and share a remarkable amount of plumbing.

Where they live

Object	API types	Validation	Registry	Controller
Deployment	staging/src/k8s.io/api/apps/v1/types.go	pkg/apis/apps/validation/validation.go	pkg/registry/apps/deployment/	pkg/controller/deployment/
ReplicaSet	staging/src/k8s.io/api/apps/v1/types.go	pkg/apis/apps/validation/validation.go	pkg/registry/apps/replicaset/	pkg/controller/replicaset/
StatefulSet	staging/src/k8s.io/api/apps/v1/types.go	pkg/apis/apps/validation/validation.go	pkg/registry/apps/statefulset/	pkg/controller/statefulset/
DaemonSet	staging/src/k8s.io/api/apps/v1/types.go	pkg/apis/apps/validation/validation.go	pkg/registry/apps/daemonset/	pkg/controller/daemon/
Job	staging/src/k8s.io/api/batch/v1/types.go	pkg/apis/batch/validation/validation.go	pkg/registry/batch/job/	pkg/controller/job/
CronJob	staging/src/k8s.io/api/batch/v1/types.go	pkg/apis/batch/validation/validation.go	pkg/registry/batch/cronjob/	pkg/controller/cronjob/

Deployment

A Deployment owns a sequence of ReplicaSets, each representing a revision of the Pod template. The controller orchestrates rolling updates between revisions and tracks history via ControllerRevision (or, in the v1 era, embedded inside the Deployment's annotations).

Key flows:

• Rolling update — create a new ReplicaSet, scale it up by maxSurge, scale the old one down by maxUnavailable, repeat.
• Recreate — kill all old Pods first, then create new ones.
• Pause / Resume — hold the rollout in place.
• Rollback — set .spec.template back to a prior revision; the controller creates a fresh ReplicaSet matching the old template.

The controller is in pkg/controller/deployment/deployment_controller.go, with the bulk of the logic in pkg/controller/deployment/sync.go, …/rolling.go, …/recreate.go, …/rollback.go.

ReplicaSet

The simplest workload controller. Watches Pod and ReplicaSet; uses OwnerReferences to track pods it owns; creates or deletes pods to match spec.replicas. The legacy ReplicationController (the v1 API) is implemented as a thin wrapper that delegates to the same code path.

pkg/controller/replicaset/replica_set.go is the entry point. The shared adoption logic in pkg/controller/controller_ref_manager.go does the dance of "is this Pod mine?".

StatefulSet

Where ReplicaSet treats Pods as fungible, StatefulSet treats them as distinct identities:

• Pods are named <sts>-0, <sts>-1, … in order.
• Pods get a stable DNS hostname via the parent headless Service.
• Each Pod gets its own PVC bound on creation and preserved across rescheduling.
• Update / scale operations happen in order.

The controller is in pkg/controller/statefulset/. stateful_pod_control.go carries the per-Pod operations (create, update, delete) coordinated with the PVC. stateful_set_utils.go carries name generation and ordinal extraction. stateful_set_control.go is the main reconcile loop.

PVC management modes:

• Retain (default) — PVCs survive Pod deletion.
• Delete — PVCs are deleted when the Pod is.

DaemonSet

A DaemonSet runs one Pod per (matching) Node. Match logic is via spec.template.spec.nodeSelector, affinity, and toleration of node taints.

The controller is in pkg/controller/daemon/. The reconciler iterates Nodes, computes which Pods should exist, creates / deletes accordingly. Update strategies (OnDelete, RollingUpdate) follow the same shape as Deployment but operate at the per-Node level.

Job

A Job runs a Pod (or a parallel set) until spec.completions succeed.

Key fields:

• spec.parallelism — how many Pods can run at once.
• spec.completions — how many Pods must succeed to consider the Job complete.
• spec.completionMode — NonIndexed (default) vs Indexed (each Pod gets JOB_COMPLETION_INDEX from 0 to completions-1).
• spec.backoffLimit — failed-Pod budget before the Job fails.
• spec.activeDeadlineSeconds — wall-clock timeout.
• spec.podFailurePolicy — fine-grained "treat exit code N from this container as a Job failure / retry / ignore".
• spec.successPolicy (alpha) — declare success early when N specific indexed Pods complete.

The controller is in pkg/controller/job/job_controller.go. Indexed mode has its own sync path. The job tracker tracks finalizers on Pods so the Job knows for sure when each Pod has terminated, even if the Pod is GC'd before the controller observes it.

CronJob

A CronJob is a schedule-driven Job creator. Fields:

• spec.schedule — cron expression in the cluster's spec.timeZone (defaults to UTC).
• spec.timeZone — IANA tz; the binary's tzdata is embedded via _ "time/tzdata" in the controller-manager main.
• spec.concurrencyPolicy — Allow, Forbid, Replace.
• spec.startingDeadlineSeconds — drop missed runs older than this.
• spec.jobTemplate — a Job object template.

The controller is in pkg/controller/cronjob/cronjob_controllerv2.go. It computes the next run time, creates a Job, tracks history (spec.successfulJobsHistoryLimit, failedJobsHistoryLimit), and cleans up old Jobs.

Shared idioms

All six controllers share these helpers from pkg/controller/:

• PodControlInterface — typed wrapper for Pod create/delete with consistent owner refs and metrics.
• Expectations — track in-flight create/delete to avoid double-counting.
• ControllerRefManager — adopt or release children based on selector.
• controller.RealRSControl, etc. — the same idea for typed children.

A common bug class is forgetting to set up expectations correctly: the controller observes its own newly-created Pods on the next sync, double-counts them, and creates more than intended.

Pause-the-world for review

Most workload controllers honor spec.paused (Deployment) or equivalent (spec.suspend for Job and CronJob). When paused, the controller updates status but doesn't take action. Useful for:

• Holding a rollout while a human investigates.
• Stopping a CronJob without deleting it.
• Preventing a Job's backoff loop from continuing while a fix lands.