CronJob History and Retention
What you'll learn: How to control how many completed Job objects Kubernetes keeps around after your CronJobs run.
Every time a CronJob triggers, it creates a Job object. Those Jobs stick around even after they complete—both successful and failed ones. Over time, this can clutter your cluster with dozens or hundreds of old Job records. Kubernetes gives you two simple knobs to control this housekeeping.
The Two History Limits
successfulJobsHistoryLimit
This field determines how many successfully completed Jobs are retained in history. The default is 3. Once you exceed this number, Kubernetes automatically deletes the oldest successful Job objects.
failedJobsHistoryLimit
This field determines how many failed Jobs are kept. The default is 1. Failed Jobs are often more important to keep around for debugging, but you still don't want infinite accumulation.
Why This Matters
Think of these limits like your email inbox filters. You might keep recent successful newsletters (you know they worked fine), but archive or delete old ones. For failed deliveries, you keep a few to troubleshoot what went wrong, but don't need years of failures piling up.
Setting these values too low means you lose debugging history quickly. Setting them too high wastes cluster resources storing metadata you'll never look at.
Example Configuration
apiVersion: batch/v1
kind: CronJob
metadata:
name: daily-report
spec:
schedule: "0 2 * * *"
successfulJobsHistoryLimit: 5
failedJobsHistoryLimit: 3
jobTemplate:
# ... job spec here
This configuration keeps the last 5 successful runs and the last 3 failed runs visible for inspection.
Key Takeaway: Use successfulJobsHistoryLimit and failedJobsHistoryLimit in your CronJob spec to balance cluster cleanliness with debugging visibility—preventing old Job objects from accumulating indefinitely.