docs/release_notes/v1.17.0.md
We're excited to announce the release of Dapr 1.17! This release introduces workflow versioning, giving you the tools to safely evolve long-running workflow code without breaking in-flight instances. Combined with new state retention policies, up to 41% higher workflow throughput, and end-to-end tracing, Dapr Workflows are now ready for the most demanding production workloads. This release also stabilizes the Bulk PubSub API, improves Placement service resilience, and adds new CLI commands for managing Workflows and Scheduler.
Thanks to all the new and existing contributors who helped make this release happen.
If you're new to Dapr, visit the getting started page and familiarize yourself with Dapr.
The docs have been updated with all the new features and changes of this release. To get started with new capabilities introduced in this release, go to the Concepts and the Developing applications.
Go to the upgrading Dapr section for steps to upgrade to version 1.17.
Thanks to everyone who made this release possible!
@acroca, @adam6878, @AdarshRavichandran, @addjuarez, @aharonYK, @akotsarelation, @alekhrycaiko, @alicejgibbons, @ankurinfoblox, @antontroshin, @artur-ciocanu, @artursouza, @atrauzzi, @BlackRider97, @by-nelson, @CasperGN, @cicoyle, @citymaus, @ConstantinChirila, @cr3ativ3cod3r, @daanschutte, @DeepanshuA, @Eileen-Yu, @elena-kolevska, @famarting, @FarmerChillax, @filintod, @Flern, @fyzanshaik, @fyzanshaik-atlan, @halspang, @HusseinYasser, @imneov, @ItalyPaleAle, @javier-aliaga, @JeffreyJPZ, @jjcollinge, @jmfloreszazo, @johansja, @joshm998, @JoshVanL, @jslatten, @kapilthareja, @kaspernissen, @kayaj1009, @kgal-akl, @lijujoseph4, @lindner, @lony2003, @lrascao, @majiayu000, @marcduiker, @MasayaAoyama, @mcruzdev, @MichaelHindley, @middt, @mikeee, @mohitpalsingh, @msfussell, @MyMirelHub, @nelson-parente, @ngruson, @nikitasarawgi, @nmalocic, @oglok, @olitomlinson, @passuied, @paulorfjesus, @philliphoff, @pravinpushkar, @RaymundoZa, @robertojrojas, @RyanLettieri, @sadath-12, @salaboy, @seal90, @sicoyle, @siri-varma, @SpiffyEight77, @StarJourneyMingsing, @StoopidBoi-6128, @sunnynagavo, @TheForbiddenAi, @titanventura, @tmacam, @tomflenner, @WhitWaldo, @wlfgang, @yaron2, @ytimocin, @ZeBobo5, @ZeynelKoca, @zglp
These are the v1.17 release highlights:
Dapr v1.17 introduces workflow versioning, giving developers the tools to safely evolve workflow code while in-flight workflows continue to run correctly. This is critical because Dapr workflows are durable, may run for extended periods, and application upgrades can introduce changes that break deterministic replay of existing workflow instances. Workflow versioning in Dapr supports two complementary strategies:
ctx.IsPatched("patch_name"). New executions take the updated code path, while replaying instances follow the original path they were started on. This avoids duplicating entire workflow definitions for minor adjustments.SDK support is already available in Go, Python, .NET, and Java. Learn more in the workflow versioning documentation.
Dapr Workflows now supports a history retention policy to help control how much workflow state history is kept in your state store.
By default, workflow execution history is retained indefinitely, which is great for auditing and troubleshooting—but can also lead to significant growth in actor state storage for high-volume workloads or workflows that emit lots of state changes.
With v1.17 you can configure how long to retain workflow history after a workflow reaches a terminal state (Completed, Failed, or Terminated). You can set:
a default retention duration for any terminal state, and
per-terminal-state overrides (for example, keep Failed longer than Completed).
Retention durations use Go duration strings (for example 72h, 30m).
Example configuration:
kind: Configuration
metadata:
name: appconfig
spec:
workflow:
stateRetentionPolicy:
anyTerminal: "360h"
completed: "1m"
failed: "720h"
terminated: "360h"
Operational tip: a common pattern is to keep Completed workflows for a shorter period, while retaining Failed and Terminated workflows longer to support investigation.
In v1.17, the Placement service is more robust during deployments, scaling events, and sidecar churn, helping Actors and Workflows converge faster and avoid inconsistent routing decisions.
The Dapr CLI in v1.17 adds smoother operational workflows for Workflows and Scheduler, plus better defaults for local development.
DAPR_HOST_IP=127.0.0.1 when it isn’t already set, improving “works out of the box” behavior in self-hosted mode on MacOS.list, history, suspend/resume, terminate, rerun, raise-event, purge).$ dapr workflow <..>
$ dapr scheduler <..>
In Dapr v1.17 made greater use of the performance test suite and added visualizations so you can inspect and compare performance results yourself.
Added a performance charts directory under tests/perf/report/charts. It contains chart outputs (ex: duration breakdown, throughput, tail latency, resource usage, etc) generated from our performance runs, organized by API and Dapr version. From there, you can open the API and Dapr version that matches your usage and compare runs or versions relevant to your APIs and workloads. Each API folder for the v1.17 folder contains a highlights section where common scenario performance results are highlighted at the top of each README.
The performance suite runs in CI regularly. Visual charts are created from code, based on runs in Azure. This helps visually highlight regressions or improvements and provides a single place to see current and historical performance.
Keep in mind that numbers can vary slightly between runs and environments. The figures below are from a comparison of two individual performance runs (one v1.16, one v1.17) - not averaged across multiple runs, so they may not be representative of every environment. Below are highlights from our generated v1.16 and v1.17 runs:
| API | v1.16 | v1.17 | % Improvement |
|---|---|---|---|
| Actor (activation avg latency) | 2.70 ms | 2.35 ms | 13% |
| Actor (timer with state avg latency) | 8.20 ms | 6.84 ms | 17% |
| Workflows (throughput: iterations/sec) | 19.80 | 28.01 | 41.5% |
| Workflows (req duration avg in ms) | 1467 | 1042 | 29% |
| Workflows (req duration p90 in ms) | 1642 | 1166 | 29% |
Test references for the numbers above:
TestActorActivateTestWorkflowWithConstantVUs with the same scenario (30 VUs, 300s)Actors show lower latency for activation and timer with state. Because workflows use actors under the hood, you see higher workflow throughput and lower request latency (both average and p90) for the constant VU scenario.
Links:
After several releases of availability via the Alpha APIs, first introduced in Dapr v1.10.0, Bulk Publish and Bulk Subscribe are now stable in Dapr v1.17.
The stabilization brings production-ready, consistent APIs for Bulk PubSub, allowing you to publish and receive multiple messages in a single operation via the stable APIs:
/v1.0/publish/bulk/<pubsub-name>/<topic> was promoted from /v1.0-alpha1/publish/bulk/<pubsub-name>/<topic>. For gRPC, BulkPublishEvent was promoted from BulkPublishEventAlpha1.OnBulkTopicEvent was promoted from OnBulkTopicEventAlpha1.Application code should be updated to implement the stable endpoints/callbacks when using Bulk PubSub. All SDKs are updated accordingly to support and use the stable APIs on both Publish and Subscribe sides. Please check SDK release notes and examples for details.
Backwards compatibility: If your application still implements the previous OnBulkTopicEventAlpha1 callback, Dapr logs a deprecation warning and automatically falls back to the Alpha APIs (for now), giving you time to migrate to using the stable API. Alpha paths remain functional, but are deprecated in favor of the stable APIs.
This stabilization follows the Dapr API Lifecycle expectations, backed by extensive testing ensuring production readiness.
Links:
This release improves end-to-end tracing for Dapr Workflows by ensuring that incoming trace context is preserved when scheduling and executing workflows.
Previously, traces could become disconnected when workflows were scheduled or orchestrations executed, making distributed traces harder to follow. Now workflow spans are correctly linked to the caller’s trace.
The Conversation API received several enhancements in this release to improve reliability, flexibility, and observability.
Various component improvements were included in this release, focused on enhanced authentication, resiliency, and feature completeness:
FailurePolicy on Actor Reminders to allow for controlling the retry behaviour of failed Actor Reminder invocations.The v1.17 release of the Dapr .NET SDK features a complete overhaul of the Dapr.Workflow package removing all dependencies on DurableTask and updating to support all Dapr runtime functionality: task execution identifiers, multi-app workflows (workflows & activities), and both patch- and name-based workflow versioning.
This release includes official support for .NET 10 in addition to the already supported .NET 8 and 9.
The Conversation API has been updated to reflect the latest runtime capabilities for detailing token usage and specifying both response schema structure and prompt cache durations.
The PubSub API has been updated to reflect the graduation of the bulk PubSub runtime support to stable.
Finally, this release ships Testcontainers support via the Dapr.Testcontainers package facilitating integration tests across the SDK and better enabling developers to improve their own testing infrastructure with Dapr.
The v1.17 release of the Dapr Python SDK introduces two new AI agent framework extensions: dapr-ext-langgraph and dapr-ext-strands, enabling durable and observable AI agent workflows backed by Dapr's building blocks.
Workflow versioning is now supported with both patch-based and name-based versioning, allowing safe evolution of long-running workflow definitions without breaking in-flight instances.
@sicoyle is now a maintainer and @CasperGN an approver of the python SDK.
Workflow versioning is now supported with both patch-based and name-based versioning, allowing safe evolution of long-running workflow definitions without breaking in-flight instances.
Spring Boot 4 support has been introduced, as Spring Boot 3 reaches end of support on June 30, 2026.
The Conversation API has been updated to reflect the latest runtime capabilities for detailing token usage and specifying both response schema structure and prompt cache durations.
PubSub API has been updated to reflect the graduation of the bulk PubSub runtime support to stable.
Actor Reminders API has been updated to support failure policies
ListInstanceIDs & GetInstanceHistory 9170dapr.proto into multiple files 9200dapr scheduler command 1559kid header to kafka JWT auth 4099Dapr.Workflow.Versioning package 1709A big thank you to the following .NET SDK contributors that made this release possible: @whitwaldo, @zglp, @sunnynagavo, @atrauzzi, @marcduiker, @daanschutte, @ali-Hamza817, @ZeBobo5
To upgrade to this release of Dapr, follow the steps below to ensure a smooth upgrade.
Uninstall Dapr using the CLI you currently have installed. Note that this will remove the default $HOME/.dapr directory, binaries and all containers dapr_redis, dapr_placement and dapr_zipkin. Linux users need to run sudo if docker command needs sudo:
dapr uninstall --all
Download the latest release from here and put the dapr binary in your PATH.
Once you have installed the CLI, run:
dapr init --runtime-version=1.17
Wait for the update to finish, ensure you are using the latest version of Dapr(1.17) with:
$ dapr --version
CLI version: 1.17
Runtime version: 1.17
You can perform zero-downtime upgrades using both Helm 3 and the Dapr CLI.
Download the latest release from here and put the dapr binary in your PATH.
To upgrade Dapr, run:
dapr upgrade --runtime-version 1.17 -k
To upgrade with high availability mode:
dapr upgrade --runtime-version 1.17 --enable-ha=true -k
Wait until the operation is finished and check your status with dapr status -k.
All done!
Note: Make sure your deployments are restarted to pick the latest version of the Dapr sidecar
To upgrade Dapr using Helm, run:
helm repo add dapr https://dapr.github.io/helm-charts/
helm repo update
helm upgrade dapr dapr/dapr --version 1.17 --namespace=dapr-system --wait
Wait until the operation is finished and check your status with dapr status -k.
All done!
Note: Make sure your deployments are restarted to pick the latest version of the Dapr sidecar
Please see how to deploy Dapr on a Kubernetes cluster for a complete guide to installing Dapr on Kubernetes
You can use Helm 3 to install Dapr:
helm repo add dapr https://dapr.github.io/helm-charts/
helm repo update
kubectl create namespace dapr-system
helm install dapr dapr/dapr --version 1.17 --namespace dapr-system --wait
Alternatively, you can use the latest version of CLI:
dapr init --runtime-version=1.17 -k
Verify the control plane pods are running and are healthy:
$ dapr status -k
NAME NAMESPACE HEALTHY STATUS REPLICAS VERSION AGE CREATED
dapr-sidecar-injector dapr-system True Running 1 1.17 15s 2026-02-12 13:07.39
dapr-sentry dapr-system True Running 1 1.17 15s 2026-02-12 13:07.39
dapr-operator dapr-system True Running 1 1.17 15s 2026-02-12 13:07.39
dapr-placement dapr-system True Running 1 1.17 15s 2026-02-12 13:07.39
After Dapr 1.17 has been installed, perform a rolling restart for your deployments to pick up the new version of the sidecar. This can be done with:
kubectl rollout restart deploy/<deployment-name>
None.
Alpha Bulk PubSub APIs are being deprecated in favor of the stable Bulk PubSub APIs. The alpha Bulk Publish and Bulk Subscribe APIs (/v1.0-alpha1/publish/bulk/<pubsub-name>/<topic> and BulkPublishEventAlpha1) are now deprecated. The app callback OnBulkTopicEventAlpha1 is also now deprecated.
The alpha APIs remain functional in Dapr v1.17 - Dapr will log a deprecation warning and automatically fallback to them if your application still uses them. This gives users time to migrate to the stable APIs (/v1.0/publish/bulk/<pubsub-name>/<topic> and BulkPublishEvent) and OnBulkTopicEvent for the app callback.
See the section above titled Bulk PubSub API is now Stable for full details on the promoted APIs, migration steps, backwards compatibility behavior, and documentation links.