Jobs [Distributed Scheduler] API docs, pt.1

daprdocs/content/en/concepts/building-blocks-concept.md

@@ -29,4 +29,5 @@ Dapr provides the following building blocks:
 | [**Secrets**]({{< ref "secrets-overview.md" >}}) | `/v1.0/secrets` | Dapr provides a secrets building block API and integrates with secret stores such as public cloud stores, local stores and Kubernetes to store the secrets. Services can call the secrets API to retrieve secrets, for example to get a connection string to a database.
 | [**Configuration**]({{< ref "configuration-api-overview.md" >}}) | `/v1.0/configuration` | The Configuration API enables you to retrieve and subscribe to application configuration items for supported configuration stores. This enables an application to retrieve specific configuration information, for example, at start up or when configuration changes are made in the store. 
 | [**Distributed lock**]({{< ref "distributed-lock-api-overview.md" >}}) | `/v1.0-alpha1/lock` | The distributed lock API enables you to take a lock on a resource so that multiple instances of an application can access the resource without conflicts and provide consistency guarantees.  
-| [**Cryptography**]({{< ref "cryptography-overview.md" >}}) | `/v1.0-alpha1/crypto` | The Cryptography API enables you to perform cryptographic operations, such as encrypting and decrypting messages, without exposing keys to your application.
+| [**Cryptography**]({{< ref "cryptography-overview.md" >}}) | `/v1.0-alpha1/crypto` | The Cryptography API enables you to perform cryptographic operations, such as encrypting and decrypting messages, without exposing keys to your application.
+| [**Scheduler**]({{< ref "scheduler-overview.md" >}}) | `/v1.0-alpha1/scheduler` | The Scheduler API enables you to schedule and orchestrate jobs at scale in your distributed environment.

daprdocs/content/en/concepts/dapr-services/scheduler.md

@@ -0,0 +1,24 @@
+---
+type: docs
+title: "Dapr Scheduler control plane service overview"
+linkTitle: "Scheduler"
+description: "Overview of the Dapr scheduler process"
+---
+
+The Dapr Scheduler service is used to schedule and orchestrate jobs within your application environment running in [self-hosted mode]({{< ref self-hosted >}}) or on [Kubernetes]({{< ref kubernetes >}}). 
+
+## Self-hosted mode
+
+The scheduler service Docker container is started automatically as part of `dapr init`. It can also be run manually as a process if you are running in [slim-init mode]({{< ref self-hosted-no-docker.md >}}).
+
+## Kubernetes mode
+
+The scheduler service is deployed as part of `dapr init -k`, or via the Dapr Helm charts. For more information on running Dapr on Kubernetes, visit the [Kubernetes hosting page]({{< ref kubernetes >}}).
+
+
+### Examples
+
+
+## Related links
+
+[Learn more about the Scheduler API.]({{< ref scheduler_api.md >}})

daprdocs/content/en/concepts/overview.md

@@ -54,6 +54,7 @@ Each of these building block APIs is independent, meaning that you can use any n
 | [**Configuration**]({{< ref "configuration-api-overview.md" >}})  | The configuration API enables you to retrieve and subscribe to application configuration items from configuration stores. 
 | [**Distributed lock**]({{< ref "distributed-lock-api-overview.md" >}})  | The distributed lock API enables your application to acquire a lock for any resource that gives it exclusive access until either the lock is released by the application, or a lease timeout occurs. 
 | [**Cryptography**]({{< ref "cryptography-overview.md" >}}) | The cryptography API provides an abstraction layer on top of security infrastructure such as key vaults. It contains APIs that allow you to perform cryptographic operations, such as encrypting and decrypting messages, without exposing keys to your applications.
+| [**Scheduler**]({{< ref "scheduler-overview.md" >}}) | The scheduler API is a way to schedule and orchestrate jobs at scale across a distributed computing environment at specific times or intervals.
 
 ### Cross-cutting APIs
 

daprdocs/content/en/developing-applications/building-blocks/scheduler/_index.md

