Skip to content

Adds documentation for $ dapr scheduler #4909

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: v1.16
Choose a base branch
from
+424 −13
Open

Adds documentation for $ dapr scheduler #4909

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d6bf973
Adds documentation for `$ dapr scheduler`
JoshVanL Oct 3, 2025
5512bf2
Merge branch 'v1.16' into dapr-scheduler
marcduiker Oct 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 73 additions & 12 deletions daprdocs/content/en/concepts/dapr-services/scheduler.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,25 +115,85 @@ services:
- ./dapr_scheduler/2:/var/run/dapr/scheduler
```

## Back Up and Restore Scheduler Data
## Managing jobs with the Dapr CLI
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My nit would be I think we should have a section on job naming convention here since it differs slightly across 'job types'.

For example, we have actor reminders prefixed with actor/type/id/name, jobs are prefixed with app/... and wf related 'jobs' due to the reminders being used under the hood are workflow/... prefixed vs activity/... prefixed. I think we should just spell this out very explicitly to limit confusion to users.


In production environments, it's recommended to perform periodic backups of this data at an interval that aligns with your recovery point objectives.
Dapr provides a CLI for inspecting and managing all scheduled jobs, regardless of type.
The CLI is the recommended way to view, back up, and delete jobs.

### Port Forward for Backup Operations

To perform backup and restore operations, you'll need to access the embedded etcd instance. This requires port forwarding to expose the etcd ports (port 2379).
### List jobs

#### Kubernetes Example
```bash
dapr scheduler list
```

Here's how to port forward and connect to the etcd instance:
Example output:

```bash
NAME BEGIN COUNT LAST TRIGGER
actor/myactortype/actorid1/test1 -3.89s 1 2025-10-03T16:58:55Z
actor/myactortype/actorid2/test2 -3.89s 1 2025-10-03T16:58:55Z
app/test-scheduler/test1 -3.89s 1 2025-10-03T16:58:55Z
app/test-scheduler/test2 -3.89s 1 2025-10-03T16:58:55Z
activity/test-scheduler/xyz1::0::1 -888.8ms 0
activity/test-scheduler/xyz2::0::1 -888.8ms 0
workflow/test-scheduler/abc1/timer-0-TVIQGkvu +50.0h 0
workflow/test-scheduler/abc2/timer-0-OM2xqG9m +50.0h 0
```

```shell
kubectl port-forward svc/dapr-scheduler-server 2379:2379 -n dapr-system
For more detail, use the wide output format:

```bash
dapr scheduler list -o wide
```

```yaml
NAMESPACE NAME BEGIN EXPIRATION SCHEDULE DUE TIME TTL REPEATS COUNT LAST TRIGGER
default actor/myactortype/actorid1/test1 2025-10-03T16:58:55Z @every 2h46m40s 2025-10-03T17:58:55+01:00 100 1 2025-10-03T16:58:55Z
default actor/myactortype/actorid2/test2 2025-10-03T16:58:55Z @every 2h46m40s 2025-10-03T17:58:55+01:00 100 1 2025-10-03T16:58:55Z
default app/test-scheduler/test1 2025-10-03T16:58:55Z @every 100m 2025-10-03T17:58:55+01:00 1234 1 2025-10-03T16:58:55Z
default app/test-scheduler/test2 2025-10-03T16:58:55Z 2025-10-03T19:45:35Z @every 100m 2025-10-03T17:58:55+01:00 10000s 56788 1 2025-10-03T16:58:55Z
default activity/test-scheduler/xyz1::0::1 2025-10-03T16:58:58Z 0s 0
default activity/test-scheduler/xyz2::0::1 2025-10-03T16:58:58Z 0s 0
default workflow/test-scheduler/abc1/timer-0-TVIQGkvu 2025-10-05T18:58:58Z 2025-10-05T18:58:58Z 0
default workflow/test-scheduler/abc2/timer-0-OM2xqG9m 2025-10-05T18:58:58Z 2025-10-05T18:58:58Z 0
```

### Get job details

```bash
dapr scheduler get app/my-app/job1 -o yaml
```

### Delete jobs

Delete one or more specific jobs:

```bash
dapr scheduler delete app/my-app/job1 actor/MyActor/123/reminder1
```

Bulk delete jobs with filters:

