Last reviewed: November 9, 2026 (Asia/Shanghai); official references checked November 8 UTC.
Direct answer
Review an agent-written Kubernetes CronJob by defining which scheduled periods matter, how late a Job may start, what happens when executions overlap, and how repeated attempts affect application data. Inspect the rendered CronJob and its nested Job and Pod templates together. Then test scheduled execution, a missed start, an overlong run, and duplicate application work in an approved disposable environment.
The CronJob reference
says scheduling is approximate: a scheduled occurrence can produce two Jobs or no Job. The Jobs reference
also warns that the same program can start twice even with one completion, one parallel Pod, and restartPolicy: Never. Approval therefore needs evidence about business effects as well as controller status.
Who this is for
Use this workflow when a coding agent edits a batch/v1 CronJob, its schedule, time zone, concurrency policy, suspension setting, Job retry policy, or application code that processes scheduled work. Include Helm values and Kustomize overlays that change the effective object.
Give the agent the target Kubernetes version, intended business periods, acceptable lateness, runtime budget, and recovery procedure. Ask it to explain missed work and repeated execution before changing configuration. The examples below are review fixtures and proposed acceptance checks; no authenticated cluster tests or deployments were performed for this article.
Key takeaways
- A start deadline limits lateness; a Job active deadline limits execution duration.
Forbidgoverns Jobs created by the same CronJob, rather than all callers of the application.- Suspending a CronJob leaves already-started Jobs running.
- Resuming a schedule is not a mechanism for replaying every missed business period.
- A successful Job condition and a correct application result require separate evidence.
- Bind observations to the CronJob UID, created Job UID, actual template, and intended work period.
Sources checked
Three primary Kubernetes pages were retrieved successfully on November 8, 2026 UTC:
- CronJob defines schedules, time zones, starting deadlines, concurrency, suspension, template changes, missed schedules, and approximate Job creation. It reports an October 31, 2026 modification correcting missed-schedule and unsuspend wording.
- Jobs defines Pod retries, backoff limits, active deadlines, repeated program starts, terminal conditions, and cleanup. It reports an October 12, 2026 modification.
- kubectl create job documents creating a Job from a CronJob and server-side dry-run. It reports an August 26, 2026 update for Kubernetes v1.37.
These maintained technical references support an evergreen review task. Match the fields and controller behavior to the target cluster and client versions, particularly when an older runbook describes missed schedules differently.
Contract details to verify
Define the business schedule before the cron expression
Render every affected environment from the exact candidate. Record the namespace, CronJob name, schedule, time zone, suspension state, complete Job template, container commands, image references, and relevant configuration. A correct base manifest can still be overridden by environment values.
Write an acceptance statement in application terms. For example: “Refresh the report snapshot every five minutes in UTC. Starting more than two minutes late is useless. An execution may run for seven minutes; skipped refresh periods are acceptable, but publishing the same period twice must not create duplicate records.” These are illustrative business decisions, not Kubernetes defaults.
If every period must be processed, have the worker reconcile a durable list of outstanding periods. Do not assume the CronJob controller provides that backlog. Record who may authorize historical regeneration and how it differs from ordinary scheduled work.
Set .spec.timeZone explicitly when the schedule must have a fixed interpretation. Without it, the controller uses its local time zone. The reference supports Etc/UTC; embedding TZ or CRON_TZ in .spec.schedule is unsupported and causes validation errors. A change from local time to UTC deserves review of the actual expected run times.
Separate lateness, runtime, retries, and retention
This policy fragment belongs under an existing CronJob’s spec. It omits the reviewed containers, service account, and resource settings and is not a standalone manifest:
schedule: "*/5 * * * *"
timeZone: "Etc/UTC"
concurrencyPolicy: Forbid
startingDeadlineSeconds: 120
successfulJobsHistoryLimit: 3
failedJobsHistoryLimit: 3
jobTemplate:
spec:
completions: 1
parallelism: 1
backoffLimit: 1
activeDeadlineSeconds: 420
template:
spec:
restartPolicy: Never
Review each setting at its actual nesting level:
| Setting | Decision it controls | What it does not establish |
|---|---|---|
CronJob startingDeadlineSeconds: 120 | Whether a missed occurrence may still start within its lateness window | A two-minute runtime limit |
Job activeDeadlineSeconds: 420 | Active duration across the Job’s Pods and retries | Completion by a fixed offset from the original schedule |
Job backoffLimit: 1 | Retry budget before Job failure | Exactly one application invocation |
Pod restartPolicy: Never | A failed container is not restarted in that Pod | Prevention of a replacement Pod or duplicate program start |
| Successful and failed history limits | Counts of finished Jobs retained | An application audit log or runtime limit |
For a 12:00 UTC occurrence, creation at 12:01:30 is within the 120-second start window; creation at 12:02:01 is too late. If the Job’s recorded start time is 12:01:30, its 420-second active budget points to 12:08:30. Controller observation and graceful termination mean those calculations are not exact process-stop timestamps.
In that overlong case, the 12:05 occurrence encounters the previous Job still active and is skipped under Forbid. By 12:08:30, that occurrence is already outside its own two-minute start window. This policy deliberately tolerates a missed refresh; it cannot satisfy a requirement to publish every five-minute period.
The Jobs reference gives the active deadline precedence over the backoff limit. Retrying Pods cannot extend that budget indefinitely, and a failed Job is not automatically restarted as the same Job. Also avoid treating an extremely short start deadline as a precise timer: the CronJob reference warns that values below ten seconds may prevent scheduling because of the controller’s checking interval.
Review overlap and application effects separately
The default Allow permits concurrent Jobs. Forbid skips a scheduled run when the previous Job has not finished; a later start can still be considered within the starting deadline. Replace replaces the running Job with a new one. Choose from the application’s tolerance for skipped, overlapping, or interrupted work. Replacement does not undo an external write already performed by the old execution.
The policy applies only to Jobs created by the same CronJob. Do not treat it as an application lock covering another CronJob or an operator-started Job. The Jobs reference’s duplicate-start warning also means parallelism: 1 is insufficient as an exactly-once argument.
As an application design recommendation, define a durable work key from the logical task and business period. Reuse it across retries and deliberate replays of that period. A fresh random key for every Pod cannot identify duplicate work. Where possible, commit the deduplication record and database effect atomically; for an external service, use its documented idempotency contract. Preserve an uncertain external outcome for reconciliation before authorizing another attempt.
Test that rule with a harmless output sink: start two attempts for the same period, interrupt an attempt after its effect but before acknowledgement, and retry the same key. Require one accepted business effect and an explainable duplicate result. If the patch changes locks or shared state, attach reproducible overlap evidence using the concurrency testing guide .
Inspect the candidate and the Jobs it actually creates
The CronJob reference says template changes affect future Jobs. Existing Jobs and Pods continue unchanged. During review, an old Job succeeding after the update is therefore insufficient evidence that the candidate template ran.
Capture the rendered candidate and the live fixture CronJob’s UID and generation. Read the created Jobs and retain their owner references, templates, Pod identities, conditions, and timestamps. On Kubernetes v1.32 and later, controller-created Jobs carry batch.kubernetes.io/cronjob-scheduled-timestamp, identifying their originally scheduled creation time. Keep that distinct from actual Job start and completion times.
For a fixture named report, these read-only commands capture the CronJob and select Jobs by its UID. Replace the sample context, namespace, and name with the approved fixture values:
kubectl --context review-cluster --namespace agent-review \
get cronjob report -o json > review-cronjob.json
cronjob_uid=$(jq -er '.metadata.uid' review-cronjob.json)
kubectl --context review-cluster --namespace agent-review \
get jobs -o json |
jq --arg uid "$cronjob_uid" '[.items[] |
select(any(.metadata.ownerReferences[]?;
.kind == "CronJob" and .uid == $uid)) |
{name: .metadata.name,
uid: .metadata.uid,
scheduled: .metadata.annotations["batch.kubernetes.io/cronjob-scheduled-timestamp"],
start: .status.startTime,
completion: .status.completionTime,
active: .status.active,
conditions: .status.conditions,
template: .spec.template}]'
Check each command’s exit status before interpreting its output. Owner references identify the creating CronJob; compare the actual Job template with the saved candidate as well. Keep full objects in protected review artifacts and share sanitized summaries.
After confirming that the fixture CronJob contains the candidate, preview a Job from its current template:
kubectl --context review-cluster --namespace agent-review \
create job report-review --from=cronjob/report \
--dry-run=server --validate=strict -o yaml
The command reference defines server dry-run as a server request without persisting the resource. It does not run Pods or exercise scheduled ticks. A deliberately launched manual Job can help test application behavior, but use actual CronJob-created Jobs for schedule, suspension, and concurrency observations. Review scheduling or quota failures with the requests and limits guide rather than silently weakening resource policy.
Exercise missed starts and recovery
Use the authorized disposable-cluster workflow with synthetic data and bounded observation windows. Establish a healthy baseline, isolate one case at a time, and restore the baseline between cases. These are proposed checks:
| Controlled case | Evidence required |
|---|---|
| Healthy scheduled execution | Scheduled timestamp, candidate Job template, Pod identity, terminal condition, and expected synthetic output |
Execution remains active across the next tick under Forbid | Original Job remains identifiable; skipped occurrence and any later eligible start match the deadline policy |
| Pod fails and is retried | Distinct attempt identities, retry diagnostics, and one accepted effect for the same work key |
| Execution exceeds its active deadline | DeadlineExceeded failure, Pod termination evidence, and reconciliation of partial output |
| CronJob is suspended and resumed across missed ticks | Already-started Job continues; subsequent creation matches the configured lateness window |
| Template changes while an earlier Job runs | Old Job retains its template; a later controller-created Job contains the candidate |
Suspension does not stop Jobs already started. The current CronJob reference says that resuming without a starting deadline starts a Job for the most recent missed schedule, rather than every earlier missed schedule. It also describes more than 100 missed schedules as producing a warning while still starting the most recent missed occurrence. Match that behavior to the target version; do not copy an older rule that assumes catch-up stops entirely.
Keep application checks alongside Kubernetes conditions. A Job marked complete cannot by itself establish that a report contains the intended period, a duplicate was rejected, or an external effect was reconciled. Export the evidence before history cleanup removes finished Jobs and their Pods.
Failure modes
The start deadline is described as a runtime timeout. Check the CronJob field and the nested Job active deadline independently, then calculate the latest acceptable finish from the actual start.
Forbid is presented as exactly-once processing. Test duplicate application attempts and preserve a stable work key across retries and manual recovery.
Unsuspending is expected to backfill every period. Reconcile outstanding business periods explicitly; the schedule controller is not that ledger.
An old Job’s success approves a new template. Retain the candidate render and compare it with the actual created Job and Pod identities.
FAQ
Does restartPolicy: Never disable Job retries?
No. It prevents a container restart within that Pod. The Job controller can create replacement Pods, subject to its failure policy and deadline, and the documentation still requires tolerance for duplicate program starts.
Does suspending the CronJob cancel the current execution?
No. Already-started Jobs continue. Stopping one requires a separate authorized recovery decision that accounts for partial application effects.
Does a server dry-run prove the schedule works?
No. It previews the requested Job without persisting it. Observe actual controller-created Jobs to test the schedule and inspect application output to test business correctness.
Reader next step
Choose one agent-written CronJob patch. Write its business-period and lateness contract, render the nested Job policy, and calculate one late-start and overlong-run timeline. In the approved fixture, collect a healthy scheduled execution, an overlap or missed-start case, and a duplicate-effect test. Attach the candidate render, CronJob and Job UIDs, scheduled and actual timestamps, conditions, and sanitized output evidence to the pull request before approval.