What content needs to be created or modified?
The docs describe dapr.io/block-shutdown-duration, dapr.io/graceful-shutdown-seconds, drainOngoingCallTimeout, and drainRebalancedActors individually, but nothing explains how they interact with Kubernetes pod termination for actor hosts.
Kubernetes sends SIGTERM to the application container and the daprd sidecar at the same time. An idle application typically exits in well under a second, while the sidecar is still in its shutdown sequence. The sidecar then fails every actor deactivation with connection refused (Failed to halt all actors...), OnDeactivateAsync never runs, and until the sidecar exits and placement is re-disseminated, other sidecars keep routing calls to actors placed on the dying pod — a multi-second window of failed actor invocations on every ordinary rolling restart. The drain settings are silently ineffective in this configuration because the application is already gone when draining happens.
We hit this in production and verified the behavior experimentally on dapr 1.18.4: with defaults, every rolling restart produces refused deactivations and a multi-second actor black-hole; with the sidecar-outlives-app configuration described below, deactivations complete against a live app and the failure window disappears.
Describe the solution you'd like
A production-guidelines section explaining the parallel-SIGTERM pitfall and the sidecar-outlives-app pattern: a preStop sleep on the application container, block-shutdown-duration, terminationGracePeriodSeconds, the drain settings, and the app health check (on an app-only endpoint) so the block ends early if the app genuinely dies — including how to size the durations relative to each other, a warning against probing the app through the sidecar (circular dependency), and a note that this guidance does not apply to native sidecars (where the app terminates first by design).
Where should the new material be placed?
operations/hosting/kubernetes/kubernetes-production.md — new section "Graceful shutdown for actor hosts" (main content)developing-applications/building-blocks/actors/actors-runtime-config.md — short note that the drain settings require the app to outlive the sidecar's shutdown, linking to the new sectionoperations/resiliency/health-checks/sidecar-health.md — one-line caveat under "Delay graceful shutdown" (the flag list there is also duplicated and can be fixed in passing)
The associated pull request from dapr/dapr, dapr/components-contrib, or other Dapr code repos
None — documentation of existing runtime behavior.
Additional context
Happy to submit the PR; the content is written and follows the docs contribution guide.
What content needs to be created or modified?
The docs describe
dapr.io/block-shutdown-duration,dapr.io/graceful-shutdown-seconds,drainOngoingCallTimeout, anddrainRebalancedActorsindividually, but nothing explains how they interact with Kubernetes pod termination for actor hosts.Kubernetes sends
SIGTERMto the application container and the daprd sidecar at the same time. An idle application typically exits in well under a second, while the sidecar is still in its shutdown sequence. The sidecar then fails every actor deactivation with connection refused (Failed to halt all actors...),OnDeactivateAsyncnever runs, and until the sidecar exits and placement is re-disseminated, other sidecars keep routing calls to actors placed on the dying pod — a multi-second window of failed actor invocations on every ordinary rolling restart. The drain settings are silently ineffective in this configuration because the application is already gone when draining happens.We hit this in production and verified the behavior experimentally on dapr 1.18.4: with defaults, every rolling restart produces refused deactivations and a multi-second actor black-hole; with the sidecar-outlives-app configuration described below, deactivations complete against a live app and the failure window disappears.
Describe the solution you'd like
A production-guidelines section explaining the parallel-SIGTERM pitfall and the sidecar-outlives-app pattern: a
preStopsleep on the application container,block-shutdown-duration,terminationGracePeriodSeconds, the drain settings, and the app health check (on an app-only endpoint) so the block ends early if the app genuinely dies — including how to size the durations relative to each other, a warning against probing the app through the sidecar (circular dependency), and a note that this guidance does not apply to native sidecars (where the app terminates first by design).Where should the new material be placed?
operations/hosting/kubernetes/kubernetes-production.md— new section "Graceful shutdown for actor hosts" (main content)developing-applications/building-blocks/actors/actors-runtime-config.md— short note that the drain settings require the app to outlive the sidecar's shutdown, linking to the new sectionoperations/resiliency/health-checks/sidecar-health.md— one-line caveat under "Delay graceful shutdown" (the flag list there is also duplicated and can be fixed in passing)The associated pull request from dapr/dapr, dapr/components-contrib, or other Dapr code repos
None — documentation of existing runtime behavior.
Additional context
Happy to submit the PR; the content is written and follows the docs contribution guide.