10.21 Kubernetes CronJob Retention Control

Kubernetes CronJob Retention Control is the configuration governing how many historical Job objects created by a CronJob are preserved after they complete, balancing the operational value of retaining execution history for auditing and troubleshooting against the ongoing accumulation of completed objects that would otherwise persist indefinitely within the cluster.

Separate Limits for Success and Failure

successfulJobsHistoryLimit

The successfulJobsHistoryLimit field specifies how many completed Jobs that finished successfully are retained, with the oldest successful Jobs beyond this limit being automatically deleted by the CronJob controller as newer successful completions accumulate.

failedJobsHistoryLimit

The failedJobsHistoryLimit field independently specifies how many failed Jobs are retained, allowing operators to configure a different retention policy for failures than for successes, such as retaining more failed executions to aid in diagnosing recurring problems while keeping fewer successful ones since they typically carry less diagnostic value.

Rationale for Independent Limits

Differing Diagnostic Value

Failed Job executions often carry substantially more diagnostic value than successful ones, since they represent the cases requiring investigation, which is why operators commonly configure a higher retention limit for failures relative to successes, preserving a longer troubleshooting window specifically for the executions that are more likely to require review.

Preventing Object Accumulation

Without any retention limit, a frequently scheduled CronJob could accumulate a very large number of completed Job objects over time, each with its own associated Pods, placing unnecessary load on the API server and etcd simply through the sheer volume of retained historical objects providing diminishing operational value.

Cleanup Mechanics

Automatic Deletion by the Controller

The CronJob controller itself is responsible for enforcing these limits, periodically checking the count of retained successful and failed Jobs against their respective configured limits and deleting the oldest excess Jobs, along with their owned Pods, through the standard cascading deletion mechanism tied to owner references.

Interaction With ttlSecondsAfterFinished

Job-level cleanup through ttlSecondsAfterFinished, if configured on the CronJob's embedded jobTemplate, operates independently of and in addition to the CronJob's own history limits, meaning a Job could be cleaned up due to its TTL expiring before it would have otherwise been removed purely due to exceeding the history count limit.

Setting Retention Limits to Zero

Disabling History Retention Entirely

Setting either history limit to zero results in no Jobs of that outcome category being retained at all, with each completed Job immediately eligible for cleanup once it finishes, which may be appropriate for extremely frequent CronJobs where retaining any history would provide little value relative to the object churn it generates.

Tradeoffs of Zero Retention

While eliminating retained history reduces cluster object overhead to a minimum, it also removes the ability to inspect any past execution after the fact, meaning diagnosing an intermittent failure becomes significantly harder without access to the logs and status of previous Job attempts.

Interaction With Concurrency and Scheduling

History Retention Independent of Concurrency Policy

The history limits apply uniformly regardless of the CronJob's configured concurrencyPolicy, meaning even a CronJob configured to forbid overlapping executions still accumulates and prunes its history of past, non-overlapping runs according to these same retention rules.

Retention Relative to Schedule Frequency

Because these limits are expressed as a count of retained Jobs rather than a time duration, the effective historical time window they represent varies depending on how frequently the CronJob's schedule triggers, with a highly frequent schedule resulting in a much shorter retained time window than a less frequent one under the same numeric limit.