CronGuard

SLO-style observability for Kubernetes CronJobs.
CronGuard is a small Kubernetes operator that wraps any existing batch/v1.CronJob with a CronJobMonitor custom resource. It watches child Jobs, tracks execution history, and exposes high-quality Prometheus metrics — so you can alert on missed runs, duration budget violations, and consecutive failures without hand-rolling PromQL against kube-state-metrics.
Why
Kubernetes CronJobs fail silently more often than you think: a skipped run under concurrencyPolicy: Forbid, a Job that completes with no succeeded pods, control-plane drift pushing starts minutes late. Teams keep re-inventing the same fragile PromQL:
time() - kube_cronjob_status_last_successful_time{cronjob="..."} > 86400
CronGuard replaces that with a declarative SLO per CronJob.
Quickstart
Helm (OCI)
helm install cronguard oci://ghcr.io/dmazhukov/charts/cronguard \
--version 0.2.0 \
--namespace cronguard-system --create-namespace
Helm (GitHub Pages)
helm repo add cronguard https://dmazhukov.github.io/cronguard/
helm repo update
helm install cronguard cronguard/cronguard --version 0.2.0 \
--namespace cronguard-system --create-namespace
Raw manifests
kubectl apply -f https://github.com/dmazhukov/cronguard/releases/download/v0.2.0/install.yaml
Apply a sample monitor:
kubectl apply -f config/samples/cronjob_example.yaml
kubectl apply -f config/samples/monitoring_v1alpha1_cronjobmonitor.yaml
kubectl get cronjobmonitors
# NAME SCHEDULE LASTSUCCESS CONSECFAILS MISSED READY AGE
# nightly-settlement 0 2 * * * 5m 0 0 True 10m
See docs/distribution.md for the full installation reference and all configuration knobs.
Example
apiVersion: monitoring.cronguard.io/v1alpha1
kind: CronJobMonitor
metadata:
name: nightly-settlement
spec:
cronJobRef:
name: nightly-settlement
schedule: "0 2 * * *"
maxDurationSeconds: 1800 # SLO: finish within 30 minutes
maxConsecutiveFailures: 2 # alert after 2 failures in a row
alertAfterMissedRuns: 2 # alert after 2 missed starts
gracePeriodSeconds: 60
historyLimit: 10
Walkthrough

Recorded against a real kind cluster. Replay locally with:
asciinema play docs/cast/install.cast
Or open the .cast file directly.
Metrics
All metrics are labelled {namespace, name, cronjob}.
| Metric |
Type |
Meaning |
cronguard_last_success_timestamp_seconds |
gauge |
Unix time of last successful Job |
cronguard_last_failure_timestamp_seconds |
gauge |
Unix time of last failed Job |
cronguard_next_expected_timestamp_seconds |
gauge |
Unix time of next expected run |
cronguard_consecutive_failures |
gauge |
Consecutive failed runs |
cronguard_missed_runs |
gauge |
Consecutive missed runs |
cronguard_schedule_drift_seconds |
gauge |
Drift of most recent run |
cronguard_last_duration_seconds |
gauge |
Duration of last completed run |
cronguard_condition |
gauge |
1/0/-1 per condition type/reason |
Example alerts (PromQL):
# No success in 25 hours for a daily CronJob
(time() - cronguard_last_success_timestamp_seconds) > 90000
# Execution SLO breached
cronguard_condition{type="ExecutionHealthy"} == 0
Dashboards
A pre-built Grafana dashboard ships under config/grafana/ — six panels covering all CronGuard metrics. See the dashboards README for import instructions.
Architecture
User applies CronJobMonitor YAML
│
▼
apiserver ──► Reconciler ──► computes SLO ──► patches .status
▲ │
└──── Job events (informer) ─┘
/metrics scrape ──► Collector reads cache ──► emits cronguard_*
No webhooks, no finalizers, no ownership of foreign resources.
Roadmap
v0.1.0 (Phase 1, this release): operator core, CRD, envtest suite, raw manifests, Prometheus metrics.
Phase 2 (planned): Helm chart, Grafana dashboard, PrometheusRule bundle, ServiceMonitor, kind-based e2e, Artifact Hub publication.
Phase 3 (possible): admission webhook (CEL validation), OLM bundle, namespace-scoped variant, burn-rate alerts.
Development
# Run unit + envtest
make test
# Run the manager against your current kube-context
make run
# Build a local Docker image
make docker-build IMG=cronguard:dev
Contributing
See CONTRIBUTING.md.
Security
See SECURITY.md.
License
Apache 2.0 — see LICENSE.