@@ -0,0 +1,7 @@
+---
+type: docs
+title: "Scheduler"
+linkTitle: "Scheduler"
+weight: 120
+description: "Manage the scheduling and orchestration of jobs across distributed computing environments"
+---

daprdocs/content/en/developing-applications/building-blocks/scheduler/howto-use-scheduler.md

@@ -0,0 +1,30 @@
+---
+type: docs
+title: "How-To: Set up a scheduler"
+linkTitle: "How-To: Set up a scheduler"
+weight: 2000
+description: "Learn how to use the scheduler API to schedule jobs"
+---
+
+Now that you've learned what the [Dapr scheduler building block]({{< ref scheduler-overview.md >}}) provides, learn how it can work in your environment. The below code example loosely describes an application that schedules and orchestrates an application.
+
+<!-- 
+Include a diagram or image, if possible. 
+-->
+
+<!-- 
+Make sure the how-to includes examples for multiple programming languages, OS, or deployment targets, if applicable. 
+-->
+
+## Configure the scheduler
+
+
+<!-- 
+Each H2 step should start with a verb/action word.
+-->
+
+
+## Next steps
+
+- [Learn more about the Scheduler control plane service]({{< ref "concepts/dapr-services/scheduler.md" >}})
+- [Scheduler API reference]({{< ref scheduler_api.md >}})

daprdocs/content/en/developing-applications/building-blocks/scheduler/scheduler-overview.md

@@ -0,0 +1,51 @@
+---
+type: docs
+title: "Scheduler overview"
+linkTitle: "Overview"
+weight: 1000
+description: "Overview of the scheduler API building block"
+---
+
+The Scheduler API works as an orchestrator for scheduling jobs in the future,  either at a specific time or a specific interval. The scheduler helps you with scheduling jobs, including scalable actor reminders. 
+
+The Scheduler consists of two parts that work together to seamlessly schedule jobs across all of Dapr's API building blocks:
+- The Scheduler building block
+- [The Scheduler control plane service]({{< ref "concepts/dapr-services/scheduler.md" >}})
+
+<img src="/images/scheduler/scheduler-architecture.png" alt="Diagram showing basics of the Scheduler control plane and the Scheduler API">
+
+## How it works
+
+The Scheduler building block is a job orchestrator, not executor. The design guarantees *at least once* job execution with a bias towards durability and horizontal scaling over precision. This means:
+- **Guaranteed:** A job is never invoked *before* the schedule is due.
+- **Not guaranteed:** A ceiling time on when the job is invoked *after* the due time is reached.
+
+All job details and user-associated data for scheduled jobs are stored in the embedded Etcd. 
+
+## Features
+
+### Delayed pub/sub
+
+The Scheduler building block enables you to delay your pub/sub messaging. You can publish a message in a future specific time -- for example, a week from today, or a specific UTC date/time.
+
+### Scheduled service invocation
+
+The Scheduler building block provides the [service invocation]({{< ref service-invocation-overview.md >}}) building block with an orchestrator that schedules method calls between applications.
+
+### Schedule jobs across multiple replicas
+
+The Scheduler service enables the scheduling of jobs to scale across multiple replicas, while guaranteeing that a job is only triggered by 1 scheduler service instance.
+
+### Scheduler reminders
+
+Actors have actor reminders, but present some limitations involving scalability. Make reminders more scalable by using `SchedulerReminders`. 
+
+## Try out the Scheduler
+
+You can try out the Scheduler building block directly in your application. After [Dapr is installed]({{< ref install-dapr-cli.md >}}), you can begin using the Scheduler API, starting with [the How-to: Set up a Scheduler guide]({{< ref howto-use-scheduler.md >}}).
+
+## Next steps
+
+- [Learn how to use the scheduler in your environment]({{< ref howto-use-scheduler.md >}})
+- [Learn more about the Scheduler control plane service]({{< ref "concepts/dapr-services/scheduler.md" >}})
+- [Scheduler API reference]({{< ref scheduler_api.md >}})

daprdocs/content/en/getting-started/install-dapr-selfhost.md

