Last reviewed: November 13, 2026 (Asia/Shanghai); official Kubernetes references retrieved November 12, 2026 UTC.

Direct answer

Review a standalone Kubernetes Job by first stating what one completion means, then checking whether the rendered batch/v1 object counts interchangeable Pods, fixed indexes, or work-queue progress. Calculate the permitted parallelism and retry budget, inspect the interaction between restartPolicy, backoffLimit, failure policy, and activeDeadlineSeconds, and bind every status observation to the candidate Job and Pod identities. Use a bounded kubectl wait command to collect controller evidence, but require application-level evidence separately. A Job reaching Complete proves that the controller met its completion rule; it does not prove that the intended records, files, or external effects were produced exactly once.

The Kubernetes Jobs reference defines the controller’s completion, retry, suspension, and cleanup behavior. The Job v1 API reference defines the fields and status counters a review should capture. The kubectl wait reference explains how to wait for conditions or JSONPath values with a timeout. Together they support a review that connects the manifest to a specific workload result.

Who this is for

Use this workflow when a coding agent edits a standalone batch/v1 Job, its Pod template, a Helm value, or a Kustomize overlay that renders one. It is also useful when a patch changes the worker command, completion count, index handling, retry policy, deadline, suspension switch, or cleanup timing. A CronJob creates Jobs but has its own schedule and overlap contract; use the CronJob review guide when the scheduled controller is part of the change.

Give the agent the target Kubernetes version, the number and identity of work items, the allowed overlap, the retry and recovery policy, the resource ceiling, and the evidence that an application owner considers a successful run. Ask for the rendered object and a before-and-after explanation of every changed field. The examples below are review fixtures and proposed acceptance checks; no authenticated cluster tests or deployments were performed for this article.

Key takeaways

  • A non-parallel Job, a fixed-completion Job, and a work-queue Job have different success contracts.
  • parallelism is an upper target, not a promise that that many Pods will run.
  • An Indexed Job counts one successful Pod per index; duplicate Pods for an index can still start.
  • restartPolicy, Job retries, and application idempotency are separate decisions.
  • activeDeadlineSeconds stops the Job even when its backoff budget remains.
  • Suspension terminates active work and resets the active timer when the Job resumes.
  • Controller conditions and kubectl wait output must be retained with Pod and candidate identities.

Sources checked

Three primary Kubernetes references were retrieved successfully on November 12, 2026 UTC:

  • Jobs documents the three Job patterns, defaults, parallel execution, completion modes, Pod failure behavior, backoff and per-index limits, suspension, terminal conditions, and automatic cleanup. The page reports an October 12, 2026 modification.
  • Job v1 API reference defines JobSpec and JobStatus, including completion and retry fields, suspend, startTime, active, succeeded, failed, and terminal conditions. The generated v1.37 reference reports an August 26, 2026 update.
  • kubectl wait documents condition and JSONPath waits, sequential multiple conditions, and the default 30-second timeout. The generated v1.37 reference reports an August 26, 2026 update.

These maintained platform references support an evergreen review task. Their retrieval dates establish when the documentation was checked, rather than when the behavior was introduced. Match fields and feature availability to the target server version; the references do not establish the target cluster’s quotas, scheduler capacity, controller settings, or application semantics.

Contract details to verify

Choose the completion model before reading the numbers

Render every affected environment from the candidate revision. Record the namespace, Job UID if a fixture already exists, Pod template, command, image, restart policy, resource requests, completions, parallelism, completion mode, and any failure or cleanup fields. Leave the selector to Kubernetes unless the patch has a documented reason to manage it: the API reference warns that a manually chosen selector must be unique, or another Job’s Pods can be counted.

Write the application contract in one sentence. For example: “Process four independent partitions, accept one successful result for each partition, allow two workers at once, and keep a failed partition visible for repair.” That is a fixed-completion contract. A single one-off task can omit completions and parallelism, which default to one. A work-queue Job omits completions and lets workers coordinate through the queue; a successful worker tells the controller that no new Pods are needed, so the workers must stop producing work when the queue is drained. Do not approve a change until the chosen pattern matches the program.

