Overview of Dapr configuration options

Information on Dapr configuration and how to set options for your application

Sidecar configuration

Setup sidecar configuration

Self-hosted sidecar

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 eg: $HOME/.dapr/config.yaml in Linux/MacOS and %USERPROFILE%\.dapr\config.yaml in Windows.

A Dapr sidecar can also apply a configuration by using a --config flag to the file path with dapr run CLI command.

Kubernetes sidecar

In Kubernetes mode the Dapr configuration is a Configuration resource, that is applied to the cluster. For example:

  1. kubectl apply -f myappconfig.yaml

You can use the Dapr CLI to list the Configuration resources

  1. dapr configurations -k

A Dapr sidecar can apply a specific configuration by using a dapr.io/config annotation. For example:

  1. annotations:
  2. dapr.io/enabled: "true"
  3. dapr.io/app-id: "nodeapp"
  4. dapr.io/app-port: "3000"
  5. dapr.io/config: "myappconfig"

Note: There are more Kubernetes annotations available to configure the Dapr sidecar on activation by sidecar Injector system service.

Sidecar configuration settings

The following configuration settings can be applied to Dapr application sidecars:

Tracing

Tracing configuration turns on tracing for an application.

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

  1. tracing:
  2. samplingRate: "1"
  3. otel:
  4. endpointAddress: "https://..."
  5. zipkin:
  6. endpointAddress: "http://zipkin.default.svc.cluster.local:9411/api/v2/spans"

The following table lists the properties for tracing:

PropertyTypeDescription
samplingRatestringSet sampling rate for tracing to be enabled or disabled.
stdoutboolTrue write more verbose information to the traces
otel.endpointAddressstringSet the Open Telemetry (OTEL) server address to send traces to
otel.isSecureboolIs the connection to the endpoint address encrypted
otel.protocolstringSet to http or grpc protocol
zipkin.endpointAddressstringSet the Zipkin server address to send traces to

samplingRate is used to enable or disable the tracing. To disable the sampling rate , set samplingRate : "0" in the configuration. The valid range of samplingRate is between 0 and 1 inclusive. The sampling rate determines whether a trace span should be sampled or not based on value. samplingRate : "1" samples all traces. By default, the sampling rate is (0.0001) or 1 in 10,000 traces.

The OpenTelemetry (otel) endpoint can also be configured via an environment variables. The presence of the OTEL_EXPORTER_OTLP_ENDPOINT environment variable turns on tracing for the sidecar.

Environment VariableDescription
OTEL_EXPORTER_OTLP_ENDPOINTSets the Open Telemetry (OTEL) server address, turns on tracing
OTEL_EXPORTER_OTLP_INSECURESets the connection to the endpoint as unencrypted (true/false)
OTEL_EXPORTER_OTLP_PROTOCOLTransport protocol (grpc, http/protobuf, http/json)

See Observability distributed tracing for more information.

Metrics

The metrics section can be used to enable or disable metrics for an application.

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

  1. metrics:
  2. enabled: true
  3. rules: []
  4. http:
  5. increasedCardinality: true

The following table lists the properties for metrics:

PropertyTypeDescription
enabledbooleanWhen set to true, the default, enables metrics collection and the metrics endpoint.
rulesarrayNamed rule to filter metrics. Each rule contains a set of labels to filter on and a regex expression to apply to the metrics path.
http.increasedCardinalitybooleanWhen set to true, in the Dapr HTTP server each request path causes the creation of a new “bucket” of metrics. This can cause issues, including excessive memory consumption, when there many different requested endpoints (such as when interacting with RESTful APIs).
In Dapr 1.13 the default value is true (to preserve the behavior of Dapr <= 1.12), but will change to false in Dapr 1.14.

To mitigate high memory usage and egress costs associated with high cardinality metrics with the HTTP server, you should set the metrics.http.increasedCardinality property to false.

Using rules, you can set regular expressions for every metric exposed by the Dapr sidecar. For example:

  1. metrics:
  2. enabled: true
  3. rules:
  4. - name: dapr_runtime_service_invocation_req_sent_total
  5. labels:
  6. - name: method
  7. regex:
  8. "orders/": "orders/.+"

See metrics documentation for more information.

Logging

The logging section can be used to configure how logging works in the Dapr Runtime.

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

  1. logging:
  2. apiLogging:
  3. enabled: false
  4. obfuscateURLs: false
  5. omitHealthChecks: false

The following table lists the properties for logging:

PropertyTypeDescription
apiLogging.enabledbooleanThe default value for the —enable-api-logging flag for daprd (and the corresponding dapr.io/enable-api-logging annotation): the value set in the Configuration spec is used as default unless a true or false value is passed to each Dapr Runtime. Default: false.
apiLogging.obfuscateURLsbooleanWhen enabled, obfuscates the values of URLs in HTTP API logs (if enabled), logging the abstract route name rather than the full path being invoked, which could contain Personal Identifiable Information (PII). Default: false.
apiLogging.omitHealthChecksbooleanIf true, calls to health check endpoints (e.g. /v1.0/healthz) are not logged when API logging is enabled. This is useful if those calls are adding a lot of noise in your logs. Default: false

See logging documentation for more information.

Middleware

