Cron Scheduler Configuration
The OLIVE Platform includes a scheduler service that executes jobs on a recurring schedule. Configure scheduled tasks using standard cron expressions in your values.yaml file.
| Deployment | Configure the trigger? |
|---|---|
Development (single-no-auth) | Yes |
Tenant (multi-tenant) | Yes — once per tenant |
Shared runtime pool (multi-shared) | No |
The shared pool runs no scheduler cron job. Scheduled jobs belong to a tenant and its content, so the trigger lives in the deployment that owns them — each tenant's, and the development deployment's, which is a tenant and a pool at once. Adding scheduler.schedule-trigger-cron-job to the shared pool's values achieves nothing; leave it out so the values file does not imply a CronJob that is not there.
What Is the OLIVE Scheduler?
The OLIVE Scheduler consists of two key components:
- Scheduler Service: The core service that maintains a job queue and executes jobs when their conditions are met
- Scheduler Trigger (Metronome): A cron job (
schedule-trigger-cron-job) that provides periodic "ticks" — at each tick, the scheduler service checks if any jobs are due for execution
Think of it like a metronome in music: the schedule-trigger-cron-job provides the steady beat, and the scheduler service listens to each beat and decides which jobs should run. The frequency of the ticks determines how often the scheduler checks for jobs, but does not define when individual jobs execute.
Common Use Cases
- Running data synchronization jobs at off-peak hours
- Periodic maintenance and cleanup tasks
- Scheduled reporting or data export
- Background processing orchestration
Configure the Scheduler
Understanding the Trigger Frequency vs Job Execution
The schedule-trigger-cron-job configuration controls how frequently the scheduler checks for jobs to execute. This is the metronome that provides "ticks":
- A
*/1 * * * *schedule means the scheduler checks for jobs every minute - A
0 * * * *schedule means the scheduler checks for jobs every hour - Each check is an opportunity for the scheduler service to find and execute any pending jobs
The actual job execution is determined by individual job configurations, not by the trigger frequency. However, the trigger frequency sets a practical limit on how quickly jobs can start executing after their scheduled time arrives.
Example: If you have a job scheduled to run at 2:00 AM and the trigger is set to check every 5 minutes, the job might not start until the next 5-minute interval after 2:00 AM.
Basic Configuration
In the development deployment's or the tenant's values.yaml — not the shared pool's — the scheduler trigger is configured under scheduler.schedule-trigger-cron-job:
scheduler:
schedule-trigger-cron-job:
schedule:
cronSchedule: "*/5 * * * *"
Understanding the Cron Schedule
A cron expression has 5 fields:
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6, where 0 = Sunday)
│ │ │ │ │
│ │ │ │ │
* * * * *
Common Cron Expressions
| Expression | Meaning | Use Case |
|---|---|---|
*/1 * * * * | Every minute | Testing, very frequent tasks |
*/5 * * * * | Every 5 minutes | High-frequency monitoring |
0 * * * * | Every hour | Hourly reports or sync |
0 2 * * * | Daily at 2 AM | Daily maintenance |
0 0 * * 0 | Weekly (Sunday midnight) | Weekly data cleanup |
0 0 1 * * | Monthly (1st of month at midnight) | Monthly reports |
0 12 * * MON-FRI | Weekdays at noon | Business hours task |
30 9 * * * | Daily at 9:30 AM | Scheduled backup |
Build Custom Expressions
Use an online cron expression tester to validate your expression before deploying. For example: https://crontab.guru/
Common patterns:
Every N minutes:
*/5 * * * * (every 5 minutes)
*/15 * * * * (every 15 minutes)
*/30 * * * * (every 30 minutes)
Examples
Frequent Testing
With this configuration, the scheduler will check for pending jobs every two minutes.
scheduler:
schedule-trigger-cron-job:
schedule:
# Trigger metronome checks every minute for rapid job execution
cronSchedule: "*/2 * * * *"
Three Services Use This Trigger
schedule-trigger-cron-job is a shared chart, and three services instantiate it independently. Each gets its own CronJob, its own endpoint and its own cadence, configured under that service's own key:
| Values path | Endpoint it calls | Default cadence | What it does |
|---|---|---|---|
scheduler.schedule-trigger-cron-job | triggerScheduledTasks | */1 * * * * | The metronome described above — drives execution of ScheduledTask instances |
data-orchestrator.schedule-trigger-cron-job | clearOutdated | 17 */3 * * * | Deletes orchestrator entries whose TTL has passed |
session-memory.schedule-trigger-cron-job | clearOutdated | */30 * * * * | Deletes session-memory entries whose TTL has passed |
Only the first is a scheduler concern. The other two are storage maintenance: they keep per-tenant tables from growing without bound. For all three, cronSchedule and suspend are the only values intended to be set — the rest of the chart's values are internal wiring, and changing them stops the trigger working.
All three render only in a tenant or development deployment, never in the shared runtime pool.
Full Values Reference
Everything the trigger chart exposes lives under the service's schedule-trigger-cron-job key. cronSchedule is the only value most deployments need to set; the rest are listed so an operator can see what exists before reaching for a patch.
Schedule and run control (schedule.*)
| Value | Default | What it does |
|---|---|---|
cronSchedule | */2 * * * * | How often the metronome ticks. This is the floor for how quickly a ScheduledTask can start after it becomes due |
suspend | false | Pauses the trigger. true stops new runs while keeping the CronJob and its history. This is the supported way to stop scheduled execution for a tenant — no scheduled task runs while it is set |
concurrencyPolicy | Forbid | Allow / Forbid / Replace. Keep Forbid: two overlapping ticks mean two evaluation passes over the same due tasks |
startingDeadlineSeconds | null | Grace period for a missed tick before it is skipped |
successfulJobsHistoryLimit | 3 | Completed Job records kept |
failedJobsHistoryLimit | 1 | Failed Job records kept |
ttlSecondsAfterFinished | 500 | Garbage-collects finished Jobs |
backoffLimit | 1 | Pod-level retries for a failed Job, on top of the in-script curl retries |
activeDeadlineSeconds | 300 | Hard cap on one run's total runtime |
Authentication (schedule.oauth.*, schedule.authAPI)
In an authenticated deployment (global.authentication: true) each run first obtains an access token from Keycloak with the client-credentials grant, then sends it as a bearer token on the POST. In single-no-auth the token step is skipped entirely.
| Value | Default | What it does |
|---|---|---|
oauth.clientId | olive-gateway | The Keycloak client used for the grant. The realm is global.tenant |
The client secret is not a value. It is read at runtime from the <tenant>-oauth2-proxy-secret Secret (key client-secret) that keycloak-setup maintains in the namespace. The pod needs no Vault login and mounts no ServiceAccount token.
olive-gateway is the client used by all three triggers, and it must stay that way. The oauth.clientId value exists but is not a customization point: the secret comes from the auth-proxy Secret, so naming a different client sends that client's id with olive-gateway's secret and Keycloak answers 401 invalid_client — every run fails at the token request, and scheduled execution and TTL cleanup both stop.
In Keycloak, olive-gateway must therefore keep its name and its editor role. Do not rename it, delete it, or remove the role. All three endpoints the triggers call are guarded by that role:
| Endpoint | Guard |
|---|---|
scheduler /triggerScheduledTasks | admin or editor role |
data-orchestrator /clearOutdated/ | editor role |
session-memory /clearOutdated/ | editor role |
Replacing olive-gateway with a dedicated service-account client would require a change to this chart and to keycloak-setup, and is not something a platform administrator can configure. See also Tenant Admin → User and Access Management.
How a Scheduled Call Is Authorized
- The run requests a token from Keycloak with the client-credentials grant, using
olive-gatewayand the secret from the auth-proxy Secret. - It POSTs the in-cluster endpoint with that token as
Authorization: Bearerplus atenant-idheader. - The service validates the token and requires its tenant claim to match the
tenant-idheader. Anything invalid, mismatched or missing is rejected before the handler runs. - The role guard then checks the token's roles —
editorfor all three endpoints. - The token is carried onward: calls the service makes to other OLIVE services in the cluster reuse it, so the whole triggered sequence runs with the permissions of
olive-gateway.
Two consequences. Scheduled execution is genuinely limited by that client's role, so an API needing admin cannot be scheduled while olive-gateway holds only editor. And the token stays inside the cluster — calls an HTTP datapoint makes to an external host do not carry it, which is why such a datapoint needs its own Auth configuration.
Keycloak Behind an Internal CA
The token request is the trigger's only HTTPS call, so if Keycloak's certificate is issued by your own certificate authority rather than a public one, the trigger needs that CA. It picks it up automatically from the platform-wide setting in Custom CA Certificates — global.customCa.enabled: true plus services.infra.custom-ca: true — with nothing to configure on the trigger itself. A publicly trusted Keycloak keeps working either way.
What Makes a Run Fail
Each run exits non-zero — and the Job is marked failed — on any of the following. A failed run means the metronome missed a beat: no scheduled task was evaluated at that tick.
| Condition | Message in the pod log |
|---|---|
The composed URL is empty or not http(s) | CRON_API_URL is empty or not an http(s) URL |
| The auth-proxy Secret is absent or empty | OAUTH2_CLIENT_SECRET is empty (is the <tenant>-oauth2-proxy-secret Secret present?) |
| Keycloak answers non-2xx, times out, or is unreachable | token request to Keycloak failed |
The response carries no access_token | no access_token in Keycloak response |
| The custom CA ConfigMap is enabled but not mounted | CUSTOM_CA_FILE is set to ... but that file is not readable |
| Keycloak's certificate cannot be validated | curl error 60, unable to get local issuer certificate — see Keycloak Behind an Internal CA |
| The target service answers non-2xx | curl exit status, with the response body printed |
Non-2xx responses from the target service already fail the run; this is not optional. The trigger retries a failing call a few times first, so a persistent 401 takes a moment to surface as a failed Job.
The secret and the bearer token are never passed on a command line or echoed — the form body and the Authorization header are piped in on stdin, so neither appears in ps or in the logs. The log line at token time names only the client_id.
Checking the trigger
# Is the CronJob there, and is it suspended?
kubectl -n <tenant-namespace> get cronjob -l olive/workload=schedule-trigger
# What did the last runs do?
kubectl -n <tenant-namespace> get jobs --sort-by=.metadata.creationTimestamp | tail
kubectl -n <tenant-namespace> logs job/<job-name>
# Run one tick now, out of schedule
kubectl -n <tenant-namespace> create job manual-tick-1 \
--from=cronjob/schedule-trigger-<scheduler-service-name>
With network policies enabled, a trigger whose runs all time out on the token request is usually a global.keycloakIpBlocks value that no longer matches Keycloak's address — a stale range fails closed. See What keycloakIpBlocks is for.
A run that reports Recv failure: Connection reset by peer (curl 56) on a mesh-enabled cluster is usually the pod-startup race, not a firewall — the trigger retries internally to ride it out. If it persists across several ticks, raise it with the platform team before suspecting NetworkPolicy.
Related Topics
- Chart Values Reference - Core configuration properties
- Resource Scaling - Scale scheduler if needed for high-frequency jobs
- Custom CA Certificates - Internal PKI, and why the trigger does not pick it up