For the fixed-partition example, this fragment belongs inside an existing Job’s spec; it omits the reviewed image, resources, and command:

completions: 4
parallelism: 2
completionMode: Indexed
backoffLimitPerIndex: 1
maxFailedIndexes: 1
activeDeadlineSeconds: 900
ttlSecondsAfterFinished: 86400
template:
  spec:
    restartPolicy: Never

Indexed requires a completion count and gives each intended index a value from zero through completions - 1. The worker can read JOB_COMPLETION_INDEX; the review should also check the rendered Pod annotation or label on the target version. maxFailedIndexes only applies with per-index backoff. These fields describe controller accounting, not the correctness of the partition output.

Check parallelism and index identity

parallelism is the maximum desired number of Pods at one instant. Actual concurrency can be lower because the controller has not reacted, quota or permission blocks Pod creation, capacity is unavailable, or the controller throttles after repeated failures. For a fixed-completion Job, the controller also cannot run more Pods than the remaining completions. Capture the requested and observed values rather than calling a short-lived two-Pod sample a guaranteed concurrency limit.

For an Indexed Job, write the expected index-to-output table before running it. A Pod for index 2 must read and write partition 2, not choose a random queue item. The Jobs reference warns that node failures, kubelet restarts, or evictions can start more than one Pod for the same index; only the first successful Pod counts, and the controller removes other Pods after detecting the duplicate. Make the output key include the logical index and use an atomic or documented idempotency mechanism. The same rule protects a non-indexed Job when a replacement Pod starts after an uncertain external write.

When the patch changes resource requests or scheduling constraints, use the Kubernetes requests and limits review as a separate acceptance task. A Job can remain pending because it is unschedulable, not because its work completed.

Separate container restarts, Pod retries, and Job failure

With restartPolicy: OnFailure, a failed container can run again inside the same Pod. With Never, a failed Pod can cause the Job controller to create another Pod. In both cases the application may run more than once. The Jobs reference explicitly warns that even parallelism: 1, completions: 1, and restartPolicy: Never do not guarantee one program start. Require an idempotency key, a durable work claim, or a reconciliation step before approving a side effect.

backoffLimit is the Job-level retry budget and defaults to six unless per-index backoff is used. Failed Pods are recreated with an exponential delay that begins at ten seconds and is capped at ten minutes. A podFailurePolicy can count, ignore, fail the Job, or fail an index based on exit codes or Pod conditions; it requires restartPolicy: Never and rules are evaluated in order. Review whether a disruption should consume a retry and whether an application error should stop all remaining work.

For an Indexed Job, backoffLimitPerIndex keeps failure accounting separate by index. A failed index does not interrupt other indexes until the overall policy says so. maxFailedIndexes terminates the remaining running Pods after the configured number is exceeded. Preserve the completedIndexes and failedIndexes status strings; a single succeeded count hides which partitions still need repair.

Bound the deadline and status observation

activeDeadlineSeconds applies to the Job’s active duration, regardless of how many Pods or retries it uses, and it takes precedence over backoffLimit. The API reference says the timer is relative to startTime; suspension stops and resets that timer on resume. Keep the Job-level field distinct from any container or Pod deadline. A Job that reaches its deadline is permanently failed and requires an authorized recovery action; it does not automatically restart as a new Job.

Record the Job UID, generation, candidate digest or source revision, startTime, desired counts, and status conditions before launching the fixture. Then collect the exact Pods by the controller-generated Job label, keeping Pod UIDs, index values, restart counts, exit codes, deletion timestamps, and logs. A successful Complete condition is a controller result, not an application assertion.

For a fixture called partition-job, these read-only waits are bounded examples; replace the context and namespace explicitly:

kubectl --context review-cluster --namespace agent-review \
  wait --for=condition=Complete job/partition-job --timeout=15m

kubectl --context review-cluster --namespace agent-review \
  get job/partition-job -o json > review-job.json

