k8s-sentinel: CronJob Hygiene for Single-Admin Homelab Clusters

Jul 17, 2026

Article cover: k8s-sentinel: CronJob Hygiene for Single-Admin Homelab Clusters

Why CronJob Failures Haunt Homelab Clusters

Why CronJob Failures Haunt Homelab Clusters
Why CronJob Failures Haunt Homelab Clusters

In the world of self-hosted Kubernetes, CronJobs are a powerful tool for automating batch tasks like backups, syncs, and CI cleanup. However, when these jobs fail, they can be easy to miss, especially in a single-admin homelab environment. Unlike cloud-based clusters, where monitoring and alerting are often handled by dedicated teams, homelab operators must rely on their own vigilance and automation to ensure that critical tasks succeed.

Consider a scenario where a backup job fails due to a misconfigured volume mount. The job might not immediately alert you, and the failure might not be obvious until storage space is critically low. By the time you notice, the job might have run multiple times, filling up your disk with failed backup attempts. This is where the kube_job_failed metric can be misleading. It might show that a job failed, but it doesn't provide context or logs to help you understand why.

In a homelab setting, you might find yourself constantly checking logs and metrics, only to find that the issue is not immediately apparent. This can lead to alert fatigue, where you become desensitized to repeated alerts and miss critical issues. The kube_job_failed metric can linger in your monitoring dashboard, creating a false sense of security. It's only when you manually inspect the job's logs that you realize the problem.

To address this, we need a more robust system for monitoring and alerting on CronJob failures. This is where k8s-sentinel comes in, specifically its cronjobs module. This module scans for failed batch jobs, attaches relevant log tails, and provides context about the failure. By automating this process, we can reduce the risk of missed failures and ensure that our homelab remains healthy.

Prometheus vs Operator Reality

kube_job_failed and CronJobFailed

Prometheus is a powerful tool for monitoring Kubernetes clusters, and it provides several metrics that can help us track the health of our CronJobs. Two of the most relevant metrics are kube_job_failed and CronJobFailed.

The kube_job_failed metric is a generic indicator that a job has failed. It can be useful for identifying failures, but it lacks context. For example, if a backup job fails, kube_job_failed will notify you, but it won't tell you why the job failed or provide any logs to help you diagnose the issue.

On the other hand, the CronJobFailed metric is more specific to CronJobs. It provides a timestamp for the last successful run and the last failed run, which can be useful for identifying recent failures. However, CronJobFailed is only emitted if the CronJob has failed at least once. If the job has never failed, this metric will not be emitted, making it less useful for proactive monitoring.

Last-Success Timestamps

Another useful metric is the last-success timestamp. This can be found in the status.lastScheduleTime field of a CronJob's status. It provides a clear indication of when the job was last successfully executed. However, this metric alone is not sufficient for monitoring CronJob failures. It only tells you when the job was last successful, but it doesn't provide any information about why the job failed or what logs are available to help you diagnose the issue.

Why Metrics Alone Aren't Enough

While metrics are a valuable tool for monitoring CronJob failures, they are not enough on their own. Metrics provide a high-level view of the health of your CronJobs, but they lack the context and detail needed to diagnose and resolve issues. For example, a kube_job_failed alert might indicate that a job has failed, but it won't tell you what went wrong or where to find the relevant logs.

To address this, we need to combine metrics with logs and context. This is where k8s-sentinel comes in. The cronjobs module scans for failed batch jobs, attaches relevant log tails, and provides context about the failure. By automating this process, we can reduce the risk of missed failures and ensure that our homelab remains healthy.

The cronjobs Check Module

Cluster-Wide Job Scan

The cronjobs check module in k8s-sentinel is designed to scan for failed batch jobs cluster-wide. It uses the kube_job_status metric to identify jobs that have failed and then attaches relevant log tails to provide context about the failure. This module is particularly useful in a homelab setting, where you might have multiple CronJobs running across different namespaces and applications.

To use the cronjobs module, you need to configure it in your k8s-sentinel configuration. Here's an example configuration:

cronjobs:
  enabled: true
  log_tail: 100
  max_age_hours: 48

