cronguard

module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 25, 2026 License: Apache-2.0

README

CronGuard

CI Go Report Card License Go Version

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

# Install CRDs and the operator
kubectl apply -f https://github.com/dmazhukov/cronguard/releases/download/v0.1.0/install.yaml

# Apply a sample
kubectl apply -f config/samples/cronjob_example.yaml
kubectl apply -f config/samples/monitoring_v1alpha1_cronjobmonitor.yaml

# Check it
kubectl get cronjobmonitors
# NAME                  SCHEDULE      LASTSUCCESS   CONSECFAILS   MISSED   READY   AGE
# nightly-settlement    0 2 * * *     5m            0             0        True    10m

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

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

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.

Directories

Path Synopsis
api
v1alpha1
Package v1alpha1 contains API Schema definitions for the monitoring v1alpha1 API group.
Package v1alpha1 contains API Schema definitions for the monitoring v1alpha1 API group.
internal
history
Package history provides a ring-buffer merge for ExecutionRecord slices.
Package history provides a ring-buffer merge for ExecutionRecord slices.
metrics
Package metrics implements a Prometheus custom collector for CronJobMonitor.
Package metrics implements a Prometheus custom collector for CronJobMonitor.
schedule
Package schedule parses cron expressions and provides helpers for computing expected run times, drift, and missed-run counts.
Package schedule parses cron expressions and provides helpers for computing expected run times, drift, and missed-run counts.
test

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL