cron-and-scheduled-jobs

Files (5)

• SKILL.md
• choosing-and-operations.md · references/
• kubernetes-cronjob.md · references/
• repo-evidence.md · references/
• temporal-schedules.md · references/

SKILL.md (first lines)

# Cron & Scheduled Jobs

Two mechanisms run recurring work in this stack, and they put the *schedule* in two very different
places. Knowing which one you're in tells you where the schedule lives and what owns the recurrence:

1. **Kubernetes CronJob** — the cluster's `CronJob` controller is the scheduler. It fires a fresh pod
   on the schedule; the pod runs the **same service image** booted in a one-shot `MODE=cron` that
   executes a single named job from a Python registry and exits. The schedule lives in **Helm values**,
   never in the app.
2. **Temporal Schedule** — the **Temporal server** is the durable scheduler. A `Schedule` object fires
   a workflow on a cron expression or interval; a missed window, catch-up, pause, and backfill are all
   first-class. The schedule lives in **a registration step** (run once / idempotently on deploy).

> Companion skills: `temporal-config-driven` (workflow/activity/worker mechanics, retries, idempotency,
> and the deeper schedule-registration reference — this skill cross-links it rather than repeating it),
> `containerization-and-deployment` (the `MODE`-dispatch entrypoint and Helm packaging),
> `kubernetes-workload-hardening` (securityContext/NetworkPolicy for the CronJob pod), and
> `observability-and-logging` (the cron execution metric).

## When to use

- Adding a **periodic / scheduled job** to a service and deciding where the schedule belongs
- Wiring a **`MODE=cron` entrypoint** and registering a job in the **Python cron registry**
- Declaring a **CronJob in Helm values** (`Crons` block) and understanding the rendered manifest
- **Registering or updating a Temporal Schedule** (cron vs interval, overlap, pause-on-failure)
- Deploying schedule registration as a **one-shot k8s `Job`**
- Choosing between a **Kubernetes CronJob** and a **Temporal Schedule**
- Debugging "the job didn't run", overlapping runs, timezone drift, or piled-up executions

## Two mechanisms at a glance

| | **Kubernetes CronJob + `MODE=cron`** | **Temporal Schedule** |
|---|---|---|
| Scheduler | k8s `CronJob` controller | Temporal server |
| Where the schedule lives | Helm `values.yaml` → `Crons.<name>.Schedule` | a registration step (`create_schedule`) |
| What runs | one-shot pod: `MODE=cron CRON_JOB=<name>` → registry handler → exit | a Temporal workflow |
| Recurrence units | 5-field cron only | cron **or** interval (`every=` + `offset=`) |
| Overlap control | `concurrencyPolicy: Forbid` (coarse) | `ScheduleOverlapPolicy.SKIP/BUFFER_ONE/...` (rich) |
| Missed-run visibility | none (the pod just didn't run) | first-class (server tracks it) |
| Pause / backfill / manual fire | suspend the CronJob (no backfill) | `pause`/`unpause`/`backfill`/`trigger` |
| Retry across fires | none (pod exits; next fire is fresh) | per-fire `pause_on_failure` + workflow RetryPolicy |
| Best for | simple, self-contained periodic app tasks | durable/long jobs needing overlap, catch-up, visibility |

## Core conventions

### Kubernetes CronJob + `MODE=cron`

**The schedule is config, not code.** You declare a cron under the service's `Crons` block in Helm
values; the chart renders one `kind: CronJob` per entry. The job's *only* app-side coupling is two env
vars — `MODE=cron` and `CRON_JOB=<name>` — that tell the shared image which single job to run.

```yaml
# Helm values — Projects.<service>.Crons.<job-name>
Crons:
  nightly-report:
    Schedule: "0 2 * * *"            # 5-field cron (the authoritative schedule)
    Envs:
      MODE: cron                     # boot the image in one-shot cron mode
      CRON_JOB: nightly-report       # which registry entry to run
    ConcurrencyPolicy: Forbid        # default; don't start a fire if the last is still running
    Suspend: false                   # set true to pause without deleting
    TtlSecondsAfterFinished: 300     # GC the finished Job pod
    # Parallelism, Resources, NodeSelector, Tolerations also supported
```

The rendered CronJob carries sensible defaults from the chart: `concurrencyPolicy: Forbid`,
`failedJobsHistoryLimit: 3`, `successfulJobsHistoryLimit: 1`, `restartPolicy: Never`,
`ttlSecondsAfterFinished: 300`. **The chart has no `timeZone` and no `startingDeadlineSeconds`** — so
the schedule evaluates in the cluster's timezone (usually UTC) and a controller that's down past a fire
window silently skips it. Plan around both (see `references/choosing-and-operations.md`).

**The app side is a one-shot dispatcher, not a daemon.** A multi-mode `entrypoint.py` reads `MODE`; the
`cron` branch runs a single job from a registry and the process exits. There is no in-process scheduler
or loop — k8s owns the cadence.

```python
# entrypoint.py — the cron branch of the MODE dispatch
if MODE == "cron":                    # (server / consumer / worker / temporal_worker handled above)
    from crons.run import main as cron_main
    asyncio.run(cron_main())          # runs ONE job named by CRON_JOB, then exits

# crons/run.py — look up CRON_JOB, run it once, record the outcome
async def main():
    name = loaded_config.CRON_JOB
    entry = CRON_TASKS.get(name)
    if not entry:
        raise ValueError(f"No cron job found for name: {name}")
    start = asyncio.get_event_loop().time()
    try:
        result = await entry["task"]()                       # one-shot
        record_cron_job_executed(name, "success", asyncio.get_event_loop().time() - start)
        return result
    except Exception:
        record_cron_job_executed(name, "error", asyncio.get_event_loop().time() - start)
        raise
```

**The registry maps a name to a handler.** Two shapes are common — a plain `name → async callable`, or a
richer `name → {task, description, schedule}`. In the rich shape the `schedule` field is
**documentation only**; the authoritative schedule is the Helm `Crons` entry. Keep them in sync by
convention (the registry comment should point at the Helm values).

```python
# crons/registry.py — rich shape (schedule is a doc hint, NOT the real schedule)
CRON_TASKS = {
    "nightly-report": {
        "task": generate_nightly_report,
        "description": "Aggregate yesterday's events into the report table",
        "schedule": "0 2 * * *",        # for reference; defined for real in Helm values
    },
}
# simple shape: CRON_TASKS = {"nightly-report": generate_nightly_report}
```

Conventions that matter for CronJobs:
- **Idempotency is the job's responsibility.** `concurrencyPolicy: Forbid` prevents *overlap*, not
  *re-runs* — a retried/late fire may reprocess the same window. Make the handler safe to run twice
  (upsert, watermark/cursor, or a dedupe key).
- **Exit non-zero on failure.** `restartPolicy: Never` + a raised exception marks the Job failed and

From ajyadav013/claude-kit, MIT.

More from ajyadav013/claude-kit