In this configuration, enabled is set to true to enable the module, log_tail is set to 100 to attach the last 100 lines of logs to the alert, and max_age_hours is set to 48 to ignore stale failures older than 48 hours.

Log Tail (SENTINEL_CRONJOB_LOG_TAIL)

The log_tail parameter in the cronjobs module is used to specify the number of lines of logs to attach to the alert. This is particularly useful for identifying the root cause of a failure. For example, if a backup job fails due to a misconfigured volume mount, the relevant log lines might be near the end of the log file. By attaching the last 100 lines of logs to the alert, you can quickly identify the issue and take corrective action.

Owner CronJob Name

The cronjobs module also provides the owner CronJob name in the alert. This is useful for identifying which CronJob caused the failure. For example, if you have multiple CronJobs running in the same namespace, the owner CronJob name can help you quickly identify which job failed and take corrective action.

Known-Pattern Hints

The cronjobs module also provides known-pattern hints from real incidents. These hints are useful for identifying common failure patterns and providing context about the failure. For example, if a job fails due to a mapfile: not found error, the module might provide a hint that the file is missing from the job's volume. This can help you quickly identify the issue and take corrective action.

Age Windows and Safe Cleanup

SENTINEL_CRONJOB_MAX_AGE_HOURS

One of the key features of the cronjobs module is the ability to ignore stale failures. This is controlled by the SENTINEL_CRONJOB_MAX_AGE_HOURS parameter, which specifies the maximum age of a failure in hours. If a failure is older than this age, it will be ignored and not included in the alert.

For example, if you set SENTINEL_CRONJOB_MAX_AGE_HOURS to 48, the module will ignore failures that are older than 48 hours. This is useful for reducing alert fatigue and ensuring that you only receive alerts for recent failures.

Ignore Stale Failures

By ignoring stale failures, you can reduce the number of alerts that you receive and focus on recent failures. This is particularly useful in a homelab setting, where you might have multiple CronJobs running across different namespaces and applications. By ignoring stale failures, you can ensure that you only receive alerts for recent failures and take corrective action.

Auto-Fix Deletes Failed Job Objects

The cronjobs module also provides the ability to auto-fix failed job objects. This is controlled by the auto_fix parameter, which is set to true by default. When auto_fix is set to true, the module will automatically delete failed job objects (not pods) after a certain period of time.

For example, if you set auto_fix to true and SENTINEL_CRONJOB_MAX_AGE_HOURS to 48, the module will automatically delete failed job objects that are older than 48 hours. This is useful for reducing the number of failed job objects in your cluster and ensuring that your cluster remains healthy.

Skip k8s-sentinel-* Test Jobs

The cronjobs module also provides the ability to skip k8s-sentinel-* test jobs. This is controlled by the skip_test_jobs parameter, which is set to true by default. When skip_test_jobs is set to true, the module will skip any jobs that are named k8s-sentinel-*.

For example, if you have a test job named k8s-sentinel-backup-test, the module will skip this job and not include it in the alert. This is useful for reducing the number of false positives and ensuring that you only receive alerts for real failures.

Alert Deduplication

Alert Deduplication
Alert Deduplication

SentinelModuleWarning{module!="cronjobs"}

To reduce alert fatigue, the cronjobs module provides the ability to deduplicate alerts. This is controlled by the SentinelModuleWarning metric, which is emitted by the module when a failure is detected. The SentinelModuleWarning metric is emitted with the module label set to the name of the module that detected the failure.

For example, if the cronjobs module detects a failure, it will emit a SentinelModuleWarning metric with the module label set to cronjobs. This metric can be used to deduplicate alerts from other modules, ensuring that you only receive one alert for each failure.

Telegram + CronJobFailed

To further reduce alert fatigue, the cronjobs module provides the ability to route alerts to Telegram. This is controlled by the telegram parameter, which is set to true by default. When telegram is set to true, the module will route alerts to Telegram.

For example, if the cronjobs module detects a failure and emits a SentinelModuleWarning metric, it will also route the alert to Telegram. This is useful for ensuring that you receive alerts on your mobile device and can take corrective action quickly.

Pushgateway sentinel_check_status and Stale-Metrics Alert

To further reduce alert fatigue, the cronjobs module provides the ability to emit a sentinel_check_status metric to the Pushgateway. This metric can be used to trigger a stale-metrics alert if the module has not detected any failures in a certain period of time.

For example, if the cronjobs module has not detected any failures in the last 24 hours, it will emit a sentinel_check_status metric with the status label set to ok. If the module has detected a failure, it will emit a sentinel_check_status metric with the status label set to failure. This metric can be used to trigger a stale-metrics alert, ensuring that you receive alerts when the module is not functioning as expected.

Homelab Tuning Checklist

Schedule

The cronjobs module can be configured with a schedule to run at regular intervals. This is controlled by the schedule parameter, which is set to */30 * * * * by default. This schedule runs the module every 30 minutes, which is a good balance between frequency and resource usage.

For example, if you set schedule to */15 * * * *, the module will run every 15 minutes. This is useful for ensuring that you receive alerts for recent failures and take corrective action quickly.

failedJobsHistoryLimit

The cronjobs module can be configured with a failedJobsHistoryLimit parameter to control the number of failed jobs that are retained. This is controlled by the failedJobsHistoryLimit parameter, which is set to 10 by default. This parameter controls the number of failed jobs that are retained in the module's state.

For example, if you set failedJobsHistoryLimit to 5, the module will retain the last 5 failed jobs in its state. This is useful for ensuring that you have enough context to diagnose failures and take corrective action.

Namespace CSV Filter

The cronjobs module can be configured with a namespace CSV filter to control which namespaces are monitored. This is controlled by the namespace parameter, which is set to kube-system by default. This parameter controls which namespaces are monitored by the module.

For example, if you set namespace to kube-system,monitoring, the module will monitor the kube-system and monitoring namespaces. This is useful for ensuring that you only monitor the namespaces that are relevant to your cluster.

Module List in Helm Values

The cronjobs module can be configured with a module list in the Helm values to control which modules are included in the check. This is controlled by the module_list parameter, which is set to cronjobs by default. This parameter controls which modules are included in the check.

For example, if you set module_list to cronjobs,deployments, the module will include the cronjobs and deployments modules in the check. This is useful for ensuring that you only include the modules that are relevant to your cluster.

Relation to Node-Level Disk Maintenance Cron

The cronjobs module can be configured with a relation to the node-level disk maintenance cron to ensure that disk maintenance tasks are not affected by failed CronJobs. This is controlled by the disk_maintenance_cron parameter, which is set to false by default. This parameter controls whether the module is related to the node-level disk maintenance cron.

For example, if you set disk_maintenance_cron to true, the module will be related to the node-level disk maintenance cron. This is useful for ensuring that disk maintenance tasks are not affected by failed CronJobs and that your cluster remains healthy.

Runbook Pointer

Copy-Paste Ops Live in kb

To ensure that you can quickly take corrective action when a CronJob fails, we recommend that you copy-paste the runbook live in your knowledge base (kb). The kb_slug for this runbook is k8s-sentinel-cronjob-hygiene. This runbook provides step-by-step instructions for troubleshooting CronJob failures and taking corrective action.

For example, if a backup job fails due to a misconfigured volume mount, the runbook might provide the following steps:

  1. Check the kube_job_status metric to identify the failed job.
  2. Attach the last 100 lines of logs to the alert to identify the root cause of the failure.
  3. Identify the owner CronJob name in the alert to determine which CronJob caused the failure.
  4. Take corrective action to resolve the issue, such as updating the volume mount configuration.
  5. Monitor the job to ensure that it runs successfully.

By following these steps, you can quickly take corrective action when a CronJob fails and ensure that your homelab remains healthy.

Conclusion

Conclusion
Conclusion

In this article, we've discussed the challenges of monitoring CronJob failures in a homelab setting and how the cronjobs module in k8s-sentinel can help address these challenges. By combining metrics with logs and context, the cronjobs module can help you quickly identify and resolve CronJob failures, reducing the risk of missed failures and ensuring that your homelab remains healthy.

To learn more about k8s-sentinel and the cronjobs module, we recommend that you check out the runbook live in your knowledge base (kb). This runbook provides step-by-step instructions for troubleshooting CronJob failures and taking corrective action.