Kubernetes Job Controller

Kubernetes Job Controller is the control loop responsible for running Pods to completion rather than maintaining them indefinitely, tracking successful and failed completions against a target, and marking the Job itself finished once that target is met or a failure limit is exhausted. It is the workload controller purpose-built for bounded, run-to-completion work, batch processing, one-off migrations, scheduled computations, as opposed to the continuously running services that Deployments and StatefulSets manage.

Completion Tracking

completions and parallelism

spec.completions defines how many successful Pod completions are required for the Job to be considered done, while spec.parallelism bounds how many Pods may run concurrently while working toward that target.

apiVersion: batch/v1
kind: Job
metadata:
  name: job-controller-example
spec:
  completions: 10
  parallelism: 3
  template:
    spec:
      restartPolicy: OnFailure
      containers:
        - name: worker
          image: registry.example.com/worker:1.0.0

Non-Parallel Jobs

If neither completions nor parallelism is set, the Job defaults to requiring exactly one successful Pod completion, the simplest form, suited to single-shot tasks like a one-time database migration.

Failure Handling and backoffLimit

Bounded Retry Attempts

spec.backoffLimit caps how many times the controller will retry a failed Pod (or, for indexed completion mode, a failed index) before marking the Job itself as Failed, applying exponential backoff between attempts similarly to container-level restart backoff.

spec:
  backoffLimit: 4

restartPolicy Constraints

Jobs require restartPolicy to be either OnFailure or Never; Always is not permitted, since a Job Pod that always restarts on any exit, including success, could never reach the terminal state the controller needs to count as a completion.

Completion Modes

NonIndexed Versus Indexed

The default NonIndexed completion mode treats all Pod completions as interchangeable toward the completions target. Indexed mode instead assigns each Pod a unique completion index from 0 to completions - 1, exposed to the Pod through the JOB_COMPLETION_INDEX environment variable, allowing each Pod to work on a distinct, deterministic partition of the overall task.

spec:
  completionMode: Indexed
  completions: 5
  parallelism: 5

Job Status and Terminal Conditions

Succeeded and Failed Conditions

The controller updates status.succeeded and status.failed counts as Pods complete, and sets a Complete condition once the required number of successes is reached, or a Failed condition once backoffLimit is exhausted without reaching that target.

status:
  succeeded: 10
  conditions:
    - type: Complete
      status: "True"

activeDeadlineSeconds

spec.activeDeadlineSeconds imposes an overall wall-clock time limit on the Job, independent of backoffLimit; exceeding it causes the controller to terminate all running Pods and mark the Job Failed with reason DeadlineExceeded, regardless of how many completions remain outstanding.

spec:
  activeDeadlineSeconds: 3600

Pod Cleanup After Completion

ttlSecondsAfterFinished

Without additional configuration, completed Job Pods and the Job object itself remain in the cluster indefinitely for inspection. spec.ttlSecondsAfterFinished enables automatic cleanup, deleting the Job and its Pods a specified time after the Job reaches a terminal state.

spec:
  ttlSecondsAfterFinished: 86400

Job Controller Diagram

Once succeeded reaches completions, the controller stops creating new Pods, marks the Job Complete, and takes no further action beyond the optional TTL-driven cleanup, in sharp contrast to the continuous reconciliation a Deployment or StatefulSet performs for the entire life of the cluster.