@@ -21,9 +21,10 @@ Dapr initialization includes:
 1. Running a **Zipkin container instance** for observability.
 1. Creating a **default components folder** with component definitions for the above.
 1. Running a **Dapr placement service container instance** for local actor support.
+1. Running a **Dapr scheduler service container instance** for job orchestration.
 
 {{% alert title="Kubernetes Development Environment" color="primary" %}}
-To initialize Dapr in your local or remote **Kubernetes** cluster for development (including the Redis and Zipkin containers listed above), see [how to initialize Dapr for development on Kubernetes]({{<ref "kubernetes-deploy.md#install-dapr-from-the-official-dapr-helm-chart-with-development-flag">}})
+To initialize Dapr in your local or remote **Kubernetes** cluster for development (including the Redis and Zipkin containers listed above), see [how to initialize Dapr for development on Kubernetes]({{<ref "kubernetes-deploy.md#install-dapr-from-the-official-dapr-helm-chart-with-development-flag" >}})
 {{% /alert %}}
 
 {{% alert title="Docker" color="primary" %}}
@@ -68,7 +69,13 @@ Install the latest Dapr runtime binaries:
 dapr init
 ```
 
-**If you are installing on Mac OS Silicon with Docker,** you may need to perform the following workaround to enable `dapr init` to talk to Docker without using Kubernetes.
+If you run your Docker cmds with sudo, you need to use:
+
+```bash
+sudo dapr init
+```
+
+If you are installing on **Mac OS Silicon** with Docker, you may need to perform the following workaround to enable `dapr init` to talk to Docker without using Kubernetes.
 1. Navigate to **Docker Desktop** > **Settings** > **Advanced**.
 1. Select the **Allow the default Docker socket to be used (requires password)** checkbox.
 
@@ -86,8 +93,30 @@ dapr init
 
 {{< /tabs >}}
 
+**Expected output:**
+
+```
+⌛  Making the jump to hyperspace...
+✅  Downloaded binaries and completed components set up.
+ℹ️  daprd binary has been installed to  $HOME/.dapr/bin.
+ℹ️  dapr_placement container is running.
+ℹ️  dapr_scheduler container is running.
+ℹ️  dapr_redis container is running.
+ℹ️  dapr_zipkin container is running.
+ℹ️  Use `docker ps` to check running containers.
+✅  Success! Dapr is up and running. To get started, go here: https://aka.ms/dapr-getting-started
+```
+
 [See the troubleshooting guide if you encounter any error messages regarding Docker not being installed or running.]({{< ref "common_issues.md#dapr-cant-connect-to-docker-when-installing-the-dapr-cli" >}})
 
+#### Slim init
+
+To install the CLI without any default configuration files or Docker containers, use the `--slim` flag. [Learn more about the `init` command and its flags.]({{< ref dapr-init.md >}})
+
+```bash
+dapr init --slim
+```
+
 ### Step 3: Verify Dapr version
 
 ```bash

daprdocs/content/en/operations/support/alpha-beta-apis.md