Middleware configuration set named HTTP pipeline middleware handlers The httpPipeline and the appHttpPipeline section under the Configuration spec contains the following properties:

  1. httpPipeline: # for incoming http calls
  2. handlers:
  3. - name: oauth2
  4. type: middleware.http.oauth2
  5. - name: uppercase
  6. type: middleware.http.uppercase
  7. appHttpPipeline: # for outgoing http calls
  8. handlers:
  9. - name: oauth2
  10. type: middleware.http.oauth2
  11. - name: uppercase
  12. type: middleware.http.uppercase

The following table lists the properties for HTTP handlers:

PropertyTypeDescription
namestringName of the middleware component
typestringType of middleware component

See Middleware pipelines for more information

Name resolution component

You can set name resolution component to use within the configuration YAML. For example, to set the spec.nameResolution.component property to "sqlite", pass configuration options in the spec.nameResolution.configuration dictionary as shown below.

This is the basic example of a configuration resource:

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Configuration
  3. metadata:
  4. name: appconfig
  5. spec:
  6. nameResolution:
  7. component: "sqlite"
  8. version: "v1"
  9. configuration:
  10. connectionString: "/home/user/.dapr/nr.db"

For more information, see:

Scope secret store access

See the Scoping secrets guide for information and examples on how to scope secrets to an application.

Access Control allow lists for building block APIs

See the selectively enable Dapr APIs on the Dapr sidecar guide for information and examples on how to set ACLs on the building block APIs lists.

Access Control allow lists for service invocation API

See the Allow lists for service invocation guide for information and examples on how to set allow lists with ACLs which using service invocation API.

Disallow usage of certain component types

Using the components.deny property in the Configuration spec you can specify a denylist of component types that cannot be initialized.

For example, the configuration below disallows the initialization of components of type bindings.smtp and secretstores.local.file:

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Configuration
  3. metadata:
  4. name: myappconfig
  5. spec:
  6. components:
  7. deny:
  8. - bindings.smtp
  9. - secretstores.local.file

You can optionally specify a version to disallow by adding it at the end of the component name. For example, state.in-memory/v1 disables initializing components of type state.in-memory and version v1, but does not disable a (hypothetical) v2 version of the component.

Note: One special note applies to the component type secretstores.kubernetes. When you add that component to the denylist, Dapr forbids the creation of additional components of type secretstores.kubernetes. However, it does not disable the built-in Kubernetes secret store, which is created by Dapr automatically and is used to store secrets specified in Components specs. If you want to disable the built-in Kubernetes secret store, you need to use the dapr.io/disable-builtin-k8s-secret-store annotation.

Turning on preview features

See the preview features guide for information and examples on how to opt-in to preview features for a release. Preview feature enable new capabilities to be added that still need more time until they become generally available (GA) in the runtime.

Example sidecar configuration

The following YAML shows an example configuration file that can be applied to an applications’ Dapr sidecar.

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Configuration
  3. metadata:
  4. name: myappconfig
  5. namespace: default
  6. spec:
  7. tracing:
  8. samplingRate: "1"
  9. stdout: true
  10. otel:
  11. endpointAddress: "localhost:4317"
  12. isSecure: false
  13. protocol: "grpc"
  14. httpPipeline:
  15. handlers:
  16. - name: oauth2
  17. type: middleware.http.oauth2
  18. secrets:
  19. scopes:
  20. - storeName: localstore
  21. defaultAccess: allow
  22. deniedSecrets: ["redis-password"]
  23. components:
  24. deny:
  25. - bindings.smtp
  26. - secretstores.local.file
  27. accessControl:
  28. defaultAction: deny
  29. trustDomain: "public"
  30. policies:
  31. - appId: app1
  32. defaultAction: deny
  33. trustDomain: 'public'
  34. namespace: "default"
  35. operations:
  36. - name: /op1
  37. httpVerb: ['POST', 'GET']
  38. action: deny
  39. - name: /op2/*
  40. httpVerb: ["*"]
  41. action: allow

Control plane configuration

There is a single configuration file called daprsystem installed with the Dapr control plane system services that applies global settings. This is only set up when Dapr is deployed to Kubernetes.

Control plane configuration settings

A Dapr control plane configuration contains the following sections:

  • mtls for mTLS (Mutual TLS)

mTLS (Mutual TLS)

The mtls section contains properties for mTLS.

PropertyTypeDescription
enabledboolIf true, enables mTLS for communication between services and apps in the cluster.
allowedClockSkewstringAllowed tolerance when checking the expiration of TLS certificates, to allow for clock skew. Follows the format used by Go’s time.ParseDuration. Default is 15m (15 minutes).
workloadCertTTLstringHow long a certificate TLS issued by Dapr is valid for. Follows the format used by Go’s time.ParseDuration. Default is 24h (24 hours).
sentryAddressstringHostname port address for connecting to the Sentry server.
controlPlaneTrustDomainstringTrust domain for the control plane. This is used to verify connection to control plane services.
tokenValidatorsarrayAdditional Sentry token validators to use for authenticating certificate requests.

See the mTLS how-to and security concepts for more information.

Example control plane configuration

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Configuration
  3. metadata:
  4. name: daprsystem
  5. namespace: default
  6. spec:
  7. mtls:
  8. enabled: true
  9. allowedClockSkew: 15m
  10. workloadCertTTL: 24h

Last modified March 21, 2024: Merge pull request #4082 from newbe36524/v1.13 (f4b0938)