Dapr Docs

Authenticating to AWS

Mon, 01 Jan 0001 00:00:00 +0000

Dapr components leveraging AWS services (for example, DynamoDB, SQS, S3) utilize standardized configuration attributes via the AWS SDK. Learn more about how the AWS SDK handles credentials.

You can configure authentication using the AWS SDK’s default provider chain or one of the predefined AWS authentication profiles outlined below. Verify your component configuration by testing and inspecting Dapr runtime logs to confirm proper initialization.

Terminology

ARN (Amazon Resource Name): A unique identifier used to specify AWS resources. Format: arn:partition:service:region:account-id:resource. Example: arn:aws:iam::123456789012:role/example-role.
IAM (Identity and Access Management): AWS’s service for managing access to AWS resources securely.

Authentication Profiles

Access Key ID and Secret Access Key

Use static Access Key and Secret Key credentials, either through component metadata fields or via default AWS configuration.

Conceptual article template

Mon, 01 Jan 0001 00:00:00 +0000

Contributing a new conceptual or overview article

Conceptual (or overview) articles answer the questions:

Why should you care about this feature?
What problems does it help you solve?

While a component, API, or SDK spec may help readers understand how to use or work with these features, a conceptual article provides more depth and context. Link off to the spec article, but try not to simply repeat the spec.

When naming your conceptual article, make sure it is consistent with the spec in terms of names, parameters, and terminology. Make sure you update both as needed.

Contributors guide

Mon, 01 Jan 0001 00:00:00 +0000

In this guide, you’ll learn how to contribute to the Dapr docs repository. Since Dapr docs are published to docs.dapr.io, you must make sure your contributions compile and publish correctly.

Prerequisites

Before contributing to the Dapr docs:

Review the guidance around general Dapr project contributions.
Install and set up your local environment with Hugo with the Docsy theme. Follow the instructions in the repository README.md.
Fork and clone the docs repository.

Branch guidance

The Dapr docs handles branching differently than most code repositories. Instead of a main branch, every branch is labeled to match the major and minor version of a runtime release. For the full list visit the Docs repo

Install the Dapr CLI

Mon, 01 Jan 0001 00:00:00 +0000

You’ll use the Dapr CLI as the main tool for various Dapr-related tasks. You can use it to:

Run an application with a Dapr sidecar.
Review sidecar logs.
List running services.
Run the Dapr dashboard.

The Dapr CLI works with both self-hosted and Kubernetes environments.

Before you begin

In Docker Desktop’s advanced options, verify you’ve allowed the default Docker socket to be used. This option is not available if you are using WSL integration on Windows.

Step 1: Install the Dapr CLI

Install from Terminal

Install the latest Linux Dapr CLI to /usr/local/bin:

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

Dapr Agents v1.0 — Generally Available

Dapr Agents v1.0 is production ready with stable APIs and enterprise-grade support for agentic workloads.

Dapr Agents is a developer framework for building durable and resilient AI agent systems powered by Large Language Models (LLMs). Built on the battle-tested Dapr project, it enables developers to create autonomous systems that have identity, reason through problems, make dynamic decisions, and collaborate seamlessly. It includes built-in observability and stateful workflow execution to ensure agentic workflows complete successfully, regardless of complexity. Whether you’re developing single-agent applications or complex multi-agent workflows, Dapr Agents provides the infrastructure for intelligent, adaptive systems that scale across environments.

Contribution overview

Mon, 01 Jan 0001 00:00:00 +0000

Thank you for your interest in Dapr! This document provides the guidelines for how to contribute to the Dapr project through issues and pull requests. Contributions can also come in additional ways such as engaging with the community in community calls, commenting on issues or pull requests, and more.

See the Dapr community repository for more information on community engagement and community membership.

Dapr Repository Index

Below is a list of repositories under the Dapr organization where you can contribute:

Actors overview

Mon, 01 Jan 0001 00:00:00 +0000

The actor pattern describes actors as the lowest-level “unit of computation”. In other words, you write your code in a self-contained unit (called an actor) that receives messages and processes them one at a time, without any kind of concurrency or threading.

While your code processes a message, it can send one or more messages to other actors, or create new actors. An underlying runtime manages how, when and where each actor runs, and also routes messages between actors.

Service invocation overview

Mon, 01 Jan 0001 00:00:00 +0000

Using service invocation, your application can reliably and securely communicate with other applications using the standard gRPC or HTTP protocols.

In many microservice-based applications, multiple services need the ability to communicate with one another. This inter-service communication requires that application developers handle problems like:

Service discovery. How do I discover my different services?
Standardizing API calls between services. How do I invoke methods between services?
Secure inter-service communication. How do I call other services securely with encryption and apply access control on the methods?
Mitigating request timeouts or failures. How do I handle retries and transient errors?
Implementing observability and tracing. How do I use tracing to see a call graph with metrics to diagnose issues in production?

Service invocation API

Dapr addresses these challenges by providing a service invocation API that acts similar to a reverse proxy with built-in service discovery, while leveraging built-in distributed tracing, metrics, error handling, encryption and more.

Errors overview

Mon, 01 Jan 0001 00:00:00 +0000

An error code is a numeric or alphanumeric code that indicates the nature of an error and, when possible, why it occured.

Dapr error codes are standardized strings for over 80+ common errors across HTTP and gRPC requests when using the Dapr APIs. These codes are both:

Returned in the JSON response body of the request.
When enabled, logged in debug-level logs in the runtime.
- If you’re running in Kubernetes, error codes are logged in the sidecar.
- If you’re running in self-hosted, you can enable and run debug logs.

Error format

Dapr error codes consist of a prefix, a category, and shorthand of the error itself. For example:

Distributed tracing overview

Mon, 01 Jan 0001 00:00:00 +0000

Dapr uses the Open Telemetry (OTEL) and Zipkin protocols for distributed traces. OTEL is the industry standard and is the recommended trace protocol to use.

Most observability tools support OTEL, including:

The following diagram demonstrates how Dapr (using OTEL and Zipkin protocols) integrates with multiple observability tools.

Scenarios

Tracing is used with service invocaton and pub/sub APIs. You can flow trace context between services that uses these APIs. There are two scenarios for how tracing is used:

Retry resiliency policies

Mon, 01 Jan 0001 00:00:00 +0000

Requests can fail due to transient errors, like encountering network congestion, reroutes to overloaded instances, and more. Sometimes, requests can fail due to other resiliency policies set in place, like triggering a defined timeout or circuit breaker policy.

In these cases, configuring retries can either:

Send the same request to a different instance, or
Retry sending the request after the condition has cleared.

Retries and timeouts work together, with timeouts ensuring your system fails fast when needed, and retries recovering from temporary glitches.

Dapr command line interface (CLI) reference

Mon, 01 Jan 0001 00:00:00 +0000

The Dapr CLI allows you to setup Dapr on your local dev machine or on a Kubernetes cluster, provides debugging support, and launches and manages Dapr instances.


 __
 ____/ /___ _____ _____
 / __ / __ '/ __ \/ ___/
 / /_/ / /_/ / /_/ / /
 \__,_/\__,_/ .___/_/
 /_/

===============================
Distributed Application Runtime

Usage:
 dapr [command]

Available Commands:
 annotate Add dapr annotations to a Kubernetes configuration. Supported platforms: Kubernetes
 build-info Print build info of Dapr CLI and runtime
 completion Generates shell completion scripts
 components List all Dapr components. Supported platforms: Kubernetes
 configurations List all Dapr configurations. Supported platforms: Kubernetes
 dashboard Start Dapr dashboard. Supported platforms: Kubernetes and self-hosted
 help Help about any command
 init Install Dapr on supported hosting platforms. Supported platforms: Kubernetes and self-hosted
 invoke Invoke a method on a given Dapr application. Supported platforms: Self-hosted
 list List all Dapr instances. Supported platforms: Kubernetes and self-hosted
 logs Get Dapr sidecar logs for an application. Supported platforms: Kubernetes
 mtls Check if mTLS is enabled. Supported platforms: Kubernetes
 publish Publish a pub-sub event. Supported platforms: Self-hosted
 run Run Dapr and (optionally) your application side by side. Supported platforms: Self-hosted
 status Show the health status of Dapr services. Supported platforms: Kubernetes
 stop Stop Dapr instances and their associated apps. Supported platforms: Self-hosted
 uninstall Uninstall Dapr runtime. Supported platforms: Kubernetes and self-hosted
 upgrade Upgrades a Dapr control plane installation in a cluster. Supported platforms: Kubernetes
 version Print the Dapr runtime and CLI version

Flags:
 -h, --help help for dapr
 --log-as-json Log output in JSON format
 -v, --version version for dapr

Use "dapr [command] --help" for more information about a command.

Command Reference

You can learn more about each Dapr command from the links below.

Timeout resiliency policies

Mon, 01 Jan 0001 00:00:00 +0000

Network calls can fail for many reasons, causing your application to wait indefinitely for responses. By setting a timeout duration, you can cut off those unresponsive services, freeing up resources to handle new requests.

Timeouts are optional policies that can be used to early-terminate long-running operations. Set a realistic timeout duration that reflects actual response times in production. If you’ve exceeded a timeout duration:

The operation in progress is terminated (if possible).
An error is returned.

Timeout policy format

spec:
 policies:
 # Timeouts are simple named durations.
 timeouts:
 timeoutName: timeout1
 general: 5s
 important: 60s
 largeResponse: 10s

Spec metadata

Agent Sessions

Mon, 01 Jan 0001 00:00:00 +0000

Overview

By using Dapr to manage the state and session data for OpenAI agents, users can store agent state in all databases supported by Dapr, including key/value stores, caches and SQL databases. Developers also get built-in tracing, metrics and resiliency policies that make agent session data operate reliably in production.

Getting Started

Initialize Dapr locally to set up a self-hosted environment for development. This process fetches and installs the Dapr sidecar binaries, runs essential services as Docker containers, and prepares a default components folder for your application. For detailed steps, see the official guide on initializing Dapr locally.

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Dapr Agents Concepts

If you are looking for an introductory overview of Dapr Agents and want to learn more about basic Dapr Agents terminology, we recommend starting with the introduction and concepts sections.

Install Dapr CLI

While simple examples in Dapr Agents can be used without the sidecar, the recommended mode is with the Dapr sidecar. To benefit from the full power of Dapr Agents, install the Dapr CLI for running Dapr locally or on Kubernetes for development purposes. For a complete step-by-step guide, follow the Dapr CLI installation page.

Authenticating an MCP server

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The MCP specification does not mandate any form of authentication between an MCP client and server. The security model is left to the user to plan and implement. This creates a maintenance burden on developers and opens up MCP servers to various attack surfaces.

While MCP servers lack identity, OAuth2 is a well established standard that can be used to properly authenticate MCP clients to MCP servers.

OAuth2 becomes essential when MCP servers are:

How-To: Invoke services using HTTP

Mon, 01 Jan 0001 00:00:00 +0000

This article demonstrates how to deploy services each with an unique application ID for other services to discover and call endpoints on them using service invocation over HTTP.

Note

If you haven’t already, try out the service invocation quickstart for a quick walk-through on how to use the service invocation API.

Choose an ID for your service

Dapr allows you to assign a global, unique ID for your app. This ID encapsulates the state for your application, regardless of the number of instances it may have.

Initialize Dapr in your local environment

Mon, 01 Jan 0001 00:00:00 +0000

Now that you’ve installed the Dapr CLI, use the CLI to initialize Dapr on your local machine.

Dapr runs as a sidecar alongside your application. In self-hosted mode, this means it is a process on your local machine. By initializing Dapr, you:

Fetch and install the Dapr sidecar binaries locally.
Create a development environment that streamlines application development with Dapr.

Dapr initialization includes:

Running a Redis container instance to be used as a local state store and message broker.
Running a Zipkin container instance for observability.
Creating a default components folder with component definitions for the above.
Running a Dapr placement service container instance for local actor support.
Running a Dapr scheduler service container instance for job scheduling.

Kubernetes Development Environment

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

Docker

The recommended development environment requires Docker. While you can initialize Dapr without a dependency on Docker, the next steps in this guide assume the recommended Docker development environment.

Maintainer guide

Mon, 01 Jan 0001 00:00:00 +0000

In this guide, you’ll learn how to perform routine Dapr docs maintainer and approver responsibilities. In order to successfully accomplish these tasks, you need either approver or maintainer status in the dapr/docs repo.

To learn how to contribute to Dapr docs, review the Contributor guide.

Branch guidance

The Dapr docs handles branching differently than most code repositories. Instead of a main branch, every branch is labeled to match the major and minor version of a runtime release.

Override default retry resiliency policies

Mon, 01 Jan 0001 00:00:00 +0000

Dapr provides default retries for any unsuccessful request, such as failures and transient errors. Within a resiliency spec, you have the option to override Dapr’s default retry logic by defining policies with reserved, named keywords. For example, defining a policy with the name DaprBuiltInServiceRetries, overrides the default retries for failures between sidecars via service-to-service requests. Policy overrides are not applied to specific targets.

Note: Although you can override default values with more robust retries, you cannot override with lesser values than the provided default value, or completely remove default retries. This prevents unexpected downtime.

Giving a presentation on Dapr

Mon, 01 Jan 0001 00:00:00 +0000

We encourage community members to give presentations on Dapr. To get you started quickly, we offer three PowerPoint files:

dapr-slidedeck.pptx, this is a 150+ page slide deck and contains: an overview of Dapr, all of its building block APIs, cross-cutting concerns, hosting options, and assets to create your own architecture diagrams.
dapr-workflow-slidedeck.pptx, this is a dedicated slide deck about Dapr Workflow and contains: durable execution concept, workflow authoring, workflow patterns, workflow management, and challenges & tips.
dapr-agents-slidedeck.pptx, this is a dedicated slide deck about Dapr Agents and contains: AI agents explanation, Dapr Agent types, multi-agent systems, and agentic patterns.

There is a downloadable zip file that contains all slide decks.

Quickstart guide template

Mon, 01 Jan 0001 00:00:00 +0000

Contributing a new quickstart guide

Dapr quickstart guides consist of quick instructions that walk readers through a prepared quickstart, saved to the dapr/quickstarts repo. These quickstarts package an entire feature or building block in one place, making it easy for the reader to experience how it works without compromising their own project.

The quickstart instructions should be succinct, direct, and clear. The sole purpose of a quickstart guide is to simply instruct a reader through the prepared quickstart. If you’d like to explain the concepts behind the quickstart, direct the reader to a concept article for more context.

Error codes reference guide

Mon, 01 Jan 0001 00:00:00 +0000

The following tables list the error codes returned by Dapr runtime. The error codes are returned in the response body of an HTTP request or in the ErrorInfo section of a gRPC status response, if one is present. An effort is underway to enrich all gRPC error responses according to the Richer Error Model. Error codes without a corresponding gRPC code indicate those errors have not yet been updated to this model.

Actor runtime features

Mon, 01 Jan 0001 00:00:00 +0000

Now that you’ve learned about the actor building block at a high level, let’s deep dive into the features and concepts included with actors in Dapr.

Actor lifetime

Dapr actors are virtual, meaning that their lifetime is not tied to their in-memory representation. As a result, they do not need to be explicitly created or destroyed. The Dapr actor runtime automatically activates an actor the first time it receives a request for that actor ID. If an actor is not used for a period of time, the Dapr actor runtime garbage-collects the in-memory object. It will also maintain knowledge of the actor’s existence should it need to be reactivated later.

W3C trace context overview

Mon, 01 Jan 0001 00:00:00 +0000

Dapr uses the Open Telemetry protocol, which in turn uses the W3C trace context for distributed tracing for both service invocation and pub/sub messaging. Dapr generates and propagates the trace context information, which can be sent to observability tools for visualization and querying.

Background

Distributed tracing is a methodology implemented by tracing tools to follow, analyze, and debug a transaction across multiple software components.

Typically, a distributed trace traverses more than one service, which requires it to be uniquely identifiable. Trace context propagation passes along this unique identification.

CrewAI Workflows

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Dapr Workflows make it possible to run CrewAI agents reliably, durably, and with built-in resiliency.
By orchestrating CrewAI tasks with the Dapr Workflow engine, developers can:

Ensure long-running CrewAI work survives crashes and restarts.
Get automatic checkpoints, retries, and state recovery.
Run each CrewAI task as a durable activity.
Observe execution through tracing, metrics, and structured logs.

This guide walks through orchestrating multiple CrewAI tasks using Dapr Workflows, ensuring each step is run exactly once even if the process restarts.

Agent Sessions

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Dapr Python SDK provides integration with LangGraph Checkpointer using the dapr-ext-langgraph extension.

Getting Started

To initialize the Dapr control plane containers and create a default configuration file, run:

Circuit breaker resiliency policies

Mon, 01 Jan 0001 00:00:00 +0000

Circuit breaker policies are used when other applications/services/components are experiencing elevated failure rates. Circuit breakers reduce load by monitoring the requests and shutting off all traffic to the impacted service when a certain criteria is met.

After a certain number of requests fail, circuit breakers “trip” or open to prevent cascading failures. By doing this, circuit breakers give the service time to recover from their outage instead of flooding it with events.

Configure Dapr to send distributed tracing data

Mon, 01 Jan 0001 00:00:00 +0000

Note

It is recommended to run Dapr with tracing enabled for any production scenario. You can configure Dapr to send tracing and telemetry data to many observability tools based on your environment, whether it is running in the cloud or on-premises.

Configuration

The tracing section under the Configuration spec contains the following properties:

spec:
 tracing:
 samplingRate: "1"
 otel: 
 endpointAddress: "myendpoint.cluster.local:4317"
 headers:
 - name: "x-api-key"
 secretKeyRef:
 name: "my-secret-store"
 key: "otel-api-key"
 timeout: "30s"
 zipkin:
 endpointAddress: "https://..."

The following table lists the properties for tracing:

How-to guide template

Mon, 01 Jan 0001 00:00:00 +0000

Contributing a new how-to guide

How-to guides provide step-by-step practical guidance to readers who wish to:

Enable a feature
Integrate a technology
Use Dapr in a specific scenario

How-to guides can be considered “next-level”, self-guided docs compared to quickstarts. How-to scenarios will take longer and can be more easily applied to the reader’s individual project or environment.

When naming your how-to document, include the sub-directory name in the file name. If you need to create a new sub-directory, make sure it’s descriptive and includes the relevant component or concept name. For example, pubsub-namespaces.

How-To: Invoke services using gRPC

Mon, 01 Jan 0001 00:00:00 +0000

This article describe how to use Dapr to connect services using gRPC.

By using Dapr’s gRPC proxying capability, you can use your existing proto-based gRPC services and have the traffic go through the Dapr sidecar. Doing so yields the following Dapr service invocation benefits to developers:

Mutual authentication
Tracing
Metrics
Access lists
Network level resiliency
API token based authentication

Dapr allows proxying all kinds of gRPC invocations, including unary and stream-based ones.

Handling HTTP error codes

Mon, 01 Jan 0001 00:00:00 +0000

For HTTP calls made to Dapr runtime, when an error is encountered, an error JSON is returned in response body. The JSON contains an error code and an descriptive error message.

{
 "errorCode": "ERR_STATE_GET",
 "message": "Requested state key does not exist in state store."
}

Dapr Roadmap

Mon, 01 Jan 0001 00:00:00 +0000

See this document to view the Dapr project’s roadmap.

Actor runtime configuration parameters

Mon, 01 Jan 0001 00:00:00 +0000

You can modify the default Dapr actor runtime behavior using the following configuration parameters.

Parameter	Description	Default
`entities`	The actor types supported by this host.	N/A
`actorIdleTimeout`	The timeout before deactivating an idle actor. Checks for timeouts occur every `actorScanInterval` interval.	60 minutes
`actorScanInterval`	The duration which specifies how often to scan for actors to deactivate idle actors. Actors that have been idle longer than actor_idle_timeout will be deactivated.	30 seconds
`drainOngoingCallTimeout`	The duration when in the process of draining rebalanced actors. This specifies the timeout for the current active actor method to finish. If there is no current actor method call, this is ignored. The effective value is clamped against the placement dissemination budget (see Drain timeout clamping).	60 seconds
`drainRebalancedActors`	If true, Dapr will wait for `drainOngoingCallTimeout` duration to allow a current actor call to complete before trying to deactivate an actor.	true
`reentrancy` (`ActorReentrancyConfig`)	Configure the reentrancy behavior for an actor. If not provided, reentrancy is disabled.	disabled, false
`entitiesConfig`	Configure each actor type individually with an array of configurations. Any entity specified in the individual entity configurations must also be specified in the top level `entities` field. Per-entity `drainOngoingCallTimeout` values are honored and subject to the same clamping rule as the top-level value.	N/A

Drain timeout clamping

When a daprd host is being drained (for example during a rolling upgrade), the LOCK -> UPDATE -> UNLOCK round on placement holds the host out of the dissemination loop for the configured drainOngoingCallTimeout. If that timeout meets or exceeds the daprd-side placement dissemination timeout (default 30 seconds), placement gives up on the host and resets the stream, which produces noisy reconnects and reschedules. A common case is an SDK that hard-codes a 60-second drain default against the 30-second dissemination default.

Use the Dapr API

Mon, 01 Jan 0001 00:00:00 +0000

In this guide, you’ll simulate an application by running the sidecar and calling the state management API directly. After running Dapr using the Dapr CLI, you’ll:

Save a state object.
Read/get the state object.
Delete the state object.

Learn more about the state building block and how it works in our concept docs.

Pre-requisites

Step 1: Run the Dapr sidecar

The dapr run command normally runs your application and a Dapr sidecar. In this case, it only runs the sidecar since you are interacting with the state management API directly.

Why Dapr Agents

Mon, 01 Jan 0001 00:00:00 +0000

Dapr Agents is a production-ready, open-source framework (v1.0) for building and orchestrating LLM-based autonomous agents that leverages Dapr’s proven distributed systems foundation. Unlike other agentic frameworks that require developers to build infrastructure from scratch, Dapr Agents enables teams to focus on agent intelligence by providing enterprise-grade scalability, state management, and messaging capabilities out of the box. This approach eliminates the complexity of recreating distributed system fundamentals while delivering agentic workflows powered by Dapr.

Core Concepts

Mon, 01 Jan 0001 00:00:00 +0000

Dapr Agents provides a structured way to build and orchestrate applications that use LLMs without getting bogged down in infrastructure details. The primary goal is to enable AI development by abstracting away the complexities of working with LLMs, tools, memory management, and distributed systems, allowing developers to focus on the business logic of their AI applications. Agents in this framework are the fundamental building blocks.

Agents

Agents are autonomous units powered by Large Language Models (LLMs), designed to execute tasks, reason through problems, and collaborate within workflows. Acting as intelligent building blocks, agents combine reasoning with tool integration, memory, and collaboration features to get to the desired outcome.

Default resiliency policies

Mon, 01 Jan 0001 00:00:00 +0000

In resiliency, you can set default policies, which have a broad scope. This is done through reserved keywords that let Dapr know when to apply the policy. There are 3 default policy types:

DefaultRetryPolicy
DefaultTimeoutPolicy
DefaultCircuitBreakerPolicy

If these policies are defined, they are used for every operation to a service, application, or component. They can also be modified to be more specific through the appending of additional keywords. The specific policies follow the following pattern, Default%sRetryPolicy, Default%sTimeoutPolicy, and Default%sCircuitBreakerPolicy. Where the %s is replaced by a target of the policy.

Handling gRPC error codes

Mon, 01 Jan 0001 00:00:00 +0000

Initially, errors followed the Standard gRPC error model. However, to provide more detailed and informative error messages, an enhanced error model has been defined which aligns with the gRPC Richer error model.

Note

Not all Dapr errors have been converted to the richer gRPC error model.

Standard gRPC Error Model

The Standard gRPC error model is an approach to error reporting in gRPC. Each error response includes an error code and an error message. The error codes are standardized and reflect common error conditions.

How-To: Invoke Non-Dapr Endpoints using HTTP

Mon, 01 Jan 0001 00:00:00 +0000

This article demonstrates how to call a non-Dapr endpoint using Dapr over HTTP.

Using Dapr’s service invocation API, you can communicate with endpoints that either use or do not use Dapr. Using Dapr to call endpoints that do not use Dapr not only provides a consistent API, but also the following Dapr service invocation benefits:

Ability to apply resiliency policies
Call observability with tracing & metrics
Security access control through scoping
Ability to utilize middleware pipeline components
Service discovery
Authentication through the use of headers

HTTP service invocation to external services or non-Dapr endpoints

Sometimes you need to call a non-Dapr HTTP endpoint. For example:

Namespaced actors

Mon, 01 Jan 0001 00:00:00 +0000

Namespacing in Dapr provides isolation, and thus multi-tenancy. With actor namespacing, the same actor type can be deployed into different namespaces. You can call instances of these actors in the same namespace.

Note

Each namespaced actor deployment must use its own separate state store, especially if the same actor type is used across namespaces. In other words, no namespace information is written as part of the actor record, and hence separate state stores are required for each namespace. See Configuring actor state stores for namespacing section for examples.

Creating and configuring namespaces

You can use namespaces either in self-hosted mode or on Kubernetes.

Agentic Patterns

Mon, 01 Jan 0001 00:00:00 +0000

Dapr Agents simplify the implementation of agentic systems, from simple augmented LLMs to fully autonomous agents in enterprise environments. The following sections describe several application patterns that can benefit from Dapr Agents.

Overview

Agentic systems use design patterns such as reflection, tool use, planning, and multi-agent collaboration to achieve better results than simple single-prompt interactions. Rather than thinking of “agent” as a binary classification, it’s more useful to think of systems as being agentic to different degrees.

How to: Service invocation across namespaces

Mon, 01 Jan 0001 00:00:00 +0000

In this article, you’ll learn how you can call between services deployed to different namespaces. By default, service invocation supports invoking services within the same namespace by simply referencing the app ID (nodeapp):

localhost:3500/v1.0/invoke/nodeapp/method/neworder

Service invocation also supports calls across namespaces. On all supported hosting platforms, Dapr app IDs conform to a valid FQDN format that includes the target namespace. You can specify both:

The app ID (nodeapp), and
The namespace the app runs in (production).

Example 1

Actors timers and reminders

Mon, 01 Jan 0001 00:00:00 +0000

Actors can schedule periodic work on themselves by registering either timers or reminders.

The functionality of timers and reminders is very similar. The main difference is that Dapr actor runtime is not retaining any information about timers after deactivation, while persisting the information about reminders using Dapr Scheduler.

This distinction allows users to trade off between light-weight but stateless timers vs. more resource-demanding but stateful reminders.

The scheduling configuration of timers and reminders is summarized below:

Contributing with GitHub Codespaces

Mon, 01 Jan 0001 00:00:00 +0000

GitHub Codespaces is the easiest way to get up and running for contributing to a Dapr repo. In as little as a single click, you can have an environment with all of the prerequisites ready to go in your browser.

Features

Click and Run: Get a dedicated and sandboxed environment with all of the required frameworks and packages ready to go.
Usage-based Billing: Only pay for the time you spend developing in the Codespaces. Environments are spun down automatically when not in use.
Portable: Run in your browser or in Visual Studio Code, or connect to it using SSH.

Open a Dapr repo in a Codespace

To open a Dapr repository in a Codespace, select “Code” from the repo homepage and “Open with Codespaces”:

Integrations

Mon, 01 Jan 0001 00:00:00 +0000

Out-of-the-box Tools

Text Splitter

The Text Splitter module is a foundational integration in Dapr Agents designed to preprocess documents for use in Retrieval-Augmented Generation (RAG) workflows and other in-context learning applications. Its primary purpose is to break large documents into smaller, meaningful chunks that can be embedded, indexed, and efficiently retrieved based on user queries.

By focusing on manageable chunk sizes and preserving contextual integrity through overlaps, the Text Splitter ensures documents are processed in a way that supports downstream tasks like question answering, summarization, and document retrieval.

Dapr bot reference

Mon, 01 Jan 0001 00:00:00 +0000

Dapr bot is triggered by a list of commands that helps with common tasks in the Dapr organization. It is set up individually for each repository (example) and can be configured to run on specific events. Below is a list of commands and the list of repositories they are implemented on.

Command reference

Command	Target	Description	Who can use	Repository
`/assign`	Issue	Assigns an issue to a user or group of users	Anyone	`dapr`, `docs`, `quickstarts`, `cli`, `components-contrib`, `go-sdk`, `js-sdk`, `java-sdk`, `python-sdk`, `dotnet-sdk`, `rust-sdk`
`/ok-to-test`	Pull request	`dapr`: trigger end to end tests `components-contrib`: trigger conformance and certification tests	Users listed in the bot	`dapr`, `components-contrib`
`/ok-to-perf`	Pull request	Trigger performance tests.	Users listed in the bot	`dapr`
`/make-me-laugh`	Issue or pull request	Posts a random joke	Users listed in the bot	`dapr`, `components-contrib`

Label reference

You can query issues created by the Dapr bot by using the created-by/dapr-bot label (query).

Define a component

Mon, 01 Jan 0001 00:00:00 +0000

When building an app, you’d most likely create your own component file definitions, depending on the building block and specific component that you’d like to use.

In this tutorial, you will create a component definition file to interact with the secrets building block API:

Create a local JSON secret store.
Register the secret store with Dapr using a component definition file.
Obtain the secret using the Dapr HTTP API.

Step 1: Create a JSON secret store

Create a new directory named my-components to hold the new secret and component file:

How-to: Interact with virtual actors using scripting

Mon, 01 Jan 0001 00:00:00 +0000

Learn how to use virtual actors by calling HTTP/gRPC endpoints.

Invoke the actor method

You can interact with Dapr to invoke the actor method by calling HTTP/gRPC endpoint.

POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/method/<method>

Provide data for the actor method in the request body. The response for the request, which is data from actor method call, is in the response body.

Refer to the Actors API spec for more details.

Note

Alternatively, you can use Dapr SDKs to use actors.

Save state with actors

You can interact with Dapr via HTTP/gRPC endpoints to save state reliably using the Dapr actor state management capabaility.

Quickstarts

Mon, 01 Jan 0001 00:00:00 +0000

Dapr Agents Quickstarts demonstrate how to use Dapr Agents to build applications with LLM-powered autonomous agents and event-driven workflows. Each quickstart builds upon the previous one, introducing new concepts incrementally.

Before you begin

Set up your local Dapr environment.

Quickstarts

Scenario	What You’ll Learn
Dapr Agents Fundamentals An end-to-end introduction to the Dapr Agents programming model, progressing from basic LLM calls to durable agents, workflows, memory, tools, and tracing.	- LLM Clients and Agents: Call LLMs directly and wrap them in agents with roles and instructions - Tools and MCP: Invoke local tools and dynamically loaded MCP tools - Agent Memory: Persist and restore multi-turn conversation state - Durable Agents: Run agents as workflow-backed executions via HTTP or pub/sub - Deterministic Workflows: Build workflows with LLM and agent activities - Observability: Enable distributed tracing for agents and workflows with Zipkin
LLM Call with Dapr Chat Client Explore interaction with Language Models through Dapr Agents’ `DaprChatClient`, featuring basic text generation with plain text prompts and templates.	- Text Completion: Generating responses to prompts - Swapping LLM providers: Switching LLM backends without application code change - Resilience: Setting timeout, retry and circuit-breaking - PII Obfuscation: Automatically detect and mask sensitive user information
LLM Call with OpenAI Client Leverage native LLM client libraries with Dapr Agents using the OpenAI Client for chat completion, audio processing, and embeddings.	- Text Completion: Generating responses to prompts - Structured Outputs: Converting LLM responses to Pydantic objects Note: Other quickstarts for specific clients are available for Elevenlabs, Hugging Face, and Nvidia.
Standalone & Durable Agents Standalone Agent Tool Call · Durable Agent Tool Call	- Standalone Agents: Build conversational agents with tools in under 20 lines using the `Agent` class - Durable Agents: Upgrade to workflow-backed `DurableAgent` instances with `AgentRunner.run/subscribe/serve` - Tool Definition: Reuse tools with the `@tool` decorator and structured args models - Function Calling: Let LLMs invoke Python functions safely
Agentic Workflow Dive into stateful workflows with Dapr Agents by orchestrating sequential and parallel tasks through powerful workflow capabilities.	- LLM-powered Tasks: Using language models in workflows - Task Chaining: Creating resilient multi-step processes executing in sequence - Fan-out/Fan-in: Executing activities in parallel; then synchronizing these activities until all preceding activities have completed
Multi-Agent Workflows Explore advanced event-driven workflows featuring a Lord of the Rings themed multi-agent system where autonomous agents collaborate to solve problems.	- Multi-agent Systems: Creating a network of specialized agents - Event-driven Architecture: Implementing pub/sub messaging between agents - Workflow Orchestration: Coordinating agents through different selection strategies
Multi-Agent Workflow on Kubernetes Run multi-agent workflows in Kubernetes, demonstrating deployment and orchestration of event-driven agent systems in a containerized environment.	- Kubernetes Deployment: Running agents on Kubernetes - Container Orchestration: Managing agent lifecycles with K8s - Service Communication: Inter-agent communication in K8s
Document Agent with Chainlit Create a conversational agent with an operational UI that can upload, and learn unstructured documents while retaining long-term memory.	- Conversational Document Agent: Upload and converse over unstructured documents - Cloud Agnostic Storage: Upload files to multiple storage providers - Conversation Memory Storage: Persists conversation history using external storage.
Data Agent with MCP and Chainlit Build a conversational agent over a Postgres database using Model Composition Protocol (MCP) with a ChatGPT-like interface.	- Database Querying: Natural language queries to relational databases - MCP Integration: Connecting to databases without DB-specific code - Data Analysis: Complex data analysis through conversation

Quickstart: Service Invocation

Mon, 01 Jan 0001 00:00:00 +0000

With Dapr’s Service Invocation building block, your application can communicate reliably and securely with other applications.

Dapr offers several methods for service invocation, which you can choose depending on your scenario. For this Quickstart, you’ll enable the checkout service to invoke a method using HTTP proxy in the order-processor service and by either:

Learn more about Dapr’s methods for service invocation in the overview article.

Quickstart: Publish and Subscribe

Mon, 01 Jan 0001 00:00:00 +0000

Let’s take a look at Dapr’s Publish and Subscribe (Pub/sub) building block. In this Quickstart, you will run a publisher microservice and a subscriber microservice to demonstrate how Dapr enables a Pub/sub pattern.

Using a publisher service, developers can repeatedly publish messages to a topic.
A Pub/sub component queues or brokers those messages. Our example below uses Redis, you can use RabbitMQ, Kafka, etc.
The subscriber to that topic pulls messages from the queue and processes them.

You can try out this pub/sub quickstart by either:

Quickstart: Workflow

Mon, 01 Jan 0001 00:00:00 +0000

Note

Redis is currently used as the state store component for Workflows in the Quickstarts. However, Redis does not support transaction rollbacks and should not be used in production as an actor state store.

Let’s take a look at the Dapr Workflow building block. In this Quickstart, you’ll create a simple console application to demonstrate Dapr’s workflow programming model and the workflow management APIs.

In this guide, you’ll:

Run the order-processor application.
Start the workflow and watch the workflow activites/tasks execute.
Review the workflow logic and the workflow activities and how they’re represented in the code.

The workflow contains the following activities:

Quickstart: State Management

Mon, 01 Jan 0001 00:00:00 +0000

Let’s take a look at Dapr’s State Management building block. In this Quickstart, you will save, get, and delete state using a Redis state store by either:

While this sample uses Redis, you can swap it out for any one of the supported state stores.

Run using Multi-App Run

Select your preferred language-specific Dapr SDK before proceeding with the Quickstart.

Quickstart: Input & Output Bindings

Mon, 01 Jan 0001 00:00:00 +0000

Let’s take a look at Dapr’s Bindings building block. Using bindings, you can:

Trigger your app with events coming in from external systems.
Interface with external systems.

In this Quickstart, you schedule a batch script to run every 10 seconds using an input Cron binding. The script processes a JSON file and outputs data to a SQL database using the PostgreSQL Dapr binding.

Select your preferred language-specific Dapr SDK before proceeding with the Quickstart.

Quickstart: Actors

Mon, 01 Jan 0001 00:00:00 +0000

Let’s take a look at Dapr’s Actors building block. In this Quickstart, you will run a smart device microservice and a simple console client to demonstrate the stateful object patterns in Dapr Actors.

Currently, you can experience this actors quickstart using the .NET SDK.

As a quick overview of the .NET actors quickstart:

Using a SmartDevice.Service microservice, you host:
- Two SmokeDetectorActor smoke alarm objects
- A ControllerActor object that commands and controls the smart devices
Using a SmartDevice.Client console app, the client app interacts with each actor, or the controller, to perform actions in aggregate.
The SmartDevice.Interfaces contains the shared interfaces and data types used by both the service and client apps.

Pre-requisites

For this example, you will need:

Quickstart: Secrets Management

Mon, 01 Jan 0001 00:00:00 +0000

Dapr provides a dedicated secrets API that allows developers to retrieve secrets from a secrets store. In this quickstart, you:

Run a microservice with a secret store component.
Retrieve secrets using the Dapr secrets API in the application code.

Select your preferred language-specific Dapr SDK before proceeding with the Quickstart.

Pre-requisites

For this example, you will need:

Quickstart: Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Let’s take a look at Dapr’s Configuration building block. A configuration item is often dynamic in nature and tightly coupled to the needs of the application that consumes it. Configuration items are key/value pairs containing configuration data, such as:

App ids
Partition keys
Database names, etc

In this quickstart, you’ll run an order-processor microservice that utilizes the Configuration API. The service:

Gets configuration items from the configuration store.
Subscribes for configuration updates.

Select your preferred language-specific Dapr SDK before proceeding with the Quickstart.

Quickstart: Cryptography

Mon, 01 Jan 0001 00:00:00 +0000

Alpha

The cryptography building block is currently in alpha.

Let’s take a look at the Dapr cryptography building block. In this Quickstart, you’ll create an application that encrypts and decrypts data using the Dapr cryptography APIs. You’ll:

Encrypt and then decrypt a short string (using an RSA key), reading the result in-memory, in a Go byte slice.
Encrypt and then decrypt a large file (using an AES key), storing the encrypted and decrypted data to files using streams.

Note

This example uses the Dapr SDK, which leverages gRPC and is strongly recommended when using cryptographic APIs to encrypt and decrypt messages.

Currently, you can experience the cryptography API using the Go SDK.

Tutorial: Configure state store and pub/sub message broker

Mon, 01 Jan 0001 00:00:00 +0000

To get up and running with the state and Pub/sub building blocks, you’ll need two components:

A state store component for persistence and restoration.
As pub/sub message broker component for async-style message delivery.

A full list of supported components can be found here:

For this tutorial, we describe how to get up and running with Redis.

Step 1: Create a Redis store

Dapr can use any Redis instance, either:

How-to: Enable and use actor reentrancy in Dapr

Mon, 01 Jan 0001 00:00:00 +0000

A core tenet of the virtual actor pattern is the single-threaded nature of actor execution. Without reentrancy, the Dapr runtime locks on all actor requests. A second request wouldn’t be able to start until the first had completed. This means an actor cannot call itself, or have another actor call into it, even if it’s part of the same call chain.

Reentrancy solves this by allowing requests from the same chain, or context, to re-enter into an already locked actor. This proves useful in scenarios where:

Quickstart: Jobs

Mon, 01 Jan 0001 00:00:00 +0000

Alpha

The jobs building block is currently in alpha.

Let’s take a look at the Dapr jobs building block, which schedules and runs jobs at a specific time or interval. In this Quickstart, you’ll schedule, get, and delete a job using Dapr’s Job API.

You can try out this jobs quickstart by either:

Run using Multi-App Run

Select your preferred language-specific Dapr SDK before proceeding with the Quickstart. Currently, you can experiment with the jobs API with the Go SDK.

Contributing to Dapr Agents

Mon, 01 Jan 0001 00:00:00 +0000

When contributing to Dapr Agents, the following rules and best-practices should be followed.

Examples

The examples directory contains code samples for users to run to try out specific functionality of the various Dapr Agents packages and extensions. When writing new and updated samples keep in mind:

All examples should be runnable on Windows, Linux, and MacOS. While Python code is consistent among operating systems, any pre/post example commands should provide options through codetabs
Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine.

Dependencies

This project uses modern Python packaging with pyproject.toml. Dependencies are managed as follows:

Quickstart: Conversation

Mon, 01 Jan 0001 00:00:00 +0000

Alpha

The conversation building block is currently in alpha.

Let’s take a look at how the Dapr conversation building block makes interacting with Large Language Models (LLMs) easier. In this quickstart, you use the echo component to communicate with the mock LLM and ask it to define Dapr.

You can try out this conversation quickstart by either:

Note

Currently, you can only use JavaScript for the quickstart sample using HTTP, not the JavaScript SDK.

Run the app with the template file

Select your preferred language-specific Dapr SDK before proceeding with the Quickstart.

App health checks

Mon, 01 Jan 0001 00:00:00 +0000

The app health checks feature allows probing for the health of your application and reacting to status changes.

Applications can become unresponsive for a variety of reasons. For example, your application:

Could be too busy to accept new work;
Could have crashed; or
Could be in a deadlock state.

Sometimes the condition can be transitory, for example:

If the app is just busy and will resume accepting new work eventually
If the application is being restarted for whatever reason and is in its initialization phase

App health checks are disabled by default. Once you enable app health checks, the Dapr runtime (sidecar) periodically polls your application via HTTP or gRPC calls. When it detects a failure in the app’s health, Dapr stops accepting new work on behalf of the application by:

General Dapr questions and answers

Mon, 01 Jan 0001 00:00:00 +0000

How does Dapr compare to service meshes such as Istio, Linkerd or OSM?

Dapr is not a service mesh. While service meshes focus on fine-grained network control, Dapr is focused on helping developers build distributed applications. Both Dapr and service meshes use the sidecar pattern and run alongside the application. They do have some overlapping features, but also offer unique benefits. For more information please read the Dapr & service meshes concept page.

Workflow Protocol - Management API

Mon, 01 Jan 0001 00:00:00 +0000

Workflow Management API

The Workflow Management API allows Dapr clients to control the lifecycle of workflow instances. These APIs are exposed via the standard Dapr gRPC endpoint and are typically made available via the SDKs.

gRPC Service Definition

The management APIs are part of the Dapr service in dapr.proto.runtime.v1. While multiple versions (Alpha1, Beta1) may exist, the following describes the current implementation logic.

StartWorkflow

Starts a new instance of a workflow.

Overview

Mon, 01 Jan 0001 00:00:00 +0000

Dapr is a portable, event-driven runtime that makes it easy for any developer to build resilient, stateless, and stateful applications that run on the cloud and edge and embraces the diversity of languages and developer frameworks.

Any language, any framework, anywhere

With the current wave of cloud adoption, web + database application architectures (such as classic 3-tier designs) are trending more toward microservice application architectures, which are inherently distributed. You shouldn’t have to become a distributed systems expert just to create microservices applications.

Bindings overview

Mon, 01 Jan 0001 00:00:00 +0000

Using Dapr’s bindings API, you can trigger your app with events coming in from external systems and interface with external systems. With the bindings API, you can:

Avoid the complexities of connecting to and polling from messaging systems, such as queues and message buses.
Focus on business logic, instead of the implementation details of interacting with a system.
Keep your code free from SDKs or libraries.
Handle retries and failure recovery.
Switch between bindings at runtime.
Build portable applications with environment-specific bindings set-up and no required code changes.

For example, with bindings, your application can respond to incoming Twilio/SMS messages without:

State management overview

Mon, 01 Jan 0001 00:00:00 +0000

Your application can use Dapr’s state management API to save, read, and query key/value pairs in the supported state stores. Using a state store component, you can build stateful, long running applications that save and retrieve their state (like a shopping cart or a game’s session state). For example, in the diagram below:

Use HTTP POST to save or query key/value pairs.
Use HTTP GET to read a specific key and have its value returned.

The following overview video and demo demonstrates how Dapr state management works.

Dapr configuration

Mon, 01 Jan 0001 00:00:00 +0000

Dapr configurations are settings and policies that enable you to change both the behavior of individual Dapr applications, or the global behavior of the Dapr control plane system services.

for more information, read the configuration concept.

Application configuration

Set up application configuration

You can set up application configuration either in self-hosted or Kubernetes mode.

In self hosted mode, the Dapr configuration is a configuration file - for example, config.yaml. By default, the Dapr sidecar looks in the default Dapr folder for the runtime configuration:

Overview

Mon, 01 Jan 0001 00:00:00 +0000

Dapr provides the capability for defining and applying fault tolerance resiliency policies via a resiliency spec. Resiliency specs are saved in the same location as components specs and are applied when the Dapr sidecar starts. The sidecar determines how to apply resiliency policies to your Dapr API calls.

In self-hosted mode: The resiliency spec must be named resiliency.yaml.
In Kubernetes: Dapr finds the named resiliency specs used by your application.

Policies

You can configure Dapr resiliency policies with the following parts:

Dapr sidecar (daprd) overview

Mon, 01 Jan 0001 00:00:00 +0000

Dapr uses a sidecar pattern, meaning the Dapr APIs are run and exposed on a separate process, the Dapr sidecar, running alongside your application. The Dapr sidecar process is named daprd and is launched in different ways depending on the hosting environment.

The Dapr sidecar exposes:

Building block APIs used by your application business logic
A metadata API for discoverability of capabilities and to set attributes
A health API to determine health status and sidecar readiness and liveness

The Dapr sidecar will reach readiness state once the application is accessible on its configured port. The application cannot access the Dapr components during application start up/initialization.

Quickstart: Service-to-component resiliency

Mon, 01 Jan 0001 00:00:00 +0000

Observe Dapr resiliency capabilities by simulating a system failure. In this Quickstart, you will:

Execute a microservice application that continuously persists and retrieves state via Dapr’s state management API.
Trigger resiliency policies by simulating a system failure.
Resolve the failure and the microservice application will resume.

Select your preferred language-specific Dapr SDK before proceeding with the Quickstart.

Pre-requisites

For this example, you will need:

Quickstart: Service-to-service resiliency

Mon, 01 Jan 0001 00:00:00 +0000

Observe Dapr resiliency capabilities by simulating a system failure. In this Quickstart, you will:

Run two microservice applications: checkout and order-processor. checkout will continuously make Dapr service invocation requests to order-processor.
Trigger the resiliency spec by simulating a system failure.
Remove the failure to allow the microservice application to recover.

Select your preferred language-specific Dapr SDK before proceeding with the Quickstart.

Pre-requisites

For this example, you will need:

Actors API reference

Mon, 01 Jan 0001 00:00:00 +0000

Dapr provides native, cross-platform, and cross-language virtual actor capabilities. Besides the language specific SDKs, a developer can invoke an actor using the API endpoints below.

User service code calling Dapr

Invoke actor method

Invoke an actor method through Dapr.

HTTP Request

POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/method/<method>

HTTP Response Codes

Code	Description
200	Request successful
500	Request failed
XXX	Status code from upstream call

URL Parameters

Parameter	Description
`daprPort`	The Dapr port.
`actorType`	The actor type.
`actorId`	The actor ID.
`method`	The name of the method to invoke.

Note, all URL parameters are case-sensitive.

Building blocks

Mon, 01 Jan 0001 00:00:00 +0000

A building block is an HTTP or gRPC API that can be called from your code and uses one or more Dapr components. Dapr consists of a set of API building blocks, with extensibility to add new building blocks. Dapr’s building blocks:

Address common challenges in building resilient, microservices applications
Codify best practices and patterns

The diagram below shows how building blocks expose a public API that is called from your code, using components to implement the building blocks’ capability.

Certification lifecycle

Mon, 01 Jan 0001 00:00:00 +0000

Note

Certification lifecycle only applies to built-in components and does not apply to pluggable components.

Overview

Dapr uses a modular design where functionality is delivered as a component. Each component has an interface definition. All of the components are interchangeable, so that in ideal scenarios, you can swap out one component with the same interface for another. Each component used in production maintains a certain set of technical requirements to ensure functional compatibility and robustness.

Workflow Protocol - Execution API

Mon, 01 Jan 0001 00:00:00 +0000

Workflow Execution API (Task Hub Protocol)

The Workflow Execution API is a low-level gRPC protocol used by Dapr Workflow SDKs to act as “Workers”. The SDK connects to the Dapr sidecar via this protocol to poll for work and report completion.

The service is named TaskHubSidecarService.

Service Definition (gRPC)

service TaskHubSidecarService {
 rpc GetWorkItems(GetWorkItemsRequest) returns (stream WorkItem);
 rpc CompleteOrchestratorTask(OrchestratorResponse) returns (CompleteBatchResponse);
 rpc CompleteActivityTask(ActivityResponse) returns (CompleteBatchResponse);
 // ... other management methods
}

Worker Lifecycle

Connection: The SDK opens a long-running bidirectional stream to GetWorkItems.
Polling: The SDK receives WorkItem messages from the stream.
Execution:
- If the work item is an Orchestration, the SDK retrieves and replays the history events to determine the next actions.
- If the work item is an Activity, the SDK executes the activity logic.
Completion:
- For Orchestrations, the SDK calls CompleteOrchestratorTask with a list of actions to take.
- For Activities, the SDK calls CompleteActivityTask with the result or failure information.

gRPC Service: `TaskHubSidecarService`

GetWorkItems

Opens a stream to receive work items for orchestrations and activities.

How-To: Trigger your application with input bindings

Mon, 01 Jan 0001 00:00:00 +0000

With input bindings, you can trigger your application when an event from an external resource occurs. An external resource could be a queue, messaging pipeline, cloud-service, filesystem, etc. An optional payload and metadata may be sent with the request.

Input bindings are ideal for event-driven processing, data pipelines, or generally reacting to events and performing further processing. Dapr input bindings allow you to:

Receive events without including specific SDKs or libraries
Replace bindings without changing your code
Focus on business logic and not the event resource implementation

This guide uses a Kafka binding as an example. You can find your preferred binding spec from the list of bindings components. In this guide:

How-To: Save and get state

Mon, 01 Jan 0001 00:00:00 +0000

State management is one of the most common needs of any new, legacy, monolith, or microservice application. Dealing with and testing different database libraries and handling retries and faults can be both difficult and time consuming.

In this guide, you’ll learn the basics of using the key/value state API to allow an application to save, get, and delete state.

The code example below loosely describes an application that processes orders with an order processing service which has a Dapr sidecar. The order processing service uses Dapr to store state in a Redis state store.

How to: Author middleware components

Mon, 01 Jan 0001 00:00:00 +0000

Dapr allows custom processing pipelines to be defined by chaining a series of middleware components. In this guide, you’ll learn how to create a middleware component. To learn how to configure an existing middleware component, see Configure middleware components

Writing a custom HTTP middleware

HTTP middlewares in Dapr wrap standard Go net/http handler functions.

Your middleware needs to implement a middleware interface, which defines a GetHandler method that returns a http.Handler callback and an error:

Dapr and service meshes

Mon, 01 Jan 0001 00:00:00 +0000

Dapr uses a sidecar architecture, running as a separate process alongside the application and includes features such as service invocation, network security, and distributed tracing. This often raises the question: how does Dapr compare to service mesh solutions such as Linkerd, Istio and Open Service Mesh among others?

How Dapr and service meshes compare

While Dapr and service meshes do offer some overlapping capabilities, Dapr is not a service mesh, where a service mesh is defined as a networking service mesh. Unlike a service mesh which is focused on networking concerns, Dapr is focused on providing building blocks that make it easier for developers to build applications as microservices. Dapr is developer-centric, versus service meshes which are infrastructure-centric.

Sidecar health

Mon, 01 Jan 0001 00:00:00 +0000

Dapr provides a way to determine its health using an HTTP /healthz endpoint. With this endpoint, the daprd process, or sidecar, can be:

Probed for its overall health
Probed for Dapr sidecar readiness from infrastructure platforms
Determined for readiness and liveness with Kubernetes

In this guide, you learn how the Dapr /healthz endpoint integrates with health probes from the application hosting platform (for example, Kubernetes) as well as the Dapr SDKs.

How-To: Query state

Mon, 01 Jan 0001 00:00:00 +0000

alpha

The state query API is in alpha stage.

With the state query API, you can retrieve, filter, and sort the key/value data stored in state store components. The query API is not a replacement for a complete query language.

Even though the state store is a key/value store, the value might be a JSON document with its own hierarchy, keys, and values. The query API allows you to use those keys/values to retrieve corresponding documents.

Dapr arguments and annotations for daprd, CLI, and Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

This table is meant to help users understand the equivalent options for running Dapr sidecars in different contexts: via the CLI directly, via daprd, or on Kubernetes via annotations.

daprd	Dapr CLI	CLI shorthand	Kubernetes annotations	Description
`--allowed-origins`	not supported		not supported	Allowed HTTP origins (default “*”)
`--app-id`	`--app-id`	`-i`	`dapr.io/app-id`	The unique ID of the application. Used for service discovery, state encapsulation and the pub/sub consumer ID
`--app-port`	`--app-port`	`-p`	`dapr.io/app-port`	This parameter tells Dapr which port your application is listening on
`--components-path`	`--components-path`	`-d`	not supported	Deprecated in favor of `--resources-path`
`--resources-path`	`--resources-path`	`-d`	not supported	Path for components directory. If empty, components will not be loaded
`--config`	`--config`	`-c`	`dapr.io/config`	Tells Dapr which Configuration resource to use
`--control-plane-address`	not supported		not supported	Address for a Dapr control plane
`--dapr-grpc-port`	`--dapr-grpc-port`		`dapr.io/grpc-port`	Sets the Dapr API gRPC port (default `50001`); all cluster services must use the same port for communication
`--dapr-http-port`	`--dapr-http-port`		not supported	HTTP port for the Dapr API to listen on (default `3500`)
`--dapr-http-max-request-size`	`--dapr-http-max-request-size`		`dapr.io/http-max-request-size`	Deprecated in favor of `--max-body-size`. Inreasing the request max body size to handle large file uploads using http and grpc protocols. Default is `4` MB
`--max-body-size`	not supported		`dapr.io/max-body-size`	Inreasing the request max body size to handle large file uploads using http and grpc protocols. Set the value using size units (e.g., `16Mi` for 16MB). The default is `4Mi`
`--dapr-http-read-buffer-size`	`--dapr-http-read-buffer-size`		`dapr.io/http-read-buffer-size`	Deprecated in favor of `--read-buffer-size`. Increasing max size of http header read buffer in KB to to support larger header values, for example `16` to support headers up to 16KB . Default is `16` for 16KB
`--read-buffer-size`	not supported		`dapr.io/read-buffer-size`	Increasing max size of http header read buffer in KB to to support larger header values. Set the value using size units, for example `32Ki` will support headers up to 32KB . Default is `4Ki` for 4KB
not supported	`--image`		`dapr.io/sidecar-image`	Dapr sidecar image. Default is daprio/daprd:latest. The Dapr sidecar uses this image instead of the latest default image. Use this when building your own custom image of Dapr and or using an alternative stable Dapr image
`--internal-grpc-port`	not supported		`dapr.io/internal-grpc-port`	Sets the internal Dapr gRPC port (default `50002`); all cluster services must use the same port for communication
`--enable-metrics`	not supported		configuration spec	Enable prometheus metric (default true)
`--enable-mtls`	not supported		configuration spec	Enables automatic mTLS for daprd to daprd communication channels
`--enable-profiling`	`--enable-profiling`		`dapr.io/enable-profiling`	Enable profiling
`--unix-domain-socket`	`--unix-domain-socket`	`-u`	`dapr.io/unix-domain-socket-path`	The parent directory of socket file. On Linux, when communicating with the Dapr sidecar, use unix domain sockets for lower latency and greater throughput compared to TCP ports. Not available on Windows OS.
`--log-as-json`	not supported		`dapr.io/log-as-json`	Setting this parameter to `true` outputs logs in JSON format. Default is `false`
`--log-level`	`--log-level`		`dapr.io/log-level`	Sets the log level for the Dapr sidecar. Allowed values are `debug`, `info`, `warn`, `error`. Default is `info`
`--enable-api-logging`	`--enable-api-logging`		`dapr.io/enable-api-logging`	Enables API logging for the Dapr sidecar
`--app-max-concurrency`	`--app-max-concurrency`		`dapr.io/app-max-concurrency`	Limit the concurrency of your application. A valid value is any number larger than `0`. Default value: `-1`, meaning no concurrency.
`--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.
`--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 a single space (`' '`), or “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 a single space (`' '`), or “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:50055,127.0.0.1:50056`
`--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.
`--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`
`--enable-app-health-check`	`--enable-app-health-check`		`dapr.io/enable-app-health-check`	Boolean that enables the health checks. Default is `false`.
`--app-health-check-path`	`--app-health-check-path`		`dapr.io/app-health-check-path`	Path that Dapr invokes for health probes when the app channel is HTTP (this value is ignored if the app channel is using gRPC). Requires app health checks to be enabled. Default is `/healthz`.
`--app-health-probe-interval`	`--app-health-probe-interval`		`dapr.io/app-health-probe-interval`	Number of seconds between each health probe. Requires app health checks to be enabled. Default is `5`
`--app-health-probe-timeout`	`--app-health-probe-timeout`		`dapr.io/app-health-probe-timeout`	Timeout in milliseconds for health probe requests. Requires app health checks to be enabled. Default is `500`
`--app-health-threshold`	`--app-health-threshold`		`dapr.io/app-health-threshold"`	Max number of consecutive failures before the app is considered unhealthy. Requires app health checks to be enabled. Default is `3`
`--sentry-address`	`--sentry-address`		not supported	Address for the Sentry CA service
`--version`	`--version`	`-v`	not supported	Prints the runtime version
`--dapr-graceful-shutdown-seconds`	not supported		`dapr.io/graceful-shutdown-seconds`	Graceful shutdown duration in seconds for Dapr, the maximum duration before forced shutdown when waiting for all in-progress requests to complete. Defaults to `5`. If you are running in Kubernetes mode, this value should not be larger than the Kubernetes termination grace period, who’s default value is `30`.
`--dapr-block-shutdown-duration`	not supported		`dapr.io/block-shutdown-duration`	Block shutdown duration, if set, blocks the graceful shutdown procedure (as described above) from starting until the given duration has elapsed or the application becomes unhealthy as configured through application health options. This is useful for applications that need to execute Dapr APIs during their own termination procedure. Any new invocations of any Dapr APIs are not available to the application once the block has expired. Accepts Go duration string.
not supported	not supported		`dapr.io/enabled`	Setting this paramater to true injects the Dapr sidecar into the pod
not supported	not supported		`dapr.io/api-token-secret`	Tells Dapr which Kubernetes secret to use for token-based API authentication. By default this is not set
not supported	not supported		`dapr.io/app-token-secret`	Tells Dapr which Kubernetes secret to use for token-based application authentication. By default, this is not set
`--dapr-listen-addresses`	not supported		`dapr.io/sidecar-listen-addresses`	Comma separated list of IP addresses that sidecar will listen to. Defaults to all in standalone mode. Defaults to `[::1],127.0.0.1` in Kubernetes. To listen to all IPv4 addresses, use `0.0.0.0`. To listen to all IPv6 addresses, use `[::]`.
not supported	not supported		`dapr.io/sidecar-cpu-limit`	Maximum amount of CPU that the Dapr sidecar can use. See valid values here. By default this is not set
not supported	not supported		`dapr.io/sidecar-memory-limit`	Maximum amount of Memory that the Dapr sidecar can use. See valid values here. By default this is not set
not supported	not supported		`dapr.io/sidecar-cpu-request`	Amount of CPU that the Dapr sidecar requests. See valid values here. By default this is not set
not supported	not supported		`dapr.io/sidecar-memory-request`	Amount of Memory that the Dapr sidecar requests .See valid values here. By default this is not set
not supported	not supported		`dapr.io/sidecar-liveness-probe-delay-seconds`	Number of seconds after the sidecar container has started before liveness probe is initiated. Read more here. Default is `180`
not supported	not supported		`dapr.io/sidecar-liveness-probe-timeout-seconds`	Number of seconds after which the sidecar liveness probe times out. Read more here. Default is `3`
not supported	not supported		`dapr.io/sidecar-liveness-probe-period-seconds`	How often (in seconds) to perform the sidecar liveness probe. Read more here. Default is `10`
not supported	not supported		`dapr.io/sidecar-liveness-probe-threshold`	When the sidecar liveness probe fails, Kubernetes will try N times before giving up. In this case, the Pod will be marked Unhealthy. Read more about `failureThreshold` here. Default is `5`
not supported	not supported		`dapr.io/sidecar-readiness-probe-delay-seconds`	Number of seconds after the sidecar container has started before readiness probe is initiated. Read more here. Default is `1`
not supported	not supported		`dapr.io/sidecar-readiness-probe-timeout-seconds`	Number of seconds after which the sidecar readiness probe times out. Read more here. Default is `1`
not supported	not supported		`dapr.io/sidecar-readiness-probe-period-seconds`	How often (in seconds) to perform the sidecar readiness probe. Read more here. Default is `1`
not supported	not supported		`dapr.io/sidecar-readiness-probe-threshold`	When the sidecar readiness probe fails, Kubernetes will try N times before giving up. In this case, the Pod will be marked Unready. Read more about `failureThreshold` here. Default is `5`
not supported	not supported		`dapr.io/env`	List of environment variable to be injected into the sidecar. Strings consisting of key=value pairs separated by a comma.
not supported	not supported		`dapr.io/env-from-secret`	List of environment variables to be injected into the sidecar from secret. Strings consisting of `"key=secret-name:secret-key"` pairs are separated by a comma.
not supported	not supported		`dapr.io/volume-mounts`	List of pod volumes to be mounted to the sidecar container in read-only mode. Strings consisting of `volume:path` pairs separated by a comma. Example, `"volume-1:/tmp/mount1,volume-2:/home/root/mount2"`.
not supported	not supported		`dapr.io/volume-mounts-rw`	List of pod volumes to be mounted to the sidecar container in read-write mode. Strings consisting of `volume:path` pairs separated by a comma. Example, `"volume-1:/tmp/mount1,volume-2:/home/root/mount2"`.
`--disable-builtin-k8s-secret-store`	not supported		`dapr.io/disable-builtin-k8s-secret-store`	Disables BuiltIn Kubernetes secret store. Default value is false. See Kubernetes secret store component for details.
`--disable-init-endpoints`	`--disable-init-endpoints`		`dapr.io/disable-init-endpoints`	Comma-separated list of initialization endpoints to disable. Supported values are `config` (disables `/dapr/config`) and `subscribe` (disables `/dapr/subscribe`). Example: `"config,subscribe"`. By default, this is not set.
not supported	not supported		`dapr.io/sidecar-seccomp-profile-type`	Set the sidecar container’s `securityContext.seccompProfile.type` to `Unconfined`, `RuntimeDefault`, or `Localhost`. By default, this annotation is not set on the Dapr sidecar, hence the field is omitted from sidecar container.
not supported	not supported		`dapr.io/sidecar-svc-annotations`	Custom annotations to be applied to the operator-managed `-dapr` sidecar service. Strings consisting of `key=value` pairs separated by a comma. Read more here.
not supported	not supported		`dapr.io/enable-native-sidecar`	When set to `"true"`, injects daprd as a Kubernetes native sidecar (init container with `restartPolicy: Always`, KEP-753). Overrides the global `dapr_sidecar_injector.nativeSidecar` Helm setting. Requires Kubernetes 1.28+. Default is not set (inherits global Helm value).

Bindings API reference

Mon, 01 Jan 0001 00:00:00 +0000

Dapr provides bi-directional binding capabilities for applications and a consistent approach to interacting with different cloud/on-premise services or systems. Developers can invoke output bindings using the Dapr API, and have the Dapr runtime trigger an application with input bindings.

Examples for bindings include Kafka, Rabbit MQ, Azure Event Hubs, AWS SQS, GCP Storage to name a few.

Bindings Structure

A Dapr Binding yaml file has the following structure:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
 namespace: <NAMESPACE>
spec:
 type: bindings.<TYPE>
 version: v1
 metadata:
 - name: <NAME>
 value: <VALUE>

The metadata.name is the name of the binding.

Components

Mon, 01 Jan 0001 00:00:00 +0000

Dapr uses a modular design where functionality is delivered as a component. Each component has an interface definition. All of the components are interchangeable so that you can swap out one component with the same interface for another.

You can contribute implementations and extend Dapr’s component interfaces capabilities via:

A building block can use any combination of components. For example, the actors and the state management building blocks both use state components.

Debugging Dapr Apps running in Docker Compose

Mon, 01 Jan 0001 00:00:00 +0000

The goal of this article is to demonstrate a way to debug one or more daprised applications (via your IDE, locally) while remaining integrated with the other applications that have deployed in the docker compose environment.

Let’s take the minimal example of a docker compose file which contains just two services :

nodeapp - your app
nodeapp-dapr - the dapr sidecar process to your nodeapp service

compose.yml

services:
 nodeapp:
 build: ./node
 ports:
 - "50001:50001"
 networks:
 - hello-dapr
 nodeapp-dapr:
 image: "daprio/daprd:edge"
 command: [
 "./daprd",
 "--app-id", "nodeapp",
 "--app-port", "3000",
 "--resources-path", "./components"
 ]
 volumes:
 - "./components/:/components"
 depends_on:
 - nodeapp
 network_mode: "service:nodeapp"
networks:
 hello-dapr

When you run this docker file with docker compose -f compose.yml up this will deploy to Docker and run as normal.

How-To: Build a stateful service

Mon, 01 Jan 0001 00:00:00 +0000

In this article, you’ll learn how to create a stateful service which can be horizontally scaled, using opt-in concurrency and consistency models. Consuming the state management API frees developers from difficult state coordination, conflict resolution, and failure handling.

Set up a state store

A state store component represents a resource that Dapr uses to communicate with a database. For the purpose of this guide, we’ll use the default Redis state store.

How-To: Use output bindings to interface with external resources

Mon, 01 Jan 0001 00:00:00 +0000

With output bindings, you can invoke external resources. An optional payload and metadata can be sent with the invocation request.

This guide uses a Kafka binding as an example. You can find your preferred binding spec from the list of bindings components. In this guide:

The example invokes the /binding endpoint with checkout, the name of the binding to invoke.
The payload goes inside the mandatory data field, and can be any JSON serializable value.
The operation field tells the binding what action it needs to take. For example, the Kafka binding supports the create operation.
- You can check which operations (specific to each component) are supported for every output binding.

Note

If you haven’t already, try out the bindings quickstart for a quick walk-through on how to use the bindings API.

Create a binding

Create a binding.yaml file and save to a components sub-folder in your application directory.

Workflow Protocol - Orchestration Lifecycle

Mon, 01 Jan 0001 00:00:00 +0000

Orchestration Lifecycle

This document describes the lifecycle of an orchestration at the protocol level, specifically how the Dapr engine and the SDK interact to execute workflow logic reliably.

Replay-based Execution

Dapr Workflows use event sourcing and replay to maintain state. Instead of saving the entire state of the worker process (stack, variables, etc.), Dapr saves a history of events that have occurred.

The Replay Loop

Work Item Arrival: The Dapr engine sends an OrchestratorWorkItem to the SDK via the GetWorkItems stream. This work item contains the full history of the workflow instance plus any new events (e.g., an activity completion or an external event).
Reconstruction: The SDK starts executing the orchestration function from the very beginning.
Deterministic Execution: As the function executes, it encounters “tasks” (e.g., calling an activity, sleeping).
- For each task, the SDK checks the provided History to see if that task has already completed.
- If the task is in the history, the SDK returns the recorded result immediately without actually re-executing the task logic.
- If the task is NOT in the history, the SDK records that this task needs to be scheduled and suspends execution of the orchestration function (typically by throwing a special exception or returning a pending promise).
Reporting: Once the orchestration function is suspended or completes, the SDK sends a CompleteOrchestratorTask request to Dapr. This request contains a list of Actions (e.g., ScheduleTask, CreateTimer) that the engine should perform.
State Commitment: The Dapr engine receives the actions, updates the workflow history in the state store, and schedules any requested tasks (e.g., by sending work to an activity worker).

Step-by-Step Example

Imagine a workflow: Activity A -> Activity B.

Targets

Mon, 01 Jan 0001 00:00:00 +0000

Targets

Named policies are applied to targets. Dapr supports three target types that apply all Dapr building block APIs:

apps
components
actors

Apps

With the apps target, you can apply retry, timeout, and circuitBreaker policies to service invocation calls between Dapr apps. Under targets/apps, policies are applied to each target service’s app-id. The policies are invoked when a failure occurs in communication between sidecars, as shown in the diagram below.

Updating resources

Mon, 01 Jan 0001 00:00:00 +0000

When making an update to an existing deployed component used by an application, Dapr does not update the component automatically unless the HotReload feature gate is enabled. The Dapr sidecar needs to be restarted in order to pick up the latest version of the component. How this is done depends on the hosting environment.

Kubernetes

When running in Kubernetes, the process of updating a component involves two steps:

Apply the new component YAML to the desired namespace
Unless the HotReload feature gate is enabled, perform a rollout restart operation on your deployments to pick up the latest component

Self Hosted

Unless the HotReload feature gate is enabled, the process of updating a component involves a single step of stopping and restarting the daprd process to pick up the latest component.

Workflow Protocol - Activity Lifecycle

Mon, 01 Jan 0001 00:00:00 +0000

Activity Lifecycle

Activities are the basic units of work in a Dapr Workflow. Unlike orchestrations, activities are not replayed and do not need to be deterministic. They are executed exactly once per “schedule” (though retries may occur).

Execution Flow

Scheduling: An orchestration requests an activity by sending a ScheduleTask action to the Dapr engine.
Work Item Dispatch: The Dapr engine enqueues an activity task. When an activity worker (SDK) is available, the engine sends an ActivityWorkItem via the GetWorkItems stream.
Execution: The SDK receives the ActivityWorkItem, which contains:
- name: The name of the activity to execute.
- input: The input data for the activity.
- instance_id: The ID of the workflow instance that scheduled the activity.
- task_id: A unique identifier for this specific activity execution.
- task_execution_id: A unique identifier for the specific attempt of this activity. This is useful for implementing idempotency in activity logic.
- completion_token: An opaque token used to correlate the response with this specific work item.
Reporting: After the activity logic finishes, the SDK sends a CompleteActivityTask request back to Dapr.
- Success: The SDK provides the serialized output in the result field.
- Failure: The SDK provides failure_details (error message, type, stack trace).

Task Execution IDs

The task_execution_id (also known as the Task Execution Key) is a unique, runtime-generated string (typically a UUID) that identifies a specific attempt to execute an activity task.

Application and control plane configuration

Mon, 01 Jan 0001 00:00:00 +0000

With Dapr configurations, you use settings and policies to change:

The behavior of individual Dapr applications
The global behavior of the Dapr control plane system services

For example, set a sampling rate policy on the application sidecar configuration to indicate which methods can be called from another application. If you set a policy on the Dapr control plane configuration, you can change the certificate renewal period for all certificates that are deployed to application sidecar instances.

Configuration API reference

Mon, 01 Jan 0001 00:00:00 +0000

Get Configuration

This endpoint lets you get configuration from a store.

HTTP Request

GET http://localhost:<daprPort>/v1.0/configuration/<storename>

URL Parameters

Parameter	Description
`daprPort`	The Dapr port
`storename`	The `metadata.name` field component file. Refer to the component spec

Query Parameters

If no query parameters are provided, all configuration items are returned. To specify the keys of the configuration items to get, use one or more key query parameters. For example:

GET http://localhost:<daprPort>/v1.0/configuration/mystore?key=config1&key=config2

To retrieve all configuration items:

How to: Use the gRPC interface in your Dapr application

Mon, 01 Jan 0001 00:00:00 +0000

Dapr implements both an HTTP and a gRPC API for local calls. gRPC is useful for low-latency, high performance scenarios and has language integration using the proto clients.

Find a list of auto-generated clients in the Dapr SDK documentation.

The Dapr runtime implements a proto service that apps can communicate with via gRPC.

In addition to calling Dapr via gRPC, Dapr supports service-to-service calls with gRPC by acting as a proxy. Learn more in the gRPC service invocation how-to guide.

How-To: Enable the transactional outbox pattern

Mon, 01 Jan 0001 00:00:00 +0000

The transactional outbox pattern is a well known design pattern for sending notifications regarding changes in an application’s state. The transactional outbox pattern uses a single transaction that spans across the database and the message broker delivering the notification.

Developers are faced with many difficult technical challenges when trying to implement this pattern on their own, which often involves writing error-prone central coordination managers that, at most, support a combination of one or two databases and message brokers.

How-To: Share state between applications

Mon, 01 Jan 0001 00:00:00 +0000

Dapr provides different ways to share state between applications.

Different architectures might have different needs when it comes to sharing state. In one scenario, you may want to:

Encapsulate all state within a given application
Have Dapr manage the access for you

In a different scenario, you may need two applications working on the same state to get and save the same keys.

To enable state sharing, Dapr supports the following key prefixes strategies:

Resiliency

Mon, 01 Jan 0001 00:00:00 +0000

Distributed applications are commonly comprised of many microservices, with dozens - sometimes hundreds - of instances scaling across underlying infrastructure. As these distributed solutions grow in size and complexity, the potential for system failures inevitably increases. Service instances can fail or become unresponsive due to any number of issues, including hardware failures, unexpected throughput, or application lifecycle events, such as scaling out and application restarts. Designing and implementing a self-healing solution with the ability to detect, mitigate, and respond to failure is critical.

How-To: Scope components to one or more applications

Mon, 01 Jan 0001 00:00:00 +0000

Dapr components are namespaced (separate from the Kubernetes namespace concept), meaning a Dapr runtime instance can only access components that have been deployed to the same namespace.

When Dapr runs, it matches it’s own configured namespace with the namespace of the components that it loads and initializes only the ones matching its namespaces. All other components in a different namespace are not loaded.

Namespaces

Namespaces can be used to limit component access to particular Dapr instances.

Serialization in Dapr's SDKs

Mon, 01 Jan 0001 00:00:00 +0000

Dapr SDKs provide serialization for two use cases. First, for API objects sent through request and response payloads. Second, for objects to be persisted. For both of these cases, a default serialization method is provided in each language SDK.

Language SDK	Default Serializer
.NET	DataContracts for remoted actors, System.Text.Json otherwise. Read more about .NET serialization here
Java	DefaultObjectSerializer for JSON serialization
JavaScript	JSON

Service invocation

 using var client = (new DaprClientBuilder()).Build();
 await client.InvokeMethodAsync("myappid", "saySomething", "My Message");

 DaprClient client = (new DaprClientBuilder()).build();
 client.invokeMethod("myappid", "saySomething", "My Message", HttpExtension.POST).block();

In the example above, the app myappid receives a POST request for the saySomething method with the request payload as "My Message" - quoted since the serializer will serialize the input String to JSON.

How-To: Encrypt application state

Mon, 01 Jan 0001 00:00:00 +0000

Encrypt application state at rest to provide stronger security in enterprise workloads or regulated environments. Dapr offers automatic client-side encryption based on AES in Galois/Counter Mode (GCM), supporting keys of 128, 192, and 256-bits.

In addition to automatic encryption, Dapr supports primary and secondary encryption keys to make it easier for developers and ops teams to enable a key rotation strategy. This feature is supported by all Dapr state stores.

The encryption keys are always fetched from a secret, and cannot be supplied as plaintext values on the metadata section.

Conversation API reference

Mon, 01 Jan 0001 00:00:00 +0000

Alpha

The conversation API is currently in alpha.

Dapr provides an API to interact with Large Language Models (LLMs) and enables critical performance and security functionality with features like prompt caching, PII data obfuscation, and tool calling capabilities.

Tool calling follows OpenAI’s function calling format, making it easy to integrate with existing AI development workflows and tools.

Converse

This endpoint lets you converse with LLMs using the Alpha2 version of the API, which provides enhanced tool calling support and alignment with OpenAI’s interface.

Observability

Mon, 01 Jan 0001 00:00:00 +0000

When building an application, understanding the system behavior is an important, yet challenging part of operating it, such as:

Observing the internal calls of an application
Gauging its performance
Becoming aware of problems as soon as they occur

This can be particularly challenging for a distributed system comprised of multiple microservices, where a flow made of several calls may start in one microservice and continue in another.

Observability into your application is critical in production environments, and can be useful during development to:

How-To: Reference secrets in components

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Components can reference secrets for the spec.metadata section within the components definition.

In order to reference a secret, you need to set the auth.secretStore field to specify the name of the secret store that holds the secrets.

When running in Kubernetes, if the auth.secretStore is empty, the Kubernetes secret store is assumed.

Supported secret stores

Go to this link to see all the secret stores supported by Dapr, along with information on how to configure and use them.

Workflow Protocol - State & History

Mon, 01 Jan 0001 00:00:00 +0000

State and History Management

Dapr Workflows are event-sourced, meaning the state of a workflow is derived from a sequence of events. This document describes how Dapr stores and manages this history and state.

Backend Storage: Dapr Actors

By default, the Dapr Workflow engine uses Dapr Actors as its storage backend. Each workflow instance is mapped to a unique actor instance. This provides:

Concurrency Control: Actors ensure that only one operation is happening on a workflow instance at a time.
Reliability: Actor state is persisted in the configured Dapr State Store.
Timers: Dapr Actors provide durable reminders which are used to implement workflow timers.

Workflow State Schema

The state of a workflow instance (actor) consists of several components:

State Time-to-Live (TTL)

Mon, 01 Jan 0001 00:00:00 +0000

Dapr enables per state set request time-to-live (TTL). This means that applications can set time-to-live per state stored, and these states cannot be retrieved after expiration.

For supported state stores, you simply set the ttlInSeconds metadata when publishing a message. Other state stores will ignore this value. For some state stores, you can specify a default expiration on a per-table/container basis.

Native state TTL support

When state TTL has native support in the state store component, Dapr forwards the TTL configuration without adding any extra logic, maintaining predictable behavior. This is helpful when the expired state is handled differently by the component.

Cryptography API reference

Mon, 01 Jan 0001 00:00:00 +0000

Dapr provides cross-platform and cross-language support for encryption and decryption support via the cryptography building block. Besides the language specific SDKs, a developer can invoke these capabilities using the HTTP API endpoints below.

The HTTP APIs are intended for development and testing only. For production scenarios, the use of the SDKs is strongly recommended as they implement the gRPC APIs providing higher performance and capability than the HTTP APIs.

Encrypt Payload

This endpoint lets you encrypt a value provided as a byte array using a specified key and crypto component.

Security

Mon, 01 Jan 0001 00:00:00 +0000

Security is fundamental to Dapr. This article describes the security features and capabilities when using Dapr in a distributed application. These can be divided into:

Secure communication with service invocation and pub/sub APIs.
Security policies on components and applied through configuration.
Operational security practices.
State security, focusing on data at rest.

An example application is used to illustrate many of the security features available in Dapr.

Secure communication

Dapr provides end-to-end security with the service invocation API, with the ability to authenticate an application with Dapr and set endpoint access policies. This is shown in the diagram below.

State stores components

Mon, 01 Jan 0001 00:00:00 +0000

Dapr integrates with existing databases to provide apps with state management capabilities for CRUD operations, transactions and more. It also supports the configuration of multiple, named, state store components per application.

State stores are extensible and can be found in the components-contrib repo.

A state store in Dapr is described using a Component file:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: statestore
spec:
 type: state.<DATABASE>
 version: v1
 metadata:
 - name: <KEY>
 value: <VALUE>
 - name: <KEY>
 value: <VALUE>
...

The type of database is determined by the type field, and things like connection strings and other metadata are put in the .metadata section. Even though metadata values can contain secrets in plain text, it is recommended you use a secret store.

Workflow Protocol - Versioning

Mon, 01 Jan 0001 00:00:00 +0000

Workflow Versioning

Dapr Workflow supports versioning of workflow definitions, allowing you to update workflow logic while existing instances continue to run on their original logic.

Named Workflow Versioning

When registering a workflow with the Dapr engine, you can provide a version name. This allows multiple versions of the same workflow to coexist.

Default Version: One version of a workflow can be marked as the default. If a client starts a workflow by name without specifying a version, the default version is used.
Specific Version: Clients can request a specific version of a workflow when starting a new instance.

Registration API

SDKs register versioned workflows using the AddVersionedOrchestrator (or similar) method in their task registry.

Distributed lock API reference

Mon, 01 Jan 0001 00:00:00 +0000

Lock

This endpoint lets you acquire a lock by supplying a named lock owner and the resource ID to lock.

HTTP Request

POST http://localhost:<daprPort>/v1.0-alpha1/lock/<storename>

URL Parameters

Parameter	Description
`daprPort`	The Dapr port
`storename`	The `metadata.name` field component file. Refer to the component schema

Query Parameters

None

HTTP Response codes

Code	Description
200	Request successful
204	Empty Response
400	Malformed request
500	Request failed

HTTP Request Body

The lock endpoint receives the following JSON payload:

Isolation

Mon, 01 Jan 0001 00:00:00 +0000

Dapr namespacing provides isolation and multi-tenancy across many capabilities, giving greater security. Typically applications and components are deployed to namespaces to provide isolation in a given environment, such as Kubernetes.

Dapr supports namespacing in service invocation calls between applications, when accessing components, sending pub/sub messages in consumer groups, and with actors type deployments as examples. Namespacing isolation is supported in both self-hosted and Kubernetes modes.

To get started, create and configure your namespace.

Health API reference

Mon, 01 Jan 0001 00:00:00 +0000

Dapr provides health checking probes that can be used as readiness or liveness of Dapr and for initialization readiness from SDKs.

Get Dapr health state

Gets the health state for Dapr by either:

Check for sidecar health
Check for the sidecar health, including component readiness, used during initialization.

Wait for Dapr HTTP port to become available

Wait for all components to be initialized, the Dapr HTTP port to be available and the app channel is initialized. For example, this endpoint is used with Kubernetes liveness probes.

Secret store components

Mon, 01 Jan 0001 00:00:00 +0000

Dapr integrates with secret stores to provide apps and other components with secure storage and access to secrets such as access keys and passwords. Each secret store component has a name and this name is used when accessing a secret.

As with other building block components, secret store components are extensible and can be found in the components-contrib repo.

A secret store in Dapr is described using a Component file with the following fields:

Bindings components

Mon, 01 Jan 0001 00:00:00 +0000

Dapr integrates with external resources to allow apps to both be triggered by external events and interact with the resources. Each binding component has a name and this name is used when interacting with the resource.

As with other building block components, binding components are extensible and can be found in the components-contrib repo.

A binding in Dapr is described using a Component file with the following fields:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
 namespace: <NAMESPACE>
spec:
 type: bindings.<NAME>
 version: v1
 metadata:
 - name: <KEY>
 value: <VALUE>
 - name: <KEY>
 value: <VALUE>
...

The type of binding is determined by the type field, and things like connection strings and other metadata are put in the .metadata section.

Jobs API reference

Mon, 01 Jan 0001 00:00:00 +0000

Note

The jobs API is currently in alpha.

With the jobs API, you can schedule jobs and tasks in the future.

The HTTP APIs are intended for development and testing only. For production scenarios, the use of the SDKs is strongly recommended as they implement the gRPC APIs providing higher performance and capability than the HTTP APIs. This is because HTTP does JSON marshalling which can be expensive, while with gRPC, the data is transmitted over the wire and stored as-is being more performant.

Using OpenTelemetry Collector to collect traces

Mon, 01 Jan 0001 00:00:00 +0000

Dapr directly writes traces using the OpenTelemetry (OTLP) protocol as the recommended method. For observability tools that support the OTLP directly, it is recommended to use the OpenTelemetry Collector, as it allows your application to quickly offload data and includes features, such as retries, batching, and encryption. For more information, read the Open Telemetry Collector documentation.

Dapr can also write traces using the Zipkin protocol. Prior to supporting the OTLP protocol, the Zipkin protocol was used with the OpenTelemetry Collector to send traces to observability tools such as AWS X-Ray, Google Cloud Operations Suite, and Azure Monitor. Both protocol approaches are valid, however the OpenTelemetry protocol is the recommended choice.

Application Environment of a .NET Dapr pluggable component

Mon, 01 Jan 0001 00:00:00 +0000

A .NET Dapr pluggable component application can be configured for dependency injection, logging, and configuration values similarly to ASP.NET applications. The DaprPluggableComponentsApplication exposes a similar set of configuration properties to that exposed by WebApplicationBuilder.

Dependency injection

Components registered with services can participate in dependency injection. Arguments in the components constructor will be injected during creation, assuming those types have been registered with the application. You can register them through the IServiceCollection exposed by DaprPluggableComponentsApplication.

Azure Cosmos DB

Mon, 01 Jan 0001 00:00:00 +0000

Dapr doesn’t transform state values while saving and retrieving states. Dapr requires all state store implementations to abide by a certain key format scheme (see the state management spec. You can directly interact with the underlying store to manipulate the state data, such as:

Querying states.
Creating aggregated views.
Making backups.

Note

Azure Cosmos DB is a multi-modal database that supports multiple APIs. The default Dapr Cosmos DB state store implementation uses the Azure Cosmos DB SQL API.

Connect to Azure Cosmos DB

To connect to your Cosmos DB instance, you can either:

Common issues when running Dapr

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers common issues you may encounter while installing and running Dapr.

Dapr can’t connect to Docker when installing the Dapr CLI

When installing and initializing the Dapr CLI, if you see the following error message after running dapr init:

⌛ Making the jump to hyperspace...
❌ could not connect to docker. docker may not be installed or running

Troubleshoot the error by ensuring:

The correct containers are running.

Component spec

Mon, 01 Jan 0001 00:00:00 +0000

Dapr defines and registers components using a resource specifications. All components are defined as a resource and can be applied to any hosting environment where Dapr is running, not just Kubernetes.

Typically, components are restricted to a particular namespace and restricted access through scopes to any particular set of applications. The namespace is either explicit on the component manifest itself, or set by the API server, which derives the namespace through context with applying to Kubernetes.

Lifetimes of .NET Dapr pluggable components

Mon, 01 Jan 0001 00:00:00 +0000

There are two ways to register a component:

The component operates as a singleton, with lifetime managed by the SDK
A component’s lifetime is determined by the pluggable component and can be multi-instance or a singleton, as needed

Singleton components

Components registered by type are singletons: one instance will serve all configured components of that type associated with that socket. This approach is best when only a single component of that type exists and is shared amongst Dapr applications.

Custom Serialization

Mon, 01 Jan 0001 00:00:00 +0000

Dapr uses JSON serialization and thus (complex) type information is lost when sending/receiving data.

Serialization

When returning an object from a controller, passing an object to the DaprClient, or storing an object in a state store, only public properties are scanned and serialized. You can customize this behavior by implementing \Dapr\Serialization\ISerialize. For example, if you wanted to create an ID type that serialized to a string, you may implement it like so:

Debug Dapr control plane on Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Sometimes it is necessary to understand what’s going on in Dapr control plane (aka, Kubernetes services), including dapr-sidecar-injector, dapr-operator, dapr-placement, and dapr-sentry, especially when you diagnose your Dapr application and wonder if there’s something wrong in Dapr itself. Additionally, you may be developing a new feature for Dapr on Kubernetes and want to debug your code.

This guide will cover how to use Dapr debugging binaries to debug the Dapr services on your Kubernetes cluster.

DaprWorkflowClient lifetime management and registration

Mon, 01 Jan 0001 00:00:00 +0000

Lifetime management

A DaprWorkflowClient holds access to networking resources in the form of TCP sockets used to communicate with the Dapr sidecar as well as other types used in the management and operation of Workflows. DaprWorkflowClient implements IAsyncDisposable to support eager cleanup of resources.

Dependency Injection

The AddDaprWorkflow() method will register the Dapr workflow services with ASP.NET Core dependency injection. This method requires an options delegate that defines each of the workflows and activities you wish to register and use in your application.

Metadata API reference

Mon, 01 Jan 0001 00:00:00 +0000

Dapr has a metadata API that returns information about the sidecar allowing runtime discoverability. The metadata endpoint returns the following information.

Runtime version
List of the loaded resources (components, subscriptions and HttpEndpoints)
Registered actor types
Features enabled
Application connection details
Custom, ephemeral attributes with information.

Metadata API

Components

Each loaded component provides its name, type and version and also information about supported features in the form of component capabilities. These features are available for the state store and binding component types. The table below shows the component type and the list of capabilities for a given version. This list might grow in future and only represents the capabilities of the loaded components.

Set up a Minikube cluster

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Install:
- Docker
- kubectl
- Minikube
For Windows:
- Enable Virtualization in BIOS
- Install Hyper-V

Note

See the official Minikube documentation on drivers for details on supported drivers and how to install plugins.

Start the Minikube cluster

If applicable for your project, set the default VM.
```
minikube config set vm-driver [driver_name]
```
Start the cluster. If necessary, specify version 1.13.x or newer of Kubernetes with --kubernetes-version
```
minikube start --cpus=4 --memory=4096
```
Enable the Minikube dashboard and ingress add-ons.

mtls export CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

Export the root Certificate Authority (CA), issuer cert and issuer key to local files

Supported platforms

Kubernetes

Usage

dapr mtls export [flags]

Flags

Name	Environment Variable	Default	Description
`--help`, `-h`			help for export
`--out`, `-o`		current directory	The output directory path to save the certs

Examples

# Check expiry of Kubernetes certs
dapr mtls export -o ./certs

Warning messages

This command can issue warning messages.

Root certificate renewal warning

If the mtls root certificate deployed to the Kubernetes cluster expires in under 30 days the following warning message is displayed:

Multi-App Run overview

Mon, 01 Jan 0001 00:00:00 +0000

Note

Multi-App Run for Kubernetes is currently a preview feature.

Let’s say you want to run several applications locally to test them together, similar to a production scenario. Multi-App Run allows you to start and stop a set of applications simultaneously, either:

Locally/self-hosted with processes, or
By building container images and deploying to a Kubernetes cluster
- You can use a local Kubernetes cluster (KiND) or one deploy to a Cloud (AKS, EKS, and GKE).

The Multi-App Run template file describes how to start multiple applications as if you had run many separate CLI run commands. By default, this template file is called dapr.yaml.

Multiple services in a .NET Dapr pluggable component

Mon, 01 Jan 0001 00:00:00 +0000

A pluggable component can host multiple components of varying types. You might do this:

To minimize the number of sidecars running in a cluster
To group related components that are likely to share libraries and implementation, such as:
- A database exposed both as a general state store, and
- Output bindings that allow more specific operations.

Each Unix Domain Socket can manage calls to one component of each type. To host multiple components of the same type, you can spread those types across multiple sockets. The SDK binds each socket to a “service”, with each service composed of one or more component types.

Configuration overview

Mon, 01 Jan 0001 00:00:00 +0000

Consuming application configuration is a common task when writing applications. Frequently, configuration stores are used to manage this configuration data. A configuration item is often dynamic in nature and tightly coupled to the needs of the application that consumes it.

For example, application configuration can include:

Names of secrets
Different identifiers
Partition or consumer IDs
Names of databases to connect to, etc

Usually, configuration items are stored as key/value items in a state store or database. Developers or operators can change application configuration at runtime in the configuration store. Once changes are made, a service is notified to load the new configuration.

Conversation overview

Mon, 01 Jan 0001 00:00:00 +0000

Alpha

The conversation API is currently in alpha.

Dapr’s conversation API reduces the complexity of securely and reliably interacting with Large Language Models (LLM) at scale. Whether you’re a developer who doesn’t have the necessary native SDKs or a polyglot shop who just wants to focus on the prompt aspects of LLM interactions, the conversation API provides one consistent API entry point to talk to underlying LLM providers.

In addition to enabling critical performance and security functionality (like caching and PII scrubbing), the conversation API also provides:

Cryptography overview

Mon, 01 Jan 0001 00:00:00 +0000

With the cryptography building block, you can leverage cryptography in a safe and consistent way. Dapr exposes APIs that allow you to perform operations, such as encrypting and decrypting messages, within key vaults or the Dapr sidecar, without exposing cryptographic keys to your application.

Why Cryptography?

Applications make extensive use of cryptography, which, when implemented correctly, can make solutions safer even when data is compromised. In certain cases, you may be required to use cryptography to comply with industry regulations (for example, in finance) or legal requirements (including privacy regulations such as GDPR).

Distributed lock overview

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

Locks are used to provide mutually exclusive access to a resource. For example, you can use a lock to:

Provide exclusive access to a database row, table, or an entire database
Lock reading messages from a queue in a sequential manner

Any resource that is shared where updates occur can be the target for a lock. Locks are usually used on operations that mutate state, not on reads.

Each lock has a name. The application determines the resources that the named lock accesses. Typically, multiple instances of the same application use this named lock to exclusively access the resource and perform updates.

Jobs overview

Mon, 01 Jan 0001 00:00:00 +0000

Many applications require job scheduling, or the need to take an action in the future. The jobs API is an orchestrator for scheduling these future jobs, either at a specific time or for a specific interval.

Not only does the jobs API help you with scheduling jobs, but internally, Dapr uses the Scheduler service to schedule actor reminders.

Jobs in Dapr consist of:

See example scenarios.

Publish and subscribe overview

Mon, 01 Jan 0001 00:00:00 +0000

Publish and subscribe (pub/sub) enables microservices to communicate with each other using messages for event-driven architectures.

The producer, or publisher, writes messages to an input channel and sends them to a topic, unaware which application will receive them.
The consumer, or subscriber, subscribes to the topic and receives messages from an output channel, unaware which service produced these messages.

An intermediary message broker copies each message from a publisher’s input channel to an output channel for all subscribers interested in that message. This pattern is especially useful when you need to decouple microservices from one another.

Secrets management overview

Mon, 01 Jan 0001 00:00:00 +0000

Applications usually store sensitive information in secrets by using a dedicated secret store. For example, you authenticate databases, services, and external systems with connection strings, keys, tokens, and other application-level secrets stored in a secret store, such as AWS Secrets Manager, Azure Key Vault, Hashicorp Vault, etc.

To access these secret stores, the application imports the secret store SDK, often requiring a fair amount of unrelated boilerplate code. This poses an even greater challenge in multi-cloud scenarios, where different vendor-specific secret stores may be used.

Workflow overview

Mon, 01 Jan 0001 00:00:00 +0000

Dapr workflow makes it easy for developers to write business logic and integrations in a reliable way. Since Dapr workflows are stateful, they support long-running and fault-tolerant applications, ideal for orchestrating microservices. Dapr workflow works seamlessly with other Dapr building blocks, such as service invocation, pub/sub, state management, and bindings.

The durable, resilient Dapr Workflow capability:

Offers a built-in workflow runtime for driving Dapr Workflow execution.
Provides SDKs for authoring workflows in code, using any language.
Provides HTTP and gRPC APIs for managing workflows (start, query, pause/resume, raise event, terminate, purge).

Some example scenarios that Dapr Workflow can perform are:

Pluggable components overview

Mon, 01 Jan 0001 00:00:00 +0000

Pluggable components are components that are not included as part the runtime, as opposed to the built-in components included with dapr init. You can configure Dapr to use pluggable components that leverage the building block APIs, but are registered differently from the built-in Dapr components.

Pluggable components vs. built-in components

Dapr provides two approaches for registering and creating components:

The built-in components included in the runtime and found in the components-contrib repository .
Pluggable components which are deployed and registered independently.

While both registration options leverage Dapr’s building block APIs, each has a different implementation processes.

Logs

Mon, 01 Jan 0001 00:00:00 +0000

Dapr produces structured logs to stdout, either in plain-text or JSON-formatted. By default, all Dapr processes (runtime, or sidecar, and all control plane services) write logs to the console (stdout) in plain-text. To enable JSON-formatted logging, you need to add the --log-as-json command flag when running Dapr processes.

Note

If you want to use a search engine such as Elastic Search or Azure Monitor to search the logs, it is strongly recommended to use JSON-formatted logs which the log collector and search engine can parse using the built-in JSON parser.

Log schema

Dapr produces logs based on the following schema:

Production Reference: Actors

Mon, 01 Jan 0001 00:00:00 +0000

Proxy modes

There are four different modes actor proxies are handled. Each mode presents different trade-offs that you’ll need to weigh during development and in production.

<?php
\Dapr\Actors\Generators\ProxyFactory::GENERATED;
\Dapr\Actors\Generators\ProxyFactory::GENERATED_CACHED;
\Dapr\Actors\Generators\ProxyFactory::ONLY_EXISTING;
\Dapr\Actors\Generators\ProxyFactory::DYNAMIC;

It can be set with dapr.actors.proxy.generation configuration key.

This is the default mode. In this mode, a class is generated and eval’d on every request. It’s mostly for development and shouldn’t be used in production.

How-To: Register a pluggable component

Mon, 01 Jan 0001 00:00:00 +0000

Component registration process

Pluggable, gRPC-based components are typically run as containers or processes that need to communicate with the Dapr runtime via Unix Domain Sockets (or UDS for short). They are automatically discovered and registered in the runtime with the following steps:

The component listens to an Unix Domain Socket placed on the shared volume.
The Dapr runtime lists all Unix Domain Socket in the shared volume.
The Dapr runtime connects with each socket and uses gRPC reflection to discover all proto services from a given building block API that the component implements.

A single component can implement multiple component interfaces at once.

Setup & configure mTLS certificates

Mon, 01 Jan 0001 00:00:00 +0000

Dapr supports in-transit encryption of communication between Dapr instances using the Dapr control plane, Sentry service, which is a central Certificate Authority (CA).

Dapr allows operators and developers to bring in their own certificates, or instead let Dapr automatically create and persist self-signed root and issuer certificates.

For detailed information on mTLS, read the security concepts section.

Workload identity key algorithm (Ed25519, Dapr 1.18+)

Starting with Dapr 1.18, Sentry generates workload identity keys using Ed25519 instead of ECDSA P-256. On a normal install or upgrade this is transparent — no configuration change is needed.

Dapr terminology and definitions

Mon, 01 Jan 0001 00:00:00 +0000

This page details all of the common terms you may come across in the Dapr docs.

Term	Definition	More information
App/Application	A running service/binary, usually one that you as the user create and run.
Building block	An API that Dapr provides to users to help in the creation of microservices and applications.	Dapr building blocks
Component	Modular types of functionality that are used either individually or with a collection of other components, by a Dapr building block.	Dapr components
Configuration	A YAML file declaring all of the settings for Dapr sidecars or the Dapr control plane. This is where you can configure control plane mTLS settings, or the tracing and middleware settings for an application instance.	Dapr configuration
Dapr	Distributed Application Runtime.	Dapr overview
Dapr Actors	A Dapr building block that implements the virtual actor pattern for building stateful, single-threaded objects with identity, lifecycle, and concurrency management.	Actors overview
Dapr Agents	A developer framework built on top of Dapr Python SDK for creating durable agentic applications powered by LLMs.	Dapr Agents
Dapr control plane	A collection of services that are part of a Dapr installation on a hosting platform such as a Kubernetes cluster. This allows Dapr-enabled applications to run on the platform and handles Dapr capabilities such as actor placement, Dapr sidecar injection, or certificate issuance/rollover.	Self-hosted overview Kubernetes overview
Dapr Workflows	A Dapr building block for authoring code-first workflows with durable execution that survive crashes, support long-running processes, and enable human-in-the-loop interactions.	Workflow overview
HTTPEndpoint	HTTPEndpoint is a Dapr resource use to identify non-Dapr endpoints to invoke via the service invocation API.	Service invocation API
Namespacing	Namespacing in Dapr provides isolation, and thus provides multi-tenancy.	Learn more about namespacing components, service invocation, pub/sub, and actors
Self-hosted	Windows/macOS/Linux machine(s) where you can run your applications with Dapr. Dapr provides the capability to run on machines in “self-hosted” mode.	Self-hosted mode
Service	A running application or binary. This can refer to your application or to a Dapr application.
Sidecar	A program that runs alongside your application as a separate process or container.	Sidecar pattern

Unit Testing

Mon, 01 Jan 0001 00:00:00 +0000

Unit and integration tests are first-class citizens with the PHP SDK. Using the DI container, mocks, stubs, and the provided \Dapr\Mocks\TestClient allows you to have very fine-grained tests.

Testing Actors

With actors, there are two things we’re interested in while the actor is under test:

The returned result based on an initial state
The resulting state based on the initial state

Here’s an example test a very simple actor that updates its state and returns a specific value:

Using Dynatrace OpenTelemetry Collector to collect traces to send to Dynatrace

Mon, 01 Jan 0001 00:00:00 +0000

Dapr integrates with the Dynatrace Collector using the OpenTelemetry protocol (OTLP). This guide walks through an example using Dapr to push traces to Dynatrace, using the Dynatrace version of the OpenTelemetry Collector.

Note

This guide refers to the Dynatrace OpenTelemetry Collector, which uses the same Helm chart as the open-source collector but overridden with the Dynatrace-maintained image for better support and Dynatrace-specific features.

Prerequisites

Install Dapr on Kubernetes
Access to a Dynatrace tenant and an API token with openTelemetryTrace.ingest, metrics.ingest, and logs.ingest scopes
Helm

Set up Dynatrace OpenTelemetry Collector to push to your Dynatrace instance

To push traces to your Dynatrace instance, install the Dynatrace OpenTelemetry Collector on your Kubernetes cluster.

Using OpenTelemetry Collector to collect traces to send to App Insights

Mon, 01 Jan 0001 00:00:00 +0000

Dapr integrates with OpenTelemetry (OTEL) Collector using the OpenTelemetry protocol (OTLP). This guide walks through an example using Dapr to push traces to Azure Application Insights, using the OpenTelemetry Collector.

Prerequisites

Install Dapr on Kubernetes
Create an Application Insights resource and make note of your Application Insights connection string.

Set up OTEL Collector to push to your App Insights instance

To push traces to your Application Insights instance, install the OpenTelemetry Collector on your Kubernetes cluster.

Versioning policy

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

Dapr is designed for future changes in the runtime, APIs and components with versioning schemes. This topic describes the versioning schemes and strategies for APIs, manifests such as components and Github repositories.

Versioning

Versioning is the process of assigning either unique version names or unique version numbers to unique states of computer software.

Versioning provides compatibility, explicit change control and handling changes, in particular breaking changes.
Dapr strives to be backwards compatible. If a breaking change is needed it’ll be announced in advance.
Deprecated features are done over multiple releases with both new and deprecated features working side-by-side.

Versioning refers to the following Dapr repos: dapr, CLI, stable language SDKs, dashboard, components-contrib, quickstarts, helm-charts and documentation.

How to: Implement pluggable components

Mon, 01 Jan 0001 00:00:00 +0000

In this guide, you’ll learn why and how to implement a pluggable component. To learn how to configure and register a pluggable component, refer to How to: Register a pluggable component

Implement a pluggable component

In order to implement a pluggable component, you need to implement a gRPC service in the component. Implementing the gRPC service requires three steps:

Find the proto definition file

Proto definitions are provided for each supported service interface (state store, pub/sub, bindings, secret stores).

Set up a KiND cluster

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Install:
- Docker
- kubectl
For Windows:
- Enable Virtualization in BIOS
- Install Hyper-V

Install and configure KiND

Refer to the KiND documentation to install.

If you are using Docker Desktop, verify that you have the recommended settings.

Configure and create the KiND cluster

Create a file named kind-cluster-config.yaml, and paste the following:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
 kubeadmConfigPatches:
 - |
 kind: InitConfiguration
 nodeRegistration:
 kubeletExtraArgs:
 node-labels: "ingress-ready=true"
 extraPortMappings:
 - containerPort: 80
 hostPort: 8081
 protocol: TCP
 - containerPort: 443
 hostPort: 8443
 protocol: TCP
- role: worker
- role: worker

This cluster configuration:

Placement API reference

Mon, 01 Jan 0001 00:00:00 +0000

Dapr has an HTTP API /placement/state for Placement service that exposes placement table information. The API is exposed on the sidecar on the same port as the healthz. This is an unauthenticated endpoint, and is disabled by default.

To enable the placement metadata in self-hosted mode you can either setDAPR_PLACEMENT_METADATA_ENABLED environment variable or metadata-enabled command line args on the Placement service to true to. See how to run the Placement service in self-hosted mode.

Shutdown API reference

Mon, 01 Jan 0001 00:00:00 +0000

The Shutdown API triggers a graceful shutdown of the Dapr sidecar (daprd). It is the same shutdown path that runs when daprd receives a SIGTERM: input bindings and pub/sub subscriptions are closed, in-flight requests are allowed to complete (subject to --dapr-graceful-shutdown-seconds), reminders and components are flushed, and then the process exits.

The API has two modes:

Graceful (default): triggers the normal shutdown sequence and returns.
Force: skips the graceful sequence and exits the process via os.Exit(1) after a short delay so the HTTP/gRPC response can flush. Intended for stuck sidecars where draining is not making progress.

HTTP request

POST http://localhost:<daprPort>/v1.0/shutdown

URL parameters

This endpoint takes no path or query parameters.

Pub/sub API reference

Mon, 01 Jan 0001 00:00:00 +0000

Publish a message to a given topic

This endpoint lets you publish data to multiple consumers who are listening on a topic. Dapr guarantees At-Least-Once semantics for this endpoint.

HTTP Request

POST http://localhost:<daprPort>/v1.0/publish/<pubsubname>/<topic>[?<metadata>]

HTTP Response codes

Code	Description
204	Message delivered
403	Message forbidden by access controls
404	No pubsub name or topic given
500	Delivery failed

URL Parameters

Parameter	Description
`daprPort`	The Dapr port
`pubsubname`	The name of pubsub component
`topic`	The name of the topic
`metadata`	Query parameters for metadata as described below

Note, all URL parameters are case-sensitive.

Using OpenTelemetry to send traces to Jaeger V2

Mon, 01 Jan 0001 00:00:00 +0000

Dapr supports writing traces using the OpenTelemetry (OTLP) protocol, and Jaeger V2 natively supports OTLP, allowing Dapr to send traces directly to a Jaeger V2 instance. This approach is recommended for production to leverage Jaeger V2’s capabilities for distributed tracing.

Configure Jaeger V2 in self-hosted mode

Local setup

The simplest way to start Jaeger is to run the pre-built, all-in-one Jaeger image published to DockerHub and expose the OTLP port:

Secrets API reference

Mon, 01 Jan 0001 00:00:00 +0000

Get Secret

This endpoint lets you get the value of a secret for a given secret store.

HTTP Request

GET http://localhost:<daprPort>/v1.0/secrets/<secret-store-name>/<name>

URL Parameters

Parameter	Description
daprPort	the Dapr port
secret-store-name	the name of the secret store to get the secret from
name	the name of the secret to get

Note, all URL parameters are case-sensitive.

Query Parameters

Some secret stores support optional, per-request metadata properties. Use query parameters to provide those properties. For example:

Service invocation API reference

Mon, 01 Jan 0001 00:00:00 +0000

Dapr provides users with the ability to call other applications that are using Dapr with a unique named identifier (appId), or HTTP endpoints that are not using Dapr. This allows applications to interact with one another via named identifiers and puts the burden of service discovery on the Dapr runtime.

Invoke a method on a remote Dapr app

This endpoint lets you invoke a method in another Dapr enabled app.

State management API reference

Mon, 01 Jan 0001 00:00:00 +0000

Component file

A Dapr statestore.yaml component file has the following structure:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
 namespace: <NAMESPACE>
spec:
 type: state.<TYPE>
 version: v1
 metadata:
 - name:<KEY>
 value:<VALUE>
 - name: <KEY>
 value: <VALUE>

Setting	Description
`metadata.name`	The name of the state store.
`spec/metadata`	An open key value pair metadata that allows a binding to define connection properties.

Key scheme

Dapr state stores are key/value stores. To ensure data compatibility, Dapr requires these data stores follow a fixed key scheme. For general states, the key format is:

Workflow serialization in the .NET SDK

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Starting with Dapr .NET SDK v1.17.0, Dapr.Workflow supports pluggable serialization. The SDK continues to use System.Text.Json by default, but you can now:

Override the default System.Text.Json settings.
Register a custom serializer (for example, MessagePack or BSON).

Serialization configuration is entirely client-side and does not require a specific Dapr runtime version.

Note

This feature requires Dapr .NET SDK v1.17.0 or later.

Compatibility and breaking changes

Warning

Changing serialization can be a breaking change for existing workflows. There is no supported migration path between serialization implementations.

Multi-application workflows in the .NET SDK

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Dapr workflows can call activities or child workflows that are hosted in a different Dapr application. In .NET, multi-application workflows are supported starting with:

Dapr runtime v1.16.0+
Dapr .NET SDK v1.17.0+

Conceptual guidance and constraints are covered in Multi Application Workflows.

Requirements

Multi-application workflow calls require:

The target app ID must exist and must register the activity or workflow you invoke.
All participating app IDs must be in the same namespace.
All participating app IDs must use the same workflow (actor) state store.

Call an activity in another application

Set TargetAppId on WorkflowTaskOptions when calling an activity to execute it in another app:

Workflow API reference

Mon, 01 Jan 0001 00:00:00 +0000

Dapr provides users with the ability to interact with workflows through its built-in workflow engine, which is implemented using Dapr Actors.

To interact with the workflow engine, see [how to author]https://v1-18.docs.dapr.io/developing-applications/building-blocks/workflow/howto-author-workflow/ and manage workflows.

HTTP API reference (Deprecated)

Below is the reference for the Dapr Workflow API. This API is deprecated and will eventually be removed.

Start workflow request

Start a workflow instance with the given name and optionally, an instance ID.

Dapr integration policies for Azure API Management

Mon, 01 Jan 0001 00:00:00 +0000

Azure API Management is a way to create consistent and modern API gateways for back-end services, including those built with Dapr. You can enable Dapr support in self-hosted API Management gateways to allow them to:

Forward requests to Dapr services
Send messages to Dapr Pub/Sub topics
Trigger Dapr output bindings

Try out the Dapr & Azure API Management Integration sample.

Learn more about Dapr integration policies

Set up an Azure Kubernetes Service (AKS) cluster

Mon, 01 Jan 0001 00:00:00 +0000

This guide walks you through installing an Azure Kubernetes Service (AKS) cluster. If you need more information, refer to Quickstart: Deploy an AKS cluster using the Azure CLI

Prerequisites

Install:
- Docker
- kubectl
- Azure CLI

Deploy an AKS cluster

In the terminal, log into Azure.
```
az login
```

Set your default subscription:

az account set -s [your_subscription_id]

Create a resource group.

az group create --name [your_resource_group] --location [region]

Create an AKS cluster. To use a specific version of Kubernetes, use --kubernetes-version (1.13.x or newer version required).

How-To: Control concurrency and rate limit applications

Mon, 01 Jan 0001 00:00:00 +0000

Typically, in distributed computing, you may only want to allow for a given number of requests to execute concurrently. Using Dapr’s app-max-concurrency, you can control how many requests and events can invoke your application simultaneously.

Default app-max-concurrency is set to -1, meaning no concurrency limit is enforced.

Different approaches

Dapr provides several approaches to concurrency and rate limiting. It’s important to understand the differences:

Approach	What it controls	Scope
`app-max-concurrency`	Max concurrent requests and events to an app	Per-sidecar
`middleware.http.ratelimit`	HTTP requests per second by remote IP	Per-sidecar
Workflow concurrency limits	Workflow and activity executions, with per-name granularity	Per-sidecar or global (across all replicas)

This guide focuses on app-max-concurrency. See Rate limit middleware and Workflow Concurrency Limits for the other approaches.

Configure endpoint authorization with OAuth

Mon, 01 Jan 0001 00:00:00 +0000

Dapr OAuth 2.0 middleware allows you to enable OAuth authorization on Dapr endpoints for your web APIs using the Authorization Code Grant flow. You can also inject authorization tokens into your endpoint APIs which can be used for authorization towards external APIs called by your APIs using the Client Credentials Grant flow. When the middleware is enabled any method invocation through Dapr needs to be authorized before getting passed to the user code.

The main difference between the two flows is that the Authorization Code Grant flow needs user interaction and authorizes a user where the Client Credentials Grant flow doesn’t need a user interaction and authorizes a service/application.

Configure middleware components

Mon, 01 Jan 0001 00:00:00 +0000

Dapr allows custom processing pipelines to be defined by chaining a series of middleware components. There are two places that you can use a middleware pipeline:

Building block APIs - HTTP middleware components are executed when invoking any Dapr HTTP APIs.
Service-to-Service invocation - HTTP middleware components are applied to service-to-service invocation calls.

Configure API middleware pipelines

When launched, a Dapr sidecar constructs a middleware processing pipeline for incoming HTTP calls. By default, the pipeline consists of the tracing and CORS middlewares. Additional middlewares, configured by a Dapr Configuration, can be added to the pipeline in the order they are defined. The pipeline applies to all Dapr API endpoints, including state, pub/sub, service invocation, bindings, secrets, configuration, distributed lock, etc.

Debug daprd on Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Sometimes it is necessary to understand what’s going on in the Dapr sidecar (daprd), which runs as a sidecar next to your application, especially when you diagnose your Dapr application and wonder if there’s something wrong in Dapr itself. Additionally, you may be developing a new feature for Dapr on Kubernetes and want to debug your code.

This guide covers how to use built-in Dapr debugging to debug the Dapr sidecar in your Kubernetes pods. To learn how to view logs and troubleshoot Dapr in Kubernetes, see the Configure and view Dapr logs guide

Conductor: Enterprise Dapr for Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

Diagrid Conductor quickly and securely connects to all your Kubernetes clusters running Dapr and Daprized applications, delivering operational excellence, security & reliability and insights & collaboration.

Automated Dapr management

One-click installation, upgrade and patching of Dapr with selective application update and automated rollback means you’re always up to date.

Advisor: Discover and automate best practices

Be informed and apply production best practices, with continuous checking to prevent misconfigurations, increasing security, reliability and performance.

Features and concepts

Mon, 01 Jan 0001 00:00:00 +0000

Now that you’ve learned about the jobs building block at a high level, let’s deep dive into the features and concepts included with Dapr Jobs and the various SDKs. Dapr Jobs:

Provides a robust and scalable API for scheduling operations to be triggered in the future.
Exposes several capabilities which are common across all supported languages.
Supports sub-second precision when using duration values (for example 500ms). Actual trigger resolution may vary by runtime; Cron-based schedules are at the seconds level only.

Job identity

All jobs are registered with a case-sensitive job name. These names are intended to be unique across all services interfacing with the Dapr runtime. The name is used as an identifier when creating and modifying the job as well as to indicate which job a triggered invocation is associated with.

Features and concepts

Mon, 01 Jan 0001 00:00:00 +0000

Now that you’ve learned about the workflow building block at a high level, let’s deep dive into the features and concepts included with the Dapr Workflow engine and SDKs. Dapr Workflow exposes several core features and concepts which are common across all supported languages.

Note

For more information on how workflow state is managed, see the workflow architecture guide.

Workflows

Dapr Workflows are functions you write that define a series of tasks to be executed in a particular order. The Dapr Workflow engine takes care of scheduling and execution of the tasks, including managing failures and retries. If the app hosting your workflows is scaled out across multiple machines, the workflow engine load balances the execution of workflows and their tasks across multiple machines. You can configure concurrency limits to control how many workflows and activities run simultaneously, either per-sidecar or globally across all replicas.

How-To: Set up Fluentd, Elastic search and Kibana in Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Kubernetes (> 1.14)
kubectl
Helm 3

Install Elastic search and Kibana

Create a Kubernetes namespace for monitoring tools
```
kubectl create namespace dapr-monitoring
```

Add the helm repo for Elastic Search

helm repo add elastic https://helm.elastic.co
helm repo update

Install Elastic Search using Helm

By default, the chart creates 3 replicas which must be on different nodes. If your cluster has fewer than 3 nodes, specify a smaller number of replicas. For example, this sets the number of replicas to 1:

How to: Publish a message and subscribe to a topic

Mon, 01 Jan 0001 00:00:00 +0000

Now that you’ve learned what the Dapr pub/sub building block provides, learn how it can work in your service. The below code example loosely describes an application that processes orders with two services, each with Dapr sidecars:

A checkout service using Dapr to subscribe to the topic in the message queue.
An order processing service using Dapr to publish a message to RabbitMQ.

Dapr automatically wraps the user payload in a CloudEvents v1.0 compliant envelope, using Content-Type header value for datacontenttype attribute. Learn more about messages with CloudEvents.

How To: Retrieve a secret

Mon, 01 Jan 0001 00:00:00 +0000

Now that you’ve learned what the Dapr secrets building block provides, learn how it can work in your service. This guide demonstrates how to call the secrets API and retrieve secrets in your application code from a configured secret store.

Note

If you haven’t already, try out the secrets management quickstart for a quick walk-through on how to use the secrets API.

Set up a secret store

Before retrieving secrets in your application’s code, you must configure a secret store component. This example configures a secret store that uses a local JSON file to store secrets.

How to: Use the cryptography APIs

Mon, 01 Jan 0001 00:00:00 +0000

Now that you’ve read about Cryptography as a Dapr building block, let’s walk through using the cryptography APIs with the SDKs.

Note

Dapr cryptography is currently in alpha.

Encrypt

Using the Dapr SDK in your project, with the gRPC APIs, you can encrypt a stream of data, such as a file or a string:

How to: Use the Multi-App Run template file

Mon, 01 Jan 0001 00:00:00 +0000

Note

Multi-App Run for Kubernetes is currently a preview feature.

The Multi-App Run template file is a YAML file that you can use to run multiple applications at once. In this guide, you’ll learn how to:

Use the multi-app template
View started applications
Stop the multi-app template
Structure the multi-app template file

Use the multi-app template

You can use the multi-app template file in one of the following two ways:

How-To: Converse with an LLM using the conversation API

Mon, 01 Jan 0001 00:00:00 +0000

Alpha

The conversation API is currently in alpha.

Let’s get started using the conversation API. In this guide, you’ll learn how to:

Set up one of the available Dapr components (echo) that work with the conversation API.
Add the conversation client to your application.
Run the connection using dapr run.

Set up the conversation component

Create a new configuration file called conversation.yaml and save to a components or config sub-folder in your application directory.

How-To: Manage configuration from a store

Mon, 01 Jan 0001 00:00:00 +0000

This example uses the Redis configuration store component to demonstrate how to retrieve a configuration item.

Note

If you haven’t already, try out the configuration quickstart for a quick walk-through on how to use the configuration API.

Disabling configuration initialization endpoint

If your application does not use the configuration building block, the automatic HTTP call to the /dapr/config endpoint during initialization can be disabled to reduce log noise. Use the --disable-init-endpoints config flag with dapr run, or the dapr.io/disable-init-endpoints: "config" annotation in Kubernetes. Learn more about disabling initialization endpoints.

Create a configuration item in store

Create a configuration item in a supported configuration store. This can be a simple key-value item, with any key of your choice. As mentioned earlier, this example uses the Redis configuration store component.

How-To: Use a lock

Mon, 01 Jan 0001 00:00:00 +0000

Now that you’ve learned what the Dapr distributed lock API building block provides, learn how it can work in your service. In this guide, an example application acquires a lock using the Redis lock component to demonstrate how to lock resources. For a list of supported lock stores, see this reference page.

In the diagram below, two instances of the same application acquire a lock, where one instance is successful and the other is denied.

IntelliJ

Mon, 01 Jan 0001 00:00:00 +0000

When developing Dapr applications, you typically use the Dapr CLI to start your ‘Daprized’ service similar to this:

dapr run --app-id nodeapp --app-port 3000 --dapr-http-port 3500 app.js

This uses the default components yaml files (created on dapr init) so that your service can interact with the local Redis container. This is great when you are just getting started but what if you want to attach a debugger to your service and step through the code? This is where you can use the dapr cli without invoking an app.

Configure and view Dapr Logs

Mon, 01 Jan 0001 00:00:00 +0000

This section will assist you in understanding how logging works in Dapr, configuring and viewing logs.

Overview

Logs have different, configurable verbosity levels. The levels outlined below are the same for both system components and the Dapr sidecar process/container:

error
warn
info
debug

error produces the minimum amount of output, where debug produces the maximum amount. The default level is info, which provides a balanced amount of information for operating Dapr in normal conditions.

mtls expiry CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

Checks the expiry of the root Certificate Authority (CA) certificate

Supported platforms

Kubernetes

Usage

dapr mtls expiry [flags]

Flags

Name	Environment Variable	Default	Description
`--help`, `-h`			help for expiry

Examples

# Check expiry of Kubernetes certs
dapr mtls expiry

How-To: Set-up New Relic for distributed tracing

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Perpetually free New Relic account, 100 GB/month of free data ingest, 1 free full access user, unlimited free basic users

Configure Dapr tracing

Dapr natively captures metrics and traces that can be send directly to New Relic. The easiest way to export these is by configuring Dapr to send the traces to New Relic’s Trace API using the Zipkin trace format.

In order for the integration to send data to New Relic Telemetry Data Platform, you need a New Relic Insights Insert API key.

Redis

Mon, 01 Jan 0001 00:00:00 +0000

Querying states.
Creating aggregated views.
Making backups.

Note

The following examples uses Redis CLI against a Redis store using the default Dapr state store implementation.

Connect to Redis

You can use the official redis-cli or any other Redis compatible tools to connect to the Redis state store to query Dapr states directly. If you are running Redis in a container, the easiest way to use redis-cli is via a container:

Subscription spec

Mon, 01 Jan 0001 00:00:00 +0000

The Subscription Dapr resource allows you to subscribe declaratively to a topic using an external component YAML file.

Note

Any subscription can be restricted to a particular namespace and restricted access through scopes to any particular set of applications.

This guide demonstrates two subscription API versions:

v2alpha1 (default spec)
v1alpha1 (deprecated)

`v2alpha1` format

The following is the basic v2alpha1 spec for a Subscription resource. v2alpha1 is the default spec for the subscription API.

Supported runtime and SDK releases

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

This topic details the supported versions of Dapr releases, the upgrade policies and how deprecations and breaking changes are communicated in all Dapr repositories (runtime, CLI, SDKs, etc) at versions 1.x and above.

Dapr releases use MAJOR.MINOR.PATCH versioning. For example, 1.0.0.

Versioning	Description
`MAJOR`	Updated when there’s a non-backward compatible change to the runtime, such as an API change. A `MAJOR` release can also occur then there is a considered a significant addition/change of functionality that needs to differentiate from the previous version.
`MINOR`	Updated as part of the regular release cadence, including new features, bug, and security fixes.
`PATCH`	Incremented for a critical issue (P0) and security hot fixes.

A supported release means:

Workflow management operations with DaprWorkflowClient

Mon, 01 Jan 0001 00:00:00 +0000

Workflow management operations with `DaprWorkflowClient`

The DaprWorkflowClient class provides methods to manage workflow instances. Below are the operations you can perform using the DaprWorkflowClient.

Schedule a new workflow instance

To start a new workflow instance, use the ScheduleNewWorkflowAsync method. This method requires the workflow type name and an input required by the workflow. The workflow instancedId is an optional argument; if not provided, a new GUID is generated by the DaprWorkflowClient. The final optional argument is a startTime of type DateTimeOffset which can be used to define when the workflow instance should start. The method returns the instanceId of the scheduled workflow which is used for other workflow management operations.

Publishing & subscribing messages with Cloudevents

Mon, 01 Jan 0001 00:00:00 +0000

To enable message routing and provide additional context with each message, Dapr uses the CloudEvents 1.0 specification as its message format. Any message sent by an application to a topic using Dapr is automatically wrapped in a CloudEvents envelope, using the Content-Type header value for datacontenttype attribute.

Dapr uses CloudEvents to provide additional context to the event payload, enabling features like:

Tracing
Content-type for proper deserialization of event data
Verification of sender application

You can choose any of three methods for publish a CloudEvent via pub/sub:

Publishing & subscribing messages without CloudEvents

Mon, 01 Jan 0001 00:00:00 +0000

When adding Dapr to your application, some services may still need to communicate via pub/sub messages not encapsulated in CloudEvents, due to either compatibility reasons or some apps not using Dapr. These are referred to as “raw” pub/sub messages. Dapr enables apps to publish and subscribe to raw events not wrapped in a CloudEvent for compatibility and to send data that is not JSON serializable.

Publishing raw messages

Dapr apps are able to publish raw events to pub/sub topics without CloudEvent encapsulation, for compatibility with non-Dapr apps.

How-To: Route messages to different event handlers

Mon, 01 Jan 0001 00:00:00 +0000

Pub/sub routing is an implementation of content-based routing, a messaging pattern that utilizes a DSL instead of imperative application code. With pub/sub routing, you use expressions to route CloudEvents (based on their contents) to different URIs/paths and event handlers in your application. If no route matches, then an optional default route is used. This proves useful as your applications expand to support multiple event versions or special cases.

While routing can be implemented with code, keeping routing rules external from the application can improve portability.

Breaking changes and deprecations

Mon, 01 Jan 0001 00:00:00 +0000

Breaking changes

Breaking changes are defined as a change to any of the following that cause compilation errors or undesirable runtime behavior to an existing 3rd party consumer application or script after upgrading to the next stable minor version of a Dapr artifact (SDK, CLI, runtime, etc):

Code behavior
Schema
Default configuration value
Command line argument
Published metric
Kubernetes resource template
Publicly accessible API
Publicly visible SDK interface, method, class, or attribute

Breaking changes can be applied right away to the following cases:

Workflow versioning

Mon, 01 Jan 0001 00:00:00 +0000

Versioning

There are many scenarios where it is necessary to introduce changes to workflow code while workflows are actively running. In cases where these changes are non-deterministic, a versioning strategy is required so that existing workflows can continue executing with the original code, while new workflows use the updated version.

Workflows can be versioned using two complementary approaches and it’s intended that both are used in conjunction with one another. These are:

Workflow versioning in the .NET SDK

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Dapr Workflow versioning lets you evolve workflows without breaking deterministic execution for in-flight instances. The .NET SDK supports two approaches:

Patch-based versioning: introduce conditional branches guarded by context.IsPatched("patch-name").
Name-based versioning: create a new workflow type name and let a versioning strategy select the newest version.

Use patch-based versioning for small, in-place changes. Use name-based versioning for larger refactors where you want a clean new workflow type.

Note

Workflow versioning requires Dapr .NET SDK v1.17.0 or later and Dapr runtime v1.17.0 or later.

When to use each approach

Patch-based versioning is a good fit when:

Contributing to the .NET SDK

Mon, 01 Jan 0001 00:00:00 +0000

Welcome!

If you’re reading this, you’re likely interested in contributing to Dapr and/or the Dapr .NET SDK. Welcome to the project and thank you for your interest in contributing!

Please review the documentation, familiarize yourself with what Dapr is and what it’s seeking to accomplish and reach out on Discord. Let us know how you’d like to contribute and we’d be happy to chime in with ideas and suggestions.

There are many ways to contribute to Dapr:

Dapr API Logs

Mon, 01 Jan 0001 00:00:00 +0000

API logging enables you to see the API calls your application makes to the Dapr sidecar. This is useful to monitor your application’s behavior or for other debugging purposes. You can also combine Dapr API logging with Dapr log events (see configure and view Dapr Logs into the output if you want to use the logging capabilities together.

Overview

API logging is disabled by default.

To enable API logging, you can use the --enable-api-logging command-line option when starting the daprd process. For example:

Dapr extension for Azure Functions runtime

Mon, 01 Jan 0001 00:00:00 +0000

Dapr integrates with the Azure Functions runtime via an extension that lets a function seamlessly interact with Dapr.

Azure Functions provides an event-driven programming model.
Dapr provides cloud-native building blocks.

The extension combines the two for serverless and event-driven apps.

Try out the Dapr extension for Azure Functions

Enable API token authentication in Dapr

Mon, 01 Jan 0001 00:00:00 +0000

By default, Dapr relies on the network boundary to limit access to its public API. If you plan on exposing the Dapr API outside of that boundary, or if your deployment demands an additional level of security, consider enabling the token authentication for Dapr APIs. This will cause Dapr to require every incoming gRPC and HTTP request for its APIs for to include authentication token, before allowing that request to pass through.

Contributing to the Go SDK

Mon, 01 Jan 0001 00:00:00 +0000

When contributing to the Go SDK the following rules and best-practices should be followed.

Examples

The examples directory contains code samples for users to run to try out specific functionality of the various Go SDK packages and extensions. When writing new and updated samples keep in mind:

All examples should be runnable on Windows, Linux, and MacOS. While Go code is consistent among operating systems, any pre/post example commands should provide options through tabpane
Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine.

Docs

The daprdocs directory contains the markdown files that are rendered into the Dapr Docs website. When the documentation website is built this repo is cloned and configured so that its contents are rendered with the docs content. When writing docs keep in mind:

Set up a Google Kubernetes Engine (GKE) cluster

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Install:
- kubectl
- Google Cloud SDK

Create a new cluster

Create a GKE cluster by running the following:

$ gcloud services enable container.googleapis.com && \
 gcloud container clusters create $CLUSTER_NAME \
 --zone $ZONE \
 --project $PROJECT_ID

For more options:

Refer to the Google Cloud SDK docs.
Create a cluster through the Cloud Console for a more interactive experience.

Sidecar injection for private GKE clusters

Sidecar injection for private clusters requires extra steps.

In private GKE clusters, an automatically created firewall rule for master access doesn’t open port 4000, which Dapr needs for sidecar injection.

How To: Use secret scoping

Mon, 01 Jan 0001 00:00:00 +0000

Once you configure a secret store for your application, any secret defined within that store is accessible by default from the Dapr application.

You can limit the Dapr application’s access to specific secrets by defining secret scopes. Simply add a secret scope policy to the application configuration with restrictive permissions.

The secret scoping policy applies to any secret store, including:

A local secret store
A Kubernetes secret store
A public cloud secret store

For details on how to set up a secret store, read How To: Retrieve a secret.

Contributing to the Java SDK

Mon, 01 Jan 0001 00:00:00 +0000

When contributing to the Java SDK the following rules and best-practices should be followed.

Examples

The examples directory contains code samples for users to run to try out specific functionality of the various Java SDK packages and extensions. When writing new and updated samples keep in mind:

All examples should be runnable on Windows, Linux, and MacOS. While Java code is consistent among operating systems, any pre/post example commands should provide options through tabpane
Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine.

Docs

The daprdocs directory contains the markdown files that are rendered into the Dapr Docs website. When the documentation website is built, this repo is cloned and configured so that its contents are rendered with the docs content. When writing docs, keep in mind:

Contributing to the JavaScript SDK

Mon, 01 Jan 0001 00:00:00 +0000

When contributing to the JavaScript SDK the following rules and best-practices should be followed.

💡 You can run npm pretty-fix to run prettier on all your files

Commit Guidelines

The Dapr Javascript SDK uses the Conventional Commits specification. The automatic changelog tool uses these to automatically generate a changelog based on the commit messages. Here’s a guide to writing a commit message to allow this:

Format

type(scope)!: subject

type: the type of the commit is one of the following:

How to: Autoscale a Dapr app with KEDA

Mon, 01 Jan 0001 00:00:00 +0000

Dapr, with its building-block API approach, along with the many pub/sub components, makes it easy to write message processing applications. Since Dapr can run in many environments (for example VMs, bare-metal, Cloud or Edge Kubernetes) the autoscaling of Dapr applications is managed by the hosting layer.

For Kubernetes, Dapr integrates with KEDA, an event driven autoscaler for Kubernetes. Many of Dapr’s pub/sub components overlap with the scalers provided by KEDA, so it’s easy to configure your Dapr deployment on Kubernetes to autoscale based on the back pressure using KEDA.

How-To: Limit the secrets that can be read from secret stores

Mon, 01 Jan 0001 00:00:00 +0000

In addition to scoping which applications can access a given component, you can also scope a named secret store component to one or more secrets for an application. By defining allowedSecrets and/or deniedSecrets lists, you restrict applications to access only specific secrets.

For more information about configuring a Configuration resource:

Configure secrets access

The secrets section under the Configuration spec contains the following properties:

secrets:
 scopes:
 - storeName: kubernetes
 defaultAccess: allow
 allowedSecrets: ["redis-password"]
 - storeName: localstore
 defaultAccess: allow
 deniedSecrets: ["redis-password"]

The following table lists the properties for secret scopes:

mtls renew certificate CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

This command can be used to renew expiring Dapr certificates. For example the Dapr Sentry service can generate default root and issuer certificates used by applications. For more information see secure Dapr to Dapr communication

Supported platforms

Kubernetes

Usage

dapr mtls renew-certificate [flags]

Flags

Name	Default	Description
`--help`, `-h`		help for renew-certificate
`--kubernetes`, `-k`	`false`	supported platform
`--valid-until`	365 days	Validity for newly created certificates
`--restart`	false	Restarts Dapr control plane services (Sentry service, Operator service and Placement server)
`--timeout`	300 sec	The timeout for the certificate renewal process
`--ca-root-certificate`		File path to user provided PEM root certificate
`--issuer-public-certificate`		File path to user provided PEM issuer certificate
`--issuer-private-key`		File path to user provided PEM issue private key
`--private-key`		User provided root.key file which is used to generate root certificate

Examples

Renew certificates by generating brand new certificates

Generates new root and issuer certificates for the Kubernetes cluster with a default validity of 365 days. The certificates are not applied to the Dapr control plane.

How-To: Set-up New Relic for Dapr logging

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Perpetually free New Relic account, 100 GB/month of free data ingest, 1 free full access user, unlimited free basic users

Background

New Relic offers a Fluent Bit output plugin to easily forward your logs to New Relic Logs. This plugin is also provided in a standalone Docker image that can be installed in a Kubernetes cluster in the form of a DaemonSet, which we refer as the Kubernetes plugin.

This document explains how to install it in your cluster, either using a Helm chart (recommended), or manually by applying Kubernetes manifests.

Contributing to the Python SDK

Mon, 01 Jan 0001 00:00:00 +0000

When contributing to the Python SDK the following rules and best-practices should be followed.

Examples

The examples directory contains code samples for users to run to try out specific functionality of the various Python SDK packages and extensions. When writing new and updated samples keep in mind:

All examples should be runnable on Windows, Linux, and MacOS. While Python code is consistent among operating systems, any pre/post example commands should provide options through tabpane
Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine.

Docs

Reporting security issues

Mon, 01 Jan 0001 00:00:00 +0000

The Dapr project and maintainers make security a central focus of how we operate and design our software. From the Dapr binaries to the GitHub release processes, we take numerous steps to ensure user applications and data is secure. For more information on Dapr security features, visit the security page.

Repositories and issues covered

When we say “a security vulnerability in Dapr”, this means a security issue in any repository under the dapr GitHub organization.

Resiliency spec

Mon, 01 Jan 0001 00:00:00 +0000

The Resiliency Dapr resource allows you to define and apply fault tolerance resiliency policies. Resiliency specs are applied when the Dapr sidecar starts.

Note

Any resiliency resource can be restricted to a particular namepsace and restricted access through scopes to any particular set of applications.

Format

apiVersion: dapr.io/v1alpha1
kind: Resiliency
metadata:
 name: <REPLACE-WITH-RESOURCE-NAME>
version: v1alpha1
scopes:
 - <REPLACE-WITH-SCOPED-APPIDS>
spec:
 policies: # Required
 timeouts:
 timeoutName: <REPLACE-WITH-TIME-VALUE> # Replace with any unique name
 retries:
 retryName: # Replace with any unique name
 policy: <REPLACE-WITH-VALUE>
 duration: <REPLACE-WITH-VALUE>
 maxInterval: <REPLACE-WITH-VALUE>
 maxRetries: <REPLACE-WITH-VALUE>
 matching:
 httpStatusCodes: <REPLACE-WITH-VALUE>
 gRPCStatusCodes: <REPLACE-WITH-VALUE>
 circuitBreakers:
 circuitBreakerName: # Replace with any unique name
 maxRequests: <REPLACE-WITH-VALUE>
 timeout: <REPLACE-WITH-VALUE> 
 trip: <REPLACE-WITH-CONSECUTIVE-FAILURE-VALUE>
targets: # Required
 apps:
 appID: # Replace with scoped app ID
 timeout: <REPLACE-WITH-TIMEOUT-NAME>
 retry: <REPLACE-WITH-RETRY-NAME>
 circuitBreaker: <REPLACE-WITH-CIRCUIT-BREAKER-NAME>
 actors:
 myActorType: 
 timeout: <REPLACE-WITH-TIMEOUT-NAME>
 retry: <REPLACE-WITH-RETRY-NAME>
 circuitBreaker: <REPLACE-WITH-CIRCUIT-BREAKER-NAME>
 circuitBreakerCacheSize: <REPLACE-WITH-VALUE>
 components:
 componentName: # Replace with your component name
 outbound:
 timeout: <REPLACE-WITH-TIMEOUT-NAME>
 retry: <REPLACE-WITH-RETRY-NAME>
 circuitBreaker: <REPLACE-WITH-CIRCUIT-BREAKER-NAME>

Spec fields

Field	Required	Details	Example
policies	Y	The configuration of resiliency policies, including: `timeouts` `retries` `circuitBreakers` See more examples with all of the built-in policies	timeout: `general` retry: `retryForever` circuit breaker: `simpleCB`
targets	Y	The configuration for the applications, actors, or components that use the resiliency policies. See more examples in the resiliency targets guide	`apps` `components` `actors`

Learn more about resiliency policies and targets

Contributing to the Rust SDK

Mon, 01 Jan 0001 00:00:00 +0000

When contributing to the Rust SDK the following rules and best-practices should be followed.

Examples

The examples directory contains code samples for users to run to try out specific functionality of the various Rust SDK packages and extensions. It also hosts component examples used for validation. When writing new and updated samples keep in mind:

All examples should be runnable on Windows, Linux, and MacOS. While Rust code is consistent among operating systems aside from minor OS-feature gating, any pre/post example commands should provide options through tabpane
Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine.
Examples should be pass validation and include mechanical markdown steps and be added to the validation workflow TBA

Docs

dapr scheduler

Mon, 01 Jan 0001 00:00:00 +0000

dapr scheduler

Manage scheduled jobs and reminders stored in the Dapr Scheduler.

dapr scheduler [command]

Aliases

scheduler
sched

Available Commands

list: List scheduled jobs
get: Get a scheduled job by key
delete: Delete a scheduled job by key
delete-all): Delete all scheduled jobs by key prefix
export: Export all scheduled jobs to a file
import: Import scheduled jobs from a file

Global Flags

SQL server

Mon, 01 Jan 0001 00:00:00 +0000

Querying states.
Creating aggregated views.
Making backups.

Connect to SQL Server

The easiest way to connect to your SQL Server instance is to use the:

Azure Data Studio (Windows, macOS, Linux)
SQL Server Management Studio (Windows)

Note

When you configure an Azure SQL database for Dapr, you need to specify the exact table name to use. The following Azure SQL samples assume you’ve already connected to the right database with a table named “states”.

List keys by App ID

To get all state keys associated with application “myapp”, use the query:

Declarative, streaming, and programmatic subscription types

Mon, 01 Jan 0001 00:00:00 +0000

Pub/sub API subscription types

Dapr applications can subscribe to published topics via three subscription types that support the same features: declarative, streaming and programmatic.

Subscription type	Description
Declarative	Subscription is defined in an external file. The declarative approach removes the Dapr dependency from your code and allows for existing applications to subscribe to topics, without having to change code.
Streaming	Subscription is defined in the application code. Streaming subscriptions are dynamic, meaning they allow for adding or removing subscriptions at runtime. They do not require a subscription endpoint in your application (that is required by both programmatic and declarative subscriptions), making them easy to configure in code. Streaming subscriptions also do not require an app to be configured with the sidecar to receive messages.
Programmatic	Subscription is defined in the application code. The programmatic approach implements the static subscription and requires an endpoint in your code.

The examples below demonstrate pub/sub messaging between a checkout app and an orderprocessing app via the orders topic. The examples demonstrate the same Dapr pub/sub component used first declaratively, then programmatically.

.NET Workflow Examples

Mon, 01 Jan 0001 00:00:00 +0000

Workflow tutorials in the Dapr Quickstarts repository

The Dapr Quickstarts repository on GitHub includes many workflow tutorials that showcase the various workflow patterns and how to use the workflow management operations. You can find these tutorials in the quickstarts/tutorials/workflow/csharp folder.

Workflow examples in the .NET SDK repository

The Dapr .NET SDK repository on GitHub contains several examples demonstrating how to use Dapr Workflows with .NET. You can find these examples in the examples/Workflow folder.

Workflow patterns

Mon, 01 Jan 0001 00:00:00 +0000

Dapr Workflows simplify complex, stateful coordination requirements in microservice architectures. The following sections describe several application patterns that can benefit from Dapr Workflows.

Task chaining

In the task chaining pattern, multiple steps in a workflow are run in succession, and the output of one step may be passed as the input to the next step. Task chaining workflows typically involve creating a sequence of operations that need to be performed on some data, such as filtering, transforming, and reducing.

Properties

Mon, 01 Jan 0001 00:00:00 +0000

Properties

The Dapr Java SDK provides a set of global properties that control the behavior of the SDK. These properties can be configured using environment variables or system properties. System properties can be set using the -D flag when running your Java application.

These properties affect the entire SDK, including clients and runtime. They control aspects such as:

Sidecar connectivity (endpoints, ports)
Security settings (TLS, API tokens)
Performance tuning (timeouts, connection pools)
Protocol settings (gRPC, HTTP)
String encoding

Environment Variables

The following environment variables are available for configuring the Dapr Java SDK:

Authenticate requests from Dapr using token authentication

Mon, 01 Jan 0001 00:00:00 +0000

For some building blocks such as pub/sub, service invocation and input bindings, Dapr communicates with an app over HTTP or gRPC. To enable the application to authenticate requests that are arriving from the Dapr sidecar, you can configure Dapr to send an API token as a header (in HTTP requests) or metadata (in gRPC requests).

Create a token

Dapr uses shared tokens for API authentication. You are free to define the API token to use.

Dapr extension for Azure Kubernetes Service (AKS)

Mon, 01 Jan 0001 00:00:00 +0000

The recommended approach for installing Dapr on AKS is to use the AKS Dapr extension. The extension offers:

Support for all native Dapr configuration capabilities through command-line arguments via the Azure CLI
The option of opting into automatic minor version upgrades of the Dapr runtime

Note

If you install Dapr through the AKS extension, best practice is to continue using the extension for future management of Dapr instead of the Dapr CLI. Combining the two tools can cause conflicts and result in undesired behavior.

Prerequisites for using the Dapr extension for AKS:

Dead Letter Topics

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

There are times when applications might not be able to handle messages for a variety of reasons. For example, there could be transient issues retrieving data needed to process a message or the app business logic fails returning an error. Dead letter topics are used to forward messages that cannot be delivered to a subscribing app. This eases the pressure on app by freeing them from dealing with these failed messages, allowing developers to write code that reads from the dead letter topic and either fixes the message and resends this, or abandons it completely.

Profiling & Debugging

Mon, 01 Jan 0001 00:00:00 +0000

In any real world scenario, an app might start exhibiting undesirable behavior in terms of resource spikes. CPU/Memory spikes are not uncommon in most cases.

Dapr allows users to start an on-demand profiling session using pprof through its profiling server endpoint and start an instrumentation session to discover problems and issues such as concurrency, performance, cpu and memory usage.

Enable profiling

Dapr allows you to enable profiling in both Kubernetes and stand-alone modes.

Set up an Elastic Kubernetes Service (EKS) cluster

Mon, 01 Jan 0001 00:00:00 +0000

This guide walks you through installing an Elastic Kubernetes Service (EKS) cluster. If you need more information, refer to Create an Amazon EKS cluster

Prerequisites

Install:

Deploy an EKS cluster

In the terminal, log into AWS.
```
aws configure
```
Create a new file called cluster-config.yaml and add the content below to it, replacing [your_cluster_name], [your_cluster_region], and [your_k8s_version] with the appropriate values:

HTTPEndpoint spec

Mon, 01 Jan 0001 00:00:00 +0000

The HTTPEndpoint is a Dapr resource that is used to enable the invocation of non-Dapr endpoints from a Dapr application.

Note

Any HTTPEndpoint resource can be restricted to a particular namepsace and restricted access through scopes to any particular set of applications.

Format

apiVersion: dapr.io/v1alpha1
kind: HTTPEndpoint
metadata:
 name: <NAME> 
spec:
 baseUrl: <REPLACE-WITH-BASEURL> # Required. Use "http://" or "https://" prefix.
 headers: # Optional
 - name: <REPLACE-WITH-A-HEADER-NAME>
 value: <REPLACE-WITH-A-HEADER-VALUE>
 - name: <REPLACE-WITH-A-HEADER-NAME>
 secretKeyRef:
 name: <REPLACE-WITH-SECRET-NAME>
 key: <REPLACE-WITH-SECRET-KEY>
 clientTLS:
 rootCA:
 secretKeyRef:
 name: <REPLACE-WITH-SECRET-NAME>
 key: <REPLACE-WITH-SECRET-KEY>
 certificate:
 secretKeyRef:
 name: <REPLACE-WITH-SECRET-NAME>
 key: <REPLACE-WITH-SECRET-KEY>
 privateKey:
 secretKeyRef:
 name: <REPLACE-WITH-SECRET-NAME>
 key: <REPLACE-WITH-SECRET-KEY>
scopes: # Optional
 - <REPLACE-WITH-SCOPED-APPIDS>
auth: # Optional
 secretStore: <REPLACE-WITH-SECRETSTORE>

Spec fields

Field	Required	Details	Example
baseUrl	Y	Base URL of the non-Dapr endpoint	`"https://api.github.com"`, `"http://api.github.com"`
headers	N	HTTP request headers for service invocation	`name: "Accept-Language" value: "en-US"` `name: "Authorization" secretKeyRef.name: "my-secret" secretKeyRef.key: "myGithubToken"`
clientTLS	N	Enables TLS authentication to an endpoint with any standard combination of root certificate, client certificate and private key

Learn how to invoke non-Dapr endpoints.

Configure metrics

Mon, 01 Jan 0001 00:00:00 +0000

By default, each Dapr system process emits Go runtime/process metrics and has their own Dapr metrics.

Prometheus endpoint

The Dapr sidecar exposes a Prometheus-compatible metrics endpoint that you can scrape to gain a greater understanding of how Dapr is behaving.

Configuring metrics using the CLI

The metrics application endpoint is enabled by default. You can disable it by passing the command line argument --enable-metrics=false.

The default metrics port is 9090. You can override this by passing the command line argument --metrics-port to daprd.

Preview features

Mon, 01 Jan 0001 00:00:00 +0000

Preview features in Dapr are considered experimental when they are first released.

Runtime preview features require explicit opt-in in order to be used. The runtime opt-in is specified in a preview setting feature in Dapr’s application configuration. See How-To: Enable preview features for more information.

For CLI there is no explicit opt-in, just the version that this was first made available.

Current preview features

Feature	Description	Setting	Documentation	Version introduced
Pluggable components	Allows creating self-hosted gRPC-based components written in any language that supports gRPC. The following component APIs are supported: State stores, Pub/sub, Bindings	N/A	Pluggable components concept	v1.9
Multi-App Run for Kubernetes	Configure multiple Dapr applications from a single configuration file and run from a single command on Kubernetes	`dapr run -k -f`	Multi-App Run	v1.12
Cryptography	Encrypt or decrypt data without having to manage secrets keys	N/A	Cryptography concept	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 for more information.	`ActorStateTTL`	Actor State Transactions	v1.11
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	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	v1.14
Configuration, Resiliency, and HTTPEndpoint Hot Reloading	Changes to Configuration, Resiliency, and HTTPEndpoint resources are automatically detected and trigger a graceful restart of the Dapr sidecar via SIGHUP. Not supported on Windows.	`HotReload`	Hot Reloading	v1.18
Workflows Clustered Deployment	Enable Workflows to function when workflow clients communicate to multiple daprds of the same appID who are behind a loadbalancer. Only relevant when using Dapr shared	`WorkflowsClusteredDeployment`	Dapr Shared	v1.16
Workflows Durable Activity Results	If set, ensures that activity results are durably sent to the owning workflow in multi-application scenarios, even when the owning workflow application is unavailable. Strongly recommended to always be enabled when all Dapr applications are running the same version. Enabled by default as of v1.18.	`WorkflowsRemoteActivityReminder`	Multi-application Workflows	v1.17

How-To: Observe metrics with Prometheus

Mon, 01 Jan 0001 00:00:00 +0000

Setup Prometheus Locally

To run Prometheus on your local machine, you can either install and run it as a process or run it as a Docker container.

Install

Note

You don’t need to install Prometheus if you plan to run it as a Docker container. Please refer to the Container instructions.

To install Prometheus, follow the steps outlined here for your OS.

Configure

Now you’ve installed Prometheus, you need to create a configuration.

How-To: Apply access control list configuration for service invocation

Mon, 01 Jan 0001 00:00:00 +0000

Using access control, you can configure policies that restrict what the operations calling applications can perform, via service invocation, on the called application. You can define an access control policy specification in the Configuration schema to limit access:

To a called application from specific operations, and
To HTTP verbs from the calling applications.

An access control policy is specified in Configuration and applied to the Dapr sidecar for the called application. Access to the called app is based on the matched policy action.

Workflow architecture

Mon, 01 Jan 0001 00:00:00 +0000

Dapr Workflows allow developers to define workflows using ordinary code in a variety of programming languages. The workflow engine runs inside of the Dapr sidecar and orchestrates workflow code deployed as part of your application. Dapr Workflows are built on top of Dapr Actors providing durability and scalability for workflow execution.

This article describes:

The architecture of the Dapr Workflow engine
How the workflow engine interacts with application code
How the workflow engine fits into the overall Dapr architecture
How different workflow backends can work with workflow engine

For more information on how to author Dapr Workflows in your application, see How to: Author a workflow.

How-To: Set up Zipkin for distributed tracing

Mon, 01 Jan 0001 00:00:00 +0000

Configure self hosted mode

For self hosted mode, on running dapr init:

The following YAML file is created by default in $HOME/.dapr/config.yaml (on Linux/Mac) or %USERPROFILE%\.dapr\config.yaml (on Windows) and it is referenced by default on dapr run calls unless otherwise overridden `:

config.yaml

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
 name: daprConfig
 namespace: default
spec:
 tracing:
 samplingRate: "1"
 zipkin:
 endpointAddress: "http://localhost:9411/api/v2/spans"

The openzipkin/zipkin docker container is launched on running dapr init or it can be launched with the following code.

Launch Zipkin using Docker:

How-To: Selectively enable Dapr APIs on the Dapr sidecar

Mon, 01 Jan 0001 00:00:00 +0000

In scenarios such as zero trust networks or when exposing the Dapr sidecar to external traffic through a frontend, it’s recommended to only enable the Dapr sidecar APIs being used by the app. Doing so reduces the attack surface and helps keep the Dapr APIs scoped to the actual needs of the application.

Dapr allows you to control which APIs are accessible to the application by setting an API allowlist or denylist using a Dapr Configuration.

Alpha and Beta APIs

Mon, 01 Jan 0001 00:00:00 +0000

Alpha APIs

Building block/API	gRPC	HTTP	Description	Documentation	Version introduced
Query State	Query State proto	`v1.0-alpha1/state/statestore/query`	The state query API enables you to retrieve, filter, and sort the key/value data stored in state store components.	Query State API	v1.5
Distributed Lock	Lock proto	`/v1.0-alpha1/lock`	The distributed lock API enables you to take a lock on a resource.	Distributed Lock API	v1.8
Cryptography	Crypto proto	`v1.0-alpha1/crypto`	The cryptography API enables you to perform high level cryptography operations for encrypting and decrypting messages.	Cryptography API	v1.11
Jobs	Jobs proto	`v1.0-alpha1/jobs`	The jobs API enables you to schedule and orchestrate jobs.	Jobs API	v1.14
Streaming Subscription	Streaming Subscription proto	N/A	Subscription is defined in the application code. Streaming subscriptions are dynamic, meaning they allow for adding or removing subscriptions at runtime.	Streaming Subscription API	v1.14
Conversation	Conversation proto	`v1.0-alpha2/conversation`	Converse between different large language models using the conversation API.	Conversation API	v1.15

Beta APIs

No current beta APIs.

Configuration spec

Mon, 01 Jan 0001 00:00:00 +0000

The Configuration is a Dapr resource that is used to configure the Dapr sidecar, control plane, and others.

Sidecar format

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
 name: <REPLACE-WITH-NAME>
 namespace: <REPLACE-WITH-NAMESPACE>
spec:
 api:
 allowed:
 - name: <REPLACE-WITH-API>
 version: <VERSION>
 protocol: <HTTP-OR-GRPC>
 tracing:
 samplingRate: <REPLACE-WITH-INTEGER>
 stdout: true
 otel:
 endpointAddress: <REPLACE-WITH-ENDPOINT-ADDRESS>
 isSecure: <TRUE-OR-FALSE>
 protocol: <HTTP-OR-GRPC>
 headers:
 - name: <HEADER-NAME>
 value: <HEADER-VALUE>
 - name: <HEADER-NAME>
 secretKeyRef:
 name: <SECRET-STORE-NAME>
 key: <SECRET-KEY>
 timeout: <DURATION>
 metrics:
 enabled: <TRUE-OR-FALSE>
 rules:
 - name: <METRIC-NAME>
 labels:
 - name: <LABEL-NAME>
 regex: {}
 recordErrorCodes: <TRUE-OR-FALSE>
 latencyDistributionBuckets:
 - <BUCKET-VALUE-MS-0>
 - <BUCKET-VALUE-MS-1>
 http:
 increasedCardinality: <TRUE-OR-FALSE>
 pathMatching: 
 - <PATH-A>
 - <PATH-B>
 excludeVerbs: <TRUE-OR-FALSE>
 httpPipeline: # for incoming http calls
 handlers:
 - name: <HANDLER-NAME>
 type: <HANDLER-TYPE>
 appHttpPipeline: # for outgoing http calls
 handlers:
 - name: <HANDLER-NAME>
 type: <HANDLER-TYPE>
 nameResolution:
 component: <NAME-OF-NAME-RESOLUTION-COMPONENT>
 version: <NAME-RESOLUTION-COMPONENT-VERSION>
 configuration:
 <NAME-RESOLUTION-COMPONENT-METADATA-CONFIGURATION>
 secrets:
 scopes:
 - storeName: <NAME-OF-SCOPED-STORE>
 defaultAccess: <ALLOW-OR-DENY>
 deniedSecrets: <REPLACE-WITH-DENIED-SECRET>
 components:
 deny:
 - <COMPONENT-TO-DENY>
 accessControl:
 defaultAction: <ALLOW-OR-DENY>
 trustDomain: <REPLACE-WITH-TRUST-DOMAIN>
 policies:
 - appId: <APP-NAME>
 defaultAction: <ALLOW-OR-DENY>
 trustDomain: <REPLACE-WITH-TRUST-DOMAIN>
 namespace: "default"
 operations:
 - name: <OPERATION-NAME>
 httpVerb: ['POST', 'GET']
 action: <ALLOW-OR-DENY>

Spec fields

Field	Required	Details	Example
accessControl	N	Applied to Dapr sidecar for the called application. Enables the configuration of policies that restrict what operations calling applications can perform (via service invocation) on the called appliaction.	Learn more about the `accessControl` configuration.
api	N	Used to enable only the Dapr sidecar APIs used by the application.	Learn more about the `api` configuration.
httpPipeline	N	Configure API middleware pipelines	Middleware pipeline configuration overview Learn more about the `httpPipeline` configuration.
appHttpPipeline	N	Configure application middleware pipelines	Middleware pipeline configuration overview Learn more about the `appHttpPipeline` configuration.
components	N	Used to specify a denylist of component types that can’t be initialized.	Learn more about the `components` configuration.
features	N	Defines the preview features that are enabled/disabled.	Learn more about the `features` configuration.
logging	N	Configure how logging works in the Dapr runtime.	Learn more about the `logging` configuration.
metrics	N	Enable or disable metrics for an application.	Learn more about the `metrics` configuration.
nameResolution	N	Name resolution configuration spec for the service invocation building block.	Learn more about the `nameResolution` configuration per components.
secrets	N	Limit the secrets to which your Dapr application has access.	Learn more about the `secrets` configuration.
tracing	N	Turns on tracing for an application.	Learn more about the `tracing` configuration.

Control plane format

The daprsystem configuration file installed with Dapr applies global settings and is only set up when Dapr is deployed to Kubernetes.

How-To: Set up Dash0 for distributed tracing

Mon, 01 Jan 0001 00:00:00 +0000

Dapr captures metrics, traces, and logs that can be sent directly to Dash0 through the OpenTelemetry Collector. Dash0 is an OpenTelemetry-native observability platform that provides comprehensive monitoring capabilities for distributed applications.

Configure Dapr tracing with the OpenTelemetry Collector and Dash0

By using the OpenTelemetry Collector with the OTLP exporter to send data to Dash0, you can configure Dapr to create traces for each application in your Kubernetes cluster and collect them in Dash0 for analysis and monitoring.

How-To: Set up Datadog for distributed tracing

Mon, 01 Jan 0001 00:00:00 +0000

Dapr captures metrics and traces that can be sent directly to Datadog through the OpenTelemetry Collector Datadog exporter.

Configure Dapr tracing with the OpenTelemetry Collector and Datadog

Using the OpenTelemetry Collector Datadog exporter, you can configure Dapr to create traces for each application in your Kubernetes cluster and collect them in Datadog.

Before you begin, set up the OpenTelemetry Collector.

Add your Datadog API key to the ./deploy/opentelemetry-collector-generic-datadog.yaml file in the datadog exporter configuration section:

How to: Use the Dapr CLI in a GitHub Actions workflow

Mon, 01 Jan 0001 00:00:00 +0000

Dapr can be integrated with GitHub Actions via the Dapr tool installer available in the GitHub Marketplace. This installer adds the Dapr CLI to your workflow, allowing you to deploy, manage, and upgrade Dapr across your environments.

Install the Dapr CLI via the Dapr tool installer

Copy and paste the following installer snippet into your application’s YAML file:

- name: Dapr tool installer
 uses: dapr/setup-dapr@v1

The dapr/setup-dapr action will install the specified version of the Dapr CLI on macOS, Linux, and Windows runners. Once installed, you can run any Dapr CLI command to manage your Dapr environments.

How-To: Observe metrics with Grafana

Mon, 01 Jan 0001 00:00:00 +0000

Available dashboards

The grafana-system-services-dashboard.json template shows Dapr system component status, dapr-operator, dapr-sidecar-injector, dapr-sentry, and dapr-placement:

The grafana-sidecar-dashboard.json template shows Dapr sidecar status, including sidecar health/resources, throughput/latency of HTTP and gRPC, Actor, mTLS, etc.:

How to: Author a workflow

Mon, 01 Jan 0001 00:00:00 +0000

This article provides a high-level overview of how to author workflows that are executed by the Dapr Workflow engine.

Note

If you haven’t already, try out the workflow quickstart for a quick walk-through on how to use workflows.

Author workflows as code

Dapr Workflow logic is implemented using general purpose programming languages, allowing you to:

Use your preferred programming language (no need to learn a new DSL or YAML schema).
Have access to the language’s standard libraries.
Build your own libraries and abstractions.
Use debuggers and examine local variables.
Write unit tests for your workflows, just like any other part of your application logic.

The Dapr sidecar doesn’t load any workflow definitions. Rather, the sidecar simply drives the execution of the workflows, leaving all the workflow activities to be part of the application.

How to: Set up pub/sub namespace consumer groups

Mon, 01 Jan 0001 00:00:00 +0000

You’ve set up Dapr’s pub/sub API building block, and your applications are publishing and subscribing to topics smoothly, using a centralized message broker. What if you’d like to perform simple A/B testing, blue/green deployments, or even canary deployments for your applications? Even with using Dapr, this can prove difficult.

Dapr solves multi-tenancy at-scale with its pub/sub namespace consumer groups construct.

Without namespace consumer groups

Let’s say you have a Kubernetes cluster, with two applications (App1 and App2) deployed to the same namespace (namespace-a). App2 publishes to a topic called order, while App1 subscribes to the topic called order. This will create two consumer groups, named after your applications (App1 and App2).

How-To: Schedule and handle triggered jobs

Mon, 01 Jan 0001 00:00:00 +0000

Now that you’ve learned what the jobs building block provides, let’s look at an example of how to use the API. The code example below describes an application that schedules jobs for a database backup application and handles them at trigger time, also known as the time the job was sent back to the application because it reached it’s dueTime.

Start the Scheduler service

When you run dapr init in either self-hosted mode or on Kubernetes, the Dapr Scheduler service is started.

How-To: Configure Dapr to use gRPC

Mon, 01 Jan 0001 00:00:00 +0000

Dapr implements both an HTTP and a gRPC API for local calls. gRPC is useful for low-latency, high performance scenarios and has language integration using the proto clients. You can see the full list of auto-generated clients (Dapr SDKs).

The Dapr runtime implements a proto service that apps can communicate with via gRPC.

Not only can you call Dapr via gRPC, Dapr can communicate with an application via gRPC. To do that, the app needs to host a gRPC server and implement the Dapr appcallback service

How to: Horizontally scale subscribers with StatefulSets

Mon, 01 Jan 0001 00:00:00 +0000

Unlike Deployments, where Pods are ephemeral, StatefulSets allows deployment of stateful applications on Kubernetes by keeping a sticky identity for each Pod.

Below is an example of a StatefulSet with Dapr:

apiVersion: apps/v1
kind: StatefulSet
metadata:
 name: python-subscriber
spec:
 selector:
 matchLabels:
 app: python-subscriber  # has to match .spec.template.metadata.labels
 serviceName: "python-subscriber"
 replicas: 3
 template:
 metadata:
 labels:
 app: python-subscriber # has to match .spec.selector.matchLabels
 annotations:
 dapr.io/enabled: "true"
 dapr.io/app-id: "python-subscriber"
 dapr.io/app-port: "5001"
 spec:
 containers:
 - name: python-subscriber
 image: ghcr.io/dapr/samples/pubsub-python-subscriber:latest
 ports:
 - containerPort: 5001
 imagePullPolicy: Always

When subscribing to a pub/sub topic via Dapr, the application can define the consumerID, which determines the subscriber’s position in the queue or topic. With the StatefulSets sticky identity of Pods, you can have a unique consumerID per Pod, allowing each horizontal scale of the subscriber application. Dapr keeps track of the name of each Pod, which can be used when declaring components using the {podName} marker.

How to: Manage workflows

Mon, 01 Jan 0001 00:00:00 +0000

Now that you’ve authored the workflow and its activities in your application, you can start, terminate, rerun, and get information about the workflow using the CLI or API calls.

Managing Workflows with the Dapr CLI

The Dapr CLI provides commands for managing workflow instances in both self-hosted and Kubernetes environments.

How-To: Handle large HTTP header size

Mon, 01 Jan 0001 00:00:00 +0000

Dapr has a default limit of 4KB for the HTTP header read buffer size. If you’re sending HTTP headers larger than the default 4KB, you may encounter a Too big request header service invocation error.

You can increase the HTTP header size by using:

The dapr.io/http-read-buffer-size annotation, or
The --dapr-http-read-buffer-size flag when using the CLI.

When running in self-hosted mode, use the --dapr-http-read-buffer-size flag to configure Dapr to use non-default http header size:

How-To: Set-up New Relic to collect and analyze metrics

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Perpetually free New Relic account, 100 GB/month of free data ingest, 1 free full access user, unlimited free basic users

Background

New Relic offers a Prometheus OpenMetrics Integration.

This document explains how to install it in your cluster, either using a Helm chart (recommended).

Installation

Install Helm following the official instructions.
Add the New Relic official Helm chart repository following these instructions
Run the following command to install the New Relic Logging Kubernetes plugin via Helm, replacing the placeholder value YOUR_LICENSE_KEY with your New Relic license key:

How-To: Handle larger body requests

Mon, 01 Jan 0001 00:00:00 +0000

Note

The existing flag/annotationdapr-http-max-request-size has been deprecated and updated to max-body-size.

By default, Dapr has a limit for the request body size, set to 4MB. You can change this for both HTTP and gRPC requests by defining:

The dapr.io/max-body-size annotation, or
The --max-body-size flag.

When running in self-hosted mode, use the --max-body-size flag to configure Dapr to use non-default request body size:

Scope Pub/sub topic access

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

Namespaces or component scopes can be used to limit component access to particular applications. These application scopes added to a component limit only the applications with specific IDs to be able to use the component.

In addition to this general component scope, the following can be limited for pub/sub components:

Which topics can be used (published or subscribed)
Which applications are allowed to publish to specific topics
Which applications are allowed to subscribe to specific topics

This is called pub/sub topic scoping.

How-To: Install certificates in the Dapr sidecar

Mon, 01 Jan 0001 00:00:00 +0000

The Dapr sidecar can be configured to trust certificates for communicating with external services. This is useful in scenarios where a self-signed certificate needs to be trusted, such as:

Using an HTTP binding
Configuring an outbound proxy for the sidecar

Both certificate authority (CA) certificates and leaf certificates are supported.

You can make the following configurations when the sidecar is running as a container.

How-To: Set up Azure Monitor to search logs and collect metrics

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Enable Prometheus metric scrape using config map

Make sure that Azure Monitor Agents (AMA) are running.

$ kubectl get pods -n kube-system
NAME READY STATUS RESTARTS AGE
...
ama-logs-48kpv 2/2 Running 0 2d13h
ama-logs-mx24c 2/2 Running 0 2d13h
ama-logs-rs-f9bbb9898-vbt6k 1/1 Running 0 30h
ama-logs-sm2mz 2/2 Running 0 2d13h
ama-logs-z7p4c 2/2 Running 0 2d13h
...

Apply config map to enable Prometheus metrics endpoint scrape.

How to: Use the Dapr Kubernetes Operator

Mon, 01 Jan 0001 00:00:00 +0000

You can use the Dapr Kubernetes Operator to manage the Dapr control plane. Use the operator to automate the tasks required to manage the lifecycle of Dapr control plane in Kubernetes mode.

Install and use the Dapr Kubernetes Operator

Message Time-to-Live (TTL)

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

Dapr enables per-message time-to-live (TTL). This means that applications can set time-to-live per message, and subscribers do not receive those messages after expiration.

All Dapr pub/sub components are compatible with message TTL, as Dapr handles the TTL logic within the runtime. Simply set the ttlInSeconds metadata when publishing a message.

In some components, such as Kafka, time-to-live can be configured in the topic via retention.ms as per documentation. With message TTL in Dapr, applications using Kafka can now set time-to-live per message in addition to per topic.

Multi Application Workflows

Mon, 01 Jan 0001 00:00:00 +0000

It is often the case that a single workflow spans multiple applications, microservices, or programming languages. This is where an activity or a child workflow will be executed on a different application than the one hosting the parent workflow.

Some scenarios where this is useful include:

A Machine Learning (ML) training activity must be executed on GPU-enabled machines, while the rest of the workflow runs on CPU-only orchestration machines.
Activities need access to sensitive data or credentials that are only available to particular identities or locales.
Different parts of the workflow need to be executed in different trust zones or networks.
Different parts of the workflow need to be executed in different geographic regions due to data residency requirements.
An involved business process spans multiple teams or departments, each owning their own application.
Implementation of a workflow spans different programming languages based on team expertise or existing codebases.
Different team boundaries or microservice ownership.

The diagram below shows an example scenario of a complex workflow that orchestrates across multiple applications that are written in different languages. Each applications’ main steps and activities are:

How-To: Enable preview features

Mon, 01 Jan 0001 00:00:00 +0000

Preview features in Dapr are considered experimental when they are first released. These preview features require you to explicitly opt-in to use them. You specify this opt-in in Dapr’s Configuration file.

Preview features are enabled on a per application basis by setting configuration when running an application instance.

Configuration properties

The features section under the Configuration spec contains the following properties:

Property	Type	Description
`name`	string	The name of the preview feature that is enabled/disabled
`enabled`	bool	Boolean specifying if the feature is enabled or disabled

Enabling a preview feature

Preview features are specified in the configuration. Here is an example of a full configuration that contains multiple features:

Publish and subscribe to bulk messages

Mon, 01 Jan 0001 00:00:00 +0000

With the bulk publish and subscribe APIs, you can publish and subscribe to multiple messages in a single request. When writing applications that need to send or receive a large number of messages, using bulk operations allows achieving high throughput by reducing the overall number of requests between the Dapr sidecar, the application, and the underlying pub/sub broker.

Publishing messages in bulk

Restrictions when publishing messages in bulk

The bulk publish API allows you to publish multiple messages to a topic in a single request. It is non-transactional, i.e., from a single bulk request, some messages can succeed and some can fail. If any of the messages fail to publish, the bulk publish operation returns a list of failed messages.

How-To: Configure Environment Variables from Secrets for Dapr sidecar

Mon, 01 Jan 0001 00:00:00 +0000

In special cases, the Dapr sidecar needs an environment variable injected into it. This use case may be required by a component, a 3rd party library, or a module that uses environment variables to configure the said component or customize its behavior. This can be useful for both production and non-production environments.

Overview

In Dapr 1.15, the new dapr.io/env-from-secret annotation was introduced, similar to dapr.io/env. With this annotation, you can inject an environment variable into the Dapr sidecar, with a value from a secret.

History Retention Policy

Mon, 01 Jan 0001 00:00:00 +0000

Dapr workflow state is stored in the [actor state store]{{ %ref workflow-architecture.md#state-store-usage %}}. By default, Dapr Workflows retains the complete history of workflow state changes indefinitely. This means historical workflows can be queried and inspected at any time. Running many workflows or workflows which generate large amounts of state change history can lead to increased storage usage, which can eventually fill up the state store disk space.

To help manage storage usage, Dapr Workflows supports configuring a history retention policy. The retention policy defines how long to retain workflow state change history before it is deleted. Workflows will only be eligible for deletion once it has reached a terminal state (Completed, Failed, or Terminated). Each workflow terminal state can have a custom retention duration, as well as a default retention duration for any terminal states not explicitly configured. The duration is defined as a Go duration string (for example, 72h for 72 hours, or 30m for 30 minutes).

How to: Integrate with Kratix

Mon, 01 Jan 0001 00:00:00 +0000

As part of the Kratix Marketplace, Dapr can be used to build custom platforms tailored to your needs.

Note

The Dapr Helm chart generates static public and private key pairs that are published in the repository. This promise should only be used locally for demo purposes. If you wish to use this promise for more than demo purposes, it’s recommended to manually update all the secrets in the promise with keys with your own credentials.

Get started by simply installing the Dapr Promise, which installs Dapr on all matching clusters.

How-To: Add custom annotations to the Dapr sidecar service

Mon, 01 Jan 0001 00:00:00 +0000

The Dapr operator automatically creates a Service (named with the -dapr suffix) for the Dapr sidecar when running in Kubernetes. In some cases, you may need to add custom annotations to this service, for example to support specific network policies (such as Illumio) or metrics scraping configurations.

Overview

The dapr.io/sidecar-svc-annotations annotation allows you to specify a comma-separated list of key=value pairs that will be added as annotations to the Dapr sidecar service.

How to: Integrate with Argo CD

Mon, 01 Jan 0001 00:00:00 +0000

Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes. It enables you to manage your Kubernetes deployments by tracking the desired application state in Git repositories and automatically syncing it to your clusters.

Integration with Dapr

You can use Argo CD to manage the deployment of Dapr control plane components and Dapr-enabled applications. By adopting a GitOps approach, you ensure that Dapr’s configurations and applications are consistently deployed, versioned, and auditable across your environments. Argo CD can be easily configured to deploy Helm charts, manifests, and Dapr components stored in Git repositories.

Workflow Concurrency Limits

Mon, 01 Jan 0001 00:00:00 +0000

Dapr provides concurrency limits for workflows and activities at two levels:

Per-sidecar limits control how many workflows or activities a single Dapr instance can execute concurrently.
Global limits control the total across all replicas, enforced by the scheduler.

Both levels can be configured independently and work together. Per-sidecar limits protect individual instances from resource exhaustion. Global limits enforce cluster-wide capacity constraints, for example, to respect rate limits on downstream services.

Getting started with the Dapr client Python SDK

Mon, 01 Jan 0001 00:00:00 +0000

The Dapr client package allows you to interact with other Dapr applications from a Python application.

Note

If you haven’t already, try out one of the quickstarts for a quick walk-through on how to use the Dapr Python SDK with an API building block.

Prerequisites

Install the Dapr Python package before getting started.

Import the client package

The dapr package contains the DaprClient, which is used to create and use a client.

Dapr Visual Studio Code extension overview

Mon, 01 Jan 0001 00:00:00 +0000

Deprecation notice

The extension was previously supported by Microsoft, but is now deprecated. The extension will remain available in the Visual Studio Code marketplace, but it will no longer receive updates or support.

The deprecated Dapr Visual Studio Code extension for local development which enables users a variety of features related to better managing their Dapr applications and debugging of your Dapr applications for all supported Dapr languages which are .NET, Go, PHP, Python and Java.

Getting started with the Dapr HTTP Service SDK for Go

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisite

Start by importing Dapr Go service/http package:

daprd "github.com/dapr/go-sdk/service/http"

Creating and Starting Service

To create an HTTP Dapr service, first, create a Dapr callback instance with a specific address:

s := daprd.NewService(":8080")

Or with address and an existing http.ServeMux in case you want to combine existing server implementations:

mux := http.NewServeMux()
mux.HandleFunc("/", myOtherHandler)
s := daprd.NewServiceWithMux(":8080", mux)

Once you create a service instance, you can “attach” to that service any number of event, binding, and service invocation logic handlers as shown below. Onces the logic is defined, you are ready to start the service:

Longhaul performance and stability

Mon, 01 Jan 0001 00:00:00 +0000

This article provides longhaul performance and stability benchmarks for Dapr on Kubernetes.

The longhaul tests are designed to run for a period of a week, validating the stability of Dapr and its components, while measuring resource utilization and performance over time.

Public Dashboard

You can access the live longhaul test results on the public Grafana dashboard. This dashboard is updated in near real-time, showing the latest results from the longhaul tests.

HowTo: Configure Pub/Sub components with multiple namespaces

Mon, 01 Jan 0001 00:00:00 +0000

In some scenarios, applications can be spread across namespaces and share a queue or topic via PubSub. In this case, the PubSub component must be provisioned on each namespace.

Note

Namespaces are a Dapr concept used for scoping applications and components. This example uses Kubernetes namespaces, however the Dapr component namespace scoping can be used on any supported platform. Read How-To: Scope components to one or more applications for more information on scoping components.

This example uses the PubSub sample. The Redis installation and the subscribers are in namespace-a while the publisher UI is in namespace-b. This solution will also work if Redis is installed on another namespace or if you use a managed cloud service like Azure ServiceBus, AWS SNS/SQS or GCP PubSub.

Authenticating to Azure

Mon, 01 Jan 0001 00:00:00 +0000

About authentication with Microsoft Entra ID

Microsoft Entra ID is Azure’s identity and access management (IAM) solution, which is used to authenticate and authorize users and services. It’s built on top of open standards such OAuth 2.0, which allows services (applications) to obtain access tokens to make requests to Azure services, including Azure Storage, Azure Service Bus, Azure Key Vault, Azure Cosmos DB, Azure Database for Postgres, Azure SQL, etc.

Overview of Dapr on Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

Dapr can be configured to run on any supported versions of Kubernetes. To achieve this, Dapr begins by deploying the following Kubernetes services, which provide first-class integration to make running applications with Dapr easy.

Kubernetes services	Description
`dapr-operator`	Manages component updates and Kubernetes services endpoints for Dapr (state stores, pub/subs, etc.)
`dapr-sidecar-injector`	Injects Dapr into annotated deployment pods and adds the environment variables `DAPR_HTTP_PORT` and `DAPR_GRPC_PORT` to enable user-defined applications to easily communicate with Dapr without hard-coding Dapr port values.
`dapr-placement`	Used for actors only. Creates mapping tables that map actor instances to pods
`dapr-sentry`	Manages mTLS between services and acts as a certificate authority. For more information read the security overview
`dapr-scheduler`	Provides distributed job scheduling capabilities used by the Jobs API, Workflow API, and Actor Reminders

Supported versions

Dapr support for Kubernetes is aligned with Kubernetes Version Skew Policy.

Overview of Dapr in self-hosted mode

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Dapr can be configured to run in self-hosted mode on your local developer machine or on production VMs. Each running service has a Dapr runtime process (or sidecar) which is configured to use state stores, pub/sub, binding components and the other building blocks.

Initialization

Dapr can be initialized with Docker (default) or in slim-init mode. It can also be initialized and run in offline or airgap environments.

Note

You can also use Podman in place of Docker as container runtime. Please refer dapr init with Podman for more details. It can be useful in the scenarios where docker cannot be installed due to various networking constraints.

The default Docker setup provides out of the box functionality with the following containers and configuration:

Performance results

Mon, 01 Jan 0001 00:00:00 +0000

For performance results see the Dapr performance test suite in the dapr/dapr repository, where you can view performance charts and numbers for each Dapr version and API.

Visit the performance charts directory to view detailed performance metrics, including latency, throughput, and resource utilization per API for different Dapr versions. Inside each folder you’ll find a README with performance highlights from several common use cases along with the corresponding performance charts to visualize the data.

Getting started with the Dapr actor Python SDK

Mon, 01 Jan 0001 00:00:00 +0000

The Dapr actor package allows you to interact with Dapr virtual actors from a Python application.

Pre-requisites

Dapr CLI installed
Initialized Dapr environment
Python 3.9+ installed
Dapr Python package installed

Actor interface

The interface defines the actor contract that is shared between the actor implementation and the clients calling the actor. Because a client may depend on it, it typically makes sense to define it in an assembly that is separate from the actor implementation.

Deploy Dapr on a Kubernetes cluster

Mon, 01 Jan 0001 00:00:00 +0000

When setting up Dapr on Kubernetes, you can use either the Dapr CLI or Helm.

Hybrid clusters

Both the Dapr CLI and the Dapr Helm chart automatically deploy with affinity for nodes with the label kubernetes.io/os=linux. You can deploy Dapr to Windows nodes if your application requires it. For more information, see Deploying to a hybrid Linux/Windows Kubernetes cluster.

Install with Dapr CLI

You can install Dapr on a Kubernetes cluster using the Dapr CLI.

Getting started with the Dapr Service (Callback) SDK for Go

Mon, 01 Jan 0001 00:00:00 +0000

Dapr gRPC Service SDK for Go

Prerequisite

Start by importing Dapr Go service/grpc package:

daprd "github.com/dapr/go-sdk/service/grpc"

Creating and Starting Service

To create a gRPC Dapr service, first, create a Dapr callback instance with a specific address:

s, err := daprd.NewService(":50001")
if err != nil {
 log.Fatalf("failed to start the server: %v", err)
}

Or with address and an existing net.Listener in case you want to combine existing server listener:

list, err := net.Listen("tcp", "localhost:0")
if err != nil {
	log.Fatalf("gRPC listener creation failed: %s", err)
}
s := daprd.NewServiceWithListener(list)

How to: Author and manage Dapr Conversation AI in the Java SDK

Mon, 01 Jan 0001 00:00:00 +0000

As part of this demonstration, we will look at how to use the Conversation API to converse with a Large Language Model (LLM). The API will return the response from the LLM for the given prompt. With the provided conversation ai example, you will:

You will provide a prompt using the Conversation AI example
Filter out Personally identifiable information (PII).

This example uses the default configuration from dapr init in self-hosted mode.

Prerequisites

Dapr CLI and initialized environment.
Java JDK 11 (or greater):
- Oracle JDK, or
- OpenJDK
Apache Maven, version 3.x.
Docker Desktop

Set up the environment

Clone the Java SDK repo and navigate into it.

How to: Author and manage Dapr Jobs in the Java SDK

Mon, 01 Jan 0001 00:00:00 +0000

As part of this demonstration we will schedule a Dapr Job. The scheduled job will trigger an endpoint registered in the same app. With the provided jobs example, you will:

Schedule a Job Job scheduling example
Register an endpoint for the dapr sidecar to invoke at trigger time Endpoint Registration

This example uses the default configuration from dapr init in self-hosted mode.

Prerequisites

Dapr CLI and initialized environment.
Java JDK 11 (or greater):
- Oracle JDK, or
- OpenJDK
Apache Maven, version 3.x.
Docker Desktop

Set up the environment

Clone the Java SDK repo and navigate into it.

How to: Author and manage Dapr Workflow in the Java SDK

Mon, 01 Jan 0001 00:00:00 +0000

Let’s create a Dapr workflow and invoke it using the console. With the provided workflow example, you will:

Execute the workflow instance using the Java workflow worker
Utilize the Java workflow client and API calls to start and terminate workflow instances

This example uses the default configuration from dapr init in self-hosted mode.

Prerequisites

Dapr CLI and initialized environment.
Java JDK 11 (or greater):
- Oracle JDK, or
- OpenJDK
Apache Maven, version 3.x.

Docker Desktop

Verify you’re using the latest proto bindings

Set up the environment

Clone the Java SDK repo and navigate into it.

How to: Use workload identity federation

Mon, 01 Jan 0001 00:00:00 +0000

This guide will help you configure your Kubernetes cluster to run Dapr with Azure workload identity federation.

What is it?

Workload identity federation is a way for your applications to authenticate to Azure without having to store or manage credentials as part of your releases.

By using workload identity federation, any Dapr components running on Kubernetes and AKS that target Azure can authenticate transparently with no extra configuration.

Guide

We’ll show how to configure an Azure Key Vault resource against your AKS cluster. You can adapt this guide for different Dapr Azure components by substituting component definitions as necessary.

How-To: Debug Dapr applications with Visual Studio Code

Mon, 01 Jan 0001 00:00:00 +0000

Deprecation notice

Manual debugging

When developing Dapr applications, you typically use the Dapr CLI to start your daprized service similar to this:

dapr run --app-id nodeapp --app-port 3000 --dapr-http-port 3500 app.js

One approach to attaching the debugger to your service is to first run daprd with the correct arguments from the command line and then launch your code and attach the debugger. While this is a perfectly acceptable solution, it does require a few extra steps and some instruction to developers who might want to clone your repo and hit the “play” button to begin debugging.

How-To: Run Dapr in self-hosted mode with Docker

Mon, 01 Jan 0001 00:00:00 +0000

This article provides guidance on running Dapr with Docker on a Windows/Linux/macOS machine or VM.

Prerequisites

Initialize Dapr environment

To initialize the Dapr control plane containers and create a default configuration file, run:

dapr init

Run both app and sidecar as a process

The dapr run CLI command can be used to launch a Dapr sidecar along with your application:

dapr run --app-id myapp --app-port 5000 -- dotnet run

This command will launch both the daprd sidecar binary and run dotnet run, launching your application.

How-To: Run Dapr in self-hosted mode with Podman

Mon, 01 Jan 0001 00:00:00 +0000

This article provides guidance on running Dapr with Podman on a Windows/Linux/macOS machine or VM.

Prerequisites

Initialize Dapr environment

To initialize the Dapr control plane containers and create a default configuration file, run:

dapr init --container-runtime podman

Run both app and sidecar as a process

The dapr run CLI command can be used to launch a Dapr sidecar along with your application:

dapr run --app-id myapp --app-port 5000 -- dotnet run

This command launches both the daprd sidecar and your application.

Developing Dapr applications with Dev Containers

Mon, 01 Jan 0001 00:00:00 +0000

Deprecation notice

The Visual Studio Code Dev Containers extension lets you use a self-contained Docker container as a complete development environment, without installing any additional packages, libraries, or utilities in your local filesystem.

Dapr has pre-built Dev Containers for C# and JavaScript/TypeScript; you can pick the one of your choice for a ready made environment. Note these pre-built containers automatically update to the latest Dapr release.

How to: Generate a new Microsoft Entra ID application and Service Principal

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

An Azure subscription
Azure CLI
jq
OpenSSL (included by default on all Linux and macOS systems, as well as on WSL)
Make sure you’re using a bash or zsh shell

Log into Azure using the Azure CLI

In a new terminal, run the following command:

az login
az account set -s [your subscription id]

Create an Microsoft Entra ID application

Create the Microsoft Entra ID application with:

# Friendly name for the application / Service Principal
APP_NAME="dapr-application"

# Create the app
APP_ID=$(az ad app create --display-name "${APP_NAME}" | jq -r .appId)

Select how you’d prefer to pass credentials.

How-To: Run Dapr in an offline or airgap environment

Mon, 01 Jan 0001 00:00:00 +0000

Overview

By default, Dapr initialization downloads binaries and pulls images from the network to setup the development environment. However, Dapr also supports offline or airgap installation using pre-downloaded artifacts, either with a Docker or slim environment. The artifacts for each Dapr release are built into a Dapr Installer Bundle which can be downloaded. By using this installer bundle with the Dapr CLI init command, you can install Dapr into environments that do not have any network access.

How-To: Run Dapr in self-hosted mode without Docker

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Install the Dapr CLI

Initialize Dapr without containers

The Dapr CLI provides an option to initialize Dapr using slim init, without the default creation of a development environment with a dependency on Docker. To initialize Dapr with slim init, after installing the Dapr CLI, use the following command:

dapr init --slim

Two different binaries are installed:

daprd
placement

The placement binary is needed to enable actors in a Dapr self-hosted installation.

Upgrade Dapr on a Kubernetes cluster

Mon, 01 Jan 0001 00:00:00 +0000

You can upgrade the Dapr control plane on a Kubernetes cluster using either the Dapr CLI or Helm.

Note

Refer to the Dapr version policy for guidance on Dapr’s upgrade path.

Upgrade using the Dapr CLI

You can upgrade Dapr using the Dapr CLI.

Getting started with the Dapr Workflow Python SDK

Mon, 01 Jan 0001 00:00:00 +0000

Let’s create a Dapr workflow and invoke it using the console. With the provided workflow example, you will:

Run a Python console application that demonstrates workflow orchestration with activities, child workflows, and external events
Learn how to handle retries, timeouts, and workflow state management
Use the Python workflow SDK to start, pause, resume, and purge workflow instances

This example uses the default configuration from dapr init in self-hosted mode.

In the Python example project, the simple.py file contains the setup of the app, including:

How to: Author and manage Dapr Workflow with Spring Boot

Mon, 01 Jan 0001 00:00:00 +0000

Following the same approach that we used for Spring Data and Spring Messaging, the dapr-spring-boot-starter brings Dapr Workflow integration for Spring Boot users.

With Dapr Workflows you define complex orchestrations (workflows) in Java code. The Dapr Spring Boot Starter makes your development easier by managing Workflows and WorkflowActivitys as Spring Beans.

In order to enable the automatic bean discovery you annotate your @SpringBootApplication with the @EnableDaprWorkflows annotation:

@SpringBootApplication
@EnableDaprWorkflows
public class MySpringBootApplication {
 ...
}

By adding this annotation, all the Workflows and WorkflowActivitys beans are automatically discovered by Spring and registered to the workflow engine.

How to: Use managed identities

Mon, 01 Jan 0001 00:00:00 +0000

Using managed identities, authentication happens automatically by virtue of your application running on top of an Azure service that has either a system-managed or a user-assigned identity.

To get started, you need to enable a managed identity as a service option/functionality in various Azure services, independent of Dapr. Enabling this creates an identity (or application) under the hood for Microsoft Entra ID (previously Azure Active Directory ID) purposes.

Your Dapr services can then leverage that identity to authenticate with Microsoft Entra ID, transparently and without you having to specify any credentials.

Production guidelines on Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

Cluster and capacity requirements

Dapr support for Kubernetes is aligned with Kubernetes Version Skew Policy.

Use the following resource settings as a starting point. Requirements vary depending on cluster size, number of pods, and other factors. Perform individual testing to find the right values for your environment. In production, it’s recommended to not add memory limits to the Dapr control plane components to avoid OOMKilled pod statuses.

Deployment	CPU	Memory
Operator	Limit: 1, Request: 100m	Request: 100Mi
Sidecar Injector	Limit: 1, Request: 100m	Request: 30Mi
Sentry	Limit: 1, Request: 100m	Request: 30Mi
Placement	Limit: 1, Request: 250m	Request: 75Mi

Note

For more information, refer to the Kubernetes documentation on CPU and Memory resource units and their meaning.

Helm

When installing Dapr using Helm, no default limit/request values are set. Each component has a resources option (for example, dapr_dashboard.resources), which you can use to tune the Dapr control plane to fit your environment.

Deploy Dapr per-node or per-cluster with Dapr Shared

Mon, 01 Jan 0001 00:00:00 +0000

Dapr automatically injects a sidecar to enable the Dapr APIs for your applications for the best availability and reliability.

Dapr Shared enables two alternative deployment strategies to create Dapr applications using a Kubernetes Daemonset for a per-node deployment or a Deployment for a per-cluster deployment.

DaemonSet: When running Dapr Shared as a Kubernetes DaemonSet resource, the daprd container runs on each Kubernetes node in the cluster. This can reduce network hops between the applications and Dapr.
Deployment: When running Dapr Shared as a Kubernetes Deployment, the Kubernetes scheduler decides on which single node in the cluster the daprd container instance runs.

Dapr Shared deployments

For each Dapr application you deploy, you need to deploy the Dapr Shared Helm chart using different shared.appIds.

Why Dapr Shared?

By default, when Dapr is installed into a Kubernetes cluster, the Dapr control plane injects Dapr as a sidecar to applications annotated with Dapr annotations ( dapr.io/enabled: "true"). Sidecars offer many advantages, including improved resiliency, since there is an instance per application and all communication between the application and the sidecar happens without involving the network.

How-to: Persist Scheduler Jobs

Mon, 01 Jan 0001 00:00:00 +0000

The Scheduler service is responsible for writing jobs to its Etcd database and scheduling them for execution. By default, the Scheduler service database embeds Etcd and writes data to a Persistent Volume Claim volume of size 1Gb, using the cluster’s default storage class. This means that there is no additional parameter required to run the scheduler service reliably on most Kubernetes deployments, although you will need additional configuration if a default StorageClass is not available or when running a production environment.

How-to: Persist Scheduler Jobs

Mon, 01 Jan 0001 00:00:00 +0000

The Scheduler service is responsible for writing jobs to its Etcd database and scheduling them for execution. By default, the Scheduler service database writes this data to the local volume dapr_scheduler, meaning that this data is persisted across restarts.

The host file location for this local volume is typically located at either /var/lib/docker/volumes/dapr_scheduler/_data or ~/.local/share/containers/storage/volumes/dapr_scheduler/_data, depending on your container runtime. Note that if you are using Docker Desktop, this volume is located in the Docker Desktop VM’s filesystem, which can be accessed using:

Steps to upgrade Dapr in a self-hosted environment

Mon, 01 Jan 0001 00:00:00 +0000

Uninstall the current Dapr deployment:

Note
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 and install the latest CLI by visiting this guide.
Initialize the Dapr runtime:
```
dapr init
```
Ensure you are using the latest version of Dapr (v1.16.9)) with:
```
$ dapr --version

CLI version: 1.16
Runtime version: 1.16
```

Dapr AI Client

Mon, 01 Jan 0001 00:00:00 +0000

The Dapr AI client package allows you to interact with the AI capabilities provided by the Dapr sidecar.

Note

The Dapr Conversation building block requires Dapr runtime v1.16.0 or later. Response format, prompt cache retention, and token usage statistics require Dapr runtime v1.17.0 or later.

Lifetime management

A DaprConversationClient is a version of the Dapr client that is dedicated to interacting with the Dapr Conversation API. It can be registered alongside a DaprClient and other Dapr clients without issue.

How to: Create and use Dapr AI Conversations in the .NET SDK

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Installation

To get started with the Dapr AI .NET SDK client, install the Dapr.AI package from NuGet:

dotnet add package Dapr.AI

A DaprConversationClient maintains access to networking resources in the form of TCP sockets used to communicate with the Dapr sidecar.

Dependency Injection

The AddDaprAiConversation() method will register the Dapr client ASP.NET Core dependency injection and is the recommended approach for using this package. This method accepts an optional options delegate for configuring the DaprConversationClient and a ServiceLifetime argument, allowing you to specify a different lifetime for the registered services instead of the default Singleton value.

How to: Using Microsoft's AI extensions with Dapr's .NET Conversation SDK

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Installation

To get started with this SDK, install both the Dapr.AI and Dapr.AI.Microsoft.Extensions packages from NuGet:

dotnet add package Dapr.AI
dotnet add package Dapr.AI.Microsoft.Extensions

The DaprChatClient is a Dapr-based implementation of the IChatClient interface provided in the Microsoft.Extensions.AI.Abstractions package using Dapr’s [conversation building block]({{ ref conversation-overview.md }}). It allows developers to build against the types provided by Microsoft’s abstraction while providing the greatest conformity to the Dapr conversation building block available. As both approaches adopt OpenAI’s API approach, these are expected to increasingly converge over time.

How to: Author and manage Dapr Jobs in the .NET SDK

Mon, 01 Jan 0001 00:00:00 +0000

Let’s create an endpoint that will be invoked by Dapr Jobs when it triggers, then schedule the job in the same app. We’ll use the simple example provided here, for the following demonstration and walk through it as an explainer of how you can schedule one-time or recurring jobs using either an interval or Cron expression yourself. In this guide, you will:

Deploy a .NET Web API application (JobsSample)
Utilize the Dapr .NET Jobs SDK to schedule a job invocation and set up the endpoint to be triggered

In the .NET example project:

How to: Manage secrets with the Dapr Secrets Management .NET SDK

Mon, 01 Jan 0001 00:00:00 +0000

Let’s walk through how to retrieve secrets from a Dapr secret store using the Dapr.SecretsManagement package. We’ll use the sample project provided here for the following demonstration, covering direct secret retrieval, bulk secret retrieval, and strongly-typed access via the included source generator. In this guide, you will:

Deploy a .NET Web API application (SecretManagementSample)
Utilize the Dapr .NET Secrets Management SDK to retrieve individual and bulk secrets
Use the source generator to create a strongly-typed interface for your secret store

In the .NET example project:

DaprSecretsManagementClient usage

Mon, 01 Jan 0001 00:00:00 +0000

Lifetime management

A DaprSecretsManagementClient is a subset of the Dapr client that is dedicated to interacting with the Dapr Secrets API. It can be registered alongside a DaprClient and other Dapr clients without issue.

It maintains access to networking resources in the form of TCP sockets used to communicate with the Dapr sidecar and implements IDisposable to support the eager cleanup of resources.

For best performance, create a single long-lived instance of DaprSecretsManagementClient and provide access to that shared instance throughout your application. DaprSecretsManagementClient instances are thread-safe and intended to be shared.

How to: Manage state with the Dapr State Management .NET SDK

Mon, 01 Jan 0001 00:00:00 +0000

Let’s walk through how to manage state using the Dapr.StateManagement package. We’ll use the sample project provided here for the following demonstration, covering typed state store clients via the source generator, direct client usage for bulk operations and transactions, and optimistic concurrency control with ETags. In this guide, you will:

Deploy a .NET application (StateManagementExample)
Utilize the Dapr .NET State Management SDK to save, retrieve, and delete state entries
Use ETags for optimistic concurrency control
Perform bulk operations and state transactions
Use the source generator to create a strongly-typed, store-scoped interface

In the .NET example project:

DaprStateManagementClient usage

Mon, 01 Jan 0001 00:00:00 +0000

Lifetime management

A DaprStateManagementClient holds long-lived network resources (gRPC channels, HTTP connections). For best performance:

Register a single shared instance and reuse it for the lifetime of the application.
Avoid creating and disposing a client per operation — this can lead to socket exhaustion.
The DI registration via AddDaprStateManagementClient() defaults to ServiceLifetime.Singleton, which is the recommended approach for most applications.

The client is thread-safe and can be shared across concurrent requests.

DaprJobsClient usage

Mon, 01 Jan 0001 00:00:00 +0000

Lifetime management

A DaprJobsClient is a version of the Dapr client that is dedicated to interacting with the Dapr Jobs API. It can be registered alongside a DaprClient and other Dapr clients without issue.

It maintains access to networking resources in the form of TCP sockets used to communicate with the Dapr sidecar and implements IDisposable to support the eager cleanup of resources.

For best performance, create a single long-lived instance of DaprJobsClient and provide access to that shared instance throughout your application. DaprJobsClient instances are thread-safe and intended to be shared.

Uninstall Dapr in a self-hosted environment

Mon, 01 Jan 0001 00:00:00 +0000

The following CLI command removes the Dapr sidecar binaries and the placement container:

dapr uninstall

The above command will not remove the Redis or Zipkin containers that were installed during dapr init by default, just in case you were using them for other purposes. To remove Redis, Zipkin, Actor Placement container, as well as the default Dapr directory located at $HOME/.dapr or %USERPROFILE%\.dapr\, run:

dapr uninstall --all

Note

For Linux/MacOS users, if you run your docker cmds with sudo or the install path is /usr/local/bin(default install path), you need to use sudo dapr uninstall to remove dapr binaries and/or the containers.

How to: Author and manage Dapr streaming subscriptions in the .NET SDK

Mon, 01 Jan 0001 00:00:00 +0000

Let’s create a subscription to a pub/sub topic or queue at using the streaming capability. We’ll use the simple example provided here, for the following demonstration and walk through it as an explainer of how you can configure message handlers at runtime and which do not require an endpoint to be pre-configured. In this guide, you will:

Deploy a .NET Web API application (StreamingSubscriptionExample)
Utilize the Dapr .NET Messaging SDK to subscribe dynamically to a pub/sub topic.

Prerequisites

Dapr CLI
Initialized Dapr environment
.NET 8, .NET 9, or .NET 10 installed
Dapr.Messaging NuGet package installed to your project

Set up the environment

Clone the .NET SDK repo.

How to: Create and use Dapr Distributed Lock in the .NET SDK

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Installation

To get started with the Dapr Distributed lock .NET SDK client, install the Dapr.Distributed Lock package from NuGet:

dotnet add package Dapr.DistributedLock

A DaprDistributedLockClient maintains access to networking resources in the form of TCP sockets used to communicate with the Dapr sidecar.

Dependency Injection

The AddDaprDistributedLock() method will register the Dapr client ASP.NET Core dependency injection and is the recommended approach for using this package. This method accepts an optional options delegate for configuring the DaprDistributedLockClient and a ServiceLifetime argument, allowing you to specify a different lifetime for the registered services instead of the default Singleton value.

DaprPublishSubscribeClient usage

Mon, 01 Jan 0001 00:00:00 +0000

Lifetime management

A DaprPublishSubscribeClient is a version of the Dapr client that is dedicated to interacting with the Dapr Messaging API. It can be registered alongside a DaprClient and other Dapr clients without issue.

It maintains access to networking resources in the form of TCP sockets used to communicate with the Dapr sidecar and implements IAsyncDisposable to support the eager cleanup of resources.

For best performance, create a single long-lived instance of DaprPublishSubscribeClient and provide access to that shared instance throughout your application. DaprPublishSubscribeClient instances are thread-safe and intended to be shared.

Deploy to hybrid Linux/Windows Kubernetes clusters

Mon, 01 Jan 0001 00:00:00 +0000

Dapr supports running your microservices on Kubernetes clusters on:

Windows
Linux
A combination of both

This is especially helpful during a piecemeal migration of a legacy application into a Dapr Kubernetes cluster.

Kubernetes uses a concept called node affinity to denote whether you want your application to be launched on a Linux node or a Windows node. When deploying to a cluster which has both Windows and Linux nodes, you must provide affinity rules for your applications, otherwise the Kubernetes scheduler might launch your application on the wrong type of node.

Running Dapr with a Kubernetes Job

Mon, 01 Jan 0001 00:00:00 +0000

The Dapr sidecar is designed to be a long running process. In the context of a Kubernetes Job this behavior can block your job completion.

Native sidecars

On Kubernetes 1.28+, you can enable native sidecars to ensure daprd operates as a Kubernetes native sidecar and follows its shutdown semantics.

When running a basic Kubernetes Job, you need to call the /shutdown endpoint for the sidecar to gracefully stop and the job to be considered Completed.

Error Model in the Dapr .NET SDK

Mon, 01 Jan 0001 00:00:00 +0000

The Dapr .NET SDK supports the richer error model, implemented by the Dapr runtime. This model provides a way for applications to enrich their errors with added context, allowing consumers of the application to better understand the issue and resolve it faster. You can read more about the richer error model here, and you can find the Dapr proto file implementing these errors here.

The Dapr .NET SDK implements all details supported by the Dapr runtime, implemented in the Dapr.Common.Exceptions namespace, and is accessible through the DaprException extension method TryGetExtendedErrorInfo. Currently, this detail extraction is only supported for RpcExceptions where the details are present.

Experimental Attributes

Mon, 01 Jan 0001 00:00:00 +0000

Experimental Attributes

Introduction to Experimental Attributes

With the release of .NET 8, C# 12 introduced the [Experimental] attribute, which provides a standardized way to mark APIs that are still in development or experimental. This attribute is defined in the System.Diagnostics.CodeAnalysis namespace and requires a diagnostic ID parameter used to generate compiler warnings when the experimental API is used.

In the Dapr .NET SDK, we now use the [Experimental] attribute instead of [Obsolete] to mark building blocks and components that have not yet passed the stable lifecycle certification. This approach provides a clearer distinction between:

Integration testing with Dapr.Testcontainers

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Dapr.Testcontainers is a helper package for writing integration tests against real Dapr runtime components using containers. It wraps the Testcontainers library to spin up Dapr sidecars, control plane services (placement and scheduler), and the infrastructure needed by specific Dapr building blocks.

Important

Dapr.Testcontainers is an initial release. The API is still evolving and may change in future versions. We aim to keep changes minimal, but you should expect potential breaking changes while the package matures.

Packages

Dapr.Testcontainers (core harnesses and infrastructure)
Dapr.Testcontainers.Xunit (optional xUnit helpers)

Prerequisites

A container runtime (Docker Desktop, Podman, or equivalent).
Network access to pull Dapr and dependency images.

Core concepts

Dapr.Testcontainers models tests around environments and harnesses:

Dapr source code analyzers and generators

Mon, 01 Jan 0001 00:00:00 +0000

Dapr supports a growing collection of optional Roslyn analyzers and code fix providers that inspect your code for code quality issues. Starting with the release of v1.16, developers have the opportunity to install additional projects from NuGet alongside each of the standard capability packages to enable these analyzers in their solutions.

Note

A future release of the Dapr .NET SDK will include these analyzers by default without requiring a separate package install.

Rule violations will typically be marked as Info or Warning so that if the analyzer identifies an issue, it won’t necessarily break builds. All code analysis violations appear with the prefix “DAPR” and are uniquely distinguished by a number following this prefix.

How-to: Mount Pod volumes to the Dapr sidecar

Mon, 01 Jan 0001 00:00:00 +0000

The Dapr sidecar can be configured to mount any Kubernetes Volume attached to the application Pod. These Volumes can be accessed by the daprd (sidecar) container in read-only or read-write modes. If a Volume is configured to be mounted but it does not exist in the Pod, Dapr logs a warning and ignores it.

For more information on different types of Volumes, check the Kubernetes documentation.

Configuration

You can set the following annotations in your deployment YAML:

Dapr .NET SDK Development with Dapr CLI

Mon, 01 Jan 0001 00:00:00 +0000

Dapr CLI

Consider this to be a .NET companion to the Dapr Self-Hosted with Docker Guide.

The Dapr CLI provides you with a good base to work from by initializing a local redis container, zipkin container, the placement service, and component manifests for redis. This will enable you to work with the following building blocks on a fresh install with no additional setup:

You can run .NET services with dapr run as your strategy for developing locally. Plan on running one of these commands per-service in order to launch your application.

Dapr .NET SDK Development with Docker-Compose

Mon, 01 Jan 0001 00:00:00 +0000

Docker-Compose

Consider this to be a .NET companion to the Dapr Self-Hosted with Docker Guide.

docker-compose is a CLI tool included with Docker Desktop that you can use to run multiple containers at a time. It is a way to automate the lifecycle of multiple containers together, and offers a development experience similar to a production environment for applications targeting Kubernetes.

Pro: Since docker-compose manages containers for you, you can make dependencies part of the application definition and stop the long-running containers on your machine.
Con: most investment required, services need to be containerized to get started.
Con: can be difficult to debug and troubleshoot if you are unfamilar with Docker.

Using docker-compose

From the .NET perspective, there is no specialized guidance needed for docker-compose with Dapr. docker-compose runs containers, and once your service is in a container, configuring it similar to any other programming technology.

Dapr .NET SDK Development with .NET Aspire

Mon, 01 Jan 0001 00:00:00 +0000

.NET Aspire

.NET Aspire is a development tool designed to make it easier to include external software into .NET applications by providing a framework that allows third-party services to be readily integrated, observed and provisioned alongside your own software.

Aspire simplifies local development by providing rich integration with popular IDEs including Microsoft Visual Studio, Visual Studio Code, JetBrains Rider and others to launch your application with the debugger while automatically launching and provisioning access to other integrations as well, including Dapr.

The IActorProxyFactory interface

Mon, 01 Jan 0001 00:00:00 +0000

Inside of an Actor class or an ASP.NET Core project, the IActorProxyFactory interface is recommended to create actor clients.

The AddActors(...) method will register actor services with ASP.NET Core dependency injection.

Outside of an actor instance: The IActorProxyFactory instance is available through dependency injection as a singleton service.
Inside an actor instance: The IActorProxyFactory instance is available as a property (this.ProxyFactory).

The following is an example of creating a proxy inside an actor:

DaprClient usage

Mon, 01 Jan 0001 00:00:00 +0000

Lifetime management

A DaprClient holds access to networking resources in the form of TCP sockets used to communicate with the Dapr sidecar. DaprClient implements IDisposable to support eager cleanup of resources.

Dependency Injection

The AddDaprClient() method will register the Dapr client with ASP.NET Core dependency injection. This method accepts an optional options delegate for configuring the DaprClient and an ServiceLifetime argument, allowing you to specify a different lifetime for the registered resources instead of the default Singleton value.

Getting started with the Dapr Python gRPC service extension

Mon, 01 Jan 0001 00:00:00 +0000

The Dapr Python SDK provides a built in gRPC server extension, dapr.ext.grpc, for creating Dapr services.

Installation

You can download and install the Dapr gRPC server extension with:

pip install dapr-ext-grpc

Note

The development package will contain features and behavior that will be compatible with the pre-release version of the Dapr runtime. Make sure to uninstall any stable versions of the Python SDK extension before installing the <code>dapr-dev</code> package.

pip3 install dapr-ext-grpc-dev

Examples

The App object can be used to create a server.

Troubleshoot Pub/Sub with the .NET SDK

Mon, 01 Jan 0001 00:00:00 +0000

Troubleshooting Pub/Sub

The most common problem with pub/sub is that the pub/sub endpoint in your application is not being called.

There are a few layers to this problem with different solutions:

The application is not receiving any traffic from Dapr
The application is not registering pub/sub endpoints with Dapr
The pub/sub endpoints are registered with Dapr, but the request is not reaching the desired endpoint

Step 1: Turn up the logs

This is important. Future steps will depend on your ability to see logging output. ASP.NET Core logs almost nothing with the default log settings, so you will need to change it.

Author & run actors

Mon, 01 Jan 0001 00:00:00 +0000

Author actors

ActorHost

The ActorHost:

Is a required constructor parameter of all actors
Is provided by the runtime
Must be passed to the base class constructor
Contains all of the state that allows that actor instance to communicate with the runtime

internal class MyActor : Actor, IMyActor, IRemindable
{
 public MyActor(ActorHost host) // Accept ActorHost in the constructor
 : base(host) // Pass ActorHost to the base class constructor
 {
 }
}

Since the ActorHost contains state unique to the actor, you don’t need to pass the instance into other parts of your code. It’s recommended only create your own instances of ActorHost in tests.

Dapr Python SDK integration with FastAPI

Mon, 01 Jan 0001 00:00:00 +0000

The Dapr Python SDK provides integration with FastAPI using the dapr-ext-fastapi extension.

Installation

You can download and install the Dapr FastAPI extension with:

pip install dapr-ext-fastapi

Note

The development package will contain features and behavior that will be compatible with the pre-release version of the Dapr runtime. Make sure to uninstall any stable versions of the Python SDK extension before installing the <code>dapr-dev</code> package.

pip install dapr-ext-fastapi-dev

Example

Subscribing to events of different types

import uvicorn
from fastapi import Body, FastAPI
from dapr.ext.fastapi import DaprApp
from pydantic import BaseModel

class RawEventModel(BaseModel):
 body: str

class User(BaseModel):
 id: int
 name: str

class CloudEventModel(BaseModel):
 data: User
 datacontenttype: str
 id: str
 pubsubname: str
 source: str
 specversion: str
 topic: str
 traceid: str
 traceparent: str
 tracestate: str
 type: str 
 
 
app = FastAPI()
dapr_app = DaprApp(app)

# Allow handling event with any structure (Easiest, but least robust)
# dapr publish --publish-app-id sample --topic any_topic --pubsub pubsub --data '{"id":"7", "desc": "good", "size":"small"}'
@dapr_app.subscribe(pubsub='pubsub', topic='any_topic')
def any_event_handler(event_data = Body()):
 print(event_data) 

# For robustness choose one of the below based on if publisher is using CloudEvents

# Handle events sent with CloudEvents
# dapr publish --publish-app-id sample --topic cloud_topic --pubsub pubsub --data '{"id":"7", "name":"Bob Jones"}'
@dapr_app.subscribe(pubsub='pubsub', topic='cloud_topic')
def cloud_event_handler(event_data: CloudEventModel):
 print(event_data) 

# Handle raw events sent without CloudEvents
# curl -X "POST" http://localhost:3500/v1.0/publish/pubsub/raw_topic?metadata.rawPayload=true -H "Content-Type: application/json" -d '{"body": "345"}'
@dapr_app.subscribe(pubsub='pubsub', topic='raw_topic')
def raw_event_handler(event_data: RawEventModel):
 print(event_data) 

 

if __name__ == "__main__":
 uvicorn.run(app, host="0.0.0.0", port=30212)

Creating an actor

from fastapi import FastAPI
from dapr.ext.fastapi import DaprActor
from demo_actor import DemoActor

app = FastAPI(title=f'{DemoActor.__name__}Service')

# Add Dapr Actor Extension
actor = DaprActor(app)

@app.on_event("startup")
async def startup_event():
 # Register DemoActor
 await actor.register_actor(DemoActor)

@app.get("/GetMyData")
def get_my_data():
 return "{'message': 'myData'}"

Actor serialization in the .NET SDK

Mon, 01 Jan 0001 00:00:00 +0000

Actor Serialization

The Dapr actor package enables you to use Dapr virtual actors within a .NET application with either a weakly- or strongly-typed client. Each utilizes a different serialization approach. This document will review the differences and convey a few key ground rules to understand in either scenario.

Please be advised that it is not a supported scenario to use the weakly- or strongly typed actor clients interchangeably because of these different serialization approaches. The data persisted using one Actor client will not be accessible using the other Actor client, so it is important to pick one and use it consistently throughout your application.

Dapr Python SDK integration with Flask

Mon, 01 Jan 0001 00:00:00 +0000

The Dapr Python SDK provides integration with Flask using the flask-dapr extension.

Installation

You can download and install the Dapr Flask extension with:

pip install flask-dapr

Note

The development package will contain features and behavior that will be compatible with the pre-release version of the Dapr runtime. Make sure to uninstall any stable versions of the Python SDK extension before installing the <code>dapr-dev</code> package.

pip install flask-dapr-dev

Example

from flask import Flask
from flask_dapr.actor import DaprActor

from dapr.conf import settings
from demo_actor import DemoActor

app = Flask(f'{DemoActor.__name__}Service')

# Enable DaprActor Flask extension
actor = DaprActor(app)

# Register DemoActor
actor.register_actor(DemoActor)

# Setup method route
@app.route('/GetMyData', methods=['GET'])
def get_my_data():
 return {'message': 'myData'}, 200

# Run application
if __name__ == '__main__':
 app.run(port=settings.HTTP_APP_PORT)

How to: Run and use virtual actors in the .NET SDK

Mon, 01 Jan 0001 00:00:00 +0000

The Dapr actor package allows you to interact with Dapr virtual actors from a .NET application. In this guide, you learn how to:

Create an Actor (MyActor).
Invoke its methods on the client application.

MyActor --- MyActor.Interfaces
 |
 +- MyActorService
 |
 +- MyActorClient

The interface project (\MyActor\MyActor.Interfaces)

This project contains the interface definition for the actor. Actor interfaces can be defined in any project with any name. The interface defines the actor contract shared by:

Dapr Cryptography Client

Mon, 01 Jan 0001 00:00:00 +0000

The Dapr Cryptography package allows you to perform encryption and decryption operations provided by the Dapr sidecar.

Lifetime management

A DaprEncryptionClient is a version of the Dapr client that is dedicated to interacting with the Dapr Cryptography API. It can be registered alongside a DaprClient and other Dapr clients without issue.

It maintains access to networking resources in the form of TCP sockets used to communicate with the Dapr sidecar.

How to: Create and use Dapr Cryptography in the .NET SDK

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Installation

To get started with the Dapr Cryptography client, install the Dapr.Cryptography package from NuGet:

dotnet add package Dapr.Cryptography

A DaprEncryptionClient maintains access to networking resources in the form of TCP sockets used to communicate with the Dapr sidecar.

Dependency Injection

The AddDaprEncryptionClient() method will register the Dapr client with dependency injection and is the recommended approach for using this package. This method accepts an optional options delegate for configuring the DaprEncryptionClient and a ServiceLifetime argument, allowing you to specify a different lifetime for the registered services instead of the default Singleton value.

Mon, 01 Jan 0001 00:00:00 +0000

title: “Conversation API (Python) – Recommended Usage” linkTitle: “Conversation” weight: 11000 type: docs description: Recommended patterns for using Dapr Conversation API in Python with and without tools, including multi‑turn flows and safety guidance.

The Dapr Conversation API is currently in alpha. This page presents the recommended, minimal patterns to use it effectively with the Python SDK:

Plain requests (no tools)
Requests with tools (functions as tools)
Multi‑turn flows with tool execution
Async variants
Important safety notes for executing tool calls

Prerequisites

Dapr CLI installed
Initialized Dapr environment
Python 3.9+ installed
Dapr Python package installed
A configured LLM component (for example, OpenAI or Azure OpenAI) in your Dapr environment

For full, end‑to‑end flows and provider setup, see:

Aerospike

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Aerospike state store create a component of type state.Aerospike. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.Aerospike
 version: v1
 metadata:
 - name: hosts
 value: <REPLACE-WITH-HOSTS> # Required. A comma delimited string of hosts. Example: "aerospike:3000,aerospike2:3000"
 - name: namespace
 value: <REPLACE-WITH-NAMESPACE> # Required. The aerospike namespace.
 - name: set
 value: <REPLACE-WITH-SET> # Optional

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
hosts	Y	Host name/port of database server	`"localhost:3000"`, `"aerospike:3000,aerospike2:3000"`
namespace	Y	The Aerospike namespace	`"namespace"`
set	N	The setName in the database	`"myset"`

Setup Aerospike

You can run Aerospike locally using Docker:

Alibaba Cloud DingTalk binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Setup Dapr component

To setup an Alibaba Cloud DingTalk binding create a component of type bindings.dingtalk.webhook. See this guide on how to create and apply a secretstore configuration. See this guide on referencing secrets to retrieve and use the secret with Dapr components.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.dingtalk.webhook
 version: v1
 metadata:
 - name: id
 value: "test_webhook_id"
 - name: url
 value: "https://oapi.dingtalk.com/robot/send?access_token=******"
 - name: secret
 value: "****************"
 - name: direction
 value: "input, output"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`id`	Y	Input/Output	Unique id	`"test_webhook_id"`
`url`	Y	Input/Output	DingTalk’s Webhook url	`"https://oapi.dingtalk.com/robot/send?access_token=******"`
`secret`	N	Input/Output	The secret of DingTalk’s Webhook	`"****************"`
`direction`	N	Input/Output	The direction of the binding	`"input"`, `"output"`, `"input, output"`

Binding support

This component supports both input and output binding interfaces.

Alibaba Cloud Log Storage Service binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup an Alibaba Cloud SLS binding create a component of type bindings.alicloud.sls. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: alicloud.sls
spec:
 type: bindings.alicloud.sls
 version: v1
 metadata:
 - name: AccessKeyID
 value: "[accessKey-id]"
 - name: AccessKeySecret
 value: "[accessKey-secret]"
 - name: Endpoint
 value: "[endpoint]"

Spec metadata fields

Field	Required	Binding support	Details
`AccessKeyID`	Y	Output	Access key ID credential.
`AccessKeySecret`	Y	Output	Access key credential secret
`Endpoint`	Y	Output	Alicloud SLS endpoint.

Binding support

This component supports output binding with the following operations:

Alibaba Cloud Object Storage Service binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup an Alibaba Cloud Object Storage binding create a component of type bindings.alicloud.oss. See this guide on how to create and apply a secretstore configuration. See this guide on referencing secrets to retrieve and use the secret with Dapr components.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: alicloudobjectstorage
spec:
 type: bindings.alicloud.oss
 version: v1
 metadata:
 - name: endpoint
 value: "[endpoint]"
 - name: accessKeyID
 value: "[key-id]"
 - name: accessKey
 value: "[access-key]"
 - name: bucket
 value: "[bucket]"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`endpoint`	Y	Output	Alicloud OSS endpoint.	https://oss-cn-hangzhou.aliyuncs.com
`accessKeyID`	Y	Output	Access key ID credential.
`accessKey`	Y	Output	Access key credential.
`bucket`	Y	Output	Name of the storage bucket.

Binding support

This component supports output binding with the following operations:

Alibaba Cloud Tablestore binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup an Alibaba Cloud Tablestore binding create a component of type bindings.alicloud.tablestore. See this guide on how to create and apply a secretstore configuration. See this guide on referencing secrets to retrieve and use the secret with Dapr components.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: mytablestore
spec:
 type: bindings.alicloud.tablestore
 version: v1
 metadata:
 - name: endpoint
 value: "[endpoint]"
 - name: accessKeyID
 value: "[key-id]"
 - name: accessKey
 value: "[access-key]"
 - name: instanceName
 value: "[instance]"
 - name: tableName
 value: "[table]"
 - name: endpoint
 value: "[endpoint]"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`endpoint`	Y	Output	Alicloud Tablestore endpoint.	https://tablestore-cn-hangzhou.aliyuncs.com
`accessKeyID`	Y	Output	Access key ID credential.
`accessKey`	Y	Output	Access key credential.
`instanceName`	Y	Output	Name of the instance.
`tableName`	Y	Output	Name of the table.

Binding support

This component supports output binding with the following operations:

Alibaba Cloud TableStore

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up an Alibaba Cloud TableStore state store, create a component of type state.alicloud.tablestore. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.alicloud.tablestore
 version: v1
 metadata:
 - name: endpoint
 value: <REPLACE-WITH-ENDPOINT>
 - name: instanceName
 value: <REPLACE-WITH-INSTANCE-NAME>
 - name: tableName
 value: <REPLACE-WITH-TABLE-NAME>
 - name: accessKeyID
 value: <REPLACE-WITH-ACCESS-KEY-ID>
 - name: accessKey
 value: <REPLACE-WITH-ACCESS-KEY>

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
`endpoint`	Y	The endpoint of the Alibaba Cloud TableStore instance	`"https://tablestore.aliyuncs.com"`
`instanceName`	Y	The name of the Alibaba Cloud TableStore instance	`"my_instance"`
`tableName`	Y	The name of the table to use for Dapr state. Will be created if it does not exist	`"my_table"`
`accessKeyID`	Y	The access key ID for authentication	`"my_access_key_id"`
`accessKey`	Y	The access key for authentication	`"my_access_key"`

Authentication

Alibaba Cloud TableStore supports authentication using an Access Key and Access Key ID.

AlibabaCloud OOS Parameter Store

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup AlibabaCloud OOS Parameter Store secret store create a component of type secretstores.alicloud.parameterstore. See this guide on how to create and apply a secretstore configuration. See this guide on referencing secrets to retrieve and use the secret with Dapr components.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: alibabacloudparameterstore
spec:
 type: secretstores.alicloud.parameterstore
 version: v1
 metadata:
 - name: regionId
 value: "[alicloud_region_id]"
 - name: accessKeyId 
 value: "[alicloud_access_key_id]"
 - name: accessKeySecret
 value: "[alicloud_access_key_secret]"
 - name: securityToken
 value: "[alicloud_security_token]"

Warning

The above example uses secrets as plain strings. It is recommended to use a local secret store such as Kubernetes secret store or a local file to bootstrap secure key storage.

Spec metadata fields

Field	Required	Details	Example
regionId	Y	The specific region the AlibabaCloud OOS Parameter Store instance is deployed in	`"cn-hangzhou"`
accessKeyId	Y	The AlibabaCloud Access Key ID to access this resource	`"accessKeyId"`
accessKeySecret	Y	The AlibabaCloud Access Key Secret to access this resource	`"accessKeySecret"`
securityToken	N	The AlibabaCloud Security Token to use	`"securityToken"`

Optional per-request metadata properties

The following optional query parameters can be provided when retrieving secrets from this secret store:

annotate CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

Add Dapr annotations to a Kubernetes configuration. This enables you to add/change the Dapr annotations on a deployment files. See Kubernetes annotations for a full description of each annotation available in the following list of flags.

Supported platforms

Kubernetes

Usage

dapr annotate [flags] CONFIG-FILE

Flags

Name	Default	Description
`--kubernetes, -k`		Apply annotations to Kubernetes resources. Required
`--api-token-secret`		The secret to use for the API token
`--app-id, -a`		The app id to annotate
`--app-max-concurrency`	`-1`	The maximum number of concurrent requests to allow
`--app-port, -p`	`-1`	The port to expose the app on
`--app-protocol`		The protocol to use for the app: `http` (default), `grpc`, `https`, `grpcs`, `h2c`
`--app-token-secret`		The secret to use for the app token
`--config, -c`		The config file to annotate
`--cpu-limit`		The CPU limit to set for the sidecar. See valid values here.
`--cpu-request`		The CPU request to set for the sidecar. See valid values here.
`--dapr-image`		The image to use for the dapr sidecar container
`--enable-debug`	`false`	Enable debug
`--enable-metrics`	`false`	Enable metrics
`--enable-profile`	`false`	Enable profiling
`--env`		Environment variables to set (key value pairs, comma separated)
`--graceful-shutdown-seconds`	`-1`	The number of seconds to wait for the app to shutdown
`--help, -h`		help for annotate
`--listen-addresses`		The addresses for sidecar to listen on. To listen to all IPv4 addresses, use `0.0.0.0`. To listen to all IPv6 addresses, use `[::]`.
`--liveness-probe-delay`	`-1`	The delay for sidecar to use for the liveness probe. Read more here.
`--liveness-probe-period`	`-1`	The period used by the sidecar for the liveness probe. Read more here.
`--liveness-probe-threshold`	`-1`	The threshold used by the sidecar for the liveness probe. Read more here.
`--liveness-probe-timeout`	`-1`	The timeout used by the sidecar for the liveness probe. Read more here.
`--log-level`		The log level to use
`--max-request-body-size`	`-1`	The maximum request body size to use
`--http-read-buffer-size`	`-1`	The maximum size of HTTP header read buffer in kilobytes
`--memory-limit`		The memory limit to set for the sidecar. See valid values here
`--memory-request`		The memory request to set for the sidecar
`--metrics-port`	`-1`	The port to expose the metrics on
`--namespace, -n`		The namespace the resource target is in (can only be set if `--resource` is also set)
`--readiness-probe-delay`	`-1`	The delay to use for the readiness probe in the sidecar. Read more here.
`--readiness-probe-period`	`-1`	The period to use for the readiness probe in the sidecar. Read more here.
`--readiness-probe-threshold`	`-1`	The threshold to use for the readiness probe in the sidecar. Read more here.
`--readiness-probe-timeout`	`-1`	The timeout to use for the readiness probe in the sidecar. Read more here.
`--resource, -r`		The Kubernetes resource target to annotate
`--enable-api-logging`		Enable API logging for the Dapr sidecar
`--unix-domain-socket-path`		Linux domain socket path to use for communicating with the Dapr sidecar
`--volume-mounts`		List of pod volumes to be mounted to the sidecar container in read-only mode
`--volume-mounts-rw`		List of pod volumes to be mounted to the sidecar container in read-write mode
`--disable-builtin-k8s-secret-store`		Disable the built-in Kubernetes secret store
`--placement-host-address`		Comma separated list of addresses for Dapr actor placement servers

Warning

If an application ID is not provided using --app-id, -a, an ID is generated using the format <namespace>-<kind>-<name>.

Examples

# Annotate the first deployment found in the input
kubectl get deploy -l app=node -o yaml | dapr annotate -k - | kubectl apply -f -

# Annotate multiple deployments by name in a chain
kubectl get deploy -o yaml | dapr annotate -k -r nodeapp - | dapr annotate -k -r pythonapp - | kubectl apply -f -

# Annotate deployment in a specific namespace from file or directory by name
dapr annotate -k -r nodeapp -n namespace mydeploy.yaml | kubectl apply -f -

# Annotate deployment from url by name
dapr annotate -k -r nodeapp --log-level debug https://raw.githubusercontent.com/dapr/quickstarts/master/tutorials/hello-kubernetes/deploy/node.yaml | kubectl apply -f -

Anthropic

Mon, 01 Jan 0001 00:00:00 +0000

Component format

A Dapr conversation.yaml component file has the following structure:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: anthropic
spec:
 type: conversation.anthropic
 metadata:
 - name: key
 value: "mykey"
 - name: model
 value: claude-3-5-sonnet-20240620
 - name: responseCacheTTL
 value: 10m

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets, as described here.

Spec metadata fields

Field	Required	Details	Example
`key`	Y	API key for Anthropic.	`"mykey"`
`model`	N	The Anthropic LLM to use. Defaults to `claude-3-5-sonnet-20240620`	`claude-3-5-sonnet-20240620`
`responseCacheTTL`	N	Time-to-live for the in-memory response cache. When set, identical requests are served from cache until they expire.	`10m`

Conversation API overview

Apache Kafka

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up Apache Kafka pub/sub, create a component of type pubsub.kafka. See the pub/sub broker component file to learn how ConsumerID is automatically generated. Read the How-to: Publish and Subscribe guide on how to create and apply a pub/sub configuration.

All component metadata field values can carry templated metadata values, which are resolved on Dapr sidecar startup. For example, you can choose to use {namespace} as the consumerGroup to enable using the same appId in different namespaces using the same topics as described in this article.

Apple Push Notification Service binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Apple Push Notifications binding create a component of type bindings.apns. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.apns
 version: v1
 metadata:
 - name: development
 value: "<bool>"
 - name: key-id
 value: "<APPLE_KEY_ID>"
 - name: team-id
 value: "<APPLE_TEAM_ID>"
 - name: private-key
 secretKeyRef:
 name: <SECRET>
 key: "<SECRET-KEY-NAME>"

Spec metadata fields

Field	Required	Binding support	Details	Example
`development`	Y	Output	Tells the binding which APNs service to use. Set to `"true"` to use the development service or `"false"` to use the production service. Default: `"true"`	`"true"`
`key-id`	Y	Output	The identifier for the private key from the Apple Developer Portal	`"private-key-id`"
`team-id`	Y	Output	The identifier for the organization or author from the Apple Developer Portal	`"team-id"`
`private-key`	Y	Output	Is a PKCS #8-formatted private key. It is intended that the private key is stored in the secret store and not exposed directly in the configuration. See here for more details	`"pem file"`

Private key

The APNS binding needs a cryptographic private key in order to generate authentication tokens for the APNS service. The private key can be generated from the Apple Developer Portal and is provided as a PKCS #8 file with the private key stored in PEM format. The private key should be stored in the Dapr secret store and not stored directly in the binding’s configuration file.

AWS Bedrock

Mon, 01 Jan 0001 00:00:00 +0000

Component format

A Dapr conversation.yaml component file has the following structure:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: awsbedrock
spec:
 type: conversation.aws.bedrock
 metadata:
 - name: endpoint
 value: "http://localhost:4566"
 - name: model
 value: amazon.titan-text-express-v1
 - name: responseCacheTTL
 value: 10m

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets, as described here.

Spec metadata fields

Field	Required	Details	Example
`region`	N	AWS region for the Bedrock service.	`us-east-1`
`endpoint`	N	AWS endpoint for the component to use and connect to emulators. Not recommended for production AWS use.	`http://localhost:4566`
`accessKey`	N	AWS access key for authentication. It is recommended to use a secret store for this value.	`"AKIAIOSFODNN7EXAMPLE"`
`secretKey`	N	AWS secret key for authentication. It is recommended to use a secret store for this value.	`"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"`
`sessionToken`	N	AWS session token for temporary credentials. It is recommended to use a secret store for this value.	`"session-token-example"`
`model`	N	The LLM to use. Defaults to Bedrock’s default provider model from Amazon.	`amazon.titan-text-express-v1`
`responseCacheTTL`	N	A time-to-live for the in-memory response cache. When set, identical requests are served from cache until they expire.	`10m`
`assumeRoleArn`	N	ARN of the role to assume for authentication.	`arn:aws:iam::123456789012:role/MyRole`
`trustAnchorArn`	N	ARN of the trust anchor for authentication.	`arn:aws:rolesanywhere:us-east-1:123456789012:trust-anchor/12345678-1234-1234-1234-123456789012`
`trustProfileArn`	N	ARN of the trust profile for authentication.	`arn:aws:rolesanywhere:us-east-1:123456789012:profile/12345678-1234-1234-1234-123456789012`

Authenticating AWS

Instead of using a key parameter, AWS Bedrock authenticates using Dapr’s standard method of IAM or static credentials. Learn more about authenticating with AWS.

AWS Cloudmap

Mon, 01 Jan 0001 00:00:00 +0000

This component uses AWS Cloud Map for service discovery in Dapr. It supports both HTTP and DNS namespaces, allowing services to discover and connect to other services using AWS Cloud Map’s service discovery capabilities.

Configuration format

Name resolution is configured via the Dapr Configuration.

Within the configuration YAML, set the spec.nameResolution.component property to "aws.cloudmap", then pass configuration options in the spec.nameResolution.configuration dictionary.

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
 name: appconfig
spec:
 nameResolution:
 component: "aws.cloudmap"
 version: "v1"
 configuration:
 # Required: AWS CloudMap namespace configuration (one of these is required)
 namespaceName: "my-namespace" # The name of your CloudMap namespace
 # namespaceId: "ns-xxxxxx" # Alternative: Use namespace ID instead of name

 # Optional: AWS authentication (choose one authentication method)
 # Option 1: Environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
 # Option 2: IAM roles for Amazon EKS
 # Option 3: Explicit credentials (not recommended for production)
 accessKey: "****"
 secretKey: "****"
 sessionToken: "****" # Optional

 # Optional: AWS region and endpoint configuration
 region: "us-west-2"
 endpoint: "http://localhost:4566" # Optional: Custom endpoint for testing

 # Optional: Dapr configuration
 defaultDaprPort: 50002 # Default port for Dapr sidecar if not specified in instance attributes

Specification

AWS authentication

The component supports multiple authentication methods:

AWS DynamoDB binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup AWS DynamoDB binding create a component of type bindings.aws.dynamodb. See this guide on how to create and apply a binding configuration.

See Authenticating to AWS for information about authentication-related attributes

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.aws.dynamodb
 version: v1
 metadata:
 - name: table
 value: "items"
 - name: region
 value: "us-west-2"
 - name: accessKey
 value: "*****************"
 - name: secretKey
 value: "*****************"
 - name: sessionToken
 value: "*****************"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`table`	Y	Output	The DynamoDB table name	`"items"`
`region`	Y	Output	The specific AWS region the AWS DynamoDB instance is deployed in	`"us-east-1"`
`accessKey`	Y	Output	The AWS Access Key to access this resource	`"key"`
`secretKey`	Y	Output	The AWS Secret Access Key to access this resource	`"secretAccessKey"`
`sessionToken`	N	Output	The AWS session token to use	`"sessionToken"`

Important

When running the Dapr sidecar (daprd) with your application on EKS (AWS Kubernetes), if you’re using a node/pod that has already been attached to an IAM policy defining access to AWS resources, you must not provide AWS access-key, secret-key, and tokens in the definition of the component spec you’re using.

Binding support

This component supports output binding with the following operations:

AWS DynamoDB

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup a DynamoDB state store create a component of type state.aws.dynamodb. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.aws.dynamodb
 version: v1
 metadata:
 - name: table
 value: "Contracts"
 - name: accessKey
 value: "AKIAIOSFODNN7EXAMPLE" # Optional
 - name: secretKey
 value: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" # Optional
 - name: endpoint
 value: "http://localhost:8080" # Optional
 - name: region
 value: "eu-west-1" # Optional
 - name: sessionToken
 value: "myTOKEN" # Optional
 - name: ttlAttributeName
 value: "expiresAt" # Optional
 - name: ttlInSeconds
 value: <int> # Optional
 - name: partitionKey
 value: "ContractID" # Optional
 # Uncomment this if you wish to use AWS DynamoDB as a state store for actors (optional)
 #- name: actorStateStore
 # value: "true"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Primary Key

In order to use DynamoDB as a Dapr state store, the table must have a primary key named key. See the section Partition Keys for an option to change this behavior.

AWS Kinesis binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup AWS Kinesis binding create a component of type bindings.aws.kinesis. See this guide on how to create and apply a binding configuration.

See this for instructions on how to set up an AWS Kinesis data streams See Authenticating to AWS for information about authentication-related attributes

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.aws.kinesis
 version: v1
 metadata:
 - name: streamName
 value: "KINESIS_STREAM_NAME" # Kinesis stream name
 - name: consumerName
 value: "KINESIS_CONSUMER_NAME" # Kinesis consumer name
 - name: mode
 value: "shared" # shared - Shared throughput or extended - Extended/Enhanced fanout
 - name: region
 value: "AWS_REGION" #replace
 - name: accessKey
 value: "AWS_ACCESS_KEY" # replace
 - name: secretKey
 value: "AWS_SECRET_KEY" #replace
 - name: sessionToken
 value: "*****************"
 - name: direction
 value: "input, output"
 - name: endpoint
 value: "http://localhost:4566" # Optional: Custom endpoint (e.g. for LocalStack)

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`mode`	N	Input	The Kinesis stream mode. `shared`- Shared throughput, `extended` - Extended/Enhanced fanout methods. More details are here. Defaults to `"shared"`	`"shared"`, `"extended"`
`streamName`	Y	Input/Output	The AWS Kinesis Stream Name	`"stream"`
`consumerName`	Y	Input	The AWS Kinesis Consumer Name	`"myconsumer"`
`region`	Y	Output	The specific AWS region the AWS Kinesis instance is deployed in	`"us-east-1"`
`accessKey`	Y	Output	The AWS Access Key to access this resource	`"key"`
`secretKey`	Y	Output	The AWS Secret Access Key to access this resource	`"secretAccessKey"`
`sessionToken`	N	Output	The AWS session token to use	`"sessionToken"`
`direction`	N	Input/Output	The direction of the binding	`"input"`, `"output"`, `"input, output"`
`endpoint`	N	Input	Custom endpoint for Kinesis and DynamoDB (for example to enable AWS LocalStack support)	`"http://localhost:4566"`

Important

Binding support

This component supports both input and output binding interfaces.

AWS S3 binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup an AWS S3 binding create a component of type bindings.aws.s3. This binding works with other S3-compatible services, such as Minio. See this guide on how to create and apply a binding configuration.

See Authenticating to AWS for information about authentication-related attributes.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.aws.s3
 version: v1
 metadata:
 - name: bucket
 value: "mybucket"
 - name: region
 value: "us-west-2"
 - name: endpoint
 value: "s3.us-west-2.amazonaws.com"
 - name: accessKey
 value: "*****************"
 - name: secretKey
 value: "*****************"
 - name: sessionToken
 value: "mysession"
 - name: decodeBase64
 value: "<bool>"
 - name: encodeBase64
 value: "<bool>"
 - name: forcePathStyle
 value: "<bool>"
 - name: disableSSL
 value: "<bool>"
 - name: insecureSSL
 value: "<bool>"
 - name: storageClass
 value: "<string>"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`bucket`	Y	Output	The name of the S3 bucket to write to	`"bucket"`
`region`	Y	Output	The specific AWS region	`"us-east-1"`
`endpoint`	N	Output	The specific AWS endpoint	`"s3.us-east-1.amazonaws.com"`
`accessKey`	Y	Output	The AWS Access Key to access this resource	`"key"`
`secretKey`	Y	Output	The AWS Secret Access Key to access this resource	`"secretAccessKey"`
`sessionToken`	N	Output	The AWS session token to use	`"sessionToken"`
`forcePathStyle`	N	Output	Currently Amazon S3 SDK supports virtual hosted-style and path-style access. `"true"` is path-style format like `"https://<endpoint>/<your bucket>/<key>"`. `"false"` is hosted-style format like `"https://<your bucket>.<endpoint>/<key>"`. Defaults to `"false"`	`"true"`, `"false"`
`decodeBase64`	N	Output	Configuration to decode base64 file content before saving to bucket storage. (In case of saving a file with binary content). `"true"` is the only allowed positive value. Other positive variations like `"True", "1"` are not acceptable. Defaults to `false`	`"true"`, `"false"`
`encodeBase64`	N	Output	Configuration to encode base64 file content before return the content. (In case of opening a file with binary content). `"true"` is the only allowed positive value. Other positive variations like `"True", "1"` are not acceptable. Defaults to `"false"`	`"true"`, `"false"`
`disableSSL`	N	Output	Allows to connect to non `https://` endpoints. Defaults to `"false"`	`"true"`, `"false"`
`insecureSSL`	N	Output	When connecting to `https://` endpoints, accepts invalid or self-signed certificates. Defaults to `"false"`	`"true"`, `"false"`
`storageClass`	N	Output	The desired storage class for objects during the create operation. Valid aws storage class types can be found here	`STANDARD_IA`

Important

S3 Bucket Creation

Using with Minio

Minio is a service that exposes local storage as S3-compatible block storage, and it’s a popular alternative to S3 especially in development environments. You can use the S3 binding with Minio too, with some configuration tweaks:

AWS Secrets Manager

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup AWS Secrets Manager secret store create a component of type secretstores.aws.secretmanager. See this guide on how to create and apply a secretstore configuration. See this guide on referencing secrets to retrieve and use the secret with Dapr components.

See Authenticating to AWS for information about authentication-related attributes.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: awssecretmanager
spec:
 type: secretstores.aws.secretmanager
 version: v1
 metadata:
 - name: region
 value: "[aws_region]"
 - name: accessKey
 value: "[aws_access_key]"
 - name: secretKey
 value: "[aws_secret_key]"
 - name: sessionToken
 value: "[aws_session_token]"
 - name: multipleKeyValuesPerSecret
 value: "false"

Warning

The above example uses secrets as plain strings. It is recommended to use a local secret store such as Kubernetes secret store or a local file to bootstrap secure key storage.

Spec metadata fields

Field	Required	Details	Example
region	Y	The specific AWS region the AWS Secrets Manager instance is deployed in	`"us-east-1"`
accessKey	Y	The AWS Access Key to access this resource	`"key"`
secretKey	Y	The AWS Secret Access Key to access this resource	`"secretAccessKey"`
sessionToken	N	The AWS session token to use	`"sessionToken"`
multipleKeyValuesPerSecret	N	When set to `"true"` allows for multiple key value pairs to be stored in a single secret. Defaults to `"false"`	`"true"`

Important

Optional per-request metadata properties

The following optional query parameters can be provided when retrieving secrets from this secret store:

AWS SES binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup AWS binding create a component of type bindings.aws.ses. See this guide on how to create and apply a binding configuration.

See Authenticating to AWS for information about authentication-related attributes

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: ses
spec:
 type: bindings.aws.ses
 version: v1
 metadata:
 - name: accessKey
 value: *****************
 - name: secretKey
 value: *****************
 - name: region
 value: "eu-west-1"
 - name: sessionToken
 value: mysession
 - name: emailFrom
 value: "sender@example.com"
 - name: emailTo
 value: "receiver@example.com"
 - name: emailCc
 value: "cc@example.com"
 - name: emailBcc
 value: "bcc@example.com"
 - name: subject
 value: "subject"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`region`	N	Output	The specific AWS region	`"eu-west-1"`
`accessKey`	N	Output	The AWS Access Key to access this resource	`"key"`
`secretKey`	N	Output	The AWS Secret Access Key to access this resource	`"secretAccessKey"`
`sessionToken`	N	Output	The AWS session token to use	`"sessionToken"`
`emailFrom`	N	Output	If set, this specifies the email address of the sender. See also	`"me@example.com"`
`emailTo`	N	Output	If set, this specifies the email address of the receiver. See also	`"me@example.com"`
`emailCc`	N	Output	If set, this specifies the email address to CC in. See also	`"me@example.com"`
`emailBcc`	N	Output	If set, this specifies email address to BCC in. See also	`"me@example.com"`
`subject`	N	Output	If set, this specifies the subject of the email message. See also	`"subject of mail"`

Important

Binding support

This component supports output binding with the following operations:

AWS SNS binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup AWS SNS binding create a component of type bindings.aws.sns. See this guide on how to create and apply a binding configuration.

See Authenticating to AWS for information about authentication-related attributes

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.aws.sns
 version: v1
 metadata:
 - name: topicArn
 value: "mytopic"
 - name: region
 value: "us-west-2"
 - name: endpoint
 value: "sns.us-west-2.amazonaws.com"
 - name: accessKey
 value: "*****************"
 - name: secretKey
 value: "*****************"
 - name: sessionToken
 value: "*****************"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`topicArn`	Y	Output	The SNS topic name	`"arn:::topicarn"`
`region`	Y	Output	The specific AWS region	`"us-east-1"`
`endpoint`	N	Output	The specific AWS endpoint	`"sns.us-east-1.amazonaws.com"`
`accessKey`	Y	Output	The AWS Access Key to access this resource	`"key"`
`secretKey`	Y	Output	The AWS Secret Access Key to access this resource	`"secretAccessKey"`
`sessionToken`	N	Output	The AWS session token to use	`"sessionToken"`

Important

Binding support

This component supports output binding with the following operations:

AWS SNS/SQS

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up AWS SNS/SQS pub/sub, create a component of type pubsub.aws.snssqs.

By default, the AWS SNS/SQS component:

Generates the SNS topics
Provisions the SQS queues
Configures a subscription of the queues to the topics

Note

If you only have a publisher and no subscriber, only the SNS topics are created.

However, if you have a subscriber, SNS, SQS, and the dynamic or static subscription thereof are generated.

AWS SQS binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup AWS SQS binding create a component of type bindings.aws.sqs. See this guide on how to create and apply a binding configuration.

See Authenticating to AWS for information about authentication-related attributes

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.aws.sqs
 version: v1
 metadata:
 - name: queueName
 value: "items"
 - name: region
 value: "us-west-2"
 - name: endpoint
 value: "sqs.us-west-2.amazonaws.com" 
 - name: accessKey
 value: "*****************"
 - name: secretKey
 value: "*****************"
 - name: sessionToken
 value: "*****************"
 - name: direction 
 value: "input, output"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`queueName`	Y	Input/Output	The SQS queue name	`"myqueue"`
`region`	Y	Input/Output	The specific AWS region	`"us-east-1"`
`endpoint`	N	Output	The specific AWS endpoint	`"sqs.us-east-1.amazonaws.com"`
`accessKey`	Y	Input/Output	The AWS Access Key to access this resource	`"key"`
`secretKey`	Y	Input/Output	The AWS Secret Access Key to access this resource	`"secretAccessKey"`
`sessionToken`	N	Input/Output	The AWS session token to use	`"sessionToken"`
`direction`	N	Input/Output	The direction of the binding	`"input"`, `"output"`, `"input, output"`

Important

Binding support

This component supports both input and output binding interfaces.

AWS SSM Parameter Store

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup AWS SSM Parameter Store secret store create a component of type secretstores.aws.parameterstore. See this guide on how to create and apply a secretstore configuration. See this guide on referencing secrets to retrieve and use the secret with Dapr components.

See Authenticating to AWS for information about authentication-related attributes.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: awsparameterstore
spec:
 type: secretstores.aws.parameterstore
 version: v1
 metadata:
 - name: region
 value: "[aws_region]"
 - name: accessKey
 value: "[aws_access_key]"
 - name: secretKey
 value: "[aws_secret_key]"
 - name: sessionToken
 value: "[aws_session_token]"
 - name: prefix
 value: "[secret_name]"

Warning

The above example uses secrets as plain strings. It is recommended to use a local secret store such as Kubernetes secret store or a local file to bootstrap secure key storage.

Spec metadata fields

Field	Required	Details	Example
region	Y	The specific AWS region the AWS SSM Parameter Store instance is deployed in	`"us-east-1"`
accessKey	Y	The AWS Access Key to access this resource	`"key"`
secretKey	Y	The AWS Secret Access Key to access this resource	`"secretAccessKey"`
sessionToken	N	The AWS session token to use	`"sessionToken"`
prefix	N	Allows you to specify more than one SSM parameter store secret store component.	`"prefix"`

Important

Create an AWS SSM Parameter Store instance

Setup AWS SSM Parameter Store using the AWS documentation: https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html.

Azure App Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up an Azure App Configuration configuration store, create a component of type configuration.azure.appconfig.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: configuration.azure.appconfig
 version: v1
 metadata:
 - name: host # host should be used when Azure Authentication mechanism is used.
 value: <HOST>
 - name: connectionString # connectionString should not be used when Azure Authentication mechanism is used.
 value: <CONNECTIONSTRING>
 - name: maxRetries
 value: # Optional
 - name: retryDelay
 value: # Optional
 - name: maxRetryDelay
 value: # Optional
 - name: azureEnvironment # Optional, defaults to AZUREPUBLICCLOUD
 value: "AZUREPUBLICCLOUD"
 # See authentication section below for all options
 - name: azureTenantId # Optional
 value: "[your_service_principal_tenant_id]"
 - name: azureClientId # Optional
 value: "[your_service_principal_app_id]"
 - name: azureCertificateFile # Optional
 value : "[pfx_certificate_file_fully_qualified_local_path]"
 - name: subscribePollInterval # Optional
 value: #Optional [Expected format example - 24h]

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
connectionString	Y*	Connection String for the Azure App Configuration instance. No Default. Can be `secretKeyRef` to use a secret reference. Mutually exclusive with host field. Not to be used when Azure Authentication is used	`Endpoint=https://foo.azconfig.io;Id=osOX-l9-s0:sig;Secret=00000000000000000000000000000000000000000000`
host	N*	Endpoint for the Azure App Configuration instance. No Default. Mutually exclusive with connectionString field. To be used when Azure Authentication is used	`https://dapr.azconfig.io`
maxRetries	N	Maximum number of retries before giving up. Defaults to `3`	`5`, `10`
retryDelay	N	RetryDelay specifies the initial amount of delay to use before retrying an operation. The delay increases exponentially with each retry up to the maximum specified by MaxRetryDelay. Defaults to `4` seconds; `"-1"` disables delay between retries.	`4s`
maxRetryDelay	N	MaxRetryDelay specifies the maximum delay allowed before retrying an operation. Typically the value is greater than or equal to the value specified in RetryDelay. Defaults to `120` seconds; `"-1"` disables the limit	`120s`
subscribePollInterval	N	subscribePollInterval specifies the poll interval in nanoseconds for polling the subscribed keys for any changes. This will be updated in the future to Go Time format. Default polling interval is set to `24` hours.	`24h`

Note: either host or connectionString must be specified.

Azure Blob Storage binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Azure Blob Storage binding create a component of type bindings.azure.blobstorage. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.azure.blobstorage
 version: v1
 metadata:
 - name: accountName
 value: myStorageAccountName
 - name: accountKey
 value: ***********
 - name: containerName
 value: container1
# - name: decodeBase64
# value: <bool>
# - name: getBlobRetryCount
# value: <integer>
# - name: publicAccessLevel
# value: <publicAccessLevel>
# - name: disableEntityManagement
# value: <bool>

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`accountName`	Y	Input/Output	The name of the Azure Storage account	`"myexmapleaccount"`
`accountKey`	Y*	Input/Output	The access key of the Azure Storage account. Only required when not using Microsoft Entra ID authentication.	`"access-key"`
`containerName`	Y	Output	The name of the Blob Storage container to write to	`myexamplecontainer`
`endpoint`	N	Input/Output	Optional custom endpoint URL. This is useful when using the Azurite emulator or when using custom domains for Azure Storage (although this is not officially supported). The endpoint must be the full base URL, including the protocol (`http://` or `https://`), the IP or FQDN, and optional port.	`"http://127.0.0.1:10000"`
`decodeBase64`	N	Output	Configuration to decode base64 file content before saving to Blob Storage. (In case of saving a file with binary content). Defaults to `false`	`true`, `false`
`getBlobRetryCount`	N	Output	Specifies the maximum number of HTTP GET requests that will be made while reading from a RetryReader Defaults to `10`	`1`, `2`
`publicAccessLevel`	N	Output	Specifies whether data in the container may be accessed publicly and the level of access (only used if the container is created by Dapr). Defaults to `none`	`blob`, `container`, `none`
`disableEntityManagement`	N	Output	Configuration to disable entity management. When set to `true`, the binding skips the attempt to create the specified storage container. This is useful when operating with minimal Azure AD permissions. Defaults to `false`	`true`, `false`

Microsoft Entra ID authentication

The Azure Blob Storage binding component supports authentication using all Microsoft Entra ID mechanisms. For further information and the relevant component metadata fields to provide depending on the choice of Microsoft Entra ID authentication mechanism, see the docs for authenticating to Azure.

Azure Blob Storage

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup the Azure Blob Storage state store create a component of type state.azure.blobstorage. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.azure.blobstorage
 # Supports v1 and v2. Users should always use v2 by default. There is no
 # migration path from v1 to v2, see `versioning` below.
 version: v2
 metadata:
 - name: accountName
 value: "[your_account_name]"
 - name: accountKey
 value: "[your_account_key]"
 - name: containerName
 value: "[your_container_name]"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Versioning

Dapr has 2 versions of the Azure Blob Storage state store component: v1 and v2. It is recommended to use v2 for all new applications. v1 is considered legacy and is preserved for compatibility with existing applications only.

Azure Container Apps

Mon, 01 Jan 0001 00:00:00 +0000

Azure Container Apps is a serverless application hosting service where users do not see nor manage any underlying VMs, orchestrators, or other cloud infrastructure. Azure Container Apps enables you to run your application code packaged in multiple containers and is unopinionated about runtimes or programming models that are used.

Dapr is built-in to Container Apps, enabling you to use the Dapr API building blocks without any manual deployment of the Dapr runtime. You simply deploy your services with their Dapr components.

Azure Cosmos DB (Gremlin API) binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup an Azure Cosmos DB (Gremlin API) binding create a component of type bindings.azure.cosmosdb.gremlinapi. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.azure.cosmosdb.gremlinapi
 version: v1
 metadata:
 - name: url
 value: "wss://******.gremlin.cosmos.azure.com:443/"
 - name: masterKey
 value: "*****"
 - name: username
 value: "*****"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`url`	Y	Output	The Cosmos DB url for Gremlin APIs	`"wss://******.gremlin.cosmos.azure.com:443/"`
`masterKey`	Y	Output	The Cosmos DB account master key	`"masterKey"`
`username`	Y	Output	The username of the Cosmos DB database	`"/dbs/<database_name>/colls/<graph_name>"`

For more information see Quickstart: Azure Cosmos Graph DB using Gremlin.

Azure Cosmos DB (SQL API) binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Azure Cosmos DB binding create a component of type bindings.azure.cosmosdb. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.azure.cosmosdb
 version: v1
 metadata:
 - name: url
 value: "https://******.documents.azure.com:443/"
 - name: masterKey
 value: "*****"
 - name: database
 value: "OrderDb"
 - name: collection
 value: "Orders"
 - name: partitionKey
 value: "<message>"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`url`	Y	Output	The Cosmos DB url	`"https://******.documents.azure.com:443/"`
`masterKey`	Y	Output	The Cosmos DB account master key	`"master-key"`
`database`	Y	Output	The name of the Cosmos DB database	`"OrderDb"`
`collection`	Y	Output	The name of the container inside the database.	`"Orders"`
`partitionKey`	Y	Output	The name of the key to extract from the payload (document to be created) that is used as the partition key. This name must match the partition key specified upon creation of the Cosmos DB container.	`"OrderId"`, `"message"`

For more information see Azure Cosmos DB resource model.

Azure Cosmos DB (SQL API)

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Azure Cosmos DB state store create a component of type state.azure.cosmosdb. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.azure.cosmosdb
 version: v1
 metadata:
 - name: url
 value: <REPLACE-WITH-URL>
 - name: masterKey
 value: <REPLACE-WITH-MASTER-KEY>
 - name: database
 value: <REPLACE-WITH-DATABASE>
 - name: collection
 value: <REPLACE-WITH-COLLECTION>
 # Uncomment this if you wish to use Azure Cosmos DB as a state store for actors (optional)
 #- name: actorStateStore
 # value: "true"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

If you wish to use Cosmos DB as an actor store, append the following to the yaml.

Azure Event Grid binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup an Azure Event Grid binding create a component of type bindings.azure.eventgrid. See this guide on how to create and apply a binding configuration.

See this for the documentation for Azure Event Grid.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <name>
spec:
 type: bindings.azure.eventgrid
 version: v1
 metadata:
 # Required Output Binding Metadata
 - name: accessKey
 value: "[AccessKey]"
 - name: topicEndpoint
 value: "[TopicEndpoint]"
 # Required Input Binding Metadata
 - name: azureTenantId
 value: "[AzureTenantId]"
 - name: azureSubscriptionId
 value: "[AzureSubscriptionId]"
 - name: azureClientId
 value: "[ClientId]"
 - name: azureClientSecret
 value: "[ClientSecret]"
 - name: subscriberEndpoint
 value: "[SubscriberEndpoint]"
 - name: handshakePort
 # Make sure to pass this as a string, with quotes around the value
 value: "[HandshakePort]"
 - name: scope
 value: "[Scope]"
 # Optional Input Binding Metadata
 - name: eventSubscriptionName
 value: "[EventSubscriptionName]"
 # Optional metadata
 - name: direction
 value: "input, output"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`accessKey`	Y	Output	The Access Key to be used for publishing an Event Grid Event to a custom topic	`"accessKey"`
`topicEndpoint`	Y	Output	The topic endpoint in which this output binding should publish events	`"topic-endpoint"`
`azureTenantId`	Y	Input	The Azure tenant ID of the Event Grid resource	`"tenentID"`
`azureSubscriptionId`	Y	Input	The Azure subscription ID of the Event Grid resource	`"subscriptionId"`
`azureClientId`	Y	Input	The client ID that should be used by the binding to create or update the Event Grid Event Subscription and to authenticate incoming messages	`"clientId"`
`azureClientSecret`	Y	Input	The client id that should be used by the binding to create or update the Event Grid Event Subscription and to authenticate incoming messages	`"clientSecret"`
`subscriberEndpoint`	Y	Input	The HTTPS endpoint of the webhook Event Grid sends events (formatted as Cloud Events) to. If you’re not re-writing URLs on ingress, it should be in the form of: `"https://[YOUR HOSTNAME]/<path>"` If testing on your local machine, you can use something like ngrok to create a public endpoint.	`"https://[YOUR HOSTNAME]/<path>"`
`handshakePort`	Y	Input	The container port that the input binding listens on when receiving events on the webhook	`"9000"`
`scope`	Y	Input	The identifier of the resource to which the event subscription needs to be created or updated. See the scope section for more details	`"/subscriptions/{subscriptionId}/"`
`eventSubscriptionName`	N	Input	The name of the event subscription. Event subscription names must be between 3 and 64 characters long and should use alphanumeric letters only	`"name"`
`direction`	N	Input/Output	The direction of the binding	`"input"`, `"output"`, `"input, output"`

Scope

Scope is the identifier of the resource to which the event subscription needs to be created or updated. The scope can be a subscription, a resource group, a top-level resource belonging to a resource provider namespace, or an Event Grid topic. For example:

Azure Event Hubs binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup an Azure Event Hubs binding, create a component of type bindings.azure.eventhubs. See this guide on how to create and apply a binding configuration.

See this for instructions on how to set up an Event Hub.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.azure.eventhubs
 version: v1
 metadata:
 # Hub name ("topic")
 - name: eventHub
 value: "mytopic"
 - name: consumerGroup
 value: "myapp"
 # Either connectionString or eventHubNamespace is required
 # Use connectionString when *not* using Microsoft Entra ID
 - name: connectionString
 value: "Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={EventHub}"
 # Use eventHubNamespace when using Microsoft Entra ID
 - name: eventHubNamespace
 value: "namespace"
 - name: enableEntityManagement
 value: "false"
 - name: enableInOrderMessageDelivery
 value: "false"
 # The following four properties are needed only if enableEntityManagement is set to true
 - name: resourceGroupName
 value: "test-rg"
 - name: subscriptionID
 value: "value of Azure subscription ID"
 - name: partitionCount
 value: "1"
 - name: messageRetentionInDays
 value: "3"
 # Checkpoint store attributes
 - name: storageAccountName
 value: "myeventhubstorage"
 - name: storageAccountKey
 value: "112233445566778899"
 - name: storageContainerName
 value: "myeventhubstoragecontainer"
 # Alternative to passing storageAccountKey
 - name: storageConnectionString
 value: "DefaultEndpointsProtocol=https;AccountName=<account>;AccountKey=<account-key>"
 # Optional metadata
 - name: getAllMessageProperties
 value: "true"
 - name: direction
 value: "input, output"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`eventHub`	Y*	Input/Output	The name of the Event Hubs hub (“topic”). Required if using Microsoft Entra ID authentication or if the connection string doesn’t contain an `EntityPath` value	`mytopic`
`connectionString`	Y*	Input/Output	Connection string for the Event Hub or the Event Hub namespace. * Mutually exclusive with `eventHubNamespace` field. * Required when not using Microsoft Entra ID Authentication	`"Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={EventHub}"` or `"Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key}"`
`eventHubNamespace`	Y*	Input/Output	The Event Hub Namespace name. * Mutually exclusive with `connectionString` field. * Required when using Microsoft Entra ID Authentication	`"namespace"`
`enableEntityManagement`	N	Input/Output	Boolean value to allow management of the EventHub namespace and storage account. Default: `false`	`"true"`, `"false"`
`enableInOrderMessageDelivery`	N	Input/Output	Boolean value to allow messages to be delivered in the order in which they were posted. This assumes `partitionKey` is set when publishing or posting to ensure ordering across partitions. Default: `false`	`"true"`, `"false"`
`resourceGroupName`	N	Input/Output	Name of the resource group the Event Hub namespace is part of. Required when entity management is enabled	`"test-rg"`
`subscriptionID`	N	Input/Output	Azure subscription ID value. Required when entity management is enabled	`"azure subscription id"`
`partitionCount`	N	Input/Output	Number of partitions for the new Event Hub namespace. Used only when entity management is enabled. Default: `"1"`	`"2"`
`messageRetentionInDays`	N	Input/Output	Number of days to retain messages for in the newly created Event Hub namespace. Used only when entity management is enabled. Default: `"1"`	`"90"`
`consumerGroup`	Y	Input	The name of the Event Hubs Consumer Group to listen on	`"group1"`
`storageAccountName`	Y	Input	Storage account name to use for the checkpoint store.	`"myeventhubstorage"`
`storageAccountKey`	Y*	Input	Storage account key for the checkpoint store account. * When using Microsoft Entra ID, it’s possible to omit this if the service principal has access to the storage account too.	`"112233445566778899"`
`storageConnectionString`	Y*	Input	Connection string for the checkpoint store, alternative to specifying `storageAccountKey`	`"DefaultEndpointsProtocol=https;AccountName=myeventhubstorage;AccountKey=<account-key>"`
`storageContainerName`	Y	Input	Storage container name for the storage account name.	`"myeventhubstoragecontainer"`
`getAllMessageProperties`	N	Input	When set to `true`, retrieves all user/app/custom properties from the Event Hub message and forwards them in the returned event metadata. Default setting is `"false"`.	`"true"`, `"false"`
`direction`	N	Input/Output	The direction of the binding.	`"input"`, `"output"`, `"input, output"`

Microsoft Entra ID authentication

The Azure Event Hubs pub/sub component supports authentication using all Microsoft Entra ID mechanisms. For further information and the relevant component metadata fields to provide depending on the choice of Microsoft Entra ID authentication mechanism, see the docs for authenticating to Azure.

Azure Event Hubs

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up an Azure Event Hubs pub/sub, create a component of type pubsub.azure.eventhubs. See the pub/sub broker component file to learn how ConsumerID is automatically generated. Read the How-to: Publish and Subscribe guide on how to create and apply a pub/sub configuration.

Apart from the configuration metadata fields shown below, Azure Event Hubs also supports Azure Authentication mechanisms.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: eventhubs-pubsub
spec:
 type: pubsub.azure.eventhubs
 version: v1
 metadata:
 # Either connectionString or eventHubNamespace is required
 # Use connectionString when *not* using Microsoft Entra ID
 - name: connectionString
 value: "Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={EventHub}"
 # Use eventHubNamespace when using Microsoft Entra ID
 - name: eventHubNamespace
 value: "namespace"
 - name: consumerID # Optional. If not supplied, the runtime will create one.
 value: "channel1"
 - name: enableEntityManagement
 value: "false"
 - name: enableInOrderMessageDelivery
 value: "false"
 # The following four properties are needed only if enableEntityManagement is set to true
 - name: resourceGroupName
 value: "test-rg"
 - name: subscriptionID
 value: "value of Azure subscription ID"
 - name: partitionCount
 value: "1"
 - name: messageRetentionInDays
 value: "3"
 # Checkpoint store attributes
 - name: storageAccountName
 value: "myeventhubstorage"
 - name: storageAccountKey
 value: "112233445566778899"
 - name: storageContainerName
 value: "myeventhubstoragecontainer"
 # Alternative to passing storageAccountKey
 - name: storageConnectionString
 value: "DefaultEndpointsProtocol=https;AccountName=<account>;AccountKey=<account-key>"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
`connectionString`	Y*	Connection string for the Event Hub or the Event Hub namespace. * Mutually exclusive with `eventHubNamespace` field. * Required when not using Microsoft Entra ID Authentication	`"Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={EventHub}"` or `"Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key}"`
`eventHubNamespace`	Y*	The Event Hub Namespace name. * Mutually exclusive with `connectionString` field. * Required when using Microsoft Entra ID Authentication	`"namespace"`
`consumerID`	N	Consumer ID (consumer tag) organizes one or more consumers into a group. Consumers with the same consumer ID work as one virtual consumer; for example, a message is processed only once by one of the consumers in the group. If the `consumerID` is not provided, the Dapr runtime set it to the Dapr application ID (`appID`) value.	Can be set to string value (such as `"channel1"` in the example above) or string format value (such as `"{podName}"`, etc.). See all of template tags you can use in your component metadata.
`enableEntityManagement`	N	Boolean value to allow management of the EventHub namespace and storage account. Default: `false`	`"true", "false"`
`enableInOrderMessageDelivery`	N	Input/Output	Boolean value to allow messages to be delivered in the order in which they were posted. This assumes `partitionKey` is set when publishing or posting to ensure ordering across partitions. Default: `false`
`storageAccountName`	Y	Storage account name to use for the checkpoint store.	`"myeventhubstorage"`
`storageAccountKey`	Y*	Storage account key for the checkpoint store account. * When using Microsoft Entra ID, it’s possible to omit this if the service principal has access to the storage account too.	`"112233445566778899"`
`storageConnectionString`	Y*	Connection string for the checkpoint store, alternative to specifying `storageAccountKey`	`"DefaultEndpointsProtocol=https;AccountName=myeventhubstorage;AccountKey=<account-key>"`
`storageContainerName`	Y	Storage container name for the storage account name.	`"myeventhubstoragecontainer"`
`resourceGroupName`	N	Name of the resource group the Event Hub namespace is part of. Required when entity management is enabled	`"test-rg"`
`subscriptionID`	N	Azure subscription ID value. Required when entity management is enabled	`"azure subscription id"`
`partitionCount`	N	Number of partitions for the new Event Hub namespace. Used only when entity management is enabled. Default: `"1"`	`"2"`
`messageRetentionInDays`	N	Number of days to retain messages for in the newly created Event Hub namespace. Used only when entity management is enabled. Default: `"1"`	`"90"`

Microsoft Entra ID authentication

Azure Key Vault

Mon, 01 Jan 0001 00:00:00 +0000

Component format

A Dapr crypto.yaml component file has the following structure:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: azurekeyvault
spec:
 type: crypto.azure.keyvault
 metadata:
 - name: vaultName
 value: mykeyvault
 # See authentication section below for all options
 - name: azureTenantId
 value: ${{AzureKeyVaultTenantId}}
 - name: azureClientId
 value: ${{AzureKeyVaultServicePrincipalClientId}}
 - name: azureClientSecret
 value: ${{AzureKeyVaultServicePrincipalClientSecret}}

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets, as described here.

Authenticating with Microsoft Entra ID

The Azure Key Vault cryptography component supports authentication with Microsoft Entra ID only. Before you enable this component:

Azure Key Vault secret store

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Azure Key Vault secret store, create a component of type secretstores.azure.keyvault.

See the secret store components guide on how to create and apply a secret store configuration.
See the guide on referencing secrets to retrieve and use the secret with Dapr components.
See the Configure the component section below.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: azurekeyvault
spec:
 type: secretstores.azure.keyvault
 version: v1
 metadata:
 - name: vaultName # Required
 value: [your_keyvault_name]
 - name: azureEnvironment # Optional, defaults to AZUREPUBLICCLOUD
 value: "AZUREPUBLICCLOUD"
 # See authentication section below for all options
 - name: azureTenantId
 value: "[your_service_principal_tenant_id]"
 - name: azureClientId
 value: "[your_service_principal_app_id]"
 - name: azureCertificateFile
 value : "[pfx_certificate_file_fully_qualified_local_path]"

Authenticating with Microsoft Entra ID

The Azure Key Vault secret store component supports authentication with Microsoft Entra ID only. Before you enable this component:

Azure OpenAI binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup an Azure OpenAI binding create a component of type bindings.azure.openai. See this guide on how to create and apply a binding configuration. See this for the documentation for Azure OpenAI Service.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.azure.openai
 version: v1
 metadata:
 - name: apiKey # Required
 value: "1234567890abcdef"
 - name: endpoint # Required
 value: "https://myopenai.openai.azure.com"

Warning

The above example uses apiKey as a plain string. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`endpoint`	Y	Output	Azure OpenAI service endpoint URL.	`"https://myopenai.openai.azure.com"`
`apiKey`	Y*	Output	The access key of the Azure OpenAI service. Only required when not using Microsoft Entra ID authentication.	`"1234567890abcdef"`
`azureTenantId`	Y*	Input	The tenant ID of the Azure OpenAI resource. Only required when `apiKey` is not provided.	`"tenentID"`
`azureClientId`	Y*	Input	The client ID that should be used by the binding to create or update the Azure OpenAI Subscription and to authenticate incoming messages. Only required when `apiKey` is not provided.	`"clientId"`
`azureClientSecret`	Y*	Input	The client secret that should be used by the binding to create or update the Azure OpenAI Subscription and to authenticate incoming messages. Only required when `apiKey` is not provided.	`"clientSecret"`

Microsoft Entra ID authentication

The Azure OpenAI binding component supports authentication using all Microsoft Entra ID mechanisms. For further information and the relevant component metadata fields to provide depending on the choice of Microsoft Entra ID authentication mechanism, see the docs for authenticating to Azure.

Azure Service Bus Queues binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Azure Service Bus Queues binding create a component of type bindings.azure.servicebusqueues. See this guide on how to create and apply a binding configuration.

Connection String Authentication

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.azure.servicebusqueues
 version: v1
 metadata:
 - name: connectionString # Required when not using Azure Authentication.
 value: "Endpoint=sb://{ServiceBusNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={ServiceBus}"
 - name: queueName
 value: "queue1"
 # - name: timeoutInSec # Optional
 # value: "60"
 # - name: handlerTimeoutInSec # Optional
 # value: "60"
 # - name: disableEntityManagement # Optional
 # value: "false"
 # - name: maxDeliveryCount # Optional
 # value: "3"
 # - name: lockDurationInSec # Optional
 # value: "60"
 # - name: lockRenewalInSec # Optional
 # value: "20"
 # - name: maxActiveMessages # Optional
 # value: "10000"
 # - name: maxConcurrentHandlers # Optional
 # value: "10"
 # - name: defaultMessageTimeToLiveInSec # Optional
 # value: "10"
 # - name: autoDeleteOnIdleInSec # Optional
 # value: "3600"
 # - name: minConnectionRecoveryInSec # Optional
 # value: "2"
 # - name: maxConnectionRecoveryInSec # Optional
 # value: "300"
 # - name: maxRetriableErrorsPerSec # Optional
 # value: "10"
 # - name: publishMaxRetries # Optional
 # value: "5"
 # - name: publishInitialRetryIntervalInMs # Optional
 # value: "500"
 # - name: direction
 # value: "input, output"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`connectionString`	Y	Input/Output	The Service Bus connection string. Required unless using Microsoft Entra ID authentication.	`"Endpoint=sb://************"`
`queueName`	Y	Input/Output	The Service Bus queue name. Queue names are case-insensitive and will always be forced to lowercase.	`"queuename"`
`timeoutInSec`	N	Input/Output	Timeout for all invocations to the Azure Service Bus endpoint, in seconds. Note that this option impacts network calls and it’s unrelated to the TTL applies to messages. Default: `"60"`	`"60"`
`namespaceName`	N	Input/Output	Parameter to set the address of the Service Bus namespace, as a fully-qualified domain name. Required if using Microsoft Entra ID authentication.	`"namespace.servicebus.windows.net"`
`disableEntityManagement`	N	Input/Output	When set to true, queues and subscriptions do not get created automatically. Default: `"false"`	`"true"`, `"false"`
`lockDurationInSec`	N	Input/Output	Defines the length in seconds that a message will be locked for before expiring. Used during subscription creation only. Default set by server.	`"30"`
`autoDeleteOnIdleInSec`	N	Input/Output	Time in seconds to wait before auto deleting idle subscriptions. Used during subscription creation only. Must be 300s or greater. Default: `"0"` (disabled)	`"3600"`
`defaultMessageTimeToLiveInSec`	N	Input/Output	Default message time to live, in seconds. Used during subscription creation only.	`"10"`
`maxDeliveryCount`	N	Input/Output	Defines the number of attempts the server will make to deliver a message. Used during subscription creation only. Default set by server.	`"10"`
`minConnectionRecoveryInSec`	N	Input/Output	Minimum interval (in seconds) to wait before attempting to reconnect to Azure Service Bus in case of a connection failure. Default: `"2"`	`"5"`
`maxConnectionRecoveryInSec`	N	Input/Output	Maximum interval (in seconds) to wait before attempting to reconnect to Azure Service Bus in case of a connection failure. After each attempt, the component waits a random number of seconds, increasing every time, between the minimum and the maximum. Default: `"300"` (5 minutes)	`"600"`
`maxActiveMessages`	N	Defines the maximum number of messages to be processing or in the buffer at once. This should be at least as big as the maximum concurrent handlers. Default: `"1"`	`"1"`
`handlerTimeoutInSec`	N	Input	Timeout for invoking the app’s handler. Default: `"0"` (no timeout)	`"30"`
`minConnectionRecoveryInSec`	N	Input	Minimum interval (in seconds) to wait before attempting to reconnect to Azure Service Bus in case of a connection failure. Default: `"2"`	`"5"`
`maxConnectionRecoveryInSec`	N	Input	Maximum interval (in seconds) to wait before attempting to reconnect to Azure Service Bus in case of a connection failure. After each attempt, the binding waits a random number of seconds, increasing every time, between the minimum and the maximum. Default: `"300"` (5 minutes)	`"600"`
`lockRenewalInSec`	N	Input	Defines the frequency at which buffered message locks will be renewed. Default: `"20"`.	`"20"`
`maxActiveMessages`	N	Input	Defines the maximum number of messages to be processing or in the buffer at once. This should be at least as big as the maximum concurrent handlers. Default: `"1"`	`"2000"`
`maxConcurrentHandlers`	N	Input	Defines the maximum number of concurrent message handlers; set to `0` for unlimited. Default: `"1"`	`"10"`
`maxRetriableErrorsPerSec`	N	Input	Maximum number of retriable errors that are processed per second. If a message fails to be processed with a retriable error, the component adds a delay before it starts processing another message, to avoid immediately re-processing messages that have failed. Default: `"10"`	`"10"`
`publishMaxRetries`	N	Output	The max number of retries for when Azure Service Bus responds with “too busy” in order to throttle messages. Defaults: `"5"`	`"5"`
`publishInitialRetryIntervalInMs`	N	Output	Time in milliseconds for the initial exponential backoff when Azure Service Bus throttle messages. Defaults: `"500"`	`"500"`
`direction`	N	Input/Output	The direction of the binding	`"input"`, `"output"`, `"input, output"`

Microsoft Entra ID authentication

The Azure Service Bus Queues binding component supports authentication using all Microsoft Entra ID mechanisms, including Managed Identities. For further information and the relevant component metadata fields to provide depending on the choice of Microsoft Entra ID authentication mechanism, see the docs for authenticating to Azure.

Azure Service Bus Queues

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up Azure Service Bus Queues pub/sub, create a component of type pubsub.azure.servicebus.queues. See the pub/sub broker component file to learn how ConsumerID is automatically generated. Read the How-to: Publish and Subscribe guide on how to create and apply a pub/sub configuration.

This component uses queues on Azure Service Bus; see the official documentation for the differences between topics and queues. For using topics, see the Azure Service Bus Topics pubsub component.

Azure Service Bus Topics

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up Azure Service Bus Topics pub/sub, create a component of type pubsub.azure.servicebus.topics. See the pub/sub broker component file to learn how ConsumerID is automatically generated. Read the How-to: Publish and Subscribe guide on how to create and apply a pub/sub configuration.

This component uses topics on Azure Service Bus; see the official documentation for the differences between topics and queues.
For using queues, see the Azure Service Bus Queues pubsub component.

Azure SignalR binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Azure SignalR binding create a component of type bindings.azure.signalr. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.azure.signalr
 version: v1
 metadata:
 - name: connectionString
 value: "Endpoint=https://<your-azure-signalr>.service.signalr.net;AccessKey=<your-access-key>;Version=1.0;"
 - name: hub  # Optional
 value: "<hub name>"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`connectionString`	Y	Output	The Azure SignalR connection string	`"Endpoint=https://<your-azure-signalr>.service.signalr.net;AccessKey=<your-access-key>;Version=1.0;"`
`hub`	N	Output	Defines the hub in which the message will be send. The hub can be dynamically defined as a metadata value when publishing to an output binding (key is “hub”)	`"myhub"`
`endpoint`	N	Output	Endpoint of Azure SignalR; required if not included in the `connectionString` or if using Microsoft Entra ID	`"https://<your-azure-signalr>.service.signalr.net"`
`accessKey`	N	Output	Access key	`"your-access-key"`

Microsoft Entra ID authentication

The Azure SignalR binding component supports authentication using all Microsoft Entra ID mechanisms. See the docs for authenticating to Azure to learn more about the relevant component metadata fields based on your choice of Microsoft Entra ID authentication mechanism.

Azure Storage Queues binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Azure Storage Queues binding create a component of type bindings.azure.storagequeues. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.azure.storagequeues
 version: v1
 metadata:
 - name: accountName
 value: "account1"
 - name: accountKey
 value: "***********"
 - name: queueName
 value: "myqueue"
# - name: pollingInterval
# value: "30s"
# - name: ttlInSeconds
# value: "60"
# - name: decodeBase64
# value: "false"
# - name: encodeBase64
# value: "false"
# - name: endpoint
# value: "http://127.0.0.1:10001"
# - name: visibilityTimeout
# value: "30s"
# - name: initialVisibilityDelay
# value: "30s"
# - name: direction 
# value: "input, output"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`accountName`	Y	Input/Output	The name of the Azure Storage account	`"account1"`
`accountKey`	Y*	Input/Output	The access key of the Azure Storage account. Only required when not using Microsoft Entra ID authentication.	`"access-key"`
`queueName`	Y	Input/Output	The name of the Azure Storage queue	`"myqueue"`
`pollingInterval`	N	Output	Set the interval to poll Azure Storage Queues for new messages, as a Go duration value. Default: `"10s"`	`"30s"`
`ttlInSeconds`	N	Output	Parameter to set the default message time to live. If this parameter is omitted, messages will expire after 10 minutes. See also	`"60"`
`decodeBase64`	N	Input	Configuration to decode base64 content received from the Storage Queue into a string. Defaults to `false`	`true`, `false`
`encodeBase64`	N	Output	If enabled base64 encodes the data payload before uploading to Azure storage queues. Default `false`.	`true`, `false`
`endpoint`	N	Input/Output	Optional custom endpoint URL. This is useful when using the Azurite emulator or when using custom domains for Azure Storage (although this is not officially supported). The endpoint must be the full base URL, including the protocol (`http://` or `https://`), the IP or FQDN, and optional port.	`"http://127.0.0.1:10001"` or `"https://accountName.queue.example.com"`
`initialVisibilityDelay`	N	Input	Allows setting a custom queue visibility timeout to avoid immediate retrying of recently failed messages. Defaults to 30 seconds.	`"100s"`
`visibilityTimeout`	N	Input	Sets a delay before a message becomes visible in the queue after being added. It can also be specified per message by setting the `initialVisibilityDelay` property in the invocation request’s metadata. Defaults to 0 seconds.	`"30s"`
`direction`	N	Input/Output	Direction of the binding.	`"input"`, `"output"`, `"input, output"`

Microsoft Entra ID authentication

The Azure Storage Queue binding component supports authentication using all Microsoft Entra ID mechanisms. See the docs for authenticating to Azure to learn more about the relevant component metadata fields based on your choice of Microsoft Entra ID authentication mechanism.

Azure Table Storage

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Azure Tablestorage state store create a component of type state.azure.tablestorage. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.azure.tablestorage
 version: v1
 metadata:
 - name: accountName
 value: <REPLACE-WITH-ACCOUNT-NAME>
 - name: accountKey
 value: <REPLACE-WITH-ACCOUNT-KEY>
 - name: tableName
 value: <REPLACE-WITH-TABLE-NAME>
# - name: cosmosDbMode
# value: false

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
`accountName`	Y	The storage account name	`"mystorageaccount"`.
`accountKey`	Y	Primary or secondary storage key	`"key"`
`tableName`	Y	The name of the table to be used for Dapr state. The table will be created for you if it doesn’t exist	`"table"`
`cosmosDbMode`	N	If enabled, connects to Cosmos DB Table API instead of Azure Tables (Storage Accounts). Defaults to `false`.	`"false"`
`serviceURL`	N	The full storage service endpoint URL. Useful for Azure environments other than public cloud.	`"https://mystorageaccount.table.core.windows.net/"`
`skipCreateTable`	N	Skips the check for and, if necessary, creation of the specified storage table. This is useful when using active directory authentication with minimal privileges. Defaults to `false`.	`"true"`

Microsoft Entra ID authentication

The Azure Cosmos DB state store component supports authentication using all Microsoft Entra ID mechanisms. For further information and the relevant component metadata fields to provide depending on the choice of Microsoft Entra ID authentication mechanism, see the docs for authenticating to Azure.

Bearer

Mon, 01 Jan 0001 00:00:00 +0000

The bearer HTTP middleware verifies a Bearer Token using OpenID Connect on a Web API, without modifying the application. This design separates authentication/authorization concerns from the application, so that application operators can adopt and configure authentication/authorization providers without impacting the application code.

Component format

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: bearer-token
spec:
 type: middleware.http.bearer
 version: v1
 metadata:
 - name: audience
 value: "<your token audience; i.e. the application's client ID>"
 - name: issuer
 value: "<your token issuer, e.g. 'https://accounts.google.com'>"

 # Optional values
 - name: jwksURL
 value: "<JWKS URL, e.g. 'https://accounts.google.com/.well-known/openid-configuration'>"

Spec metadata fields

Field	Required	Details	Example
`audience`	Y	The audience expected in the tokens. Usually, this corresponds to the client ID of your application that is created as part of a credential hosted by a OpenID Connect platform.
`issuer`	Y	The issuer authority, which is the value expected in the issuer claim in the tokens.	`"https://accounts.google.com"`
`jwksURL`	N	Address of the JWKS (JWK Set containing the public keys for verifying tokens). If empty, will try to fetch the URL set in the OpenID Configuration document `<issuer>/.well-known/openid-configuration`.	`"https://accounts.google.com/.well-known/openid-configuration"`

Common values for issuer include:

build-info CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

Get the version and git commit data for dapr and daprd executables.

Supported platforms

Self-Hosted

Usage

dapr build-info

You can get daprd build information directly by invoking daprd --build-info command.

Cassandra

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Cassandra state store create a component of type state.cassandra. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.cassandra
 version: v1
 metadata:
 - name: hosts
 value: <REPLACE-WITH-COMMA-DELIMITED-HOSTS> # Required. Example: cassandra.cassandra.svc.cluster.local
 - name: username
 value: <REPLACE-WITH-PASSWORD> # Optional. default: ""
 - name: password
 value: <REPLACE-WITH-PASSWORD> # Optional. default: ""
 - name: consistency
 value: <REPLACE-WITH-CONSISTENCY> # Optional. default: "All"
 - name: table
 value: <REPLACE-WITH-TABLE> # Optional. default: "items"
 - name: keyspace
 value: <REPLACE-WITH-KEYSPACE> # Optional. default: "dapr"
 - name: protoVersion
 value: <REPLACE-WITH-PROTO-VERSION> # Optional. default: "4"
 - name: replicationFactor
 value: <REPLACE-WITH-REPLICATION-FACTOR> # Optional. default: "1"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
hosts	Y	Comma separated value of the hosts	`"cassandra.cassandra.svc.cluster.local"`.
port	N	Port for communication. Default `"9042"`	`"9042"`
username	Y	The username of database user. No default	`"user"`
password	Y	The password for the user	`"password"`
consistency	N	The consistency values	`"All"`, `"Quorum"`
table	N	Table name. Defaults to `"items"`	`"items"`, `"tab"`
keyspace	N	The cassandra keyspace to use. Defaults to `"dapr"`	`"dapr"`
protoVersion	N	The proto version for the client. Defaults to `"4"`	`"3"`, `"4"`
replicationFactor	N	The replication factor for the calls. Defaults to `"1"`	`"3"`

Setup Cassandra

You can run Cassandra locally with the Datastax Docker image:

Cloudflare Queues bindings spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

This output binding for Dapr allows interacting with Cloudflare Queues to publish new messages. It is currently not possible to consume messages from a Queue using Dapr.

To setup a Cloudflare Queues binding, create a component of type bindings.cloudflare.queues. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.cloudflare.queues
 version: v1
 # Increase the initTimeout if Dapr is managing the Worker for you
 initTimeout: "120s"
 metadata:
 # Name of the existing Cloudflare Queue (required)
 - name: queueName
 value: ""
 # Name of the Worker (required)
 - name: workerName
 value: ""
 # PEM-encoded private Ed25519 key (required)
 - name: key
 value: |
 -----BEGIN PRIVATE KEY-----
 MC4CAQ...
 -----END PRIVATE KEY-----
 # Cloudflare account ID (required to have Dapr manage the Worker)
 - name: cfAccountID
 value: ""
 # API token for Cloudflare (required to have Dapr manage the Worker)
 - name: cfAPIToken
 value: ""
 # URL of the Worker (required if the Worker has been pre-created outside of Dapr)
 - name: workerUrl
 value: ""

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`queueName`	Y	Output	Name of the existing Cloudflare Queue	`"mydaprqueue"`
`key`	Y	Output	Ed25519 private key, PEM-encoded	See example above
`cfAccountID`	Y/N	Output	Cloudflare account ID. Required to have Dapr manage the worker.	`"456789abcdef8b5588f3d134f74ac"def`
`cfAPIToken`	Y/N	Output	API token for Cloudflare. Required to have Dapr manage the Worker.	`"secret-key"`
`workerUrl`	Y/N	Output	URL of the Worker. Required if the Worker has been pre-provisioned outside of Dapr.	`"https://mydaprqueue.mydomain.workers.dev"`

When you configure Dapr to create your Worker for you, you may need to set a longer value for the initTimeout property of the component, to allow enough time for the Worker script to be deployed. For example: initTimeout: "120s"

Cloudflare Workers KV

Mon, 01 Jan 0001 00:00:00 +0000

Create a Dapr component

To setup a Cloudflare Workers KV state store, create a component of type state.cloudflare.workerskv. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.cloudflare.workerskv
 version: v1
 # Increase the initTimeout if Dapr is managing the Worker for you
 initTimeout: "120s"
 metadata:
 # ID of the Workers KV namespace (required)
 - name: kvNamespaceID
 value: ""
 # Name of the Worker (required)
 - name: workerName
 value: ""
 # PEM-encoded private Ed25519 key (required)
 - name: key
 value: |
 -----BEGIN PRIVATE KEY-----
 MC4CAQ...
 -----END PRIVATE KEY-----
 # Cloudflare account ID (required to have Dapr manage the Worker)
 - name: cfAccountID
 value: ""
 # API token for Cloudflare (required to have Dapr manage the Worker)
 - name: cfAPIToken
 value: ""
 # URL of the Worker (required if the Worker has been pre-created outside of Dapr)
 - name: workerUrl
 value: ""

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
`kvNamespaceID`	Y	ID of the pre-created Workers KV namespace	`"123456789abcdef8b5588f3d134f74ac"`
`workerName`	Y	Name of the Worker to connect to	`"mydaprkv"`
`key`	Y	Ed25519 private key, PEM-encoded	See example above
`cfAccountID`	Y/N	Cloudflare account ID. Required to have Dapr manage the worker.	`"456789abcdef8b5588f3d134f74ac"def`
`cfAPIToken`	Y/N	API token for Cloudflare. Required to have Dapr manage the Worker.	`"secret-key"`
`workerUrl`	Y/N	URL of the Worker. Required if the Worker has been pre-provisioned outside of Dapr.	`"https://mydaprkv.mydomain.workers.dev"`

When you configure Dapr to create your Worker for you, you may need to set a longer value for the initTimeout property of the component, to allow enough time for the Worker script to be deployed. For example: initTimeout: "120s"

CockroachDB

Mon, 01 Jan 0001 00:00:00 +0000

Create a Dapr component

Create a file called cockroachdb.yaml, paste the following and replace the <CONNECTION STRING> value with your connection string. The connection string for CockroachDB follow the same standard for PostgreSQL connection string. For example, "host=localhost user=root port=26257 connect_timeout=10 database=dapr_test". See the CockroachDB documentation on database connections for information on how to define a connection string.

If you want to also configure CockroachDB to store actors, add the actorStateStore option as in the example below.

Coherence

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Coherence state store, create a component of type state.coherence. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.coherence
 version: v1
 metadata:
 - name: serverAddress
 value: <REPLACE-WITH-GRPC-PROXY-HOST-AND-PORT> # Required. Example: "my-cluster-grpc:1408"
 - name: tlsEnabled
 value: <REPLACE-WITH-BOOLEAN> # Optional
 - name: tlsClientCertPath
 value: <REPLACE-WITH-PATH> # Optional
 - name: tlsClientKey
 value: <REPLACE-WITH-PATH> # Optional
 - name: tlsCertsPath
 value: <REPLACE-WITH-PATH> # Optional
 - name: ignoreInvalidCerts
 value: <REPLACE-WITH-BOOLEAN> # Optional
 - name: scopeName
 value: <REPLACE-WITH-SCOPE> # Optional
 - name: requestTimeout
 value: <REPLACE-WITH-REQUEST-TIMEOUT> # Optional
 - name: nearCacheTTL
 value: <REPLACE-WITH-NEAR-CACHE-TTL> # Optional
 - name: nearCacheUnits
 value: <REPLACE-WITH-NEAR-CACHE-UNITS> # Optional
 - name: nearCacheMemory
 value: <REPLACE-WITH-NEAR-CACHE-MEMORY> # Optional

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
serverAddress	Y	Comma delimited endpoints	`"my-cluster-grpc:1408"`
tlsEnabled	N	Indicates if TLS should be enabled. Defaults to false	`"true"`
tlsClientCertPath	N	Client certificate path for Coherence. Defaults to “”. Can be `secretKeyRef` to use a secret reference.	`"-----BEGIN CERTIFICATE-----\nMIIC9TCCA..."`
tlsClientKey	N	Client key for Coherence. Defaults to “”. Can be `secretKeyRef` to use a secret reference.	`"-----BEGIN CERTIFICATE-----\nMIIC9TCCA..."`
tlsCertsPath	N	Additional certificates for Coherence. Defaults to “”. Can be `secretKeyRef` to use a secret reference.	`"-----BEGIN CERTIFICATE-----\nMIIC9TCCA..."`
ignoreInvalidCerts	N	Indicates if to ignore self-signed certificates for testing only, not to be used in production. Defaults to false	`"false"`
scopeName	N	A scope name to use for the internal cache. Defaults to ""	`"my-scope"`
requestTimeout	N	ATimeout for calls to the cluster Defaults to “30s”	`"15s"`
nearCacheTTL	N	If non-zero a near cache is used and the TTL of the near cache is this value. Defaults to 0s	`"60s"`
nearCacheUnits	N	If non-zero a near cache is used and the maximum size of the near cache is this value in units. Defaults to 0	`"1000"`
nearCacheMemory	N	If non-zero a near cache is used and the maximum size of the near cache is this value in bytes. Defaults to 0	`"4096"`

About Using Near Cache TTL

The Coherence state store allows you to specify a near cache to cache frequently accessed data when using the DAPR client. When you access data using Get(ctx context.Context, req *GetRequest), returned entries are stored in the near cache and subsequent data access for keys in the near cache is almost instant, where without a near cache each Get() operation results in a network call.

commercetools GraphQL binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup commercetools GraphQL binding create a component of type bindings.commercetools. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.commercetools
 version: v1
 metadata:
 - name: region # required.
 value: "region"
 - name: provider # required.
 value: "gcp"
 - name: projectKey # required.
 value: "<project-key>"
 - name: clientID # required.
 value: "*****************"
 - name: clientSecret # required.
 value: "*****************"
 - name: scopes # required.
 value: "<project-scopes>"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`region`	Y	Output	The region of the commercetools project	`"europe-west1"`
`provider`	Y	Output	The cloud provider, either gcp or aws	`"gcp"`, `"aws"`
`projectKey`	Y	Output	The commercetools project key
`clientID`	Y	Output	The commercetools client ID for the project
`clientSecret`	Y	Output	The commercetools client secret for the project
`scopes`	Y	Output	The commercetools scopes for the project	`"manage_project:project-key"`

For more information see commercetools - Creating an API Client and commercetools - Regions.

completion CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

Generates shell completion scripts

Usage

dapr completion [flags]
dapr completion [command]

Flags

Name	Environment Variable	Default	Description
`--help`, `-h`			Prints this help message

Examples

Installing bash completion on macOS using Homebrew

If running Bash 3.2 included with macOS:

brew install bash-completion

Or, if running Bash 4.1+:

brew install bash-completion@2

Add the completion to your completion directory:

dapr completion bash > $(brew --prefix)/etc/bash_completion.d/dapr
source ~/.bash_profile

Installing bash completion on Linux

If bash-completion is not installed on Linux, please install the bash-completion’ package via your distribution’s package manager.

components CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

List all Dapr components.

Supported platforms

Kubernetes

Usage

dapr components [flags]

Flags

Name	Default	Description
`--kubernetes`, `-k`	`false`	List all Dapr components in a Kubernetes cluster (required)
`--all-namespaces`, `-A`	`true`	If true, list all Dapr components in all namespaces
`--help`, `-h`		Print this help message
`--name`, `-n`		The components name to be printed (optional)
`--namespace`		List all components in the specified namespace
`--output`, `-o`	`list`	Output format (options: json or yaml or list)

Examples

# List Dapr components in all namespaces in Kubernetes mode
dapr components -k

# List Dapr components in specific namespace in Kubernetes mode
dapr components -k --namespace default

# Print specific Dapr component in Kubernetes mode
dapr components -k -n mycomponent

# List Dapr components in all namespaces in Kubernetes mode
dapr components -k --all-namespaces

Warning messages

This command can issue warning messages.

configurations CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

List all Dapr configurations.

Supported platforms

Kubernetes

Usage

dapr configurations [flags]

Flags

Name	Default	Description
`--kubernetes`, `-k`	`false`	List all Dapr configurations in Kubernetes cluster (required).
`--all-namespaces`, `-A`	`true`	If true, list all Dapr configurations in all namespaces (optional)
`--namespace`		List Dapr configurations in specific namespace.
`--name`, `-n`		Print specific Dapr configuration. (optional)
`--output`, `-o`	`list`	Output format (options: json or yaml or list)
`--help`, `-h`		Print this help message

Examples

# List Dapr configurations in all namespaces in Kubernetes mode
dapr configurations -k

# List Dapr configurations in specific namespace in Kubernetes mode
dapr configurations -k --namespace default

# Print specific Dapr configuration in Kubernetes mode
dapr configurations -k -n appconfig

# List Dapr configurations in all namespaces in Kubernetes mode
dapr configurations -k --all-namespaces

Warning messages

This command can issue warning messages.

Couchbase

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Couchbase state store create a component of type state.couchbase. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.couchbase
 version: v1
 metadata:
 - name: couchbaseURL
 value: <REPLACE-WITH-URL> # Required. Example: "http://localhost:8091"
 - name: username
 value: <REPLACE-WITH-USERNAME> # Required.
 - name: password
 value: <REPLACE-WITH-PASSWORD> # Required.
 - name: bucketName
 value: <REPLACE-WITH-BUCKET> # Required.

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
couchbaseURL	Y	The URL of the Couchbase server	`"http://localhost:8091"`
username	Y	The username for the database	`"user"`
password	Y	The password for access	`"password"`
bucketName	Y	The bucket name to write to	`"bucket"`

Setup Couchbase

You can run Couchbase locally using Docker:

Cron binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup cron binding create a component of type bindings.cron. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.cron
 version: v1
 metadata:
 - name: schedule
 value: "@every 15m" # valid cron schedule
 - name: direction
 value: "input"

Spec metadata fields

Field	Required	Binding support	Details	Example
`schedule`	Y	Input	The valid cron schedule to use. See this for more details	`"@every 15m"`
`direction`	N	Input	The direction of the binding	`"input"`

Schedule Format

The Dapr cron binding supports following formats:

dashboard CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

Start Dapr dashboard.

Supported platforms

Usage

dapr dashboard [flags]

Flags

Name	Default	Description
`--address`, `-a`	`localhost`	Address to listen on. Only accepts IP address or localhost as a value
`--help`, `-h`		Prints this help message
`--kubernetes`, `-k`	`false`	Opens Dapr dashboard in local browser via local proxy to Kubernetes cluster
`--namespace`, `-n`	`dapr-system`	The namespace where Dapr dashboard is running
`--port`, `-p`	`8080`	The local port on which to serve Dapr dashboard
`--version`, `-v`	`false`	Print the version for Dapr dashboard

Examples

# Start dashboard locally
dapr dashboard

# Start dashboard service locally on a specified port
dapr dashboard -p 9999

# Port forward to dashboard service running in Kubernetes
dapr dashboard -k

# Port forward to dashboard service running in Kubernetes on all addresses on a specified port
dapr dashboard -k -p 9999 --address 0.0.0.0

# Port forward to dashboard service running in Kubernetes on a specified port
dapr dashboard -k -p 9999

Warning messages - Kubernetes Mode

This command can issue warning messages.

DeepSeek

Mon, 01 Jan 0001 00:00:00 +0000

Component format

A Dapr conversation.yaml component file has the following structure:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: deepseek
spec:
 type: conversation.deepseek
 metadata:
 - name: key
 value: mykey
 - name: maxTokens
 value: 2048

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets, as described here.

Spec metadata fields

Field	Required	Details	Example
`key`	Y	API key for DeepSeek.	`mykey`
`maxTokens`	N	The max amount of tokens for each request.	`2048`

Conversation API overview

Apache Dubbo binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up an Apache Dubbo binding, create a component of type bindings.dubbo. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.dubbo
 version: v1
 metadata:
 - name: interfaceName
 value: "com.example.UserService"
 - name: methodName
 value: "getUser"
 # Optional
 - name: version
 value: "1.0.0"
 - name: group
 value: "mygroup"
 - name: providerHostname
 value: "localhost"
 - name: providerPort
 value: "8080"

Note

The Dubbo binding does not require authentication or secret configuration by default. However, if your Dubbo deployment requires secure communication, you can integrate Dapr’s secret store for sensitive values.

Spec metadata fields

Field	Required	Binding support	Details	Example
`interfaceName`	Y	Output	The Dubbo interface name to invoke.	`"com.example.UserService"`
`methodName`	Y	Output	The method name to call on the interface.	`"getUser"`
`version`	N	Output	Version of the Dubbo service.	`"1.0.0"`
`group`	N	Output	Group name for the Dubbo service.	`"mygroup"`
`providerHostname`	N	Output	Hostname of the Dubbo provider.	`"localhost"`
`providerPort`	N	Output	Port of the Dubbo provider.	`"8080"`

Binding support

This component supports output binding with the following operation:

Local Testing

Mon, 01 Jan 0001 00:00:00 +0000

Component format

A Dapr conversation.yaml component file has the following structure:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: echo
spec:
 type: conversation.echo
 version: v1

Information

This component is only meant for local validation and testing of a Conversation component implementation. It does not actually send the data to any LLM but rather echos the input back directly.

Conversation API overview

Etcd

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup an Etcd state store create a component of type state.etcd. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.etcd
 # Supports v1 and v2. Users should always use v2 by default. There is no
 # migration path from v1 to v2, see `versioning` below.
 version: v2
 metadata:
 - name: endpoints
 value: <CONNECTION STRING> # Required. Example: 192.168.0.1:2379,192.168.0.2:2379,192.168.0.3:2379
 - name: keyPrefixPath
 value: <KEY PREFIX STRING> # Optional. default: "". Example: "dapr"
 - name: tlsEnable
 value: <ENABLE TLS> # Optional. Example: "false"
 - name: ca
 value: <CA> # Optional. Required if tlsEnable is `true`.
 - name: cert
 value: <CERT> # Optional. Required if tlsEnable is `true`.
 - name: key
 value: <KEY> # Optional. Required if tlsEnable is `true`.
 # Uncomment this if you wish to use Etcd as a state store for actors (optional)
 #- name: actorStateStore
 # value: "true"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Versioning

Dapr has 2 versions of the Etcd state store component: v1 and v2. It is recommended to use v2, as v1 is deprecated.

GCP

Mon, 01 Jan 0001 00:00:00 +0000

Create a Dapr component

To set up GCP pub/sub, create a component of type pubsub.gcp.pubsub. See the pub/sub broker component file to learn how ConsumerID is automatically generated. Read the How-to: Publish and Subscribe guide on how to create and apply a pub/sub configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: gcp-pubsub
spec:
 type: pubsub.gcp.pubsub
 version: v1
 metadata:
 - name: type
 value: service_account
 - name: projectId
 value: <PROJECT_ID> # replace
 - name: endpoint # Optional.
 value: "http://localhost:8085"
 - name: consumerID # Optional - defaults to the app's own ID
 value: <CONSUMER_ID>
 - name: identityProjectId
 value: <IDENTITY_PROJECT_ID> # replace
 - name: privateKeyId
 value: <PRIVATE_KEY_ID> #replace
 - name: clientEmail
 value: <CLIENT_EMAIL> #replace
 - name: clientId
 value: <CLIENT_ID> # replace
 - name: authUri
 value: https://accounts.google.com/o/oauth2/auth
 - name: tokenUri
 value: https://oauth2.googleapis.com/token
 - name: authProviderX509CertUrl
 value: https://www.googleapis.com/oauth2/v1/certs
 - name: clientX509CertUrl
 value: https://www.googleapis.com/robot/v1/metadata/x509/<PROJECT_NAME>.iam.gserviceaccount.com #replace PROJECT_NAME
 - name: privateKey
 value: <PRIVATE_KEY> # replace x509 cert
 - name: disableEntityManagement
 value: "false"
 - name: enableMessageOrdering
 value: "false"
 - name: orderingKey # Optional
 value: <ORDERING_KEY>
 - name: maxReconnectionAttempts # Optional
 value: 30
 - name: connectionRecoveryInSec # Optional
 value: 2
 - name: deadLetterTopic # Optional
 value: <EXISTING_PUBSUB_TOPIC>
 - name: maxDeliveryAttempts # Optional
 value: 5
 - name: maxOutstandingMessages # Optional
 value: 1000
 - name: maxOutstandingBytes # Optional
 value: 1000000000
 - name: maxConcurrentConnections # Optional
 value: 10

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
projectId	Y	GCP project ID	`myproject-123`
endpoint	N	GCP endpoint for the component to use. Only used for local development (for example) with GCP Pub/Sub Emulator. The `endpoint` is unnecessary when running against the GCP production API.	`"http://localhost:8085"`
`consumerID`	N	The Consumer ID organizes one or more consumers into a group. Consumers with the same consumer ID work as one virtual consumer; for example, a message is processed only once by one of the consumers in the group. If the `consumerID` is not provided, the Dapr runtime set it to the Dapr application ID (`appID`) value. The `consumerID`, along with the `topic` provided as part of the request, are used to build the Pub/Sub subscription ID	Can be set to string value (such as `"channel1"`) or string format value (such as `"{podName}"`, etc.). See all of template tags you can use in your component metadata.
identityProjectId	N	If the GCP pubsub project is different from the identity project, specify the identity project using this attribute	`"myproject-123"`
privateKeyId	N	If using explicit credentials, this field should contain the `private_key_id` field from the service account json document	`"my-private-key"`
privateKey	N	If using explicit credentials, this field should contain the `private_key` field from the service account json	`-----BEGIN PRIVATE KEY-----MIIBVgIBADANBgkqhkiG9w0B`
clientEmail	N	If using explicit credentials, this field should contain the `client_email` field from the service account json	`"myservice@myproject-123.iam.gserviceaccount.com"`
clientId	N	If using explicit credentials, this field should contain the `client_id` field from the service account json	`106234234234`
authUri	N	If using explicit credentials, this field should contain the `auth_uri` field from the service account json	`https://accounts.google.com/o/oauth2/auth`
tokenUri	N	If using explicit credentials, this field should contain the `token_uri` field from the service account json	`https://oauth2.googleapis.com/token`
authProviderX509CertUrl	N	If using explicit credentials, this field should contain the `auth_provider_x509_cert_url` field from the service account json	`https://www.googleapis.com/oauth2/v1/certs`
clientX509CertUrl	N	If using explicit credentials, this field should contain the `client_x509_cert_url` field from the service account json	`https://www.googleapis.com/robot/v1/metadata/x509/myserviceaccount%40myproject.iam.gserviceaccount.com`
disableEntityManagement	N	When set to `"true"`, topics and subscriptions do not get created automatically. Default: `"false"`	`"true"`, `"false"`
enableMessageOrdering	N	When set to `"true"`, subscribed messages will be received in order, depending on publishing and permissions configuration.	`"true"`, `"false"`
orderingKey	N	The key provided in the request. It’s used when `enableMessageOrdering` is set to `true` to order messages based on such key.	“my-orderingkey”
maxReconnectionAttempts	N	Defines the maximum number of reconnect attempts. Default: `30`	`30`
connectionRecoveryInSec	N	Time in seconds to wait between connection recovery attempts. Default: `2`	`2`
deadLetterTopic	N	Name of the GCP Pub/Sub Topic. This topic must exist before using this component.	`"myapp-dlq"`
maxDeliveryAttempts	N	Maximum number of attempts to deliver the message. If `deadLetterTopic` is specified, `maxDeliveryAttempts` is the maximum number of attempts for failed processing of messages. Once that number is reached, the message will be moved to the dead-letter topic. Default: `5`	`5`
type	N	DEPRECATED GCP credentials type. Only `service_account` is supported. Defaults to `service_account`	`service_account`
maxOutstandingMessages	N	Maximum number of outstanding messages a given streaming-pull connection can have. Default: `1000`	`50`
maxOutstandingBytes	N	Maximum number of outstanding bytes a given streaming-pull connection can have. Default: `1000000000`	`1000000000`
maxConcurrentConnections	N	Maximum number of concurrent streaming-pull connections to be maintained. Default: `10`	`2`
ackDeadline	N	Message acknowledgement duration deadline. Default: `20s`	`1m`

Warning

If enableMessageOrdering is set to “true”, the roles/viewer or roles/pubsub.viewer role will be required on the service account in order to guarantee ordering in cases where order tokens are not embedded in the messages. If this role is not given, or the call to Subscription.Config() fails for any other reason, ordering by embedded order tokens will still function correctly.

GCP Credentials

Since the GCP Pub/Sub component uses the GCP Go Client Libraries, by default it authenticates using Application Default Credentials. This is explained further in the Authenticate to GCP Cloud services using client libraries guide.

GCP Firestore (Datastore mode)

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup GCP Firestore state store create a component of type state.gcp.firestore. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.gcp.firestore
 version: v1
 metadata:
 - name: project_id
 value: <REPLACE-WITH-PROJECT-ID> # Required.
 - name: type 
 value: <REPLACE-WITH-CREDENTIALS-TYPE> # Required.
 - name: endpoint # Optional. 
 value: "http://localhost:8432"
 - name: private_key_id
 value: <REPLACE-WITH-PRIVATE-KEY-ID> # Optional.
 - name: private_key
 value: <REPLACE-WITH-PRIVATE-KEY> # Optional, but Required if `private_key_id` is specified.
 - name: client_email
 value: <REPLACE-WITH-CLIENT-EMAIL> # Optional, but Required if `private_key_id` is specified.
 - name: client_id
 value: <REPLACE-WITH-CLIENT-ID> # Optional, but Required if `private_key_id` is specified.
 - name: auth_uri
 value: <REPLACE-WITH-AUTH-URI> # Optional.
 - name: token_uri
 value: <REPLACE-WITH-TOKEN-URI> # Optional.
 - name: auth_provider_x509_cert_url
 value: <REPLACE-WITH-AUTH-X509-CERT-URL> # Optional.
 - name: client_x509_cert_url
 value: <REPLACE-WITH-CLIENT-x509-CERT-URL> # Optional.
 - name: entity_kind
 value: <REPLACE-WITH-ENTITY-KIND> # Optional. default: "DaprState"
 - name: noindex
 value: <REPLACE-WITH-BOOLEAN> # Optional. default: "false"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
project_id	Y	The ID of the GCP project to use	`"project-id"`
type	Y	The credentials type	`"service_account"`
endpoint	N	GCP endpoint for the component to use. Only used for local development with (for example) GCP Datastore Emulator. The `endpoint` is unnecessary when running against the GCP production API.	`"localhost:8432"`
private_key_id	N	The ID of the prvate key to use	`"private-key-id"`
privateKey	N	If using explicit credentials, this field should contain the `private_key` field from the service account json	`-----BEGIN PRIVATE KEY-----MIIBVgIBADANBgkqhkiG9w0B`
client_email	N	The email address for the client	`"eample@example.com"`
client_id	N	The client id value to use for authentication	`"client-id"`
auth_uri	N	The authentication URI to use	`"https://accounts.google.com/o/oauth2/auth"`
token_uri	N	The token URI to query for Auth token	`"https://oauth2.googleapis.com/token"`
auth_provider_x509_cert_url	N	The auth provider certificate URL	`"https://www.googleapis.com/oauth2/v1/certs"`
client_x509_cert_url	N	The client certificate URL	`"https://www.googleapis.com/robot/v1/metadata/x509/x"`
entity_kind	N	The entity name in Filestore. Defaults to `"DaprState"`	`"DaprState"`
noindex	N	Whether to disable indexing of state entities. Use this setting if you encounter Firestore index size limitations. Defaults to `"false"`	`"true"`

GCP Credentials

Since the GCP Firestore component uses the GCP Go Client Libraries, by default it authenticates using Application Default Credentials. This is explained in the Authenticate to GCP Cloud services using client libraries guide.

GCP Pub/Sub binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup GCP Pub/Sub binding create a component of type bindings.gcp.pubsub. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.gcp.pubsub
 version: v1
 metadata:
 - name: topic
 value: "topic1"
 - name: subscription
 value: "subscription1"
 - name: type
 value: "service_account"
 - name: project_id
 value: "project_111"
 - name: private_key_id
 value: "*************"
 - name: client_email
 value: "name@domain.com"
 - name: client_id
 value: "1111111111111111"
 - name: auth_uri
 value: "https://accounts.google.com/o/oauth2/auth"
 - name: token_uri
 value: "https://oauth2.googleapis.com/token"
 - name: auth_provider_x509_cert_url
 value: "https://www.googleapis.com/oauth2/v1/certs"
 - name: client_x509_cert_url
 value: "https://www.googleapis.com/robot/v1/metadata/x509/<project-name>.iam.gserviceaccount.com"
 - name: private_key
 value: "PRIVATE KEY"
 - name: direction
 value: "input, output"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`topic`	Y	Output	GCP Pub/Sub topic name	`"topic1"`
`subscription`	N	GCP Pub/Sub subscription name	`"name1"`
`type`	Y	Output	GCP credentials type	`service_account`
`project_id`	Y	Output	GCP project id	`projectId`
`private_key_id`	N	Output	GCP private key id	`"privateKeyId"`
`private_key`	Y	Output	GCP credentials private key. Replace with x509 cert	`12345-12345`
`client_email`	Y	Output	GCP client email	`"client@email.com"`
`client_id`	N	Output	GCP client id	`0123456789-0123456789`
`auth_uri`	N	Output	Google account OAuth endpoint	`https://accounts.google.com/o/oauth2/auth`
`token_uri`	N	Output	Google account token uri	`https://oauth2.googleapis.com/token`
`auth_provider_x509_cert_url`	N	Output	GCP credentials cert url	`https://www.googleapis.com/oauth2/v1/certs`
`client_x509_cert_url`	N	Output	GCP credentials project x509 cert url	`https://www.googleapis.com/robot/v1/metadata/x509/<PROJECT_NAME>.iam.gserviceaccount.com`
`direction`	N	Input/Output	The direction of the binding.	`"input"`, `"output"`, `"input, output"`

Binding support

This component supports both input and output binding interfaces.

GCP Secret Manager

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup GCP Secret Manager secret store create a component of type secretstores.gcp.secretmanager. See this guide on how to create and apply a secretstore configuration. See this guide on referencing secrets to retrieve and use the secret with Dapr components.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: gcpsecretmanager
spec:
 type: secretstores.gcp.secretmanager
 version: v1
 metadata:
 - name: type
 value: <replace-with-account-type>
 - name: project_id
 value: <replace-with-project-id>
 - name: private_key_id
 value: <replace-with-private-key-id>
 - name: client_email
 value: <replace-with-email>
 - name: client_id
 value: <replace-with-client-id>
 - name: auth_uri
 value: <replace-with-auth-uri>
 - name: token_uri
 value: <replace-with-token-uri>
 - name: auth_provider_x509_cert_url
 value: <replace-with-auth-provider-cert-url>
 - name: client_x509_cert_url
 value: <replace-with-client-cert-url>
 - name: private_key
 value: <replace-with-private-key>

Warning

The above example uses secrets as plain strings. It is recommended to use a local secret store such as Kubernetes secret store or a local file to bootstrap secure key storage.

Spec metadata fields

Field	Required	Details	Example
`project_id`	Y	The project ID associated with this component.	`"project_id"`
`type`	N	The type of the account.	`"service_account"`
`private_key_id`	N	If using explicit credentials, this field should contain the `private_key_id` field from the service account json document	`"privateKeyId"`
`private_key`	N	If using explicit credentials, this field should contain the `private_key` field from the service account json. Replace with x509 cert	`12345-12345`
`client_email`	N	If using explicit credentials, this field should contain the `client_email` field from the service account json	`"client@email.com"`
`client_id`	N	If using explicit credentials, this field should contain the `client_id` field from the service account json	`0123456789-0123456789`
`auth_uri`	N	If using explicit credentials, this field should contain the `auth_uri` field from the service account json	`https://accounts.google.com/o/oauth2/auth`
`token_uri`	N	If using explicit credentials, this field should contain the `token_uri` field from the service account json	`https://oauth2.googleapis.com/token`
`auth_provider_x509_cert_url`	N	If using explicit credentials, this field should contain the `auth_provider_x509_cert_url` field from the service account json	`https://www.googleapis.com/oauth2/v1/certs`
`client_x509_cert_url`	N	If using explicit credentials, this field should contain the `client_x509_cert_url` field from the service account json	`https://www.googleapis.com/robot/v1/metadata/x509/<PROJECT_NAME>.iam.gserviceaccount.com`

GCP Credentials

Since the GCP Secret Manager component uses the GCP Go Client Libraries, by default it authenticates using Application Default Credentials. This is explained further in the Authenticate to GCP Cloud services using client libraries guide. Also, see how to Set up Application Default Credentials.

GCP Storage Bucket binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup GCP Storage Bucket binding create a component of type bindings.gcp.bucket. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.gcp.bucket
 version: v1
 metadata:
 - name: bucket
 value: "mybucket"
 - name: type
 value: "service_account"
 - name: project_id
 value: "project_111"
 - name: private_key_id
 value: "*************"
 - name: client_email
 value: "name@domain.com"
 - name: client_id
 value: "1111111111111111"
 - name: auth_uri
 value: "https://accounts.google.com/o/oauth2/auth"
 - name: token_uri
 value: "https://oauth2.googleapis.com/token"
 - name: auth_provider_x509_cert_url
 value: "https://www.googleapis.com/oauth2/v1/certs"
 - name: client_x509_cert_url
 value: "https://www.googleapis.com/robot/v1/metadata/x509/<project-name>.iam.gserviceaccount.com"
 - name: private_key
 value: "PRIVATE KEY"
 - name: decodeBase64
 value: "<bool>"
 - name: encodeBase64
 value: "<bool>"
 - name: contentType
 value: "<string>"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`bucket`	Y	Output	The bucket name	`"mybucket"`
`project_id`	Y	Output	GCP project ID	`projectId`
`type`	N	Output	The GCP credentials type	`"service_account"`
`private_key_id`	N	Output	If using explicit credentials, this field should contain the `private_key_id` field from the service account json document	`"privateKeyId"`
`private_key`	N	Output	If using explicit credentials, this field should contain the `private_key` field from the service account json. Replace with x509 cert	`12345-12345`
`client_email`	N	Output	If using explicit credentials, this field should contain the `client_email` field from the service account json	`"client@email.com"`
`client_id`	N	Output	If using explicit credentials, this field should contain the `client_id` field from the service account json	`0123456789-0123456789`
`auth_uri`	N	Output	If using explicit credentials, this field should contain the `auth_uri` field from the service account json	`https://accounts.google.com/o/oauth2/auth`
`token_uri`	N	Output	If using explicit credentials, this field should contain the `token_uri` field from the service account json	`https://oauth2.googleapis.com/token`
`auth_provider_x509_cert_url`	N	Output	If using explicit credentials, this field should contain the `auth_provider_x509_cert_url` field from the service account json	`https://www.googleapis.com/oauth2/v1/certs`
`client_x509_cert_url`	N	Output	If using explicit credentials, this field should contain the `client_x509_cert_url` field from the service account json	`https://www.googleapis.com/robot/v1/metadata/x509/<PROJECT_NAME>.iam.gserviceaccount.com`
`decodeBase64`	N	Output	Configuration to decode base64 file content before saving to bucket storage. (In case of saving a file with binary content). `true` is the only allowed positive value. Other positive variations like `"True", "1"` are not acceptable. Defaults to `false`	`true`, `false`
`encodeBase64`	N	Output	Configuration to encode base64 file content before return the content. (In case of opening a file with binary content). `true` is the only allowed positive value. Other positive variations like `"True", "1"` are not acceptable. Defaults to `false`	`true`, `false`
`contentType`	N	Output	The MIME type to set for objects created in the bucket. If not specified, GCP attempts to auto-detect the content type.	`"text/csv"`, `"application/json"`, `"image/png"`
`signTTL`	N	Output	Time-to-live for signed URLs generated by the `sign` operation. Accepts any Go duration string (e.g. `"15m"`, `"1h"`). Can be overridden per-request in metadata.	`"15m"`, `"1h"`

GCP Credentials

Since the GCP Storage Bucket component uses the GCP Go Client Libraries, by default it authenticates using Application Default Credentials. This is explained further in the Authenticate to GCP Cloud services using client libraries guide. Also, see how to Set up Application Default Credentials.

GoogleAI

Mon, 01 Jan 0001 00:00:00 +0000

Component format

A Dapr conversation.yaml component file has the following structure:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: googleai
spec:
 type: conversation.googleai
 metadata:
 - name: key
 value: mykey
 - name: model
 value: gemini-1.5-flash
 - name: responseCacheTTL
 value: 10m

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets, as described here.

Spec metadata fields

Field	Required	Details	Example
`key`	Y	API key for GoogleAI.	`mykey`
`model`	N	The GoogleAI LLM to use. Defaults to `gemini-1.5-flash`.	`gemini-2.0-flash`
`responseCacheTTL`	N	Time-to-live for the in-memory response cache. When set, identical requests are served from cache until they expire.	`10m`

Conversation API overview

GraphQL binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup GraphQL binding create a component of type bindings.graphql. See this guide on how to create and apply a binding configuration. To separate normal config settings (e.g. endpoint) from headers, “header:” is used a prefix on the header names.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: example.bindings.graphql
spec:
 type: bindings.graphql
 version: v1
 metadata:
 - name: endpoint
 value: "http://localhost:8080/v1/graphql"
 - name: header:x-hasura-access-key
 value: "adminkey"
 - name: header:Cache-Control
 value: "no-cache"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`endpoint`	Y	Output	GraphQL endpoint string See here for more details	`"http://localhost:4000/graphql/graphql"`
`header:[HEADERKEY]`	N	Output	GraphQL header. Specify the header key in the `name`, and the header value in the `value`.	`"no-cache"` (see above)
`variable:[VARIABLEKEY]`	N	Output	GraphQL query variable. Specify the variable name in the `name`, and the variable value in the `value`.	`"123"` (see below)

Endpoint and Header format

The GraphQL binding uses GraphQL client internally.

HashiCorp Consul

Mon, 01 Jan 0001 00:00:00 +0000

Configuration format

Hashicorp Consul is setup within the Dapr Configuration.

Within the config, add a nameResolution spec and set the component field to "consul".

If you are using the Dapr sidecar to register your service to Consul then you will need the following configuration:

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
 name: appconfig
spec:
 nameResolution:
 component: "consul"
 configuration:
 selfRegister: true

If Consul service registration is managed externally from Dapr you need to ensure that the Dapr-to-Dapr internal gRPC port is added to the service metadata under DAPR_PORT (this key is configurable) and that the Consul service Id matches the Dapr app Id. You can then omit selfRegister from the config above.

HashiCorp Consul

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Hashicorp Consul state store create a component of type state.consul. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.consul
 version: v1
 metadata:
 - name: datacenter
 value: <REPLACE-WITH-DATA-CENTER> # Required. Example: dc1
 - name: httpAddr
 value: <REPLACE-WITH-CONSUL-HTTP-ADDRESS> # Required. Example: "consul.default.svc.cluster.local:8500"
 - name: aclToken
 value: <REPLACE-WITH-ACL-TOKEN> # Optional. default: ""
 - name: scheme
 value: <REPLACE-WITH-SCHEME> # Optional. default: "http"
 - name: keyPrefixPath
 value: <REPLACE-WITH-TABLE> # Optional. default: ""

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
datacenter	Y	Datacenter to use	`"dc1"`
httpAddr	Y	Address of the Consul server	`"consul.default.svc.cluster.local:8500"`
aclToken	N	Per Request ACL Token. Default is `""`	`"token"`
scheme	N	Scheme is the URI scheme for the Consul server. Default is `"http"`	`"http"`
keyPrefixPath	N	Key prefix path in Consul. Default is `""`	`"dapr"`

Setup HashiCorp Consul

You can run Consul locally using Docker:

HashiCorp Vault

Mon, 01 Jan 0001 00:00:00 +0000

Create the Vault component

To setup HashiCorp Vault secret store create a component of type secretstores.hashicorp.vault. See this guide on how to create and apply a secretstore configuration. See this guide on referencing secrets to retrieve and use the secret with Dapr components.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: vault
spec:
 type: secretstores.hashicorp.vault
 version: v1
 metadata:
 - name: vaultAddr
 value: [vault_address] # Optional. Default: "https://127.0.0.1:8200"
 - name: caCert # Optional. This or caPath or caPem
 value: "[ca_cert]"
 - name: caPath # Optional. This or CaCert or caPem
 value: "[path_to_ca_cert_file]"
 - name: caPem # Optional. This or CaCert or CaPath
 value : "[encoded_ca_cert_pem]"
 - name: skipVerify # Optional. Default: false
 value : "[skip_tls_verification]"
 - name: tlsServerName # Optional.
 value : "[tls_config_server_name]"
 - name: vaultTokenMountPath # Required if vaultToken not provided. Path to token file.
 value : "[path_to_file_containing_token]"
 - name: vaultToken # Required if vaultTokenMountPath not provided. Token value.
 value : "[path_to_file_containing_token]"
 - name: vaultKVPrefix # Optional. Default: "dapr"
 value : "[vault_prefix]"
 - name: vaultKVUsePrefix # Optional. default: "true"
 value: "[true/false]"
 - name: enginePath # Optional. default: "secret"
 value: "secret"
 - name: vaultValueType # Optional. default: "map"
 value: "map"

Warning

The above example uses secrets as plain strings. It is recommended to use a local secret store such as Kubernetes secret store or a local file to bootstrap secure key storage.

Spec metadata fields

Field	Required	Details	Example
vaultAddr	N	The address of the Vault server. Defaults to `"https://127.0.0.1:8200"`	`"https://127.0.0.1:8200"`
caPem	N	The inlined contents of the CA certificate to use, in PEM format. If defined, takes precedence over `caPath` and `caCert`.	See below
caPath	N	The path to a folder holding the CA certificate file to use, in PEM format. If the folder contains multiple files, only the first file found will be used. If defined, takes precedence over `caCert`.	`"path/to/cacert/holding/folder"`
caCert	N	The path to the CA certificate to use, in PEM format.	`""path/to/cacert.pem"`
skipVerify	N	Skip TLS verification. Defaults to `"false"`	`"true"`, `"false"`
tlsServerName	N	The name of the server requested during TLS handshake in order to support virtual hosting. This value is also used to verify the TLS certificate presented by Vault server.	`"tls-server"`
vaultTokenMountPath	Y	Path to file containing token	`"path/to/file"`
vaultToken	Y	Token for authentication within Vault.	`"tokenValue"`
vaultKVPrefix	N	The prefix in vault. Defaults to `"dapr"`	`"dapr"`, `"myprefix"`
vaultKVUsePrefix	N	If false, vaultKVPrefix is forced to be empty. If the value is not given or set to true, vaultKVPrefix is used when accessing the vault. Setting it to false is needed to be able to use the BulkGetSecret method of the store.	`"true"`, `"false"`
enginePath	N	The engine path in vault. Defaults to `"secret"`	`"kv"`, `"any"`
vaultValueType	N	Vault value type. `map` means to parse the value into `map[string]string`, `text` means to use the value as a string. ‘map’ sets the `multipleKeyValuesPerSecret` behavior. `text` makes Vault behave as a secret store with name/value semantics. Defaults to `"map"`	`"map"`, `"text"`

Optional per-request metadata properties

The following optional query parameters can be provided to Hashicorp Vault secret store component:

Hazelcast

Mon, 01 Jan 0001 00:00:00 +0000

Create a Dapr component

To setup Hazelcast state store create a component of type state.hazelcast. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.hazelcast
 version: v1
 metadata:
 - name: hazelcastServers
 value: <REPLACE-WITH-HOSTS> # Required. A comma delimited string of servers. Example: "hazelcast:3000,hazelcast2:3000"
 - name: hazelcastMap
 value: <REPLACE-WITH-MAP> # Required. Hazelcast map configuration.

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
hazelcastServers	Y	A comma delimited string of servers	`"hazelcast:3000,hazelcast2:3000"`
hazelcastMap	Y	Hazelcast Map configuration	`"foo-map"`

Setup Hazelcast

You can run Hazelcast locally using Docker:

help CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

Help provides help for any command in the application.

Usage

dapr help [command] [flags]

Flags

Name	Environment Variable	Default	Description
`--help`, `-h`			Prints this help message

HTTP binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Alternative

The service invocation API allows invoking non-Dapr HTTP endpoints and is the recommended approach. Read “How-To: Invoke Non-Dapr Endpoints using HTTP” for more information.

Setup Dapr component

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.http
 version: v1
 metadata:
 - name: url
 value: "http://something.com"
 #- name: maxResponseBodySize
 # value: "100Mi" # OPTIONAL maximum amount of data to read from a response
 #- name: MTLSRootCA
 # value: "/Users/somepath/root.pem" # OPTIONAL path to root CA or PEM-encoded string
 #- name: MTLSClientCert
 # value: "/Users/somepath/client.pem" # OPTIONAL path to client cert or PEM-encoded string
 #- name: MTLSClientKey
 # value: "/Users/somepath/client.key" # OPTIONAL path to client key or PEM-encoded string
 #- name: MTLSRenegotiation
 # value: "RenegotiateOnceAsClient" # OPTIONAL one of: RenegotiateNever, RenegotiateOnceAsClient, RenegotiateFreelyAsClient
 #- name: securityToken # OPTIONAL <token to include as a header on HTTP requests>
 # secretKeyRef:
 # name: mysecret
 # key: "mytoken"
 #- name: securityTokenHeader
 # value: "Authorization: Bearer" # OPTIONAL <header name for the security token>
 #- name: errorIfNot2XX
 # value: "false" # OPTIONAL

Spec metadata fields

Field	Required	Binding support	Details	Example
`url`	Y	Output	The base URL of the HTTP endpoint to invoke	`http://host:port/path`, `http://myservice:8000/customers`
`maxResponseBodySize`	N	Output	Maximum length of the response to read. A whole number is interpreted as bytes; units such as `Ki, Mi, Gi` (SI) or `k	M
`MTLSRootCA`	N	Output	Path to root CA certificate or PEM-encoded string
`MTLSClientCert`	N	Output	Path to client certificate or PEM-encoded string
`MTLSClientKey`	N	Output	Path client private key or PEM-encoded string
`MTLSRenegotiation`	N	Output	Type of mTLS renegotiation to be used	`RenegotiateOnceAsClient`
`securityToken`	N	Output	The value of a token to be added to a HTTP request as a header. Used together with `securityTokenHeader`
`securityTokenHeader`	N	Output	The name of the header for `securityToken` on a HTTP request
`errorIfNot2XX`	N	Output	If a binding error should be thrown when the response is not in the 2xx range. Defaults to `true`

The values for MTLSRootCA, MTLSClientCert and MTLSClientKey can be provided in three ways:

Huawei OBS binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Huawei Object Storage Service (OBS) (output) binding create a component of type bindings.huawei.obs. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.huawei.obs
 version: v1
 - name: bucket
 value: "<your-bucket-name>"
 - name: endpoint
 value: "<obs-bucket-endpoint>"
 - name: accessKey
 value: "<your-access-key>"
 - name: secretKey
 value: "<your-secret-key>"
 # optional fields
 - name: region
 value: "<your-bucket-region>"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`bucket`	Y	Output	The name of the Huawei OBS bucket to write to	`"My-OBS-Bucket"`
`endpoint`	Y	Output	The specific Huawei OBS endpoint	`"obs.cn-north-4.myhuaweicloud.com"`
`accessKey`	Y	Output	The Huawei Access Key (AK) to access this resource	`"************"`
`secretKey`	Y	Output	The Huawei Secret Key (SK) to access this resource	`"************"`
`region`	N	Output	The specific Huawei region of the bucket	`"cn-north-4"`

Binding support

This component supports output binding with the following operations:

HuaweiCloud Cloud Secret Management Service (CSMS)

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup HuaweiCloud Cloud Secret Management Service (CSMS) secret store create a component of type secretstores.huaweicloud.csms. See this guide on how to create and apply a secretstore configuration. See this guide on referencing secrets to retrieve and use the secret with Dapr components.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: huaweicloudcsms
spec:
 type: secretstores.huaweicloud.csms
 version: v1
 metadata:
 - name: region
 value: "[huaweicloud_region]"
 - name: accessKey
 value: "[huaweicloud_access_key]"
 - name: secretAccessKey
 value: "[huaweicloud_secret_access_key]"

Warning

The above example uses secrets as plain strings. It is recommended to use a local secret store such as Kubernetes secret store or a local file to bootstrap secure key storage.

Spec metadata fields

Field	Required	Details	Example
region	Y	The specific region the HuaweiCloud CSMS instance is deployed in	`"cn-north-4"`
accessKey	Y	The HuaweiCloud Access Key to access this resource	`"accessKey"`
secretAccessKey	Y	The HuaweiCloud Secret Access Key to access this resource	`"secretAccessKey"`

Optional per-request metadata properties

The following optional query parameters can be provided when retrieving secrets from this secret store:

Huggingface

Mon, 01 Jan 0001 00:00:00 +0000

Component format

A Dapr conversation.yaml component file has the following structure:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: huggingface
spec:
 type: conversation.huggingface
 metadata:
 - name: key
 value: mykey
 - name: model
 value: meta-llama/Meta-Llama-3-8B
 - name: responseCacheTTL
 value: 10m

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets, as described here.

Spec metadata fields

Field	Required	Details	Example
`key`	Y	API key for Huggingface.	`mykey`
`model`	N	The Huggingface LLM to use. Defaults to `meta-llama/Meta-Llama-3-8B`.	`meta-llama/Meta-Llama-3-8B`
`responseCacheTTL`	N	Time-to-live for the in-memory response cache. When set, identical requests are served from cache until they expire.	`10m`

Conversation API overview

In-memory

Mon, 01 Jan 0001 00:00:00 +0000

The in-memory pub/sub component operates within a single Dapr sidecar. This is primarily meant for development purposes. State is not replicated across multiple sidecars and is lost when the Dapr sidecar is restarted.

Component format

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: pubsub
spec:
 type: pubsub.in-memory
 version: v1
 metadata: []

Note: in-memory does not require any specific metadata for the component to work, however spec.metadata is a required field.

In-memory

Mon, 01 Jan 0001 00:00:00 +0000

The in-memory state store component maintains state in the Dapr sidecar’s memory. This is primarily meant for development purposes. State is not replicated across multiple sidecars and is lost when the Dapr sidecar is restarted.

Component format

To setup in-memory state store, create a component of type state.in-memory. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.in-memory
 version: v1
 metadata: 
 # Uncomment this if you wish to use In-memory as a state store for actors (optional)
 #- name: actorStateStore
 # value: "true"

Note: While in-memory does not require any specific metadata for the component to work, spec.metadata is a required field.

InfluxDB binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup InfluxDB binding create a component of type bindings.influx. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.influx
 version: v1
 metadata:
 - name: url # Required
 value: "<INFLUX-DB-URL>"
 - name: token # Required
 value: "<TOKEN>"
 - name: org # Required
 value: "<ORG>"
 - name: bucket # Required
 value: "<BUCKET>"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`url`	Y	Output	The URL for the InfluxDB instance	`"http://localhost:8086"`
`token`	Y	Output	The authorization token for InfluxDB	`"mytoken"`
`org`	Y	Output	The InfluxDB organization	`"myorg"`
`bucket`	Y	Output	Bucket name to write to	`"mybucket"`

Binding support

This component supports output binding with the following operations:

init CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

Install Dapr on supported hosting platforms.

Supported platforms

Usage

dapr init [flags]

Flags

Name	Environment Variable	Default	Description
`--dashboard-version`		`latest`	The version of the Dapr dashboard to install, for example: `1.0.0`
`--enable-ha`		`false`	Enable high availability (HA) mode
`--enable-mtls`		`true`	Enable mTLS in your cluster
`--from-dir`			Path to a local directory containing a downloaded “Dapr Installer Bundle” release which is used to `init` the airgap environment
`--help`, `-h`			Print this help message
`--image-registry`			Pulls container images required by Dapr from the given image registry
`--kubernetes`, `-k`		`false`	Deploy Dapr to a Kubernetes cluster
`--namespace`, `-n`		`dapr-system`	The Kubernetes namespace to install Dapr in
`--network`			The Docker network on which to install and deploy the Dapr runtime
`--runtime-version`		`latest`	The version of the Dapr runtime to install, for example: `1.0.0`
`--image-variant`			The image variant to use for the Dapr runtime, for example: `mariner`
`--set`			Configure options on the command line to be passed to the Dapr Helm chart and the Kubernetes cluster upon install. Can specify multiple values in a comma-separated list, for example: `key1=val1,key2=val2`
`--slim`, `-s`		`false`	Exclude placement service, scheduler service, and the Redis and Zipkin containers from self-hosted installation
`--timeout`		`300`	The wait timeout for the Kubernetes installation
`--wait`		`false`	Wait for Kubernetes initialization to complete
N/A	DAPR_DEFAULT_IMAGE_REGISTRY		It is used to specify the default container registry to pull images from. When its value is set to `GHCR` or `ghcr` it pulls the required images from Github container registry. To default to Docker hub, unset the environment variable or leave it blank
N/A	DAPR_HELM_REPO_URL		Specifies a private Dapr Helm chart url
N/A	DAPR_HELM_REPO_USERNAME	A username for a private Helm chart	The username required to access the private Dapr Helm chart. If it can be accessed publicly, this env variable does not need to be set
N/A	DAPR_HELM_REPO_PASSWORD	A password for a private Helm chart	The password required to access the private Dapr Helm chart. If it can be accessed publicly, this env variable does not need to be set
`--container-runtime`		`docker`	Used to pass in a different container runtime other than Docker. Supported container runtimes are: `docker`, `podman`
`--dev`			Creates Redis and Zipkin deployments when run in Kubernetes.
`--scheduler-volume`			Self-hosted only. Optionally, you can specify a volume for the scheduler service data directory. By default, without this flag, scheduler data is not persisted and not resilient to restarts.
`--scheduler-override-broadcast-host-port`		localhost:50006 (6060 for Windows)	Self-hosted only. Specify the scheduler broadcast host and port, for example: 192.168.42.42:50006.

Examples

Install

invoke CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

Invoke a method on a given Dapr application.

Supported platforms

Self-Hosted

Usage

dapr invoke [flags]

Flags

Name	Environment Variable	Default	Description
`--app-id`, `-a`	`APP_ID`		The application id to invoke
`--help`, `-h`			Print this help message
`--method`, `-m`			The method to invoke
`--data`, `-d`			The JSON serialized data string (optional)
`--data-file`, `-f`			A file containing the JSON serialized data (optional)
`--verb`, `-v`		`POST`	The HTTP verb to use

Examples

# Invoke a sample method on target app with POST Verb
dapr invoke --app-id target --method sample --data '{"key":"value"}'

# Invoke a sample method on target app with GET Verb
dapr invoke --app-id target --method sample --verb GET

JetStream

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up JetStream pub/sub, create a component of type pubsub.jetstream. See the pub/sub broker component file to learn how ConsumerID is automatically generated. Read the How-to: Publish and Subscribe guide on how to create and apply a pub/sub configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: jetstream-pubsub
spec:
 type: pubsub.jetstream
 version: v1
 metadata:
 - name: natsURL
 value: "nats://localhost:4222"
 - name: jwt # Optional. Used for decentralized JWT authentication.
 value: "eyJhbGciOiJ...6yJV_adQssw5c"
 - name: seedKey # Optional. Used for decentralized JWT authentication.
 value: "SUACS34K232O...5Z3POU7BNIL4Y"
 - name: tls_client_cert # Optional. Used for TLS Client authentication.
 value: "/path/to/tls.crt"
 - name: tls_client_key # Optional. Used for TLS Client authentication.
 value: "/path/to/tls.key"
 - name: token # Optional. Used for token based authentication.
 value: "my-token"
 - name: name
 value: "my-conn-name"
 - name: streamName
 value: "my-stream"
 - name: durableName 
 value: "my-durable-subscription"
 - name: queueGroupName
 value: "my-queue-group"
 - name: startSequence
 value: 1
 - name: startTime # In Unix format
 value: 1630349391
 - name: flowControl
 value: false
 - name: ackWait
 value: 10s
 - name: maxDeliver
 value: 5
 - name: backOff
 value: "50ms, 1s, 10s"
 - name: maxAckPending
 value: 5000
 - name: replicas
 value: 1
 - name: memoryStorage
 value: false
 - name: rateLimit
 value: 1024
 - name: heartbeat
 value: 15s
 - name: ackPolicy
 value: explicit
 - name: deliverPolicy
 value: all
 - name: domain
 value: hub
 - name: apiPrefix
 value: PREFIX

Spec metadata fields

Field	Required	Details	Example
natsURL	Y	NATS server address URL	`"nats://localhost:4222"`
jwt	N	NATS decentralized authentication JWT	`"eyJhbGciOiJ...6yJV_adQssw5c"`
seedKey	N	NATS decentralized authentication seed key	`"SUACS34K232O...5Z3POU7BNIL4Y"`
tls_client_cert	N	NATS TLS Client Authentication Certificate	`"/path/to/tls.crt"`
tls_client_key	N	NATS TLS Client Authentication Key	`"/path/to/tls.key"`
token	N	NATS token based authentication	`"my-token"`
name	N	NATS connection name	`"my-conn-name"`
streamName	N	Name of the JetStream Stream to bind to	`"my-stream"`
durableName	N	Durable name	`"my-durable"`
queueGroupName	N	Queue group name	`"my-queue"`
startSequence	N	Start Sequence	`1`
startTime	N	Start Time in Unix format	`1630349391`
flowControl	N	Flow Control	`true`
ackWait	N	Ack Wait	`10s`
maxDeliver	N	Max Deliver	`15`
backOff	N	BackOff	`"50ms, 1s, 5s, 10s"`
maxAckPending	N	Max Ack Pending	`5000`
replicas	N	Replicas	`3`
memoryStorage	N	Memory Storage	`false`
rateLimit	N	Rate Limit	`1024`
heartbeat	N	Heartbeat	`10s`
ackPolicy	N	Ack Policy	`explicit`
deliverPolicy	N	One of: all, last, new, sequence, time	`all`
domain	N	[JetStream Leafondes]	`HUB`
apiPrefix	N	[JetStream Leafnodes]	`PREFIX`

Create a NATS server

You can run a NATS Server with JetStream enabled locally using Docker:

JetStream KV

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup a JetStream KV state store create a component of type state.jetstream. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.jetstream
 version: v1
 metadata:
 - name: natsURL
 value: "nats://localhost:4222"
 - name: jwt
 value: "eyJhbGciOiJ...6yJV_adQssw5c" # Optional. Used for decentralized JWT authentication
 - name: seedKey
 value: "SUACS34K232O...5Z3POU7BNIL4Y" # Optional. Used for decentralized JWT authentication
 - name: bucket
 value: "<bucketName>"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadatafield

Field	Required	Details	Example
natsURL	Y	NATS server address URL	“`nats://localhost:4222`”
jwt	N	NATS decentralized authentication JWT	“`eyJhbGciOiJ...6yJV_adQssw5c`”
seedKey	N	NATS decentralized authentication seed key	“`SUACS34K232O...5Z3POU7BNIL4Y`”
bucket	Y	JetStream KV bucket name	`"<bucketName>"`

Create a NATS server

You can run a NATS Server with JetStream enabled locally using Docker:

JSON Web Key Sets (JWKS)

Mon, 01 Jan 0001 00:00:00 +0000

Component format

The purpose of this component is to load keys from a JSON Web Key Set (RFC 7517). These are JSON documents that contain 1 or more keys as JWK (JSON Web Key); they can be public, private, or shared keys.

This component supports loading a JWKS:

From a local file; in this case, Dapr watches for changes to the file on disk and reloads it automatically.
From a HTTP(S) URL, which is periodically refreshed.
By passing the actual JWKS in the jwks metadata property, as a string (optionally, base64-encoded).

Note

This component uses the cryptographic engine in Dapr to perform operations. Although keys are never exposed to your application, Dapr has access to the raw key material.

A Dapr crypto.yaml component file has the following structure:

Kafka binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Kafka binding create a component of type bindings.kafka. See this guide on how to create and apply a binding configuration. For details on using secretKeyRef, see the guide on how to reference secrets in components.

All component metadata field values can carry templated metadata values, which are resolved on Dapr sidecar startup. For example, you can choose to use {namespace} as the consumerGroup, to enable using the same appId in different namespaces using the same topics as described in this article.

Kitex

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The binding for Kitex mainly utilizes the generic-call feature in Kitex. Learn more from the official documentation around Kitex generic-call. Currently, Kitex only supports Thrift generic calls. The implementation integrated into components-contrib adopts binary generic calls.

Component format

To setup an Kitex binding, create a component of type bindings.kitex. See the How-to: Use output bindings to interface with external resources guide on creating and applying a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: bindings.kitex
spec:
 type: bindings.kitex
 version: v1
 metadata: 
 - name: hostPorts
 value: "127.0.0.1:8888"
 - name: destService
 value: "echo"
 - name: methodName
 value: "echo"
 - name: version
 value: "0.5.0"

Spec metadata fields

The InvokeRequest.Metadata for bindings.kitex requires the client to fill in four required items when making a call:

KubeMQ binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup KubeMQ binding create a component of type bindings.kubemq. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: binding-topic
spec:
 type: bindings.kubemq
 version: v1
 metadata:
 - name: address
 value: "localhost:50000"
 - name: channel
 value: "queue1"
 - name: direction
 value: "input, output"

Spec metadata fields

Field	Required	Details	Example
`address`	Y	Address of the KubeMQ server	`"localhost:50000"`
`channel`	Y	The Queue channel name	`"queue1"`
`authToken`	N	Auth JWT token for connection. Check out KubeMQ Authentication	`"ew..."`
`autoAcknowledged`	N	Sets if received queue message is automatically acknowledged	`"true"` or `"false"` (default is `"false"`)
`pollMaxItems`	N	Sets the number of messages to poll on every connection	`"1"`
`pollTimeoutSeconds`	N	Sets the time in seconds for each poll interval	`"3600"`
`direction`	N	The direction of the binding	`"input"`, `"output"`, `"input, output"`

Binding support

This component supports both input and output binding interfaces.

KubeMQ

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up KubeMQ pub/sub, create a component of type pubsub.kubemq. See the pub/sub broker component file to learn how ConsumerID is automatically generated. Read the How-to: Publish and Subscribe guide on how to create and apply a pub/sub configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: kubemq-pubsub
spec:
 type: pubsub.kubemq
 version: v1
 metadata:
 - name: address
 value: localhost:50000
 - name: store
 value: false
 - name: consumerID
 value: channel1

Spec metadata fields

Field	Required	Details	Example
address	Y	Address of the KubeMQ server	`"localhost:50000"`
store	N	type of pubsub, true: pubsub persisted (EventsStore), false: pubsub in-memory (Events)	`true` or `false` (default is `false`)
consumerID	N	Consumer ID (consumer tag) organizes one or more consumers into a group. Consumers with the same consumer ID work as one virtual consumer; for example, a message is processed only once by one of the consumers in the group. If the `consumerID` is not provided, the Dapr runtime set it to the Dapr application ID (`appID`) value.	Can be set to string value (such as `"channel1"` in the example above) or string format value (such as `"{podName}"`, etc.). See all of template tags you can use in your component metadata.
clientID	N	Name for client id connection	`sub-client-12345`
authToken	N	Auth JWT token for connection Check out KubeMQ Authentication	`ew...`
group	N	Subscriber group for load balancing	`g1`
disableReDelivery	N	Set if message should be re-delivered in case of error coming from application	`true` or `false` (default is `false`)

Create a KubeMQ broker

Obtain KubeMQ Key.
Wait for an email confirmation with your Key

You can run a KubeMQ broker with Docker:

Kubernetes ConfigMap

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up a Kubernetes ConfigMap configuration store, create a component of type configuration.kubernetes. See this guide on how to create and apply a configuration store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: configuration.kubernetes
 version: v1
 metadata:
 - name: configMapName
 value: "<CONFIGMAP_NAME>"
 # Optional: path to kubeconfig (only needed when running outside the cluster)
 #- name: kubeconfigPath
 # value: "/path/to/kubeconfig"
 # Optional: informer resync period
 #- name: resyncPeriod
 # value: "0"

Spec metadata fields

Field	Required	Details	Example
`configMapName`	Y	The name of the Kubernetes ConfigMap to use as the configuration source. Must be a valid RFC 1123 DNS label name.	`"my-app-config"`
`kubeconfigPath`	N	Path to a kubeconfig file. When running inside a Kubernetes cluster (the typical case), this is not needed. When running outside the cluster, it falls back to the `KUBECONFIG` environment variable, then to `~/.kube/config`.	`"/path/to/kubeconfig"`
`resyncPeriod`	N	How often the informer fully re-syncs the ConfigMap state from the API server as a consistency safety net, independent of watch events. Set to `"0"` (default) to disable periodic resync and rely solely on watch events.	`"10m"`

Set up a Kubernetes ConfigMap as Configuration Store

The Kubernetes ConfigMap configuration store requires no external infrastructure beyond the Kubernetes cluster itself.

Kubernetes DNS

Mon, 01 Jan 0001 00:00:00 +0000

Configuration format

Generally, Kubernetes DNS name resolution is configured automatically in Kubernetes mode by Dapr. There is no configuration needed to use Kubernetes DNS as your name resolution provider unless some overrides are necessary for the Kubernetes name resolution component.

In the scenario that an override is required, within a Dapr Configuration CRD, add a nameResolution spec and set the component field to "kubernetes". The other configuration fields can be set as needed in a configuration map, as seen below.

Kubernetes Events binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Kubernetes Events binding create a component of type bindings.kubernetes. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.kubernetes
 version: v1
 metadata:
 - name: namespace
 value: "<NAMESPACE>"
 - name: resyncPeriodInSec
 value: "<seconds>"
 - name: direction
 value: "input"

Spec metadata fields

Field	Required	Binding support	Details	Example
`namespace`	Y	Input	The Kubernetes namespace to read events from	`"default"`
`resyncPeriodInSec`	N	Input	The period of time to refresh event list from Kubernetes API server. Defaults to `"10"`	`"15"`
`direction`	N	Input	The direction of the binding	`"input"`
`kubeconfigPath`	N	Input	The path to the kubeconfig file. If not specified, the binding uses the default in-cluster config value	`"/path/to/kubeconfig"`

Binding support

This component supports input binding interface.

Kubernetes secrets

Mon, 01 Jan 0001 00:00:00 +0000

Default Kubernetes secret store component

When Dapr is deployed to a Kubernetes cluster, a secret store with the name kubernetes is automatically provisioned. This pre-provisioned secret store allows you to use the native Kubernetes secret store with no need to author, deploy or maintain a component configuration file for the secret store and is useful for developers looking to simply access secrets stored natively in a Kubernetes cluster.

A custom component definition file for a Kubernetes secret store can still be configured (See below for details). Using a custom definition decouples referencing the secret store in your code from the hosting platform as the store name is not fixed and can be customized, keeping your code more generic and portable. Additionally, by explicitly defining a Kubernetes secret store component you can connect to a Kubernetes secret store from a local Dapr self-hosted installation. This requires a valid kubeconfig file.

Kubernetes Secrets

Mon, 01 Jan 0001 00:00:00 +0000

Component format

The purpose of this component is to load the Kubernetes secret named after the key name.

Note

This component uses the cryptographic engine in Dapr to perform operations. Although keys are never exposed to your application, Dapr has access to the raw key material.

A Dapr crypto.yaml component file has the following structure:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: crypto.dapr.kubernetes.secrets
 version: v1
 metadata:[]

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets, as described here.

Spec metadata fields

Field	Required	Details	Example
`defaultNamespace`	N	Default namespace to retrieve secrets from. If unset, the namespace must be specified for each key, as `namespace/secretName/key`	`"default-ns"`
`kubeconfigPath`	N	The path to the kubeconfig file. If not specified, the component uses the default in-cluster config value	`"/path/to/kubeconfig"`

Cryptography building block

list CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

List all Dapr instances.

Supported platforms

Usage

dapr list [flags]

Flags

Name	Default	Description
`--all-namespaces`, `-A`	`false`	List all Dapr pods in all namespaces (optional)
`--help`, `-h`		Print this help message
`--kubernetes`, `-k`	`false`	List all Dapr pods in a Kubernetes cluster (optional)
`--namespace`, `-n`	`default`	List the Dapr pods in the defined namespace in Kubernetes. Only with `-k` flag (optional)
`--output`, `-o`	`table`	The output format of the list. Valid values are: `json`, `yaml`, or `table`

Examples

# List Dapr instances in self-hosted mode
dapr list

# List Dapr instances in all namespaces in Kubernetes mode
dapr list -k

# List Dapr instances in JSON format
dapr list -o json

# List Dapr instances in a specific namespace in Kubernetes mode
dapr list -k --namespace default

# List Dapr instances in all namespaces in Kubernetes mode
dapr list -k --all-namespaces

Warning messages - Kubernetes Mode

This command can issue warning messages.

Local environment variables (for Development)

Mon, 01 Jan 0001 00:00:00 +0000

This Dapr secret store component uses locally defined environment variable and does not use authentication.

Warning

This approach to secret management is not recommended for production environments.

Component format

To setup local environment variables secret store create a component of type secretstores.local.env. Create a file with the following content in your ./components directory:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: envvar-secret-store
spec:
 type: secretstores.local.env
 version: v1
 metadata:
 # - name: prefix
 # value: "MYAPP_"

Spec metadata fields

Field	Required	Details	Example
`prefix`	N	If set, limits operations to environment variables with the given prefix. The prefix is removed from the returned secrets’ names. The matching is case-insensitive on Windows and case-sensitive on all other operating systems.	`"MYAPP_"`

Notes

For security reasons, this component cannot be used to access these environment variables:

Local file (for Development)

Mon, 01 Jan 0001 00:00:00 +0000

This Dapr secret store component reads plain text JSON from a given file and does not use authentication.

Warning

This approach to secret management is not recommended for production environments.

Component format

To setup local file based secret store create a component of type secretstores.local.file. Create a file with the following content in your ./components directory:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: local-secret-store
spec:
 type: secretstores.local.file
 version: v1
 metadata:
 - name: secretsFile
 value: [path to the JSON file]
 - name: nestedSeparator
 value: ":"
 - name: multiValued
 value: "false"

Spec metadata fields

Field	Required	Details	Example
secretsFile	Y	The path to the file where secrets are stored	`"path/to/file.json"`
nestedSeparator	N	Used by the store when flattening the JSON hierarchy to a map. Defaults to `":"`	`":"`
multiValued	N	`"true"` sets the `multipleKeyValuesPerSecret` behavior. Allows one level of multi-valued key/value pairs before flattening JSON hierarchy. Defaults to `"false"`	`"true"`

Setup JSON file to hold the secrets

Given the following JSON loaded from secretsFile:

Local storage

Mon, 01 Jan 0001 00:00:00 +0000

Component format

The purpose of this component is to load keys from a local directory.

The component accepts as input the name of a folder, and loads keys from there. Each key is in its own file, and when users request a key with a given name, Dapr loads the file with that name.

Supported file formats:

PEM with public and private keys (supports: PKCS#1, PKCS#8, PKIX)
JSON Web Key (JWK) containing a public, private, or symmetric key
Raw key data for symmetric keys

Note

This component uses the cryptographic engine in Dapr to perform operations. Although keys are never exposed to your application, Dapr has access to the raw key material.

A Dapr crypto.yaml component file has the following structure:

Local Storage binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up the Local Storage binding, create a component of type bindings.localstorage. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.localstorage
 version: v1
 metadata:
 - name: rootPath
 value: "<string>"

Spec metadata fields

Field	Required	Binding support	Details	Example
`rootPath`	Y	Output	The root path anchor to which files can be read / saved	`"/temp/files"`

Binding support

This component supports output binding with the following operations:

logs CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

Get Dapr sidecar logs for an application.

Supported platforms

Kubernetes

Usage

dapr logs [flags]

Flags

Name	Environment Variable	Default	Description
`--app-id`, `-a`	`APP_ID`		The application id for which logs are needed
`--help`, `-h`			Print this help message
`--kubernetes`, `-k`		`true`	Get logs from a Kubernetes cluster
`--namespace`, `-n`		`default`	The Kubernetes namespace in which your application is deployed
`--pod-name`, `-p`			The name of the pod in Kubernetes, in case your application has multiple pods (optional)

Examples

# Get logs of sample app from target pod in custom namespace
dapr logs -k --app-id sample --pod-name target --namespace custom

Warning messages

This command can issue warning messages.

mDNS

Mon, 01 Jan 0001 00:00:00 +0000

Configuration format

Multicast DNS (mDNS) is configured automatically in self-hosted mode by Dapr. There is no configuration needed to use mDNS as your name resolution provider.

Behaviour

The component resolves target apps by using the host system’s mDNS service. You can learn more about mDNS here.

Troubleshooting

In some cloud provider virtual networks, such as Microsoft Azure, mDNS is not available. Use an alternate provider such as HashiCorp Consul instead.

On some enterprise-managed systems, mDNS may be disabled on macOS if a network filter/proxy is configured. Check with your IT department if mDNS is disabled and you are unable to use service invocation locally.

Memcached

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Memcached state store create a component of type state.memcached. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.memcached
 version: v1
 metadata:
 - name: hosts
 value: <REPLACE-WITH-COMMA-DELIMITED-ENDPOINTS> # Required. Example: "memcached.default.svc.cluster.local:11211"
 - name: maxIdleConnections
 value: <REPLACE-WITH-MAX-IDLE-CONNECTIONS> # Optional. default: "2"
 - name: timeout
 value: <REPLACE-WITH-TIMEOUT> # Optional. default: "1000"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
hosts	Y	Comma delimited endpoints	`"memcached.default.svc.cluster.local:11211"`
maxIdleConnections	N	The max number of idle connections. Defaults to `"2"`	`"3"`
timeout	N	The timeout for the calls in milliseconds. Defaults to `"1000"`	`"1000"`

Setup Memcached

You can run Memcached locally using Docker:

Microsoft SQL Server & Azure SQL

Mon, 01 Jan 0001 00:00:00 +0000

Note

This is the v2 of the Sql Server state store component, which supports Dapr workflows. New applications are encouraged to use v2.

The Sql Server v2 state store component is not compatible with the v1 component, and data cannot be migrated between the two components.

There are no plans to deprecate the v1 component.

Component format

This state store component can be used with both Microsoft SQL Server and Azure SQL.

Microsoft SQL Server & Azure SQL

Mon, 01 Jan 0001 00:00:00 +0000

Component format

This state store component can be used with both Microsoft SQL Server and Azure SQL.

To set up this state store, create a component of type state.sqlserver. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.sqlserver
 version: v1
 metadata:
 # Authenticate using SQL Server credentials
 - name: connectionString
 value: |
 Server=myServerName\myInstanceName;Database=myDataBase;User Id=myUsername;Password=myPassword;

 # Authenticate with Microsoft Entra ID (Azure SQL only)
 # "useAzureAD" be set to "true"
 - name: useAzureAD
 value: true
 # Connection string or URL of the Azure SQL database, optionally containing the database
 - name: connectionString
 value: |
 sqlserver://myServerName.database.windows.net:1433?database=myDataBase

 # Other optional fields (listing default values)
 - name: tableName
 value: "state"
 - name: metadataTableName
 value: "dapr_metadata"
 - name: schema
 value: "dbo"
 - name: keyType
 value: "string"
 - name: keyLength
 value: "200"
 - name: indexedProperties
 value: ""
 - name: cleanupIntervalInSeconds
 value: "3600"
 # Uncomment this if you wish to use Microsoft SQL Server as a state store for actors (optional)
 #- name: actorStateStore
 # value: "true"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

If you wish to use SQL server as an actor state store, append the following to the metadata:

Mistral

Mon, 01 Jan 0001 00:00:00 +0000

Component format

A Dapr conversation.yaml component file has the following structure:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: mistral
spec:
 type: conversation.mistral
 metadata:
 - name: key
 value: mykey
 - name: model
 value: open-mistral-7b
 - name: responseCacheTTL
 value: 10m

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets, as described here.

Spec metadata fields

Field	Required	Details	Example
`key`	Y	API key for Mistral.	`mykey`
`model`	N	The Mistral LLM to use. Defaults to `open-mistral-7b`.	`open-mistral-7b`
`responseCacheTTL`	N	Time-to-live for the in-memory response cache. When set, identical requests are served from cache until they expire.	`10m`

Conversation API overview

MongoDB

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup MongoDB state store create a component of type state.mongodb. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.mongodb
 version: v1
 metadata:
 - name: server
 value: <REPLACE-WITH-SERVER> # Required unless "host" field is set . Example: "server.example.com"
 - name: host
 value: <REPLACE-WITH-HOST> # Required unless "server" field is set . Example: "mongo-mongodb.default.svc.cluster.local:27017"
 - name: username
 value: <REPLACE-WITH-USERNAME> # Optional. Example: "admin"
 - name: password
 value: <REPLACE-WITH-PASSWORD> # Optional.
 - name: databaseName
 value: <REPLACE-WITH-DATABASE-NAME> # Optional. default: "daprStore"
 - name: collectionName
 value: <REPLACE-WITH-COLLECTION-NAME> # Optional. default: "daprCollection"
 - name: writeConcern
 value: <REPLACE-WITH-WRITE-CONCERN> # Optional.
 - name: readConcern
 value: <REPLACE-WITH-READ-CONCERN> # Optional.
 - name: operationTimeout
 value: <REPLACE-WITH-OPERATION-TIMEOUT> # Optional. default: "5s"
 - name: params
 value: <REPLACE-WITH-ADDITIONAL-PARAMETERS> # Optional. Example: "?authSource=daprStore&ssl=true"
 # Uncomment this if you wish to use MongoDB as a state store for actors (optional)
 #- name: actorStateStore
 # value: "true"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Actor state store and transactions support

When using as an actor state store or to leverage transactions, MongoDB must be running in a Replica Set.

MQTT

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up MQTT pub/sub, create a component of type pubsub.mqtt. See the pub/sub broker component file to learn how ConsumerID is automatically generated. Read the How-to: Publish and Subscribe guide on how to create and apply a pub/sub configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: mqtt-pubsub
spec:
 type: pubsub.mqtt
 version: v1
 metadata:
 - name: url
 value: "tcp://[username][:password]@host.domain[:port]"
 - name: qos
 value: 1
 - name: retain
 value: "false"
 - name: cleanSession
 value: "false"
 - name: consumerID
 value: "channel1"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
url	Y	Address of the MQTT broker. Can be `secretKeyRef` to use a secret reference. Use the `tcp://` URI scheme for non-TLS communication. Use the `ssl://` URI scheme for TLS communication.	`"tcp://[username][:password]@host.domain[:port]"`
consumerID	N	The client ID used to connect to the MQTT broker for the consumer connection. Defaults to the Dapr app ID. Note: if `producerID` is not set, `-consumer` is appended to this value for the consumer connection	Can be set to string value (such as `"channel1"` in the example above) or string format value (such as `"{podName}"`, etc.). See all of template tags you can use in your component metadata.
producerID	N	The client ID used to connect to the MQTT broker for the producer connection. Defaults to `{consumerID}-producer`.	`"myMqttProducerApp"`
qos	N	Indicates the Quality of Service Level (QoS) of the message (more info). Defaults to `1`.	`0`, `1`, `2`
retain	N	Defines whether the message is saved by the broker as the last known good value for a specified topic. Defaults to `"false"`.	`"true"`, `"false"`
cleanSession	N	Sets the `clean_session` flag in the connection message to the MQTT broker if `"true"` (more info). Defaults to `"false"`.	`"true"`, `"false"`
caCert	Required for using TLS	Certificate Authority (CA) certificate in PEM format for verifying server TLS certificates.	`"-----BEGIN CERTIFICATE-----\n<base64-encoded DER>\n-----END CERTIFICATE-----"`
clientCert	Required for using TLS	TLS client certificate in PEM format. Must be used with `clientKey`.	`"-----BEGIN CERTIFICATE-----\n<base64-encoded DER>\n-----END CERTIFICATE-----"`
clientKey	Required for using TLS	TLS client key in PEM format. Must be used with `clientCert`. Can be `secretKeyRef` to use a secret reference.	`"-----BEGIN RSA PRIVATE KEY-----\n<base64-encoded PKCS8>\n-----END RSA PRIVATE KEY-----"`

Enabling message delivery retries

The MQTT pub/sub component has no built-in support for retry strategies. This means that the sidecar sends a message to the service only once. If the service marks the message as not processed, the message won’t be acknowledged back to the broker. Only if broker resends the message, would it would be retried.

MQTT3 binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup a MQTT3 binding create a component of type bindings.mqtt3. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.mqtt3
 version: v1
 metadata:
 - name: url
 value: "tcp://[username][:password]@host.domain[:port]"
 - name: topic
 value: "mytopic"
 - name: consumerID
 value: "myapp"
 # Optional
 - name: retain
 value: "false"
 - name: cleanSession
 value: "false"
 - name: backOffMaxRetries
 value: "0"
 - name: direction
 value: "input, output"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`url`	Y	Input/Output	Address of the MQTT broker. Can be `secretKeyRef` to use a secret reference. Use the `tcp://` URI scheme for non-TLS communication. Use the `ssl://` URI scheme for TLS communication.	`"tcp://[username][:password]@host.domain[:port]"`
`topic`	Y	Input/Output	The topic to listen on or send events to.	`"mytopic"`
`consumerID`	Y	Input/Output	The client ID used to connect to the MQTT broker.	`"myMqttClientApp"`
`retain`	N	Input/Output	Defines whether the message is saved by the broker as the last known good value for a specified topic. Defaults to `"false"`.	`"true"`, `"false"`
`cleanSession`	N	Input/Output	Sets the `clean_session` flag in the connection message to the MQTT broker if `"true"`. Defaults to `"false"`.	`"true"`, `"false"`
`caCert`	Required for using TLS	Input/Output	Certificate Authority (CA) certificate in PEM format for verifying server TLS certificates.	See example below
`clientCert`	Required for using TLS	Input/Output	TLS client certificate in PEM format. Must be used with `clientKey`.	See example below
`clientKey`	Required for using TLS	Input/Output	TLS client key in PEM format. Must be used with `clientCert`. Can be `secretKeyRef` to use a secret reference.	See example below
`backOffMaxRetries`	N	Input	The maximum number of retries to process the message before returning an error. Defaults to `"0"`, which means that no retries will be attempted. `"-1"` can be specified to indicate that messages should be retried indefinitely until they are successfully processed or the application is shutdown. The component will wait 5 seconds between retries.	`"3"`
`direction`	N	Input/Output	The direction of the binding	`"input"`, `"output"`, `"input, output"`

Communication using TLS

To configure communication using TLS, ensure that the MQTT broker (e.g. emqx) is configured to support certificates and provide the caCert, clientCert, clientKey metadata in the component configuration. For example:

MQTT3

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up a MQTT3 pub/sub, create a component of type pubsub.mqtt3. See the pub/sub broker component file to learn how ConsumerID is automatically generated. Read the How-to: Publish and Subscribe guide on how to create and apply a pub/sub configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: mqtt-pubsub
spec:
 type: pubsub.mqtt3
 version: v1
 metadata:
 - name: url
 value: "tcp://[username][:password]@host.domain[:port]"
 # Optional
 - name: retain
 value: "false"
 - name: cleanSession
 value: "false"
 - name: qos
 value: "1"
 - name: consumerID
 value: "channel1"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
`url`	Y	Address of the MQTT broker. Can be `secretKeyRef` to use a secret reference. Use the `tcp://` URI scheme for non-TLS communication. Use the `ssl://` URI scheme for TLS communication.	`"tcp://[username][:password]@host.domain[:port]"`
`consumerID`	N	The client ID used to connect to the MQTT broker. Defaults to the Dapr app ID.	Can be set to string value (such as `"channel1"` in the example above) or string format value (such as `"{podName}"`, etc.). See all of template tags you can use in your component metadata.
`retain`	N	Defines whether the message is saved by the broker as the last known good value for a specified topic. Defaults to `"false"`.	`"true"`, `"false"`
`cleanSession`	N	Sets the `clean_session` flag in the connection message to the MQTT broker if `"true"` (more info). Defaults to `"false"`.	`"true"`, `"false"`
`caCert`	Required for using TLS	Certificate Authority (CA) certificate in PEM format for verifying server TLS certificates.	See example below
`clientCert`	Required for using TLS	TLS client certificate in PEM format. Must be used with `clientKey`.	See example below
`clientKey`	Required for using TLS	TLS client key in PEM format. Must be used with `clientCert`. Can be `secretKeyRef` to use a secret reference.	See example below
`qos`	N	Indicates the Quality of Service Level (QoS) of the message (more info). Defaults to `1`.	`0`, `1`, `2`

Communication using TLS

To configure communication using TLS, ensure that the MQTT broker (for example, emqx) is configured to support certificates and provide the caCert, clientCert, clientKey metadata in the component configuration. For example:

MySQL & MariaDB binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

The MySQL binding allows connecting to both MySQL and MariaDB databases. In this document, we refer to “MySQL” to indicate both databases.

To setup a MySQL binding create a component of type bindings.mysql. See this guide on how to create and apply a binding configuration.

The MySQL binding uses Go-MySQL-Driver internally.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.mysql
 version: v1
 metadata:
 - name: url # Required, define DB connection in DSN format
 value: "<CONNECTION_STRING>"
 - name: pemPath # Optional
 value: "<PEM PATH>"
 - name: maxIdleConns
 value: "<MAX_IDLE_CONNECTIONS>"
 - name: maxOpenConns
 value: "<MAX_OPEN_CONNECTIONS>"
 - name: connMaxLifetime
 value: "<CONNECTION_MAX_LIFE_TIME>"
 - name: connMaxIdleTime
 value: "<CONNECTION_MAX_IDLE_TIME>"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here. Note that you can not use secret just for username/password. If you use secret, it has to be for the complete connection string.

Spec metadata fields

Field	Required	Binding support	Details	Example
`url`	Y	Output	Represent DB connection in Data Source Name (DNS) format. See here SSL details	`"user:password@tcp(localhost:3306)/dbname"`
`pemPath`	Y	Output	Path to the PEM file. Used with SSL connection	`"path/to/pem/file"`
`maxIdleConns`	N	Output	The max idle connections. Integer greater than 0	`"10"`
`maxOpenConns`	N	Output	The max open connections. Integer greater than 0	`"10"`
`connMaxLifetime`	N	Output	The max connection lifetime. Duration string	`"12s"`
`connMaxIdleTime`	N	Output	The max connection idle time. Duration string	`"12s"`

SSL connection

If your server requires SSL your connection string must end of &tls=custom for example:

MySQL & MariaDB

Mon, 01 Jan 0001 00:00:00 +0000

Component format

The MySQL state store components allows connecting to both MySQL and MariaDB databases. In this document, we refer to “MySQL” to indicate both databases.

To setup MySQL state store create a component of type state.mysql. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.mysql
 version: v1
 metadata:
 - name: connectionString
 value: "<CONNECTION STRING>"
 - name: schemaName
 value: "<SCHEMA NAME>"
 - name: tableName
 value: "<TABLE NAME>"
 - name: timeoutInSeconds
 value: "30"
 - name: pemPath # Required if pemContents not provided. Path to pem file.
 value: "<PEM PATH>"
 - name: pemContents # Required if pemPath not provided. Pem value.
 value: "<PEM CONTENTS>" 
# Uncomment this if you wish to use MySQL & MariaDB as a state store for actors (optional)
 #- name: actorStateStore
 # value: "true"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

If you wish to use MySQL as an actor store, append the following to the yaml.

Nameformat

Mon, 01 Jan 0001 00:00:00 +0000

The Name Format name resolver provides a flexible way to resolve service names using a configurable format string with placeholders. This is useful in scenarios where you want to map service names to predictable DNS names following a specific pattern.

Consider using this name resolver if there is no specific name resolver available for your service registry, but your service registry can expose services via internal DNS names using predictable naming conventions.

OAuth2

Mon, 01 Jan 0001 00:00:00 +0000

The OAuth2 HTTP middleware enables the OAuth2 Authorization Code flow on a Web API without modifying the application. This design separates authentication/authorization concerns from the application, so that application operators can adopt and configure authentication/authorization providers without impacting the application code.

Component format

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: oauth2
spec:
 type: middleware.http.oauth2
 version: v1
 metadata:
 - name: clientId
 value: "<your client ID>"
 - name: clientSecret
 value: "<your client secret>"
 - name: scopes
 value: "https://www.googleapis.com/auth/userinfo.email"
 - name: authURL
 value: "https://accounts.google.com/o/oauth2/v2/auth"
 - name: tokenURL
 value: "https://accounts.google.com/o/oauth2/token"
 - name: redirectURL
 value: "http://dummy.com"
 - name: authHeaderName
 value: "authorization"
 - name: forceHTTPS
 value: "false"
 - name: pathFilter
 value: ".*/users/.*"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Details	Example
clientId	The client ID of your application that is created as part of a credential hosted by a OAuth-enabled platform
clientSecret	The client secret of your application that is created as part of a credential hosted by a OAuth-enabled platform
scopes	A list of space-delimited, case-sensitive strings of scopes which are typically used for authorization in the application	`"https://www.googleapis.com/auth/userinfo.email"`
authURL	The endpoint of the OAuth2 authorization server	`"https://accounts.google.com/o/oauth2/v2/auth"`
tokenURL	The endpoint is used by the client to obtain an access token by presenting its authorization grant or refresh token	`"https://accounts.google.com/o/oauth2/token"`
redirectURL	The URL of your web application that the authorization server should redirect to once the user has authenticated	`"https://myapp.com"`
authHeaderName	The authorization header name to forward to your application	`"authorization"`
forceHTTPS	If true, enforces the use of TLS/SSL	`"true"`,`"false"`
pathFilter	Applies the middleware only to requests matching the given path pattern	`"./users/."`

Dapr configuration

To be applied, the middleware must be referenced in configuration. See middleware pipelines.

OAuth2 client credentials

Mon, 01 Jan 0001 00:00:00 +0000

The OAuth2 client credentials HTTP middleware enables the OAuth2 Client Credentials flow on a Web API without modifying the application. This design separates authentication/authorization concerns from the application, so that application operators can adopt and configure authentication/authorization providers without impacting the application code.

Component format

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: oauth2clientcredentials
spec:
 type: middleware.http.oauth2clientcredentials
 version: v1
 metadata:
 - name: clientId
 value: "<your client ID>"
 - name: clientSecret
 value: "<your client secret>"
 - name: scopes
 value: "https://www.googleapis.com/auth/userinfo.email"
 - name: tokenURL
 value: "https://accounts.google.com/o/oauth2/token"
 - name: headerName
 value: "authorization"
 - name: pathFilter
 value: ".*/users/.*"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Details	Example
clientId	The client ID of your application that is created as part of a credential hosted by a OAuth-enabled platform
clientSecret	The client secret of your application that is created as part of a credential hosted by a OAuth-enabled platform
scopes	A list of space-delimited, case-sensitive strings of scopes which are typically used for authorization in the application	`"https://www.googleapis.com/auth/userinfo.email"`
tokenURL	The endpoint is used by the client to obtain an access token by presenting its authorization grant or refresh token	`"https://accounts.google.com/o/oauth2/token"`
headerName	The authorization header name to forward to your application	`"authorization"`
endpointParamsQuery	Specifies additional parameters for requests to the token endpoint	`true`
authStyle	Optionally specifies how the endpoint wants the client ID & client secret sent. See the table of possible values below	`0`
pathFilter	Applies the middleware only to requests matching the given path pattern	`"./users/."`

Possible values for `authStyle`

Value	Meaning
`1`	Sends the “client_id” and “client_secret” in the POST body as application/x-www-form-urlencoded parameters.
`2`	Sends the “client_id” and “client_secret” using HTTP Basic Authorization. This is an optional style described in the OAuth2 RFC 6749 section 2.3.1.
`0`	Means to auto-detect which authentication style the provider wants by trying both ways and caching the successful way for the future.

Dapr configuration

To be applied, the middleware must be referenced in a configuration. See middleware pipelines.

OCI Object Storage

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup OCI Object Storage state store create a component of type state.oci.objectstorage. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.oci.objectstorage
 version: v1
 metadata:
 - name: instancePrincipalAuthentication
 value: <"true" or "false">  # Optional. default: "false" 
 - name: configFileAuthentication
 value: <"true" or "false">  # Optional. default: "false" . Not used when instancePrincipalAuthentication == "true" 
 - name: configFilePath
 value: <REPLACE-WITH-FULL-QUALIFIED-PATH-OF-CONFIG-FILE>  # Optional. No default. Only used when configFileAuthentication == "true" 
 - name: configFileProfile
 value: <REPLACE-WITH-NAME-OF-PROFILE-IN-CONFIG-FILE> # Optional. default: "DEFAULT" . Only used when configFileAuthentication == "true" 
 - name: tenancyOCID
 value: <REPLACE-WITH-TENANCY-OCID>  # Not used when configFileAuthentication == "true" or instancePrincipalAuthentication == "true" 
 - name: userOCID
 value: <REPLACE-WITH-USER-OCID>  # Not used when configFileAuthentication == "true" or instancePrincipalAuthentication == "true" 
 - name: fingerPrint
 value: <REPLACE-WITH-FINGERPRINT>  # Not used when configFileAuthentication == "true" or instancePrincipalAuthentication == "true" 
 - name: privateKey  # Not used when configFileAuthentication == "true" or instancePrincipalAuthentication == "true" 
 value: |
 -----BEGIN RSA PRIVATE KEY-----
 REPLACE-WITH-PRIVATE-KEY-AS-IN-PEM-FILE
 -----END RSA PRIVATE KEY----- 
 - name: region
 value: <REPLACE-WITH-OCI-REGION>  # Not used when configFileAuthentication == "true" or instancePrincipalAuthentication == "true" 
 - name: bucketName
	 value: <REPLACE-WITH-BUCKET-NAME>
 - name: compartmentOCID
 value: <REPLACE-WITH-COMPARTMENT-OCID>

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
instancePrincipalAuthentication	N	Boolean to indicate whether instance principal based authentication is used. Default: `"false"`	`"true"` or `"false"` .
configFileAuthentication	N	Boolean to indicate whether identity credential details are provided through a configuration file. Default: `"false"` Not required nor used when instancePrincipalAuthentication is true.	`"true"` or `"false"` .
configFilePath	N	Full path name to the OCI configuration file. No default value exists. Not used when instancePrincipalAuthentication is true. Note: the ~/ prefix is not supported.	`"/home/apps/configuration-files/myOCIConfig.txt"`.
configFileProfile	N	Name of profile in configuration file to use. Default: `"DEFAULT"` Not used when instancePrincipalAuthentication is true.	`"DEFAULT"` or `"PRODUCTION"` .
tenancyOCID	Y	The OCI tenancy identifier. Not required nor used when instancePrincipalAuthentication is true.	`"ocid1.tenancy.oc1..aaaaaaaag7c7sljhsdjhsdyuwe723"`.
userOCID	Y	The OCID for an OCI account (this account requires permissions to access OCI Object Storage). Not required nor used when instancePrincipalAuthentication is true.	`"ocid1.user.oc1..aaaaaaaaby4oyyyuqwy7623yuwe76"`
fingerPrint	Y	Fingerprint of the public key. Not required nor used when instancePrincipalAuthentication is true.	`"02:91:6c:49:e2:94:21:15:a7:6b:0e:a7:34:e1:3d:1b"`
privateKey	Y	Private key of the RSA key pair. Not required nor used when instancePrincipalAuthentication is true.	`"MIIEoyuweHAFGFG2727as+7BTwQRAIW4V"`
region	Y	OCI Region. Not required nor used when instancePrincipalAuthentication is true.	`"us-ashburn-1"`
bucketName	Y	Name of the bucket written to and read from (and if necessary created)	`"application-state-store-bucket"`
compartmentOCID	Y	The OCID for the compartment that contains the bucket	`"ocid1.compartment.oc1..aaaaaaaacsssekayyuq7asjh78"`

Setup OCI Object Storage

The OCI Object Storage state store needs to interact with Oracle Cloud Infrastructure. The state store supports two different approaches to authentication. One is based on an identity (a user or service account) and the other is instance principal authentication leveraging the permissions granted to the compute instance running the application workload. Note: Resource Principal Authentication - used for resources that are not instances such as serverless functions - is not currently supported.

Ollama

Mon, 01 Jan 0001 00:00:00 +0000

Component format

A Dapr conversation.yaml component file has the following structure:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: ollama
spec:
 type: conversation.ollama
 metadata:
 - name: model
 value: llama3.2:latest
 - name: responseCacheTTL
 value: 10m

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets, as described here.

Spec metadata fields

Field	Required	Details	Example
`model`	N	The Ollama LLM to use. Defaults to `llama3.2:latest`.	`phi4:latest`
`responseCacheTTL`	N	Time-to-live for the in-memory response cache. When set, identical requests are served from cache until they expire.	`10m`

OpenAI Compatibility

Ollama is compatible with OpenAI’s API. You can use the OpenAI component with Ollama models with the following changes:

Apply Open Policy Agent (OPA) policies

Mon, 01 Jan 0001 00:00:00 +0000

The Open Policy Agent (OPA) HTTP middleware applies OPA Policies to incoming Dapr HTTP requests. This can be used to apply reusable authorization policies to app endpoints.

Component format

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: my-policy
spec:
 type: middleware.http.opa
 version: v1
 metadata:
 # `includedHeaders` is a comma-separated set of case-insensitive headers to include in the request input.
 # Request headers are not passed to the policy by default. Include to receive incoming request headers in
 # the input
 - name: includedHeaders
 value: "x-my-custom-header, x-jwt-header"

 # `defaultStatus` is the status code to return for denied responses
 - name: defaultStatus
 value: 403

 # `readBody` controls whether the middleware reads the entire request body in-memory and make it
 # available for policy decisions.
 - name: readBody
 value: "false"

 # `rego` is the open policy agent policy to evaluate. required
 # The policy package must be http and the policy must set data.http.allow
 - name: rego
 value: |
 package http

 default allow = true

 # Allow may also be an object and include other properties

 # For example, if you wanted to redirect on a policy failure, you could set the status code to 301 and set the location header on the response:
 allow = {
 "status_code": 301,
 "additional_headers": {
 "location": "https://my.site/authorize"
 }
 } {
 not jwt.payload["my-claim"]
 }

 # You can also allow the request and add additional headers to it:
 allow = {
 "allow": true,
 "additional_headers": {
 "x-my-claim": my_claim
 }
 } {
 my_claim := jwt.payload["my-claim"]
 }
 jwt = { "payload": payload } {
 auth_header := input.request.headers["Authorization"]
 [_, jwt] := split(auth_header, " ")
 [_, payload, _] := io.jwt.decode(jwt)
 }

You can prototype and experiment with policies using the official OPA playground. For example, you can find the example policy above here.

OpenAI

Mon, 01 Jan 0001 00:00:00 +0000

Component format

A Dapr conversation.yaml component file has the following structure:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: openai
spec:
 type: conversation.openai
 metadata:
 - name: key
 value: mykey
 - name: model
 value: gpt-4-turbo
 - name: endpoint
 value: 'https://api.openai.com/v1'
 - name: responseCacheTTL
 value: 10m
 # - name: apiType # Optional
 # value: 'azure'
 # - name: apiVersion # Optional
 # value: '2025-01-01-preview'

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets, as described here.

Spec metadata fields

Field	Required	Details	Example
`key`	Y	API key for OpenAI.	`mykey`
`model`	N	The OpenAI LLM to use. Defaults to `gpt-4-turbo`.	`gpt-4-turbo`
`endpoint`	N	Custom API endpoint URL for OpenAI API-compatible services. If not specified, the default OpenAI API endpoint is used. Required when `apiType` is set to `azure`.	`https://api.openai.com/v1`, `https://example.openai.azure.com/`
`responseCacheTTL`	N	Time-to-live for the in-memory response cache. When set, identical requests are served from cache until they expire.	`10m`
`apiType`	N	Specifies the API provider type. Required when using a provider that does not follow the default OpenAI API endpoint conventions.	`azure`
`apiVersion`	N	The API version to use. Required when the `apiType` is set to `azure`.	`2025-04-01-preview`

Azure OpenAI Configuration

To configure the OpenAI component to connect to Azure OpenAI, you need to set the following metadata fields which are required for Azure’s API format.

OpenBao

Mon, 01 Jan 0001 00:00:00 +0000

Usage

Currently, there is no dedicated OpenBao Secrets Store. However, you can utilize the secretstores.hashicorp.vault component, which has been tested and confirmed to work effectively.

For instructions on how to set up and configure a secret store, refer to the HashiCorp Vault guide. The same metadata fields are compatible with OpenBao.

Example Component

---
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: openbao
spec:
 # Use the secrets store provider
 # from vault
 type: secretstores.hashicorp.vault
 version: v1
 metadata:
 - name: vaultAddr
 value: http://openbao.openbao.svc.cluster.local:8200
 - name: skipVerify # Optional. Default: false
 value: true
 - name: vaultToken
 secretKeyRef:
 name: roottoken
 key: token
 - name: enginePath # Optional. default: "secret"
 value: "secrets"
 - name: vaultValueType # Optional. default: "map"
 value: "map"

Further Information

Dapr Operator control plane service overview

Mon, 01 Jan 0001 00:00:00 +0000

When running Dapr in Kubernetes mode, a pod running the Dapr Operator service manages Dapr component updates and provides Kubernetes services endpoints for Dapr.

Running the operator service

The operator 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.

Additional configuration options

The operator service includes additional configuration options.

Injector watchdog

The operator service includes an injector watchdog feature which periodically polls all pods running in your Kubernetes cluster and confirms that the Dapr sidecar is injected in those which have the dapr.io/enabled=true annotation. It is primarily meant to address situations where the Injector service did not successfully inject the sidecar (the daprd container) into pods.

Oracle Database

Mon, 01 Jan 0001 00:00:00 +0000

Component format

Create a component properties yaml file, for example called oracle.yaml (but it could be named anything ), paste the following and replace the <CONNECTION STRING> value with your connection string. The connection string is a standard Oracle Database connection string, composed as: "oracle://user/password@host:port/servicename" for example "oracle://demo:demo@localhost:1521/xe".

In case you connect to the database using an Oracle Wallet, you should specify a value for the oracleWalletLocation property, for example: "/home/app/state/Wallet_daprDB/"; this should refer to the local file system directory that contains the file cwallet.sso that is extracted from the Oracle Wallet archive file.

Dapr Placement control plane service overview

Mon, 01 Jan 0001 00:00:00 +0000

The Dapr Placement service is used to calculate and distribute distributed hash tables for the location of Dapr actors running in self-hosted mode or on Kubernetes. Grouped by namespace, the hash tables map actor types to pods or processes so a Dapr application can communicate with the actor. Anytime a Dapr application activates a Dapr actor, the Placement service updates the hash tables with the latest actor location.

Self-hosted mode

The Placement 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.

PostgreSQL binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup PostgreSQL binding create a component of type bindings.postgresql. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.postgresql
 version: v1
 metadata:
 # Connection string
 - name: connectionString
 value: "<CONNECTION STRING>"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Authenticate using a connection string

The following metadata options are required to authenticate using a PostgreSQL connection string.

PostgreSQL

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up an PostgreSQL configuration store, create a component of type configuration.postgresql

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: configuration.postgresql
 version: v1
 metadata:
 # Connection string
 - name: connectionString
 value: "host=localhost user=postgres password=example port=5432 connect_timeout=10 database=config"
 # Name of the table which holds configuration information
 - name: table
 value: "[your_configuration_table_name]" 
 # Individual connection parameters - can be used instead to override connectionString parameters
 #- name: host
 # value: "localhost"
 #- name: hostaddr
 # value: "127.0.0.1"
 #- name: port
 # value: "5432"
 #- name: database
 # value: "my_db"
 #- name: user
 # value: "postgres"
 #- name: password
 # value: "example"
 #- name: sslRootCert
 # value: "/path/to/ca.crt"
 # Timeout for database operations, in seconds (optional)
 #- name: timeoutInSeconds
 # value: 20
 # Name of the table where to store the state (optional)
 #- name: tableName
 # value: "state"
 # Name of the table where to store metadata used by Dapr (optional)
 #- name: metadataTableName
 # value: "dapr_metadata"
 # Cleanup interval in seconds, to remove expired rows (optional)
 #- name: cleanupIntervalInSeconds
 # value: 3600
 # Maximum number of connections pooled by this component (optional)
 #- name: maxConns
 # value: 0
 # Max idle time for connections before they're closed (optional)
 #- name: connectionMaxIdleTime
 # value: 0
 # Controls the default mode for executing queries. (optional)
 #- name: queryExecMode
 # value: ""
 # Uncomment this if you wish to use PostgreSQL as a state store for actors (optional)
 #- name: actorStateStore
 # value: "true"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Authenticate using a connection string

The following metadata options are required to authenticate using a PostgreSQL connection string.

PostgreSQL

Mon, 01 Jan 0001 00:00:00 +0000

Note

This is the v2 of the PostgreSQL state store component, which contains some improvements to performance and reliability. New applications are encouraged to use v2.

The PostgreSQL v2 state store component is not compatible with the v1 component, and data cannot be migrated between the two components. The v2 component does not offer support for state store query APIs.

There are no plans to deprecate the v1 component.

This component allows using PostgreSQL (Postgres) as state store for Dapr, using the “v2” component. See this guide on how to create and apply a state store configuration.

PostgreSQL v1

Mon, 01 Jan 0001 00:00:00 +0000

Note

Starting with Dapr 1.13, you can leverage the PostgreSQL v2 state store component, which contains some improvements to performance and reliability.
The v2 component is not compatible with v1, and data cannot be migrated between the two components. The v2 component does not offer support for state store query APIs.

There are no plans to deprecate the v1 component.

This component allows using PostgreSQL (Postgres) as state store for Dapr, using the “v1” component. See this guide on how to create and apply a state store configuration.

Postmark binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Postmark binding create a component of type bindings.postmark. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: postmark
spec:
 type: bindings.postmark
 metadata:
 - name: accountToken
 value: "YOUR_ACCOUNT_TOKEN" # required, this is your Postmark account token
 - name: serverToken
 value: "YOUR_SERVER_TOKEN" # required, this is your Postmark server token
 - name: emailFrom
 value: "testapp@dapr.io" # optional
 - name: emailTo
 value: "dave@dapr.io" # optional
 - name: subject
 value: "Hello!" # optional

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`accountToken`	Y	Output	The Postmark account token, this should be considered a secret value	`"account token"`
`serverToken`	Y	Output	The Postmark server token, this should be considered a secret value	`"server token"`
`emailFrom`	N	Output	If set this specifies the ‘from’ email address of the email message	`"me@exmaple.com"`
`emailTo`	N	Output	If set this specifies the ’to’ email address of the email message	`"me@example.com"`
`emailCc`	N	Output	If set this specifies the ‘cc’ email address of the email message	`"me@example.com"`
`emailBcc`	N	Output	If set this specifies the ‘bcc’ email address of the email message	`"me@example.com"`
`subject`	N	Output	If set this specifies the subject of the email message	`"me@example.com"`

You can specify any of the optional metadata properties on the output binding request too (e.g. emailFrom, emailTo, subject, etc.)

publish CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

Publish a pub-sub event.

Supported platforms

Self-Hosted

Usage

dapr publish [flags]

Flags

Name	Default	Description
`--publish-app-id`, `-i`	The ID that represents the app from which you are publishing
`--pubsub`, `-p`	The name of the pub/sub component
`--topic`, `-t`		The topic to be published to
`--data`, `-d`		The JSON serialized string (optional)
`--data-file`, `-f`		A file containing the JSON serialized data (optional)
`--help`, `-h`		Print this help message
`--metadata`, `-m`		A JSON serialized publish metadata (optional)
`--unix-domain-socket`, `-u`		The path to the unix domain socket (optional)

Examples

# Publish to sample topic in target pubsub via a publishing app
dapr publish --publish-app-id appId --topic sample --pubsub target --data '{"key":"value"}'

# Publish to sample topic in target pubsub via a publishing app using Unix domain socket
dapr publish --enable-domain-socket --publish-app-id myapp --pubsub target --topic sample --data '{"key":"value"}'

# Publish to sample topic in target pubsub via a publishing app without cloud event
dapr publish --publish-app-id myapp --pubsub target --topic sample --data '{"key":"value"}' --metadata '{"rawPayload":"true"}'

Pulsar

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up Apache Pulsar pub/sub, create a component of type pubsub.pulsar. See the pub/sub broker component file to learn how ConsumerID is automatically generated. Read the How-to: Publish and Subscribe guide on how to create and apply a pub/sub configuration.

For more information on Apache Pulsar, read the official docs.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: pulsar-pubsub
spec:
 type: pubsub.pulsar
 version: v1
 metadata:
 - name: host
 value: "localhost:6650"
 - name: enableTLS
 value: "false"
 - name: tenant
 value: "public"
 - name: token
 value: "eyJrZXlJZCI6InB1bHNhci1wajU0cXd3ZHB6NGIiLCJhbGciOiJIUzI1NiJ9.eyJzd"
 - name: consumerID
 value: "channel1"
 - name: namespace
 value: "default"
 - name: persistent
 value: "true"
 - name: disableBatching
 value: "false"
 - name: receiverQueueSize
 value: "1000"
 - name: <topic-name>.jsonschema # sets a json schema validation for the configured topic
 value: |
 {
 "type": "record",
 "name": "Example",
 "namespace": "test",
 "fields": [
 {"name": "ID","type": "int"},
 {"name": "Name","type": "string"}
 ]
 }
 - name: <topic-name>.avroschema # sets an avro schema validation for the configured topic
 value: |
 {
 "type": "record",
 "name": "Example",
 "namespace": "test",
 "fields": [
 {"name": "ID","type": "int"},
 {"name": "Name","type": "string"}
 ]
 }

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets. This component supports storing the token parameter and any other sensitive parameter and data as Kubernetes Secrets.

Spec metadata fields

Field	Required	Details	Example
host	Y	Address of the Pulsar broker. Default is `"localhost:6650"`	`"localhost:6650"` OR `"http://pulsar-pj54qwwdpz4b-pulsar.ap-sg.public.pulsar.com:8080"`
enableTLS	N	Enable TLS. Default: `"false"`	`"true"`, `"false"`
tenant	N	The topic tenant within the instance. Tenants are essential to multi-tenancy in Pulsar, and spread across clusters. Default: `"public"`	`"public"`
consumerID	N	Used to set the subscription name or consumer ID.	Can be set to string value (such as `"channel1"` in the example above) or string format value (such as `"{podName}"`, etc.). See all of template tags you can use in your component metadata.
namespace	N	The administrative unit of the topic, which acts as a grouping mechanism for related topics. Default: `"default"`	`"default"`
persistent	N	Pulsar supports two kinds of topics: persistent and non-persistent. With persistent topics, all messages are durably persisted on disks (if the broker is not standalone, messages are durably persisted on multiple disks), whereas data for non-persistent topics is not persisted to storage disks.
disableBatching	N	disable batching.When batching enabled default batch delay is set to 10 ms and default batch size is 1000 messages,Setting `disableBatching: true` will make the producer to send messages individually. Default: `"false"`	`"true"`, `"false"`
receiverQueueSize	N	Sets the size of the consumer receiver queue. Controls how many messages can be accumulated by the consumer before it is explicitly called to read messages by Dapr. Default: `"1000"`	`"1000"`
redeliveryDelay	N	Delay before redelivering a message that was not acknowledged by the app. Default: `"30s"`	`"30s"`, `"200ms"`
batchingMaxPublishDelay	N	batchingMaxPublishDelay set the time period within which the messages sent will be batched,if batch messages are enabled. If set to a non zero value, messages will be queued until this time interval or batchingMaxMessages (see below) or batchingMaxSize (see below). There are two valid formats, one is the fraction with a unit suffix format, and the other is the pure digital format that is processed as milliseconds. Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”. Default: `"10ms"`	`"10ms"`, `"10"`
batchingMaxMessages	N	batchingMaxMessages set the maximum number of messages permitted in a batch.If set to a value greater than 1, messages will be queued until this threshold is reached or batchingMaxSize (see below) has been reached or the batch interval has elapsed. Default: `"1000"`	`"1000"`
batchingMaxSize	N	batchingMaxSize sets the maximum number of bytes permitted in a batch. If set to a value greater than 1, messages will be queued until this threshold is reached or batchingMaxMessages (see above) has been reached or the batch interval has elapsed. Default: `"128KB"`	`"131072"`
compressionType	N	Sets the compression type for messages sent by the producer. Default: `"none"`	`"none"`, `"lz4"`, `"zlib"`, `"zstd"`
compressionLevel	N	Sets the compression level used when `compressionType` is enabled. Default: `"default"`	`"default"`, `"faster"`, `"better"`
.jsonschema	N	Enforces JSON schema validation for the configured topic.
.avroschema	N	Enforces Avro schema validation for the configured topic.
.rawschema	N	Registers the provided Avro or JSON schema as-is instead of wrapping it in a CloudEvents envelope schema. Default: `"false"`	`"true"`, `"false"`
publicKey	N	A public key to be used for publisher and consumer encryption. Value can be one of two options: file path for a local PEM cert, or the cert data string value
privateKey	N	A private key to be used for consumer encryption. Value can be one of two options: file path for a local PEM cert, or the cert data string value
keys	N	A comma delimited string containing names of Pulsar session keys. Used in conjunction with `publicKey` for publisher encryption
processMode	N	Enable processing multiple messages at once. Default: `"async"`	`"async"`, `"sync"`
subscribeType	N	Pulsar supports four kinds of subscription types. Default: `"shared"`	`"shared"`, `"exclusive"`, `"failover"`, `"key_shared"`
subscribeInitialPosition	N	Subscription position is the initial position which the cursor is set when start consuming. Default: `"latest"`	`"latest"`, `"earliest"`
subscribeMode	N	Subscription mode indicates the cursor persistence, durable subscription retains messages and persists the current position. Default: `"durable"`	`"durable"`, `"non_durable"`
partitionKey	N	Sets the key of the message for routing policy. Default: `""`
`maxConcurrentHandlers`	N	Defines the maximum number of concurrent message handlers. Default: `100`	`10`
replicateSubscriptionState	N	Enable replication of subscription state across geo-replicated Pulsar clusters. Default: `"false"`	`"true"`, `"false"`

Authenticate using Token

To authenticate to pulsar using a static JWT token, you can use the following metadata field:

RabbitMQ binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup RabbitMQ binding create a component of type bindings.rabbitmq. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.rabbitmq
 version: v1
 metadata:
 - name: queueName
 value: "queue1"
 - name: host
 value: "amqp://[username][:password]@host.domain[:port]"
 - name: durable
 value: "true"
 - name: deleteWhenUnused
 value: "false"
 - name: ttlInSeconds
 value: "60"
 - name: prefetchCount
 value: "0"
 - name: exclusive
 value: "false"
 - name: maxPriority
 value: "5"
 - name: contentType
 value: "text/plain"
 - name: reconnectWaitInSeconds
 value: "5"
 - name: externalSasl
 value: "false"
 - name: caCert
 value: "null"
 - name: clientCert
 value: "null"
 - name: clientKey
 value: "null"
 - name: direction 
 value: "input, output"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

When a new RabbitMQ message gets published, all values from the associated metadata are added to the message’s header values.

RabbitMQ

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up RabbitMQ pub/sub, create a component of type pubsub.rabbitmq. See the pub/sub broker component file to learn how ConsumerID is automatically generated. Read the How-to: Publish and Subscribe guide on how to create and apply a pub/sub configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: rabbitmq-pubsub
spec:
 type: pubsub.rabbitmq
 version: v1
 metadata:
 - name: connectionString
 value: "amqp://localhost:5672"
 - name: protocol
 value: amqp 
 - name: hostname
 value: localhost 
 - name: username
 value: username
 - name: password
 value: password 
 - name: consumerID
 value: channel1
 - name: durable
 value: false
 - name: deletedWhenUnused
 value: false
 - name: autoAck
 value: false
 - name: deliveryMode
 value: 0
 - name: requeueInFailure
 value: false
 - name: prefetchCount
 value: 0
 - name: reconnectWait
 value: 0
 - name: concurrencyMode
 value: parallel
 - name: publisherConfirm
 value: false
 - name: enableDeadLetter # Optional enable dead Letter or not
 value: true
 - name: maxLen # Optional max message count in a queue
 value: 3000
 - name: maxLenBytes # Optional maximum length in bytes of a queue.
 value: 10485760
 - name: exchangeKind
 value: fanout
 - name: saslExternal
 value: false
 - name: ttlInSeconds
 value: 60
 - name: clientName
 value: {podName}
 - name: heartBeat
 value: 10s
 - name: publishMessagePropertiesToMetadata
 value: "true"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
connectionString	Y*	The RabbitMQ connection string. *Mutually exclusive with protocol, hostname, username, password field	`amqp://user:pass@localhost:5672`
protocol	N*	The RabbitMQ protocol. *Mutually exclusive with connectionString field	`amqp`
hostname	N*	The RabbitMQ hostname. *Mutually exclusive with connectionString field	`localhost`
username	N*	The RabbitMQ username. *Mutually exclusive with connectionString field	`username`
password	N*	The RabbitMQ password. *Mutually exclusive with connectionString field	`password`
consumerID	N	Consumer ID (consumer tag) organizes one or more consumers into a group. Consumers with the same consumer ID work as one virtual consumer; for example, a message is processed only once by one of the consumers in the group. If the `consumerID` is not provided, the Dapr runtime set it to the Dapr application ID (`appID`) value.	Can be set to string value (such as `"channel1"` in the example above) or string format value (such as `"{podName}"`, etc.). See all of template tags you can use in your component metadata.
durable	N	Whether or not to use durable queues. Defaults to `"false"`	`"true"`, `"false"`
deletedWhenUnused	N	Whether or not the queue should be configured to auto-delete Defaults to `"true"`	`"true"`, `"false"`
autoAck	N	Whether or not the queue consumer should auto-ack messages. Defaults to `"false"`	`"true"`, `"false"`
deliveryMode	N	Persistence mode when publishing messages. Defaults to `"0"`. RabbitMQ treats `"2"` as persistent, all other numbers as non-persistent	`"0"`, `"2"`
requeueInFailure	N	Whether or not to requeue when sending a negative acknowledgement in case of a failure. Defaults to `"false"`	`"true"`, `"false"`
prefetchCount	N	Number of messages to prefetch. Consider changing this to a non-zero value for production environments. Defaults to `"0"`, which means that all available messages will be pre-fetched.	`"2"`
publisherConfirm	N	If enabled, client waits for publisher confirms after publishing a message. Defaults to `"false"`	`"true"`, `"false"`
reconnectWait	N	How long to wait (in seconds) before reconnecting if a connection failure occurs	`"0"`
concurrencyMode	N	`parallel` is the default, and allows processing multiple messages in parallel (limited by the `app-max-concurrency` annotation, if configured). Set to `single` to disable parallel processing. In most situations there’s no reason to change this.	`parallel`, `single`
enableDeadLetter	N	Enable forwarding Messages that cannot be handled to a dead-letter topic. Defaults to `"false"`	`"true"`, `"false"`
maxLen	N	The maximum number of messages of a queue and its dead letter queue (if dead letter enabled). If both `maxLen` and `maxLenBytes` are set then both will apply; whichever limit is hit first will be enforced. Defaults to no limit.	`"1000"`
maxLenBytes	N	Maximum length in bytes of a queue and its dead letter queue (if dead letter enabled). If both `maxLen` and `maxLenBytes` are set then both will apply; whichever limit is hit first will be enforced. Defaults to no limit.	`"1048576"`
exchangeKind	N	Exchange kind of the rabbitmq exchange. Defaults to `"fanout"`.	`"fanout"`,`"topic"`
saslExternal	N	With TLS, should the username be taken from an additional field (for example, CN). See RabbitMQ Authentication Mechanisms. Defaults to `"false"`.	`"true"`, `"false"`
ttlInSeconds	N	Set message TTL at the component level, which can be overwritten by message level TTL per request.	`"60"`
caCert	Required for using TLS	Certificate Authority (CA) certificate in PEM format for verifying server TLS certificates.	`"-----BEGIN CERTIFICATE-----\n<base64-encoded DER>\n-----END CERTIFICATE-----"`
clientCert	Required for using TLS	TLS client certificate in PEM format. Must be used with `clientKey`.	`"-----BEGIN CERTIFICATE-----\n<base64-encoded DER>\n-----END CERTIFICATE-----"`
clientKey	Required for using TLS	TLS client key in PEM format. Must be used with `clientCert`. Can be `secretKeyRef` to use a secret reference.	`"-----BEGIN RSA PRIVATE KEY-----\n<base64-encoded PKCS8>\n-----END RSA PRIVATE KEY-----"`
clientName	N	This RabbitMQ client-provided connection name is a custom identifier. If set, the identifier is mentioned in RabbitMQ server log entries and management UI. Can be set to {uuid}, {podName}, or {appID}, which is replaced by Dapr runtime to the real value.	`"app1"`, `{uuid}`, `{podName}`, `{appID}`
heartBeat	N	Defines the heartbeat interval with the server, detecting the aliveness of the peer TCP connection with the RabbitMQ server. Defaults to `10s` .	`"10s"`
`publishMessagePropertiesToMetadata`	N	Whether to publish AMQP message properties (headers, message ID, etc.) to the metadata.	“true”, “false”

Communication using TLS

To configure communication using TLS, ensure that the RabbitMQ nodes have TLS enabled and provide the caCert, clientCert, clientKey metadata in the component configuration. For example:

Rate limiting

Mon, 01 Jan 0001 00:00:00 +0000

The rate limit HTTP middleware allows restricting the maximum number of allowed HTTP requests per second. Rate limiting can protect your application from Denial of Service (DoS) attacks. DoS attacks can be initiated by malicious 3rd parties but also by bugs in your software (a.k.a. a “friendly fire” DoS attack).

Component format

In the following definition, the maximum requests per second are set to 10:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: ratelimit
spec:
 type: middleware.http.ratelimit
 version: v1
 metadata:
 - name: maxRequestsPerSecond
 value: 10

Spec metadata fields

Field	Details	Example
`maxRequestsPerSecond`	The maximum requests per second by remote IP. The component looks at the `X-Forwarded-For` and `X-Real-IP` headers to determine the caller’s IP.	`10`

Once the limit is reached, the requests will fail with HTTP Status code 429: Too Many Requests.

RavenDB

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup RavenDB state store create a component of type state.ravendb. See this guide on how to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.ravendb
 version: v1
 metadata:
 - name: serverURL
 value: <REPLACE-WITH-SERVER-URL> # Required. Example: "http://localhost:8080"
 - name: databaseName
 value: <REPLACE-WITH-DATABASE-NAME> # Optional. default: "daprStore"
 - name: certPath
 value: <REPLACE-WITH-CERT-PATH> # Required unless server is insecure.
 - name: keyPath
 value: <REPLACE-WITH-KEY-PATH> # Required unless server is insecure.
 - name: EnableTTL
 value: <REPLACE-WITH-ENABLE-TTL> # Optional. default: "true"
 - name: TTLFrequency
 value: <REPLACE-WITH-TTL-FREQUENCY> # Optional. Example: "15". Default: "60"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
serverURL	Y	URL to RavenDB instance	`"http://localhost:8080"`
databaseName	N	The name of the database to use. Defaults to `"daprStore"`	`"daprStore"`
certPath	N¹	Path to certificate file	`"/path/to/client.certificate.crt"`
keyPath	N¹	Path to key file	`"/path/to/certificate.key"`
EnableTTL	N	Boolean value to enable TTL capability. Defaults to `"true"`	`"true"`
TTLFrequency	N	Frequency in seconds for TTL cleanup. Defaults to `"60"`	`"60"`

^[1] The certPath and keyPath fields are not mandatory if server URL is http. However, if the server URL is https and no certPath and keyPath are present, then Dapr returns an error.

Redis binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Redis binding create a component of type bindings.redis. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.redis
 version: v1
 metadata:
 - name: redisHost
 value: "<address>:6379"
 - name: redisPassword
 value: "**************"
 - name: useEntraID
 value: "true"
 - name: enableTLS
 value: "<bool>"
 - name: insecureSkipTLSVerify
 value: "<bool>"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`redisHost`	Y	Output	Connection-string for the redis host. If `"redisType"` is `"cluster"`, it can be multiple hosts separated by commas or just a single host. When using Redis Sentinel (`"failover"` is `"true"`), multiple sentinel addresses can also be provided as comma-separated values.	`localhost:6379`, `redis-master.default.svc.cluster.local:6379`, `sentinel1:26379,sentinel2:26379,sentinel3:26379`
`redisPassword`	N	Output	The Redis password	`"password"`
`redisUsername`	N	Output	Username for Redis host. Defaults to empty. Make sure your redis server version is 6 or above, and have created acl rule correctly.	`"username"`
`useEntraID`	N	Output	Implements EntraID support for Azure Cache for Redis. Before enabling this: The `redisHost` name must be specified in the form of `"server:port"` TLS must be enabled Learn more about this setting under Create a Redis instance > Azure Cache for Redis	`"true"`, `"false"`
`enableTLS`	N	Output	If the Redis instance supports TLS with public certificates it can be configured to enable or disable TLS. Defaults to `"false"`	`"true"`, `"false"`
`insecureSkipTLSVerify`	N	Output	Skip TLS certificate verification when `enableTLS` is `"true"`. Only use for testing. Defaults to `"false"`	`"true"`, `"false"`
`clientCert`	N	Output	The content of the client certificate, used for Redis instances that require client-side certificates. Must be used with `clientKey` and `enableTLS` must be set to true. It is recommended to use a secret store as described here	`"----BEGIN CERTIFICATE-----\nMIIC..."`
`clientKey`	N	Output	The content of the client private key, used in conjunction with `clientCert` for authentication. It is recommended to use a secret store as described here	`"----BEGIN PRIVATE KEY-----\nMIIE..."`
`failover`	N	Output	Property to enable failover configuration. Needs sentinelMasterName to be set. When enabled, redisHost should contain the sentinel addresses. Defaults to `"false"`	`"true"`, `"false"`
`sentinelMasterName`	N	Output	The sentinel master name. See Redis Sentinel Documentation	`""`, `"mymaster"`
`sentinelUsername`	N	Output	Username for Redis Sentinel. Applicable only when “failover” is true, and Redis Sentinel has authentication enabled	`"username"`
`sentinelPassword`	N	Output	Password for Redis Sentinel. Applicable only when “failover” is true, and Redis Sentinel has authentication enabled	`"password"`
`redeliverInterval`	N	Output	The interval between checking for pending messages to redelivery. Defaults to `"60s"`. `"0"` disables redelivery.	`"30s"`
`processingTimeout`	N	Output	The amount time a message must be pending before attempting to redeliver it. Defaults to `"15s"`. `"0"` disables redelivery.	`"30s"`
`redisType`	N	Output	The type of redis. There are two valid values, one is `"node"` for single node mode, the other is `"cluster"` for redis cluster mode. Defaults to `"node"`.	`"cluster"`
`redisDB`	N	Output	Database selected after connecting to redis. If `"redisType"` is `"cluster"` this option is ignored. Defaults to `"0"`.	`"0"`
`redisMaxRetries`	N	Output	Maximum number of times to retry commands before giving up. Default is to not retry failed commands.	`"5"`
`redisMinRetryInterval`	N	Output	Minimum backoff for redis commands between each retry. Default is `"8ms"`; `"-1"` disables backoff.	`"8ms"`
`redisMaxRetryInterval`	N	Output	Maximum backoff for redis commands between each retry. Default is `"512ms"`;`"-1"` disables backoff.	`"5s"`
`dialTimeout`	N	Output	Dial timeout for establishing new connections. Defaults to `"5s"`.	`"5s"`
`readTimeout`	N	Output	Timeout for socket reads. If reached, redis commands will fail with a timeout instead of blocking. Defaults to `"3s"`, `"-1"` for no timeout.	`"3s"`
`writeTimeout`	N	Output	Timeout for socket writes. If reached, redis commands will fail with a timeout instead of blocking. Defaults is readTimeout.	`"3s"`
`poolSize`	N	Output	Maximum number of socket connections. Default is 10 connections per every CPU as reported by runtime.NumCPU.	`"20"`
`poolTimeout`	N	Output	Amount of time client waits for a connection if all connections are busy before returning an error. Default is readTimeout + 1 second.	`"5s"`
`maxConnAge`	N	Output	Connection age at which the client retires (closes) the connection. Default is to not close aged connections.	`"30m"`
`minIdleConns`	N	Output	Minimum number of idle connections to keep open in order to avoid the performance degradation associated with creating new connections. Defaults to `"0"`.	`"2"`
`idleCheckFrequency`	N	Output	Frequency of idle checks made by idle connections reaper. Default is `"1m"`. `"-1"` disables idle connections reaper.	`"-1"`
`idleTimeout`	N	Output	Amount of time after which the client closes idle connections. Should be less than server’s timeout. Default is `"5m"`. `"-1"` disables idle timeout check.	`"10m"`

Binding support

This component supports output binding with the following operations:

Redis

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Redis configuration store create a component of type configuration.redis. See this guide on how to create and apply a configuration store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: configuration.redis
 version: v1
 metadata:
 - name: redisHost
 value: <address>:6379
 - name: redisPassword
 value: **************
 - name: useEntraID
 value: "true"
 - name: enableTLS
 value: <bool>
 - name: insecureSkipTLSVerify
 value: <bool>

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
redisHost	Y	Output	Connection-string for the redis host. If `"redisType"` is `"cluster"`, it can be multiple hosts separated by commas or just a single host. When using Redis Sentinel (`"failover"` is `"true"`), multiple sentinel addresses can also be provided as comma-separated values.
redisPassword	N	Output	The Redis password
redisUsername	N	Output	Username for Redis host. Defaults to empty. Make sure your Redis server version is 6 or above, and have created acl rule correctly.
enableTLS	N	Output	If the Redis instance supports TLS with public certificates it can be configured to enable or disable TLS. Defaults to `"false"`
insecureSkipTLSVerify	N	Output	Skip TLS certificate verification when `enableTLS` is `"true"`. Only use for testing. Defaults to `"false"`
clientCert	N	Output	The content of the client certificate, used for Redis instances that require client-side certificates. Must be used with `clientKey` and `enableTLS` must be set to true. It is recommended to use a secret store as described here
clientKey	N	Output	The content of the client private key, used in conjunction with `clientCert` for authentication. It is recommended to use a secret store as described here
failover	N	Output	Property to enable failover configuration. Needs sentinelMasterName to be set. When enabled, redisHost should contain the sentinel addresses. Defaults to `"false"`
sentinelMasterName	N	Output	The Sentinel master name. See Redis Sentinel Documentation
sentinelUsername	N	Output	Username for Redis Sentinel. Applicable only when “failover” is true, and Redis Sentinel has authentication enabled
sentinelPassword	N	Output	Password for Redis Sentinel. Applicable only when “failover” is true, and Redis Sentinel has authentication enabled
redisType	N	Output	The type of Redis. There are two valid values, one is `"node"` for single node mode, the other is `"cluster"` for Redis cluster mode. Defaults to `"node"`.
redisDB	N	Output	Database selected after connecting to Redis. If `"redisType"` is `"cluster"`, this option is ignored. Defaults to `"0"`.
redisMaxRetries	N	Output	Maximum number of times to retry commands before giving up. Default is to not retry failed commands.
redisMinRetryInterval	N	Output	Minimum backoff for Redis commands between each retry. Default is `"8ms"`; `"-1"` disables backoff.
redisMaxRetryInterval	N	Output	Maximum backoff for Redis commands between each retry. Default is `"512ms"`;`"-1"` disables backoff.
dialTimeout	N	Output	Dial timeout for establishing new connections. Defaults to `"5s"`.
readTimeout	N	Output	Timeout for socket reads. If reached, Redis commands fail with a timeout instead of blocking. Defaults to `"3s"`, `"-1"` for no timeout.
writeTimeout	N	Output	Timeout for socket writes. If reached, Redis commands fail with a timeout instead of blocking. Defaults is readTimeout.
poolSize	N	Output	Maximum number of socket connections. Default is 10 connections per every CPU as reported by runtime.NumCPU.
poolTimeout	N	Output	Amount of time client waits for a connection if all connections are busy before returning an error. Default is readTimeout + 1 second.
maxConnAge	N	Output	Connection age at which the client retires (closes) the connection. Default is to not close aged connections.
minIdleConns	N	Output	Minimum number of idle connections to keep open in order to avoid the performance degradation associated with creating new connections. Defaults to `"0"`.
idleCheckFrequency	N	Output	Frequency of idle checks made by idle connections reaper. Default is `"1m"`. `"-1"` disables idle connections reaper.
idleTimeout	N	Output	Amount of time after which the client closes idle connections. Should be less than server’s timeout. Default is `"5m"`. `"-1"` disables idle timeout check.

Setup Redis

Dapr can use any Redis instance: containerized, running on your local dev machine, or a managed cloud service.

Redis

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up the Redis lock, create a component of type lock.redis. See this guide on how to create a lock.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: lock.redis
 version: v1
 metadata:
 - name: redisHost
 value: <HOST>
 - name: redisPassword #Optional.
 value: <PASSWORD>
 - name: useEntraID
 value: <bool> # Optional. Allowed: true, false.
 - name: enableTLS
 value: <bool> # Optional. Allowed: true, false.
 - name: insecureSkipTLSVerify
 value: <bool> # Optional. Allowed: true, false.
 - name: failover
 value: <bool> # Optional. Allowed: true, false.
 - name: sentinelMasterName
 value: <string> # Optional
 - name: maxRetries
 value: # Optional
 - name: maxRetryBackoff
 value: # Optional
 - name: redeliverInterval
 value: # Optional
 - name: processingTimeout
 value: # Optional
 - name: redisType
 value: # Optional
 - name: redisDB
 value: # Optional
 - name: redisMaxRetries
 value: # Optional
 - name: redisMinRetryInterval
 value: # Optional
 - name: redisMaxRetryInterval
 value: # Optional
 - name: dialTimeout
 value: # Optional
 - name: readTimeout
 value: # Optional
 - name: writeTimeout
 value: # Optional
 - name: poolSize
 value: # Optional
 - name: poolTimeout
 value: # Optional
 - name: maxConnAge
 value: # Optional
 - name: minIdleConns
 value: # Optional
 - name: idleCheckFrequency
 value: # Optional
 - name: idleTimeout
 value: # Optional

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets, as described here.

Spec metadata fields

Field	Required	Details	Example
redisHost	Y	Connection-string for the redis host. If `"redisType"` is `"cluster"`, it can be multiple hosts separated by commas or just a single host. When using Redis Sentinel (`"failover"` is `"true"`), multiple sentinel addresses can also be provided as comma-separated values.	`localhost:6379`, `redis-master.default.svc.cluster.local:6379`, `sentinel1:26379,sentinel2:26379,sentinel3:26379` host
redisPassword	N	Password for Redis host. No Default. Can be `secretKeyRef` to use a secret reference	`""`, `"KeFg23!"`
redisUsername	N	Username for Redis host. Defaults to empty. Make sure your redis server version is 6 or above, and have created acl rule correctly.	`""`, `"default"`
useEntraID	N	Implements EntraID support for Azure Cache for Redis. Before enabling this: The `redisHost` name must be specified in the form of `"server:port"` TLS must be enabled Learn more about this setting under Create a Redis instance > Azure Cache for Redis	`"true"`, `"false"`
enableTLS	N	If the Redis instance supports TLS with public certificates, can be configured to be enabled or disabled. Defaults to `"false"`	`"true"`, `"false"`
insecureSkipTLSVerify	N	Skip TLS certificate verification when `enableTLS` is `"true"`. Only use for testing. Defaults to `"false"`	`"true"`, `"false"`
maxRetries	N	Maximum number of retries before giving up. Defaults to `3`	`5`, `10`
maxRetryBackoff	N	Maximum backoff between each retry. Defaults to `2` seconds; `"-1"` disables backoff.	`3000000000`
failover	N	Property to enable failover configuration. Needs sentinelMasterName to be set. When enabled, redisHost should contain the sentinel addresses. Defaults to `"false"`	`"true"`, `"false"`
sentinelMasterName	N	The sentinel master name. See Redis Sentinel Documentation	`"mymaster"`
sentinelPassword	N	Password for Redis Sentinel. No Default. Applicable only when “failover” is true, and Redis Sentinel has authentication enabled	`""`, `"KeFg23!"`
redeliverInterval	N	The interval between checking for pending messages for redelivery. Defaults to `"60s"`. `"0"` disables redelivery.	`"30s"`
processingTimeout	N	The amount of time a message must be pending before attempting to redeliver it. Defaults to `"15s"`. `"0"` disables redelivery.	`"30s"`
redisType	N	The type of redis. There are two valid values, one is `"node"` for single node mode, the other is `"cluster"` for redis cluster mode. Defaults to `"node"`.	`"cluster"`
redisDB	N	Database selected after connecting to redis. If `"redisType"` is `"cluster"` this option is ignored. Defaults to `"0"`.	`"0"`
redisMaxRetries	N	Alias for `maxRetries`. If both values are set `maxRetries` is ignored.	`"5"`
redisMinRetryInterval	N	Minimum backoff for redis commands between each retry. Default is `"8ms"`; `"-1"` disables backoff.	`"8ms"`
redisMaxRetryInterval	N	Alias for `maxRetryBackoff`. If both values are set `maxRetryBackoff` is ignored.	`"5s"`
dialTimeout	N	Dial timeout for establishing new connections. Defaults to `"5s"`.	`"5s"`
readTimeout	N	Timeout for socket reads. If reached, redis commands will fail with a timeout instead of blocking. Defaults to `"3s"`, `"-1"` for no timeout.	`"3s"`
writeTimeout	N	Timeout for socket writes. If reached, redis commands will fail with a timeout instead of blocking. Defaults is readTimeout.	`"3s"`
poolSize	N	Maximum number of socket connections. Default is 10 connections per every CPU as reported by runtime (NumCPU)	`“20”
poolTimeout	N	Amount of time client waits for a connection if all connections are busy before returning an error. Default is readTimeout + 1 second.	`"5s"`
maxConnAge	N	Connection age at which the client retires (closes) the connection. Default is to not close aged connections.	`"30m"`
minIdleConns	N	Minimum number of idle connections to keep open in order to avoid the performance degradation associated with creating new connections. Defaults to `"0"`.	`"2"`
idleCheckFrequency	N	Frequency of idle checks made by idle connections reaper. Default is `"1m"`. `"-1"` disables idle connections reaper.	`"-1"`
idleTimeout	N	Amount of time after which the client closes idle connections. Should be less than server’s timeout. Default is `"5m"`. `"-1"` disables idle timeout check.	`"10m"`

Setup Redis

Dapr can use any Redis instance: containerized, running on your local dev machine, or a managed cloud service.

Redis

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Redis state store create a component of type state.redis. See this guide on how to create and apply a state store configuration.

Limitations

Before using Redis and the Transactions API, make sure you’re familiar with Redis limitations regarding transactions.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.redis
 version: v1
 metadata:
 - name: redisHost
 value: <HOST>
 - name: redisPassword # Optional.
 value: <PASSWORD>
 - name: useEntraID
 value: <bool> # Optional. Allowed: true, false.
 - name: enableTLS
 value: <bool> # Optional. Allowed: true, false.
 - name: insecureSkipTLSVerify
 value: <bool> # Optional. Allowed: true, false.
 - name: clientCert
 value: # Optional
 - name: clientKey
 value: # Optional 
 - name: maxRetries
 value: # Optional
 - name: maxRetryBackoff
 value: # Optional
 - name: failover
 value: <bool> # Optional. Allowed: true, false.
 - name: sentinelMasterName
 value: <string> # Optional
 - name: sentinelUsername
 value: # Optional
 - name: sentinelPassword
 value: # Optional
 - name: redeliverInterval
 value: # Optional
 - name: processingTimeout
 value: # Optional
 - name: redisType
 value: # Optional
 - name: redisDB
 value: # Optional
 - name: redisMaxRetries
 value: # Optional
 - name: redisMinRetryInterval
 value: # Optional
 - name: redisMaxRetryInterval
 value: # Optional
 - name: dialTimeout
 value: # Optional
 - name: readTimeout
 value: # Optional
 - name: writeTimeout
 value: # Optional
 - name: poolSize
 value: # Optional
 - name: poolTimeout
 value: # Optional
 - name: maxConnAge
 value: # Optional
 - name: minIdleConns
 value: # Optional
 - name: idleCheckFrequency
 value: # Optional
 - name: idleTimeout
 value: # Optional
 - name: ttlInSeconds
 value: <int> # Optional
 - name: queryIndexes
 value: <string> # Optional
 # Uncomment this if you wish to use Redis as a state store for actors (optional)
 #- name: actorStateStore
 # value: "true"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

If you wish to use Redis as an actor store, append the following to the yaml.

Redis Streams

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up Redis Streams pub/sub, create a component of type pubsub.redis. See the pub/sub broker component file to learn how ConsumerID is automatically generated. Read the How-to: Publish and Subscribe guide on how to create and apply a pub/sub configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: redis-pubsub
spec:
 type: pubsub.redis
 version: v1
 metadata:
 - name: redisHost
 value: localhost:6379
 - name: redisPassword
 value: "KeFg23!"
 - name: consumerID
 value: "channel1"
 - name: useEntraID
 value: "true"
 - name: enableTLS
 value: "false"
 - name: insecureSkipTLSVerify
 value: "false"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
redisHost	Y	Connection-string for the redis host. If `"redisType"` is `"cluster"`, it can be multiple hosts separated by commas or just a single host. When using Redis Sentinel (`"failover"` is `"true"`), multiple sentinel addresses can also be provided as comma-separated values.	`localhost:6379`, `redis-master.default.svc.cluster.local:6379`, `sentinel1:26379,sentinel2:26379,sentinel3:26379`
redisPassword	N	Password for Redis host. No Default. Can be `secretKeyRef` to use a secret reference	`""`, `"KeFg23!"`
redisUsername	N	Username for Redis host. Defaults to empty. Make sure your redis server version is 6 or above, and have created acl rule correctly.	`""`, `"default"`
consumerID	N	The consumer group ID.	Can be set to string value (such as `"channel1"` in the example above) or string format value (such as `"{podName}"`, etc.). See all of template tags you can use in your component metadata.
useEntraID	N	Implements EntraID support for Azure Cache for Redis. Before enabling this: The `redisHost` name must be specified in the form of `"server:port"` TLS must be enabled Learn more about this setting under Create a Redis instance > Azure Cache for Redis	`"true"`, `"false"`
enableTLS	N	If the Redis instance supports TLS with public certificates, can be configured to be enabled or disabled. Defaults to `"false"`	`"true"`, `"false"`
insecureSkipTLSVerify	N	Skip TLS certificate verification when `enableTLS` is `"true"`. Only use for testing. Defaults to `"false"`	`"true"`, `"false"`
clientCert	N	The content of the client certificate, used for Redis instances that require client-side certificates. Must be used with `clientKey` and `enableTLS` must be set to true. It is recommended to use a secret store as described here	`"----BEGIN CERTIFICATE-----\nMIIC..."`
clientKey	N	The content of the client private key, used in conjunction with `clientCert` for authentication. It is recommended to use a secret store as described here	`"----BEGIN PRIVATE KEY-----\nMIIE..."`
redeliverInterval	N	The interval between checking for pending messages to redeliver. Can use either be Go duration string (for example “ms”, “s”, “m”) or milliseconds number. Defaults to `"60s"`. `"0"` disables redelivery.	`"30s"`, `"5000"`
processingTimeout	N	The amount time that a message must be pending before attempting to redeliver it. Can use either be Go duration string ( for example “ms”, “s”, “m”) or milliseconds number. Defaults to `"15s"`. `"0"` disables redelivery.	`"60s"`, `"600000"`
queueDepth	N	The size of the message queue for processing. Defaults to `"100"`.	`"1000"`
concurrency	N	The number of concurrent workers that are processing messages. Defaults to `"10"`.	`"15"`
redisType	N	The type of redis. There are two valid values, one is `"node"` for single node mode, the other is `"cluster"` for redis cluster mode. Defaults to `"node"`.	`"cluster"`
redisDB	N	Database selected after connecting to redis. If `"redisType"` is `"cluster"` this option is ignored. Defaults to `"0"`.	`"0"`
redisMaxRetries	N	Maximum number of times to retry commands before giving up. Default is to not retry failed commands.	`"5"`
redisMinRetryInterval	N	Minimum backoff for redis commands between each retry. Default is `"8ms"`; `"-1"` disables backoff.	`"8ms"`
redisMaxRetryInterval	N	Maximum backoff for redis commands between each retry. Default is `"512ms"`;`"-1"` disables backoff.	`"5s"`
dialTimeout	N	Dial timeout for establishing new connections. Defaults to `"5s"`.	`"5s"`
readTimeout	N	Timeout for socket reads, if set to `"0s"`, the read will be blocking. If reached, redis commands will fail with a timeout instead of blocking. Defaults to `"0s"`, `"-1"` for no timeout.	`"3s"`
writeTimeout	N	Timeout for socket writes. If reached, redis commands will fail with a timeout instead of blocking. Defaults is readTimeout.	`"3s"`
poolSize	N	Maximum number of socket connections. Default is 10 connections per every CPU as reported by runtime.NumCPU.	`"20"`
poolTimeout	N	Amount of time client waits for a connection if all connections are busy before returning an error. Default is readTimeout + 1 second.	`"5s"`
maxConnAge	N	Connection age at which the client retires (closes) the connection. Default is to not close aged connections.	`"30m"`
minIdleConns	N	Minimum number of idle connections to keep open in order to avoid the performance degradation associated with creating new connections. Defaults to `"0"`.	`"2"`
idleCheckFrequency	N	Frequency of idle checks made by idle connections reaper. Default is `"1m"`. `"-1"` disables idle connections reaper.	`"-1"`
idleTimeout	N	Amount of time after which the client closes idle connections. Should be less than server’s timeout. Default is `"5m"`. `"-1"` disables idle timeout check.	`"10m"`
failover	N	Property to enable failover configuration. Needs sentinelMasterName to be set. When enabled, redisHost should contain the sentinel addresses. Defaults to `"false"`	`"true"`, `"false"`
sentinelMasterName	N	The sentinel master name. See Redis Sentinel Documentation	`""`, `"mymaster"`
sentinelUsername	N	Username for Redis Sentinel. Applicable only when “failover” is true, and Redis Sentinel has authentication enabled	`"username"`
sentinelPassword	N	Password for Redis Sentinel. Applicable only when “failover” is true, and Redis Sentinel has authentication enabled	`"password"`
maxLenApprox	N	Maximum number of items inside a stream.The old entries are automatically evicted when the specified length is reached, so that the stream is left at a constant size. Defaults to unlimited.	`"10000"`
streamTTL	N	TTL duration for stream entries. Entries older than this duration will be evicted. This is an approximate value, as it’s implemented using Redis stream’s `MINID` trimming with the ‘~’ modifier. The actual retention may include slightly more entries than strictly defined by the TTL, as Redis optimizes the trimming operation for efficiency by potentially keeping some additional entries.	`"30d"`

Create a Redis instance

Dapr can use any Redis instance - containerized, running on your local dev machine, or a managed cloud service, provided the version of Redis is 5.x or 6.x.

RethinkDB binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

The RethinkDB state store supports transactions which means it can be used to support Dapr actors. Dapr persists only the actor’s current state which doesn’t allow the users to track how actor’s state may have changed over time.

To enable users to track change of the state of actors, this binding leverages RethinkDB’s built-in capability to monitor RethinkDB table and event on change with both the old and new state. This binding creates a subscription on the Dapr state table and streams these changes using the Dapr input binding interface.

RethinkDB

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup RethinkDB state store, create a component of type state.rethinkdb. See the how-to guide to create and apply a state store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: state.rethinkdb
 version: v1
 metadata:
 - name: address
 value: <REPLACE-RETHINKDB-ADDRESS> # Required, e.g. 127.0.0.1:28015 or rethinkdb.default.svc.cluster.local:28015).
 - name: database
 value: <REPLACE-RETHINKDB-DB-NAME> # Required, e.g. dapr (alpha-numerics only)
 - name: table
 value: # Optional
 - name: username
 value: <USERNAME> # Optional
 - name: password
 value: <PASSWORD> # Optional
 - name: archive
 value: bool # Optional (whether or not store should keep archive table of all the state changes)

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets, as described here.

If the optional archive metadata is set to true, on each state change, the RethinkDB state store will also log state changes with timestamp in the daprstate_archive table. This allows for time series analyses of the state managed by Dapr.

Apache RocketMQ binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up an Apache RocketMQ binding, create a component of type bindings.rocketmq.
See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.rocketmq
 version: v1
 metadata:
 - name: accessProto
 value: "tcp"
 - name: nameServer
 value: "localhost:9876"
 - name: endpoint
 value: "http://localhost:8080"
 - name: topics
 value: "topic1,topic2"
 - name: consumerGroup
 value: "my-consumer-group"
 # Optional
 - name: consumerBatchSize
 value: "10"
 - name: consumerThreadNums
 value: "4"
 - name: retries
 value: "3"
 - name: instanceId
 value: "my-instance"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`topics`	Y	Input/Output	Comma-separated list of topics for publishing or subscribing.	`"topic1,topic2"`
`nameServer`	N	Input/Output	Address of the RocketMQ name server.	`"localhost:9876"`
`endpoint`	N	Input/Output	RocketMQ endpoint (for `http` protocol).	`"http://localhost:8080"`
`accessProto`	N	Input/Output	SDK protocol for connecting to RocketMQ.	`"tcp"`, `"tcp-cgo"`, `"http"`
`consumerGroup`	N	Input/Output	Consumer group name for RocketMQ subscribers.	`"my-consumer-group"`
`consumerBatchSize`	N	Input	Batch size for consuming messages.	`"10"`
`consumerThreadNums`	N	Input	Number of consumer threads (for `tcp-cgo` protocol).	`"4"`
`instanceId`	N	Input/Output	RocketMQ namespace instance ID.	`"my-instance"`
`nameServerDomain`	N	Input/Output	Domain name for the RocketMQ name server.	`"rocketmq.example.com"`
`retries`	N	Input/Output	Number of retry attempts to connect to the RocketMQ broker.	`"3"`
`accessKey`	N	Input/Output	Access key for authentication. Required if access control is enabled.	`"access-key"`
`secretKey`	N	Input/Output	Secret key for authentication. Required if access control is enabled.	`"secret-key"`

Note: accessKey and secretKey can be stored in a Dapr secret store instead of the YAML file for improved security.

RocketMQ

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up RocketMQ pub/sub, create a component of type pubsub.rocketmq. See the pub/sub broker component file to learn how ConsumerID is automatically generated. Read the How-to: Publish and Subscribe guide on how to create and apply a pub/sub configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: rocketmq-pubsub
spec:
 type: pubsub.rocketmq
 version: v1
 metadata:
 - name: instanceName
 value: dapr-rocketmq-test
 - name: consumerGroup
 value: dapr-rocketmq-test-g-c
 - name: producerGroup 
 value: dapr-rocketmq-test-g-p
 - name: consumerID
 value: channel1
 - name: nameSpace
 value: dapr-test
 - name: nameServer
 value: "127.0.0.1:9876,127.0.0.2:9876"
 - name: retries
 value: 3
 - name: consumerModel
 value: "clustering"
 - name: consumeOrderly
 value: false

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	default	Example
instanceName	N	Instance name	`time.Now().String()`	`dapr-rocketmq-test`
consumerGroup	N	Consumer group name. Recommend. If `producerGroup` is `null`，`groupName` is used.		`dapr-rocketmq-test-g-c`
producerGroup (consumerID)	N	Producer group name. Recommended. If `producerGroup` is `null`，`consumerID` is used. If `consumerID` also is null, `groupName` is used.		`dapr-rocketmq-test-g-p`
consumerID	N	Consumer ID (consumer tag) organizes one or more consumers into a group. Consumers with the same consumer ID work as one virtual consumer; for example, a message is processed only once by one of the consumers in the group. If the `consumerID` is not provided, the Dapr runtime set it to the Dapr application ID (`appID`) value.	Can be set to string value (such as `"channel1"` in the example above) or string format value (such as `"{podName}"`, etc.). See all of template tags you can use in your component metadata.
groupName	N	Consumer/Producer group name. Depreciated.		`dapr-rocketmq-test-g`
nameSpace	N	RocketMQ namespace		`dapr-rocketmq`
nameServerDomain	N	RocketMQ name server domain		`https://my-app.net:8080/nsaddr`
nameServer	N	RocketMQ name server, separated by “,” or “;”		`127.0.0.1:9876;127.0.0.2:9877,127.0.0.3:9877`
accessKey	N	Access Key (Username)		`"admin"`
secretKey	N	Secret Key (Password)		`"password"`
securityToken	N	Security Token
retries	N	Number of retries to send a message to broker	`3`	`3`
producerQueueSelector (queueSelector)	N	Producer Queue selector. There are five implementations of queue selector: `hash`, `random`, `manual`, `roundRobin`, `dapr`.	`dapr`	`hash`
consumerModel	N	Message model that defines how messages are delivered to each consumer client. RocketMQ supports two message models: `clustering` and `broadcasting`.	`clustering`	`broadcasting` , `clustering`
fromWhere (consumeFromWhere)	N	Consuming point on consumer booting. There are three consuming points: `CONSUME_FROM_LAST_OFFSET`, `CONSUME_FROM_FIRST_OFFSET`, `CONSUME_FROM_TIMESTAMP`	`CONSUME_FROM_LAST_OFFSET`	`CONSUME_FROM_LAST_OFFSET`
consumeTimestamp	N	Backtracks consumption time with second precision. Time format is `yyyymmddhhmmss`. For example, `20131223171201` implies the time of 17:12:01 and date of December 23, 2013	`time.Now().Add(time.Minute * (-30)).Format("20060102150405")`	`20131223171201`
consumeOrderly	N	Determines if it’s an ordered message using FIFO order.	`false`	`false`
consumeMessageBatchMaxSize	N	Batch consumption size out of range `[1, 1024]`	`512`	`10`
consumeConcurrentlyMaxSpan	N	Concurrently max span offset. This has no effect on sequential consumption. Range: `[1, 65535]`	`1000`	`1000`
maxReconsumeTimes	N	Max re-consume times. `-1` means 16 times. If messages are re-consumed more than {@link maxReconsumeTimes} before success, they’ll be directed to a deletion queue.	Orderly message is `MaxInt32`; Concurrently message is `16`	`16`
autoCommit	N	Enable auto commit	`true`	`false`
consumeTimeout	N	Maximum amount of time a message may block the consuming thread. Time unit: Minute	`15`	`15`
consumerPullTimeout	N	The socket timeout in milliseconds
pullInterval	N	Message pull interval	`100`	`100`
pullBatchSize	N	The number of messages pulled from the broker at a time. If `pullBatchSize` is `null`, use `ConsumerBatchSize`. `pullBatchSize` out of range `[1, 1024]`	`32`	`10`
pullThresholdForQueue	N	Flow control threshold on queue level. Each message queue will cache a maximum of 1000 messages by default. Consider the `PullBatchSize` - the instantaneous value may exceed the limit. Range: `[1, 65535]`	`1024`	`1000`
pullThresholdForTopic	N	Flow control threshold on topic level. The value of `pullThresholdForQueue` will be overwritten and calculated based on `pullThresholdForTopic` if it isn’t unlimited. For example, if the value of `pullThresholdForTopic` is 1000 and 10 message queues are assigned to this consumer, then `pullThresholdForQueue` will be set to 100. Range: `[1, 6553500]`	`-1(Unlimited)`	`10`
pullThresholdSizeForQueue	N	Limit the cached message size on queue level. Consider the `pullBatchSize` - the instantaneous value may exceed the limit. The size of a message is only measured by message body, so it’s not accurate. Range: `[1, 1024]`	`100`	`100`
pullThresholdSizeForTopic	N	Limit the cached message size on topic level. The value of `pullThresholdSizeForQueue` will be overwritten and calculated based on `pullThresholdSizeForTopic` if it isn’t unlimited. For example, if the value of `pullThresholdSizeForTopic` is 1000 MiB and 10 message queues are assigned to this consumer, then `pullThresholdSizeForQueue` will be set to 100 MiB. Range: `[1, 102400]`	`-1`	`100`
content-type	N	Message content type.	`"text/plain"`	`"application/cloudevents+json; charset=utf-8"`, `"application/octet-stream"`
logLevel	N	Log level	`warn`	`info`
sendTimeOut	N	Send message timeout to connect RocketMQ’s broker, measured in nanoseconds. Deprecated.	3 seconds	`10000000000`
sendTimeOutSec	N	Timeout duration for publishing a message in seconds. If `sendTimeOutSec` is `null`, `sendTimeOut` is used.	3 seconds	`3`
mspProperties	N	The RocketMQ message properties in this collection are passed to the APP in Data Separate multiple properties with “,”		`key,mkey`

For backwards-compatibility reasons, the following values in the metadata are supported, although their use is discouraged.

Router alias http request routing

Mon, 01 Jan 0001 00:00:00 +0000

The router alias HTTP middleware component allows you to convert arbitrary HTTP routes arriving into Dapr to valid Dapr API endpoints.

Component format

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: routeralias 
spec:
 type: middleware.http.routeralias
 version: v1
 metadata:
 # String containing a JSON-encoded or YAML-encoded dictionary
 # Each key in the dictionary is the incoming path, and the value is the path it's converted to
 - name: "routes"
 value: |
 {
 "/mall/activity/info": "/v1.0/invoke/srv.default/method/mall/activity/info",
 "/hello/activity/{id}/info": "/v1.0/invoke/srv.default/method/hello/activity/info",
 "/hello/activity/{id}/user": "/v1.0/invoke/srv.default/method/hello/activity/user"
 }

In the example above, an incoming HTTP request for /mall/activity/info?id=123 is transformed into /v1.0/invoke/srv.default/method/mall/activity/info?id=123.

RouterChecker http request routing

Mon, 01 Jan 0001 00:00:00 +0000

The RouterChecker HTTP middleware component leverages regexp to check the validity of HTTP request routing to prevent invalid routers from entering the Dapr cluster. In turn, the RouterChecker component filters out bad requests and reduces noise in the telemetry and log data.

Component format

The RouterChecker applies a set of rules to the incoming HTTP request. You define these rules in the component metadata using regular expressions. In the following example, the HTTP request RouterChecker is set to validate all requests message against the ^[A-Za-z0-9/._-]+$: regex.

run CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

Run Dapr and (optionally) your application side by side. A full list comparing daprd arguments, CLI arguments, and Kubernetes annotations can be found here.

Supported platforms

Self-Hosted

Usage

dapr run [flags] [command]

Flags

Name	Environment Variable	Default	Description
`--app-id`, `-a`	`APP_ID`		The id for your application, used for service discovery. Cannot contain dots.
`--app-max-concurrency`		`unlimited`	The concurrency level of the application; default is unlimited
`--app-port`, `-p`	`APP_PORT`		The port your application is listening on
`--app-protocol`, `-P`		`http`	The protocol Dapr uses to talk to the application. Valid values are: `http`, `grpc`, `https` (HTTP with TLS), `grpcs` (gRPC with TLS), `h2c` (HTTP/2 Cleartext)
`--resources-path`, `-d`		Linux/Mac: `$HOME/.dapr/components` Windows: `%USERPROFILE%\.dapr\components`	The path for resources directory. If you’ve organized your resources into multiple folders (for example, components in one folder, resiliency policies in another), you can define multiple resource paths. See example below.
`--app-channel-address`		`127.0.0.1`	The network address the application listens on
`--runtime-path`			Dapr runtime install path
`--config`, `-c`		Linux/Mac: `$HOME/.dapr/config.yaml` Windows: `%USERPROFILE%\.dapr\config.yaml`	Dapr configuration file
`--dapr-grpc-port`, `-G`	`DAPR_GRPC_PORT`	`50001`	The gRPC port for Dapr to listen on
`--dapr-internal-grpc-port`, `-I`		`50002`	The gRPC port for the Dapr internal API to listen on. Set during development for apps experiencing temporary errors with service invocation failures due to mDNS caching, or configuring Dapr sidecars behind firewall. Can be any value greater than 1024 and must be different for each app.
`--dapr-http-port`, `-H`	`DAPR_HTTP_PORT`	`3500`	The HTTP port for Dapr to listen on
`--enable-profiling`		`false`	Enable “pprof” profiling via an HTTP endpoint
`--help`, `-h`			Print the help message
`--run-file`, `-f`		Linux/MacOS: `$HOME/.dapr/dapr.yaml`	Run multiple applications at once using a Multi-App Run template file. Currently in alpha and only available in Linux/MacOS
`--image`			Use a custom Docker image. Format is `repository/image` for Docker Hub, or `example.com/repository/image` for a custom registry.
`--log-level`		`info`	The log verbosity. Valid values are: `debug`, `info`, `warn`, `error`, `fatal`, or `panic`
`--enable-api-logging`		`false`	Enable the logging of all API calls from application to Dapr
`--metrics-port`	`DAPR_METRICS_PORT`	`9090`	The port that Dapr sends its metrics information to
`--profile-port`		`7777`	The port for the profile server to listen on
`--placement-host-address`		Linux/Mac: `$HOME/.dapr/components` Windows: `%USERPROFILE%\.dapr\components`	Run in any containers within your Docker network. Uses `<hostname>` or `<hostname>:<port>`. If the port is omitted, it will default to: Linux/MacOS: `50005` Windows: `6050`
`--scheduler-host-address`		Linux/Mac: `$HOME/.dapr/components` Windows: `%USERPROFILE%\.dapr\components`	Run in any containers within your Docker network. Uses `<hostname>` or `<hostname>:<port>`. If the port is omitted, it will default to: Linux/MacOS: `50006` Windows: `6060`
`--enable-app-health-check`		`false`	Enable health checks for the application using the protocol defined with app-protocol
`--app-health-check-path`			Path used for health checks; HTTP only
`--app-health-probe-interval`			Interval to probe for the health of the app in seconds
`--app-health-probe-timeout`			Timeout for app health probes in milliseconds
`--app-health-threshold`			Number of consecutive failures for the app to be considered unhealthy
`--unix-domain-socket`, `-u`			Path to a unix domain socket dir mount. If specified, communication with the Dapr sidecar uses unix domain sockets for lower latency and greater throughput when compared to using TCP ports. Not available on Windows.
`--dapr-http-max-request-size`		`4`	Max size of the request body in MB.
`--dapr-http-read-buffer-size`		`4`	Max size of the HTTP read buffer in KB. This also limits the maximum size of HTTP headers. The default 4 KB
`--kubernetes`, `-k`			Running Dapr on Kubernetes, and used for Multi-App Run template files on Kubernetes.
`--components-path`, `-d`		Linux/Mac: `$HOME/.dapr/components` Windows: `%USERPROFILE%\.dapr\components`	Deprecated in favor of `--resources-path`

Examples

# Run a .NET application
dapr run --app-id myapp --app-port 5000 -- dotnet run

# Run a .Net application with unix domain sockets
dapr run --app-id myapp --app-port 5000 --unix-domain-socket /tmp -- dotnet run

# Run a Java application
dapr run --app-id myapp -- java -jar myapp.jar

# Run a NodeJs application that listens to port 3000
dapr run --app-id myapp --app-port 3000 -- node myapp.js

# Run a Python application
dapr run --app-id myapp -- python myapp.py

# Run sidecar only
dapr run --app-id myapp

# Run a gRPC application written in Go (listening on port 3000)
dapr run --app-id myapp --app-port 5000 --app-protocol grpc -- go run main.go

# Run a NodeJs application that listens to port 3000 with API logging enabled
dapr run --app-id myapp --app-port 3000 --enable-api-logging -- node myapp.js

# Pass multiple resource paths
dapr run --app-id myapp --resources-path path1 --resources-path path2

# Run the multi-app run template file
dapr run -f dapr.yaml

# Run the multi-app run template file on Kubernetes
dapr run -k -f dapr.yaml

Dapr Scheduler control plane service overview

Mon, 01 Jan 0001 00:00:00 +0000

The Dapr Scheduler service is used to schedule different types of jobs, running in self-hosted mode or on Kubernetes.

Jobs created through the Jobs API
Actor reminder jobs (used by the actor reminders)
Actor reminder jobs created by the Workflow API (which uses actor reminders)

There is no concept of a leader Scheduler instance. All Scheduler service replicas are considered peers. All receive jobs to be scheduled for execution and the jobs are allocated between the available Scheduler service replicas for load balancing of the trigger events.

Sentinel fault-tolerance middleware component

Mon, 01 Jan 0001 00:00:00 +0000

Sentinel is a powerful fault-tolerance component that takes “flow” as the breakthrough point and covers multiple fields including flow control, traffic shaping, concurrency limiting, circuit breaking, and adaptive system protection to guarantee the reliability and resiliency of microservices.

The Sentinel HTTP middleware enables Dapr to facilitate Sentinel’s powerful abilities to protect your application. You can refer to Sentinel Wiki for more details on Sentinel.

Component format

In the following definition, the maximum requests per second are set to 10:

Dapr Sentry control plane service overview

Mon, 01 Jan 0001 00:00:00 +0000

The Dapr Sentry service manages mTLS between services and acts as a certificate authority. It generates mTLS certificates and distributes them to any running sidecars. This allows sidecars to communicate with encrypted, mTLS traffic. For more information read the sidecar-to-sidecar communication overview.

Self-hosted mode

The Sentry service Docker container is not started automatically as part of dapr init. However it can be executed manually by following the instructions for setting up mutual TLS.

SFTP binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up the SFTP binding, create a component of type bindings.sftp. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.sftp
 version: v1
 metadata:
 - name: rootPath
 value: "<string>"
 - name: address
 value: "<string>"
 - name: username
 value: "<string>"
 - name: password
 value: "*****************"
 - name: privateKey
 value: "*****************"
 - name: privateKeyPassphrase
 value: "*****************"
 - name: hostPublicKey
 value: "*****************"
 - name: knownHostsFile
 value: "<string>"
 - name: insecureIgnoreHostKey
 value: "<bool>"
 - name: sequentialMode
 value: "<bool>"

Spec metadata fields

Field	Required	Binding support	Details	Example
`rootPath`	Y	Output	Root path for default working directory	`"/path"`
`address`	Y	Output	Address of SFTP server	`"localhost:22"`
`username`	Y	Output	Username for authentication	`"username"`
`password`	N	Output	Password for username/password authentication	`"password"`
`privateKey`	N	Output	Private key for public key authentication	"\|- —–BEGIN OPENSSH PRIVATE KEY—– ***************** —–END OPENSSH PRIVATE KEY—–"
`privateKeyPassphrase`	N	Output	Private key passphrase for public key authentication	`"passphrase"`
`hostPublicKey`	N	Output	Host public key for host validation	`"ecdsa-sha2-nistp256 *** root@openssh-server"`
`knownHostsFile`	N	Output	Known hosts file for host validation	`"/path/file"`
`insecureIgnoreHostKey`	N	Output	Allows to skip host validation. Defaults to `"false"`	`"true"`, `"false"`
`sequentialMode`	N	Output	Used to specify if multiple concurrent operations are allowed within a single SFTP connection. Set this this to true to prevent concurrent operations that might confuse strict SFTP servers. Defaults to `"false"`	`"true"`, `"false"`

Binding support

This component supports output binding with the following operations:

Dapr Sidecar Injector control plane service overview

Mon, 01 Jan 0001 00:00:00 +0000

When running Dapr in Kubernetes mode, a pod is created running the Dapr Sidecar Injector service, which looks for pods initialized with the Dapr annotations, and then creates another container in that pod for the daprd service

Running the sidecar injector

The sidecar injector 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.

SMTP binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup SMTP binding create a component of type bindings.smtp. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: smtp
spec:
 type: bindings.smtp
 version: v1
 metadata:
 - name: host
 value: "smtp host"
 - name: port
 value: "smtp port"
 - name: user
 value: "username"
 - name: password
 value: "password"
 - name: skipTLSVerify
 value: true|false
 - name: emailFrom
 value: "sender@example.com"
 - name: emailTo
 value: "receiver@example.com"
 - name: emailCC
 value: "cc@example.com"
 - name: emailBCC
 value: "bcc@example.com"
 - name: subject
 value: "subject"
 - name: priority
 value: "[value 1-5]"

Warning

The example configuration shown above, contain a username and password as plain-text strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`host`	Y	Output	The host where your SMTP server runs	`"smtphost"`
`port`	Y	Output	The port your SMTP server listens on	`"9999"`
`user`	Y	Output	The user to authenticate against the SMTP server	`"user"`
`password`	Y	Output	The password of the user	`"password"`
`skipTLSVerify`	N	Output	If set to true, the SMPT server’s TLS certificate will not be verified. Defaults to `"false"`	`"true"`, `"false"`
`emailFrom`	N	Output	If set, this specifies the email address of the sender. See also	`"me@example.com"`
`emailTo`	N	Output	If set, this specifies the email address of the receiver. See also	`"me@example.com"`
`emailCc`	N	Output	If set, this specifies the email address to CC in. See also	`"me@example.com"`
`emailBcc`	N	Output	If set, this specifies email address to BCC in. See also	`"me@example.com"`
`subject`	N	Output	If set, this specifies the subject of the email message. See also	`"subject of mail"`
`priority`	N	Output	If set, this specifies the priority (X-Priority) of the email message, from 1 (lowest) to 5 (highest) (default value: 3). See also	`"1"`

Binding support

This component supports output binding with the following operations:

Solace-AMQP

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To set up Solace-AMQP pub/sub, create a component of type pubsub.solace.amqp. See the pub/sub broker component file to learn how ConsumerID is automatically generated. Read the How-to: Publish and Subscribe guide on how to create and apply a pub/sub configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: solace
spec:
 type: pubsub.solace.amqp
 version: v1
 metadata:
 - name: url
 value: 'amqp://localhost:5672'
 - name: username
 value: 'default'
 - name: password
 value: 'default'
 - name: consumerID
 value: 'channel1'

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Details	Example
url	Y	Address of the AMQP broker. Can be `secretKeyRef` to use a secret reference. Use the `amqp://` URI scheme for non-TLS communication. Use the `amqps://` URI scheme for TLS communication.	`"amqp://host.domain[:port]"`
username	Y	The username to connect to the broker. Only required if anonymous is not specified or set to `false` .	`default`
password	Y	The password to connect to the broker. Only required if anonymous is not specified or set to `false`.	`default`
consumerID	N	Consumer ID (consumer tag) organizes one or more consumers into a group. Consumers with the same consumer ID work as one virtual consumer; for example, a message is processed only once by one of the consumers in the group. If the `consumerID` is not provided, the Dapr runtime set it to the Dapr application ID (`appID`) value.	Can be set to string value (such as `"channel1"` in the example above) or string format value (such as `"{podName}"`, etc.). See all of template tags you can use in your component metadata.
anonymous	N	To connect to the broker without credential validation. Only works if enabled on the broker. A username and password would not be required if this is set to `true`.	`true`
caCert	Required for using TLS	Certificate Authority (CA) certificate in PEM format for verifying server TLS certificates.	`"-----BEGIN CERTIFICATE-----\n<base64-encoded DER>\n-----END CERTIFICATE-----"`
clientCert	Required for using TLS	TLS client certificate in PEM format. Must be used with `clientKey`.	`"-----BEGIN CERTIFICATE-----\n<base64-encoded DER>\n-----END CERTIFICATE-----"`
clientKey	Required for using TLS	TLS client key in PEM format. Must be used with `clientCert`. Can be `secretKeyRef` to use a secret reference.	`"-----BEGIN RSA PRIVATE KEY-----\n<base64-encoded PKCS8>\n-----END RSA PRIVATE KEY-----"`

Communication using TLS

To configure communication using TLS:

SQLite

Mon, 01 Jan 0001 00:00:00 +0000

As an alternative to mDNS, the SQLite name resolution component can be used for running Dapr on single-node environments and for local development scenarios. Dapr sidecars that are part of the cluster store their information in a SQLite database on the local machine.

Note

This component is optimized to be used in scenarios where all Dapr instances are running on the same physical machine, where the database is accessed through the same, locally-mounted disk.
Using the SQLite nameresolver with a database file accessed over the network (including via SMB/NFS) can lead to issues such as data corruption, and is not supported.

Configuration format

Name resolution is configured via the Dapr Configuration.

SQLite

Mon, 01 Jan 0001 00:00:00 +0000

This component allows using SQLite 3 as state store for Dapr.

The component is currently compiled with SQLite version 3.41.2.

Create a Dapr component

Create a file called sqlite.yaml, paste the following, and replace the <CONNECTION STRING> value with your connection string, which is the path to a file on disk.

If you want to also configure SQLite to store actors, add the actorStateStore option as in the example below.

status CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

Show the health status of Dapr services.

Supported platforms

Kubernetes

Usage

dapr status -k

Flags

Name	Environment Variable	Default	Description
`--help`, `-h`			Print this help message
`--kubernetes`, `-k`		`false`	Show the health status of Dapr services on Kubernetes cluster

Examples

# Get status of Dapr services from Kubernetes
dapr status -k

Warning messages

This command can issue warning messages.

Root certificate renewal warning

If the mtls root certificate deployed to the Kubernetes cluster expires in under 30 days the following warning message is displayed:

stop CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

Stop Dapr instances and their associated apps.

Supported platforms

Self-Hosted

Usage

dapr stop [flags]

Flags

Name	Environment Variable	Description
`--app-id`, `-a`	`APP_ID`	The application id to be stopped
`--help`, `-h`		Print this help message
`--run-file`, `-f`		Stop running multiple applications at once using a Multi-App Run template file. Currently in alpha and only available in Linux/MacOS

Examples

# Stop Dapr application
dapr stop --app-id <ID>

Tencent Cloud Secrets Manager (SSM)

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Tencent Cloud Secrets Manager (SSM) secret store create a component of type secretstores.tencentcloud.ssm. See this guide on how to create and apply a secretstore configuration. See this guide on referencing secrets to retrieve and use the secret with Dapr components.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: tencentcloudssm
spec:
 type: secretstores.tencentcloud.ssm
 version: v1
 metadata:
 - name: region
 value: "[tencentcloud_region]"
 - name: secretId
 value: "[tencentcloud_secret_id]"
 - name: secretKey
 value: "[tencentcloud_secret_key]"
 - name: token
 value: "[tencentcloud_secret_token]"

Warning

The above example uses secrets as plain strings. It is recommended to use a local secret store such as Kubernetes secret store or a local file to bootstrap secure key storage.

Spec metadata fields

Field	Required	Details	Example
region	Y	The specific region the Tencent SSM instance is deployed in	`"ap-beijing-3"`
secretId	Y	The SecretId of the Tencent Cloud account	`"xyz"`
secretKey	Y	The SecretKey of the Tencent Cloud account	`"xyz"`
token	N	The Token of the Tencent Cloud account. This is required only if using temporary credentials	`""`

Optional per-request metadata properties

The following optional query parameters can be provided when retrieving secrets from this secret store:

Twilio SendGrid binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Twilio SendGrid binding create a component of type bindings.twilio.sendgrid. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: sendgrid
spec:
 type: bindings.twilio.sendgrid
 version: v1
 metadata:
 - name: emailFrom
 value: "testapp@dapr.io" # optional
 - name: emailFromName
 value: "test app" # optional
 - name: emailTo
 value: "dave@dapr.io" # optional
 - name: emailToName
 value: "dave" # optional
 - name: subject
 value: "Hello!" # optional
 - name: emailCc
 value: "jill@dapr.io" # optional
 - name: emailBcc
 value: "bob@dapr.io" # optional
 - name: dynamicTemplateId
 value: "d-123456789" # optional
 - name: dynamicTemplateData
 value: '{"customer":{"name":"John Smith"}}' # optional
 - name: apiKey
 value: "YOUR_API_KEY" # required, this is your SendGrid key

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`apiKey`	Y	Output	SendGrid API key, this should be considered a secret value	`"apikey"`
`emailFrom`	N	Output	If set this specifies the ‘from’ email address of the email message. Only a single email address is allowed. Optional field, see below	`"me@example.com"`
`emailFromName`	N	Output	If set this specifies the ‘from’ name of the email message. Optional field, see below	`"me"`
`emailTo`	N	Output	If set this specifies the ’to’ email address of the email message. Only a single email address is allowed. Optional field, see below	`"me@example.com"`
`emailToName`	N	Output	If set this specifies the ’to’ name of the email message. Optional field, see below	`"me"`
`emailCc`	N	Output	If set this specifies the ‘cc’ email address of the email message. Only a single email address is allowed. Optional field, see below	`"me@example.com"`
`emailBcc`	N	Output	If set this specifies the ‘bcc’ email address of the email message. Only a single email address is allowed. Optional field, see below	`"me@example.com"`
`subject`	N	Output	If set this specifies the subject of the email message. Optional field, see below	`"subject of the email"`

Binding support

This component supports output binding with the following operations:

Twilio SMS binding spec

Mon, 01 Jan 0001 00:00:00 +0000

Component format

To setup Twilio SMS binding create a component of type bindings.twilio.sms. See this guide on how to create and apply a binding configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
spec:
 type: bindings.twilio.sms
 version: v1
 metadata:
 - name: toNumber # required.
 value: "111-111-1111"
 - name: fromNumber # required.
 value: "222-222-2222"
 - name: accountSid # required.
 value: "*****************"
 - name: authToken # required.
 value: "*****************"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

Field	Required	Binding support	Details	Example
`toNumber`	Y	Output	The target number to send the sms to	`"111-111-1111"`
`fromNumber`	Y	Output	The sender phone number	`"222-222-2222"`
`accountSid`	Y	Output	The Twilio account SID	`"account sid"`
`authToken`	Y	Output	The Twilio auth token	`"auth token"`

Binding support

This component supports output binding with the following operations:

uninstall CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

Uninstall Dapr runtime.

Supported platforms

Usage

dapr uninstall [flags]

Flags

Name	Default	Description
`--all`	`false`	Remove Redis, Zipkin containers in addition to the Scheduler service and the actor Placement service containers. Remove default Dapr dir located at `$HOME/.dapr or %USERPROFILE%\.dapr\`.
`--help`, `-h`		Print this help message
`--kubernetes`, `-k`	`false`	Uninstall Dapr from a Kubernetes cluster
`--namespace`, `-n`	`dapr-system`	The Kubernetes namespace from which Dapr is uninstalled
`--container-runtime`	`docker`	Used to pass in a different container runtime other than Docker. Supported container runtimes are: `docker`, `podman`

Examples

Uninstall from self-hosted mode

dapr uninstall

You can also use option --all to remove .dapr directory, Redis, Placement, Scheduler, and Zipkin containers

upgrade CLI command reference

Mon, 01 Jan 0001 00:00:00 +0000

Description

Upgrade or downgrade Dapr on supported hosting platforms.

Warning

Version steps should be done incrementally, including minor versions as you upgrade or downgrade.

Prior to downgrading, confirm components are backwards compatible and application code does ultilize APIs that are not supported in previous versions of Dapr.

Supported platforms

Kubernetes

Usage

dapr upgrade [flags]

Flags

Name	Default	Description
`--help`, `-h`		Print this help message
`--kubernetes`, `-k`	`false`	Upgrade/Downgrade Dapr in a Kubernetes cluster
`--runtime-version`	`latest`	The version of the Dapr runtime to upgrade/downgrade to, for example: `1.0.0`
`--set`		Set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)
`--image-registry`		Pulls container images required by Dapr from the given image registry

Examples

# Upgrade Dapr in Kubernetes to latest version
dapr upgrade -k

# Upgrade or downgrade to a specified version of Dapr runtime in Kubernetes
dapr upgrade -k --runtime-version 1.2

# Upgrade or downgrade to a specified version of Dapr runtime in Kubernetes with value set
dapr upgrade -k --runtime-version 1.2 --set global.logAsJson=true

# Upgrade or downgrade using private registry, if you are using private registry for hosting dapr images and have used it while doing `dapr init -k`
# Scenario 1 : dapr image hosted directly under root folder in private registry - 
dapr init -k --image-registry docker.io/username
# Scenario 2 : dapr image hosted under a new/different directory in private registry - 
dapr init -k --image-registry docker.io/username/<directory-name>

Warning messages

This command can issue warning messages.

Dapr Docs

Authenticating to AWS

Terminology

Authentication Profiles

Access Key ID and Secret Access Key

Conceptual article template

Contributing a new conceptual or overview article

Contributors guide

Prerequisites

Branch guidance

Install the Dapr CLI

Before you begin

Step 1: Install the Dapr CLI

Install from Terminal

Introduction

Dapr Agents v1.0 — Generally Available

Contribution overview

Dapr Repository Index

Actors overview

Service invocation overview

Service invocation API

Errors overview

Error format

Distributed tracing overview

Scenarios

Retry resiliency policies

Dapr command line interface (CLI) reference

Command Reference

Timeout resiliency policies

Timeout policy format

Spec metadata

Agent Sessions

Overview

Getting Started

Getting Started

Dapr Agents Concepts

Install Dapr CLI

Authenticating an MCP server

Overview

How-To: Invoke services using HTTP

Note

Choose an ID for your service

Initialize Dapr in your local environment

Kubernetes Development Environment

Docker

Maintainer guide

Branch guidance

Override default retry resiliency policies

Giving a presentation on Dapr

Quickstart guide template

Contributing a new quickstart guide

Error codes reference guide

Actor runtime features

Actor lifetime

W3C trace context overview

Background

CrewAI Workflows

Overview

Agent Sessions

Overview

Getting Started

Circuit breaker resiliency policies

Configure Dapr to send distributed tracing data

Note

Configuration

How-to guide template

Contributing a new how-to guide

How-To: Invoke services using gRPC

Handling HTTP error codes

Related

Dapr Roadmap

Actor runtime configuration parameters

Drain timeout clamping

Use the Dapr API

Pre-requisites

Step 1: Run the Dapr sidecar

Why Dapr Agents

Core Concepts

Agents

Default resiliency policies