placement -> scheduler service docs - #5296
Open
cicoyle wants to merge 2 commits into
Open
Conversation
Signed-off-by: Cassandra Coyle <cassie@diagrid.io>
Contributor
There was a problem hiding this comment.
Pull request overview
Documents serving Dapr actor placement through the Scheduler instead of the standalone Placement service across deployment, operations, APIs, and actor concepts.
Changes:
- Adds Scheduler placement configuration and behavior documentation.
- Updates Kubernetes upgrade, HA, deployment, and mTLS guidance.
- Clarifies Placement API availability and timeout settings.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| daprdocs/content/en/reference/api/placement_api.md | Updated as part of this pull request. |
| daprdocs/content/en/operations/security/mtls.md | Updated as part of this pull request. |
| daprdocs/content/en/operations/hosting/kubernetes/kubernetes-upgrade.md | Updated as part of this pull request. |
| daprdocs/content/en/operations/hosting/kubernetes/kubernetes-production.md | Updated as part of this pull request. |
| daprdocs/content/en/operations/hosting/kubernetes/kubernetes-overview.md | Updated as part of this pull request. |
| daprdocs/content/en/operations/hosting/kubernetes/kubernetes-deploy.md | Updated as part of this pull request. |
| daprdocs/content/en/developing-applications/building-blocks/actors/actors-runtime-config.md | Updated as part of this pull request. |
| daprdocs/content/en/developing-applications/building-blocks/actors/actors-features-concepts.md | Updated as part of this pull request. |
| daprdocs/content/en/concepts/dapr-services/scheduler.md | Updated as part of this pull request. |
| daprdocs/content/en/concepts/dapr-services/placement.md | Updated as part of this pull request. |
Suppressed comments (8)
daprdocs/content/en/concepts/dapr-services/placement.md:43
- Because the Placement StatefulSet is removed before Scheduler placement is advertised, an old sidecar can leave the Scheduler withholding placement; the preceding sentence says those sidecars' Actor/Workflow APIs stall. There can therefore be a period with no serving placement, not “a single placement authority throughout the rollout.” Please describe this as avoiding split-brain while placement may be unavailable until all sidecars are upgraded.
Complete your Dapr version rollout before enabling this setting. Sidecars running an older Dapr version can only use the Placement service: with it undeployed, their Actor and Workflow APIs stall until the pod is upgraded to a version that supports scheduler placement. No actor state is lost. The Scheduler also withholds serving placement while any connected sidecar runs an older Dapr version, keeping a single placement authority throughout the rollout.
daprdocs/content/en/concepts/dapr-services/scheduler.md:220
- During a cutover, the old Placement service is stood down/removed before the Scheduler advertises, and the Scheduler can withhold advertisement while compatibility gates are open. In that window
whichever service ... advertisescan be neither, so “always has exactly one placement authority” overstates availability; scope this guarantee to steady state and mention the temporary no-placement window.
Sidecars take actor placement from whichever service the control plane advertises, so applications need no configuration of their own and the cluster always has exactly one placement authority. Toggling the setting in either direction requires no sidecar restarts. [Learn more about serving placement from the Scheduler service.]({{% ref "placement#serving-placement-from-the-scheduler-service" %}})
daprdocs/content/en/concepts/dapr-services/scheduler.md:13
- When Scheduler serves placement, the placement subsystem still elects a placement leader and only that leader accepts sidecar placement streams. The earlier blanket statement that there is no leader Scheduler instance is therefore misleading; scope it to job scheduling or mention this separate placement leadership here.
The Scheduler service can also serve actor placement in place of the standalone [Placement service]({{% ref placement %}}). See [Serving actor placement](#serving-actor-placement).
daprdocs/content/en/operations/hosting/kubernetes/kubernetes-deploy.md:251
- When this option is enabled, Scheduler is the placement authority, but the verification instructions above still ask for Placement and omit Scheduler from both the expected pod list and sample. This note only says that Placement is absent, so the critical replacement service remains unverified; include
dapr-schedulerin the verification instructions and make Placement conditional.
> **Note:** The `dapr-placement` pod is not present when actor placement is served by the Scheduler service (`global.scheduler.placement.enabled=true`).
daprdocs/content/en/operations/hosting/kubernetes/kubernetes-production.md:329
- This tells Kubernetes operators to tune Scheduler placement with these flags, but the chart currently renders only
--placement-enabledand exposes no Helm values or extra arguments for--placement-disseminate-timeoutor--placement-disseminate-coalesce-window. Please either add supported chart values/templates or document a supported way to configure these flags; otherwise this guidance cannot be applied through the deployment method described here.
When actor placement is served by the Scheduler service (`global.scheduler.placement.enabled=true`), the `dapr_placement.*` values above do not apply because the Placement service is not deployed. Scheduler-served placement is tuned with the Scheduler flags `--placement-disseminate-timeout` (the time a dissemination round waits for every sidecar to acknowledge before evicting the slow ones, default `8s`, a different knob than `dapr_placement.disseminateTimeout`) and `--placement-disseminate-coalesce-window` (the window in which membership changes are folded into a single dissemination round, default `0` for immediate dissemination). [Learn more about serving placement from the Scheduler service.]({{% ref "placement#serving-placement-from-the-scheduler-service" %}})
daprdocs/content/en/operations/hosting/kubernetes/kubernetes-upgrade.md:134
- Helm does not reset release values on every upgrade: when no new values are supplied, the previous release values are reused. The reset risk occurs when a later upgrade supplies
--setor--valueswithout--reuse-values; as written, this tells operators to repeat the flag on every upgrade and incorrectly predicts a hand-back on ordinary upgrades. Please qualify this guidance and mention--reuse-values.
Because `helm upgrade` resets values not passed on the command line, pass the setting on every subsequent upgrade (or keep it in your values file), otherwise the placement StatefulSet is redeployed and placement hands back to it.
daprdocs/content/en/operations/hosting/kubernetes/kubernetes-upgrade.md:129
- The Placement StatefulSet is undeployed while the Scheduler withholds advertisement when an old sidecar is connected, so there is a window with no available placement and the APIs stall—not a single serving authority “throughout the rollout.” Please call out the temporary unavailability and reserve the guarantee for avoiding split-brain.
Complete your Dapr version rollout before enabling this setting. Sidecars running an older Dapr version can only use the Placement service: with it undeployed, their Actor and Workflow APIs stall until the pod is upgraded to a version that supports scheduler placement. No actor state is lost. The Scheduler withholds serving placement while any connected sidecar runs an older Dapr version, so the cluster keeps a single placement authority throughout the rollout.
daprdocs/content/en/reference/api/placement_api.md:10
- This API page covers both hosting modes, but
global.scheduler.placement.enabledis the Kubernetes Helm setting; self-hosted users opt in withdapr init --scheduler-placement(and the Scheduler binary flag in slim mode). As written, the deprecation notice presents the Kubernetes flag as the universal opt-in and can mislead self-hosted users. Mention both mode-specific switches here.
The standalone Placement service is planned for deprecation in Dapr v1.21, when the [Scheduler service]({{% ref scheduler %}}) serves actor placement by default. Until then, scheduler placement is enabled by the opt-in flag `global.scheduler.placement.enabled=true` (`false` by default). This API is not served by the Scheduler.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
|
||
| In self-hosted mode, initialize Dapr with `dapr init --scheduler-placement` (requires Dapr 1.19 or later). The Placement container is not started, and the CLI starts the Scheduler container with `--placement-enabled=true` for you. No further configuration is needed. Only in [slim-init mode]({{% ref self-hosted-no-docker %}}), where you start the binaries yourself, the flag skips installing the Placement binary and you pass `--placement-enabled=true` when running the Scheduler binary. Applications and sidecars need no configuration of their own: each sidecar takes actor placement from whichever service the control plane advertises, so the cluster always has exactly one placement authority. Toggling the setting in either direction requires no sidecar restarts. | ||
|
|
||
| The two services place actors with different algorithms: the Placement service uses a consistent hash ring, while the Scheduler uses rendezvous hashing. Both give the same guarantees (every sidecar deterministically agrees on a single host for each actor ID, and ownership spreads across hosts), but the resulting actor-to-host assignments differ. Switching the placement authority in either direction therefore reassigns actors once: affected actors are deactivated and reactivate on their new hosts with their state intact, as in any actor rebalance. |
| 2. `dapr_placement.keepAliveTimeout` sets the timeout period for Dapr sidecars to respond to the Placement service's [keep alive](https://grpc.io/docs/guides/keepalive/) pings before the Placement service closes the connection. Lower values will lead to shorter actor rebalancing time in case of pod loss/restart, but higher network traffic during normal operation. Accepts values between `1s` and `10s`. Default is `3s`. | ||
| 3. `dapr_placement.disseminateTimeout` sets the timeout period for dissemination to be delayed after actor membership change (usually related to pod restarts) to avoid excessive dissemination during multiple pod restarts. Higher values will reduce the frequency of dissemination, but delay the table dissemination. Accepts values between `1s` and `3s`. Default is `2s`. | ||
|
|
||
| When actor placement is served by the Scheduler service (`global.scheduler.placement.enabled=true`), the `dapr_placement.*` values above do not apply because the Placement service is not deployed. Scheduler-served placement is tuned with the Scheduler flags `--placement-disseminate-timeout` (the time a dissemination round waits for every sidecar to acknowledge before evicting the slow ones, default `8s`, a different knob than `dapr_placement.disseminateTimeout`) and `--placement-disseminate-coalesce-window` (the window in which membership changes are folded into a single dissemination round, default `0` for immediate dissemination). [Learn more about serving placement from the Scheduler service.]({{% ref "placement#serving-placement-from-the-scheduler-service" %}}) |
| kubectl rollout restart statefulsets/dapr-placement-server -n <DAPR_NAMESPACE> | ||
| ``` | ||
|
|
||
| > **Note:** When actor placement is served by the Scheduler service (`global.scheduler.placement.enabled=true`), the `dapr-placement-server` StatefulSet is not deployed: skip its restart command above. |
| ```bash | ||
| kubectl rollout restart deploy/dapr-operator -n <DAPR_NAMESPACE> | ||
| kubectl rollout restart statefulsets/dapr-placement-server -n <DAPR_NAMESPACE> | ||
| kubectl rollout restart statefulsets/dapr-scheduler-server -n <DAPR_NAMESPACE> |
Signed-off-by: Cassandra Coyle <cassie@diagrid.io>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Moving placement into scheduler.
docs for these PRs:
dapr
cli