```bash
dapr scheduler delete-all all
Copy link
Contributor

@cicoyle cicoyle Oct 20, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was using a wildcard (*) considered here? so it could be:

dapr scheduler delete *
dapr scheduler delete app/*
dapr scheduler delete actor/*
etc

A single quote ('') around the name might be required with the *.

This would prevent us from have a delete-all flag/subcommand, as users could delete bulk by passing the wildcard. Or even we could have dapr scheduler delete --pattern 'app/' which would also reduce the need of the delete-all subcommand.

dapr scheduler delete-all app/my-app
dapr scheduler delete-all actor/MyActorType
```

### Performing Backup and Restore
### Backup and restore jobs

Once you have access to the etcd ports, you can follow the [official etcd backup and restore documentation](https://etcd.io/docs/v3.5/op-guide/recovery/) to perform backup and restore operations. The process involves using standard etcd commands to create snapshots and restore from them.
Export all jobs to a file:

```bash
dapr scheduler export -o backup.bin
```

Re-import jobs from a backup file:

```bash
dapr scheduler import -f backup.bin
```

## Monitoring Scheduler's etcd Metrics

Expand All @@ -155,7 +215,7 @@ For more information on running Dapr on Kubernetes, visit the [Kubernetes hostin

A number of Etcd flags are exposed on Scheduler which can be used to tune for your deployment use case.

### External Etcd database
### External Etcd database

Scheduler can be configured to use an external Etcd database instead of the embedded one inside the Scheduler service replicas.
It may be interesting to decouple the storage volume from the Scheduler StatefulSet or container, because of how the cluster or environment is administered or what storage backend is being used.
Expand Down Expand Up @@ -230,4 +290,5 @@ dapr_scheduler.etcdMaxSnapshots=10

## Related links

[Learn more about the Jobs API.]({{% ref jobs_api %}})
- [Learn more about the Jobs API.]({{% ref jobs_api %}})
- [Learn more about Actor Reminders.]{{% ref "actors-features-concepts#reminders" %}})
60 changes: 60 additions & 0 deletions ...nt/en/developing-applications/building-blocks/actors/actors-timers-reminders.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,6 +187,66 @@ To use protobuf serialization for actor reminders on self-hosted, use the follow
--max-api-level=20
```

## Managing reminders with the CLI
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My pref would be if we could move this to the scheduler.md and make a note here linking to the scheduler page so all management of all job types with the cli can be seen from the one scheduler page since scheduler stores them all. Here we should still have this section but simply link to the scheduler.md so all the info is in one place.

Or if ^ is not preferred, can we at least link to this documentation from the scheduler.md saying something to the tune of please see here for how to manage reminders with the CLI bc I could totally see people going to the scheduler docs for this information too.


Actor reminders are persisted in the Scheduler.
You can manage them with the dapr scheduler CLI commands.

#### List actor reminders

```bash
dapr scheduler list --filter actor
NAME BEGIN COUNT LAST TRIGGER
actor/MyActorType/actorid1/test1 -3.89s 1 2025-10-03T16:58:55Z
actor/MyActorType/actorid2/test2 -3.89s 1 2025-10-03T16:58:55Z
```

Get reminder details

```bash
dapr scheduler get actor/MyActorType/actorid1/test1 -o yaml
```

#### Delete reminders

Delete a single reminder:

```bash
dapr scheduler delete actor/MyActorType/actorid1/test1
```

Delete all reminders for a given actor type:

```bash
dapr scheduler delete-all actor/MyActorType
```

Delete all reminders for a specific actor instance:

```bash
dapr scheduler delete-all actor/MyActorType/actorid1
```

#### Backup and restore reminders
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if we have all docs from the scheduler.md if would limit this being noted twice bc this is the same as: Export all jobs to a file:


Export all reminders:

```bash
dapr scheduler export -o reminders-backup.bin
```

Restore from a backup file:

```bash
dapr scheduler import -f reminders-backup.bin
```

#### Summary

- Reminders are stored in the Dapr Scheduler, not in the app.
- Create reminders via the Actors API
- Manage existing reminders (list, get, delete, backup/restore) using the `dapr scheduler` CLI.

## Next steps

{{< button text="Configure actor runtime behavior >>" page="actors-runtime-config.md" >}}
Expand Down
57 changes: 57 additions & 0 deletions ...ntent/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,3 +119,60 @@ or the not-before time from which the schedule should take effect
The `DueTime` and `Ttl` fields will reflect an RC3339 timestamp value reflective of the time zone provided when the job was
originally scheduled. If no time zone was provided, these values indicate the time zone used by the server running
Dapr.

### Managing jobs

While jobs are created via API calls, you can manage (list, inspect, delete, back up, and restore) jobs is by using the dapr scheduler CLI commands.

#### List jobs

```bash
dapr scheduler list --filter app
NAME BEGIN COUNT LAST TRIGGER
app/my-app/my-job -3.89s 1 2025-10-03T16:58:55Z
app/my-app/another-job -3.89s 1 2025-10-03T16:58:55Z
```

```bash
dapr scheduler list -o wide
NAMESPACE NAME BEGIN EXPIRATION SCHEDULE DUE TIME TTL REPEATS COUNT LAST TRIGGER
default app/my-app/my-job 2025-10-03T16:58:55Z @every 5s 2025-10-03T17:58:55+01:00 100 1 2025-10-03T16:58:55Z
```

```bash
dapr scheduler get app/my-app/my-job -o yaml
```

#### Delete jobs

Delete a specific job:

```bash
dapr scheduler delete app/my-app/my-job
```

Delete all jobs for an app:

```bash
dapr scheduler delete-all app/my-app
```

#### Backup and restore jobs

Export all jobs:

```bash
dapr scheduler export -o jobs-backup.bin
```

Import them later:

```bash
dapr scheduler import -f jobs-backup.bin
```

#### Summary

- Use the Jobs API to create or update jobs from applications.
- Use the dapr scheduler CLI to view, inspect, back up, or delete jobs.
- Jobs are stored in the Dapr Scheduler, ensuring reliability across restarts and deployments.
63 changes: 62 additions & 1 deletion ...nt/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,67 @@ Now that you've [authored the workflow and its activities in your application]({

{{< tabpane text=true >}}

<!--CLI-->
{{% tab "CLI" %}}
Workflow reminders are stored in the Scheduler and can be managed using the dapr scheduler CLI.

#### List workflow reminders

```bash
dapr scheduler list --filter workflow
NAME BEGIN COUNT LAST TRIGGER
workflow/my-app/instance1/timer-0-ABC123 +50.0h 0
workflow/my-app/instance2/timer-0-XYZ789 +50.0h 0
```

Get reminder details

```bash
dapr scheduler get workflow/my-app/instance1/timer-0-ABC123 -o yaml
```

#### Delete workflow reminders

Delete a single reminder:

```bash
dapr scheduler delete workflow/my-app/instance1/timer-0-ABC123
```

Delete all reminders for a given workflow app"

```bash
dapr scheduler delete-all workflow/my-app
```

Delete all reminders for a specific workflow instance:

```bash
dapr scheduler delete-all workflow/my-app/instance1
```

#### Backup and restore reminders

Export all reminders:

```bash
dapr scheduler export -o workflow-reminders-backup.bin
```

Restore from a backup file:

```bash
dapr scheduler import -f workflow-reminders-backup.bin
```

#### Summary

- Workflow reminders are persisted in the Dapr Scheduler.
- Create workflow reminders via the Workflow API.
- Manage reminders (list, get, delete, backup/restore) with the dapr scheduler CLI.

{{% /tab %}}

<!--Python-->
{{% tab "Python" %}}

Expand Down Expand Up @@ -356,7 +417,7 @@ To resume a workflow with an ID `12345678`, run:
curl -X POST "http://localhost:3500/v1.0/workflows/dapr/12345678/resume"
```

### Purge a workflow
### Purge a workflow

The purge API can be used to permanently delete workflow metadata from the underlying state store, including any stored inputs, outputs, and workflow history records. This is often useful for implementing data retention policies and for freeing resources.

Expand Down
16 changes: 16 additions & 0 deletions daprdocs/content/en/getting-started/quickstarts/jobs-quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,15 @@ dapr run -f .
== APP - job-scheduler == Deleted job: BB-8
```

You should eventually see the jobs being scheduled in scheduler:

```bash
$ dapr scheduler list
NAME TARGET BEGIN COUNT LAST TRIGGER
C-3PO job +13.40s 0
R2-D2 job +3.40s 0
```

After 5 seconds, the terminal output should present the `R2-D2` job being processed:

```text
Expand All @@ -95,6 +104,13 @@ After 10 seconds, the terminal output should present the `C3-PO` job being proce
== APP - job-service == Executing maintenance job: Memory Wipe
```

The jobs will no longer be listed in the scheduler:

```bash
$ dapr scheduler list
NAME TARGET BEGIN COUNT LAST TRIGGER
```

Once the process has completed, you can stop and clean up application processes with a single command.

```bash
Expand Down
Loading
Loading