diff --git a/.github/workflows/website-root.yml b/.github/workflows/website-root.yml index aa2b3fe0a27..6bd00c5e6db 100644 --- a/.github/workflows/website-root.yml +++ b/.github/workflows/website-root.yml @@ -97,7 +97,7 @@ jobs: with: submodules: false - name: Download Hugo artifacts - uses: actions/download-artifact@v3 + uses: actions/download-artifact@v4.1.7 with: name: hugo_build path: site/ diff --git a/daprdocs/content/en/concepts/configuration-concept.md b/daprdocs/content/en/concepts/configuration-concept.md index f9b89ad4fa0..a4a85939592 100644 --- a/daprdocs/content/en/concepts/configuration-concept.md +++ b/daprdocs/content/en/concepts/configuration-concept.md @@ -6,9 +6,13 @@ weight: 400 description: "Change the behavior of Dapr application sidecars or globally on Dapr control plane system services" --- -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 example, you can set an ACL policy on the application sidecar configuration which indicates which methods can be called from another application, or on the Dapr control plane configuration you can change the certificate renewal period for all certificates that are deployed to application sidecar instances. +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 -Configurations are defined and deployed as a YAML file. An application configuration example is shown below, which demonstrates an example of setting a tracing endpoint for where to send the metrics information, capturing all the sample traces. +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. + +Configurations are defined and deployed as a YAML file. In the following application configuration example, a tracing endpoint is set for where to send the metrics information, capturing all the sample traces. ```yaml apiVersion: dapr.io/v1alpha1 @@ -23,9 +27,11 @@ spec: endpointAddress: "http://localhost:9411/api/v2/spans" ``` -This configuration configures tracing for metrics recording. It can be loaded in local self-hosted mode by editing the default configuration file called `config.yaml` file in your `.dapr` directory, or by applying it to your Kubernetes cluster with kubectl/helm. +The above YAML configures tracing for metrics recording. You can load it in local self-hosted mode by either: +- Editing the default configuration file called `config.yaml` file in your `.dapr` directory, or +- Applying it to your Kubernetes cluster with `kubectl/helm`. -Here is an example of the Dapr control plane configuration called `daprsystem` in the `dapr-system` namespace. +The following example shows the Dapr control plane configuration called `daprsystem` in the `dapr-system` namespace. ```yaml apiVersion: dapr.io/v1alpha1 @@ -40,8 +46,14 @@ spec: allowedClockSkew: "15m" ``` -Visit [overview of Dapr configuration options]({{}}) for a list of the configuration options. +By default, there is a single configuration file called `daprsystem` installed with the Dapr control plane system services. This configuration file applies global control plane settings and is set up when Dapr is deployed to Kubernetes. + +[Learn more about configuration options.]({{< ref "configuration-overview.md" >}}) -{{% alert title="Note" color="primary" %}} -Dapr application and control plane configurations should not be confused with the configuration building block API that enables applications to retrieve key/value data from configuration store components. Read the [Configuration building block]({{< ref configuration-api-overview >}}) for more information. +{{% alert title="Important" color="warning" %}} +Dapr application and control plane configurations should not be confused with the [configuration building block API]({{< ref configuration-api-overview >}}), which enables applications to retrieve key/value data from configuration store components. {{% /alert %}} + +## Next steps + +{{< button text="Learn more about configuration" page="configuration-overview" >}} \ No newline at end of file diff --git a/daprdocs/content/en/operations/configuration/api-allowlist.md b/daprdocs/content/en/operations/configuration/api-allowlist.md index 75930dba8bf..b0a02d9bf1f 100644 --- a/daprdocs/content/en/operations/configuration/api-allowlist.md +++ b/daprdocs/content/en/operations/configuration/api-allowlist.md @@ -6,17 +6,17 @@ weight: 4500 description: "Choose which Dapr sidecar APIs are available to the app" --- -In certain 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 that are 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. +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 developers to control which APIs are accessible to the application by setting an API allowlist or denylist using a [Dapr Configuration]({{}}). +Dapr allows you to control which APIs are accessible to the application by setting an API allowlist or denylist using a [Dapr Configuration]({{< ref "configuration-schema.md" >}}). ### Default behavior If no API allowlist or denylist is specified, the default behavior is to allow access to all Dapr APIs. -- If only a denylist is defined, all Dapr APIs are allowed except those defined in the denylist -- If only an allowlist is defined, only the Dapr APIs listed in the allowlist are allowed -- If both an allowlist and a denylist are defined, the allowed APIs are those defined in the allowlist, unless they are also included in the denylist. In other words, the denylist overrides the allowlist for APIs that are defined in both. +- If you've only defined a denylist, all Dapr APIs are allowed except those defined in the denylist +- If you've only defined an allowlist, only the Dapr APIs listed in the allowlist are allowed +- If you've defined both an allowlist and a denylist, the denylist overrides the allowlist for APIs that are defined in both. - If neither is defined, all APIs are allowed. For example, the following configuration enables all APIs for both HTTP and gRPC: @@ -119,14 +119,18 @@ See this list of values corresponding to the different Dapr APIs: | [Service Invocation]({{< ref service_invocation_api.md >}}) | `invoke` (`v1.0`) | `invoke` (`v1`) | | [State]({{< ref state_api.md>}})| `state` (`v1.0` and `v1.0-alpha1`) | `state` (`v1` and `v1alpha1`) | | [Pub/Sub]({{< ref pubsub.md >}}) | `publish` (`v1.0` and `v1.0-alpha1`) | `publish` (`v1` and `v1alpha1`) | +| [Output Bindings]({{< ref bindings_api.md >}}) | `bindings` (`v1.0`) |`bindings` (`v1`) | | Subscribe | n/a | `subscribe` (`v1alpha1`) | -| [(Output) Bindings]({{< ref bindings_api.md >}}) | `bindings` (`v1.0`) |`bindings` (`v1`) | | [Secrets]({{< ref secrets_api.md >}})| `secrets` (`v1.0`) | `secrets` (`v1`) | | [Actors]({{< ref actors_api.md >}}) | `actors` (`v1.0`) |`actors` (`v1`) | | [Metadata]({{< ref metadata_api.md >}}) | `metadata` (`v1.0`) |`metadata` (`v1`) | | [Configuration]({{< ref configuration_api.md >}}) | `configuration` (`v1.0` and `v1.0-alpha1`) | `configuration` (`v1` and `v1alpha1`) | | [Distributed Lock]({{< ref distributed_lock_api.md >}}) | `lock` (`v1.0-alpha1`)
`unlock` (`v1.0-alpha1`) | `lock` (`v1alpha1`)
`unlock` (`v1alpha1`) | -| Cryptography | `crypto` (`v1.0-alpha1`) | `crypto` (`v1alpha1`) | +| [Cryptography]({{< ref cryptography_api.md >}}) | `crypto` (`v1.0-alpha1`) | `crypto` (`v1alpha1`) | | [Workflow]({{< ref workflow_api.md >}}) | `workflows` (`v1.0-alpha1`) |`workflows` (`v1alpha1`) | | [Health]({{< ref health_api.md >}}) | `healthz` (`v1.0`) | n/a | | Shutdown | `shutdown` (`v1.0`) | `shutdown` (`v1`) | + +## Next steps + +{{< button text="Configure Dapr to use gRPC" page="grpc" >}} \ No newline at end of file diff --git a/daprdocs/content/en/operations/configuration/configuration-overview.md b/daprdocs/content/en/operations/configuration/configuration-overview.md index 0cba2414ca4..bda1cae0c37 100644 --- a/daprdocs/content/en/operations/configuration/configuration-overview.md +++ b/daprdocs/content/en/operations/configuration/configuration-overview.md @@ -1,30 +1,44 @@ --- type: docs -title: "Overview of Dapr configuration options" +title: "Dapr configuration" linkTitle: "Overview" weight: 100 -description: "Information on Dapr configuration and how to set options for your application" +description: "Overview of Dapr configuration" --- -## Sidecar configuration +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. -### Setup sidecar configuration +[for more information, read the configuration concept.]({{< ref configuration-concept.md >}}) -#### Self-hosted sidecar +## Application configuration -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. +### Set up application configuration -A Dapr sidecar can also apply a configuration by using a `--config` flag to the file path with `dapr run` CLI command. +You can set up application configuration either in self-hosted or Kubernetes mode. -#### Kubernetes sidecar +{{< tabs "Self-hosted" Kubernetes >}} -In Kubernetes mode the Dapr configuration is a Configuration resource, that is applied to the cluster. For example: + +{{% codetab %}} + +In self hosted mode, the Dapr configuration is a [configuration file]({{< ref configuration-schema.md >}}) - for example, `config.yaml`. By default, the Dapr sidecar looks in the default Dapr folder for the runtime configuration: +- Linux/MacOs: `$HOME/.dapr/config.yaml` +- Windows: `%USERPROFILE%\.dapr\config.yaml` + +An application can also apply a configuration by using a `--config` flag to the file path with `dapr run` CLI command. + +{{% /codetab %}} + + +{{% codetab %}} + +In Kubernetes mode, the Dapr configuration is a Configuration resource, that is applied to the cluster. For example: ```bash kubectl apply -f myappconfig.yaml ``` -You can use the Dapr CLI to list the Configuration resources +You can use the Dapr CLI to list the Configuration resources for applications. ```bash dapr configurations -k @@ -40,11 +54,15 @@ A Dapr sidecar can apply a specific configuration by using a `dapr.io/config` an dapr.io/config: "myappconfig" ``` -Note: There are more [Kubernetes annotations]({{< ref "arguments-annotations-overview.md" >}}) available to configure the Dapr sidecar on activation by sidecar Injector system service. +> **Note:** [See all Kubernetes annotations]({{< ref "arguments-annotations-overview.md" >}}) available to configure the Dapr sidecar on activation by sidecar Injector system service. + +{{% /codetab %}} -### Sidecar configuration settings +{{< /tabs >}} -The following configuration settings can be applied to Dapr application sidecars: +### Application configuration settings + +The following menu includes all of the configuration settings you can set on the sidecar. - [Tracing](#tracing) - [Metrics](#metrics) @@ -84,10 +102,17 @@ The following table lists the properties for tracing: | `otel.protocol` | string | Set to `http` or `grpc` protocol | `zipkin.endpointAddress` | string | Set 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. +##### `samplingRate` + +`samplingRate` is used to enable or disable the tracing. 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. -The OpenTelemetry (otel) endpoint can also be configured via an environment variables. The presence of the OTEL_EXPORTER_OTLP_ENDPOINT environment variable +`samplingRate : "1"` samples all traces. By default, the sampling rate is (0.0001), or 1 in 10,000 traces. + +To disable the sampling rate, set `samplingRate : "0"` in the configuration. + +##### `otel` + +The OpenTelemetry (`otel`) endpoint can also be configured via an environment variable. The presence of the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable turns on tracing for the sidecar. | Environment Variable | Description | @@ -100,9 +125,9 @@ See [Observability distributed tracing]({{< ref "tracing-overview.md" >}}) for m #### Metrics -The metrics section can be used to enable or disable metrics for an application. +The `metrics` section under the `Configuration` spec can be used to enable or disable metrics for an application. -The `metrics` section under the `Configuration` spec contains the following properties: +The `metrics` section contains the following properties: ```yml metrics: @@ -122,7 +147,7 @@ metrics: excludeVerbs: false ``` -In the examples above this path filter `/orders/{orderID}/items/{itemID}` would return a single metric count matching all the orderIDs and all the itemIDs rather than multiple metrics for each itemID. For more information see [HTTP metrics path matching]({{< ref "metrics-overview.md#http-metrics-path-matching" >}}) +In the examples above, the path filter `/orders/{orderID}/items/{itemID}` would return _a single metric count_ matching all the `orderID`s and all the `itemID`s, rather than multiple metrics for each `itemID`. For more information, see [HTTP metrics path matching]({{< ref "metrics-overview.md#http-metrics-path-matching" >}}) The following table lists the properties for metrics: @@ -135,7 +160,7 @@ The following table lists the properties for metrics: | `http.pathMatching` | array | Array of paths for path matching, allowing users to define matching paths to manage cardinality. | | `http.excludeVerbs` | boolean | When set to true (default is false), the Dapr HTTP server ignores each request HTTP verb when building the method metric label. | -To further help managing cardinality, path matching allows specified paths matched according to defined patterns, reducing the number of unique metrics paths and thus controlling metric cardinality. This feature is particularly useful for applications with dynamic URLs, ensuring that metrics remain meaningful and manageable without excessive memory consumption. +To further help manage cardinality, path matching allows you to match specified paths according to defined patterns, reducing the number of unique metrics paths and thus controlling metric cardinality. This feature is particularly useful for applications with dynamic URLs, ensuring that metrics remain meaningful and manageable without excessive memory consumption. Using rules, you can set regular expressions for every metric exposed by the Dapr sidecar. For example: @@ -154,9 +179,9 @@ See [metrics documentation]({{< ref "metrics-overview.md" >}}) for more informat #### Logging -The logging section can be used to configure how logging works in the Dapr Runtime. +The `logging` section under the `Configuration` spec is used to configure how logging works in the Dapr Runtime. -The `logging` section under the `Configuration` spec contains the following properties: +The `logging` section contains the following properties: ```yml logging: @@ -178,8 +203,7 @@ See [logging documentation]({{< ref "logs.md" >}}) 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: +Middleware configuration sets named HTTP pipeline middleware handlers. The `httpPipeline` and the `appHttpPipeline` section under the `Configuration` spec contain the following properties: ```yml httpPipeline: # for incoming http calls @@ -203,13 +227,13 @@ The following table lists the properties for HTTP handlers: | `name` | string | Name of the middleware component | `type` | string | Type of middleware component -See [Middleware pipelines]({{< ref "middleware.md" >}}) for more information +See [Middleware pipelines]({{< ref "middleware.md" >}}) 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. +You can set name resolution components to use within the configuration file. 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: +This is a basic example of a configuration resource: ```yaml apiVersion: dapr.io/v1alpha1 @@ -226,7 +250,7 @@ spec: For more information, see: - [The name resolution component documentation]({{< ref supported-name-resolution >}}) for more examples. -- - [The Configuration YAML documentation]({{< ref configuration-schema.md >}}) to learn more about how to configure name resolution per component. +- [The Configuration file documentation]({{< ref configuration-schema.md >}}) to learn more about how to configure name resolution per component. #### Scope secret store access @@ -234,11 +258,11 @@ See the [Scoping secrets]({{< ref "secret-scope.md" >}}) guide for information a #### Access Control allow lists for building block APIs -See the [selectively enable Dapr APIs on the Dapr sidecar]({{< ref "api-allowlist.md" >}}) guide for information and examples on how to set ACLs on the building block APIs lists. +See the guide for [selectively enabling Dapr APIs on the Dapr sidecar]({{< ref "api-allowlist.md" >}}) for information and examples on how to set access control allow lists (ACLs) on the building block APIs lists. #### Access Control allow lists for service invocation API -See the [Allow lists for service invocation]({{< ref "invoke-allowlist.md" >}}) guide for information and examples on how to set allow lists with ACLs which using service invocation API. +See the [Allow lists for service invocation]({{< ref "invoke-allowlist.md" >}}) guide for information and examples on how to set allow lists with ACLs which use the service invocation API. #### Disallow usage of certain component types @@ -258,13 +282,23 @@ spec: - 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. +Optionally, you can 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. + +{{% alert title="Note" color="primary" %}} + When you add the component type `secretstores.kubernetes` to the denylist, Dapr forbids the creation of _additional_ components of type `secretstores.kubernetes`. -> 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]({{< ref arguments-annotations-overview.md >}}). + However, it does not disable the built-in Kubernetes secret store, which is: + - Created by Dapr automatically + - 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]({{< ref arguments-annotations-overview.md >}}). +{{% /alert %}} #### Turning on preview features -See the [preview features]({{< ref "preview-features.md" >}}) 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. +See the [preview features]({{< ref "preview-features.md" >}}) guide for information and examples on how to opt-in to preview features for a release. + +Enabling preview features unlock new capabilities to be added for dev/test, since they still need more time before becoming generally available (GA) in the runtime. ### Example sidecar configuration @@ -316,7 +350,9 @@ spec: ## 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. +A single configuration file called `daprsystem` is 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 @@ -353,3 +389,7 @@ spec: allowedClockSkew: 15m workloadCertTTL: 24h ``` + +## Next steps + +{{< button text="Learn about concurrency and rate limits" page="control-concurrency" >}} diff --git a/daprdocs/content/en/operations/configuration/control-concurrency.md b/daprdocs/content/en/operations/configuration/control-concurrency.md index 85b240c19b5..976b78ab980 100644 --- a/daprdocs/content/en/operations/configuration/control-concurrency.md +++ b/daprdocs/content/en/operations/configuration/control-concurrency.md @@ -3,30 +3,57 @@ type: docs title: "How-To: Control concurrency and rate limit applications" linkTitle: "Concurrency & rate limits" weight: 2000 -description: "Control how many requests and events will invoke your application simultaneously" +description: "Learn how to control how many requests and events can invoke your application simultaneously" --- -A common scenario in distributed computing is to only allow for a given number of requests to execute concurrently. -Using Dapr, you can control how many requests and events will invoke your application simultaneously. +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. -*Note that this rate limiting is guaranteed for every event that's coming from Dapr, meaning Pub/Sub events, direct invocation from other services, bindings events etc. Dapr can't enforce the concurrency policy on requests that are coming to your app externally.* +Default `app-max-concurreny` is set to `-1`, meaning no concurrency. -*Note that rate limiting per second can be achieved by using the **middleware.http.ratelimit** middleware. However, there is an important difference between the two approaches. The rate limit middleware is time bound and limits the number of requests per second, while the `app-max-concurrency` flag specifies the number of concurrent requests (and events) at any point of time. See [Rate limit middleware]({{< ref middleware-rate-limit.md >}}). * +## Different approaches -Watch this [video](https://youtu.be/yRI5g6o_jp8?t=1710) on how to control concurrency and rate limiting ". +While this guide focuses on `app-max-concurrency`, you can also limit request rate per second using the **`middleware.http.ratelimit`** middleware. However, it's important to understand the difference between the two approaches: + +- `middleware.http.ratelimit`: Time bound and limits the number of requests per second +- `app-max-concurrency`: Specifies the number of concurrent requests (and events) at any point of time. + +See [Rate limit middleware]({{< ref middleware-rate-limit.md >}}) for more information about that approach. + +## Demo + +Watch this [video](https://youtu.be/yRI5g6o_jp8?t=1710) on how to control concurrency and rate limiting.
-## Setting app-max-concurrency +## Configure `app-max-concurrency` + +Without using Dapr, you would need to create some sort of a semaphore in the application and take care of acquiring and releasing it. + +Using Dapr, you don't need to make any code changes to your application. + +Select how you'd like to configure `app-max-concurrency`. + +{{< tabs "CLI" Kubernetes >}} + + +{{% codetab %}} + +To set concurrency limits with the Dapr CLI for running on your local dev machine, add the `app-max-concurrency` flag: + +```bash +dapr run --app-max-concurrency 1 --app-port 5000 python ./app.py +``` -Without using Dapr, a developer would need to create some sort of a semaphore in the application and take care of acquiring and releasing it. -Using Dapr, there are no code changes needed to an app. +The above example effectively turns your app into a single concurrent service. -### Setting app-max-concurrency in Kubernetes +{{% /codetab %}} -To set app-max-concurrency in Kubernetes, add the following annotation to your pod: + +{{% codetab %}} + +To configure concurrency limits in Kubernetes, add the following annotation to your pod: ```yaml apiVersion: apps/v1 @@ -50,15 +77,22 @@ spec: dapr.io/app-id: "nodesubscriber" dapr.io/app-port: "3000" dapr.io/app-max-concurrency: "1" -... +#... ``` -### Setting app-max-concurrency using the Dapr CLI +{{% /codetab %}} -To set app-max-concurrency with the Dapr CLI for running on your local dev machine, add the `app-max-concurrency` flag: +{{< /tabs >}} -```bash -dapr run --app-max-concurrency 1 --app-port 5000 python ./app.py -``` +## Limitations + +### Controlling concurrency on external requests +Rate limiting is guaranteed for every event coming _from_ Dapr, including pub/sub events, direct invocation from other services, bindings events, etc. However, Dapr can't enforce the concurrency policy on requests that are coming _to_ your app externally. + +## Related links + +[Arguments and annotations]({{< ref arguments-annotations-overview.md >}}) + +## Next steps -The above examples will effectively turn your app into a single concurrent service. +{{< button text="Limit secret store access" page="secret-scope" >}} diff --git a/daprdocs/content/en/operations/configuration/grpc.md b/daprdocs/content/en/operations/configuration/grpc.md index 59c51a4cec3..5ab2df15f07 100644 --- a/daprdocs/content/en/operations/configuration/grpc.md +++ b/daprdocs/content/en/operations/configuration/grpc.md @@ -3,20 +3,21 @@ type: docs title: "How-To: Configure Dapr to use gRPC" linkTitle: "Use gRPC interface" weight: 5000 -description: "How to configure Dapr to use gRPC for low-latency, high performance scenarios" +description: "Configure Dapr to use gRPC for low-latency, high performance scenarios" --- -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 find a list of auto-generated clients [here]({{< ref sdks >}}). +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)]({{< ref sdks >}}). The Dapr runtime implements a [proto service](https://github.com/dapr/dapr/blob/master/dapr/proto/runtime/v1/dapr.proto) that apps can communicate with via gRPC. -In addition to calling Dapr via gRPC, Dapr can communicate with an application via gRPC. To do that, the app needs to host a gRPC server and implements the [Dapr appcallback service](https://github.com/dapr/dapr/blob/master/dapr/proto/runtime/v1/appcallback.proto) +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](https://github.com/dapr/dapr/blob/master/dapr/proto/runtime/v1/appcallback.proto) ## Configuring Dapr to communicate with an app via gRPC -### Self hosted +{{< tabs "Self-hosted" Kubernetes >}} + + +{{% codetab %}} When running in self hosted mode, use the `--app-protocol` flag to tell Dapr to use gRPC to talk to the app: @@ -25,8 +26,10 @@ dapr run --app-protocol grpc --app-port 5005 node app.js ``` This tells Dapr to communicate with your app via gRPC over port `5005`. +{{% /codetab %}} -### Kubernetes + +{{% codetab %}} On Kubernetes, set the following annotations in your deployment YAML: @@ -52,5 +55,13 @@ spec: dapr.io/app-id: "myapp" dapr.io/app-protocol: "grpc" dapr.io/app-port: "5005" -... -``` \ No newline at end of file +#... +``` + +{{% /codetab %}} + +{{< /tabs >}} + +## Next steps + +{{< button text="Handle large HTTP header sizes" page="increase-read-buffer-size" >}} \ No newline at end of file diff --git a/daprdocs/content/en/operations/configuration/increase-read-buffer-size.md b/daprdocs/content/en/operations/configuration/increase-read-buffer-size.md index a8528e09bad..9fcb80c4fb0 100644 --- a/daprdocs/content/en/operations/configuration/increase-read-buffer-size.md +++ b/daprdocs/content/en/operations/configuration/increase-read-buffer-size.md @@ -1,20 +1,23 @@ --- type: docs -title: "How-To: Handle large http header size" +title: "How-To: Handle large HTTP header size" linkTitle: "HTTP header size" weight: 6000 -description: "Configure a larger http read buffer size" +description: "Configure a larger HTTP read buffer size" --- -Dapr has a default limit of 4KB for the http header read buffer size. When sending http headers that are bigger than the default 4KB, you can increase this value. Otherwise, you may encounter a `Too big request header` service invocation error. You can change the http header size by using the `dapr.io/http-read-buffer-size` annotation or `--dapr-http-read-buffer-size` flag when using the CLI. - +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. {{< tabs Self-hosted Kubernetes >}} + {{% codetab %}} -When running in self hosted mode, use the `--dapr-http-read-buffer-size` flag to configure Dapr to use non-default http header size: +When running in self-hosted mode, use the `--dapr-http-read-buffer-size` flag to configure Dapr to use non-default http header size: ```bash dapr run --dapr-http-read-buffer-size 16 node app.js @@ -23,10 +26,11 @@ This tells Dapr to set maximum read buffer size to `16` KB. {{% /codetab %}} - + {{% codetab %}} On Kubernetes, set the following annotations in your deployment YAML: + ```yaml apiVersion: apps/v1 kind: Deployment @@ -49,7 +53,7 @@ spec: dapr.io/app-id: "myapp" dapr.io/app-port: "8000" dapr.io/http-read-buffer-size: "16" -... +#... ``` {{% /codetab %}} @@ -57,4 +61,8 @@ spec: {{< /tabs >}} ## Related links -- [Dapr Kubernetes pod annotations spec]({{< ref arguments-annotations-overview.md >}}) +[Dapr Kubernetes pod annotations spec]({{< ref arguments-annotations-overview.md >}}) + +## Next steps + +{{< button text="Handle large HTTP body requests" page="increase-request-size" >}} diff --git a/daprdocs/content/en/operations/configuration/increase-request-size.md b/daprdocs/content/en/operations/configuration/increase-request-size.md index 2faadecf085..25461e3e83f 100644 --- a/daprdocs/content/en/operations/configuration/increase-request-size.md +++ b/daprdocs/content/en/operations/configuration/increase-request-size.md @@ -6,15 +6,16 @@ weight: 6000 description: "Configure http requests that are bigger than 4 MB" --- -By default Dapr has a limit for the request body size which is set to 4 MB, however you can change this by defining `dapr.io/http-max-request-size` annotation or `--dapr-http-max-request-size` flag. - - +By default, Dapr has a limit for the request body size, set to 4MB. You can change this by defining: +- The `dapr.io/http-max-request-size` annotation, or +- The `--dapr-http-max-request-size` flag. {{< tabs Self-hosted Kubernetes >}} + {{% codetab %}} -When running in self hosted mode, use the `--dapr-http-max-request-size` flag to configure Dapr to use non-default request body size: +When running in self-hosted mode, use the `--dapr-http-max-request-size` flag to configure Dapr to use non-default request body size: ```bash dapr run --dapr-http-max-request-size 16 node app.js @@ -23,10 +24,11 @@ This tells Dapr to set maximum request body size to `16` MB. {{% /codetab %}} - + {{% codetab %}} On Kubernetes, set the following annotations in your deployment YAML: + ```yaml apiVersion: apps/v1 kind: Deployment @@ -49,7 +51,7 @@ spec: dapr.io/app-id: "myapp" dapr.io/app-port: "8000" dapr.io/http-max-request-size: "16" -... +#... ``` {{% /codetab %}} @@ -57,4 +59,9 @@ spec: {{< /tabs >}} ## Related links -- [Dapr Kubernetes pod annotations spec]({{< ref arguments-annotations-overview.md >}}) + +[Dapr Kubernetes pod annotations spec]({{< ref arguments-annotations-overview.md >}}) + +## Next steps + +{{< button text="Install sidecar certificates" page="install-certificates" >}} \ No newline at end of file diff --git a/daprdocs/content/en/operations/configuration/install-certificates.md b/daprdocs/content/en/operations/configuration/install-certificates.md index 071753ef93d..7c2b79f8c86 100644 --- a/daprdocs/content/en/operations/configuration/install-certificates.md +++ b/daprdocs/content/en/operations/configuration/install-certificates.md @@ -6,20 +6,26 @@ weight: 6500 description: "Configure the Dapr sidecar container to trust certificates" --- -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. For example, using an HTTP binding or configuring an outbound proxy for the sidecar. Both certificate authority (CA) certificates and leaf certificates are supported. +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. {{< tabs Self-hosted Kubernetes >}} + {{% codetab %}} -When the sidecar is not running inside a container, certificates must be directly installed on the host operating system. +You can make the following configurations when the sidecar is running as a container. + +1. Configure certificates to be available to the sidecar container using volume mounts. +1. Point the environment variable `SSL_CERT_DIR` in the sidecar container to the directory containing the certificates. + +> **Note:** For Windows containers, make sure the container is running with administrator privileges so it can install the certificates. -When the sidecar is running as a container: -1. Certificates must be available to the sidecar container. This can be configured using volume mounts. -1. The environment variable `SSL_CERT_DIR` must be set in the sidecar container, pointing to the directory containing the certificates. -1. For Windows containers, the container needs to run with administrator privileges to be able to install the certificates. +The following example uses Docker Compose to install certificates (present locally in the `./certificates` directory) in the sidecar container: -Below is an example that uses Docker Compose to install certificates (present locally in the `./certificates` directory) in the sidecar container: ```yaml version: '3' services: @@ -39,16 +45,22 @@ services: # user: ContainerAdministrator ``` -{{% /codetab %}} +> **Note:** When the sidecar is not running inside a container, certificates must be directly installed on the host operating system. +{{% /codetab %}} + {{% codetab %}} On Kubernetes: -1. Certificates must be available to the sidecar container using a volume mount. -1. The environment variable `SSL_CERT_DIR` must be set in the sidecar container, pointing to the directory containing the certificates. -The YAML below is an example of a deployment that attaches a pod volume to the sidecar, and sets `SSL_CERT_DIR` to install the certificates. +1. Configure certificates to be available to the sidecar container using a volume mount. +1. Point the environment variable `SSL_CERT_DIR` in the sidecar container to the directory containing the certificates. + +The following example YAML shows a deployment that: +- Attaches a pod volume to the sidecar +- Sets `SSL_CERT_DIR` to install the certificates + ```yaml apiVersion: apps/v1 kind: Deployment @@ -77,23 +89,21 @@ spec: - name: certificates-vol hostPath: path: /certificates -... +#... ``` -**Note**: When using Windows containers, the sidecar container is started with admin privileges, which is required to install the certificates. This does not apply to Linux containers. +> **Note**: When using Windows containers, the sidecar container is started with admin privileges, which is required to install the certificates. This does not apply to Linux containers. {{% /codetab %}} {{< /tabs >}} -
- -All the certificates in the directory pointed by `SSL_CERT_DIR` are installed. +After following these steps, all the certificates in the directory pointed by `SSL_CERT_DIR` are installed. -1. On Linux containers, all the certificate extensions supported by OpenSSL are supported. For more information, see https://www.openssl.org/docs/man1.1.1/man1/openssl-rehash.html -1. On Windows container, all the certificate extensions supported by certoc.exe are supported. For more information, see certoc.exe present in [Windows Server Core](https://hub.docker.com/_/microsoft-windows-servercore) +- **On Linux containers:** All the certificate extensions supported by OpenSSL are supported. [Learn more.](https://www.openssl.org/docs/man1.1.1/man1/openssl-rehash.html) +- **On Windows container:** All the certificate extensions supported by `certoc.exe` are supported. [See certoc.exe present in Windows Server Core](https://hub.docker.com/_/microsoft-windows-servercore). -## Example +## Demo Watch the demo on using installing SSL certificates and securely using the HTTP binding in community call 64: @@ -106,3 +116,7 @@ Watch the demo on using installing SSL certificates and securely using the HTTP - [HTTP binding spec]({{< ref http.md >}}) - [(Kubernetes) How-to: Mount Pod volumes to the Dapr sidecar]({{< ref kubernetes-volume-mounts.md >}}) - [Dapr Kubernetes pod annotations spec]({{< ref arguments-annotations-overview.md >}}) + +## Next steps + +{{< button text="Enable preview features" page="preview-features" >}} \ No newline at end of file diff --git a/daprdocs/content/en/operations/configuration/invoke-allowlist.md b/daprdocs/content/en/operations/configuration/invoke-allowlist.md index 725c8308491..f9afe029926 100644 --- a/daprdocs/content/en/operations/configuration/invoke-allowlist.md +++ b/daprdocs/content/en/operations/configuration/invoke-allowlist.md @@ -3,71 +3,87 @@ type: docs title: "How-To: Apply access control list configuration for service invocation" linkTitle: "Service Invocation access control" weight: 4000 -description: "Restrict what operations *calling* applications can perform, via service invocation, on the *called* application" +description: "Restrict what operations calling applications can perform" --- -Access control enables the configuration of policies that restrict what operations *calling* applications can perform, via service invocation, on the *called* application. To limit access to a called applications from specific operations and HTTP verbs from the calling applications, you can define an access control policy specification in configuration. +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 be applied to Dapr sidecar for the *called* application. Example access policies are shown below and access to the called app is based on the matched policy action. You can provide a default global action for all calling applications and if no access control policy is specified, the default behavior is to allow all calling applications to access to the called app. +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. -## Concepts +You can provide a default global action for all calling applications. If no access control policy is specified, the default behavior is to allow all calling applications to access to the called app. -**TrustDomain** - A "trust domain" is a logical group to manage trust relationships. Every application is assigned a trust domain which can be specified in the access control list policy spec. If no policy spec is defined or an empty trust domain is specified, then a default value "public" is used. This trust domain is used to generate the identity of the application in the TLS cert. +[See examples of access policies.](#example-scenarios) -**App Identity** - Dapr requests the sentry service to generate a [SPIFFE](https://spiffe.io/) id for all applications and this id is attached in the TLS cert. The SPIFFE id is of the format: `**spiffe://\/ns/\/\**`. For matching policies, the trust domain, namespace and app ID values of the calling app are extracted from the SPIFFE id in the TLS cert of the calling app. These values are matched against the trust domain, namespace and app ID values specified in the policy spec. If all three of these match, then more specific policies are further matched. +## Terminology + +### `trustDomain` + +A "trust domain" is a logical group that manages trust relationships. Every application is assigned a trust domain, which can be specified in the access control list policy spec. If no policy spec is defined or an empty trust domain is specified, then a default value "public" is used. This trust domain is used to generate the identity of the application in the TLS cert. + +### App Identity + +Dapr requests the sentry service to generate a [SPIFFE](https://spiffe.io/) ID for all applications. This ID is attached in the TLS cert. + +The SPIFFE ID is of the format: `**spiffe://\/ns/\/\**`. + +For matching policies, the trust domain, namespace, and app ID values of the calling app are extracted from the SPIFFE ID in the TLS cert of the calling app. These values are matched against the trust domain, namespace, and app ID values specified in the policy spec. If all three of these match, then more specific policies are further matched. ## Configuration properties -The following tables lists the different properties for access control, policies and operations: +The following tables lists the different properties for access control, policies, and operations: ### Access Control | Property | Type | Description | |---------------|--------|-------------| -| defaultAction | string | Global default action when no other policy is matched -| trustDomain | string | Trust domain assigned to the application. Default is "public". -| policies | string | Policies to determine what operations the calling app can do on the called app +| `defaultAction` | string | Global default action when no other policy is matched +| `trustDomain` | string | Trust domain assigned to the application. Default is "public". +| `policies` | string | Policies to determine what operations the calling app can do on the called app ### Policies | Property | Type | Description | |---------------|--------|-------------| -| app | string | AppId of the calling app to allow/deny service invocation from -| namespace | string | Namespace value that needs to be matched with the namespace of the calling app -| trustDomain | string | Trust domain that needs to be matched with the trust domain of the calling app. Default is "public" -| defaultAction | string | App level default action in case the app is found but no specific operation is matched -| operations | string | operations that are allowed from the calling app +| `app` | string | AppId of the calling app to allow/deny service invocation from +| `namespace` | string | Namespace value that needs to be matched with the namespace of the calling app +| `trustDomain` | string | Trust domain that needs to be matched with the trust domain of the calling app. Default is "public" +| `defaultAction` | string | App level default action in case the app is found but no specific operation is matched +| `operations` | string | operations that are allowed from the calling app ### Operations | Property | Type | Description | | -------- | ------ | ------------------------------------------------------------ | -| name | string | Path name of the operations allowed on the called app. Wildcard "\*" can be used in a path to match. Wildcard "\**" can be used to match under multiple paths. | -| httpVerb | list | List specific http verbs that can be used by the calling app. Wildcard "\*" can be used to match any http verb. Unused for grpc invocation. | -| action | string | Access modifier. Accepted values "allow" (default) or "deny" | +| `name` | string | Path name of the operations allowed on the called app. Wildcard "\*" can be used in a path to match. Wildcard "\**" can be used to match under multiple paths. | +| `httpVerb` | list | List specific http verbs that can be used by the calling app. Wildcard "\*" can be used to match any http verb. Unused for grpc invocation. | +| `action` | string | Access modifier. Accepted values "allow" (default) or "deny" | ## Policy rules -1. If no access policy is specified, the default behavior is to allow all apps to access to all methods on the called app -2. If no global default action is specified and no app specific policies defined, the empty access policy is treated like no access policy specified and the default behavior is to allow all apps to access to all methods on the called app. -3. If no global default action is specified but some app specific policies have been defined, then we resort to a more secure option of assuming the global default action to deny access to all methods on the called app. -4. If an access policy is defined and if the incoming app credentials cannot be verified, then the global default action takes effect. -5. If either the trust domain or namespace of the incoming app do not match the values specified in the app policy, the app policy is ignored and the global default action takes effect. +1. If no access policy is specified, the default behavior is to allow all apps to access to all methods on the called app. +1. If no global default action is specified and no app specific policies defined, the empty access policy is treated like no access policy is specified. The default behavior is to allow all apps to access to all methods on the called app. +1. If no global default action is specified but some app specific policies have been defined, then we resort to a more secure option of assuming the global default action to deny access to all methods on the called app. +1. If an access policy is defined and if the incoming app credentials cannot be verified, then the global default action takes effect. +1. If either the trust domain or namespace of the incoming app do not match the values specified in the app policy, the app policy is ignored and the global default action takes effect. ## Policy priority The action corresponding to the most specific policy matched takes effect as ordered below: 1. Specific HTTP verbs in the case of HTTP or the operation level action in the case of GRPC. -2. The default action at the app level -3. The default action at the global level +1. The default action at the app level +1. The default action at the global level ## Example scenarios Below are some example scenarios for using access control list for service invocation. See [configuration guidance]({{< ref "configuration-concept.md" >}}) to understand the available configuration settings for an application sidecar. -Scenario 1: Deny access to all apps except where trustDomain = public, namespace = default, appId = app1 +### Scenario 1: -With this configuration, all calling methods with appId = app1 are allowed and all other invocation requests from other applications are denied +Deny access to all apps except where `trustDomain` = `public`, `namespace` = `default`, `appId` = `app1` + +With this configuration, all calling methods with `appId` = `app1` are allowed. All other invocation requests from other applications are denied. ```yaml apiVersion: dapr.io/v1alpha1 @@ -85,9 +101,11 @@ spec: namespace: "default" ``` -Scenario 2: Deny access to all apps except trustDomain = public, namespace = default, appId = app1, operation = op1 +### Scenario 2: + +Deny access to all apps except `trustDomain` = `public`, `namespace` = `default`, `appId` = `app1`, `operation` = `op1` -With this configuration, only method op1 from appId = app1 is allowed and all other method requests from all other apps, including other methods on app1, are denied +With this configuration, only the method `op1` from `appId` = `app1` is allowed. All other method requests from all other apps, including other methods on `app1`, are denied. ```yaml apiVersion: dapr.io/v1alpha1 @@ -109,12 +127,16 @@ spec: action: allow ``` -Scenario 3: Deny access to all apps except when a specific verb for HTTP and operation for GRPC is matched +### Scenario 3: + +Deny access to all apps except when a specific verb for HTTP and operation for GRPC is matched + +With this configuration, only the scenarios below are allowed access. All other method requests from all other apps, including other methods on `app1` or `app2`, are denied. + +- `trustDomain` = `public`, `namespace` = `default`, `appID` = `app1`, `operation` = `op1`, `httpVerb` = `POST`/`PUT` +- `trustDomain` = `"myDomain"`, `namespace` = `"ns1"`, `appID` = `app2`, `operation` = `op2` and application protocol is GRPC -With this configuration, the only scenarios below are allowed access and and all other method requests from all other apps, including other methods on app1 or app2, are denied -* trustDomain = public, namespace = default, appID = app1, operation = op1, http verb = POST/PUT -* trustDomain = "myDomain", namespace = "ns1", appID = app2, operation = op2 and application protocol is GRPC -, only HTTP verbs POST/PUT on method op1 from appId = app1 are allowed and all other method requests from all other apps, including other methods on app1, are denied +Only the `httpVerb` `POST`/`PUT` on method `op1` from `appId` = `app1` are allowe. All other method requests from all other apps, including other methods on `app1`, are denied. ```yaml apiVersion: dapr.io/v1alpha1 @@ -143,7 +165,9 @@ spec: action: allow ``` -Scenario 4: Allow access to all methods except trustDomain = public, namespace = default, appId = app1, operation = /op1/*, all http verbs +### Scenario 4: + +Allow access to all methods except `trustDomain` = `public`, `namespace` = `default`, `appId` = `app1`, `operation` = `/op1/*`, all `httpVerb` ```yaml apiVersion: dapr.io/v1alpha1 @@ -165,9 +189,11 @@ spec: action: deny ``` -Scenario 5: Allow access to all methods for trustDomain = public, namespace = ns1, appId = app1 and deny access to all methods for trustDomain = public, namespace = ns2, appId = app1 +### Scenario 5: + +Allow access to all methods for `trustDomain` = `public`, `namespace` = `ns1`, `appId` = `app1` and deny access to all methods for `trustDomain` = `public`, `namespace` = `ns2`, `appId` = `app1` -This scenario shows how applications with the same app ID but belonging to different namespaces can be specified +This scenario shows how applications with the same app ID while belonging to different namespaces can be specified. ```yaml apiVersion: dapr.io/v1alpha1 @@ -189,7 +215,9 @@ spec: namespace: "ns2" ``` -Scenario 6: Allow access to all methods except trustDomain = public, namespace = default, appId = app1, operation = /op1/**/a, all http verbs +### Scenario 6: + +Allow access to all methods except `trustDomain` = `public`, `namespace` = `default`, `appId` = `app1`, `operation` = `/op1/**/a`, all `httpVerb` ```yaml apiVersion: dapr.io/v1alpha1 @@ -211,14 +239,15 @@ spec: action: deny ``` -## Hello world examples +## "hello world" examples -These examples show how to apply access control to the [hello world](https://github.com/dapr/quickstarts#quickstarts) quickstart samples where a python app invokes a node.js app. -Access control lists rely on the Dapr [Sentry service]({{< ref "security-concept.md" >}}) to generate the TLS certificates with a SPIFFE id for authentication, which means the Sentry service either has to be running locally or deployed to your hosting environment such as a Kubernetes cluster. +In these examples, you learn how to apply access control to the [hello world](https://github.com/dapr/quickstarts/tree/master/tutorials) tutorials. -The nodeappconfig example below shows how to **deny** access to the `neworder` method from the `pythonapp`, where the python app is in the `myDomain` trust domain and `default` namespace. The nodeapp is in the `public` trust domain. +Access control lists rely on the Dapr [Sentry service]({{< ref "security-concept.md" >}}) to generate the TLS certificates with a SPIFFE ID for authentication. This means the Sentry service either has to be running locally or deployed to your hosting environment, such as a Kubernetes cluster. -**nodeappconfig.yaml** +The `nodeappconfig` example below shows how to **deny** access to the `neworder` method from the `pythonapp`, where the Python app is in the `myDomain` trust domain and `default` namespace. The Node.js app is in the `public` trust domain. + +### nodeappconfig.yaml ```yaml apiVersion: dapr.io/v1alpha1 @@ -242,7 +271,7 @@ spec: action: deny ``` -**pythonappconfig.yaml** +### pythonappconfig.yaml ```yaml apiVersion: dapr.io/v1alpha1 @@ -258,95 +287,119 @@ spec: ``` ### Self-hosted mode -This example uses the [hello world](https://github.com/dapr/quickstarts/tree/master/tutorials/hello-world/README.md) quickstart. -The following steps run the Sentry service locally with mTLS enabled, set up necessary environment variables to access certificates, and then launch both the node app and python app each referencing the Sentry service to apply the ACLs. +When walking through this tutorial, you: +- Run the Sentry service locally with mTLS enabled +- Set up necessary environment variables to access certificates +- Launch both the Node app and Python app each referencing the Sentry service to apply the ACLs + +#### Prerequisites + +- Become familiar with running [Sentry service in self-hosted mode]({{< ref "mtls.md" >}}) with mTLS enabled +- Clone the [hello world](https://github.com/dapr/quickstarts/tree/master/tutorials/hello-world/README.md) tutorial - 1. Follow these steps to run the [Sentry service in self-hosted mode]({{< ref "mtls.md" >}}) with mTLS enabled +#### Run the Node.js app - 2. In a command prompt, set these environment variables: +1. In a command prompt, set these environment variables: {{< tabs "Linux/MacOS" Windows >}} {{% codetab %}} - ```bash - export DAPR_TRUST_ANCHORS=`cat $HOME/.dapr/certs/ca.crt` - export DAPR_CERT_CHAIN=`cat $HOME/.dapr/certs/issuer.crt` - export DAPR_CERT_KEY=`cat $HOME/.dapr/certs/issuer.key` - export NAMESPACE=default - ``` + + ```bash + export DAPR_TRUST_ANCHORS=`cat $HOME/.dapr/certs/ca.crt` + export DAPR_CERT_CHAIN=`cat $HOME/.dapr/certs/issuer.crt` + export DAPR_CERT_KEY=`cat $HOME/.dapr/certs/issuer.key` + export NAMESPACE=default + ``` {{% /codetab %}} - {{% codetab %}} - ```powershell - $env:DAPR_TRUST_ANCHORS=$(Get-Content -raw $env:USERPROFILE\.dapr\certs\ca.crt) - $env:DAPR_CERT_CHAIN=$(Get-Content -raw $env:USERPROFILE\.dapr\certs\issuer.crt) - $env:DAPR_CERT_KEY=$(Get-Content -raw $env:USERPROFILE\.dapr\certs\issuer.key) - $env:NAMESPACE="default" - ``` + {{% codetab %}} + + ```powershell + $env:DAPR_TRUST_ANCHORS=$(Get-Content -raw $env:USERPROFILE\.dapr\certs\ca.crt) + $env:DAPR_CERT_CHAIN=$(Get-Content -raw $env:USERPROFILE\.dapr\certs\issuer.crt) + $env:DAPR_CERT_KEY=$(Get-Content -raw $env:USERPROFILE\.dapr\certs\issuer.key) + $env:NAMESPACE="default" + ``` {{% /codetab %}} {{< /tabs >}} -3. Run daprd to launch a Dapr sidecar for the node.js app with mTLS enabled, referencing the local Sentry service: +1. Run daprd to launch a Dapr sidecar for the Node.js app with mTLS enabled, referencing the local Sentry service: ```bash daprd --app-id nodeapp --dapr-grpc-port 50002 -dapr-http-port 3501 --log-level debug --app-port 3000 --enable-mtls --sentry-address localhost:50001 --config nodeappconfig.yaml ``` -4. Run the node app in a separate command prompt: +1. Run the Node.js app in a separate command prompt: ```bash node app.js ``` -5. In another command prompt, set these environment variables: +#### Run the Python app + +1. In another command prompt, set these environment variables: {{< tabs "Linux/MacOS" Windows >}} {{% codetab %}} - ```bash - export DAPR_TRUST_ANCHORS=`cat $HOME/.dapr/certs/ca.crt` - export DAPR_CERT_CHAIN=`cat $HOME/.dapr/certs/issuer.crt` - export DAPR_CERT_KEY=`cat $HOME/.dapr/certs/issuer.key` - export NAMESPACE=default - ``` + + ```bash + export DAPR_TRUST_ANCHORS=`cat $HOME/.dapr/certs/ca.crt` + export DAPR_CERT_CHAIN=`cat $HOME/.dapr/certs/issuer.crt` + export DAPR_CERT_KEY=`cat $HOME/.dapr/certs/issuer.key` + export NAMESPACE=default + ``` {{% /codetab %}} {{% codetab %}} + ```powershell $env:DAPR_TRUST_ANCHORS=$(Get-Content -raw $env:USERPROFILE\.dapr\certs\ca.crt) $env:DAPR_CERT_CHAIN=$(Get-Content -raw $env:USERPROFILE\.dapr\certs\issuer.crt) $env:DAPR_CERT_KEY=$(Get-Content -raw $env:USERPROFILE\.dapr\certs\issuer.key) $env:NAMESPACE="default" - ``` + ``` + {{% /codetab %}} {{< /tabs >}} -6. Run daprd to launch a Dapr sidecar for the python app with mTLS enabled, referencing the local Sentry service: +1. Run daprd to launch a Dapr sidecar for the Python app with mTLS enabled, referencing the local Sentry service: ```bash daprd --app-id pythonapp --dapr-grpc-port 50003 --metrics-port 9092 --log-level debug --enable-mtls --sentry-address localhost:50001 --config pythonappconfig.yaml ``` - -7. Run the python app in a separate command prompt: +1. Run the Python app in a separate command prompt: ```bash python app.py ``` -8. You should see the calls to the node app fail in the python app command prompt based due to the **deny** operation action in the nodeappconfig file. Change this action to **allow** and re-run the apps and you should then see this call succeed. +You should see the calls to the Node.js app fail in the Python app command prompt, due to the **deny** operation action in the `nodeappconfig` file. Change this action to **allow** and re-run the apps to see this call succeed. ### Kubernetes mode -This example uses the [hello kubernetes](https://github.com/dapr/quickstarts/tree/master/tutorials/hello-kubernetes/README.md) quickstart. -You can create and apply the above configuration files `nodeappconfig.yaml` and `pythonappconfig.yaml` as described in the [configuration]({{< ref "configuration-concept.md" >}}) to the Kubernetes deployments. +#### Prerequisites + +- Become familiar with running [Sentry service in self-hosted mode]({{< ref "mtls.md" >}}) with mTLS enabled +- Clone the [hello world](https://github.com/dapr/quickstarts/tree/master/tutorials/hello-world/README.md) tutorial + +#### Configure the Node.js and Python apps + +You can create and apply the above [`nodeappconfig.yaml`](#nodeappconfigyaml) and [`pythonappconfig.yaml`](#pythonappconfigyaml) configuration files, as described in the [configuration]({{< ref "configuration-concept.md" >}}). + +For example, the Kubernetes Deployment below is how the Python app is deployed to Kubernetes in the default namespace with this `pythonappconfig` configuration file. -For example, below is how the pythonapp is deployed to Kubernetes in the default namespace with this pythonappconfig configuration file. -Do the same for the nodeapp deployment and then look at the logs for the pythonapp to see the calls fail due to the **deny** operation action set in the nodeappconfig file. Change this action to **allow** and re-deploy the apps and you should then see this call succeed. +Do the same for the Node.js deployment and look at the logs for the Python app to see the calls fail due to the **deny** operation action set in the `nodeappconfig` file. + +Change this action to **allow** and re-deploy the apps to see this call succeed. + +##### Deployment YAML example ```yaml apiVersion: apps/v1 @@ -375,9 +428,14 @@ spec: image: dapriosamples/hello-k8s-python:edge ``` -## Community call demo +## Demo + Watch this [video](https://youtu.be/j99RN_nxExA?t=1108) on how to apply access control list for service invocation.
-
\ No newline at end of file + + +## Next steps + +{{< button text="Dapr APIs allow list" page="api-allowlist" >}} \ No newline at end of file diff --git a/daprdocs/content/en/operations/configuration/preview-features.md b/daprdocs/content/en/operations/configuration/preview-features.md index 387ba0fa6b9..1e442dcc587 100644 --- a/daprdocs/content/en/operations/configuration/preview-features.md +++ b/daprdocs/content/en/operations/configuration/preview-features.md @@ -6,23 +6,21 @@ weight: 7000 description: "How to specify and enable preview features" --- -## Overview -Preview features in Dapr are considered experimental when they are first released. These preview features require explicit opt-in in order to be used. The opt-in is specified in Dapr's configuration. +[Preview features]({{< ref support-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. -### Preview features -The current list of preview features can be found [here]({{}}). - ## 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 +|`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: ```yaml @@ -42,7 +40,11 @@ spec: enabled: true ``` -### Standalone +{{< tabs Self-hosted Kubernetes >}} + + +{{% codetab %}} + To enable preview features when running Dapr locally, either update the default configuration or specify a separate config file using `dapr run`. The default Dapr config is created when you run `dapr init`, and is located at: @@ -55,8 +57,11 @@ Alternately, you can update preview features on all apps run locally by specifyi dapr run --app-id myApp --config ./previewConfig.yaml ./app ``` +{{% /codetab %}} + + +{{% codetab %}} -### Kubernetes In Kubernetes mode, the configuration must be provided via a configuration component. Using the same configuration as above, apply it via `kubectl`: ```bash @@ -94,3 +99,11 @@ spec: - containerPort: 3000 imagePullPolicy: Always ``` + +{{% /codetab %}} + +{{< /tabs >}} + +## Next steps + +{{< button text="Configuration schema" page="configuration-schema" >}} \ No newline at end of file diff --git a/daprdocs/content/en/operations/configuration/secret-scope.md b/daprdocs/content/en/operations/configuration/secret-scope.md index 39796447268..5e129e1d7f9 100644 --- a/daprdocs/content/en/operations/configuration/secret-scope.md +++ b/daprdocs/content/en/operations/configuration/secret-scope.md @@ -3,12 +3,14 @@ type: docs title: "How-To: Limit the secrets that can be read from secret stores" linkTitle: "Limit secret store access" weight: 3000 -description: "To limit the secrets to which the Dapr application has access, users can define secret scopes by augmenting existing configuration resource with restrictive permissions." +description: "Define secret scopes by augmenting the existing configuration resource with restrictive permissions." --- -In addition to scoping which applications can access a given component, for example a secret store component (see [Scoping components]({{< ref "component-scopes.md">}})), a named secret store component itself can be scoped to one or more secrets for an application. By defining `allowedSecrets` and/or `deniedSecrets` list, applications can be restricted to access only specific secrets. +In addition to [scoping which applications can access a given component]({{< ref "component-scopes.md">}}), you can also scop 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. -Follow [these instructions]({{< ref "configuration-overview.md" >}}) to define a configuration resource. +For more information about configuring a Configuration resource: +- [Configuration overview]({{< ref configuration-overview.md >}}) +- [Configuration schema]({{< ref configuration-schema.md >}}) ## Configure secrets access @@ -38,38 +40,44 @@ When an `allowedSecrets` list is present with at least one element, only those s ## Permission priority -The `allowedSecrets` and `deniedSecrets` list values take priorty over the `defaultAccess`. +The `allowedSecrets` and `deniedSecrets` list values take priorty over the `defaultAccess`. See how this works in the following example scenarios: -| Scenarios | defaultAccess | allowedSecrets | deniedSecrets | permission -|----- | ------- | -----------| ----------| ------------ -| 1 - Only default access | deny/allow | empty | empty | deny/allow -| 2 - Default deny with allowed list | deny | ["s1"] | empty | only "s1" can be accessed -| 3 - Default allow with denied list | allow | empty | ["s1"] | only "s1" cannot be accessed -| 4 - Default allow with allowed list | allow | ["s1"] | empty | only "s1" can be accessed -| 5 - Default deny with denied list | deny | empty | ["s1"] | deny -| 6 - Default deny/allow with both lists | deny/allow | ["s1"] | ["s2"] | only "s1" can be accessed +| | Scenarios | `defaultAccess` | `allowedSecrets` | `deniedSecrets` | `permission` +|--| ----- | ------- | -----------| ----------| ------------ +| 1 | Only default access | `deny`/`allow` | empty | empty | `deny`/`allow` +| 2 | Default deny with allowed list | `deny` | [`"s1"`] | empty | only `"s1"` can be accessed +| 3 | Default allow with denied list | `allow` | empty | [`"s1"`] | only `"s1"` cannot be accessed +| 4 | Default allow with allowed list | `allow` | [`"s1"`] | empty | only `"s1"` can be accessed +| 5 | Default deny with denied list | `deny` | empty | [`"s1"`] | `deny` +| 6 | Default deny/allow with both lists | `deny`/`allow` | [`"s1"`] | [`"s2"`] | only `"s1"` can be accessed ## Examples -### Scenario 1 : Deny access to all secrets for a secret store +### Scenario 1: Deny access to all secrets for a secret store -In Kubernetes cluster, the native Kubernetes secret store is added to Dapr application by default. In some scenarios it may be necessary to deny access to Dapr secrets for a given application. To add this configuration follow the steps below: +In a Kubernetes cluster, the native Kubernetes secret store is added to your Dapr application by default. In some scenarios, it may be necessary to deny access to Dapr secrets for a given application. To add this configuration: -Define the following `appconfig.yaml` and apply it to the Kubernetes cluster using the command `kubectl apply -f appconfig.yaml`. +1. Define the following `appconfig.yaml`. -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Configuration -metadata: - name: appconfig -spec: - secrets: - scopes: - - storeName: kubernetes - defaultAccess: deny -``` + ```yaml + apiVersion: dapr.io/v1alpha1 + kind: Configuration + metadata: + name: appconfig + spec: + secrets: + scopes: + - storeName: kubernetes + defaultAccess: deny + ``` + +1. Apply it to the Kubernetes cluster using the following command: -For applications that need to be denied access to the Kubernetes secret store, follow [these instructions]({{< ref kubernetes-overview >}}), and add the following annotation to the application pod. + ```bash + kubectl apply -f appconfig.yaml`. + ``` + +For applications that you need to deny access to the Kubernetes secret store, follow [the Kubernetes instructions]({{< ref kubernetes-overview >}}), adding the following annotation to the application pod. ```yaml dapr.io/config: appconfig @@ -77,7 +85,7 @@ dapr.io/config: appconfig With this defined, the application no longer has access to Kubernetes secret store. -### Scenario 2 : Allow access to only certain secrets in a secret store +### Scenario 2: Allow access to only certain secrets in a secret store To allow a Dapr application to have access to only certain secrets, define the following `config.yaml`: @@ -94,7 +102,7 @@ spec: allowedSecrets: ["secret1", "secret2"] ``` -This example defines configuration for secret store named vault. The default access to the secret store is `deny`, whereas some secrets are accessible by the application based on the `allowedSecrets` list. Follow [these instructions]({{< ref configuration-overview.md >}}) to apply configuration to the sidecar. +This example defines configuration for secret store named `vault`. The default access to the secret store is `deny`. Meanwhile, some secrets are accessible by the application based on the `allowedSecrets` list. Follow [the Sidecar configuration instructions]({{< ref "configuration-overview.md#sidecar-configuration" >}}) to apply configuration to the sidecar. ### Scenario 3: Deny access to certain sensitive secrets in a secret store @@ -113,4 +121,8 @@ spec: deniedSecrets: ["secret1", "secret2"] ``` -The above configuration explicitly denies access to `secret1` and `secret2` from the secret store named vault while allowing access to all other secrets. Follow [these instructions]({{< ref configuration-overview.md >}}) to apply configuration to the sidecar. +This configuration explicitly denies access to `secret1` and `secret2` from the secret store named `vault,` while allowing access to all other secrets. Follow [the Sidecar configuration instructions]({{< ref "configuration-overview.md#sidecar-configuration" >}}) to apply configuration to the sidecar. + +## Next steps + +{{< button text="Service invocation access control" page="invoke-allowlist" >}} diff --git a/daprdocs/content/en/reference/arguments-annotations-overview.md b/daprdocs/content/en/reference/arguments-annotations-overview.md index 35986bfffc5..a630519b79d 100644 --- a/daprdocs/content/en/reference/arguments-annotations-overview.md +++ b/daprdocs/content/en/reference/arguments-annotations-overview.md @@ -32,7 +32,7 @@ This table is meant to help users understand the equivalent options for running | `--log-as-json` | not supported | | `dapr.io/log-as-json` | Setting this parameter to `true` outputs [logs in JSON format]({{< ref logs >}}). Default is `false` | | `--log-level` | `--log-level` | | `dapr.io/log-level` | Sets the [log level]({{< ref logs-troubleshooting >}}) 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]({{< ref "api-logs-troubleshooting.md#configuring-api-logging-in-kubernetes" >}}) for the Dapr sidecar | -| `--app-max-concurrency` | `--app-max-concurrency` | | `dapr.io/app-max-concurrency` | Limit the [concurrency of your application]({{< ref "control-concurrency.md#setting-app-max-concurrency" >}}). A valid value is any number larger than `0`| +| `--app-max-concurrency` | `--app-max-concurrency` | | `dapr.io/app-max-concurrency` | Limit the [concurrency of your application]({{< ref "control-concurrency.md#setting-app-max-concurrency" >}}). 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.]({{< ref hosting >}}) | | `--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` |