kubectl --context review-cluster --namespace agent-review \
  wait --for=jsonpath='{.status.succeeded}'=4 \
  job/partition-job --timeout=15m

The command reference supports conditions, JSONPath values, creation and deletion waits, and multiple conditions. A wait timeout is evidence that the requested observation was not reached within the window; it does not diagnose quota, scheduling, application, or controller causes. Check exit status and inspect the saved object and Pod events. Use a JSONPath check only when an empty or exact value is a deliberate contract; a missing field can indicate an earlier state rather than success.

Exercise suspension, cleanup, and recovery

Use an approved disposable namespace with synthetic data. Establish a healthy baseline and restore it between cases. These are proposed checks, not reported results:

Controlled caseEvidence to require
Four indexed partitions with two workersEach expected index has one accepted output; Job and Pod status identify the same candidate
One partition exits with a retryable errorReplacement Pod and per-index retry evidence; no duplicate business effect
One partition exits with a non-retryable codeFailure policy matches the intended action; remaining work and final condition are explained
A worker exceeds the active deadlineDeadlineExceeded, terminated Pods, partial-output reconciliation, and an explicit recovery decision
Job is suspended while Pods are active, then resumedActive Pods receive graceful termination; startTime and deadline behavior match the target version
Finished Job reaches its TTLLogs and status are exported before cascading deletion; cleanup does not erase the review record

Suspending a Job is a lifecycle action, not a pause that preserves an active process. The controller terminates active Pods, and the API reference says resuming resets startTime and the active timer. Make the worker handle termination signals by checkpointing or safely abandoning its claim. If the Job was created suspended, no Pods should exist until an authorized resume.

ttlSecondsAfterFinished makes a Complete or Failed Job eligible for cascading deletion. Choose the retention window from the debugging and audit requirement, and export logs, status, and application output before the window expires. Do not use TTL as the only business audit trail.

Failure modes

The patch calls parallelism an exact worker count. Capture requested and observed Pods, then explain quota, scheduling, controller reaction, and remaining-completion limits.

A green Job condition is treated as exactly-once processing. Bind outputs to index or work keys and test a retry after an uncertain write.

A manually chosen selector overlaps another Job. Let the controller generate labels unless a unique selector is reviewed from the rendered objects.

backoffLimit is described as a total runtime limit. Review the retry budget and activeDeadlineSeconds independently; the deadline wins when both could terminate the Job.

A timeout is called an application failure. Inspect Job conditions, Pod events, scheduling evidence, and the saved candidate before assigning a cause.

TTL cleanup removes the only evidence. Export logs and status before the retention window, and keep the application result in a durable audit record.

FAQ

Does restartPolicy: Never make a Job exactly once?

No. A failed or disrupted Pod can be replaced, and the same program can start twice even with one completion and one requested worker. Make side effects idempotent and reconcile uncertain outcomes.

Is an Indexed Job safer than a work queue?

They express different ownership models. Indexed Jobs give deterministic identities for a fixed set of partitions but still need duplicate-safe output. Work queues can handle a changing set of items, but workers must coordinate claims and stop producing work after the queue is drained. Choose from the work model, not from a preference for one field.

Does kubectl wait --for=condition=Complete prove the data is correct?

No. It proves that the observed Job condition was met within the timeout. Verify index coverage, output keys, application checks, and the exact candidate revision separately.

Can a suspended Job resume with the same deadline remaining?

The API reference says suspension stops and resets the Job start timer when it resumes. Verify the target Kubernetes version and treat the resumed run as a fresh active-duration calculation.

Reader next step

Choose one agent-written standalone Job patch. Attach its completion model, index or work-key contract, rendered retry and deadline policy, resource assumptions, and candidate identity to the pull request. In the approved fixture, collect a healthy completion, one retry or failure-policy case, and a suspension or cleanup observation. Keep Job and Pod UIDs, index status, conditions, events, logs, and application output together so a reviewer can connect every conclusion to the exact change being approved.