This is the multi-page printable view of this section. Click here to print.
Dapr resource specs
- 1: Component spec
- 2: Subscription spec
- 3: Resiliency spec
- 4: HTTPEndpoint spec
- 5: Configuration spec
1 - Component spec
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.
Note
The exception to this rule is in self-hosted mode, where daprd ingests component resources when the namespace field is omitted. However, the security profile is mute, as daprd has access to the manifest anyway, unlike in Kubernetes.Format
apiVersion: dapr.io/v1alpha1
kind: Component
auth:
secretstore: <REPLACE-WITH-SECRET-STORE-NAME>
metadata:
name: <REPLACE-WITH-COMPONENT-NAME>
namespace: <REPLACE-WITH-COMPONENT-NAMESPACE>
spec:
type: <REPLACE-WITH-COMPONENT-TYPE>
version: v1
initTimeout: <REPLACE-WITH-TIMEOUT-DURATION>
ignoreErrors: <REPLACE-WITH-BOOLEAN>
metadata:
- name: <REPLACE-WITH-METADATA-NAME>
value: <REPLACE-WITH-METADATA-VALUE>
scopes:
- <REPLACE-WITH-APPID>
- <REPLACE-WITH-APPID>
Spec fields
Field | Required | Details | Example |
---|---|---|---|
apiVersion | Y | The version of the Dapr (and Kubernetes if applicable) API you are calling | dapr.io/v1alpha1 |
kind | Y | The type of resource. For components is must always be Component |
Component |
auth | N | The name of a secret store where secretKeyRef in the metadata lookup the name of secrets used in the component |
See How-to: Reference secrets in components |
scopes | N | The applications the component is limited to, specified by their app IDs | order-processor , checkout |
metadata | - | Information about the component registration | |
metadata.name | Y | The name of the component | prod-statestore |
metadata.namespace | N | The namespace for the component for hosting environments with namespaces | myapp-namespace |
spec | - | Detailed information on the component resource | |
spec.type | Y | The type of the component | state.redis |
spec.version | Y | The version of the component | v1 |
spec.initTimeout | N | The timeout duration for the initialization of the component. Default is 5s | 5m , 1h , 20s |
spec.ignoreErrors | N | Tells the Dapr sidecar to continue initialization if the component fails to load. Default is false | false |
spec.metadata | - | A key/value pair of component specific configuration. See your component definition for fields | |
spec.metadata.name | Y | The name of the component-specific property and its value | - name: secretsFile value: secrets.json |
Templated metadata values
Metadata values can contain template tags that are resolved on Dapr sidecar startup. The table below shows the current templating tags that can be used in components.
Tag | Details | Example use case |
---|---|---|
{uuid} | Randomly generated UUIDv4 | When you need a unique identifier in self-hosted mode; for example, multiple application instances consuming a shared MQTT subscription |
{podName} | Name of the pod containing the Dapr sidecar | Use to have a persisted behavior, where the ConsumerID does not change on restart when using StatefulSets in Kubernetes |
{namespace} | Namespace where the Dapr sidecar resides combined with its appId | Using a shared clientId when multiple application instances consume a Kafka topic in Kubernetes |
{appID} | The configured appID of the resource containing the Dapr sidecar |
Having a shared clientId when multiple application instances consumer a Kafka topic in self-hosted mode |
Below is an example of using the {uuid}
tag in an MQTT pubsub component. Note that multiple template tags can be used in a single metadata value.
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: messagebus
spec:
type: pubsub.mqtt3
version: v1
metadata:
- name: consumerID
value: "{uuid}"
- name: url
value: "tcp://admin:public@localhost:1883"
- name: qos
value: 1
- name: retain
value: "false"
- name: cleanSession
value: "false"
Related links
2 - Subscription spec
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.
apiVersion: dapr.io/v2alpha1
kind: Subscription
metadata:
name: <REPLACE-WITH-NAME>
spec:
topic: <REPLACE-WITH-TOPIC-NAME> # Required
routes: # Required
rules:
- match: <REPLACE-WITH-CEL-FILTER>
path: <REPLACE-WITH-PATH>
pubsubname: <REPLACE-WITH-PUBSUB-NAME> # Required
deadLetterTopic: <REPLACE-WITH-DEADLETTERTOPIC-NAME> # Optional
bulkSubscribe: # Optional
enabled: <REPLACE-WITH-BOOLEAN-VALUE>
maxMessagesCount: <REPLACE-WITH-VALUE>
maxAwaitDurationMs: <REPLACE-WITH-VALUE>
scopes:
- <REPLACE-WITH-SCOPED-APPIDS>
Spec fields
Field | Required | Details | Example |
---|---|---|---|
topic | Y | The name of the topic to which your component subscribes. | orders |
routes | Y | The routes configuration for this topic, including specifying the condition for sending a message to a specific path. Includes the following fields:
|
match: event.type == "widget" path: /widgets |
pubsubname | N | The name of your pub/sub component. | pubsub |
deadLetterTopic | N | The name of the dead letter topic that forwards undeliverable messages. | poisonMessages |
bulkSubscribe | N | Enable bulk subscribe properties. | true , false |
v1alpha1
format
The following is the basic version v1alpha1
spec for a Subscription
resource. v1alpha1
is now deprecated.
apiVersion: dapr.io/v1alpha1
kind: Subscription
metadata:
name: <REPLACE-WITH-RESOURCE-NAME>
spec:
topic: <REPLACE-WITH-TOPIC-NAME> # Required
route: <REPLACE-WITH-ROUTE-NAME> # Required
pubsubname: <REPLACE-WITH-PUBSUB-NAME> # Required
deadLetterTopic: <REPLACE-WITH-DEAD-LETTER-TOPIC-NAME> # Optional
bulkSubscribe: # Optional
- enabled: <REPLACE-WITH-BOOLEAN-VALUE>
- maxMessagesCount: <REPLACE-WITH-VALUE>
- maxAwaitDurationMs: <REPLACE-WITH-VALUE>
scopes:
- <REPLACE-WITH-SCOPED-APPIDS>
Spec fields
Field | Required | Details | Example |
---|---|---|---|
topic | Y | The name of the topic to which your component subscribes. | orders |
route | Y | The endpoint to which all topic messages are sent. | /checkout |
pubsubname | N | The name of your pub/sub component. | pubsub |
deadlettertopic | N | The name of the dead letter topic that forwards undeliverable messages. | poisonMessages |
bulksubscribe | N | Enable bulk subscribe properties. | true , false |
Related links
3 - Resiliency spec
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:
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 |
Related links
4 - HTTPEndpoint spec
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 |
Related links
5 - Configuration spec
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>
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.
apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
name: daprsystem
namespace: default
spec:
mtls:
enabled: true
allowedClockSkew: 15m
workloadCertTTL: 24h
Spec fields
Field | Required | Details | Example |
---|---|---|---|
mtls | N | Defines the mTLS configuration | allowedClockSkew: 15m workloadCertTTL:24h Learn more about the mtls configuration. |