Schedules
Cron, rate and one-time schedules with time zones, retries and dead letters.
A schedule runs something on a clock: call a webhook every five minutes, put a message on a queue on the first of the month, start a CI workflow at 03:00 Berlin time, run an app's job every night. When the call fails it is retried with backoff; when it keeps failing it goes to a dead-letter queue and an alarm fires. Every run is an invocation you can read: when it was due, each attempt, what the target answered, and the output.
Deutsche Cloud schedules work like Amazon EventBridge Scheduler schedules.
| You want | Use |
|---|---|
| A command in your app's image on a cron, kept by its machine | the app's scheduled jobs |
| The same job with a time zone, retries, a dead-letter queue | a schedule with an app job target |
| A workflow that runs on a schedule written in the repository | on.schedule in the workflow file |
| A workflow started with inputs, retries or in a time zone | a schedule with a CI target |
| Anything with an HTTP endpoint | a schedule with an HTTP target |
| Work handed to your own consumers | a schedule with a queue target |
When it fires
| Expression | Fires |
|---|---|
cron(0 3 * * *) |
five-field cron (minute hour day-of-month month day-of-week), in the time zone |
rate(5 minutes) |
every 5 minutes (minute(s), hour(s), day(s)), counted from the start |
at(2026-12-24T18:00:00) |
once, at that local time in the time zone |
- Time zone: any IANA name (
Europe/Berlin,UTC, …). A cron reads that zone's wall clock. A time skipped when the clock jumps forward fires once, right after the jump; a time that happens twice when the clock goes back fires twice (so*/15keeps running every 15 real minutes). - Start and end date: nothing fires outside them.
- Flexible window: with a window of 15 minutes, each invocation runs at a random moment in the 15 minutes after its time — to spread load.
- Missed runs: if the scheduler was not running when a run was due (more than two minutes
late),
catchUpdecides:latest(default) runs the most recent missed one once,noneskips them,allruns each (at most 100, and none older than the maximum event age). - After an
at()schedule has run, it stays (actionAfterCompletion: none) or is deleted (delete).
The console shows the next ten times as you type; GET /scheduler/api/preview does the same.
Targets
| Target | Does | Counts as success |
|---|---|---|
http |
POST (or PUT/PATCH/GET) to an https:// URL, signed |
a 2xx within the timeout |
queue |
sends the input as a message to one of your queues | the message is stored |
ci |
starts a workflow file at a branch or tag (workflow_dispatch) |
the run is created |
app_job |
runs one of an app's jobs on its machine, like Run now | the job exits 0 |
Input (HTTP body, queue message, CI input values) may contain <ews.scheduler.scheduled-time>,
<ews.scheduler.execution-id>, <ews.scheduler.attempt-number> and
<ews.scheduler.schedule-name>, replaced on every attempt. Without an input, HTTP and queue
targets send {"schedule", "invocationId", "scheduledTime", "attempt", "trigger"}.
An app job target runs a job you defined on the app's Jobs page. Turn the job's own schedule
off (enabled: false) to run it only when the schedule fires it. The invocation waits for the job's
exit code and output; a non-zero exit is a failure, retried like any other. The app's job history
shows which runs a schedule asked for.
A CI target counts as delivered when the run starts. The run's conclusion is recorded on the
invocation afterwards and counted in the TargetRunFailed metric, but a failed workflow is not
re-run automatically.
Verifying an HTTP call
Every HTTP schedule has its own secret (Invocations → Reveal secret, or
GET /scheduler/api/schedules/{name}/signing-secret). Each request carries these headers, each
also under its name from before the rename, X-EWS-…, with the same value:
X-DCLOUD-Timestamp: 1763000000
X-DCLOUD-Signature-256: sha256=<hex HMAC-SHA256 of "<timestamp>.<body>" with the secret>
X-DCLOUD-Invocation-Id: 6f1c… (the same on every retry: de-duplicate on it)
X-DCLOUD-Schedule-Name: nightly-report
X-DCLOUD-Scheduled-Time: 2026-11-13T02:00:00.000Z
X-DCLOUD-Attempt: 1import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(req, rawBody, secret) {
const ts = req.headers['x-dcloud-timestamp'];
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // replay window
const want = 'sha256=' + createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
return req.headers['x-dcloud-signature-256']
.split(',')
.some((sig) => sig.length === want.length && timingSafeEqual(Buffer.from(sig), Buffer.from(want)));
}After rotate (POST …/signing-secret/rotate) the old secret keeps signing for 24 hours and both
signatures are sent, comma separated, so you can switch the receiver over without an outage.
URLs must be https:// on port 443 and resolve to public addresses; redirects are not followed.
Who it runs as
A schedule that calls Deutsche Cloud (queue, CI, app job, or a dead-letter queue) acts as an IAM role you
give it. Giving it the role needs iam:PassRole on that role. Every invocation is then authorized
as the role — queue:SendMessage on the queue, ci:StartWorkflow on the repository,
deploy:RunJob on the app — and recorded in the audit log under assumed-role/<role>. Take the
permission away from the role and the next invocation fails with AccessDenied, visibly.
A minimal role policy for a schedule that sends to reports and dead-letters to reports-dlq:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "queue:SendMessage",
"Resource": ["rn:ews:de1:<org-id>:queue:queue/reports", "rn:ews:de1:<org-id>:queue:queue/reports-dlq"]
}
]
}When it fails
- Retries: up to
retryMaxAttempts(0–20, default 3) more attempts, the first afterretryBackoffSeconds(default 30), doubling each time (±20 %, at most 15 minutes). - Retried: HTTP 5xx, 429 and 408, timeouts, connection errors, a job run that failed, timed out
or got no machine. Not retried: other 4xx,
AccessDenied, a target that no longer exists (TargetMissing), an invalid workflow. - Maximum event age (
maxEventAgeSeconds, 60 s – 24 h): no attempt starts later than this after the scheduled time. - Dead-letter queue: an invocation that failed for good is sent there as JSON —
{schedule, scheduleRn, invocationId, scheduledTime, attempts, errorCode, error, target}. - Failure alarm:
failureAlarm: {notifyEmails: [...]}creates an alarm on this schedule'sInvocationsFailed(sum > 0 over a minute) under Monitoring → Alarms; it is deleted with the schedule.
Deleting a schedule's target (the queue, the app, the job, the role) does not stop the schedule: its
invocations fail as TargetMissing, which you see and are alarmed on.
Seeing what happened
- Invocations (console,
dcloud scheduler schedules invocations <name>): status (pending,running,waitingfor a job run,retry_wait,succeeded,failed,dead_lettered,dropped), attempts, the target's answer and output, links to the job run or CI run. - Log: one stream per invocation, every attempt and its answer
(
GET /scheduler/api/schedules/{name}/invocations/{id}, or Monitoring logs withresourceType=schedule). - Events: created, changed, each finished invocation, missed runs.
- Metrics in namespace
EWS/Scheduler, dimensionScheduleName:InvocationAttempts,InvocationsSucceeded,InvocationsFailed,InvocationsDeadLettered,InvocationsDropped,TargetRunFailed— chart them and alarm on them like your own metrics.
Guarantees
- One invocation per scheduled time, even with several scheduler workers running.
- At-least-once delivery: an attempt can reach the target twice if the worker dies after the
target accepted it and before the result was written. Use
X-DCLOUD-Invocation-Id(HTTP), thedcloud-invocation-idmessage attribute (queues; on a FIFO queue it is the deduplication id) to de-duplicate. An app job attempt never starts twice. - Times are accurate to about a second; claims are made up to a minute ahead and handed to the worker queue to start at the due time.
API, CLI, Terraform
dcloud scheduler schedules create --name nightly-report --expression 'cron(0 3 * * *)' \
--timezone Europe/Berlin --role-name reports-scheduler \
--target '{"type":"queue","queueName":"reports"}' --dead-letter-queue reports-dlq
dcloud scheduler schedules invoke nightly-report # run it now
dcloud scheduler schedules invocations nightly-reportresource "dcloud_schedule" "nightly" {
name = "nightly-report"
expression = "cron(0 3 * * *)"
timezone = "Europe/Berlin"
role_name = dcloud_iam_role.reports.name
target = jsonencode({ type = "queue", queueName = "reports" })
}Limits: 500 schedules per organization, one minute between runs at the least, 64 KiB input, 1 000 invocations kept per schedule (30 days).