10.18 Kubernetes Job Completion Control

Kubernetes Job Completion Control is the specific set of fields and tracking mechanisms a Job uses to determine precisely when its designated work has finished, distinguishing between the different modes a Job can operate in and the corresponding criteria that must be satisfied before the Job as a whole is considered done and no further Pods are created.

Completion Mode Determination

NonIndexed Completion Mode

Under the default NonIndexed completion mode, the Job tracks only an aggregate count of successful Pod completions against the target specified by the completions field, without distinguishing between individual Pods beyond counting whether each one succeeded or failed, treating all successful completions as fungible toward the total.

Indexed Completion Mode

Under Indexed completion mode, each Pod created by the Job is assigned a completion index, exposed to the Pod through an environment variable and annotation, allowing the workload itself to know which specific portion of a larger, partitionable task it is responsible for, with the Job tracking success individually per index rather than as an undifferentiated aggregate count.

The completions Field

Defining the Success Target

The completions field specifies exactly how many successful Pod completions are required before the Job is considered finished, with the controller continuing to create replacement Pods for any that fail until this target number of successes has been reached or the retry limit is exhausted.

Omission for Work Queue Patterns

When completions is left unset while parallelism is specified, the Job instead relies on a work queue coordination pattern, where Pods themselves determine collectively when all necessary work is done, and the Job is considered complete once at least one Pod exits successfully with no other Pods still actively processing.

Tracking Successful and Failed Pods

succeeded and failed Status Counts

The Job's status reports succeeded and failed counts, reflecting the number of Pods that have reached each respective terminal state, giving a direct, numeric view into completion progress that can be monitored externally without needing to enumerate individual Pod objects.

Completed Indexes for Indexed Jobs

For Jobs using Indexed completion mode, the status additionally tracks which specific indexes have completed successfully, allowing partial progress to be understood at the granularity of individual work partitions rather than only as an aggregate total.

Completion Condition Reporting

The Complete Condition

Once the Job's completion criteria are satisfied, its status reflects a Complete condition set to true, serving as the definitive, machine-readable signal that no further Pods will be created and that the Job has successfully accomplished its designated work.

The Failed Condition

If the Job instead exhausts its retry attempts under backoffLimit or exceeds its activeDeadlineSeconds without reaching the required completions, its status reflects a Failed condition instead, marking the Job as permanently unsuccessful rather than merely still in progress.

Suspension and Its Effect on Completion Tracking

The suspend Field

Setting the suspend field to true pauses the Job, preventing the creation of new Pods and effectively halting progress toward completion without deleting the Job object itself or resetting any already-accumulated successful completion count, allowing a Job to be resumed later from where it left off.

Resuming Progress Toward Completion

Once unsuspended, the Job controller resumes creating Pods as needed to continue progressing toward its completion target, picking up exactly from the previously tracked success and failure counts rather than restarting its completion tracking from scratch.