diff --git a/daprdocs/content/en/concepts/dapr-services/scheduler.md b/daprdocs/content/en/concepts/dapr-services/scheduler.md index a143ee08b97..9096bf86a32 100644 --- a/daprdocs/content/en/concepts/dapr-services/scheduler.md +++ b/daprdocs/content/en/concepts/dapr-services/scheduler.md @@ -115,25 +115,85 @@ services: - ./dapr_scheduler/2:/var/run/dapr/scheduler ``` -## Back Up and Restore Scheduler Data +## Managing jobs with the Dapr CLI -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 +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 @@ -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. @@ -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" %}}) diff --git a/daprdocs/content/en/developing-applications/building-blocks/actors/actors-timers-reminders.md b/daprdocs/content/en/developing-applications/building-blocks/actors/actors-timers-reminders.md index 736547e91d6..8d174a8ecc3 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/actors/actors-timers-reminders.md +++ b/daprdocs/content/en/developing-applications/building-blocks/actors/actors-timers-reminders.md @@ -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 + +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 + +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" >}} diff --git a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md index fbeb0f50a0a..dcd49a80aae 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md +++ b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md @@ -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. diff --git a/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md b/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md index de4f6b23249..8b5dd89f855 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md +++ b/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md @@ -10,6 +10,67 @@ Now that you've [authored the workflow and its activities in your application]({ {{< tabpane text=true >}} + +{{% 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 %}} + {{% tab "Python" %}} @@ -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. diff --git a/daprdocs/content/en/getting-started/quickstarts/jobs-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/jobs-quickstart.md index 73e9e4b5c24..3ea0a9771c4 100644 --- a/daprdocs/content/en/getting-started/quickstarts/jobs-quickstart.md +++ b/daprdocs/content/en/getting-started/quickstarts/jobs-quickstart.md @@ -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 @@ -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 diff --git a/daprdocs/content/en/reference/cli/dapr-scheduler.md b/daprdocs/content/en/reference/cli/dapr-scheduler.md new file mode 100644 index 00000000000..61d40f190bb --- /dev/null +++ b/daprdocs/content/en/reference/cli/dapr-scheduler.md @@ -0,0 +1,156 @@ +--- +type: docs +title: "dapr scheduler" +linkTitle: "scheduler" +description: "Manage Dapr Scheduler jobs and reminders using the dapr CLI" +weight: 3000 +--- + +# dapr scheduler + +Manage scheduled jobs and reminders stored in the Dapr Scheduler. + +``` bash +dapr scheduler [command] +``` + +## Aliases +- `scheduler` +- `sched` + +## Available Commands + +- [list](#dapr-scheduler-list): List scheduled jobs +- [get](#dapr-scheduler-get): Get a scheduled job by key +- [delete](#dapr-scheduler-delete): Delete a scheduled job by key +- [delete-all)](#dapr-scheduler-delete-all): Delete all scheduled jobs by key prefix +- [export](#dapr-scheduler-export): Export all scheduled jobs to a file +- [import](#dapr-scheduler-import): Import scheduled jobs from a file + + +## Global Flags + +| Flag | Description | +| -k, --kubernetes | Perform operation on a Kubernetes Dapr cluster | +| -n, --namespace string | Namespace of the Dapr app (default "default") | +| --scheduler-namespace string | Namespace where the scheduler runs (default "dapr-system") | + +## dapr scheduler list + +List scheduled jobs in Scheduler. + +```bash +dapr scheduler list [flags] +``` + +### Flags + +- `--filter string` – Filter jobs by type. One of: all, app, actor, workflow, activity (default all) +- `-o, --output string` – Output format: short, wide, yaml, json (default short) + +### Examples + +```bash +$ dapr scheduler list +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 +``` + +```bash +$ dapr scheduler list -o wide +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 +``` + +## dapr scheduler get + +Get one or more scheduled jobs/reminders by key. + +```bash +dapr scheduler get [flags] +``` + +### Key formats + +- App job: `app//` +- Actor reminder: `actor///` +- Workflow reminder: `workflow///` +- Activity reminder: `activity//` + +### Flags + +- `-o, --output string` – Output format: `short`, `wide`, `yaml`, `json` (default `short`) + +### Examples + +```bash +dapr scheduler get app/my-app/job1 -o yaml +``` + +## dapr scheduler delete + +Delete one or more jobs. + +```bash +dapr scheduler delete +``` + +### Aliases +- `delete`, `d`, `del` + +### Examples + +```bash +dapr scheduler delete app/my-app/job1 actor/MyActor/123/reminder1 +``` + +## dapr scheduler delete-all + +Bulk delete jobs by filter key. + +```bash +dapr scheduler delete-all +``` + +### Aliases + +- `delete-all`, `da`, `delall` + +### Examples + +```bash +dapr scheduler delete-all all +dapr scheduler delete-all app/my-app +dapr scheduler delete-all actor/MyActorType +``` + +## dapr scheduler export + +Export all jobs and reminders to a file. + +```bash +dapr scheduler export -o backup.bin +``` + +## dapr scheduler import + +Import jobs and reminders from a file. + +```bash +dapr scheduler import -f backup.bin +``` +