This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Dapr resource specs

Detailed information and specifications on Dapr resources

1 - Component spec

The basic spec for a Dapr component

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.

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"

2 - Subscription spec

The basic spec for a Dapr subscription

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

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: The CEL expression used to match the event. If not specified, the route is considered the default.
  • path: The path for events that match this rule.
The endpoint to which all topic messages are sent.
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

3 - Resiliency spec

The basic spec for a Dapr resiliency resource

The Resiliency Dapr resource allows you to define and apply fault tolerance resiliency policies. Resiliency specs are applied when the Dapr sidecar starts.

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

4 - HTTPEndpoint spec

The basic spec for a Dapr HTTPEndpoint resource

The HTTPEndpoint is a Dapr resource that is used to enable the invocation of non-Dapr endpoints from a Dapr application.

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.

5 - Configuration spec

The basic spec for a Dapr Configuration resource

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.