Skip to main content

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.

Which deployments need this
DeploymentConfigure 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:

  1. Scheduler Service: The core service that maintains a job queue and executes jobs when their conditions are met
  2. 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​

ExpressionMeaningUse Case
*/1 * * * *Every minuteTesting, very frequent tasks
*/5 * * * *Every 5 minutesHigh-frequency monitoring
0 * * * *Every hourHourly reports or sync
0 2 * * *Daily at 2 AMDaily maintenance
0 0 * * 0Weekly (Sunday midnight)Weekly data cleanup
0 0 1 * *Monthly (1st of month at midnight)Monthly reports
0 12 * * MON-FRIWeekdays at noonBusiness hours task
30 9 * * *Daily at 9:30 AMScheduled 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 pathEndpoint it callsDefault cadenceWhat it does
scheduler.schedule-trigger-cron-jobtriggerScheduledTasks*/1 * * * *The metronome described above — drives execution of ScheduledTask instances
data-orchestrator.schedule-trigger-cron-jobclearOutdated17 */3 * * *Deletes orchestrator entries whose TTL has passed
session-memory.schedule-trigger-cron-jobclearOutdated*/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.*)​

ValueDefaultWhat it does
cronSchedule*/2 * * * *How often the metronome ticks. This is the floor for how quickly a ScheduledTask can start after it becomes due
suspendfalsePauses 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
concurrencyPolicyForbidAllow / Forbid / Replace. Keep Forbid: two overlapping ticks mean two evaluation passes over the same due tasks
startingDeadlineSecondsnullGrace period for a missed tick before it is skipped
successfulJobsHistoryLimit3Completed Job records kept
failedJobsHistoryLimit1Failed Job records kept
ttlSecondsAfterFinished500Garbage-collects finished Jobs
backoffLimit1Pod-level retries for a failed Job, on top of the in-script curl retries
activeDeadlineSeconds300Hard 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.

ValueDefaultWhat it does
oauth.clientIdolive-gatewayThe 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.

Changing the client is not supported

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:

EndpointGuard
scheduler /triggerScheduledTasksadmin 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​

  1. The run requests a token from Keycloak with the client-credentials grant, using olive-gateway and the secret from the auth-proxy Secret.
  2. It POSTs the in-cluster endpoint with that token as Authorization: Bearer plus a tenant-id header.
  3. The service validates the token and requires its tenant claim to match the tenant-id header. Anything invalid, mismatched or missing is rejected before the handler runs.
  4. The role guard then checks the token's roles — editor for all three endpoints.
  5. 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.

ConditionMessage 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 emptyOAUTH2_CLIENT_SECRET is empty (is the <tenant>-oauth2-proxy-secret Secret present?)
Keycloak answers non-2xx, times out, or is unreachabletoken request to Keycloak failed
The response carries no access_tokenno access_token in Keycloak response
The custom CA ConfigMap is enabled but not mountedCUSTOM_CA_FILE is set to ... but that file is not readable
Keycloak's certificate cannot be validatedcurl error 60, unable to get local issuer certificate — see Keycloak Behind an Internal CA
The target service answers non-2xxcurl 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.