@@ -15,6 +15,7 @@ description: "List of current alpha and beta APIs"
 | Bulk Publish    | [Bulk publish proto](https://github.com/dapr/dapr/blob/5aba3c9aa4ea9b3f388df125f9c66495b43c5c9e/dapr/proto/runtime/v1/dapr.proto#L59)     | `v1.0-alpha1/publish/bulk` | The bulk publish API allows you to publish multiple messages to a topic in a single request. | [Bulk Publish and Subscribe API]({{< ref "pubsub-bulk.md" >}}) | v1.10 |
 | Bulk Subscribe   | [Bulk subscribe proto](https://github.com/dapr/dapr/blob/5aba3c9aa4ea9b3f388df125f9c66495b43c5c9e/dapr/proto/runtime/v1/appcallback.proto#L57)     | N/A | The bulk subscribe application callback receives multiple messages from a topic in a single call. | [Bulk Publish and Subscribe API]({{< ref "pubsub-bulk.md" >}}) | v1.10 |
 | Cryptography    |  [Crypto proto](https://github.com/dapr/dapr/blob/5aba3c9aa4ea9b3f388df125f9c66495b43c5c9e/dapr/proto/runtime/v1/dapr.proto#L118)    | `v1.0-alpha1/crypto` | The cryptography API enables you to perform **high level** cryptography operations for encrypting and decrypting messages. | [Cryptography API]({{< ref "cryptography-overview.md" >}}) | v1.11 |
+| Scheduler    |  [Scheduler proto](todo)    | `v1.0-alpha1/scheduler` | The scheduler API enables you to schedule and orchestrate jobs in your environment. | [Scheduler API]({{< ref "scheduler-overview.md" >}}) | v1.14 |
 
 ## Beta APIs
 

daprdocs/content/en/operations/support/support-preview-features.md

@@ -22,5 +22,6 @@ For CLI there is no explicit opt-in, just the version that this was first made a
 | **Service invocation for non-Dapr endpoints** | Allow the invocation of non-Dapr endpoints by Dapr using the [Service invocation API]({{< ref service_invocation_api.md >}}). Read ["How-To: Invoke Non-Dapr Endpoints using HTTP"]({{< ref howto-invoke-non-dapr-endpoints.md >}}) for more information. | N/A | [Service invocation API]({{< ref service_invocation_api.md >}}) | v1.11  |
 | **Actor State TTL** | Allow actors to save records to state stores with Time To Live (TTL) set to automatically clean up old data. In its current implementation, actor state with TTL may not be reflected correctly by clients, read [Actor State Transactions]({{< ref actors_api.md >}}) for more information. | `ActorStateTTL` | [Actor State Transactions]({{< ref actors_api.md >}}) | v1.11  |
 | **Transactional Outbox** | Allows state operations for inserts and updates to be published to a configured pub/sub topic using a single transaction across the state store and the pub/sub | N/A | [Transactional Outbox Feature]({{< ref howto-outbox.md >}}) | v1.12  |
-| **Component Hot Reloading** | Allows for Dapr-loaded components to be "hot reloaded". A component spec is reloaded either when it is created/updated/deleted in Kubernetes, or on file in self-hosted mode. Ignores changes to actor state stores and workflow backends. | `HotReload`| [Hot Reloading]({{< ref components-concept.md >}}) | v1.13  |
+| **Component Hot Reloading** | Allows for Dapr-loaded components to be "hot reloaded". A component spec is reloaded when it is created/updated/deleted in Kubernetes or on file when running in self-hosted mode. Ignores changes to actor state stores and workflow backends. | `HotReload`| [Hot Reloading]({{< ref components-concept.md >}}) | v1.13  |
 | **Subscription Hot Reloading** | Allows for declarative subscriptions to be "hot reloaded". A subscription is reloaded either when it is created/updated/deleted in Kubernetes, or on file in self-hosted mode. In-flight messages are unaffected when reloading. | `HotReload`| [Hot Reloading]({{< ref "subscription-methods.md#declarative-subscriptions" >}}) | v1.14  |
+| **Scheduler reminders** | While [Scheduler]({{< ref "concepts/dapr-services/scheduler.md" >}}) is deployed by default, scheduler reminders (used for scheduling actor reminders) are enabled through a preview feature and needs a feature flag. | `SchedulerReminders`| [Scheduler reminders]({{< ref "scheduler-overview.md#scheduler-reminders" >}}) | v1.14  |

daprdocs/content/en/reference/api/scheduler_api.md

@@ -0,0 +1,109 @@
+---
+type: docs
+title: "Scheduler API reference"
+linkTitle: "Scheduler API"
+description: "Detailed documentation on the scheduler API"
+weight: 1300
+---
+
+{{% alert title="Note" color="primary" %}}
+Scheduler is currently in alpha.
+{{% /alert %}}
+
+With the Scheduler API, you can orchestrate jobs and tasks in your environment.
+
+## Schedule a job
+
+Schedule a job with the given name.
+
+```
+POST http://localhost:3500/v1.0-alpha1/job/schedule/<name>
+```
+
+### URL parameters
+
+Parameter | Description
+--------- | -----------
+`name` | Job name
+
+### Request content
+
+Any request content will be passed to the scheduler as input. The Dapr API passes the content as-is without attempting to interpret it.
+
+### HTTP response codes
+
+Code | Description
+---- | -----------
+`202`  | Accepted
+`400`  | Request was malformed
+`500`  | Request formatted correctly, error in dapr code or Scheduler control plane service
+
+### Response content
+
+The API call will provide a response similar to this:
+
+```json
+```
+
+## Get job data
+
+Get a job's data with its given name.
+
+```
+GET http://localhost:3500/v1.0-alpha1/job/<name>
+```
+
+### URL parameters
+
+Parameter | Description
+--------- | -----------
+`name` | Job name
+
+### HTTP response codes
+
+Code | Description
+---- | -----------
+`202`  | Accepted
+`400`  | Request was malformed
+`500`  | Request formatted correctly, error in dapr code or underlying component
+
+### Response content
+
+The API call will provide a response similar to this:
+
+```json
+
+```
+## Delete a job
+
+Delete a job you've created and scheduled with its given name.
+
+```
+DELETE http://localhost:3500/v1.0-alpha1/job/<name>
+```
+
+### URL parameters
+
+Parameter | Description
+--------- | -----------
+`name` | Job name
+
+### HTTP response codes
+
+Code | Description
+---- | -----------
+`202`  | Accepted
+`400`  | Request was malformed
+`500`  | Request formatted correctly, error in dapr code or underlying component
+
+### Response content
+
+The API call will provide a response similar to this:
+
+```json
+
+```
+
+## Next steps
+
+[Scheduler API overview]({{< ref scheduler-overview.md >}})

daprdocs/content/en/reference/arguments-annotations-overview.md

@@ -36,7 +36,9 @@ This table is meant to help users understand the equivalent options for running
 | `--metrics-port` | `--metrics-port` | | `dapr.io/metrics-port` | Sets the port for the sidecar metrics server. Default is `9090` |
 | `--mode` | not supported | | not supported | Runtime hosting option mode for Dapr, either `"standalone"` or `"kubernetes"` (default `"standalone"`). [Learn more.]({{< ref hosting >}}) |
 | `--placement-host-address` | `--placement-host-address` | | `dapr.io/placement-host-address` | Comma separated list of addresses for Dapr Actor Placement servers. When no annotation is set, the default value is set by the Sidecar Injector. When the annotation is set and the value is empty, the sidecar does not connect to Placement server. This can be used when there are no actors running in the sidecar. When the annotation is set and the value is not empty, the sidecar connects to the configured address. For example: `127.0.0.1:50057,127.0.0.1:50058` |
+| `--scheduler-host-address` | `--scheduler-host-address` | | `dapr.io/scheduler-host-address` | Comma separated list of addresses for Dapr Scheduler servers. When no annotation is set, the default value is set by the Sidecar Injector. When the annotation is set and the value is empty, the sidecar does not connect to Scheduler server. When the annotation is set and the value is not empty, the sidecar connects to the configured address. For example: `127.0.0.1:50057,127.0.0.1:50058` |
 | `--actors-service` | not supported | | not supported | Configuration for the service that offers actor placement information. The format is `<name>:<address>`. For example, setting this value to `placement:127.0.0.1:50057,127.0.0.1:50058` is an alternative to using the `--placement-host-address` flag. |
+| `--schedule` |  | |  |  |
 | `--reminders-service` | not supported | | not supported | Configuration for the service that enables actor reminders. The format is `<name>[:<address>]`. Currently, the only supported value is `"default"` (which is also the default value), which uses the built-in reminders subsystem in the Dapr sidecar. |
 | `--profiling-port` | `--profiling-port` | | not supported | The port for the profile server (default `7777`) |
 | `--app-protocol` | `--app-protocol` | `-P` | `dapr.io/app-protocol` | Configures the protocol Dapr uses to communicate with your app. Valid options are `http`, `grpc`, `https` (HTTP with TLS), `grpcs` (gRPC with TLS), `h2c` (HTTP/2 Cleartext). Note that Dapr does not validate TLS certificates presented by the app. Default is `http` |