Schedule a recurring job

Goal

Work that runs on a schedule, with a stated answer for what happens when a firing overlaps or is missed.

Before you start

• An image that runs the work and exits.
• A decision about the time zone. It is stated in the description rather than inherited from whatever the platform process is running in.
• A decision about overlapping firings, and about how late a missed firing may still start.

Dashboard

Steps

1. Open Scheduled work and choose New schedule.
2. Give it a name, the cron expression and the time zone.
3. Fill in the job it runs: image, command, networks, resources and retry limit.
4. Choose what an overlapping firing does, and how late a missed firing may start.
5. Save, and confirm the next firing time shown is the one you meant.

YAML manifest

Steps

1. Write a kind: CronJob document with the schedule and a job template.
2. Apply it. Every field is in the cronjob reference.

REST API

Steps

1. POST /api/v1/cronjobs with the schedule and the job template.
2. GET /api/v1/cronjobs/{name} to see the stored schedule and its state.
3. PUT /api/v1/cronjobs/{name} to change it — including suspending it.

CLI

Steps

1. There is no CLI command for scheduled work; use the API or the dashboard.
2. odysseus spec-audit reports on stored specs, which includes schedules.

apiVersion: odysseus/v1
kind: CronJob
metadata:
  name: addriva-etl-ingest
  labels: {app: addriva-etl-ingest, project: addriva}
spec:
  schedule: "17 1 1 * *"
  # no timezone: UTC, matching the retired host crontab
  concurrencyPolicy: skip
  startingDeadlineSeconds: 300
  suspend: false
  jobTemplate:
    image: registry.delta-telematics.ca/addriva/etl:0.1.0
    placement: {node: vps-71623e00}
    networks: [addriva-internal]
    command: ["ingest", "--sources", "oda,geoyukon,adresses_qc", "--version", "ODA_v1_2021"]
    environment:
      ADDRIVA_S3_ENDPOINT: "http://addriva-seaweedfs:8333"
      ADDRIVA_S3_BUCKET: "addriva-raw"
      ADDRIVA_OS_HOST: "http://addriva-opensearch:9200"
      ADDRIVA_OS_USER: "admin"
    secrets:
      - vaultPath: deployments/addriva-etl
        rotation: restart
    resources:
      limits:   {cpu: "2", memory: 3500Mi}
      requests: {cpu: 500m, memory: 1Gi}
    restartPolicy: "no"
    backoffLimit: 2
    activeDeadlineSeconds: 14400
    ttlAfterFinished: 4392h

Validated against CronJobManifest · testdata/docs-examples/monthly-cronjob.yaml

Verify

The schedule shows its next firing at the time you expect, in the zone you set, and the first run appears in its history.

Evidence this worked

The run history under GET /api/v1/cronjobs/{name} shows run numbers rising on the same job rather than a new job per firing. That is deliberate: a fresh name per firing would give every run the same number and scatter the retention limit across unboundedly many names.

When it fails

• The schedule is refused. The grammar, the accepted field values and the deliberate rejections are in the cronjob reference.
• A firing did not happen. It overlapped a run and your policy was to skip it, or it was missed while the platform was down and arrived later than the window you allowed.
• The job template sets identity or status. The schedule owns those; authored values are zeroed rather than rejected.
• Every code: rejections and alterations.