diff --git a/daprdocs/content/en/concepts/dapr-services/sidecar.md b/daprdocs/content/en/concepts/dapr-services/sidecar.md index e50ce3675..473f001c9 100644 --- a/daprdocs/content/en/concepts/dapr-services/sidecar.md +++ b/daprdocs/content/en/concepts/dapr-services/sidecar.md @@ -49,10 +49,10 @@ For a detailed list of all available arguments run `daprd --help` or see this [t daprd --app-id --app-port 5000 ``` -3. If you are using several custom components and want to specify the location of the component definition files, use the `--components-path` argument: +3. If you are using several custom resources and want to specify the location of the resource definition files, use the `--resources-path` argument: ```bash - daprd --app-id myapp --components-path + daprd --app-id myapp --resources-path ``` 4. Enable collection of Prometheus metrics while running your app diff --git a/daprdocs/content/en/developing-applications/building-blocks/bindings/howto-bindings.md b/daprdocs/content/en/developing-applications/building-blocks/bindings/howto-bindings.md index d17bb6eae..2f5294044 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/bindings/howto-bindings.md +++ b/daprdocs/content/en/developing-applications/building-blocks/bindings/howto-bindings.md @@ -35,7 +35,7 @@ Create a new binding component named `checkout`. Within the `metadata` section, {{% codetab %}} -Use the `--components-path` flag with `dapr run` to point to your custom components directory. +Use the `--resources-path` flag with `dapr run` to point to your custom resources directory. ```yaml apiVersion: dapr.io/v1alpha1 diff --git a/daprdocs/content/en/developing-applications/building-blocks/bindings/howto-triggers.md b/daprdocs/content/en/developing-applications/building-blocks/bindings/howto-triggers.md index 6b37300e7..a98cc37ea 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/bindings/howto-triggers.md +++ b/daprdocs/content/en/developing-applications/building-blocks/bindings/howto-triggers.md @@ -41,7 +41,7 @@ Create a new binding component named `checkout`. Within the `metadata` section, {{% codetab %}} -Use the `--components-path` flag with the `dapr run` command to point to your custom components directory. +Use the `--resources-path` flag with the `dapr run` command to point to your custom resources directory. ```yaml apiVersion: dapr.io/v1alpha1 diff --git a/daprdocs/content/en/developing-applications/building-blocks/configuration/configuration-api-overview.md b/daprdocs/content/en/developing-applications/building-blocks/configuration/configuration-api-overview.md index 5f2ac9096..2e95f6b49 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/configuration/configuration-api-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/configuration/configuration-api-overview.md @@ -6,17 +6,40 @@ weight: 1000 description: "Overview of the configuration API building block" --- -## Introduction +Consuming application configuration is a common task when writing applications. Frequently, configuration stores are used to manage this configuration data. A configuration item is often dynamic in nature and tightly coupled to the needs of the application that consumes it. -Consuming application configuration is a common task when writing applications and frequently configuration stores are used to manage this configuration data. A configuration item is often dynamic in nature and is tightly coupled to the needs of the application that consumes it. For example, common uses for application configuration include names of secrets, different identifiers, partition or consumer IDs, names of databases to connect to etc. These configuration items are typically stored as key/value items in a state store or database. Application configuration can be changed by either developers or operators at runtime and the developer needs to be notified of these changes in order to take the required action and load the new configuration. Also configuration data is typically read only from the application API perspective, with updates to the configuration store made through operator tooling. Dapr's configuration API allows developers to consume configuration items that are returned as read only key/value pairs and subscribe to changes whenever a configuration item changes. +For example, application configuration can include: +- Names of secrets +- Different identifiers +- Partition or consumer IDs +- Names of databases to connect to, etc + +Usually, configuration items are stored as key/value items in a state store or database. Developers or operators can change application configuration at runtime in the configuration store. Once changes are made, a service is notified to load the new configuration. + +Configuration data is read-only from the application API perspective, with updates to the configuration store made through operator tooling. With Dapr's configuration API, you can: +- Consume configuration items that are returned as read-only key/value pairs +- Subscribe to changes whenever a configuration item changes -It is worth noting that this configuration API should not be confused with the [Dapr sidecar and control plane configuration]({{}}) which is used to set policies and settings on instances of Dapr sidecars or the installed Dapr control plane. +{{% alert title="Note" color="primary" %}} + The Configuration API should not be confused with the [Dapr sidecar and control plane configuration]({{< ref "configuration-overview" >}}), which is used to set policies and settings on Dapr sidecar instances or the installed Dapr control plane. +{{% /alert %}} -*This API is currently in `Alpha` state* +## Try out configuration + +### Quickstart + +Want to put the Dapr configuration API to the test? Walk through the following quickstart to see the configuration API in action: + +| Quickstart | Description | +| ---------- | ----------- | +| [Configuration quickstart]({{< ref configuration-quickstart.md >}}) | Get configuration items or subscribe to configuration changes using the configuration API. | + +### Start using the configuration API directly in your app + +Want to skip the quickstarts? Not a problem. You can try out the configuration building block directly in your application to read and manage configuration data. After [Dapr is installed]({{< ref "getting-started/_index.md" >}}), you can begin using the configuration API starting with [the configuration how-to guide]({{< ref howto-manage-configuration.md >}}). -## Features ## Next steps Follow these guides on: diff --git a/daprdocs/content/en/developing-applications/building-blocks/configuration/howto-manage-configuration.md b/daprdocs/content/en/developing-applications/building-blocks/configuration/howto-manage-configuration.md index 4de325ba6..b05722312 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/configuration/howto-manage-configuration.md +++ b/daprdocs/content/en/developing-applications/building-blocks/configuration/howto-manage-configuration.md @@ -8,12 +8,13 @@ description: "Learn how to get application configuration and subscribe for chang This example uses the Redis configuration store component to demonstrate how to retrieve a configuration item. +Diagram showing get configuration of example service + {{% alert title="Note" color="primary" %}} -This API is currently in `Alpha` state and only available on gRPC. An HTTP1.1 supported version with this URL syntax `/v1.0/configuration` will be available before the API is certified into `Stable` state. + If you haven't already, [try out the configuration quickstart]({{< ref configuration-quickstart.md >}}) for a quick walk-through on how to use the configuration API. {{% /alert %}} -Diagram showing get configuration of example service ## Create a configuration item in store @@ -68,7 +69,7 @@ spec: ## Retrieve Configuration Items ### Get configuration items using Dapr SDKs -{{< tabs Dotnet Java Python>}} +{{< tabs ".NET" Java Python>}} {{% codetab %}} @@ -304,7 +305,7 @@ asyncio.run(executeConfiguration()) ``` ```bash -dapr run --app-id orderprocessing --components-path components/ -- python3 OrderProcessingService.py +dapr run --app-id orderprocessing --resources-path components/ -- python3 OrderProcessingService.py ``` {{% /codetab %}} diff --git a/daprdocs/content/en/developing-applications/building-blocks/observability/tracing-overview.md b/daprdocs/content/en/developing-applications/building-blocks/observability/tracing-overview.md index eb758b335..38ac85d25 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/observability/tracing-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/observability/tracing-overview.md @@ -18,7 +18,7 @@ There are two scenarios for how tracing is used: 1. Dapr generates the trace context and you propagate the trace context to another service. 2. You generate the trace context and Dapr propagates the trace context to a service. -### Propogating sequential service calls +### Propagating sequential service calls Dapr takes care of creating the trace headers. However, when there are more than two services, you're responsible for propagating the trace headers between them. Let's go through the scenarios with examples: @@ -45,7 +45,7 @@ There are no helper methods exposed in Dapr SDKs to propagate and retrieve trace 4. Pub/sub messages Dapr generates the trace headers in the published message topic. These trace headers are propagated to any services listening on that topic. -### Propogating multiple different service calls +### Propagating multiple different service calls In the following scenarios, Dapr does some of the work for you and you need to either create or propagate trace headers. @@ -115,4 +115,4 @@ In the gRPC API calls, trace context is passed through `grpc-trace-bin` header. - [Observability concepts]({{< ref observability-concept.md >}}) - [W3C Trace Context for distributed tracing]({{< ref w3c-tracing-overview >}}) - [W3C Trace Context specification](https://www.w3.org/TR/trace-context/) -- [Observability quickstart](https://github.com/dapr/quickstarts/tree/master/tutorials/observability) \ No newline at end of file +- [Observability quickstart](https://github.com/dapr/quickstarts/tree/master/tutorials/observability) diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md index 9a3463eaa..134bf696b 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md @@ -63,14 +63,14 @@ scopes: - checkout ``` -You can override this file with another [pubsub component]({{< ref setup-pubsub >}}) by creating a components directory (in this example, `myComponents`) containing the file and using the flag `--components-path` with the `dapr run` CLI command. +You can override this file with another [pubsub component]({{< ref setup-pubsub >}}) by creating a components directory (in this example, `myComponents`) containing the file and using the flag `--resources-path` with the `dapr run` CLI command. {{< tabs Dotnet Java Python Go Javascript >}} {{% codetab %}} ```bash -dapr run --app-id myapp --components-path ./myComponents -- dotnet run +dapr run --app-id myapp --resources-path ./myComponents -- dotnet run ``` {{% /codetab %}} @@ -78,7 +78,7 @@ dapr run --app-id myapp --components-path ./myComponents -- dotnet run {{% codetab %}} ```bash -dapr run --app-id myapp --components-path ./myComponents -- mvn spring-boot:run +dapr run --app-id myapp --resources-path ./myComponents -- mvn spring-boot:run ``` {{% /codetab %}} @@ -86,7 +86,7 @@ dapr run --app-id myapp --components-path ./myComponents -- mvn spring-boot:run {{% codetab %}} ```bash -dapr run --app-id myapp --components-path ./myComponents -- python3 app.py +dapr run --app-id myapp --resources-path ./myComponents -- python3 app.py ``` {{% /codetab %}} @@ -94,7 +94,7 @@ dapr run --app-id myapp --components-path ./myComponents -- python3 app.py {{% codetab %}} ```bash -dapr run --app-id myapp --components-path ./myComponents -- go run app.go +dapr run --app-id myapp --resources-path ./myComponents -- go run app.go ``` {{% /codetab %}} @@ -102,7 +102,7 @@ dapr run --app-id myapp --components-path ./myComponents -- go run app.go {{% codetab %}} ```bash -dapr run --app-id myapp --components-path ./myComponents -- npm start +dapr run --app-id myapp --resources-path ./myComponents -- npm start ``` {{% /codetab %}} diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md index c66088ea0..a176d9402 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md @@ -47,7 +47,7 @@ When running Dapr, set the YAML component file path to point Dapr to the compone {{% codetab %}} ```bash -dapr run --app-id myapp --components-path ./myComponents -- dotnet run +dapr run --app-id myapp --resources-path ./myComponents -- dotnet run ``` {{% /codetab %}} @@ -55,7 +55,7 @@ dapr run --app-id myapp --components-path ./myComponents -- dotnet run {{% codetab %}} ```bash -dapr run --app-id myapp --components-path ./myComponents -- mvn spring-boot:run +dapr run --app-id myapp --resources-path ./myComponents -- mvn spring-boot:run ``` {{% /codetab %}} @@ -63,7 +63,7 @@ dapr run --app-id myapp --components-path ./myComponents -- mvn spring-boot:run {{% codetab %}} ```bash -dapr run --app-id myapp --components-path ./myComponents -- python3 app.py +dapr run --app-id myapp --resources-path ./myComponents -- python3 app.py ``` {{% /codetab %}} @@ -71,7 +71,7 @@ dapr run --app-id myapp --components-path ./myComponents -- python3 app.py {{% codetab %}} ```bash -dapr run --app-id myapp --components-path ./myComponents -- npm start +dapr run --app-id myapp --resources-path ./myComponents -- npm start ``` {{% /codetab %}} @@ -79,7 +79,7 @@ dapr run --app-id myapp --components-path ./myComponents -- npm start {{% codetab %}} ```bash -dapr run --app-id myapp --components-path ./myComponents -- go run app.go +dapr run --app-id myapp --resources-path ./myComponents -- go run app.go ``` {{% /codetab %}} diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-state-query-api.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-state-query-api.md index 0aecc3224..6b321d34d 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-state-query-api.md +++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-state-query-api.md @@ -16,7 +16,7 @@ Even though the state store is a key/value store, the `value` might be a JSON do ## Querying the state -Submit query requests via HTTP POST/PUT or gRPC. The body of the request is the JSON map with 3 _optional_ entries: +Submit query requests via HTTP POST/PUT or gRPC. The body of the request is the JSON map with 3 entries: - `filter` - `sort` @@ -96,7 +96,7 @@ docker run -d --rm -p 27017:27017 --name mongodb mongo:5 Next, start a Dapr application. Refer to the [component configuration file](../query-api-examples/components/mongodb/mongodb.yml), which instructs Dapr to use MongoDB as its state store. ```bash -dapr run --app-id demo --dapr-http-port 3500 --components-path query-api-examples/components/mongodb +dapr run --app-id demo --dapr-http-port 3500 --resources-path query-api-examples/components/mongodb ``` Populate the state store with the employee dataset, so you can query it later. diff --git a/daprdocs/content/en/developing-applications/local-development/ides/vscode/vscode-dapr-extension.md b/daprdocs/content/en/developing-applications/local-development/ides/vscode/vscode-dapr-extension.md index e80b80239..85dbfe828 100644 --- a/daprdocs/content/en/developing-applications/local-development/ides/vscode/vscode-dapr-extension.md +++ b/daprdocs/content/en/developing-applications/local-development/ides/vscode/vscode-dapr-extension.md @@ -33,7 +33,7 @@ To create a dedicated components folder with the default `statestore`, `pubsub`, 1. Open your application directory in Visual Studio Code 2. Open the Command Palette with `Ctrl+Shift+P` 3. Select `Dapr: Scaffold Dapr Components` -4. Run your application with `dapr run --components-path ./components -- ...` +4. Run your application with `dapr run --resources-path ./components -- ...` ### View running Dapr applications diff --git a/daprdocs/content/en/getting-started/install-dapr-cli.md b/daprdocs/content/en/getting-started/install-dapr-cli.md index 258ff34e0..4c8d39880 100644 --- a/daprdocs/content/en/getting-started/install-dapr-cli.md +++ b/daprdocs/content/en/getting-started/install-dapr-cli.md @@ -188,6 +188,7 @@ Available Commands: stop Stop Dapr instances and their associated apps. . Supported platforms: Self-hosted uninstall Uninstall Dapr runtime. Supported platforms: Kubernetes and self-hosted upgrade Upgrades a Dapr control plane installation in a cluster. Supported platforms: Kubernetes + version Print the Dapr runtime and CLI version Flags: -h, --help help for dapr diff --git a/daprdocs/content/en/getting-started/quickstarts/_index.md b/daprdocs/content/en/getting-started/quickstarts/_index.md index 9c9f9d497..4e47d39e4 100644 --- a/daprdocs/content/en/getting-started/quickstarts/_index.md +++ b/daprdocs/content/en/getting-started/quickstarts/_index.md @@ -27,4 +27,6 @@ Hit the ground running with our Dapr quickstarts, complete with code samples aim | [State Management]({{< ref statemanagement-quickstart.md >}}) | Store a service's data as key/value pairs in supported state stores. | | [Bindings]({{< ref bindings-quickstart.md >}}) | Work with external systems using input bindings to respond to events and output bindings to call operations. | | [Secrets Management]({{< ref secrets-quickstart.md >}}) | Securely fetch secrets. | -| [Resiliency]({{< ref resiliency >}}) | Define and apply fault-tolerance policies to your Dapr API requests. | \ No newline at end of file +| [Configuration]({{< ref configuration-quickstart.md >}}) | Get configuration items and subscribe for configuration updates. | +| [Resiliency]({{< ref resiliency >}}) | Define and apply fault-tolerance policies to your Dapr API requests. | + diff --git a/daprdocs/content/en/getting-started/quickstarts/bindings-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/bindings-quickstart.md index aa52aa3e0..55c5472b0 100644 --- a/daprdocs/content/en/getting-started/quickstarts/bindings-quickstart.md +++ b/daprdocs/content/en/getting-started/quickstarts/bindings-quickstart.md @@ -46,7 +46,7 @@ Run the [PostgreSQL instance](https://www.postgresql.org/) locally in a Docker c In a terminal window, from the root of the Quickstarts clone directory, navigate to the `bindings/db` directory. ```bash -cd quickstarts/bindings/db +cd bindings/db ``` Run the following command to set up the container: @@ -73,7 +73,7 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS In a new terminal window, navigate to the SDK directory. ```bash -cd quickstarts/bindings/python/sdk/batch +cd bindings/python/sdk/batch ``` Install the dependencies: @@ -85,7 +85,7 @@ pip3 install -r requirements.txt Run the `batch-sdk` service alongside a Dapr sidecar. ```bash -dapr run --app-id batch-sdk --app-port 50051 --components-path ../../../components -- python3 app.py +dapr run --app-id batch-sdk --app-port 50051 --resources-path ../../../components -- python3 app.py ``` > **Note**: Since Python3.exe is not defined in Windows, you may need to use `python app.py` instead of `python3 app.py`. @@ -137,7 +137,7 @@ Your output binding's `print` statement output: In a new terminal, verify the same data has been inserted into the database. Navigate to the `bindings/db` directory. ```bash -cd quickstarts/bindings/db +cd bindings/db ``` Run the following to start the interactive Postgres CLI: @@ -253,7 +253,7 @@ Run the [PostgreSQL instance](https://www.postgresql.org/) locally in a Docker c In a terminal window, from the root of the Quickstarts clone directory, navigate to the `bindings/db` directory. ```bash -cd quickstarts/bindings/db +cd bindings/db ``` Run the following command to set up the container: @@ -280,7 +280,7 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS In a new terminal window, navigate to the SDK directory. ```bash -cd quickstarts/bindings/javascript/sdk/batch +cd bindings/javascript/sdk/batch ``` Install the dependencies: @@ -292,7 +292,7 @@ npm install Run the `batch-sdk` service alongside a Dapr sidecar. ```bash -dapr run --app-id batch-sdk --app-port 5002 --dapr-http-port 3500 --components-path ../../../components -- node index.js +dapr run --app-id batch-sdk --app-port 5002 --dapr-http-port 3500 --resources-path ../../../components -- node index.js ``` The code inside the `process_batch` function is executed every 10 seconds (defined in [`binding-cron.yaml`]({{< ref "#componentsbinding-cronyaml-component-file" >}}) in the `components` directory). The binding trigger looks for a route called via HTTP POST in your Flask application by the Dapr sidecar. @@ -339,7 +339,7 @@ Your output binding's `print` statement output: In a new terminal, verify the same data has been inserted into the database. Navigate to the `bindings/db` directory. ```bash -cd quickstarts/bindings/db +cd bindings/db ``` Run the following to start the interactive Postgres CLI: @@ -455,7 +455,7 @@ Run the [PostgreSQL instance](https://www.postgresql.org/) locally in a Docker c In a terminal window, from the root of the Quickstarts clone directory, navigate to the `bindings/db` directory. ```bash -cd quickstarts/bindings/db +cd bindings/db ``` Run the following command to set up the container: @@ -482,7 +482,7 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS In a new terminal window, navigate to the SDK directory. ```bash -cd quickstarts/bindings/csharp/sdk/batch +cd bindings/csharp/sdk/batch ``` Install the dependencies: @@ -495,7 +495,7 @@ dotnet build batch.csproj Run the `batch-sdk` service alongside a Dapr sidecar. ```bash -dapr run --app-id batch-sdk --app-port 7002 --components-path ../../../components -- dotnet run +dapr run --app-id batch-sdk --app-port 7002 --resources-path ../../../components -- dotnet run ``` The code inside the `process_batch` function is executed every 10 seconds (defined in [`binding-cron.yaml`]({{< ref "#componentsbinding-cronyaml-component-file" >}}) in the `components` directory). The binding trigger looks for a route called via HTTP POST in your Flask application by the Dapr sidecar. @@ -543,7 +543,7 @@ Your output binding's `print` statement output: In a new terminal, verify the same data has been inserted into the database. Navigate to the `bindings/db` directory. ```bash -cd quickstarts/bindings/db +cd bindings/db ``` Run the following to start the interactive Postgres CLI: @@ -662,7 +662,7 @@ Run the [PostgreSQL instance](https://www.postgresql.org/) locally in a Docker c In a terminal window, from the root of the Quickstarts clone directory, navigate to the `bindings/db` directory. ```bash -cd quickstarts/bindings/db +cd bindings/db ``` Run the following command to set up the container: @@ -689,7 +689,7 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS In a new terminal window, navigate to the SDK directory. ```bash -cd quickstarts/bindings/java/sdk/batch +cd bindings/java/sdk/batch ``` Install the dependencies: @@ -701,7 +701,7 @@ mvn clean install Run the `batch-sdk` service alongside a Dapr sidecar. ```bash -dapr run --app-id batch-sdk --app-port 8080 --components-path ../../../components -- java -jar target/BatchProcessingService-0.0.1-SNAPSHOT.jar +dapr run --app-id batch-sdk --app-port 8080 --resources-path ../../../components -- java -jar target/BatchProcessingService-0.0.1-SNAPSHOT.jar ``` The code inside the `process_batch` function is executed every 10 seconds (defined in [`binding-cron.yaml`]({{< ref "#componentsbinding-cronyaml-component-file" >}}) in the `components` directory). The binding trigger looks for a route called via HTTP POST in your Flask application by the Dapr sidecar. @@ -753,7 +753,7 @@ Your output binding's `print` statement output: In a new terminal, verify the same data has been inserted into the database. Navigate to the `bindings/db` directory. ```bash -cd quickstarts/bindings/db +cd bindings/db ``` Run the following to start the interactive Postgres CLI: @@ -869,7 +869,7 @@ Run the [PostgreSQL instance](https://www.postgresql.org/) locally in a Docker c In a terminal window, from the root of the Quickstarts clone directory, navigate to the `bindings/db` directory. ```bash -cd quickstarts/bindings/db +cd bindings/db ``` Run the following command to set up the container: @@ -896,7 +896,7 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS In a new terminal window, navigate to the SDK directory. ```bash -cd quickstarts/bindings/go/sdk/batch +cd bindings/go/sdk/batch ``` Install the dependencies: @@ -908,7 +908,7 @@ go build . Run the `batch-sdk` service alongside a Dapr sidecar. ```bash -dapr run --app-id batch-sdk --app-port 6002 --dapr-http-port 3502 --dapr-grpc-port 60002 --components-path ../../../components -- go run . +dapr run --app-id batch-sdk --app-port 6002 --dapr-http-port 3502 --dapr-grpc-port 60002 --resources-path ../../../components -- go run . ``` The code inside the `process_batch` function is executed every 10 seconds (defined in [`binding-cron.yaml`]({{< ref "#componentsbinding-cronyaml-component-file" >}}) in the `components` directory). The binding trigger looks for a route called via HTTP POST in your Flask application by the Dapr sidecar. @@ -965,7 +965,7 @@ Your output binding's `print` statement output: In a new terminal, verify the same data has been inserted into the database. Navigate to the `bindings/db` directory. ```bash -cd quickstarts/bindings/db +cd bindings/db ``` Run the following to start the interactive Postgres CLI: diff --git a/daprdocs/content/en/getting-started/quickstarts/configuration-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/configuration-quickstart.md new file mode 100644 index 000000000..e457612a1 --- /dev/null +++ b/daprdocs/content/en/getting-started/quickstarts/configuration-quickstart.md @@ -0,0 +1,639 @@ +--- +type: docs +title: "Quickstart: Configuration" +linkTitle: Configuration +weight: 76 +description: Get started with Dapr's Configuration building block +--- + +Let's take a look at Dapr's [Configuration building block]({{< ref configuration-api-overview.md >}}). A configuration item is often dynamic in nature and tightly coupled to the needs of the application that consumes it. Configuration items are key/value pairs containing configuration data, such as: +- App ids +- Partition keys +- Database names, etc + +In this quickstart, you'll run an `order-processor` microservice that utilizes the Configuration API. The service: +1. Gets configuration items from the configuration store. +1. Subscribes for configuration updates. + +Diagram that demonstrates the flow of the configuration API quickstart with key/value pairs used. + +Select your preferred language-specific Dapr SDK before proceeding with the Quickstart. + +{{< tabs "Python" "JavaScript" ".NET" "Java" "Go" >}} + +{{% codetab %}} + +### Pre-requisites + +For this example, you will need: + +- [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started). +- [Python 3.7+ installed](https://www.python.org/downloads/). + +- [Docker Desktop](https://www.docker.com/products/docker-desktop) + + +### Step 1: Set up the environment + +Clone the [sample provided in the Quickstarts repo](https://github.com/dapr/quickstarts/tree/master/configuration). + +```bash +git clone https://github.com/dapr/quickstarts.git +``` + +Once cloned, open a new terminal and run the following command to set values for configuration items `orderId1` and `orderId2`. + +```bash +docker exec dapr_redis redis-cli MSET orderId1 "101" orderId2 "102" +``` + +### Step 2: Run the `order-processor` service + +From the root of the Quickstarts clone directory, navigate to the `order-processor` directory. + +```bash +cd configuration/python/sdk/order-processor +``` + +Install the dependencies: + +```bash +pip3 install -r requirements.txt +``` + +Run the `order-processor` service alongside a Dapr sidecar. + +```bash +dapr run --app-id order-processor --components-path ../../../components/ --app-port 6001 -- python3 app.py +``` + +> **Note**: Since Python3.exe is not defined in Windows, you may need to use `python app.py` instead of `python3 app.py`. + +The expected output: + +``` +== APP == Configuration for orderId1 : value: "101" +== APP == +== APP == Configuration for orderId2 : value: "102" +== APP == +== APP == App unsubscribed from config changes +``` + +### (Optional) Step 3: Update configuration item values + +Once the app has unsubscribed, try updating the configuration item values. Change the `orderId1` and `orderId2` values using the following command: + +```bash +docker exec dapr_redis redis-cli MSET orderId1 "103" orderId2 "104" +``` + +Run the `order-processor` service again: + +```bash +dapr run --app-id order-processor --components-path ../../../components/ --app-port 6001 -- python3 app.py +``` + +> **Note**: Since Python3.exe is not defined in Windows, you may need to use `python app.py` instead of `python3 app.py`. + +The app will return the updated configuration values: + +``` +== APP == Configuration for orderId1 : value: "103" +== APP == +== APP == Configuration for orderId2 : value: "104" +== APP == +``` + +### The `order-processor` service + +The `order-processor` service includes code for: +- Getting the configuration items from the config store +- Subscribing to configuration updates (which you made in the CLI earlier) +- Unsubscribing from configuration updates and exiting the app after 20 seconds of inactivity. + +Get configuration items: + +```python +# Get config items from the config store +for config_item in CONFIGURATION_ITEMS: + config = client.get_configuration(store_name=DAPR_CONFIGURATION_STORE, keys=[config_item], config_metadata={}) + print(f"Configuration for {config_item} : {config.items[config_item]}", flush=True) +``` + +Subscribe to configuration updates: + +```python +# Subscribe for configuration changes +configuration = await client.subscribe_configuration(DAPR_CONFIGURATION_STORE, CONFIGURATION_ITEMS) +``` + +Unsubscribe from configuration updates and exit the application: + +```python +# Unsubscribe from configuration updates +unsubscribed = True +for config_item in CONFIGURATION_ITEMS: + unsub_item = client.unsubscribe_configuration(DAPR_CONFIGURATION_STORE, config_item) + #... +if unsubscribed == True: + print("App unsubscribed from config changes", flush=True) +``` + + +{{% /codetab %}} + + + +{{% codetab %}} + +### Pre-requisites + +For this example, you will need: + +- [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started). +- [Python 3.7+ installed](https://www.python.org/downloads/). + +- [Docker Desktop](https://www.docker.com/products/docker-desktop) + + +### Step 1: Set up the environment + +Clone the [sample provided in the Quickstarts repo](https://github.com/dapr/quickstarts/tree/master/configuration). + +```bash +git clone https://github.com/dapr/quickstarts.git +``` + +Once cloned, open a new terminal and run the following command to set values for configuration items `orderId1` and `orderId2`. + +```bash +docker exec dapr_redis redis-cli MSET orderId1 "101" orderId2 "102" +``` + +### Step 2: Run the `order-processor` service + +From the root of the Quickstarts clone directory, navigate to the `order-processor` directory. + +```bash +cd configuration/javascript/sdk/order-processor +``` + +Install the dependencies: + +```bash +npm install +``` + +Run the `order-processor` service alongside a Dapr sidecar. + +```bash +dapr run --app-id order-processor --components-path ../../../components/ --app-protocol grpc --dapr-grpc-port 3500 -- node index.js +``` + +The expected output: + +``` +== APP == Configuration for orderId1: {"key":"orderId1","value":"101","version":"","metadata":{}} +== APP == Configuration for orderId2: {"key":"orderId2","value":"102","version":"","metadata":{}} +== APP == App unsubscribed to config changes +``` + +### (Optional) Step 3: Update configuration item values + +Once the app has unsubscribed, try updating the configuration item values. Change the `orderId1` and `orderId2` values using the following command: + +```bash +docker exec dapr_redis redis-cli MSET orderId1 "103" orderId2 "104" +``` + +Run the `order-processor` service again: + +```bash +dapr run --app-id order-processor --components-path ../../../components/ --app-protocol grpc --dapr-grpc-port 3500 -- node index.js +``` + +The app will return the updated configuration values: + +``` +== APP == Configuration for orderId1: {"key":"orderId1","value":"103","version":"","metadata":{}} +== APP == Configuration for orderId2: {"key":"orderId2","value":"104","version":"","metadata":{}} +``` + +### The `order-processor` service + +The `order-processor` service includes code for: +- Getting the configuration items from the config store +- Subscribing to configuration updates (which you made in the CLI earlier) +- Unsubscribing from configuration updates and exiting the app after 20 seconds of inactivity. + +Get configuration items: + +```javascript +// Get config items from the config store +//... + const config = await client.configuration.get(DAPR_CONFIGURATION_STORE, CONFIGURATION_ITEMS); + Object.keys(config.items).forEach((key) => { + console.log("Configuration for " + key + ":", JSON.stringify(config.items[key])); + }); +``` + +Subscribe to configuration updates: + +```javascript +// Subscribe to config updates +try { + const stream = await client.configuration.subscribeWithKeys( + DAPR_CONFIGURATION_STORE, + CONFIGURATION_ITEMS, + (config) => { + console.log("Configuration update", JSON.stringify(config.items)); + } + ); +``` + +Unsubscribe from configuration updates and exit the application: + +```javascript +// Unsubscribe to config updates and exit app after 20 seconds +setTimeout(() => { + stream.stop(); + console.log("App unsubscribed to config changes"); + process.exit(0); +}, +``` + +{{% /codetab %}} + + +{{% codetab %}} + +### Pre-requisites + +For this example, you will need: + +- [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started). +- [.NET SDK or .NET 6 SDK installed](https://dotnet.microsoft.com/download). + +- [Docker Desktop](https://www.docker.com/products/docker-desktop) + + +### Step 1: Set up the environment + +Clone the [sample provided in the Quickstarts repo](https://github.com/dapr/quickstarts/tree/master/configuration). + +```bash +git clone https://github.com/dapr/quickstarts.git +``` + +Once cloned, open a new terminal and run the following command to set values for configuration items `orderId1` and `orderId2`. + +```bash +docker exec dapr_redis redis-cli MSET orderId1 "101" orderId2 "102" +``` + +### Step 2: Run the `order-processor` service + +From the root of the Quickstarts clone directory, navigate to the `order-processor` directory. + +```bash +cd configuration/csharp/sdk/order-processor +``` + +Recall NuGet packages: + +```bash +dotnet restore +dotnet build +``` + +Run the `order-processor` service alongside a Dapr sidecar. + +```bash +dapr run --app-id order-processor-http --components-path ../../../components/ --app-port 7001 -- dotnet run --project . +``` + +The expected output: + +``` +== APP == Configuration for orderId1: {"Value":"101","Version":"","Metadata":{}} +== APP == Configuration for orderId2: {"Value":"102","Version":"","Metadata":{}} +== APP == App unsubscribed from config changes +``` + +### (Optional) Step 3: Update configuration item values + +Once the app has unsubscribed, try updating the configuration item values. Change the `orderId1` and `orderId2` values using the following command: + +```bash +docker exec dapr_redis redis-cli MSET orderId1 "103" orderId2 "104" +``` + +Run the `order-processor` service again: + +```bash +dapr run --app-id order-processor-http --components-path ../../../components/ --app-port 7001 -- dotnet run --project . +``` + +The app will return the updated configuration values: + +``` +== APP == Configuration for orderId1: {"Value":"103","Version":"","Metadata":{}} +== APP == Configuration for orderId2: {"Value":"104","Version":"","Metadata":{}} +``` + +### The `order-processor` service + +The `order-processor` service includes code for: +- Getting the configuration items from the config store +- Subscribing to configuration updates (which you made in the CLI earlier) +- Unsubscribing from configuration updates and exiting the app after 20 seconds of inactivity. + +Get configuration items: + +```csharp +// Get config from configuration store +GetConfigurationResponse config = await client.GetConfiguration(DAPR_CONFIGURATION_STORE, CONFIGURATION_ITEMS); +foreach (var item in config.Items) +{ + var cfg = System.Text.Json.JsonSerializer.Serialize(item.Value); + Console.WriteLine("Configuration for " + item.Key + ": " + cfg); +} +``` + +Subscribe to configuration updates: + +```csharp +// Subscribe to config updates +SubscribeConfigurationResponse subscribe = await client.SubscribeConfiguration(DAPR_CONFIGURATION_STORE, CONFIGURATION_ITEMS); +``` + +Unsubscribe from configuration updates and exit the application: + +```csharp +// Unsubscribe to config updates and exit the app +try +{ + client.UnsubscribeConfiguration(DAPR_CONFIGURATION_STORE, subscriptionId); + Console.WriteLine("App unsubscribed from config changes"); + Environment.Exit(0); +} +``` + +{{% /codetab %}} + + +{{% codetab %}} + +### Pre-requisites + +For this example, you will need: + +- [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started). +- Java JDK 11 (or greater): + - [Oracle JDK](https://www.oracle.com/technetwork/java/javase/downloads/index.html#JDK11), or + - OpenJDK +- [Apache Maven](https://maven.apache.org/install.html), version 3.x. + +- [Docker Desktop](https://www.docker.com/products/docker-desktop) + + +### Step 1: Set up the environment + +Clone the [sample provided in the Quickstarts repo](https://github.com/dapr/quickstarts/tree/master/configuration). + +```bash +git clone https://github.com/dapr/quickstarts.git +``` + +Once cloned, open a new terminal and run the following command to set values for configuration items `orderId1` and `orderId2`. + +```bash +docker exec dapr_redis redis-cli MSET orderId1 "101" orderId2 "102" +``` + +### Step 2: Run the `order-processor` service + +From the root of the Quickstarts clone directory, navigate to the `order-processor` directory. + +```bash +cd configuration/java/sdk/order-processor +``` + +Install the dependencies: + +```bash +mvn clean install +``` + +Run the `order-processor` service alongside a Dapr sidecar. + +```bash +dapr run --app-id order-processor --components-path ../../../components -- java -jar target/OrderProcessingService-0.0.1-SNAPSHOT.jar +``` + +The expected output: + +``` +== APP == Configuration for orderId1: {'value':'101'} +== APP == Configuration for orderId2: {'value':'102'} +== APP == App unsubscribed to config changes +``` + +### (Optional) Step 3: Update configuration item values + +Once the app has unsubscribed, try updating the configuration item values. Change the `orderId1` and `orderId2` values using the following command: + +```bash +docker exec dapr_redis redis-cli MSET orderId1 "103" orderId2 "104" +``` + +Run the `order-processor` service again: + +```bash +dapr run --app-id order-processor --components-path ../../../components -- java -jar target/OrderProcessingService-0.0.1-SNAPSHOT.jar +``` + +The app will return the updated configuration values: + +``` +== APP == Configuration for orderId1: {'value':'103'} +== APP == Configuration for orderId2: {'value':'104'} +``` + +### The `order-processor` service + +The `order-processor` service includes code for: +- Getting the configuration items from the config store +- Subscribing to configuration updates (which you made in the CLI earlier) +- Unsubscribing from configuration updates and exiting the app after 20 seconds of inactivity. + +Get configuration items: + +```java +// Get config items from the config store +try (DaprPreviewClient client = (new DaprClientBuilder()).buildPreviewClient()) { + for (String configurationItem : CONFIGURATION_ITEMS) { + ConfigurationItem item = client.getConfiguration(DAPR_CONFIGURATON_STORE, configurationItem).block(); + System.out.println("Configuration for " + configurationItem + ": {'value':'" + item.getValue() + "'}"); + } +``` + +Subscribe to configuration updates: + +```java +// Subscribe for config changes +Flux subscription = client.subscribeConfiguration(DAPR_CONFIGURATON_STORE, + CONFIGURATION_ITEMS.toArray(String[]::new)); +``` + +Unsubscribe from configuration updates and exit the application: + +```java +// Unsubscribe from config changes +UnsubscribeConfigurationResponse unsubscribe = client + .unsubscribeConfiguration(subscriptionId, DAPR_CONFIGURATON_STORE).block(); +if (unsubscribe.getIsUnsubscribed()) { + System.out.println("App unsubscribed to config changes"); +} +``` + +{{% /codetab %}} + + +{{% codetab %}} + +### Pre-requisites + +For this example, you will need: + +- [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started). +- [Latest version of Go](https://go.dev/dl/). + +- [Docker Desktop](https://www.docker.com/products/docker-desktop) + + +### Step 1: Set up the environment + +Clone the [sample provided in the Quickstarts repo](https://github.com/dapr/quickstarts/tree/master/configuration). + +```bash +git clone https://github.com/dapr/quickstarts.git +``` + +Once cloned, open a new terminal and run the following command to set values for configuration items `orderId1` and `orderId2`. + +```bash +docker exec dapr_redis redis-cli MSET orderId1 "101" orderId2 "102" +``` + +### Step 2: Run the `order-processor` service + +From the root of the Quickstarts clone directory, navigate to the `order-processor` directory. + +```bash +cd configuration/go/sdk/order-processor +``` + +Run the `order-processor` service alongside a Dapr sidecar. + +```bash +dapr run --app-id order-processor --app-port 6001 --components-path ../../../components -- go run . +``` + +The expected output: + +``` +== APP == Configuration for orderId1: {"Value":"101","Version":"","Metadata":null} +== APP == Configuration for orderId2: {"Value":"102","Version":"","Metadata":null} +== APP == dapr configuration subscribe finished. +== APP == App unsubscribed to config changes +``` + +### (Optional) Step 3: Update configuration item values + +Once the app has unsubscribed, try updating the configuration item values. Change the `orderId1` and `orderId2` values using the following command: + +```bash +docker exec dapr_redis redis-cli MSET orderId1 "103" orderId2 "104" +``` + +Run the `order-processor` service again: + +```bash +dapr run --app-id order-processor --app-port 6001 --components-path ../../../components -- go run . +``` + +The app will return the updated configuration values: + +``` +== APP == Configuration for orderId1: {"Value":"103","Version":"","Metadata":null} +== APP == Configuration for orderId2: {"Value":"104","Version":"","Metadata":null} +``` + +### The `order-processor` service + +The `order-processor` service includes code for: +- Getting the configuration items from the config store +- Subscribing to configuration updates (which you made in the CLI earlier) +- Unsubscribing from configuration updates and exiting the app after 20 seconds of inactivity. + +Get configuration items: + +```go +// Get config items from config store +for _, item := range CONFIGURATION_ITEMS { + config, err := client.GetConfigurationItem(ctx, DAPR_CONFIGURATION_STORE, item) + //... + c, _ := json.Marshal(config) + fmt.Println("Configuration for " + item + ": " + string(c)) +} +``` + +Subscribe to configuration updates: + +```go +// Subscribe for config changes +err = client.SubscribeConfigurationItems(ctx, DAPR_CONFIGURATION_STORE, CONFIGURATION_ITEMS, func(id string, config map[string]*dapr.ConfigurationItem) { + // First invocation when app subscribes to config changes only returns subscription id + if len(config) == 0 { + fmt.Println("App subscribed to config changes with subscription id: " + id) + subscriptionId = id + return + } +}) +``` + +Unsubscribe from configuration updates and exit the application: + +```go +// Unsubscribe to config updates and exit app after 20 seconds +select { +case <-ctx.Done(): + err = client.UnsubscribeConfigurationItems(context.Background(), DAPR_CONFIGURATION_STORE, subscriptionId) + //... + { + fmt.Println("App unsubscribed to config changes") + } +``` + +{{% /codetab %}} + +{{< /tabs >}} + +## Tell us what you think! + +We're continuously working to improve our Quickstart examples and value your feedback. Did you find this quickstart helpful? Do you have suggestions for improvement? + +Join the discussion in our [discord channel](https://discord.com/channels/778680217417809931/953427615916638238). + +## Next steps + +- Use Dapr Configuration with HTTP instead of an SDK. + - [Python](https://github.com/dapr/quickstarts/tree/master/configuration/python/http) + - [JavaScript](https://github.com/dapr/quickstarts/tree/master/configuration/javascript/http) + - [.NET](https://github.com/dapr/quickstarts/tree/master/configuration/csharp/http) + - [Java](https://github.com/dapr/quickstarts/tree/master/configuration/java/http) + - [Go](https://github.com/dapr/quickstarts/tree/master/configuration/go/http) +- Learn more about [Configuration building block]({{< ref configuration-api-overview >}}) + +{{< button text="Explore Dapr tutorials >>" page="getting-started/tutorials/_index.md" >}} \ No newline at end of file diff --git a/daprdocs/content/en/getting-started/quickstarts/pubsub-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/pubsub-quickstart.md index ee39c39d9..9c6460290 100644 --- a/daprdocs/content/en/getting-started/quickstarts/pubsub-quickstart.md +++ b/daprdocs/content/en/getting-started/quickstarts/pubsub-quickstart.md @@ -56,7 +56,7 @@ pip3 install -r requirements.txt Run the `order-processor` subscriber service alongside a Dapr sidecar. ```bash -dapr run --app-id order-processor --components-path ../../../components/ --app-port 5001 -- python3 app.py +dapr run --app-id order-processor --resources-path ../../../components/ --app-port 5001 -- python3 app.py ``` > **Note**: Since Python3.exe is not defined in Windows, you may need to use `python app.py` instead of `python3 app.py`. @@ -105,7 +105,7 @@ pip3 install -r requirements.txt Run the `checkout` publisher service alongside a Dapr sidecar. ```bash -dapr run --app-id checkout --components-path ../../../components/ -- python3 app.py +dapr run --app-id checkout --resources-path ../../../components/ -- python3 app.py ``` > **Note**: Since Python3.exe is not defined in Windows, you may need to use `python app.py` instead of `python3 app.py`. @@ -235,7 +235,7 @@ Verify you have the following files included in the service directory: Run the `order-processor` subscriber service alongside a Dapr sidecar. ```bash -dapr run --app-port 5001 --app-id order-processing --app-protocol http --dapr-http-port 3501 --components-path ../../../components -- npm run start +dapr run --app-port 5001 --app-id order-processing --app-protocol http --dapr-http-port 3501 --resources-path ../../../components -- npm run start ``` In the `order-processor` subscriber, we're subscribing to the Redis instance called `orderpubsub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. This enables your app code to talk to the Redis component instance through the Dapr sidecar. @@ -267,7 +267,7 @@ Verify you have the following files included in the service directory: Run the `checkout` publisher service alongside a Dapr sidecar. ```bash -dapr run --app-id checkout --app-protocol http --dapr-http-port 3500 --components-path ../../../components -- npm run start +dapr run --app-id checkout --app-protocol http --dapr-http-port 3500 --resources-path ../../../components -- npm run start ``` In the `checkout` publisher service, we're publishing the orderId message to the Redis instance called `orderpubsub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. As soon as the service starts, it publishes in a loop: @@ -389,7 +389,7 @@ dotnet build Run the `order-processor` subscriber service alongside a Dapr sidecar. ```bash -dapr run --app-id order-processor --components-path ../../../components --app-port 7002 -- dotnet run +dapr run --app-id order-processor --resources-path ../../../components --app-port 7002 -- dotnet run ``` In the `order-processor` subscriber, we're subscribing to the Redis instance called `orderpubsub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. This enables your app code to talk to the Redis component instance through the Dapr sidecar. @@ -423,7 +423,7 @@ dotnet build Run the `checkout` publisher service alongside a Dapr sidecar. ```bash -dapr run --app-id checkout --components-path ../../../components -- dotnet run +dapr run --app-id checkout --resources-path ../../../components -- dotnet run ``` In the `checkout` publisher, we're publishing the orderId message to the Redis instance called `orderpubsub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. As soon as the service starts, it publishes in a loop: @@ -544,7 +544,7 @@ mvn clean install Run the `order-processor` subscriber service alongside a Dapr sidecar. ```bash -dapr run --app-port 8080 --app-id order-processor --components-path ../../../components -- java -jar target/OrderProcessingService-0.0.1-SNAPSHOT.jar +dapr run --app-port 8080 --app-id order-processor --resources-path ../../../components -- java -jar target/OrderProcessingService-0.0.1-SNAPSHOT.jar ``` In the `order-processor` subscriber, we're subscribing to the Redis instance called `orderpubsub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. This enables your app code to talk to the Redis component instance through the Dapr sidecar. @@ -582,7 +582,7 @@ mvn clean install Run the `checkout` publisher service alongside a Dapr sidecar. ```bash -dapr run --app-id checkout --components-path ../../../components -- java -jar target/CheckoutService-0.0.1-SNAPSHOT.jar +dapr run --app-id checkout --resources-path ../../../components -- java -jar target/CheckoutService-0.0.1-SNAPSHOT.jar ``` In the `checkout` publisher, we're publishing the orderId message to the Redis instance called `orderpubsub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. As soon as the service starts, it publishes in a loop: @@ -706,7 +706,7 @@ go build . Run the `order-processor` subscriber service alongside a Dapr sidecar. ```bash -dapr run --app-port 6002 --app-id order-processor-sdk --app-protocol http --dapr-http-port 3501 --components-path ../../../components -- go run . +dapr run --app-port 6002 --app-id order-processor-sdk --app-protocol http --dapr-http-port 3501 --resources-path ../../../components -- go run . ``` In the `order-processor` subscriber, we're subscribing to the Redis instance called `orderpubsub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. This enables your app code to talk to the Redis component instance through the Dapr sidecar. @@ -736,7 +736,7 @@ go build . Run the `checkout` publisher service alongside a Dapr sidecar. ```bash -dapr run --app-id checkout --app-protocol http --dapr-http-port 3500 --components-path ../../../components -- go run . +dapr run --app-id checkout --app-protocol http --dapr-http-port 3500 --resources-path ../../../components -- go run . ``` In the `checkout` publisher, we're publishing the orderId message to the Redis instance called `orderpubsub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. As soon as the service starts, it publishes in a loop: diff --git a/daprdocs/content/en/getting-started/quickstarts/secrets-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/secrets-quickstart.md index 227abaf9f..7554c89b4 100644 --- a/daprdocs/content/en/getting-started/quickstarts/secrets-quickstart.md +++ b/daprdocs/content/en/getting-started/quickstarts/secrets-quickstart.md @@ -55,7 +55,7 @@ pip3 install -r requirements.txt Run the `order-processor` service alongside a Dapr sidecar. ```bash -dapr run --app-id order-processor --components-path ../../../components/ -- python3 app.py +dapr run --app-id order-processor --resources-path ../../../components/ -- python3 app.py ``` > **Note**: Since Python3.exe is not defined in Windows, you may need to use `python app.py` instead of `python3 app.py`. @@ -106,7 +106,7 @@ In the YAML file: **`secrets.json` file** -`SECRET_NAME` is defined in the `secrets.json` file, located in [secrets_management/python/sdk/order-processor](https://github.com/dapr/quickstarts/tree/master/secrets_management/javascript/sdk/order-processor/secrets.json): +`SECRET_NAME` is defined in the `secrets.json` file, located in [secrets_management/python/sdk/order-processor](https://github.com/dapr/quickstarts/tree/master/secrets_management/python/sdk/order-processor/secrets.json): ```json { @@ -164,7 +164,7 @@ npm install Run the `order-processor` service alongside a Dapr sidecar. ```bash -dapr run --app-id order-processor --components-path ../../../components/ -- npm start +dapr run --app-id order-processor --resources-path ../../../components/ -- npm start ``` #### Behind the scenes @@ -278,7 +278,7 @@ dotnet build Run the `order-processor` service alongside a Dapr sidecar. ```bash -dapr run --app-id order-processor --components-path ../../../components/ -- dotnet run +dapr run --app-id order-processor --resources-path ../../../components/ -- dotnet run ``` #### Behind the scenes @@ -328,7 +328,7 @@ In the YAML file: **`secrets.json` file** -`SECRET_NAME` is defined in the `secrets.json` file, located in [secrets_management/csharp/sdk/order-processor](https://github.com/dapr/quickstarts/tree/master/secrets_management/javascript/sdk/order-processor/secrets.json): +`SECRET_NAME` is defined in the `secrets.json` file, located in [secrets_management/csharp/sdk/order-processor](https://github.com/dapr/quickstarts/tree/master/secrets_management/csharp/sdk/order-processor/secrets.json): ```json { @@ -389,7 +389,7 @@ mvn clean install Run the `order-processor` service alongside a Dapr sidecar. ```bash -dapr run --app-id order-processor --components-path ../../../components/ -- java -jar target/OrderProcessingService-0.0.1-SNAPSHOT.jar +dapr run --app-id order-processor --resources-path ../../../components/ -- java -jar target/OrderProcessingService-0.0.1-SNAPSHOT.jar ``` #### Behind the scenes @@ -436,7 +436,7 @@ In the YAML file: **`secrets.json` file** -`SECRET_NAME` is defined in the `secrets.json` file, located in [secrets_management/python/sdk/order-processor](https://github.com/dapr/quickstarts/tree/master/secrets_management/javascript/sdk/order-processor/secrets.json): +`SECRET_NAME` is defined in the `secrets.json` file, located in [secrets_management/java/sdk/order-processor](https://github.com/dapr/quickstarts/tree/master/secrets_management/java/sdk/order-processor/secrets.json): ```json { @@ -494,7 +494,7 @@ go build . Run the `order-processor` service alongside a Dapr sidecar. ```bash -dapr run --app-id order-processor --components-path ../../../components/ -- go run . +dapr run --app-id order-processor --resources-path ../../../components/ -- go run . ``` #### Behind the scenes @@ -543,7 +543,7 @@ In the YAML file: **`secrets.json` file** -`SECRET_NAME` is defined in the `secrets.json` file, located in [secrets_management/python/sdk/order-processor](https://github.com/dapr/quickstarts/tree/master/secrets_management/javascript/sdk/order-processor/secrets.json): +`SECRET_NAME` is defined in the `secrets.json` file, located in [secrets_management/go/sdk/order-processor](https://github.com/dapr/quickstarts/tree/master/secrets_management/go/sdk/order-processor/secrets.json): ```json { diff --git a/daprdocs/content/en/getting-started/quickstarts/statemanagement-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/statemanagement-quickstart.md index 8c2fd1adc..29e8ea54f 100644 --- a/daprdocs/content/en/getting-started/quickstarts/statemanagement-quickstart.md +++ b/daprdocs/content/en/getting-started/quickstarts/statemanagement-quickstart.md @@ -51,7 +51,7 @@ pip3 install -r requirements.txt Run the `order-processor` service alongside a Dapr sidecar. ```bash -dapr run --app-id order-processor --components-path ../../../components/ -- python3 app.py +dapr run --app-id order-processor --resources-path ../../../components/ -- python3 app.py ``` > **Note**: Since Python3.exe is not defined in Windows, you may need to use `python app.py` instead of `python3 app.py`. @@ -172,7 +172,7 @@ Verify you have the following files included in the service directory: Run the `order-processor` service alongside a Dapr sidecar. ```bash -dapr run --app-id order-processor --components-path ../../../components/ -- npm run start +dapr run --app-id order-processor --resources-path ../../../components/ -- npm run start ``` The `order-processor` service writes, reads, and deletes an `orderId` key/value pair to the `statestore` instance [defined in the `statestore.yaml` component]({{< ref "#statestoreyaml-component-file" >}}). As soon as the service starts, it performs a loop. @@ -300,7 +300,7 @@ dotnet build Run the `order-processor` service alongside a Dapr sidecar. ```bash -dapr run --app-id order-processor --components-path ../../../components/ -- dotnet run +dapr run --app-id order-processor --resources-path ../../../components/ -- dotnet run ``` The `order-processor` service writes, reads, and deletes an `orderId` key/value pair to the `statestore` instance [defined in the `statestore.yaml` component]({{< ref "#statestoreyaml-component-file" >}}). As soon as the service starts, it performs a loop. @@ -419,7 +419,7 @@ mvn clean install Run the `order-processor` service alongside a Dapr sidecar. ```bash -dapr run --app-id order-processor --components-path ../../../components -- java -jar target/OrderProcessingService-0.0.1-SNAPSHOT.jar +dapr run --app-id order-processor --resources-path ../../../components -- java -jar target/OrderProcessingService-0.0.1-SNAPSHOT.jar ``` The `order-processor` service writes, reads, and deletes an `orderId` key/value pair to the `statestore` instance [defined in the `statestore.yaml` component]({{< ref "#statestoreyaml-component-file" >}}). As soon as the service starts, it performs a loop. @@ -538,7 +538,7 @@ go build . Run the `order-processor` service alongside a Dapr sidecar. ```bash -dapr run --app-id order-processor --components-path ../../../components -- go run . +dapr run --app-id order-processor --resources-path ../../../components -- go run . ``` The `order-processor` service writes, reads, and deletes an `orderId` key/value pair to the `statestore` instance [defined in the `statestore.yaml` component]({{< ref "#statestoreyaml-component-file" >}}). As soon as the service starts, it performs a loop. diff --git a/daprdocs/content/en/getting-started/tutorials/configure-state-pubsub.md b/daprdocs/content/en/getting-started/tutorials/configure-state-pubsub.md index 49d2522c2..13c86ea49 100644 --- a/daprdocs/content/en/getting-started/tutorials/configure-state-pubsub.md +++ b/daprdocs/content/en/getting-started/tutorials/configure-state-pubsub.md @@ -317,9 +317,9 @@ When you run `dapr init`, Dapr creates a default redis `pubsub.yaml` on your loc For new component files: 1. Create a new `components` directory in your app folder containing the YAML files. -1. Provide the path to the `dapr run` command with the flag `--components-path` +1. Provide the path to the `dapr run` command with the flag `--resources-path` -If you initialized Dapr in [slim mode]({{< ref self-hosted-no-docker.md >}}) (without Docker), you need to manually create the default directory, or always specify a components directory using `--components-path`. +If you initialized Dapr in [slim mode]({{< ref self-hosted-no-docker.md >}}) (without Docker), you need to manually create the default directory, or always specify a components directory using `--resources-path`. {{% /codetab %}} diff --git a/daprdocs/content/en/getting-started/tutorials/get-started-component.md b/daprdocs/content/en/getting-started/tutorials/get-started-component.md index 79ab0f635..9f5d6f6bc 100644 --- a/daprdocs/content/en/getting-started/tutorials/get-started-component.md +++ b/daprdocs/content/en/getting-started/tutorials/get-started-component.md @@ -65,7 +65,7 @@ In the above file definition: Launch a Dapr sidecar that will listen on port 3500 for a blank application named `myapp`: ```bash -dapr run --app-id myapp --dapr-http-port 3500 --components-path ./my-components +dapr run --app-id myapp --dapr-http-port 3500 --resources-path ./my-components ``` {{% alert title="Tip" color="primary" %}} diff --git a/daprdocs/content/en/operations/components/component-schema.md b/daprdocs/content/en/operations/components/component-schema.md index 0e4ab7822..d87ac4017 100644 --- a/daprdocs/content/en/operations/components/component-schema.md +++ b/daprdocs/content/en/operations/components/component-schema.md @@ -44,7 +44,7 @@ spec: ### Special metadata values -Metadata values can contain a `{uuid}` tag that is replaced with a randomly generate UUID when the Dapr sidecar starts up. A new UUID is generated on every start up. It can be used, for example, to have a pod on Kubernetes with multiple application instances consuming a [shared MQTT subscription]({{< ref "setup-mqtt.md" >}}). Below is an example of using the `{uuid}` tag. +Metadata values can contain a `{uuid}` tag that is replaced with a randomly generate UUID when the Dapr sidecar starts up. A new UUID is generated on every start up. It can be used, for example, to have a pod on Kubernetes with multiple application instances consuming a [shared MQTT subscription]({{< ref "setup-mqtt3.md" >}}). Below is an example of using the `{uuid}` tag. ```yaml apiVersion: dapr.io/v1alpha1 @@ -52,7 +52,7 @@ kind: Component metadata: name: messagebus spec: - type: pubsub.mqtt + type: pubsub.mqtt3 version: v1 metadata: - name: consumerID diff --git a/daprdocs/content/en/operations/components/setup-bindings.md b/daprdocs/content/en/operations/components/setup-bindings.md index 3af31760c..44d762dd6 100644 --- a/daprdocs/content/en/operations/components/setup-bindings.md +++ b/daprdocs/content/en/operations/components/setup-bindings.md @@ -62,7 +62,7 @@ Once you have created the component's YAML file, follow these instructions to ap {{< tabs "Self-Hosted" "Kubernetes" >}} {{% codetab %}} -To run locally, create a `components` dir containing the YAML file and provide the path to the `dapr run` command with the flag `--components-path`. +To run locally, create a `components` dir containing the YAML file and provide the path to the `dapr run` command with the flag `--resources-path`. {{% /codetab %}} {{% codetab %}} diff --git a/daprdocs/content/en/operations/components/setup-secret-store.md b/daprdocs/content/en/operations/components/setup-secret-store.md index bd4190c2a..001595325 100644 --- a/daprdocs/content/en/operations/components/setup-secret-store.md +++ b/daprdocs/content/en/operations/components/setup-secret-store.md @@ -65,7 +65,7 @@ Once you have created the component's YAML file, follow these instructions to ap {{< tabs "Self-Hosted" "Kubernetes" >}} {{% codetab %}} -To run locally, create a `components` dir containing the YAML file and provide the path to the `dapr run` command with the flag `--components-path`. +To run locally, create a `components` dir containing the YAML file and provide the path to the `dapr run` command with the flag `--resources-path`. {{% /codetab %}} {{% codetab %}} diff --git a/daprdocs/content/en/operations/configuration/configuration-overview.md b/daprdocs/content/en/operations/configuration/configuration-overview.md index 75bd9517d..6edfa5b84 100644 --- a/daprdocs/content/en/operations/configuration/configuration-overview.md +++ b/daprdocs/content/en/operations/configuration/configuration-overview.md @@ -48,6 +48,7 @@ The following configuration settings can be applied to Dapr application sidecars - [Tracing](#tracing) - [Metrics](#metrics) +- [Logging](#logging) - [Middleware](#middleware) - [Scope secret store access](#scope-secret-store-access) - [Access Control allow lists for building block APIs](#access-control-allow-lists-for-building-block-apis) @@ -85,7 +86,7 @@ The following table lists the properties for tracing: `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. -See [Observability distributed tracing]({{< ref "tracing-overview.md" >}}) for more information +See [Observability distributed tracing]({{< ref "tracing-overview.md" >}}) for more information. #### Metrics @@ -104,7 +105,29 @@ The following table lists the properties for metrics: |--------------|--------|-------------| | `enabled` | boolean | Whether metrics should to be enabled. -See [metrics documentation]({{< ref "metrics-overview.md" >}}) for more information +See [metrics documentation]({{< ref "metrics-overview.md" >}}) 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: + +```yml +logging: + apiLogging: + enabled: false + omitHealthChecks: false +``` + +The following table lists the properties for logging: + +| Property | Type | Description | +|--------------|--------|-------------| +| `apiLogging.enabled` | boolean | The 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.omitHealthChecks` | boolean | If `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]({{< ref "logs.md" >}}) for more information. #### Middleware @@ -130,8 +153,8 @@ The following table lists the properties for HTTP handlers: | Property | Type | Description | |----------|--------|-------------| -| name | string | Name of the middleware component -| type | string | Type of middleware component +| `name` | string | Name of the middleware component +| `type` | string | Type of middleware component See [Middleware pipelines]({{< ref "middleware.md" >}}) for more information diff --git a/daprdocs/content/en/operations/hosting/kubernetes/kubernetes-deploy.md b/daprdocs/content/en/operations/hosting/kubernetes/kubernetes-deploy.md index fb860a9de..267447227 100644 --- a/daprdocs/content/en/operations/hosting/kubernetes/kubernetes-deploy.md +++ b/daprdocs/content/en/operations/hosting/kubernetes/kubernetes-deploy.md @@ -64,9 +64,11 @@ There are some scenarios where it's necessary to install Dapr from a private Hel - having a custom Dapr deployment - pulling Helm charts from trusted registries that are managed and maintained by your organization +``` export DAPR_HELM_REPO_URL="https://helm.custom-domain.com/dapr/dapr" export DAPR_HELM_REPO_USERNAME="username_xxx" export DAPR_HELM_REPO_PASSWORD="passwd_xxx" +``` Setting the above parameters will allow `dapr init -k` to install Dapr images from the configured Helm repository. diff --git a/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-with-docker.md b/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-with-docker.md index 503bd039d..3211ac08c 100644 --- a/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-with-docker.md +++ b/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-with-docker.md @@ -123,10 +123,10 @@ services: "--app-id", "nodeapp", "--app-port", "3000", "--placement-host-address", "placement:50006", # Dapr's placement service can be reach via the docker DNS entry - "--components-path", "./components" + "--resources-path", "./components" ] volumes: - - "./components/:/components" # Mount our components folder for the runtime to use. The mounted location must match the --components-path argument. + - "./components/:/components" # Mount our components folder for the runtime to use. The mounted location must match the --resources-path argument. depends_on: - nodeapp network_mode: "service:nodeapp" # Attach the nodeapp-dapr service to the nodeapp network namespace diff --git a/daprdocs/content/en/operations/monitoring/logging/logs.md b/daprdocs/content/en/operations/monitoring/logging/logs.md index 86fc9c523..397588b69 100644 --- a/daprdocs/content/en/operations/monitoring/logging/logs.md +++ b/daprdocs/content/en/operations/monitoring/logging/logs.md @@ -58,7 +58,7 @@ When using the Dapr CLI to run an application, pass the `--log-as-json` option t ```sh dapr run \ --app-id orderprocessing \ - --components-path ./components/ \ + --resources-path ./components/ \ --log-as-json \ -- python3 OrderProcessingService.py ``` @@ -109,7 +109,9 @@ spec: ## API Logging -API logging enables you to see the API calls your application makes to the Dapr sidecar, to debug issues or monitor the behavior of your application. You can combine both Dapr API logging with Dapr log events. See [configure and view Dapr Logs]({{< ref "logs-troubleshooting.md" >}}) and [configure and view Dapr API Logs]({{< ref "api-logs-troubleshooting.md" >}}) for more information. +API logging enables you to see the API calls your application makes to the Dapr sidecar, to debug issues or monitor the behavior of your application. You can combine both Dapr API logging with Dapr log events. + +See [configure and view Dapr Logs]({{< ref "logs-troubleshooting.md" >}}) and [configure and view Dapr API Logs]({{< ref "api-logs-troubleshooting.md" >}}) for more information. ## Log collectors diff --git a/daprdocs/content/en/operations/troubleshooting/api-logs-troubleshooting.md b/daprdocs/content/en/operations/troubleshooting/api-logs-troubleshooting.md index 4d8abc7a5..6d124098d 100644 --- a/daprdocs/content/en/operations/troubleshooting/api-logs-troubleshooting.md +++ b/daprdocs/content/en/operations/troubleshooting/api-logs-troubleshooting.md @@ -77,3 +77,37 @@ time="2022-03-16T18:32:02.917629403Z" level=info msg="HTTP API Called" method="P time="2022-03-16T18:32:03.137830112Z" level=info msg="HTTP API Called" method="POST /v1.0/invoke/{id}/method/{method:*}" app_id=invoke-caller instance=invokecaller-f4f949886-cbnmt scope=dapr.runtime.http-info type=log useragent=Go-http-client/1.1 ver=edge time="2022-03-16T18:32:03.359097916Z" level=info msg="HTTP API Called" method="POST /v1.0/invoke/{id}/method/{method:*}" app_id=invoke-caller instance=invokecaller-f4f949886-cbnmt scope=dapr.runtime.http-info type=log useragent=Go-http-client/1.1 ver=edge ``` + +## API logging configuration + +Using the [Dapr Configuration spec]({{< ref "configuration-overview.md" >}}#sidecar-configuration), you can configure the default behavior of API logging in Dapr runtimes. + +### Enable API logging by default + +Using the Dapr Configuration spec, you can set the default value for the `--enable-api-logging` flag (and the correspondent annotation when running on Kubernetes), with the `logging.apiLogging.enabled` option. This value applies to all Dapr runtimes that reference the Configuration document or resource in which it's defined. + +- If `logging.apiLogging.enabled` is set to `false`, the default value, API logging is disabled for Dapr runtimes unless `--enable-api-logging` is set to `true` (or the `dapr.io/enable-api-logging: true` annotation is added). +- When `logging.apiLogging.enabled` is `true`, Dapr runtimes have API logging enabled by default, and it can be disabled by setting +`--enable-api-logging=false` or with the `dapr.io/enable-api-logging: false` annotation. + +For example: + +```yaml +logging: + apiLogging: + enabled: true +``` + +### Omit health checks from API logging + +When API logging is enabled, all calls to the Dapr API server are logged, including those to health check endpoints (e.g. `/v1.0/healthz`). Depending on your environment, this may generate multiple log lines per minute and could create unwanted noise. + +You can configure Dapr to not log calls to health check endpoints when API logging is enabled using the Dapr Configuration spec, by setting `logging.apiLogging.omitHealthChecks: true`. The default value is `false`, which means that health checks calls are logged in the API logs. + +For example: + +```yaml +logging: + apiLogging: + omitHealthChecks: true +``` diff --git a/daprdocs/content/en/operations/troubleshooting/common_issues.md b/daprdocs/content/en/operations/troubleshooting/common_issues.md index 59bad856a..07a0bf170 100644 --- a/daprdocs/content/en/operations/troubleshooting/common_issues.md +++ b/daprdocs/content/en/operations/troubleshooting/common_issues.md @@ -50,45 +50,54 @@ spec: imagePullPolicy: Always ``` -If your pod spec template is annotated correctly and you still don't see the sidecar injected, make sure Dapr was deployed to the cluster before your deployment or pod were deployed. +There are some known cases where this might not properly work: -If this is the case, restarting the pods will fix the issue. +- If your pod spec template is annotated correctly, and you still don't see the sidecar injected, make sure Dapr was deployed to the cluster before your deployment or pod were deployed. -If you are deploying Dapr on a private GKE cluster, sidecar injection does not work without extra steps. See [Setup a Google Kubernetes Engine cluster]({{< ref setup-gke.md >}}). + If this is the case, restarting the pods will fix the issue. -In order to further diagnose any issue, check the logs of the Dapr sidecar injector: +- If you are deploying Dapr on a private GKE cluster, sidecar injection does not work without extra steps. See [Setup a Google Kubernetes Engine cluster]({{< ref setup-gke.md >}}). -```bash - kubectl logs -l app=dapr-sidecar-injector -n dapr-system -``` + In order to further diagnose any issue, check the logs of the Dapr sidecar injector: -*Note: If you installed Dapr to a different namespace, replace dapr-system above with the desired namespace* + ```bash + kubectl logs -l app=dapr-sidecar-injector -n dapr-system + ``` -If you are deploying Dapr on Amazon EKS and using an overlay network such as Calico, you will need to set `hostNetwork` parameter to true, this is a limitation of EKS with such CNIs. + *Note: If you installed Dapr to a different namespace, replace dapr-system above with the desired namespace* -You can set this parameter using Helm `values.yaml` file: +- If you are deploying Dapr on Amazon EKS and using an overlay network such as Calico, you will need to set `hostNetwork` parameter to true, this is a limitation of EKS with such CNIs. -``` -helm upgrade --install dapr dapr/dapr \ + You can set this parameter using Helm `values.yaml` file: + + ``` + helm upgrade --install dapr dapr/dapr \ --namespace dapr-system \ --create-namespace \ --values values.yaml -``` + ``` -`values.yaml` -```yaml -dapr_sidecar_injector: - hostNetwork: true -``` + `values.yaml` + ```yaml + dapr_sidecar_injector: + hostNetwork: true + ``` -or using command line: + or using command line: -``` -helm upgrade --install dapr dapr/dapr \ + ``` + helm upgrade --install dapr dapr/dapr \ --namespace dapr-system \ --create-namespace \ --set dapr_sidecar_injector.hostNetwork=true -``` + ``` + +- Make sure the kube api server can reach the following webhooks services: + - [Sidecar Mutating Webhook Injector Service](https://github.com/dapr/dapr/blob/44235fe8e8799589bb393a3124d2564db2dd6885/charts/dapr/charts/dapr_sidecar_injector/templates/dapr_sidecar_injector_deployment.yaml#L157) at port __4000__ that is served from the sidecar injector. + - [CRD Conversion Webhook Service](https://github.com/dapr/dapr/blob/44235fe8e8799589bb393a3124d2564db2dd6885/charts/dapr/charts/dapr_operator/templates/dapr_operator_service.yaml#L28) at port __19443__ that is served from the operator. + + Check with your cluster administrators to setup allow ingress + rules to the above ports, __4000__ and __19443__, in the cluster from the kube api servers. ## My pod is in CrashLoopBackoff or another failed state due to the daprd sidecar @@ -225,7 +234,7 @@ export DAPR_HOST_IP=127.0.0.1 This is usually due to one of the following issues - You may have defined the `NAMESPACE` environment variable locally or deployed your components into a different namespace in Kubernetes. Check which namespace your app and the components are deployed to. Read [scoping components to one or more applications]({{< ref "component-scopes.md" >}}) for more information. -- You may have not provided a `--components-path` with the Dapr `run` commands or not placed your components into the default components folder for your OS. Read [define a component]({{< ref "get-started-component.md" >}}) for more information. +- You may have not provided a `--resources-path` with the Dapr `run` commands or not placed your components into the default components folder for your OS. Read [define a component]({{< ref "get-started-component.md" >}}) for more information. - You may have a syntax issue in component YAML file. Check your component YAML with the component [YAML samples]({{< ref "components.md" >}}). ## Service invocation is failing and my Dapr service is missing an appId (macOS) diff --git a/daprdocs/content/en/reference/arguments-annotations-overview.md b/daprdocs/content/en/reference/arguments-annotations-overview.md index 90acd19ef..5af0a4ed4 100644 --- a/daprdocs/content/en/reference/arguments-annotations-overview.md +++ b/daprdocs/content/en/reference/arguments-annotations-overview.md @@ -16,7 +16,8 @@ This table is meant to help users understand the equivalent options for running | `--app-id` | `--app-id` | `-i` | `dapr.io/app-id` | The unique ID of the application. Used for service discovery, state encapsulation and the pub/sub consumer ID | | `--app-port` | `--app-port` | `-p` | `dapr.io/app-port` | This parameter tells Dapr which port your application is listening on | | `--app-ssl` | `--app-ssl` | | `dapr.io/app-ssl` | Sets the URI scheme of the app to https and attempts an SSL connection | -| `--components-path` | `--components-path` | `-d` | not supported | Path for components directory. If empty, components will not be loaded. | +| `--components-path` | `--components-path` | `-d` | not supported | **Deprecated** in favor of `--resources-path` | +| `--resources-path` | `--resources-path` | `-d` | not supported | Path for components directory. If empty, components will not be loaded. | | `--config` | `--config` | `-c` | `dapr.io/config` | Tells Dapr which Configuration CRD to use | | `--control-plane-address` | not supported | | not supported | Address for a Dapr control plane | | `--dapr-grpc-port` | `--dapr-grpc-port` | | not supported | gRPC port for the Dapr API to listen on (default "50001") | diff --git a/daprdocs/content/en/reference/cli/cli-overview.md b/daprdocs/content/en/reference/cli/cli-overview.md index 7ac94c482..ef9d17e05 100644 --- a/daprdocs/content/en/reference/cli/cli-overview.md +++ b/daprdocs/content/en/reference/cli/cli-overview.md @@ -42,6 +42,7 @@ Available Commands: stop Stop Dapr instances and their associated apps. Supported platforms: Self-hosted uninstall Uninstall Dapr runtime. Supported platforms: Kubernetes and self-hosted upgrade Upgrades a Dapr control plane installation in a cluster. Supported platforms: Kubernetes + version Print the Dapr runtime and CLI version Flags: -h, --help help for dapr @@ -73,8 +74,8 @@ You can learn more about each Dapr command from the links below. - [`dapr stop`]({{< ref dapr-stop.md >}}) - [`dapr uninstall`]({{< ref dapr-uninstall.md >}}) - [`dapr upgrade`]({{< ref dapr-upgrade.md >}}) - - [`dapr-version`]({{< ref dapr-version.md >}}) + - [`dapr version`]({{< ref dapr-version.md >}}) ### Environment Variables -Some Dapr flags can be set via environment variables (e.g. `DAPR_NETWORK` for the `--network` flag of the `dapr init` command). Note that specifying the flag on the command line overrides any set environment variable. \ No newline at end of file +Some Dapr flags can be set via environment variables (e.g. `DAPR_NETWORK` for the `--network` flag of the `dapr init` command). Note that specifying the flag on the command line overrides any set environment variable. diff --git a/daprdocs/content/en/reference/cli/dapr-run.md b/daprdocs/content/en/reference/cli/dapr-run.md index ef03ae703..995211012 100644 --- a/daprdocs/content/en/reference/cli/dapr-run.md +++ b/daprdocs/content/en/reference/cli/dapr-run.md @@ -28,7 +28,8 @@ dapr run [flags] [command] | `--app-port`, `-p` | `APP_PORT` | | The port your application is listening on | | `--app-protocol`, `-P` | | `http` | The protocol Dapr uses to talk to the application. Valid values are: `http` or `grpc` | | `--app-ssl` | | `false` | Enable https when Dapr invokes the application | -| `--components-path`, `-d` | | Linux/Mac: `$HOME/.dapr/components`
Windows: `%USERPROFILE%\.dapr\components` | The path for components directory | +| `--components-path`, `-d` | | Linux/Mac: `$HOME/.dapr/components`
Windows: `%USERPROFILE%\.dapr\components` | **Deprecated** in favor of `--resources-path` | +| `--resources-path`, `-d` | | Linux/Mac: `$HOME/.dapr/components`
Windows: `%USERPROFILE%\.dapr\components` | The path for components directory | | `--config`, `-c` | | Linux/Mac: `$HOME/.dapr/config.yaml`
Windows: `%USERPROFILE%\.dapr\config.yaml` | Dapr configuration file | | `--dapr-grpc-port` | `DAPR_GRPC_PORT` | `50001` | The gRPC port for Dapr to listen on | | `--dapr-http-port` | `DAPR_HTTP_PORT` | `3500` | The HTTP port for Dapr to listen on | diff --git a/daprdocs/content/en/reference/components-reference/supported-bindings/mqtt.md b/daprdocs/content/en/reference/components-reference/supported-bindings/mqtt3.md similarity index 93% rename from daprdocs/content/en/reference/components-reference/supported-bindings/mqtt.md rename to daprdocs/content/en/reference/components-reference/supported-bindings/mqtt3.md index 17a6cecaf..9e4824d83 100644 --- a/daprdocs/content/en/reference/components-reference/supported-bindings/mqtt.md +++ b/daprdocs/content/en/reference/components-reference/supported-bindings/mqtt3.md @@ -1,15 +1,16 @@ --- type: docs -title: "MQTT binding spec" -linkTitle: "MQTT" -description: "Detailed documentation on the MQTT binding component" +title: "MQTT3 binding spec" +linkTitle: "MQTT3" +description: "Detailed documentation on the MQTT3 binding component" aliases: + - "/operations/components/setup-bindings/supported-bindings/mqtt3/" - "/operations/components/setup-bindings/supported-bindings/mqtt/" --- ## Component format -To setup MQTT binding create a component of type `bindings.mqtt`. See [this guide]({{< ref "howto-bindings.md#1-create-a-binding" >}}) on how to create and apply a binding configuration. +To setup a MQTT3 binding create a component of type `bindings.mqtt3`. See [this guide]({{< ref "howto-bindings.md#1-create-a-binding" >}}) on how to create and apply a binding configuration. ```yaml apiVersion: dapr.io/v1alpha1 @@ -17,7 +18,7 @@ kind: Component metadata: name: spec: - type: bindings.mqtt + type: bindings.mqtt3 version: v1 metadata: - name: url @@ -63,7 +64,7 @@ kind: Component metadata: name: mqtt-binding spec: - type: bindings.mqtt + type: bindings.mqtt3 version: v1 metadata: - name: url @@ -103,7 +104,7 @@ metadata: name: mqtt-binding namespace: default spec: - type: bindings.mqtt + type: bindings.mqtt3 version: v1 metadata: - name: consumerID diff --git a/daprdocs/content/en/reference/components-reference/supported-locks/redis-lock.md b/daprdocs/content/en/reference/components-reference/supported-locks/redis-lock.md index ca6c2b54b..7c39c9f6e 100644 --- a/daprdocs/content/en/reference/components-reference/supported-locks/redis-lock.md +++ b/daprdocs/content/en/reference/components-reference/supported-locks/redis-lock.md @@ -85,8 +85,8 @@ The above example uses secrets as plain strings. It is recommended to use a secr | enableTLS | N | If the Redis instance supports TLS with public certificates, can be configured to be enabled or disabled. Defaults to `"false"` | `"true"`, `"false"` | maxRetries | N | Maximum number of retries before giving up. Defaults to `3` | `5`, `10` | maxRetryBackoff | N | Maximum backoff between each retry. Defaults to `2` seconds; `"-1"` disables backoff. | `3000000000` -| failover | N | Property to enabled failover configuration. Needs sentinalMasterName to be set. The redisHost should be the sentinel host address. See [Redis Sentinel Documentation](https://redis.io/docs/manual/sentinel/). Defaults to `"false"` | `"true"`, `"false"` -| sentinelMasterName | N | The sentinel master name. See [Redis Sentinel Documentation](https://redis.io/docs/manual/sentinel/) | `""`, `"127.0.0.1:6379"` +| failover | N | Property to enabled failover configuration. Needs sentinelMasterName to be set. The redisHost should be the sentinel host address. See [Redis Sentinel Documentation](https://redis.io/docs/manual/sentinel/). Defaults to `"false"` | `"true"`, `"false"` +| sentinelMasterName | N | The sentinel master name. See [Redis Sentinel Documentation](https://redis.io/docs/manual/sentinel/) | `"mymaster"` | redeliverInterval | N | The interval between checking for pending messages to redelivery. Defaults to `"60s"`. `"0"` disables redelivery. | `"30s"` | processingTimeout | N | The amount time a message must be pending before attempting to redeliver it. Defaults to `"15s"`. `"0"` disables redelivery. | `"30s"` | redisType | N | The type of redis. There are two valid values, one is `"node"` for single node mode, the other is `"cluster"` for redis cluster mode. Defaults to `"node"`. | `"cluster"` diff --git a/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-wasm.md b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-wasm.md index 343b25a12..e95c6671a 100644 --- a/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-wasm.md +++ b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-wasm.md @@ -14,10 +14,10 @@ extension. The Wasm [HTTP middleware]({{< ref middleware.md >}}) allows you to rewrite a request URI with custom logic compiled to a Wasm binary. In other words, you can extend Dapr using external files that are not pre-compiled into the `daprd` -binary. Dapr embeds [wazero][https://wazero.io] to accomplish this without CGO. +binary. Dapr embeds [wazero](https://wazero.io) to accomplish this without CGO. Wasm modules are loaded from a filesystem path. On Kubernetes, see [mounting -volumes to the Dapr sidecar]({{> kubernetes-volume-mounts.md >}}) to configure +volumes to the Dapr sidecar]({{< ref kubernetes-volume-mounts.md >}}) to configure a filesystem mount that can contain Wasm modules. ## Component format diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-apache-kafka.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-apache-kafka.md index 86d4a350c..a18b8c261 100644 --- a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-apache-kafka.md +++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-apache-kafka.md @@ -337,7 +337,7 @@ To run without Docker, see the getting started guide [here](https://kafka.apache {{% /codetab %}} {{% codetab %}} -To run Kafka on Kubernetes, you can use any Kafka operator, such as [Strimzi](https://strimzi.io/docs/operators/latest/quickstart.html#ref-install-prerequisites-str). +To run Kafka on Kubernetes, you can use any Kafka operator, such as [Strimzi](https://strimzi.io/quickstarts/). {{% /codetab %}} {{< /tabs >}} diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-eventhubs.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-eventhubs.md index 85044b27d..f3bba3c9a 100644 --- a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-eventhubs.md +++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-eventhubs.md @@ -105,6 +105,14 @@ spec: value: "myeventhubstoragecontainer" ``` +## Sending multiple messages + +Azure Event Hubs natively supports sending multiple messages in a single operation. To set the metadata for bulk operations, set the query parameters on the HTTP request or the gRPC metadata as documented [here]({{< ref pubsub_api >}}) + +| Metadata | Default | +|----------|---------| +| `metadata.maxBulkPubBytes` | `1000000` | + ## Create an Azure Event Hub Follow the instructions [here](https://docs.microsoft.com/azure/event-hubs/event-hubs-create) on setting up Azure Event Hubs. diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-jetstream.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-jetstream.md index d2ac9122f..d62a73fe3 100644 --- a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-jetstream.md +++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-jetstream.md @@ -62,12 +62,16 @@ spec: value: false - name: rateLimit value: 1024 - - name: hearbeat + - name: heartbeat value: 15s - name: ackPolicy value: explicit - name: deliverPolicy value: all + - name: domain + value: hub + - name: apiPrefix + value: PREFIX ``` ## Spec metadata fields @@ -94,9 +98,11 @@ spec: | replicas | N | [Replicas] | `3` | | memoryStorage | N | [Memory Storage] | `false` | | rateLimit | N | [Rate Limit] | `1024` | -| hearbeat | N | [Hearbeat] | `10s` | +| heartbeat | N | [Heartbeat] | `10s` | | ackPolicy | N | [Ack Policy] | `explicit` | | deliverPolicy | N | One of: all, last, new, sequence, time | `all` | +| domain | N | [JetStream Leafondes] | `HUB` | +| apiPrefix | N | [JetStream Leafnodes] | `PREFIX` | ## Create a NATS server @@ -160,7 +166,8 @@ nats -s localhost:4222 stream add myStream --subjects mySubject [Replicas]: https://docs.nats.io/jetstream/concepts/consumers#replicas [Memory Storage]: https://docs.nats.io/jetstream/concepts/consumers#memorystorage [Rate Limit]: https://docs.nats.io/jetstream/concepts/consumers#ratelimit -[Hearbeat]: https://docs.nats.io/jetstream/concepts/consumers#hearbeat +[Heartbeat]: https://docs.nats.io/jetstream/concepts/consumers#heartbeat [Ack Policy]: https://docs.nats.io/nats-concepts/jetstream/consumers#ackpolicy +[JetStream Leafonodes]: https://docs.nats.io/running-a-nats-service/configuration/leafnodes/jetstream_leafnodes [Decentralized JWT Authentication/Authorization]: https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro/jwt [NATS token based authentication]: https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro/tokens diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-mqtt.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-mqtt3.md similarity index 92% rename from daprdocs/content/en/reference/components-reference/supported-pubsub/setup-mqtt.md rename to daprdocs/content/en/reference/components-reference/supported-pubsub/setup-mqtt3.md index 1fbfa6105..abcb08314 100644 --- a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-mqtt.md +++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-mqtt3.md @@ -1,15 +1,16 @@ --- type: docs -title: "MQTT" -linkTitle: "MQTT" -description: "Detailed documentation on the MQTT pubsub component" +title: "MQTT3" +linkTitle: "MQTT3" +description: "Detailed documentation on the MQTT3 pubsub component" aliases: + - "/operations/components/setup-pubsub/supported-pubsub/setup-mqtt3/" - "/operations/components/setup-pubsub/supported-pubsub/setup-mqtt/" --- ## Component format -To setup MQTT pubsub create a component of type `pubsub.mqtt`. See [this guide]({{< ref "howto-publish-subscribe.md#step-1-setup-the-pubsub-component" >}}) on how to create and apply a pubsub configuration +To setup a MQTT3 pubsub create a component of type `pubsub.mqtt3`. See [this guide]({{< ref "howto-publish-subscribe.md#step-1-setup-the-pubsub-component" >}}) on how to create and apply a pubsub configuration ```yaml apiVersion: dapr.io/v1alpha1 @@ -17,7 +18,7 @@ kind: Component metadata: name: mqtt-pubsub spec: - type: pubsub.mqtt + type: pubsub.mqtt3 version: v1 metadata: - name: url @@ -59,7 +60,7 @@ kind: Component metadata: name: mqtt-pubsub spec: - type: pubsub.mqtt + type: pubsub.mqtt3 version: v1 metadata: - name: url @@ -96,7 +97,7 @@ kind: Component metadata: name: mqtt-pubsub spec: - type: pubsub.mqtt + type: pubsub.mqtt3 version: v1 metadata: - name: consumerID @@ -119,7 +120,7 @@ The above example uses secrets as plain strings. It is recommended to use a secr Note that in the case, the value of the consumer ID is random every time Dapr restarts, so we are setting `cleanSession` to true as well. -## Create a MQTT broker +## Create a MQTT3 broker {{< tabs "Self-Hosted" "Kubernetes">}} @@ -134,7 +135,7 @@ You can then interact with the server using the client port: `mqtt://localhost:1 {{% /codetab %}} {{% codetab %}} -You can run a MQTT broker in kubernetes using following yaml: +You can run a MQTT3 broker in kubernetes using following yaml: ```yaml apiVersion: apps/v1 diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-solace-amqp.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-solace-amqp.md new file mode 100644 index 000000000..6bfe09f49 --- /dev/null +++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-solace-amqp.md @@ -0,0 +1,113 @@ +--- +type: docs +title: "Solace-AMQP" +linkTitle: "Solace-AMQP" +description: "Detailed documentation on the Solace-AMQP pubsub component" +aliases: + - "/operations/components/setup-pubsub/supported-pubsub/setup-solace-amqp/" +--- + +## Component format + +To setup Solace-AMQP pub/sub, create a component of type `pubsub.solace.amqp`. See [this guide]({{< ref "howto-publish-subscribe.md#step-1-setup-the-pubsub-component" >}}) on how to create and apply a pub/sub configuration. + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: solace +spec: + type: pubsub.solace.amqp + version: v1 + metadata: + - name: url + value: 'amqp://localhost:5672' + - name: username + value: 'default' + - name: password + value: 'default' +``` + +{{% alert title="Warning" color="warning" %}} +The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described [here]({{< ref component-secrets.md >}}). +{{% /alert %}} + +## Spec metadata fields + +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| url | Y | Address of the AMQP broker. Can be `secretKeyRef` to use a secret reference.
Use the **`amqp://`** URI scheme for non-TLS communication.
Use the **`amqps://`** URI scheme for TLS communication. | `"amqp://host.domain[:port]"` +| username | Y | The username to connect to the broker. Only required if anonymous is not specified or set to `false` .| `default` +| password | Y | The password to connect to the broker. Only required if anonymous is not specified or set to `false`. | `default` +| anonymous | N | To connect to the broker without credential validation. Only works if enabled on the broker. A username and password would not be required if this is set to `true`. | `true` +| caCert | Required for using TLS | Certificate Authority (CA) certificate in PEM format for verifying server TLS certificates. | `"-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----"` +| clientCert | Required for using TLS | TLS client certificate in PEM format. Must be used with `clientKey`. | `"-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----"` +| clientKey | Required for using TLS | TLS client key in PEM format. Must be used with `clientCert`. Can be `secretKeyRef` to use a secret reference. | `"-----BEGIN RSA PRIVATE KEY-----\n\n-----END RSA PRIVATE KEY-----"` + +### Communication using TLS + +To configure communication using TLS: + +1. Ensure that the Solace broker is configured to support certificates. +1. Provide the `caCert`, `clientCert`, and `clientKey` metadata in the component configuration. + +For example: + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: solace +spec: + type: pubsub.solace.amqp + version: v1 + metadata: + - name: url + value: "amqps://host.domain[:port]" + - name: username + value: 'default' + - name: password + value: 'default' + - name: caCert + value: ${{ myLoadedCACert }} + - name: clientCert + value: ${{ myLoadedClientCert }} + - name: clientKey + secretKeyRef: + name: mySolaceClientKey + key: mySolaceClientKey +auth: + secretStore: +``` + +> While the `caCert` and `clientCert` values may not be secrets, they can be referenced from a Dapr secret store as well for convenience. + +### Publishing/subscribing to topics and queues + +By default, messages are published and subscribed over topics. If you would like your destination to be a queue, prefix the topic with `queue:` and the Solace AMQP component will connect to a queue. + +## Create a Solace broker + +{{< tabs "Self-Hosted" "SaaS">}} + +{{% codetab %}} +You can run a Solace broker [locally using Docker](https://hub.docker.com/r/solace/solace-pubsub-standard): + +```bash +docker run -d -p 8080:8080 -p 55554:55555 -p 8008:8008 -p 1883:1883 -p 8000:8000 -p 5672:5672 -p 9000:9000 -p 2222:2222 --shm-size=2g --env username_admin_globalaccesslevel=admin --env username_admin_password=admin --name=solace solace/solace-pubsub-standard +``` + +You can then interact with the server using the client port: `mqtt://localhost:5672` +{{% /codetab %}} + +{{% codetab %}} +You can also sign up for a free SaaS broker on [Solace Cloud](https://console.solace.cloud/login/new-account?product=event-streaming). +{{% /codetab %}} + +{{< /tabs >}} + +## Related links + +- [Basic schema for a Dapr component]({{< ref component-schema >}}) +- Read [this guide]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components +- [Pub/sub building block]({{< ref pubsub >}}) \ No newline at end of file diff --git a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-azure-blobstorage.md b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-azure-blobstorage.md index aadc6a5de..f4922097c 100644 --- a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-azure-blobstorage.md +++ b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-azure-blobstorage.md @@ -133,7 +133,7 @@ kubectl apply -f azureblob.yaml ### Running locally -To run locally, create a `components` dir containing the YAML file and provide the path to the `dapr run` command with the flag `--components-path`. +To run locally, create a `components` dir containing the YAML file and provide the path to the `dapr run` command with the flag `--resources-path`. This state store creates a blob file in the container and puts raw state inside it. diff --git a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-dynamodb.md b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-dynamodb.md index 3e08b9f7c..a3b1781de 100644 --- a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-dynamodb.md +++ b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-dynamodb.md @@ -21,7 +21,7 @@ spec: version: v1 metadata: - name: table - value: "mytable" + value: "Contracts" - name: accessKey value: "AKIAIOSFODNN7EXAMPLE" # Optional - name: secretKey @@ -34,6 +34,8 @@ spec: value: "myTOKEN" # Optional - name: ttlAttributeName value: "expiresAt" # Optional + - name: partitionKey + value: "ContractID" # Optional ``` {{% alert title="Warning" color="warning" %}} @@ -42,19 +44,20 @@ The above example uses secrets as plain strings. It is recommended to use a secr ## Primary Key -In order to use DynamoDB as a Dapr state store, the table must have a primary key named `key`. +In order to use DynamoDB as a Dapr state store, the table must have a primary key named `key`. See the section [Partition Keys]({{< ref "setup-dynamodb.md#partition-keys" >}}) for an option to change this behavior. ## Spec metadata fields | Field | Required | Details | Example | |--------------------|:--------:|---------|---------| -| table | Y | name of the DynamoDB table to use | `"mytable"` +| table | Y | name of the DynamoDB table to use | `"Contracts"` | accessKey | N | ID of the AWS account with appropriate permissions to SNS and SQS. Can be `secretKeyRef` to use a secret reference | `"AKIAIOSFODNN7EXAMPLE"` | secretKey | N | Secret for the AWS user. Can be `secretKeyRef` to use a secret reference |`"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"` | region | N | The AWS region to the instance. See this page for valid regions: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html. Ensure that DynamoDB are available in that region.| `"us-east-1"` | endpoint | N |AWS endpoint for the component to use. Only used for local development. The `endpoint` is unncessary when running against production AWS | `"http://localhost:4566"` | sessionToken | N |AWS session token to use. A session token is only required if you are using temporary security credentials. | `"TOKEN"` | ttlAttributeName | N |The table attribute name which should be used for TTL. | `"expiresAt"` +| partitionKey | N |The table primary key or partition key attribute name. This field is used to replace the default primary key attribute name `"key"`. See the section [Partition Keys]({{< ref "setup-dynamodb.md#partition-keys" >}}). | `"ContractID"` {{% alert title="Important" color="warning" %}} When running the Dapr sidecar (daprd) with your application on EKS (AWS Kubernetes), if you're using a node/pod that has already been attached to an IAM policy defining access to AWS resources, you **must not** provide AWS access-key, secret-key, and tokens in the definition of the component spec you're using. @@ -70,6 +73,87 @@ In order to use DynamoDB TTL feature, you must enable TTL on your table and defi The attribute name must be defined in the `ttlAttributeName` field. See official [AWS docs](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html). +## Partition Keys + +By default, the DynamoDB state store component uses the table attribute name `key` as primary/partition key in the DynamoDB table. +This can be overridden by specifying a metadata field in the component configuration with a key of `partitionKey` and a value of the desired attribute name. + +To learn more about DynamoDB primary/partition keys, read the [AWS DynamoDB Developer Guide.](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey) + +The following `statestore.yaml` file shows how to configure the DynamoDB state store component to use the partition key attribute name of `ContractID`: + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: statestore +spec: + type: state.aws.dynamodb + version: v1 + metadata: + - name: table + value: "Contracts" + - name: partitionKey + value: "ContractID" +``` + +The above component specification assumes the following DynamoDB Table Layout: + +```console +{ + "Table": { + "AttributeDefinitions": [ + { + "AttributeName": "ContractID", + "AttributeType": "S" + } + ], + "TableName": "Contracts", + "KeySchema": [ + { + "AttributeName": "ContractID", + "KeyType": "HASH" + } + ], +} +``` + +The following operation passes `"A12345"` as the value for `key`, and based on the component specification provided above, the Dapr runtime will replace the `key` attribute name +with `ContractID` as the Partition/Primary Key sent to DynamoDB: + +```shell +$ dapr run --app-id contractsprocessing --app-port ... + +$ curl -X POST http://localhost:3500/v1.0/state/ \ + -H "Content-Type: application/json" + -d '[ + { + "key": "A12345", + "value": "Dapr Contract" + } + ]' +``` + +The following AWS CLI Command displays the contents of the DynamoDB `Contracts` table: +```shell +$ aws dynamodb get-item \ + --table-name Contracts \ + --key '{"ContractID":{"S":"contractsprocessing||A12345"}}' +{ + "Item": { + "value": { + "S": "Dapr Contract" + }, + "etag": { + "S": "....." + }, + "ContractID": { + "S": "contractsprocessing||A12345" + } + } +} +``` + ## Related links - [Basic schema for a Dapr component]({{< ref component-schema >}}) diff --git a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-redis.md b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-redis.md index 12c4de8da..d19c817d3 100644 --- a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-redis.md +++ b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-redis.md @@ -360,7 +360,7 @@ Memory Store does not support modules and cannot be used with query. Next is to start a Dapr application. Refer to this [component configuration file](../../../../developing-applications/building-blocks/state-management/query-api-examples/components/redis/redis.yml), which contains query indexing schemas. Make sure to modify the `redisHost` to reflect the local forwarding port which `redislabs/rejson` uses. ```bash -dapr run --app-id demo --dapr-http-port 3500 --components-path query-api-examples/components/redis +dapr run --app-id demo --dapr-http-port 3500 --resources-path query-api-examples/components/redis ``` Now populate the state store with the employee dataset, so you can then query it later. diff --git a/daprdocs/data/components/bindings/generic.yaml b/daprdocs/data/components/bindings/generic.yaml index 4cbd411bb..c093d9bb2 100644 --- a/daprdocs/data/components/bindings/generic.yaml +++ b/daprdocs/data/components/bindings/generic.yaml @@ -54,8 +54,8 @@ features: input: false output: true -- component: MQTT - link: mqtt +- component: MQTT3 + link: mqtt3 state: Beta version: v1 since: "1.7" diff --git a/daprdocs/data/components/pubsub/generic.yaml b/daprdocs/data/components/pubsub/generic.yaml index 58fde998f..6978dc7dd 100644 --- a/daprdocs/data/components/pubsub/generic.yaml +++ b/daprdocs/data/components/pubsub/generic.yaml @@ -28,8 +28,8 @@ state: Beta version: v1 since: "1.7" -- component: MQTT - link: setup-mqtt +- component: MQTT3 + link: setup-mqtt3 state: Stable version: v1 since: "1.7" @@ -48,3 +48,8 @@ state: Alpha version: v1 since: "1.8" +- component: Solace-AMQP + link: setup-solace-amqp + state: Alpha + version: v1 + since: "1.10" diff --git a/daprdocs/data/components/state_stores/aws.yaml b/daprdocs/data/components/state_stores/aws.yaml index 65440d580..e8af47bc1 100644 --- a/daprdocs/data/components/state_stores/aws.yaml +++ b/daprdocs/data/components/state_stores/aws.yaml @@ -1,8 +1,8 @@ - component: AWS DynamoDB link: setup-dynamodb - state: Alpha + state: Stable version: v1 - since: "1.0" + since: "1.10" features: crud: true transactions: false diff --git a/daprdocs/layouts/partials/components/bindings.html b/daprdocs/layouts/partials/components/bindings.html index 31fa0c58f..1f590db2b 100644 --- a/daprdocs/layouts/partials/components/bindings.html +++ b/daprdocs/layouts/partials/components/bindings.html @@ -21,11 +21,22 @@ {{ range sort $components "component" }} - {{ .component - }} + {{ .component }} + + + {{ if .features.input }} + ✅ + {{else}} + Input binding not supported + {{ end }} + + + {{ if .features.output }} + ✅ + {{else}} + Output binding not supported + {{ end }} - {{ if .features.input }}✅{{else}}{{ end }} - {{ if .features.output }}✅{{else}}{{ end }} {{ .state }} {{ .version }} {{ .since }} diff --git a/daprdocs/layouts/partials/components/configuration-stores.html b/daprdocs/layouts/partials/components/configuration-stores.html index d9d35b134..19a123a73 100644 --- a/daprdocs/layouts/partials/components/configuration-stores.html +++ b/daprdocs/layouts/partials/components/configuration-stores.html @@ -13,8 +13,7 @@ {{ range sort $components "component" }} - {{ .component - }} + {{ .component }} {{ .state }} {{ .version }} diff --git a/daprdocs/layouts/partials/components/description.html b/daprdocs/layouts/partials/components/description.html index 7cc5a1bf6..770fa975b 100644 --- a/daprdocs/layouts/partials/components/description.html +++ b/daprdocs/layouts/partials/components/description.html @@ -1,7 +1,6 @@

Table captions:

-

Status: Component - certification status

+

Status: component certification status

-

Since: defines from which Dapr Runtime version, the component is in the current status

+

Since: the version of the Dapr Runtime in which the component first moved to the current status

-

Component version: defines the version of the component

+

Component version: the version of the component

diff --git a/daprdocs/layouts/partials/components/locks.html b/daprdocs/layouts/partials/components/locks.html index 4039e5eb0..109ba9ec8 100644 --- a/daprdocs/layouts/partials/components/locks.html +++ b/daprdocs/layouts/partials/components/locks.html @@ -13,8 +13,7 @@ {{ range sort $components "component" }} - {{ .component - }} + {{ .component }} {{ .state }} {{ .version }} diff --git a/daprdocs/layouts/partials/components/middleware.html b/daprdocs/layouts/partials/components/middleware.html index c98f9e4c2..32a1486f2 100644 --- a/daprdocs/layouts/partials/components/middleware.html +++ b/daprdocs/layouts/partials/components/middleware.html @@ -13,8 +13,7 @@ {{ range sort $components "component" }} - {{ .component - }} + {{ .component }} {{ .description | markdownify}} {{ .state }} diff --git a/daprdocs/layouts/partials/components/name-resolution.html b/daprdocs/layouts/partials/components/name-resolution.html index 816873583..a16dd0bc5 100644 --- a/daprdocs/layouts/partials/components/name-resolution.html +++ b/daprdocs/layouts/partials/components/name-resolution.html @@ -15,8 +15,7 @@ {{ range sort $components "component" }} - {{ .component - }} + {{ .component }} {{ .state }} {{ .version }} diff --git a/daprdocs/layouts/partials/components/pubsub.html b/daprdocs/layouts/partials/components/pubsub.html index 244a6f623..01c80e7ce 100644 --- a/daprdocs/layouts/partials/components/pubsub.html +++ b/daprdocs/layouts/partials/components/pubsub.html @@ -16,8 +16,7 @@ {{ range sort $components "component" }} - {{ .component - }} + {{ .component }} {{ .state }} {{ .version }} diff --git a/daprdocs/layouts/partials/components/secret-stores.html b/daprdocs/layouts/partials/components/secret-stores.html index 05d105bfb..2412f8b1d 100644 --- a/daprdocs/layouts/partials/components/secret-stores.html +++ b/daprdocs/layouts/partials/components/secret-stores.html @@ -27,10 +27,16 @@ {{ range sort $components "component" }} - {{ .component - }} + + {{ .component }} + + + {{ if .features.multipleKeyValuesPerSecret }} + ✅ + {{else}} + Multiple Key-Values Per Secret: Not supported + {{ end }} - {{ if .features.multipleKeyValuesPerSecret }}✅{{else}}{{ end }} {{ .state }} {{ .version }} {{ .since }} diff --git a/daprdocs/layouts/partials/components/state-stores.html b/daprdocs/layouts/partials/components/state-stores.html index 35d28d46b..7d1e4693a 100644 --- a/daprdocs/layouts/partials/components/state-stores.html +++ b/daprdocs/layouts/partials/components/state-stores.html @@ -24,16 +24,51 @@ {{ range sort $components "component" }} - {{ .component - }} + + {{ .component }} + + + {{ if .features.crud }} + ✅ + {{else}} + CRUD: Not supported + {{ end }} + + + {{ if .features.transactions }} + ✅ + {{else}} + Transactions: Not supported + {{ end }} + + + {{ if .features.etag }} + ✅ + {{else}} + ETag: Not supported + {{ end }} + + + {{ if .features.ttl }} + ✅ + {{else}} + TTL: Not supported + {{ end }} + + + {{ if (and .features.transactions .features.etag) }} + ✅ + {{else}} + Actors: Not supported + {{ end }} + + + {{ if .features.query }} + ✅ + {{else}} + Query: Not supported + {{ end }} - {{ if .features.crud }}✅{{else}}{{ end }} - {{ if .features.transactions }}✅{{else}}{{ end }} - {{ if .features.etag }}✅{{else}}{{ end }} - {{ if .features.ttl }}✅{{else}}{{ end }} - {{ if (and .features.transactions .features.etag) }}✅{{else}}{{ end }} - {{ if .features.query }}✅{{else}}{{ end }} {{ .state }} {{ .version }} {{ .since }} diff --git a/daprdocs/static/images/configuration-quickstart/configuration-quickstart-flow.png b/daprdocs/static/images/configuration-quickstart/configuration-quickstart-flow.png new file mode 100644 index 000000000..29dc6f44c Binary files /dev/null and b/daprdocs/static/images/configuration-quickstart/configuration-quickstart-flow.png differ