From 73da9970b38b57670363f867acf7e495b5f1ab63 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Wed, 16 Dec 2020 13:17:52 -0800 Subject: [PATCH 01/39] Add Python submodule --- .gitmodules | 4 ++++ daprdocs/sdkdocs/python | 1 + sdkdocs/python | 1 + 3 files changed, 6 insertions(+) create mode 160000 daprdocs/sdkdocs/python create mode 160000 sdkdocs/python diff --git a/.gitmodules b/.gitmodules index 9d1226e9f..5101acdce 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +1,7 @@ [submodule "daprdocs/themes/docsy"] path = daprdocs/themes/docsy url = https://github.com/google/docsy.git +[submodule "sdkdocs/python"] + path = sdkdocs/python + url = https://github.com/dapr/python-sdk.git + \ No newline at end of file diff --git a/daprdocs/sdkdocs/python b/daprdocs/sdkdocs/python new file mode 160000 index 000000000..fa1116c64 --- /dev/null +++ b/daprdocs/sdkdocs/python @@ -0,0 +1 @@ +Subproject commit fa1116c640f7c30d6295ce1033475032a4a9c0d3 diff --git a/sdkdocs/python b/sdkdocs/python new file mode 160000 index 000000000..fa1116c64 --- /dev/null +++ b/sdkdocs/python @@ -0,0 +1 @@ +Subproject commit fa1116c640f7c30d6295ce1033475032a4a9c0d3 From 60f474cef4f82d88746e596b5e64b59ad2f64fc2 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Wed, 16 Dec 2020 13:21:03 -0800 Subject: [PATCH 02/39] Add python submodule and mount --- daprdocs/config.toml | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/daprdocs/config.toml b/daprdocs/config.toml index 127ca3edf..f0e152602 100644 --- a/daprdocs/config.toml +++ b/daprdocs/config.toml @@ -2,14 +2,13 @@ baseURL = "https://v1-rc2.docs.dapr.io/" title = "Dapr Docs" theme = "docsy" +disableFastRender = true enableRobotsTXT = true enableGitInfo = true # Language Configuration languageCode = "en-us" -contentDir = "content/en" -defaultContentLanguage = "en" # Disable categories & tags disableKinds = ["taxonomy", "term"] @@ -18,6 +17,30 @@ disableKinds = ["taxonomy", "term"] [services.googleAnalytics] id = "UA-149338238-3" +# Mounts +[module] + [[module.mounts]] + source = "content/en" + target = "content" + [[module.mounts]] + source = "static" + target = "static" + [[module.mounts]] + source = "layouts" + target = "layouts" + [[module.mounts]] + source = "data" + target = "data" + [[module.mounts]] + source = "assets" + target = "assets" + [[module.mounts]] + source = "archetypes" + target = "archetypes" + [[module.mounts]] + source = "../sdkdocs/python/daprdocs/content" + target = "content/developing-applications/sdks/python" + # Markdown Engine - Allow inline html [markup] [markup.goldmark] From 7b58276be0684196b9b839975854f779f969ce1e Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Wed, 16 Dec 2020 13:21:53 -0800 Subject: [PATCH 03/39] Update SDK docs --- .../en/developing-applications/sdks/_index.md | 17 +------ .../sdks/sdk-overview.md | 44 +++++++++++++++++++ ...{serialization.md => sdk-serialization.md} | 5 ++- 3 files changed, 49 insertions(+), 17 deletions(-) create mode 100644 daprdocs/content/en/developing-applications/sdks/sdk-overview.md rename daprdocs/content/en/developing-applications/sdks/{serialization.md => sdk-serialization.md} (97%) diff --git a/daprdocs/content/en/developing-applications/sdks/_index.md b/daprdocs/content/en/developing-applications/sdks/_index.md index a905eaabf..fe494277f 100644 --- a/daprdocs/content/en/developing-applications/sdks/_index.md +++ b/daprdocs/content/en/developing-applications/sdks/_index.md @@ -4,19 +4,4 @@ title: "SDKs" linkTitle: "SDKs" weight: 20 description: "Use your favorite languages with Dapr" ---- - -### .NET -See the [.NET SDK repository](https://github.com/dapr/dotnet-sdk) - -### Java -See the [Java SDK repository](https://github.com/dapr/java-sdk) - -### Go -See the [Go SDK repository](https://github.com/dapr/go-sdk) - -### Python -See the [Python SDK repository](https://github.com/dapr/python-sdk) - -### Javascript -See the [Javascript SDK repository](https://github.com/dapr/js-sdk) \ No newline at end of file +--- \ No newline at end of file diff --git a/daprdocs/content/en/developing-applications/sdks/sdk-overview.md b/daprdocs/content/en/developing-applications/sdks/sdk-overview.md new file mode 100644 index 000000000..6282879c3 --- /dev/null +++ b/daprdocs/content/en/developing-applications/sdks/sdk-overview.md @@ -0,0 +1,44 @@ +--- +type: docs +title: "Overview of Dapr SDKs" +linkTitle: "Overview" +description: "An overview of the languages and capabilities of the Dapr SDKs" +weight: 1000 +--- + +The Dapr SDKs are the easiest way for you to get Dapr into your application. Choose your favorite language to get started today! + +## SDK capabilities + +- **Client SDK**: The Dapr client allows you to invoke Dapr building block APIs and perform actions such as: + - **Invoke** methods on other services + - Store and get **state** + - **Publish** messages to topics + - **Subscribe** to topics + - Interact with external resources through input and output **bindings** + - Get **secrets** from secret stores + - Interact with **virtual actors** +- **Service SDK**: The Dapr service allows you to create services that can: + - Be **invoked** by other services + - **Subscribe** to topics +- **Actor SDK**: The Dapr Actor SDK allows you to build virtual actors with: + - Methods that can be **invoked** by other services + - **State** that can be stored and retrieved + - **Timers** with callbacks + - Persistent **reminders** + +## SDK languages + +| Language | State | Client SDK | Service SDK | Actor SDK | +|----------|:-----:|:----------:|:-----------:|:---------:| +| [.NET](https://github.com/dapr/dotnet-sdk) | In Development | ✔ | ✔ (ASP.NET) | ✔ | +| [Python](https://github.com/dapr/python-sdk) | In Development | ✔ | ✔ | ✔ | +| [Java](https://github.com/dapr/java-sdk) | In Development | ✔ | ✔ (Spring Boot) | ✔ | +| [Go](https://github.com/dapr/go-sdk) | In Development | ✔ | ✔ | | +| [C++](https://github.com/dapr/cpp-sdk) | Backlog | ✔ | | +| [Rust]() | Backlog | ✔ | | | +| [Javascript]() | Backlog | ✔ | | + +## Further reading + +- [Serialization in the Dapr SDKs]({{< ref sdk-serialization.md >}}) \ No newline at end of file diff --git a/daprdocs/content/en/developing-applications/sdks/serialization.md b/daprdocs/content/en/developing-applications/sdks/sdk-serialization.md similarity index 97% rename from daprdocs/content/en/developing-applications/sdks/serialization.md rename to daprdocs/content/en/developing-applications/sdks/sdk-serialization.md index ae7b30e60..0e8b1f522 100644 --- a/daprdocs/content/en/developing-applications/sdks/serialization.md +++ b/daprdocs/content/en/developing-applications/sdks/sdk-serialization.md @@ -2,7 +2,10 @@ type: docs title: "Serialization in Dapr's SDKs" linkTitle: "Serialization" -weight: 1000 +description: "How Dapr serializes data within the SDKs" +weight: 2000 +aliases: + - '/developing-applications/sdks/serialization/' --- An SDK for Dapr should provide serialization for two use cases. First, for API objects sent through request and response payloads. Second, for objects to be persisted. For both these use cases, a default serialization is provided. In the Java SDK, it is the [DefaultObjectSerializer](https://dapr.github.io/java-sdk/io/dapr/serializer/DefaultObjectSerializer.html) class, providing JSON serialization. From faa545e3d58e34a5c20a89dd5816c126513d8079 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Wed, 16 Dec 2020 13:51:19 -0800 Subject: [PATCH 04/39] Add submodule files --- daprdocs/sdkdocs/python | 1 - sdkdocs/python | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) delete mode 160000 daprdocs/sdkdocs/python diff --git a/daprdocs/sdkdocs/python b/daprdocs/sdkdocs/python deleted file mode 160000 index fa1116c64..000000000 --- a/daprdocs/sdkdocs/python +++ /dev/null @@ -1 +0,0 @@ -Subproject commit fa1116c640f7c30d6295ce1033475032a4a9c0d3 diff --git a/sdkdocs/python b/sdkdocs/python index fa1116c64..95203df1f 160000 --- a/sdkdocs/python +++ b/sdkdocs/python @@ -1 +1 @@ -Subproject commit fa1116c640f7c30d6295ce1033475032a4a9c0d3 +Subproject commit 95203df1fd27632a53bd175f3334b22cb648c0b1 From a56e596d73a8fbf50b5d1af1f79a8cd9cb8a8298 Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Tue, 22 Dec 2020 14:43:12 -0800 Subject: [PATCH 05/39] Adding instructions in getting started index page --- daprdocs/content/en/getting-started/_index.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/daprdocs/content/en/getting-started/_index.md b/daprdocs/content/en/getting-started/_index.md index 51641361c..9fcb3fafe 100644 --- a/daprdocs/content/en/getting-started/_index.md +++ b/daprdocs/content/en/getting-started/_index.md @@ -7,3 +7,44 @@ description: "Get up and running with Dapr" type: docs --- +The recommended way to get started with Dapr, is to setup a local development environment (also referred to as _self-hosted_ mode). This guide will walk you through the required steps to install the Dapr CLI and initialize Dapr on your local machine with components for state store and pub/sub so you get started quickly. + +>**Tip:** If you are looking for an introductory overview of Dapr and learn more about basic Dapr terminology, it is recommended to visit the [concepts section]({{}}) in the docs. + +## Step #1: Install the Dapr CLI + +The Dapr CLI is main tool you'll be using for various Dapr related tasks, most importantly to run an application with a Dapr sidecar but also to review sidecar logs, list running services and run the Dapr dashboard. The Dapr CLI works with both self-hosted and Kubernetes environments. + +Follow the instructions in [How-To: Install the Dapr CLI]({{}}) + +## Step #2: Initialize Dapr + +Now that you have the Dapr CLI installed, it's time to initialize Dapr on your local machine using the CLI. This step will install the Dapr sidecar binaries on your machine, spin up a Zipkin container instance and a Redis container to help you get started quickly with state management and Pub/Sub as well as create default component files for these. + +Follow the instructions in [How-To: Initialize Dapr in your local environment]({{}}) + +>**TIP:** If you would like to initialize Dapr without a dependency on Docker see [this guidance]({{}}). However, if you are just starting with Dapr it is strongly recommended to use the default initialization and the next steps assume you have done so. + +## Step #3: Get and set state using the Dapr API +At this point, the `dapr init` command has ensured your local environment has the Dapr sidecar binaries as well as default component definitions for both state management and a message broker (both using Redis). Now you can use the Dapr CLI to run a Dapr sidecar and try out the state API that will allow you to store and retrieve a state. + +The way it works is depicted in the illustration below: + + + +Instead of a writing an application to call the API you can use the Dapr CLI to just run the sidecar and then send requests directly using `curl`: + +Follow the instructions in [How-To: Save and get state]({{}}) + +## Step 5: Explore the Dapr quickstarts + +Now that you had your first experience calling the Dapr API directly, you can explore how Dapr is used in an application. To get started quickly with existing code that shows various Dapr capabilities, see the Dapr quickstarts and start with the "Hello world" quickstart. + +Explore the [Dapr quickstarts]({{}}) + +>**TIP:** While running these quickstarts, consider trying out some other Dapr CLI commands such as `dapr list` and `dapr dashboard`. + +## Optional next steps +- Explore additional steps to configure a Dapr dev environment - [How-To: Setup a Dapr dev environment]({{}}) +- Try running Dapr on Kubernetes - [How-To: Install Dapr into a Kubernetes cluster]({{}}) +- Setup a non-default state store or message broker - [How-To: Configure state store and pub/sub message broker]({{}}) \ No newline at end of file From 0e84f649bc38d17dcd21e378756bd14b436a2051 Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Tue, 22 Dec 2020 14:47:43 -0800 Subject: [PATCH 06/39] Cosmetic changes to getting started init --- .../state-management/howto-get-save-state.md | 2 +- .../install-dapr-kubernetes.md | 18 ++++---- .../getting-started/install-dapr-selfhost.md | 42 +++++++++++-------- 3 files changed, 37 insertions(+), 25 deletions(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-get-save-state.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-get-save-state.md index c7dcb577b..34adbd792 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-get-save-state.md +++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-get-save-state.md @@ -22,7 +22,7 @@ For the purpose of this how to we'll use a Redis state store, but any state stor {{< tabs "Self-Hosted (CLI)" Kubernetes>}} {{% codetab %}} -When using `Dapr init` in Standalone mode, the Dapr CLI automatically provisions a state store (Redis) and creates the relevant YAML in a `components` directory, which for Linux/MacOS is `$HOME/.dapr/components` and for Windows is `%USERPROFILE%\.dapr\components` +When using `dapr init` in Standalone mode, the Dapr CLI automatically provisions a state store (Redis) and creates the relevant YAML in a `components` directory, which for Linux/MacOS is `$HOME/.dapr/components` and for Windows is `%USERPROFILE%\.dapr\components` To change the state store being used, replace the YAML under `/components` with the file of your choice. {{% /codetab %}} diff --git a/daprdocs/content/en/getting-started/install-dapr-kubernetes.md b/daprdocs/content/en/getting-started/install-dapr-kubernetes.md index 790833b6d..c3663c724 100644 --- a/daprdocs/content/en/getting-started/install-dapr-kubernetes.md +++ b/daprdocs/content/en/getting-started/install-dapr-kubernetes.md @@ -51,11 +51,13 @@ The `-k` flag initializes Dapr on the Kubernetes cluster in your current context Make sure the correct "target" cluster is set. Check `kubectl context (kubectl config kubectl config get-contexts)` to verify. You can set a different context using `kubectl config use-context `. {{% /alert %}} -Run `dapr init -k` on your local machine: +Run on your local machine: ```bash -$ dapr init -k +dapr init -k +``` +``` ⌛ Making the jump to hyperspace... ℹ️ Note: To install Dapr using Helm, see here: https://github.com/dapr/docs/blob/master/getting-started/environment-setup.md#using-helm-advanced @@ -67,7 +69,7 @@ $ dapr init -k The default namespace when initializing Dapr is `dapr-system`. You can override this with the `-n` flag. -``` +```bash dapr init -k -n mynamespace ``` @@ -76,7 +78,7 @@ dapr init -k -n mynamespace You can run Dapr with 3 replicas of each control plane pod with the exception of the Placement pod in the dapr-system namespace for [production scenarios]({{< ref kubernetes-production.md >}}). -``` +```bash dapr init -k --enable-ha=true ``` @@ -84,14 +86,14 @@ dapr init -k --enable-ha=true Dapr is initialized by default with [mTLS]({{< ref "security-concept.md#sidecar-to-sidecar-communication" >}}). You can disable it with: -``` +```bash dapr init -k --enable-mtls=false ``` ### Uninstall Dapr on Kubernetes with CLI ```bash -$ dapr uninstall --kubernetes +dapr uninstall --kubernetes ``` ## Install with Helm (advanced) @@ -130,8 +132,10 @@ The latest Dapr helm chart no longer supports Helm v2. Please migrate from helm Once the chart installation is complete verify the dapr-operator, dapr-placement, dapr-sidecar-injector and dapr-sentry pods are running in the `dapr-system` namespace: ```bash -$ kubectl get pods -n dapr-system -w +kubectl get pods -n dapr-system -w +``` +``` NAME READY STATUS RESTARTS AGE dapr-dashboard-7bd6cbf5bf-xglsr 1/1 Running 0 40s dapr-operator-7bd6cbf5bf-xglsr 1/1 Running 0 40s diff --git a/daprdocs/content/en/getting-started/install-dapr-selfhost.md b/daprdocs/content/en/getting-started/install-dapr-selfhost.md index 4a4736d48..faffcce93 100644 --- a/daprdocs/content/en/getting-started/install-dapr-selfhost.md +++ b/daprdocs/content/en/getting-started/install-dapr-selfhost.md @@ -1,9 +1,9 @@ --- type: docs -title: "How-To: Install Dapr into your local environment" +title: "How-To: Initialize Dapr in your local environment" linkTitle: "Init Dapr locally" weight: 20 -description: "Install Dapr in your local environment for testing and self-hosting" +description: "Initialize Dapr in your local environment for testing and self-hosting" aliases: - /getting-started/install-dapr/ --- @@ -40,31 +40,35 @@ This command downloads and installs Dapr runtime v0.11. To install v1.0-rc2 prev {{< /tabs >}} -1. Run `dapr init`: +1. Run the `init` CLI command: You can install or upgrade to a specific version of the Dapr runtime using `dapr init --runtime-version`. You can find the list of versions in [Dapr Release](https://github.com/dapr/dapr/releases) ```bash - $ dapr init - ⌛ Making the jump to hyperspace... - Downloading binaries and setting up components - ✅ Success! Dapr is up and running. To get started, go here: https://aka.ms/dapr-getting-started - ``` + dapr init + ``` -1. Verify Dapr version with `dapr --version`: +1. Verify Dapr version: ```bash - $ dapr --version + dapr --version + ``` + + Output should look like this: + ``` CLI version: 0.11 Runtime version: 0.11 ``` -1. Verify Dapr containers are running with `docker ps`: +1. Verify Dapr containers are running: + + ```bash + docker ps + ``` Make sure the `daprio/dapr`, `openzipkin/zipkin`, and `redis` container images are all running: - ```bash - $ docker ps + ``` CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 0dda6684dc2e openzipkin/zipkin "/busybox/sh run.sh" 2 minutes ago Up 2 minutes 9410/tcp, 0.0.0.0:9411->9411/tcp dapr_zipkin 9bf6ef339f50 redis "docker-entrypoint.s…" 2 minutes ago Up 2 minutes 0.0.0.0:6379->6379/tcp dapr_redis @@ -76,9 +80,13 @@ This command downloads and installs Dapr runtime v0.11. To install v1.0-rc2 prev {{< tabs "Linux/MacOS" "Windows">}} {{% codetab %}} - Run `ls $HOME/.dapr`: + Run: ```bash - $ ls $HOME/.dapr + ls $HOME/.dapr + ``` + Output should look like so: + + ``` bin components config.yaml ``` {{% /codetab %}} @@ -96,14 +104,14 @@ This command downloads and installs Dapr runtime v0.11. To install v1.0-rc2 prev This cli command removes the placement Dapr container: ```bash -$ dapr uninstall +dapr uninstall ``` {{% alert title="Warning" color="warning" %}} This command won't remove the Redis or Zipkin containers by default, just in case you were using them for other purposes. To remove Redis, Zipkin, Actor Placement container, as well as the default Dapr directory located at `$HOME/.dapr` or `%USERPROFILE%\.dapr\`, run: ```bash -$ dapr uninstall --all +dapr uninstall --all ``` {{% /alert %}} From 3d1b4d5fc52b2342c0322c785d21e3834f741d1e Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Tue, 22 Dec 2020 14:53:13 -0800 Subject: [PATCH 07/39] fixing numbering --- daprdocs/content/en/getting-started/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/getting-started/_index.md b/daprdocs/content/en/getting-started/_index.md index 9fcb3fafe..bd9469bae 100644 --- a/daprdocs/content/en/getting-started/_index.md +++ b/daprdocs/content/en/getting-started/_index.md @@ -36,7 +36,7 @@ Instead of a writing an application to call the API you can use the Dapr CLI to Follow the instructions in [How-To: Save and get state]({{}}) -## Step 5: Explore the Dapr quickstarts +## Step 4: Explore the Dapr quickstarts Now that you had your first experience calling the Dapr API directly, you can explore how Dapr is used in an application. To get started quickly with existing code that shows various Dapr capabilities, see the Dapr quickstarts and start with the "Hello world" quickstart. From 7e0a3fbb4dc3f3083bd84ea13e448a7f0df9b2b5 Mon Sep 17 00:00:00 2001 From: Radoslav Gatev Date: Sun, 3 Jan 2021 21:30:23 +0200 Subject: [PATCH 08/39] Add a comparison with the ratelimit middleware --- .../content/en/operations/configuration/control-concurrency.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/daprdocs/content/en/operations/configuration/control-concurrency.md b/daprdocs/content/en/operations/configuration/control-concurrency.md index 6203bac3b..73279b685 100644 --- a/daprdocs/content/en/operations/configuration/control-concurrency.md +++ b/daprdocs/content/en/operations/configuration/control-concurrency.md @@ -11,6 +11,8 @@ Using Dapr, you can control how many requests and events will invoke your applic *Note that this rate limiting is guaranteed for every event that's coming from Dapr, meaning Pub/Sub events, direct invocation from other services, bindings events etc. Dapr can't enforce the concurrency policy on requests that are coming to your app externally.* +*Note that rate limitting can be achieved by using the **middleware.http.ratelimit**. However, there is an imporant difference between the two approaches. The ratelimit middlware is time bound and limits the number of requests per second, while the app-max-concurrency specifies the number of concurrent requests (and events) at any point of time.* + ## Setting app-max-concurrency Without using Dapr, a developer would need to create some sort of a semaphore in the application and take care of acquiring and releasing it. From 32e40b492132d870b19ae3a612bdad77ba681ba3 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Tue, 5 Jan 2021 11:52:03 -0800 Subject: [PATCH 09/39] Remove # in steps and fix tips --- daprdocs/content/en/getting-started/_index.md | 26 ++++++++++++------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/daprdocs/content/en/getting-started/_index.md b/daprdocs/content/en/getting-started/_index.md index bd9469bae..dddf29ed4 100644 --- a/daprdocs/content/en/getting-started/_index.md +++ b/daprdocs/content/en/getting-started/_index.md @@ -4,28 +4,32 @@ title: "Getting started with Dapr" linkTitle: "Getting started" weight: 20 description: "Get up and running with Dapr" -type: docs +no_list: true --- -The recommended way to get started with Dapr, is to setup a local development environment (also referred to as _self-hosted_ mode). This guide will walk you through the required steps to install the Dapr CLI and initialize Dapr on your local machine with components for state store and pub/sub so you get started quickly. +The recommended way to get started with Dapr is to setup a local development environment (also referred to as [_self-hosted_ mode]({{< ref self-hosted >}})). This guide will walk you through the required steps to install the Dapr CLI and initialize Dapr on your local machine with components for state store and pub/sub so you get started quickly. ->**Tip:** If you are looking for an introductory overview of Dapr and learn more about basic Dapr terminology, it is recommended to visit the [concepts section]({{}}) in the docs. +{{% alert title="Dapr Concepts" color="primary" %}} +If you are looking for an introductory overview of Dapr and learn more about basic Dapr terminology, it is recommended to visit the [concepts section]({{}}) in the docs. +{{% /alert %}} -## Step #1: Install the Dapr CLI +## Step 1: Install the Dapr CLI -The Dapr CLI is main tool you'll be using for various Dapr related tasks, most importantly to run an application with a Dapr sidecar but also to review sidecar logs, list running services and run the Dapr dashboard. The Dapr CLI works with both self-hosted and Kubernetes environments. +The Dapr CLI is main tool you'll be using for various Dapr related tasks. Most importantly it is used to run an application with a Dapr sidecar, but it also can review sidecar logs, list running services, and run the Dapr dashboard. The Dapr CLI works with both [self-hosted]({{< ref self-hosted >}}) and [Kubernetes]({{< ref Kubernetes >}}) environments. Follow the instructions in [How-To: Install the Dapr CLI]({{}}) -## Step #2: Initialize Dapr +## Step 2: Initialize Dapr -Now that you have the Dapr CLI installed, it's time to initialize Dapr on your local machine using the CLI. This step will install the Dapr sidecar binaries on your machine, spin up a Zipkin container instance and a Redis container to help you get started quickly with state management and Pub/Sub as well as create default component files for these. +Now that you have the Dapr CLI installed, it's time to initialize Dapr on your local machine using the CLI. This step will install the Dapr sidecar binaries on your machine, spin up Zipkin and Redis Docker containers, adn create default component files to help you get started quickly with state management and Pub/Sub. Follow the instructions in [How-To: Initialize Dapr in your local environment]({{}}) ->**TIP:** If you would like to initialize Dapr without a dependency on Docker see [this guidance]({{}}). However, if you are just starting with Dapr it is strongly recommended to use the default initialization and the next steps assume you have done so. +{{% alert title="Docker" color="primary" %}} +This guide recommends and assumes you have Docker Desktop installed and initialize Dapr with Docker containers. If you would like to initialize Dapr without a dependency on Docker see [this guidance]({{}}). +{{% /alert %}} -## Step #3: Get and set state using the Dapr API +## Step 3: Get and set state using the Dapr API At this point, the `dapr init` command has ensured your local environment has the Dapr sidecar binaries as well as default component definitions for both state management and a message broker (both using Redis). Now you can use the Dapr CLI to run a Dapr sidecar and try out the state API that will allow you to store and retrieve a state. The way it works is depicted in the illustration below: @@ -42,7 +46,9 @@ Now that you had your first experience calling the Dapr API directly, you can ex Explore the [Dapr quickstarts]({{}}) ->**TIP:** While running these quickstarts, consider trying out some other Dapr CLI commands such as `dapr list` and `dapr dashboard`. +{{% alert title="Additional commands" color="primary" %}} +While running these quickstarts, consider trying out some other Dapr CLI commands such as `dapr list` and `dapr dashboard`. +{{% /alert %}} ## Optional next steps - Explore additional steps to configure a Dapr dev environment - [How-To: Setup a Dapr dev environment]({{}}) From 95a87d20dc3e693566c6dfd5915ab125a925c380 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Wed, 6 Jan 2021 23:33:12 -0800 Subject: [PATCH 10/39] Update python SDK directory --- daprdocs/config.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/config.toml b/daprdocs/config.toml index f0e152602..09f9a83be 100644 --- a/daprdocs/config.toml +++ b/daprdocs/config.toml @@ -38,7 +38,7 @@ id = "UA-149338238-3" source = "archetypes" target = "archetypes" [[module.mounts]] - source = "../sdkdocs/python/daprdocs/content" + source = "../sdkdocs/python/daprdocs/content/en/python-sdk-docs" target = "content/developing-applications/sdks/python" # Markdown Engine - Allow inline html From 62a18296a556f5a7aea92aa39e3e283d34c46607 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Wed, 6 Jan 2021 23:33:31 -0800 Subject: [PATCH 11/39] Update state guide with python and more examples --- .../state-management/howto-get-save-state.md | 378 ++++++++++++++---- 1 file changed, 301 insertions(+), 77 deletions(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-get-save-state.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-get-save-state.md index c7dcb577b..54766ec2f 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-get-save-state.md +++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-get-save-state.md @@ -14,17 +14,25 @@ Dealing with different databases libraries, testing them, handling retries and f Dapr provides state management capabilities that include consistency and concurrency options. In this guide we'll start of with the basics: Using the key/value state API to allow an application to save, get and delete state. +## Pre-requisites + +- [Dapr CLI]({{< ref install-dapr-cli.md >}}) +- Initialized [Dapr environment]({{< ref install-dapr-selfhost.md >}}) + ## Step 1: Setup a state store A state store component represents a resource that Dapr uses to communicate with a database. -For the purpose of this how to we'll use a Redis state store, but any state store from the [supported list]({{< ref supported-state-stores >}}) will work. + +For the purpose of this guide we'll use a Redis state store, but any state store from the [supported list]({{< ref supported-state-stores >}}) will work. {{< tabs "Self-Hosted (CLI)" Kubernetes>}} {{% codetab %}} -When using `Dapr init` in Standalone mode, the Dapr CLI automatically provisions a state store (Redis) and creates the relevant YAML in a `components` directory, which for Linux/MacOS is `$HOME/.dapr/components` and for Windows is `%USERPROFILE%\.dapr\components` +When using `Dapr init` in self-hosted mode, the Dapr CLI automatically provisions a state store (Redis) and creates the relevant YAML in a `components` directory: +- **Linux/MacOS**: `$HOME/.dapr/components` +- **Windows**: `%USERPROFILE%\.dapr\components` -To change the state store being used, replace the YAML under `/components` with the file of your choice. +To optionally change the state store being used, replace the YAML file `statestore.yaml` under `/components` with the file of your choice. {{% /codetab %}} {{% codetab %}} @@ -33,104 +41,105 @@ See the instructions [here]({{< ref "setup-state-store" >}}) on how to setup dif {{< /tabs >}} -## Step 2: Save state +## Step 2: Save and retrieve a single state -The following example shows how to save two key/value pairs in a single call using the state management API. +The following example shows how to a single key/value pair using the Dapr state building block. + +{{% alert title="Note" color="warning" %}} +It is important to set an app-id, as the state keys are prefixed with this value. If you don't set it one is generated for you at runtime, and the next time you run the command a new one will be generated and you will no longer be able to access previously saved state. +{{% /alert %}} {{< tabs "HTTP API (Bash)" "HTTP API (PowerShell)" "Python SDK">}} {{% codetab %}} -Begin by ensuring a Dapr sidecar is running: -```bash -dapr --app-id myapp --port 3500 run -``` -{{% alert title="Note" color="info" %}} -It is important to set an app-id, as the state keys are prefixed with this value. If you don't set it one is generated for you at runtime, and the next time you run the command a new one will be generated and you will no longer be able to access previously saved state. +Begin by launching a Dapr sidecar: -{{% /alert %}} - -Then in a separate terminal run: -```bash -curl -X POST -H "Content-Type: application/json" -d '[{ "key": "key1", "value": "value1"}, { "key": "key2", "value": "value2"}]' http://localhost:3500/v1.0/state/statestore -``` -{{% /codetab %}} - -{{% codetab %}} -Begin by ensuring a Dapr sidecar is running: ```bash dapr --app-id myapp --port 3500 run ``` -{{% alert title="Note" color="info" %}} -It is important to set an app-id, as the state keys are prefixed with this value. If you don't set it one is generated for you at runtime, and the next time you run the command a new one will be generated and you will no longer be able to access previously saved state. - -{{% /alert %}} - -Then in a separate terminal run: -```powershell -Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '[{ "key": "key1", "value": "value1"}, { "key": "key2", "value": "value2"}]' -Uri 'http://localhost:3500/v1.0/state/statestore' -``` -{{% /codetab %}} - -{{% codetab %}} -Make sure to install the Dapr Python SDK with `pip3 install dapr`. Then create a file named `state.py` with: -```python -from dapr.clients import DaprClient -from dapr.clients.grpc._state import StateItem - -with DaprClient() as d: - d.save_states(store_name="statestore", - states=[ - StateItem(key="key1", value="value1"), - StateItem(key="key2", value="value2") - ]) - +Then in a separate terminal save a key/value pair into your statestore: +```bash +curl -X POST -H "Content-Type: application/json" -d '{ "key": "key1", "value": "value1"}' http://localhost:3500/v1.0/state/statestore ``` -Run with `dapr run --app-id myapp run python state.py` - -{{% alert title="Note" color="info" %}} -It is important to set an app-id, as the state keys are prefixed with this value. If you don't set it one is generated for you at runtime, and the next time you run the command a new one will be generated and you will no longer be able to access previously saved state. - -{{% /alert %}} - -{{% /codetab %}} - -{{< /tabs >}} - -## Step 3: Get state - -The following example shows how to get an item by using a key with the state management API: - -{{< tabs "HTTP API (Bash)" "HTTP API (PowerShell)" "Python SDK">}} - -{{% codetab %}} -With the same dapr instance running from above run: +Now get the state you just saved: ```bash curl http://localhost:3500/v1.0/state/statestore/key1 ``` + +You can also restart your sidecar and try retrieving state again to see that state persists separate from the app. {{% /codetab %}} {{% codetab %}} -With the same dapr instance running from above run: + +Begin by launching a Dapr sidecar: + +```bash +dapr --app-id myapp --port 3500 run +``` + +Then in a separate terminal save a key/value pair into your statestore: +```powershell +Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '{"key": "key1", "value": "value1"}' -Uri 'http://localhost:3500/v1.0/state/statestore' +``` + +Now get the state you just saved: ```powershell Invoke-RestMethod -Uri 'http://localhost:3500/v1.0/state/statestore/key1' ``` + +You can also restart your sidecar and try retrieving state again to see that state persists separate from the app. + {{% /codetab %}} {{% codetab %}} -Add the following code to `state.py` from above and run again: + +Save the following to a file named `pythonState.py`: + ```python - data = d.get_state(store_name="statestore", - key="key1", - state_metadata={"metakey": "metavalue"}).data +from dapr.clients import DaprClient + +with DaprClient() as d: + d.save_state(store_name="statestore", key="myFirstKey", value="myFirstValue" ) + print("State has been stored") + + data = d.get_state(store_name="statestore", key="myFirstKey").data print(f"Got value: {data}") + ``` + +Once saved run the following command to launch a Dapr sidecar and run the Python application: + +```bash +dapr --app-id myapp run python pythonState.py +``` + +You should get an output similar to the following, which will show both the Dapr and app logs: + +```md +== DAPR == time="2021-01-06T21:34:33.7970377-08:00" level=info msg="starting Dapr Runtime -- version 0.11.3 -- commit a1a8e11" app_id=Braidbald-Boot scope=dapr.runtime type=log ver=0.11.3 +== DAPR == time="2021-01-06T21:34:33.8040378-08:00" level=info msg="standalone mode configured" app_id=Braidbald-Boot scope=dapr.runtime type=log ver=0.11.3 +== DAPR == time="2021-01-06T21:34:33.8040378-08:00" level=info msg="app id: Braidbald-Boot" app_id=Braidbald-Boot scope=dapr.runtime type=log ver=0.11.3 +== DAPR == time="2021-01-06T21:34:33.9750400-08:00" level=info msg="component loaded. name: statestore, type: state.redis" app_id=Braidbald-Boot scope=dapr.runtime type=log ver=0.11.3 +== DAPR == time="2021-01-06T21:34:33.9760387-08:00" level=info msg="API gRPC server is running on port 51656" app_id=Braidbald-Boot scope=dapr.runtime type=log ver=0.11.3 +== DAPR == time="2021-01-06T21:34:33.9770372-08:00" level=info msg="dapr initialized. Status: Running. Init Elapsed 172.9994ms" app_id=Braidbald-Boot scope=dapr. + +Checking if Dapr sidecar is listening on GRPC port 51656 +Dapr sidecar is up and running. +Updating metadata for app command: python pythonState.py +You are up and running! Both Dapr and your app logs will appear here. + +== APP == State has been stored +== APP == Got value: b'myFirstValue' +``` + {{% /codetab %}} {{< /tabs >}} -## Step 4: Delete state + +## Step 3: Delete state The following example shows how to delete an item by using a key with the state management API: @@ -153,16 +162,231 @@ Try getting state again and note that no value is returned. {{% /codetab %}} {{% codetab %}} -Add the following code to `state.py` from above and run again: + +Update `pythonState.py` with: + ```python - d.delete_state(store_name="statestore"", - key="key1", - state_metadata={"metakey": "metavalue"}) - data = d.get_state(store_name="statestore", - key="key1", - state_metadata={"metakey": "metavalue"}).data +from dapr.clients import DaprClient + +with DaprClient() as d: + d.save_state(store_name="statestore", key="key1", value="value1" ) + print("State has been stored") + + data = d.get_state(store_name="statestore", key="key1").data + print(f"Got value: {data}") + + d.delete_state(store_name="statestore", key="key1") + + data = d.get_state(store_name="statestore", key="key1").data print(f"Got value after delete: {data}") ``` + +Now run your program with: + +```bash +dapr --app-id myapp run python pythonState.py +``` + +You should see an output similar to the following: + +```md +Starting Dapr with id Yakchocolate-Lord. HTTP Port: 59457. gRPC Port: 59458 + +== DAPR == time="2021-01-06T22:55:36.5570696-08:00" level=info msg="starting Dapr Runtime -- version 0.11.3 -- commit a1a8e11" app_id=Yakchocolate-Lord scope=dapr.runtime type=log ver=0.11.3 +== DAPR == time="2021-01-06T22:55:36.5690367-08:00" level=info msg="standalone mode configured" app_id=Yakchocolate-Lord scope=dapr.runtime type=log ver=0.11.3 +== DAPR == time="2021-01-06T22:55:36.7220140-08:00" level=info msg="component loaded. name: statestore, type: state.redis" app_id=Yakchocolate-Lord scope=dapr.runtime type=log ver=0.11.3 +== DAPR == time="2021-01-06T22:55:36.7230148-08:00" level=info msg="API gRPC server is running on port 59458" app_id=Yakchocolate-Lord scope=dapr.runtime type=log ver=0.11.3 +== DAPR == time="2021-01-06T22:55:36.7240207-08:00" level=info msg="dapr initialized. Status: Running. Init Elapsed 154.984ms" app_id=Yakchocolate-Lord scope=dapr.runtime type=log ver=0.11.3 + +Checking if Dapr sidecar is listening on GRPC port 59458 +Dapr sidecar is up and running. +Updating metadata for app command: python pythonState.py +You're up and running! Both Dapr and your app logs will appear here. + +== APP == State has been stored +== APP == Got value: b'value1' +== APP == Got value after delete: b'' +``` {{% /codetab %}} {{< /tabs >}} + +## Step 4: Save and retrieve multiple states + +Dapr also allows you to save and retrieve multiple states in the same call. + +{{< tabs "HTTP API (Bash)" "HTTP API (PowerShell)" "Python SDK">}} + +{{% codetab %}} +With the same dapr instance running from above save two key/value pairs into your statestore: +```bash +curl -X POST -H "Content-Type: application/json" -d '[{ "key": "key1", "value": "value1"}, { "key": "key2", "value": "value2"}]' http://localhost:3500/v1.0/state/statestore +``` + +Now get the states you just saved: +```bash +curl -X POST -H "Content-Type: application/json" -d '{"keys":["key1", "key2"]}' http://localhost:3500/v1.0/state/statestore/bulk +``` +{{% /codetab %}} + +{{% codetab %}} +With the same dapr instance running from above save two key/value pairs into your statestore: +```powershell +Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '[{ "key": "key1", "value": "value1"}, { "key": "key2", "value": "value2"}]' -Uri 'http://localhost:3500/v1.0/state/statestore' +``` + +Now get the states you just saved: +```powershell +Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '{"keys":["key1", "key2"]}' -Uri 'http://localhost:3500/v1.0/state/statestore/bulk' +``` + +{{% /codetab %}} + +{{% codetab %}} + +The `StateItem` object can be used to store multiple Dapr states with the `save_states` and `get_states` methods. + +Update your `pythonState.py` file with the following code: + +```python +from dapr.clients import DaprClient +from dapr.clients.grpc._state import StateItem + +with DaprClient() as d: + s1 = StateItem(key="key1", value="value1") + s2 = StateItem(key="key2", value="value2") + + d.save_states(store_name="statestore", states=[s1,s2]) + print("States have been stored") + + items = d.get_states(store_name="statestore", keys=["key1", "key2"]).items + print(f"Got items: {[i.data for i in items]}") +``` + +Now run your program with: + +```bash +dapr --app-id myapp run python pythonState.py +``` + +You should see an output similar to the following: + +```md +== DAPR == time="2021-01-06T21:54:56.7262358-08:00" level=info msg="starting Dapr Runtime -- version 0.11.3 -- commit a1a8e11" app_id=Musesequoia-Sprite scope=dapr.runtime type=log ver=0.11.3 +== DAPR == time="2021-01-06T21:54:56.7401933-08:00" level=info msg="standalone mode configured" app_id=Musesequoia-Sprite scope=dapr.runtime type=log ver=0.11.3 +== DAPR == time="2021-01-06T21:54:56.8754240-08:00" level=info msg="Initialized name resolution to standalone" app_id=Musesequoia-Sprite scope=dapr.runtime type=log ver=0.11.3 +== DAPR == time="2021-01-06T21:54:56.8844248-08:00" level=info msg="component loaded. name: statestore, type: state.redis" app_id=Musesequoia-Sprite scope=dapr.runtime type=log ver=0.11.3 +== DAPR == time="2021-01-06T21:54:56.8854273-08:00" level=info msg="API gRPC server is running on port 60614" app_id=Musesequoia-Sprite scope=dapr.runtime type=log ver=0.11.3 +== DAPR == time="2021-01-06T21:54:56.8854273-08:00" level=info msg="dapr initialized. Status: Running. Init Elapsed 145.234ms" app_id=Musesequoia-Sprite scope=dapr.runtime type=log ver=0.11.3 + +Checking if Dapr sidecar is listening on GRPC port 60614 +Dapr sidecar is up and running. +Updating metadata for app command: python pythonState.py +You're up and running! Both Dapr and your app logs will appear here. + +== APP == States have been stored +== APP == Got items: [b'value1', b'value2'] +``` + +{{% /codetab %}} + +{{< /tabs >}} + +## Step 5: Perform state transactions + +{{% alert title="Note" color="warning" %}} +State transactions require a state store that supports multi-item transactions. Visit the [supported state stores page]({{< ref supported-state-stores >}}) page for a full list. Note that the default Redis container created in a self-hosted environment supports them. +{{% /alert %}} + +{{< tabs "HTTP API (Bash)" "HTTP API (PowerShell)" "Python SDK" >}} + +{{% codetab %}} +With the same dapr instance running from above perform two state transactions: +```bash +curl -X POST -H "Content-Type: application/json" -d '{"operations": [{"operation":"upsert", "request": {"key": "key1", "value": "newValue1"}}, {"operation":"delete", "request": {"key": "key2"}}]}' http://localhost:3500/v1.0/state/statestore/transaction +``` + +Now see the results of your state transactions: +```bash +curl -X POST -H "Content-Type: application/json" -d '{"keys":["key1", "key2"]}' http://localhost:3500/v1.0/state/statestore/bulk +``` +{{% /codetab %}} + +{{% codetab %}} +With the same dapr instance running from above save two key/value pairs into your statestore: +```powershell +Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '{"operations": [{"operation":"upsert", "request": {"key": "key1", "value": "newValue1"}}, {"operation":"delete", "request": {"key": "key2"}}]}' -Uri 'http://localhost:3500/v1.0/state/statestore' +``` + +Now see the results of your state transactions: +```powershell +Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '{"keys":["key1", "key2"]}' -Uri 'http://localhost:3500/v1.0/state/statestore/bulk' +``` + +{{% /codetab %}} + +{{% codetab %}} + +The `TransactionalStateOperation` can perform a state transaction if your state stores need to be transactional. + +Update your `pythonState.py` file with the following code: + +```python +from dapr.clients import DaprClient +from dapr.clients.grpc._state import StateItem +from dapr.clients.grpc._request import TransactionalStateOperation, TransactionOperationType + +with DaprClient() as d: + s1 = StateItem(key="key1", value="value1") + s2 = StateItem(key="key2", value="value2") + + d.save_states(store_name="statestore", states=[s1,s2]) + print("States have been stored") + + d.execute_transaction( + store_name="statestore", + operations=[ + TransactionalStateOperation(key="key1", data="newValue1", operation_type=TransactionOperationType.upsert), + TransactionalStateOperation(key="key2", data="value2", operation_type=TransactionOperationType.delete) + ] + ) + print("State transactions have been completed") + + items = d.get_states(store_name="statestore", keys=["key1", "key2"]).items + print(f"Got items: {[i.data for i in items]}") +``` + +Now run your program with: + +```bash +dapr run python pythonState.py +``` + +You should see an output similar to the following: + +```md +Starting Dapr with id Singerchecker-Player. HTTP Port: 59533. gRPC Port: 59534 +== DAPR == time="2021-01-06T22:18:14.1246721-08:00" level=info msg="starting Dapr Runtime -- version 0.11.3 -- commit a1a8e11" app_id=Singerchecker-Player scope=dapr.runtime type=log ver=0.11.3 +== DAPR == time="2021-01-06T22:18:14.1346254-08:00" level=info msg="standalone mode configured" app_id=Singerchecker-Player scope=dapr.runtime type=log ver=0.11.3 +== DAPR == time="2021-01-06T22:18:14.2747063-08:00" level=info msg="component loaded. name: statestore, type: state.redis" app_id=Singerchecker-Player scope=dapr.runtime type=log ver=0.11.3 +== DAPR == time="2021-01-06T22:18:14.2757062-08:00" level=info msg="API gRPC server is running on port 59534" app_id=Singerchecker-Player scope=dapr.runtime type=log ver=0.11.3 +== DAPR == time="2021-01-06T22:18:14.2767059-08:00" level=info msg="dapr initialized. Status: Running. Init Elapsed 142.0805ms" app_id=Singerchecker-Player scope=dapr.runtime type=log ver=0.11.3 + +Checking if Dapr sidecar is listening on GRPC port 59534 +Dapr sidecar is up and running. +Updating metadata for app command: python pythonState.py +You're up and running! Both Dapr and your app logs will appear here. + +== APP == State transactions have been completed +== APP == Got items: [b'value1', b''] +``` + +{{% /codetab %}} + +{{< /tabs >}} + +## Next steps + +- Read the full [State API reference]({{< ref state_api.md >}}) +- Try one of the [Dapr SDKs]({{< ref sdks >}}) +- Build a [stateful service]({{< ref howto-stateful-service.md >}}) \ No newline at end of file From e550537481a91d4712dc4ddb4da94bb6b51bc176 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Wed, 6 Jan 2021 23:33:40 -0800 Subject: [PATCH 12/39] Update feature list --- .../state-management-overview.md | 63 ++++++++++--------- 1 file changed, 32 insertions(+), 31 deletions(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md index e684823a3..6c0344431 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md @@ -8,6 +8,8 @@ description: "Overview of the state management building block" ## Introduction + + Dapr offers key/value storage APIs for state management. If a microservice uses state management, it can use these APIs to leverage any of the [supported state stores]({{< ref supported-state-stores.md >}}), without adding or learning a third party SDK. When using state management your application can leverage several features that would otherwise be complicated and error-prone to build yourself such as: @@ -16,39 +18,30 @@ When using state management your application can leverage several features that - Retry policies - Bulk [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) operations -See below for a diagram of state management's high level architecture. - - - ## Features -- [State management API](#state-management-api) -- [State store behaviors](#state-store-behaviors) -- [Concurrency](#concurrency) -- [Consistency](#consistency) -- [Retry policies](#retry-policies) -- [Bulk operations](#bulk-operations) -- [Querying state store directly](#querying-state-store-directly) - ### State management API -Developers can use the state management API to retrieve, save and delete state values by providing keys. +Developers can use the [state management API]({{< ref state_api.md >}}) to retrieve, save and delete state values by providing keys. -Dapr data stores are components. Dapr ships with [Redis](https://redis.io) out-of-box for local development in self hosted mode. Dapr allows you to plug in other data stores as components such as [Azure CosmosDB](https://azure.microsoft.com/services/cosmos-db/), [SQL Server](https://azure.microsoft.com/services/sql-database/), [AWS DynamoDB](https://aws.amazon.com/DynamoDB), [GCP Cloud Spanner](https://cloud.google.com/spanner) and [Cassandra](http://cassandra.apache.org/). +### Pluggable state stores -Visit [State API]({{< ref state_api.md >}}) for more information. +Dapr data stores are modeled as pluggable components, which can be swapped out without any changes to your service code. Check out the [full list of state stores]({{< ref supported-state-stores >}}) to see what Dapr supports. -> **NOTE:** Dapr prefixes state keys with the ID of the current Dapr instance. This allows multiple Dapr instances to share the same state store. +### Configurable state store behavior -### State store behaviors +Dapr allows developers to attach additional metadata to a state operation request that describes how the request is expected to be handled. -Dapr allows developers to attach to a state operation request additional metadata that describes how the request is expected to be handled. For example, you can attach concurrency requirements, consistency requirements, and retry policy to any state operation requests. +For example, you can attach: +- Concurrency requirements +- Consistency requirements +- Retry policies -By default, your application should assume a data store is **eventually consistent** and uses a **last-write-wins** concurrency pattern. On the other hand, if you do attach metadata to your requests, Dapr passes the metadata along with the requests to the state store and expects the data store to fulfill the requests. +By default, your application should assume a data store is **eventually consistent** and uses a **last-write-wins** concurrency pattern. -Not all stores are created equal. To ensure portability of your application, you can query the capabilities of the store and make your code adaptive to different store capabilities. +Not all stores are created equal. To ensure portability of your application you can query the capabilities of the store and make your code adaptive to different store capabilities. -The following table summarizes the capabilities of existing data store implementations. +The following table gives examples of capabilities of popular data store implementations. | Store | Strong consistent write | Strong consistent read | ETag | |-------------------|-------------------------|------------------------|------| @@ -60,13 +53,15 @@ The following table summarizes the capabilities of existing data store implement ### Concurrency -Dapr supports optimistic concurrency control (OCC) using ETags. When a state is requested, Dapr always attaches an **ETag** property to the returned state. And when the user code tries to update or delete a state, it's expected to attach the ETag through the **If-Match** header. The write operation can succeed only when the provided ETag matches with the ETag in the state store. +Dapr supports optimistic concurrency control (OCC) using ETags. When a state is requested, Dapr always attaches an **ETag** property to the returned state. When the user code tries to update or delete a state, it's expected to attach the ETag through the **If-Match** header. The write operation can succeed only when the provided ETag matches with the ETag in the state store. -Dapr chooses OCC because in many applications, data update conflicts are rare because clients are naturally partitioned by business contexts to operate on different data. However, if your application chooses to use ETags, a request may get rejected because of mismatched ETags. It's recommended that you use a [retry policy](#Retry-Policies) to compensate for such conflicts when using ETags. +Dapr chooses OCC because in many applications, data update conflicts are rare because clients are naturally partitioned by business contexts to operate on different data. However, if your application chooses to use ETags, a request may get rejected because of mismatched ETags. It's recommended that you use a [retry policy](#retry-policies) to compensate for such conflicts when using ETags. If your application omits ETags in writing requests, Dapr skips ETag checks while handling the requests. This essentially enables the **last-write-wins** pattern, compared to the **first-write-wins** pattern with ETags. -> **NOTE:** For stores that don't natively support ETags, it's expected that the corresponding Dapr state store implementation simulates ETags and follows the Dapr state management API specification when handling states. Because Dapr state store implementations are technically clients to the underlying data store, such simulation should be straightforward using the concurrency control mechanisms provided by the store. +{{% alert title="Note on ETags" color="primary" %}} +For stores that don't natively support ETags, it's expected that the corresponding Dapr state store implementation simulates ETags and follows the Dapr state management API specification when handling states. Because Dapr state store implementations are technically clients to the underlying data store, such simulation should be straightforward using the concurrency control mechanisms provided by the store. +{{% /alert %}} ### Consistency @@ -74,15 +69,21 @@ Dapr supports both **strong consistency** and **eventual consistency**, with eve When strong consistency is used, Dapr waits for all replicas (or designated quorums) to acknowledge before it acknowledges a write request. When eventual consistency is used, Dapr returns as soon as the write request is accepted by the underlying data store, even if this is a single replica. +Visit the [API reference]({{< ref state_api.md >}}) to learn how to set consistency options. + ### Retry policies Dapr allows you to attach a retry policy to any write request. A policy is described by an **retryInterval**, a **retryPattern** and a **retryThreshold**. Dapr keeps retrying the request at the given interval up to the specified threshold. You can choose between a **linear** retry pattern or an **exponential** (backoff) pattern. When the **exponential** pattern is used, the retry interval is doubled after each attempt. +Visit the [API reference]({{< ref state_api.md >}}) to learn how to set retry policy options. + ### Bulk operations Dapr supports two types of bulk operations - **bulk** or **multi**. You can group several requests of the same type into a bulk (or a batch). Dapr submits requests in the bulk as individual requests to the underlying data store. In other words, bulk operations are not transactional. On the other hand, you can group requests of different types into a multi-operation, which is handled as an atomic transaction. -### Querying state store directly +Visit the [API reference]({{< ref state_api.md >}}) to learn how use bulk and multi options. + +### Query state store directly Dapr saves and retrieves state values without any transformation. You can query and aggregate state directly from the [underlying state store]({{< ref query-state-store >}}). @@ -92,8 +93,6 @@ For example, to get all state keys associated with an application ID "myApp" in KEYS "myApp*" ``` -> **NOTE:** See [How to query Redis store]({{< ref query-redis-store.md >}} ) for details on how to query a Redis store. - #### Querying actor state If the data store supports SQL queries, you can query an actor's state using SQL queries. For example use: @@ -108,10 +107,12 @@ You can also perform aggregate queries across actor instances, avoiding the comm SELECT AVG(value) FROM StateTable WHERE Id LIKE '||||*||temperature' ``` -> **NOTE:** Direct queries of the state store are not governed by Dapr concurrency control, since you are not calling through the Dapr runtime. What you see are snapshots of committed data which are acceptable for read-only queries across multiple actors, however writes should be done via the actor instances. +{{% alert title="Note on direct queries" color="primary" %}} +Direct queries of the state store are not governed by Dapr concurrency control, since you are not calling through the Dapr runtime. What you see are snapshots of committed data which are acceptable for read-only queries across multiple actors, however writes should be done via the actor instances. +{{% /alert %}} ## Next steps -* Follow the [state store setup guides]({{< ref setup-state-store >}}) -* Read the [state management API specification]({{< ref state_api.md >}}) -* Read the [actors API specification]({{< ref actors_api.md >}}) +- Follow the [state store setup guides]({{< ref setup-state-store >}}) +- Read the [state management API specification]({{< ref state_api.md >}}) +- Read the [actors API specification]({{< ref actors_api.md >}}) From d7f6071997259a8a2ab4fa78455419ad1e53fad9 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Wed, 6 Jan 2021 23:33:58 -0800 Subject: [PATCH 13/39] Update Git commit --- sdkdocs/python | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdkdocs/python b/sdkdocs/python index 95203df1f..4704c925b 160000 --- a/sdkdocs/python +++ b/sdkdocs/python @@ -1 +1 @@ -Subproject commit 95203df1fd27632a53bd175f3334b22cb648c0b1 +Subproject commit 4704c925b0f2dca777497ba1ff77ba46ab547a73 From b06ed15d67cf2ff7f4f925c5b1b41e95323e6e48 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Wed, 6 Jan 2021 23:36:40 -0800 Subject: [PATCH 14/39] Update submodule --- sdkdocs/python | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdkdocs/python b/sdkdocs/python index 4704c925b..a0a68ca33 160000 --- a/sdkdocs/python +++ b/sdkdocs/python @@ -1 +1 @@ -Subproject commit 4704c925b0f2dca777497ba1ff77ba46ab547a73 +Subproject commit a0a68ca333d7432eba9847e955c50b284dec8a11 From faf2a5295a014d6dfb61a1df7bb0e1a370d14c00 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Thu, 7 Jan 2021 14:16:00 -0800 Subject: [PATCH 15/39] Add branch guidance --- README.md | 14 ++++++++++++++ .../content/en/contributing/contributing-docs.md | 8 ++++++++ 2 files changed, 22 insertions(+) diff --git a/README.md b/README.md index 3845f7cfd..a8b5f5c4b 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,20 @@ If you are looking to explore the Dapr documentation, please go to the documenta This repo contains the markdown files which generate the above website. See below for guidance on running with a local environment to contribute to the docs. +## Branch guidance + +The Dapr docs handles branching differently than most code repositories. Instead of having a `master` or `main` branch, every branch is labeled to match the major and minor version of a runtime release. + +The following branches are currently maintained: + +| Branch | Website | Description | +|--------|---------|-------------| +| [v0.11](https://github.com/dapr/docs) (primary) | https://docs.dapr.io | Latest Dapr release documentation. Typo fixes, clarifications, and most documentation goes here. +| [v1.0-rc2](https://github.com/dapr/docs/tree/v1.0-rc2) | https://v1-rc2.docs.dapr.io/ | Latest Dapr release candidate release documentation. Doc updates that are only applicable to v1.0-rc2+ go here. +| [v1.0-rc3](https://github.com/dapr/docs/tree/v1.0-rc3) (pre-release) | https://v1-rc3.docs.dapr.io/ | Pre-release release candidate documentation. Doc updates that are only applicable to v1.0-rc2+ go here. + +For more information visit the [Dapr branch structure](https://docs.dapr.io/contributing/contributing-docs/#branch-guidance) document. + ## Contribution guidelines Before making your first contribution, make sure to review the [contributing section](http://docs.dapr.io/contributing/) in the docs. diff --git a/daprdocs/content/en/contributing/contributing-docs.md b/daprdocs/content/en/contributing/contributing-docs.md index 179934fe6..39d6afc3e 100644 --- a/daprdocs/content/en/contributing/contributing-docs.md +++ b/daprdocs/content/en/contributing/contributing-docs.md @@ -18,6 +18,14 @@ Fork the [docs repository](https://github.com/dapr/docs) to work on any changes Follow the instructions in the repository [README.md](https://github.com/dapr/docs/blob/master/README.md#environment-setup) to install Hugo locally and build the docs website. +## Branch guidance + +The Dapr docs handles branching differently than most code repositories. Instead of having a `master` or `main` branch, every branch is labeled to match the major and minor version of a runtime release. For the full list visit the [Docs repo](https://github.com/dapr/docs#branch-guidance) + +Overall, all updates should go into the docs branch for the latest release of Dapr. You can find this directly at https://github.com/dapr/docs, as the latest release will be the default branch. For any docs changes that are applicable to a release candidate or a pre-release version of the docs, make your changes into that particular branch. + +For example, if you are fixing a typo, adding notes, or clarifying a point, make your changes into the default Dapr branch. If you are documenting an upcoming change to a component or the runtime, make your changes to the pre-release branch. Branches can be found in the [Docs repo](https://github.com/dapr/docs#branch-guidance) + ## Style and tone These conventions should be followed throughout all Dapr documentation to ensure a consistent experience across all docs. From e3a3ae38e406b4e89c9a562e08c91af1d135e2b7 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Thu, 7 Jan 2021 15:45:06 -0800 Subject: [PATCH 16/39] Fix version typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a8b5f5c4b..056a4a9c8 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ The following branches are currently maintained: |--------|---------|-------------| | [v0.11](https://github.com/dapr/docs) (primary) | https://docs.dapr.io | Latest Dapr release documentation. Typo fixes, clarifications, and most documentation goes here. | [v1.0-rc2](https://github.com/dapr/docs/tree/v1.0-rc2) | https://v1-rc2.docs.dapr.io/ | Latest Dapr release candidate release documentation. Doc updates that are only applicable to v1.0-rc2+ go here. -| [v1.0-rc3](https://github.com/dapr/docs/tree/v1.0-rc3) (pre-release) | https://v1-rc3.docs.dapr.io/ | Pre-release release candidate documentation. Doc updates that are only applicable to v1.0-rc2+ go here. +| [v1.0-rc3](https://github.com/dapr/docs/tree/v1.0-rc3) (pre-release) | https://v1-rc3.docs.dapr.io/ | Pre-release release candidate documentation. Doc updates that are only applicable to v1.0-rc3+ go here. For more information visit the [Dapr branch structure](https://docs.dapr.io/contributing/contributing-docs/#branch-guidance) document. From e0b2ff61a7658baccf88c98bdd66fbe2953e2722 Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Fri, 8 Jan 2021 09:08:23 -0800 Subject: [PATCH 17/39] Refactoring getting started --- daprdocs/content/en/getting-started/_index.md | 48 +---- .../getting-started/configure-state-pubsub.md | 3 +- .../en/getting-started/dev-environment.md | 26 --- .../en/getting-started/get-started-api.md | 105 +++++++++++ .../getting-started/get-started-component.md | 9 + .../en/getting-started/install-dapr-cli.md | 65 ++++++- .../install-dapr-kubernetes.md | 2 +- .../getting-started/install-dapr-selfhost.md | 168 ++++++++---------- .../self-hosted/self-hosted-uninstall.md | 22 +++ .../self-hosted/self-hosted-upgrade.md | 2 +- 10 files changed, 284 insertions(+), 166 deletions(-) delete mode 100644 daprdocs/content/en/getting-started/dev-environment.md create mode 100644 daprdocs/content/en/getting-started/get-started-api.md create mode 100644 daprdocs/content/en/getting-started/get-started-component.md create mode 100644 daprdocs/content/en/operations/hosting/self-hosted/self-hosted-uninstall.md diff --git a/daprdocs/content/en/getting-started/_index.md b/daprdocs/content/en/getting-started/_index.md index dddf29ed4..dc2fa38aa 100644 --- a/daprdocs/content/en/getting-started/_index.md +++ b/daprdocs/content/en/getting-started/_index.md @@ -7,50 +7,20 @@ description: "Get up and running with Dapr" no_list: true --- -The recommended way to get started with Dapr is to setup a local development environment (also referred to as [_self-hosted_ mode]({{< ref self-hosted >}})). This guide will walk you through the required steps to install the Dapr CLI and initialize Dapr on your local machine with components for state store and pub/sub so you get started quickly. +Welcome to the Dapr getting started guide! {{% alert title="Dapr Concepts" color="primary" %}} If you are looking for an introductory overview of Dapr and learn more about basic Dapr terminology, it is recommended to visit the [concepts section]({{}}) in the docs. {{% /alert %}} -## Step 1: Install the Dapr CLI +This guide will walk you through a series of steps to install, initialize and start using Dapr. The recommended way to get started with Dapr is to setup a local development environment (also referred to as [_self-hosted_ mode]({{< ref self-hosted >}}) which includes the Dapr CLI and Dapr sidecar binaries as well as some default components that can help you start using Dapr quickly. -The Dapr CLI is main tool you'll be using for various Dapr related tasks. Most importantly it is used to run an application with a Dapr sidecar, but it also can review sidecar logs, list running services, and run the Dapr dashboard. The Dapr CLI works with both [self-hosted]({{< ref self-hosted >}}) and [Kubernetes]({{< ref Kubernetes >}}) environments. +The following steps in this guide are: +1. Install the Dapr CLI +1. Initialize Dapr +1. Use the Dapr API +1. Configure a component +1. Explore Dapr quickstarts -Follow the instructions in [How-To: Install the Dapr CLI]({{}}) +Next step: Install the Dapr CLI >> -## Step 2: Initialize Dapr - -Now that you have the Dapr CLI installed, it's time to initialize Dapr on your local machine using the CLI. This step will install the Dapr sidecar binaries on your machine, spin up Zipkin and Redis Docker containers, adn create default component files to help you get started quickly with state management and Pub/Sub. - -Follow the instructions in [How-To: Initialize Dapr in your local environment]({{}}) - -{{% alert title="Docker" color="primary" %}} -This guide recommends and assumes you have Docker Desktop installed and initialize Dapr with Docker containers. If you would like to initialize Dapr without a dependency on Docker see [this guidance]({{}}). -{{% /alert %}} - -## Step 3: Get and set state using the Dapr API -At this point, the `dapr init` command has ensured your local environment has the Dapr sidecar binaries as well as default component definitions for both state management and a message broker (both using Redis). Now you can use the Dapr CLI to run a Dapr sidecar and try out the state API that will allow you to store and retrieve a state. - -The way it works is depicted in the illustration below: - - - -Instead of a writing an application to call the API you can use the Dapr CLI to just run the sidecar and then send requests directly using `curl`: - -Follow the instructions in [How-To: Save and get state]({{}}) - -## Step 4: Explore the Dapr quickstarts - -Now that you had your first experience calling the Dapr API directly, you can explore how Dapr is used in an application. To get started quickly with existing code that shows various Dapr capabilities, see the Dapr quickstarts and start with the "Hello world" quickstart. - -Explore the [Dapr quickstarts]({{}}) - -{{% alert title="Additional commands" color="primary" %}} -While running these quickstarts, consider trying out some other Dapr CLI commands such as `dapr list` and `dapr dashboard`. -{{% /alert %}} - -## Optional next steps -- Explore additional steps to configure a Dapr dev environment - [How-To: Setup a Dapr dev environment]({{}}) -- Try running Dapr on Kubernetes - [How-To: Install Dapr into a Kubernetes cluster]({{}}) -- Setup a non-default state store or message broker - [How-To: Configure state store and pub/sub message broker]({{}}) \ No newline at end of file diff --git a/daprdocs/content/en/getting-started/configure-state-pubsub.md b/daprdocs/content/en/getting-started/configure-state-pubsub.md index 929694192..bc64f2813 100644 --- a/daprdocs/content/en/getting-started/configure-state-pubsub.md +++ b/daprdocs/content/en/getting-started/configure-state-pubsub.md @@ -2,7 +2,7 @@ type: docs title: "How-To: Configure state store and pub/sub message broker" linkTitle: "Configure state & pub/sub" -weight: 40 +weight: 80 description: "Configure state store and pub/sub message broker components for Dapr" aliases: - /getting-started/configure-redis/ @@ -228,5 +228,4 @@ kubectl apply -f redis-pubsub.yaml {{< /tabs >}} ## Next steps -- [Setup your development environment]({{< ref dev-environment.md >}}) - [Try out a Dapr quickstart]({{< ref quickstarts.md >}}) \ No newline at end of file diff --git a/daprdocs/content/en/getting-started/dev-environment.md b/daprdocs/content/en/getting-started/dev-environment.md deleted file mode 100644 index 7249393c4..000000000 --- a/daprdocs/content/en/getting-started/dev-environment.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -type: docs -title: "How-To: Setup a Dapr dev environment" -linkTitle: "Setup Dev environment" -weight: 50 -description: "How to get up and running with Dapr SDKs, extensions, and tooling" ---- - -As you get up and running with Dapr there are a variety of SDKs and tools to make things easier for you. Check out the below the options to get up and running in your preferred tools. - -## Dapr SDKs - -Dapr offers a variety of SDKs for developing with Dapr in your preferred language. - -Visit the [Dapr SDK docs]({{< ref sdks>}}) for more information and to get started in your preferred language. - -## IDE integrations - -For information on the available extensions and integrations with IDEs such as [VS Code]({{< ref vscode.md >}}) and [IntelliJ]({{< ref intellij.md >}}) visit the [Dapr IDE integrations docs]({{< ref ides >}}). - -## Dapr Dashboard - -For easy access to key information about your Dapr applications and components, make sure to run `dapr dashboard` to launch the [dashboard app](https://github.com/dapr/dashboard). - -## Next steps -- [Try out a Dapr quickstart]({{< ref quickstarts.md >}}) \ No newline at end of file diff --git a/daprdocs/content/en/getting-started/get-started-api.md b/daprdocs/content/en/getting-started/get-started-api.md new file mode 100644 index 000000000..eb4d1f650 --- /dev/null +++ b/daprdocs/content/en/getting-started/get-started-api.md @@ -0,0 +1,105 @@ +--- +type: docs +title: "Use the Dapr API" +linkTitle: "Use the Dapr API" +weight: 30 +--- + +After running the `dapr init` command in the previous step, your local environment has the Dapr sidecar binaries as well as default component definitions for both state management and a message broker (both using Redis). You can now try out some of what Dapr has to offer by using the Dapr CLI to run a Dapr sidecar and try out the state API that will allow you to store and retrieve a state. + +The way it works is depicted in the illustration below: + + + +The illustration shows how an application calls the Dapr sidecar using the state API. In turn, the sidecar calls a state store component (in this case the local Redis container that was set up in the previous step) to get and set a state. + +You will now run the sidecar and call the API directly (simulating what an application would do). + +### Run the Dapr sidecar + +One the most useful Dapr CLI commands is `dapr run`. This command launches an application together with a sidecar. For the purpose of this tutorial, you'll run the sidecar without an application (see the [CLI reference]({{}}) for usage of `dapr run` and more information). + +Run the following command to run the Dapr sidecar, indicating it is listening on port 3500 and providing an app-id. + +```bash +dapr run --app-id myapp --dapr-http-port 3500 +``` + +### Set a state + +In a separate terminal run: + +{{< tabs "HTTP API (Bash)" "HTTP API (PowerShell)">}} +{{% codetab %}} + +```bash +curl -X POST -H "Content-Type: application/json" -d '[{ "key": "name", "value": "Bruce Wayne"}]' http://localhost:3500/v1.0/state/statestore +``` +{{% /codetab %}} + +{{% codetab %}} + +```powershell +Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '[{ "key": "name", "value": "Bruce Wayne"}]' -Uri 'http://localhost:3500/v1.0/state/statestore' +``` +{{% /codetab %}} + +{{< /tabs >}} + +### Get a state + +Now get the state you just stored using a key with the state management API: + +{{< tabs "HTTP API (Bash)" "HTTP API (PowerShell)">}} + +{{% codetab %}} +With the same dapr instance running from above run: +```bash +curl http://localhost:3500/v1.0/state/statestore/name +``` +{{% /codetab %}} + +{{% codetab %}} +With the same dapr instance running from above run: +```powershell +Invoke-RestMethod -Uri 'http://localhost:3500/v1.0/state/statestore/name' +``` +{{% /codetab %}} + +{{< /tabs >}} + +### See how the state is stored in Redis + +You can look in the Redis container and verify Dapr is using it as a state store. Run the following to use the Redis CLI: + +```bash +docker exec -it dapr_redis redis-cli +``` + +And then see how Dapr created a key value pair (with the app-id you provided to `dapr run` as a prefix to the key): + +```bash +keys * +``` + +``` +1) "myapp||name" +``` + + +```bash +hgetall "myapp||name" +``` + +``` +1) "data" +2) "\"Bruce Wayne\"" +3) "version" +4) "1" +``` + +```bash +exit +``` + +Next step: Define a component >> diff --git a/daprdocs/content/en/getting-started/get-started-component.md b/daprdocs/content/en/getting-started/get-started-component.md new file mode 100644 index 000000000..861af2575 --- /dev/null +++ b/daprdocs/content/en/getting-started/get-started-component.md @@ -0,0 +1,9 @@ +--- +type: docs +title: "Define a component" +linkTitle: "Define a component" +weight: 40 +--- + + +Next step: Explore Dapr quickstarts >> diff --git a/daprdocs/content/en/getting-started/install-dapr-cli.md b/daprdocs/content/en/getting-started/install-dapr-cli.md index 27c8a8887..dba84713c 100644 --- a/daprdocs/content/en/getting-started/install-dapr-cli.md +++ b/daprdocs/content/en/getting-started/install-dapr-cli.md @@ -1,14 +1,17 @@ --- type: docs -title: "How-To: Install Dapr CLI" +title: "Install the Dapr CLI" linkTitle: "Install Dapr CLI" weight: 10 -description: "Install the Dapr CLI to get started with Dapr" --- -## Dapr CLI installation scripts +The Dapr CLI is main tool you'll be using for various Dapr related tasks. Most importantly it is used to run an application with a Dapr sidecar, but it also can review sidecar logs, list running services, and run the Dapr dashboard. The Dapr CLI works with both [self-hosted]({{< ref self-hosted >}}) and [Kubernetes]({{< ref Kubernetes >}}) environments. -Begin by downloading and installing the Dapr CLI for v0.11. This is used to initialize your environment on your desired platform. +Learn more about the CLI and available commands in the [CLI reference docs]( {{< ref cli >}}). + +### Run the installation script + +Begin by downloading and installing the latest version of the Dapr CLI: {{% alert title="Note" color="warning" %}} This command downloads and install Dapr CLI v0.11. To install the latest preview release, please visit the [v1.0-rc2 version of this page](https://v1-rc2.docs.dapr.io/getting-started/install-dapr-cli/). @@ -54,9 +57,55 @@ Each release of Dapr CLI includes various OSes and architectures. These binary v {{% /codetab %}} {{< /tabs >}} -Learn more about the CLI and available commands in the [CLI docs]( {{< ref cli >}}). -## Next steps -- [Init Dapr locally]({{< ref install-dapr-selfhost.md >}}) -- [Init Dapr on Kubernetes]({{< ref install-dapr-kubernetes.md >}}) +### Verify the installation + +You can verify the CLI is installed by running the following: + +```bash +dapr +``` + +The output should look like this: + + +```bash + + ____/ /___ _____ _____ + / __ / __ '/ __ \/ ___/ + / /_/ / /_/ / /_/ / / + \__,_/\__,_/ .___/_/ + /_/ + +=============================== +Distributed Application Runtime + +Usage: + dapr [command] + +Available Commands: + completion Generates shell completion scripts + components List all Dapr components. Supported platforms: Kubernetes + configurations List all Dapr configurations. Supported platforms: Kubernetes + dashboard Start Dapr dashboard. Supported platforms: Kubernetes and self-hosted + help Help about any command + init Install Dapr on supported hosting platforms. Supported platforms: Kubernetes and self-hosted + invoke Invoke a method on a given Dapr application. Supported platforms: Self-hosted + list List all Dapr instances. Supported platforms: Kubernetes and self-hosted + logs Get Dapr sidecar logs for an application. Supported platforms: Kubernetes + mtls Check if mTLS is enabled. Supported platforms: Kubernetes + publish Publish a pub-sub event. Supported platforms: Self-hosted + run Run Dapr and (optionally) your application side by side. Supported platforms: Self-hosted + status Show the health status of Dapr services. Supported platforms: Kubernetes + stop Stop Dapr instances and their associated apps. . Supported platforms: Self-hosted + uninstall Uninstall Dapr runtime. Supported platforms: Kubernetes and self-hosted + +Flags: + -h, --help help for dapr + --version version for dapr + +Use "dapr [command] --help" for more information about a command. +``` + +Next step: Initialize Dapr >> diff --git a/daprdocs/content/en/getting-started/install-dapr-kubernetes.md b/daprdocs/content/en/getting-started/install-dapr-kubernetes.md index c3663c724..591626cd0 100644 --- a/daprdocs/content/en/getting-started/install-dapr-kubernetes.md +++ b/daprdocs/content/en/getting-started/install-dapr-kubernetes.md @@ -2,7 +2,7 @@ type: docs title: "How-To: Install Dapr into a Kubernetes cluster" linkTitle: "Init Dapr on Kubernetes" -weight: 30 +weight: 70 description: "Install Dapr in a Kubernetes cluster" --- diff --git a/daprdocs/content/en/getting-started/install-dapr-selfhost.md b/daprdocs/content/en/getting-started/install-dapr-selfhost.md index faffcce93..0cc333282 100644 --- a/daprdocs/content/en/getting-started/install-dapr-selfhost.md +++ b/daprdocs/content/en/getting-started/install-dapr-selfhost.md @@ -1,32 +1,32 @@ --- type: docs -title: "How-To: Initialize Dapr in your local environment" +title: "Initialize Dapr in your local environment" linkTitle: "Init Dapr locally" weight: 20 -description: "Initialize Dapr in your local environment for testing and self-hosting" aliases: - /getting-started/install-dapr/ --- -## Prerequisites - -- Install [Dapr CLI]({{< ref install-dapr-cli.md >}}) -- Install [Docker Desktop](https://docs.docker.com/install/) - - Windows users ensure that `Docker Desktop For Windows` uses Linux containers. - - (alternately) Install Dapr without Docker using [Dapr slim init]({{< ref self-hosted-no-docker.md >}}) - -## Initialize Dapr using the CLI - -This step installs the latest Dapr Docker containers and setup a developer environment to help you get started easily with Dapr. - -- In Linux/MacOS Dapr is initialized with default components and files in `$HOME/.dapr`. -- For Windows Dapr is initialized to `%USERPROFILE%\.dapr\` - {{% alert title="Note" color="warning" %}} -This command downloads and installs Dapr runtime v0.11. To install v1.0-rc2 preview, the release candidate for the upcoming v1.0 release please visit the [v1.0-rc2 docs version of this page](https://v1-rc1.docs.dapr.io/getting-started/install-dapr-selfhost/). Note you will need to ensure you are also using the preview version of the CLI (instructions to install the latest preview CLI can be found [here](https://v1-rc2.docs.dapr.io/getting-started/install-dapr-cli/)). +This page provides instructions for installing Dapr runtime v0.11. To install v1.0-rc2 preview, the release candidate for the upcoming v1.0 release please visit the [v1.0-rc2 docs version of this page](https://v1-rc1.docs.dapr.io/getting-started/install-dapr-selfhost/). Note you will need to ensure you are also using the preview version of the CLI (instructions to install the latest preview CLI can be found [here](https://v1-rc2.docs.dapr.io/getting-started/install-dapr-cli/)). {{% /alert %}} -1. Ensure you are in an elevated terminal: +Now that you have the Dapr CLI installed, it's time to initialize Dapr on your local machine using the CLI. + +Dapr runs as a sidecar alongside your application, and in self-hosted mode this means as a process on your local machine. Therefore, initializing Dapr includes fetching the Dapr sidecar binaries and installing them locally. + +In addition, the default initialization process also creates a development environment that helps streamlining application development with Dapr. This includes the following steps: + +{{% alert title="Docker" color="primary" %}} +This recommended development environment requires [Docker](https://docs.docker.com/install/). It is possible to initialize Dapr without a dependency on Docker (see [this guidance]({{}})) but next steps in this guide assume the recommended development environment. +{{% /alert %}} + +1. Running a Redis container instance to be used as a local state store and message broker +1. Running a Zipkin container instance for observability +1. Creating a default components folder with component definitions for the above +1. Running a container with a Dapr placement service for local actors + +### Ensure you are in an elevated terminal {{< tabs "Linux/MacOS" "Windows">}} @@ -40,85 +40,75 @@ This command downloads and installs Dapr runtime v0.11. To install v1.0-rc2 prev {{< /tabs >}} -1. Run the `init` CLI command: +### Run the init CLI command - You can install or upgrade to a specific version of the Dapr runtime using `dapr init --runtime-version`. You can find the list of versions in [Dapr Release](https://github.com/dapr/dapr/releases) - - ```bash - dapr init - ``` - -1. Verify Dapr version: - - ```bash - dapr --version - ``` - - Output should look like this: - ``` - CLI version: 0.11 - Runtime version: 0.11 - ``` - -1. Verify Dapr containers are running: - - ```bash - docker ps - ``` - - Make sure the `daprio/dapr`, `openzipkin/zipkin`, and `redis` container images are all running: - - ``` - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 0dda6684dc2e openzipkin/zipkin "/busybox/sh run.sh" 2 minutes ago Up 2 minutes 9410/tcp, 0.0.0.0:9411->9411/tcp dapr_zipkin - 9bf6ef339f50 redis "docker-entrypoint.s…" 2 minutes ago Up 2 minutes 0.0.0.0:6379->6379/tcp dapr_redis - 8d993e514150 daprio/dapr "./placement" 2 minutes ago Up 2 minutes 0.0.0.0:6050->50005/tcp dapr_placement - ``` - -1. Verify Dapr directory has been initialized - - {{< tabs "Linux/MacOS" "Windows">}} - - {{% codetab %}} - Run: - ```bash - ls $HOME/.dapr - ``` - Output should look like so: - - ``` - bin components config.yaml - ``` - {{% /codetab %}} - - {{% codetab %}} - Open `%USERPROFILE%\.dapr\` in file explorer - - ![Explorer files](/images/install-dapr-selfhost-windows.png) - {{% /codetab %}} - - {{< /tabs >}} - -## Uninstall Dapr in self-hosted mode - -This cli command removes the placement Dapr container: +Install the latest Dapr runtime binaries: ```bash -dapr uninstall +dapr init ``` -{{% alert title="Warning" color="warning" %}} -This command won't remove the Redis or Zipkin containers by default, just in case you were using them for other purposes. To remove Redis, Zipkin, Actor Placement container, as well as the default Dapr directory located at `$HOME/.dapr` or `%USERPROFILE%\.dapr\`, run: +Instead of the latest Dapr binaries, you can install or upgrade to a specific version of the Dapr runtime using `dapr init --runtime-version`. You can find the list of versions in [Dapr Release](https://github.com/dapr/dapr/releases) + + +### Verify Dapr version ```bash -dapr uninstall --all +dapr --version ``` -{{% /alert %}} -{{% alert title="Note" color="primary" %}} -For Linux/MacOS users, if you run your docker cmds with sudo or the install path is `/usr/local/bin`(default install path), you need to use `sudo dapr uninstall` to remove dapr binaries and/or the containers. -{{% /alert %}} +Output should look like this: +``` +CLI version: 0.11 +Runtime version: 0.11 +``` -## Next steps -- [Setup a state store and pub/sub message broker]({{< ref configure-state-pubsub.md >}}) +### Verify containers are running + +As mentioned above, the `dapr init` command launches several containers that will help you get started with Dapr. Verify this by running: + +```bash + docker ps +``` + +Make sure that instances with `daprio/dapr`, `openzipkin/zipkin`, and `redis` images are all running: + +``` +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +0dda6684dc2e openzipkin/zipkin "/busybox/sh run.sh" 2 minutes ago Up 2 minutes 9410/tcp, 0.0.0.0:9411->9411/tcp dapr_zipkin +9bf6ef339f50 redis "docker-entrypoint.s…" 2 minutes ago Up 2 minutes 0.0.0.0:6379->6379/tcp dapr_redis +8d993e514150 daprio/dapr "./placement" 2 minutes ago Up 2 minutes 0.0.0.0:6050->50005/tcp dapr_placement +``` + +### Verify components directory has been initialized + +On init, the CLI also creates a default components folder which includes several YAML files with definitions for a state store, pub/sub and zipkin. These will be read by the Dapr sidecar, telling it to use the Redis container for state management and messaging and the Zipkin container for collecting traces. + +- In Linux/MacOS Dapr is initialized with default components and files in `$HOME/.dapr`. +- For Windows Dapr is initialized to `%USERPROFILE%\.dapr\` + + +{{< tabs "Linux/MacOS" "Windows">}} + +{{% codetab %}} +Run: +```bash +ls $HOME/.dapr +``` +Output should look like so: + +``` +bin components config.yaml +``` +{{% /codetab %}} + +{{% codetab %}} +Open `%USERPROFILE%\.dapr\` in file explorer + +![Explorer files](/images/install-dapr-selfhost-windows.png) +{{% /codetab %}} + +{{< /tabs >}} + +Next step: Use the Dapr API >> diff --git a/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-uninstall.md b/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-uninstall.md new file mode 100644 index 000000000..d31d0d1e9 --- /dev/null +++ b/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-uninstall.md @@ -0,0 +1,22 @@ +--- +type: docs +title: "Uninstall Dapr in a self-hosted environment" +linkTitle: "Uninstall Dapr" +weight: 60000 +description: "Steps to remove Dapr from your local machine" +--- + +The following CLI command removes the Dapr sidecar binaries and the placement container: + +```bash +dapr uninstall +``` +The above command will not remove the Redis or Zipkin containers that were installed during `dapr init` by default, just in case you were using them for other purposes. To remove Redis, Zipkin, Actor Placement container, as well as the default Dapr directory located at `$HOME/.dapr` or `%USERPROFILE%\.dapr\`, run: + +```bash +dapr uninstall --all +``` + +{{% alert title="Note" color="primary" %}} +For Linux/MacOS users, if you run your docker cmds with sudo or the install path is `/usr/local/bin`(default install path), you need to use `sudo dapr uninstall` to remove dapr binaries and/or the containers. +{{% /alert %}} \ No newline at end of file diff --git a/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-upgrade.md b/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-upgrade.md index 7d06b48e1..43377e209 100644 --- a/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-upgrade.md +++ b/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-upgrade.md @@ -3,7 +3,7 @@ type: docs title: "Steps to upgrade Dapr in a self-hosted environment" linkTitle: "Upgrade Dapr" weight: 50000 -description: "Follow these steps to upgrade Dapr in self-hosted mode and ensure a smooth upgrade." +description: "Follow these steps to upgrade Dapr in self-hosted mode and ensure a smooth upgrade" --- From db299559bc1cd2ccb6c0c29ae4dd24f8c9610d3c Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Fri, 8 Jan 2021 21:11:49 -0800 Subject: [PATCH 18/39] Grammer and heading updates --- daprdocs/content/en/getting-started/_index.md | 8 +-- .../en/getting-started/get-started-api.md | 29 +++++----- .../en/getting-started/install-dapr-cli.md | 17 +++--- .../getting-started/install-dapr-selfhost.md | 53 ++++++++++--------- 4 files changed, 52 insertions(+), 55 deletions(-) diff --git a/daprdocs/content/en/getting-started/_index.md b/daprdocs/content/en/getting-started/_index.md index dc2fa38aa..bfcf1a98f 100644 --- a/daprdocs/content/en/getting-started/_index.md +++ b/daprdocs/content/en/getting-started/_index.md @@ -3,17 +3,17 @@ type: docs title: "Getting started with Dapr" linkTitle: "Getting started" weight: 20 -description: "Get up and running with Dapr" +description: "How to get up and running with Dapr in minutes" no_list: true --- Welcome to the Dapr getting started guide! {{% alert title="Dapr Concepts" color="primary" %}} -If you are looking for an introductory overview of Dapr and learn more about basic Dapr terminology, it is recommended to visit the [concepts section]({{}}) in the docs. +If you are looking for an introductory overview of Dapr and learn more about basic Dapr terminology, it is recommended to visit the [concepts section]({{}}). {{% /alert %}} -This guide will walk you through a series of steps to install, initialize and start using Dapr. The recommended way to get started with Dapr is to setup a local development environment (also referred to as [_self-hosted_ mode]({{< ref self-hosted >}}) which includes the Dapr CLI and Dapr sidecar binaries as well as some default components that can help you start using Dapr quickly. +This guide will walk you through a series of steps to install, initialize and start using Dapr. The recommended way to get started with Dapr is to setup a local development environment (also referred to as [_self-hosted_ mode]({{< ref self-hosted >}})) which includes the Dapr CLI, Dapr sidecar binaries, and some default components that can help you start using Dapr quickly. The following steps in this guide are: 1. Install the Dapr CLI @@ -22,5 +22,5 @@ The following steps in this guide are: 1. Configure a component 1. Explore Dapr quickstarts -Next step: Install the Dapr CLI >> +First step: Install the Dapr CLI >> diff --git a/daprdocs/content/en/getting-started/get-started-api.md b/daprdocs/content/en/getting-started/get-started-api.md index eb4d1f650..ef3c7f075 100644 --- a/daprdocs/content/en/getting-started/get-started-api.md +++ b/daprdocs/content/en/getting-started/get-started-api.md @@ -5,27 +5,21 @@ linkTitle: "Use the Dapr API" weight: 30 --- -After running the `dapr init` command in the previous step, your local environment has the Dapr sidecar binaries as well as default component definitions for both state management and a message broker (both using Redis). You can now try out some of what Dapr has to offer by using the Dapr CLI to run a Dapr sidecar and try out the state API that will allow you to store and retrieve a state. - -The way it works is depicted in the illustration below: - - - -The illustration shows how an application calls the Dapr sidecar using the state API. In turn, the sidecar calls a state store component (in this case the local Redis container that was set up in the previous step) to get and set a state. +After running the `dapr init` command in the previous step, your local environment has the Dapr sidecar binaries as well as default component definitions for both state management and a message broker (both using Redis). You can now try out some of what Dapr has to offer by using the Dapr CLI to run a Dapr sidecar and try out the state API that will allow you to store and retrieve a state. You can learn more about the state building block and how it works in [these docs]({{< ref state-management >}}). You will now run the sidecar and call the API directly (simulating what an application would do). -### Run the Dapr sidecar +### Step 1: Run the Dapr sidecar -One the most useful Dapr CLI commands is `dapr run`. This command launches an application together with a sidecar. For the purpose of this tutorial, you'll run the sidecar without an application (see the [CLI reference]({{}}) for usage of `dapr run` and more information). +One the most useful Dapr CLI commands is [`dapr run`]({{< ref dapr-run.md >}}). This command launches an application together with a sidecar. For the purpose of this tutorial you'll run the sidecar without an application. -Run the following command to run the Dapr sidecar, indicating it is listening on port 3500 and providing an app-id. +Run the following command to 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 ``` -### Set a state +### Step 2: Save state In a separate terminal run: @@ -46,21 +40,21 @@ Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '[{ "key": {{< /tabs >}} -### Get a state +### Step 2: Get state Now get the state you just stored using a key with the state management API: {{< tabs "HTTP API (Bash)" "HTTP API (PowerShell)">}} {{% codetab %}} -With the same dapr instance running from above run: +With the same Dapr instance running from above run: ```bash curl http://localhost:3500/v1.0/state/statestore/name ``` {{% /codetab %}} {{% codetab %}} -With the same dapr instance running from above run: +With the same Dapr instance running from above run: ```powershell Invoke-RestMethod -Uri 'http://localhost:3500/v1.0/state/statestore/name' ``` @@ -68,7 +62,7 @@ Invoke-RestMethod -Uri 'http://localhost:3500/v1.0/state/statestore/name' {{< /tabs >}} -### See how the state is stored in Redis +### Step 3: See how the state is stored in Redis You can look in the Redis container and verify Dapr is using it as a state store. Run the following to use the Redis CLI: @@ -76,7 +70,7 @@ You can look in the Redis container and verify Dapr is using it as a state store docker exec -it dapr_redis redis-cli ``` -And then see how Dapr created a key value pair (with the app-id you provided to `dapr run` as a prefix to the key): +List the redis keys to see how Dapr created a key value pair (with the app-id you provided to `dapr run` as a prefix to the key): ```bash keys * @@ -86,6 +80,7 @@ keys * 1) "myapp||name" ``` +View the state value by running: ```bash hgetall "myapp||name" @@ -98,6 +93,8 @@ hgetall "myapp||name" 4) "1" ``` +Exit the redis-cli with: + ```bash exit ``` diff --git a/daprdocs/content/en/getting-started/install-dapr-cli.md b/daprdocs/content/en/getting-started/install-dapr-cli.md index dba84713c..de3ecf74e 100644 --- a/daprdocs/content/en/getting-started/install-dapr-cli.md +++ b/daprdocs/content/en/getting-started/install-dapr-cli.md @@ -5,11 +5,11 @@ linkTitle: "Install Dapr CLI" weight: 10 --- -The Dapr CLI is main tool you'll be using for various Dapr related tasks. Most importantly it is used to run an application with a Dapr sidecar, but it also can review sidecar logs, list running services, and run the Dapr dashboard. The Dapr CLI works with both [self-hosted]({{< ref self-hosted >}}) and [Kubernetes]({{< ref Kubernetes >}}) environments. +The Dapr CLI is the main tool you'll be using for various Dapr related tasks. You can use it to run an application with a Dapr sidecar, as well as review sidecar logs, list running services, and run the Dapr dashboard. The Dapr CLI works with both [self-hosted]({{< ref self-hosted >}}) and [Kubernetes]({{< ref Kubernetes >}}) environments. -Learn more about the CLI and available commands in the [CLI reference docs]( {{< ref cli >}}). +You can learn more about the CLI and available commands in the [CLI reference docs]( {{< ref cli >}}). -### Run the installation script +### Step 1: Run the installation script Begin by downloading and installing the latest version of the Dapr CLI: @@ -27,11 +27,10 @@ wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O {{% /codetab %}} {{% codetab %}} -This command installs the latest windows Dapr cli to `C:\dapr` and add this directory to User PATH environment variable. Run in Command Prompt: +This Command Prompt command installs the latest windows Dapr cli to `C:\dapr` and adds this directory to User PATH environment variable. ```powershell powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex" ``` -Verify by opening Explorer and entering `C:\dapr` into the address bar. You should see folders for bin, components, and a config file. {{% /codetab %}} {{% codetab %}} @@ -53,14 +52,14 @@ Each release of Dapr CLI includes various OSes and architectures. These binary v 2. Unpack it (e.g. dapr_linux_amd64.tar.gz, dapr_windows_amd64.zip) 3. Move it to your desired location. - For Linux/MacOS - `/usr/local/bin` - - For Windows, create a directory and add this to your System PATH. For example create a directory called `c:\dapr` and add this directory to your path, by editing your system environment variable. + - For Windows, create a directory and add this to your System PATH. For example create a directory called `C:\dapr` and add this directory to your User PATH, by editing your system environment variable. {{% /codetab %}} {{< /tabs >}} -### Verify the installation +### Step 2: Verify the installation -You can verify the CLI is installed by running the following: +You can verify the CLI is installed by restarting your terminal/command prompt and running the following: ```bash dapr @@ -69,7 +68,7 @@ dapr The output should look like this: -```bash +```md ____/ /___ _____ _____ / __ / __ '/ __ \/ ___/ diff --git a/daprdocs/content/en/getting-started/install-dapr-selfhost.md b/daprdocs/content/en/getting-started/install-dapr-selfhost.md index 0cc333282..3df674abf 100644 --- a/daprdocs/content/en/getting-started/install-dapr-selfhost.md +++ b/daprdocs/content/en/getting-started/install-dapr-selfhost.md @@ -7,40 +7,40 @@ aliases: - /getting-started/install-dapr/ --- -{{% alert title="Note" color="warning" %}} -This page provides instructions for installing Dapr runtime v0.11. To install v1.0-rc2 preview, the release candidate for the upcoming v1.0 release please visit the [v1.0-rc2 docs version of this page](https://v1-rc1.docs.dapr.io/getting-started/install-dapr-selfhost/). Note you will need to ensure you are also using the preview version of the CLI (instructions to install the latest preview CLI can be found [here](https://v1-rc2.docs.dapr.io/getting-started/install-dapr-cli/)). -{{% /alert %}} - Now that you have the Dapr CLI installed, it's time to initialize Dapr on your local machine using the CLI. -Dapr runs as a sidecar alongside your application, and in self-hosted mode this means as a process on your local machine. Therefore, initializing Dapr includes fetching the Dapr sidecar binaries and installing them locally. +Dapr runs as a sidecar alongside your application, and in self-hosted mode this means it is a process on your local machine. Therefore, initializing Dapr includes fetching the Dapr sidecar binaries and installing them locally. -In addition, the default initialization process also creates a development environment that helps streamlining application development with Dapr. This includes the following steps: +In addition, the default initialization process also creates a development environment that helps streamline application development with Dapr. This includes the following steps: + +1. Running a **Redis container instance** to be used as a local state store and message broker +1. Running a **Zipkin container instance** for observability +1. Creating a **default components folder** with component definitions for the above +1. Running a **Dapr placement service container instance** for local actor support + +{{% alert title="Dapr release candidate" color="warning" %}} +This page provides instructions for installing Dapr runtime v0.11. To install v1.0-rc2 preview, the release candidate for the upcoming v1.0 release please visit the [v1.0-rc2 docs version of this page](https://v1-rc1.docs.dapr.io/getting-started/install-dapr-selfhost/). Note you will need to ensure you are also using the preview version of the CLI (instructions to install the latest preview CLI can be found [here](https://v1-rc2.docs.dapr.io/getting-started/install-dapr-cli/)). +{{% /alert %}} {{% alert title="Docker" color="primary" %}} This recommended development environment requires [Docker](https://docs.docker.com/install/). It is possible to initialize Dapr without a dependency on Docker (see [this guidance]({{}})) but next steps in this guide assume the recommended development environment. {{% /alert %}} -1. Running a Redis container instance to be used as a local state store and message broker -1. Running a Zipkin container instance for observability -1. Creating a default components folder with component definitions for the above -1. Running a container with a Dapr placement service for local actors - -### Ensure you are in an elevated terminal +### Step 1: Open an elevated terminal {{< tabs "Linux/MacOS" "Windows">}} {{% codetab %}} - If you run your docker commands with sudo or the install path is `/usr/local/bin`(default install path), you need to use `sudo` + If you run your Docker commands with sudo, or the install path is `/usr/local/bin` (default install path), you will need to use `sudo` below. {{% /codetab %}} {{% codetab %}} - Make sure that you run the command prompt terminal in administrator mode (right click, run as administrator) + Make sure that you run Command Prompt as administrator (right click, run as administrator) {{% /codetab %}} {{< /tabs >}} -### Run the init CLI command +### Step 2: Run the init CLI command Install the latest Dapr runtime binaries: @@ -48,10 +48,7 @@ Install the latest Dapr runtime binaries: dapr init ``` -Instead of the latest Dapr binaries, you can install or upgrade to a specific version of the Dapr runtime using `dapr init --runtime-version`. You can find the list of versions in [Dapr Release](https://github.com/dapr/dapr/releases) - - -### Verify Dapr version +### Step 3: Verify Dapr version ```bash dapr --version @@ -63,12 +60,12 @@ CLI version: 0.11 Runtime version: 0.11 ``` -### Verify containers are running +### Step 4: Verify containers are running As mentioned above, the `dapr init` command launches several containers that will help you get started with Dapr. Verify this by running: ```bash - docker ps +docker ps ``` Make sure that instances with `daprio/dapr`, `openzipkin/zipkin`, and `redis` images are all running: @@ -80,9 +77,9 @@ CONTAINER ID IMAGE COMMAND CREATED 8d993e514150 daprio/dapr "./placement" 2 minutes ago Up 2 minutes 0.0.0.0:6050->50005/tcp dapr_placement ``` -### Verify components directory has been initialized +### Step 5: Verify components directory has been initialized -On init, the CLI also creates a default components folder which includes several YAML files with definitions for a state store, pub/sub and zipkin. These will be read by the Dapr sidecar, telling it to use the Redis container for state management and messaging and the Zipkin container for collecting traces. +On `dapr init`, the CLI also creates a default components folder which includes several YAML files with definitions for a state store, pub/sub and zipkin. These will be read by the Dapr sidecar, telling it to use the Redis container for state management and messaging and the Zipkin container for collecting traces. - In Linux/MacOS Dapr is initialized with default components and files in `$HOME/.dapr`. - For Windows Dapr is initialized to `%USERPROFILE%\.dapr\` @@ -95,17 +92,21 @@ Run: ```bash ls $HOME/.dapr ``` -Output should look like so: +You should see: ``` bin components config.yaml ``` {{% /codetab %}} {{% codetab %}} -Open `%USERPROFILE%\.dapr\` in file explorer +Open `%USERPROFILE%\.dapr\` in file explorer: + +```powershell +explorer "%USERPROFILE%\.dapr\" +``` -![Explorer files](/images/install-dapr-selfhost-windows.png) + {{% /codetab %}} {{< /tabs >}} From ad21ab4cba4a0de94b7369b86b94f3f671ab4f18 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Fri, 8 Jan 2021 22:17:35 -0800 Subject: [PATCH 19/39] Update actors docs --- .../actors/actors-background.md | 104 ---------- .../building-blocks/actors/actors-overview.md | 185 +++++++----------- .../building-blocks/actors/howto-actors.md | 137 +++++++++++++ 3 files changed, 212 insertions(+), 214 deletions(-) delete mode 100644 daprdocs/content/en/developing-applications/building-blocks/actors/actors-background.md create mode 100644 daprdocs/content/en/developing-applications/building-blocks/actors/howto-actors.md diff --git a/daprdocs/content/en/developing-applications/building-blocks/actors/actors-background.md b/daprdocs/content/en/developing-applications/building-blocks/actors/actors-background.md deleted file mode 100644 index b2c5f3a3f..000000000 --- a/daprdocs/content/en/developing-applications/building-blocks/actors/actors-background.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -type: docs -title: "Introduction to actors" -linkTitle: "Actors background" -weight: 20 -description: Learn more about the actor pattern ---- - -The [actor pattern](https://en.wikipedia.org/wiki/Actor_model) describes **actors** as the lowest-level "unit of computation". In other words, you write your code in a self-contained unit (called an actor) that receives messages and processes them one at a time, without any kind of concurrency or threading. - -While your code processes a message, it can send one or more messages to other actors, or create new actors. An underlying **runtime** manages how, when and where each actor runs, and also routes messages between actors. - -A large number of actors can execute simultaneously, and actors execute independently from each other. - -Dapr includes a runtime that specifically implements the [Virtual Actor pattern](https://www.microsoft.com/en-us/research/project/orleans-virtual-actors/). With Dapr's implementation, you write your Dapr actors according to the Actor model, and Dapr leverages the scalability and reliability guarantees that the underlying platform provides. - -## Quick links - -- [Dapr Actor Features]({{< ref actors-overview.md >}}) -- [Dapr Actor API Spec]({{< ref actors_api.md >}} ) - -### When to use actors - -As with any other technology decision, you should decide whether to use actors based on the problem you're trying to solve. - -The actor design pattern can be a good fit to a number of distributed systems problems and scenarios, but the first thing you should consider are the constraints of the pattern. Generally speaking, consider the actor pattern to model your problem or scenario if: - -* Your problem space involves a large number (thousands or more) of small, independent, and isolated units of state and logic. -* You want to work with single-threaded objects that do not require significant interaction from external components, including querying state across a set of actors. -* Your actor instances won't block callers with unpredictable delays by issuing I/O operations. - -## Actors in dapr - -Every actor is defined as an instance of an actor type, identical to the way an object is an instance of a class. For example, there may be an actor type that implements the functionality of a calculator and there could be many actors of that type that are distributed on various nodes across a cluster. Each such actor is uniquely identified by an actor ID. - - - -## Actor lifetime - -Dapr actors are virtual, meaning that their lifetime is not tied to their in-memory representation. As a result, they do not need to be explicitly created or destroyed. The Dapr actors runtime automatically activates an actor the first time it receives a request for that actor ID. If an actor is not used for a period of time, the Dapr Actors runtime garbage-collects the in-memory object. It will also maintain knowledge of the actor's existence should it need to be reactivated later. - -Invocation of actor methods and reminders reset the idle time, e.g. reminder firing will keep the actor active. Actor reminders fire whether an actor is active or inactive, if fired for inactive actor, it will activate the actor first. Actor timers do not reset the idle time, so timer firing will not keep the actor active. Timers only fire while the actor is active. - -The idle timeout and scan interval Dapr runtime uses to see if an actor can be garbage-collected is configurable. This information can be passed when Dapr runtime calls into the actor service to get supported actor types. - -This virtual actor lifetime abstraction carries some caveats as a result of the virtual actor model, and in fact the Dapr Actors implementation deviates at times from this model. - -An actor is automatically activated (causing an actor object to be constructed) the first time a message is sent to its actor ID. After some period of time, the actor object is garbage collected. In the future, using the actor ID again, causes a new actor object to be constructed. An actor's state outlives the object's lifetime as state is stored in configured state provider for Dapr runtime. - -## Distribution and failover - -To provide scalability and reliability, actors instances are distributed throughout the cluster and Dapr automatically migrates them from failed nodes to healthy ones as required. - -Actors are distributed across the instances of the actor service, and those instance are distributed across the nodes in a cluster. Each service instance contains a set of actors for a given actor type. - -### Actor placement service -The Dapr actor runtime manages distribution scheme and key range settings for you. This is done by the actor `Placement` service. When a new instance of a service is created, the corresponding Dapr runtime registers the actor types it can create and the `Placement` service calculates the partitioning across all the instances for a given actor type. This table of partition information for each actor type is updated and stored in each Dapr instance running in the environment and can change dynamically as new instance of actor services are created and destroyed. This is shown in the diagram below. - - - -When a client calls an actor with a particular id (for example, actor id 123), the Dapr instance for the client hashes the actor type and id, and uses the information to call onto the corresponding Dapr instance that can serve the requests for that particular actor id. As a result, the same partition (or service instance) is always called for any given actor id. This is shown in the diagram below. - - - - This simplifies some choices but also carries some consideration: - -* By default, actors are randomly placed into pods resulting in uniform distribution. -* Because actors are randomly placed, it should be expected that actor operations always require network communication, including serialization and deserialization of method call data, incurring latency and overhead. - -Note: The Dapr actor Placement service is only used for actor placement and therefore is not needed if your services are not using Dapr actors. The Placement service can run in all [hosting environments]({{< ref hosting >}}), including self-hosted and Kubernetes. - -## Actor communication - -You can interact with Dapr to invoke the actor method by calling HTTP/gRPC endpoint. - -```bash -POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/// -``` - -You can provide any data for the actor method in the request body, and the response for the request would be in the response body which is the data from actor call. - -Refer to [Dapr Actor Features]({{< ref actors-overview.md >}}) for more details. - -### Concurrency - -The Dapr Actors runtime provides a simple turn-based access model for accessing actor methods. This means that no more than one thread can be active inside an actor object's code at any time. Turn-based access greatly simplifies concurrent systems as there is no need for synchronization mechanisms for data access. It also means systems must be designed with special considerations for the single-threaded access nature of each actor instance. - -A single actor instance cannot process more than one request at a time. An actor instance can cause a throughput bottleneck if it is expected to handle concurrent requests. - -Actors can deadlock on each other if there is a circular request between two actors while an external request is made to one of the actors simultaneously. The Dapr actor runtime automatically times out on actor calls and throw an exception to the caller to interrupt possible deadlock situations. - - - - -### Turn-based access - -A turn consists of the complete execution of an actor method in response to a request from other actors or clients, or the complete execution of a timer/reminder callback. Even though these methods and callbacks are asynchronous, the Dapr Actors runtime does not interleave them. A turn must be fully finished before a new turn is allowed. In other words, an actor method or timer/reminder callback that is currently executing must be fully finished before a new call to a method or callback is allowed. A method or callback is considered to have finished if the execution has returned from the method or callback and the task returned by the method or callback has finished. It is worth emphasizing that turn-based concurrency is respected even across different methods, timers, and callbacks. - -The Dapr actors runtime enforces turn-based concurrency by acquiring a per-actor lock at the beginning of a turn and releasing the lock at the end of the turn. Thus, turn-based concurrency is enforced on a per-actor basis and not across actors. Actor methods and timer/reminder callbacks can execute simultaneously on behalf of different actors. - -The following example illustrates the above concepts. Consider an actor type that implements two asynchronous methods (say, Method1 and Method2), a timer, and a reminder. The diagram below shows an example of a timeline for the execution of these methods and callbacks on behalf of two actors (ActorId1 and ActorId2) that belong to this actor type. - - - diff --git a/daprdocs/content/en/developing-applications/building-blocks/actors/actors-overview.md b/daprdocs/content/en/developing-applications/building-blocks/actors/actors-overview.md index a342db3d3..587873d99 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/actors/actors-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/actors/actors-overview.md @@ -4,134 +4,99 @@ title: "Dapr actors overview" linkTitle: "Overview" weight: 10 description: Overview of Dapr support for actors +aliases: + - "/developing-applications/building-blocks/actors/actors-background" --- -The Dapr actors runtime provides support for [virtual actors]({{< ref actors-background.md >}}) through following capabilities: +## Background +The [actor pattern](https://en.wikipedia.org/wiki/Actor_model) describes actors as the lowest-level "unit of computation". In other words, you write your code in a self-contained unit (called an actor) that receives messages and processes them one at a time, without any kind of concurrency or threading. -## Actor method invocation +While your code processes a message, it can send one or more messages to other actors, or create new actors. An underlying runtime manages how, when and where each actor runs, and also routes messages between actors. -You can interact with Dapr to invoke the actor method by calling HTTP/gRPC endpoint +A large number of actors can execute simultaneously, and actors execute independently from each other. + +Dapr includes a runtime that specifically implements the [Virtual Actor pattern](https://www.microsoft.com/en-us/research/project/orleans-virtual-actors/). With Dapr's implementation, you write your Dapr actors according to the Actor model, and Dapr leverages the scalability and reliability guarantees that the underlying platform provides. + +### When to use actors + +As with any other technology decision, you should decide whether to use actors based on the problem you're trying to solve. + +The actor design pattern can be a good fit to a number of distributed systems problems and scenarios, but the first thing you should consider are the constraints of the pattern. Generally speaking, consider the actor pattern to model your problem or scenario if: + +* Your problem space involves a large number (thousands or more) of small, independent, and isolated units of state and logic. +* You want to work with single-threaded objects that do not require significant interaction from external components, including querying state across a set of actors. +* Your actor instances won't block callers with unpredictable delays by issuing I/O operations. + +## Actors in dapr + +Every actor is defined as an instance of an actor type, identical to the way an object is an instance of a class. For example, there may be an actor type that implements the functionality of a calculator and there could be many actors of that type that are distributed on various nodes across a cluster. Each such actor is uniquely identified by an actor ID. + + + +## Actor lifetime + +Dapr actors are virtual, meaning that their lifetime is not tied to their in-memory representation. As a result, they do not need to be explicitly created or destroyed. The Dapr actors runtime automatically activates an actor the first time it receives a request for that actor ID. If an actor is not used for a period of time, the Dapr Actors runtime garbage-collects the in-memory object. It will also maintain knowledge of the actor's existence should it need to be reactivated later. + +Invocation of actor methods and reminders reset the idle time, e.g. reminder firing will keep the actor active. Actor reminders fire whether an actor is active or inactive, if fired for inactive actor, it will activate the actor first. Actor timers do not reset the idle time, so timer firing will not keep the actor active. Timers only fire while the actor is active. + +The idle timeout and scan interval Dapr runtime uses to see if an actor can be garbage-collected is configurable. This information can be passed when Dapr runtime calls into the actor service to get supported actor types. + +This virtual actor lifetime abstraction carries some caveats as a result of the virtual actor model, and in fact the Dapr Actors implementation deviates at times from this model. + +An actor is automatically activated (causing an actor object to be constructed) the first time a message is sent to its actor ID. After some period of time, the actor object is garbage collected. In the future, using the actor ID again, causes a new actor object to be constructed. An actor's state outlives the object's lifetime as state is stored in configured state provider for Dapr runtime. + +## Distribution and failover + +To provide scalability and reliability, actors instances are distributed throughout the cluster and Dapr automatically migrates them from failed nodes to healthy ones as required. + +Actors are distributed across the instances of the actor service, and those instance are distributed across the nodes in a cluster. Each service instance contains a set of actors for a given actor type. + +### Actor placement service +The Dapr actor runtime manages distribution scheme and key range settings for you. This is done by the actor `Placement` service. When a new instance of a service is created, the corresponding Dapr runtime registers the actor types it can create and the `Placement` service calculates the partitioning across all the instances for a given actor type. This table of partition information for each actor type is updated and stored in each Dapr instance running in the environment and can change dynamically as new instance of actor services are created and destroyed. This is shown in the diagram below. + + + +When a client calls an actor with a particular id (for example, actor id 123), the Dapr instance for the client hashes the actor type and id, and uses the information to call onto the corresponding Dapr instance that can serve the requests for that particular actor id. As a result, the same partition (or service instance) is always called for any given actor id. This is shown in the diagram below. + + + + This simplifies some choices but also carries some consideration: + +* By default, actors are randomly placed into pods resulting in uniform distribution. +* Because actors are randomly placed, it should be expected that actor operations always require network communication, including serialization and deserialization of method call data, incurring latency and overhead. + +Note: The Dapr actor Placement service is only used for actor placement and therefore is not needed if your services are not using Dapr actors. The Placement service can run in all [hosting environments]({{< ref hosting >}}), including self-hosted and Kubernetes. + +## Actor communication + +You can interact with Dapr to invoke the actor method by calling HTTP/gRPC endpoint. ```bash -POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors///method/ +POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/// ``` -You can provide any data for the actor method in the request body and the response for the request is in response body which is data from actor method call. +You can provide any data for the actor method in the request body, and the response for the request would be in the response body which is the data from actor call. -Refer [api spec]({{< ref "actors_api.md#invoke-actor-method" >}}) for more details. +Refer to [Dapr Actor Features]({{< ref actors-overview.md >}}) for more details. -## Actor state management +### Concurrency -Actors can save state reliably using state management capability. +The Dapr Actors runtime provides a simple turn-based access model for accessing actor methods. This means that no more than one thread can be active inside an actor object's code at any time. Turn-based access greatly simplifies concurrent systems as there is no need for synchronization mechanisms for data access. It also means systems must be designed with special considerations for the single-threaded access nature of each actor instance. -You can interact with Dapr through HTTP/gRPC endpoints for state management. +A single actor instance cannot process more than one request at a time. An actor instance can cause a throughput bottleneck if it is expected to handle concurrent requests. -To use actors, your state store must support multi-item transactions. This means your state store [component](https://github.com/dapr/components-contrib/tree/master/state) must implement the [TransactionalStore](https://github.com/dapr/components-contrib/blob/master/state/transactional_store.go) interface. The following state stores implement this interface: +Actors can deadlock on each other if there is a circular request between two actors while an external request is made to one of the actors simultaneously. The Dapr actor runtime automatically times out on actor calls and throw an exception to the caller to interrupt possible deadlock situations. -- Redis -- MongoDB -- PostgreSQL -- SQL Server -- Azure CosmosDB + -## Actor timers and reminders -Actors can schedule periodic work on themselves by registering either timers or reminders. +### Turn-based access -### Actor timers +A turn consists of the complete execution of an actor method in response to a request from other actors or clients, or the complete execution of a timer/reminder callback. Even though these methods and callbacks are asynchronous, the Dapr Actors runtime does not interleave them. A turn must be fully finished before a new turn is allowed. In other words, an actor method or timer/reminder callback that is currently executing must be fully finished before a new call to a method or callback is allowed. A method or callback is considered to have finished if the execution has returned from the method or callback and the task returned by the method or callback has finished. It is worth emphasizing that turn-based concurrency is respected even across different methods, timers, and callbacks. -You can register a callback on actor to be executed based on a timer. +The Dapr actors runtime enforces turn-based concurrency by acquiring a per-actor lock at the beginning of a turn and releasing the lock at the end of the turn. Thus, turn-based concurrency is enforced on a per-actor basis and not across actors. Actor methods and timer/reminder callbacks can execute simultaneously on behalf of different actors. -The Dapr actor runtime ensures that the callback methods respect the turn-based concurrency guarantees.This means that no other actor methods or timer/reminder callbacks will be in progress until this callback completes execution. +The following example illustrates the above concepts. Consider an actor type that implements two asynchronous methods (say, Method1 and Method2), a timer, and a reminder. The diagram below shows an example of a timeline for the execution of these methods and callbacks on behalf of two actors (ActorId1 and ActorId2) that belong to this actor type. -The next period of the timer starts after the callback completes execution. This implies that the timer is stopped while the callback is executing and is started when the callback finishes. + -The Dapr actors runtime saves changes made to the actor's state when the callback finishes. If an error occurs in saving the state, that actor object is deactivated and a new instance will be activated. - -All timers are stopped when the actor is deactivated as part of garbage collection. No timer callbacks are invoked after that. Also, the Dapr actors runtime does not retain any information about the timers that were running before deactivation. It is up to the actor to register any timers that it needs when it is reactivated in the future. - -You can create a timer for an actor by calling the HTTP/gRPC request to Dapr. - -```http -POST/PUT http://localhost:3500/v1.0/actors///timers/ -``` - -The timer `duetime` and callback are specified in the request body. The due time represents when the timer will first fire after registration. The `period` represents how often the timer fires after that. A due time of 0 means to fire immediately. Negative due times and negative periods are invalid. - -The following request body configures a timer with a `dueTime` of 9 seconds and a `period` of 3 seconds. This means it will first fire after 9 seconds, then every 3 seconds after that. -```json -{ - "dueTime":"0h0m9s0ms", - "period":"0h0m3s0ms" -} -``` - -The following request body configures a timer with a `dueTime` 0 seconds and a `period` of 3 seconds. This means it fires immediately after registration, then every 3 seconds after that. -```json -{ - "dueTime":"0h0m0s0ms", - "period":"0h0m3s0ms" -} -``` - -You can remove the actor timer by calling - -```http -DELETE http://localhost:3500/v1.0/actors///timers/ -``` - -Refer [api spec]({{< ref "actors_api.md#invoke-timer" >}}) for more details. - -### Actor reminders - -Reminders are a mechanism to trigger *persistent* callbacks on an actor at specified times. Their functionality is similar to timers. But unlike timers, reminders are triggered under all circumstances until the actor explicitly unregisters them or the actor is explicitly deleted. Specifically, reminders are triggered across actor deactivations and failovers because the Dapr actors runtime persists the information about the actors' reminders using Dapr actor state provider. - -You can create a persistent reminder for an actor by calling the Http/gRPC request to Dapr. - -```http -POST/PUT http://localhost:3500/v1.0/actors///reminders/ -``` - -The reminder `duetime` and callback can be specified in the request body. The due time represents when the reminder first fires after registration. The `period` represents how often the reminder will fire after that. A due time of 0 means to fire immediately. Negative due times and negative periods are invalid. To register a reminder that fires only once, set the period to an empty string. - -The following request body configures a reminder with a `dueTime` 9 seconds and a `period` of 3 seconds. This means it will first fire after 9 seconds, then every 3 seconds after that. -```json -{ - "dueTime":"0h0m9s0ms", - "period":"0h0m3s0ms" -} -``` - -The following request body configures a reminder with a `dueTime` 0 seconds and a `period` of 3 seconds. This means it will fire immediately after registration, then every 3 seconds after that. -```json -{ - "dueTime":"0h0m0s0ms", - "period":"0h0m3s0ms" -} -``` - -The following request body configures a reminder with a `dueTime` 15 seconds and a `period` of empty string. This means it will first fire after 15 seconds, then never fire again. -```json -{ - "dueTime":"0h0m15s0ms", - "period":"" -} -``` - -#### Retrieve actor reminder - -You can retrieve the actor reminder by calling - -```http -GET http://localhost:3500/v1.0/actors///reminders/ -``` - -#### Remove the actor reminder - -You can remove the actor reminder by calling - -```http -DELETE http://localhost:3500/v1.0/actors///reminders/ -``` - -Refer [api spec]({{< ref "actors_api.md#invoke-reminder" >}}) for more details. diff --git a/daprdocs/content/en/developing-applications/building-blocks/actors/howto-actors.md b/daprdocs/content/en/developing-applications/building-blocks/actors/howto-actors.md new file mode 100644 index 000000000..82fb6e97a --- /dev/null +++ b/daprdocs/content/en/developing-applications/building-blocks/actors/howto-actors.md @@ -0,0 +1,137 @@ +--- +type: docs +title: "How-to: Use virtual actors in Dapr" +linkTitle: "How-To: Virtual actors" +weight: 20 +description: Learn more about the actor pattern +--- + +The Dapr actors runtime provides support for [virtual actors]({{< ref actors-overview.md >}}) through following capabilities: + +## Actor method invocation + +You can interact with Dapr to invoke the actor method by calling HTTP/gRPC endpoint + +```html +POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors///method/ +``` + +You can provide any data for the actor method in the request body and the response for the request is in response body which is data from actor method call. + +Refer [api spec]({{< ref "actors_api.md#invoke-actor-method" >}}) for more details. + +## Actor state management + +Actors can save state reliably using state management capability. + +You can interact with Dapr through HTTP/gRPC endpoints for state management. + +To use actors, your state store must support multi-item transactions. This means your state store [component](https://github.com/dapr/components-contrib/tree/master/state) must implement the [TransactionalStore](https://github.com/dapr/components-contrib/blob/master/state/transactional_store.go) interface. The following state stores implement this interface: + +- Redis +- MongoDB +- PostgreSQL +- SQL Server +- Azure CosmosDB + +## Actor timers and reminders + +Actors can schedule periodic work on themselves by registering either timers or reminders. + +### Actor timers + +You can register a callback on actor to be executed based on a timer. + +The Dapr actor runtime ensures that the callback methods respect the turn-based concurrency guarantees.This means that no other actor methods or timer/reminder callbacks will be in progress until this callback completes execution. + +The next period of the timer starts after the callback completes execution. This implies that the timer is stopped while the callback is executing and is started when the callback finishes. + +The Dapr actors runtime saves changes made to the actor's state when the callback finishes. If an error occurs in saving the state, that actor object is deactivated and a new instance will be activated. + +All timers are stopped when the actor is deactivated as part of garbage collection. No timer callbacks are invoked after that. Also, the Dapr actors runtime does not retain any information about the timers that were running before deactivation. It is up to the actor to register any timers that it needs when it is reactivated in the future. + +You can create a timer for an actor by calling the HTTP/gRPC request to Dapr. + +```md +POST/PUT http://localhost:3500/v1.0/actors///timers/ +``` + +The timer `duetime` and callback are specified in the request body. The due time represents when the timer will first fire after registration. The `period` represents how often the timer fires after that. A due time of 0 means to fire immediately. Negative due times and negative periods are invalid. + +The following request body configures a timer with a `dueTime` of 9 seconds and a `period` of 3 seconds. This means it will first fire after 9 seconds, then every 3 seconds after that. +```json +{ + "dueTime":"0h0m9s0ms", + "period":"0h0m3s0ms" +} +``` + +The following request body configures a timer with a `dueTime` 0 seconds and a `period` of 3 seconds. This means it fires immediately after registration, then every 3 seconds after that. +```json +{ + "dueTime":"0h0m0s0ms", + "period":"0h0m3s0ms" +} +``` + +You can remove the actor timer by calling + +```md +DELETE http://localhost:3500/v1.0/actors///timers/ +``` + +Refer [api spec]({{< ref "actors_api.md#invoke-timer" >}}) for more details. + +### Actor reminders + +Reminders are a mechanism to trigger *persistent* callbacks on an actor at specified times. Their functionality is similar to timers. But unlike timers, reminders are triggered under all circumstances until the actor explicitly unregisters them or the actor is explicitly deleted. Specifically, reminders are triggered across actor deactivations and failovers because the Dapr actors runtime persists the information about the actors' reminders using Dapr actor state provider. + +You can create a persistent reminder for an actor by calling the Http/gRPC request to Dapr. + +```md +POST/PUT http://localhost:3500/v1.0/actors///reminders/ +``` + +The reminder `duetime` and callback can be specified in the request body. The due time represents when the reminder first fires after registration. The `period` represents how often the reminder will fire after that. A due time of 0 means to fire immediately. Negative due times and negative periods are invalid. To register a reminder that fires only once, set the period to an empty string. + +The following request body configures a reminder with a `dueTime` 9 seconds and a `period` of 3 seconds. This means it will first fire after 9 seconds, then every 3 seconds after that. +```json +{ + "dueTime":"0h0m9s0ms", + "period":"0h0m3s0ms" +} +``` + +The following request body configures a reminder with a `dueTime` 0 seconds and a `period` of 3 seconds. This means it will fire immediately after registration, then every 3 seconds after that. +```json +{ + "dueTime":"0h0m0s0ms", + "period":"0h0m3s0ms" +} +``` + +The following request body configures a reminder with a `dueTime` 15 seconds and a `period` of empty string. This means it will first fire after 15 seconds, then never fire again. +```json +{ + "dueTime":"0h0m15s0ms", + "period":"" +} +``` + +#### Retrieve actor reminder + +You can retrieve the actor reminder by calling + +```md +GET http://localhost:3500/v1.0/actors///reminders/ +``` + +#### Remove the actor reminder + +You can remove the actor reminder by calling + +```md +DELETE http://localhost:3500/v1.0/actors///reminders/ +``` + +Refer [api spec]({{< ref "actors_api.md#invoke-reminder" >}}) for more details. From 41e82bb28cd5b27286bb2aa36c8c36013674ffb5 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Fri, 8 Jan 2021 22:17:47 -0800 Subject: [PATCH 20/39] Update SDK overview --- .../en/developing-applications/sdks/_index.md | 39 +++++++++++++++- .../sdks/sdk-overview.md | 44 ------------------- 2 files changed, 38 insertions(+), 45 deletions(-) delete mode 100644 daprdocs/content/en/developing-applications/sdks/sdk-overview.md diff --git a/daprdocs/content/en/developing-applications/sdks/_index.md b/daprdocs/content/en/developing-applications/sdks/_index.md index 34b1f5b35..5e7760eb2 100644 --- a/daprdocs/content/en/developing-applications/sdks/_index.md +++ b/daprdocs/content/en/developing-applications/sdks/_index.md @@ -1,7 +1,44 @@ --- type: docs -title: "SDKs" +title: "Dapr Software Development Kits (SDKs)" linkTitle: "SDKs" weight: 20 description: "Use your favorite languages with Dapr" +no_list: true --- + +The Dapr SDKs are the easiest way for you to get Dapr into your application. Choose your favorite language and get up and running with Dapr in minutes. + +## SDK packages + +- **Client SDK**: The Dapr client allows you to invoke Dapr building block APIs and perform actions such as: + - [Invoke]({{< ref service-invocation >}}) methods on other services + - Store and get [state]({{< ref state-management >}}) + - [Publish and subscribe]({{< ref pubsub >}}) to message topics + - Interact with external resources through input and output [bindings]({{< ref bindings >}}) + - Get [secrets]({{< ref secrets >}}) from secret stores + - Interact with [virtual actors]({{< ref actors >}}) +- **Server SDK**: The Dapr server extensions allow you to create services that can: + - Be [invoked]({{< ref service-invocation >}}) by other services + - [Subscribe]({{< ref pubsub >}}) to topics +- **Actor SDK**: The Dapr Actor SDK allows you to build virtual actors with: + - Methods that can be [invoked]({{< ref "howto-actors.md#actor-method-invocation" >}}) by other services + - [State]({{< ref "howto-actors.md#actor-state-management" >}}) that can be stored and retrieved + - [Timers]({{< ref "howto-actors.md#actor-timers" >}}) with callbacks + - Persistent [reminders]({{< ref "howto-actors.md#actor-reminders" >}}) + +## SDK languages + +| Language | State | Client SDK | Service SDK | Actor SDK | +|----------|:-----:|:----------:|:-----------:|:---------:| +| [.NET](https://github.com/dapr/dotnet-sdk) | In Development | ✔ | ✔ (ASP.NET Core) | ✔ | +| [Python](https://github.com/dapr/python-sdk) | In Development | ✔ | ✔ | ✔ | +| [Java](https://github.com/dapr/java-sdk) | In Development | ✔ | ✔ (Spring Boot) | ✔ | +| [Go](https://github.com/dapr/go-sdk) | In Development | ✔ | ✔ | | +| [C++](https://github.com/dapr/cpp-sdk) | Backlog | ✔ | | +| [Rust]() | Backlog | ✔ | | | +| [Javascript]() | Backlog | ✔ | | + +## Further reading + +- [Serialization in the Dapr SDKs]({{< ref sdk-serialization.md >}}) \ No newline at end of file diff --git a/daprdocs/content/en/developing-applications/sdks/sdk-overview.md b/daprdocs/content/en/developing-applications/sdks/sdk-overview.md deleted file mode 100644 index 6282879c3..000000000 --- a/daprdocs/content/en/developing-applications/sdks/sdk-overview.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -type: docs -title: "Overview of Dapr SDKs" -linkTitle: "Overview" -description: "An overview of the languages and capabilities of the Dapr SDKs" -weight: 1000 ---- - -The Dapr SDKs are the easiest way for you to get Dapr into your application. Choose your favorite language to get started today! - -## SDK capabilities - -- **Client SDK**: The Dapr client allows you to invoke Dapr building block APIs and perform actions such as: - - **Invoke** methods on other services - - Store and get **state** - - **Publish** messages to topics - - **Subscribe** to topics - - Interact with external resources through input and output **bindings** - - Get **secrets** from secret stores - - Interact with **virtual actors** -- **Service SDK**: The Dapr service allows you to create services that can: - - Be **invoked** by other services - - **Subscribe** to topics -- **Actor SDK**: The Dapr Actor SDK allows you to build virtual actors with: - - Methods that can be **invoked** by other services - - **State** that can be stored and retrieved - - **Timers** with callbacks - - Persistent **reminders** - -## SDK languages - -| Language | State | Client SDK | Service SDK | Actor SDK | -|----------|:-----:|:----------:|:-----------:|:---------:| -| [.NET](https://github.com/dapr/dotnet-sdk) | In Development | ✔ | ✔ (ASP.NET) | ✔ | -| [Python](https://github.com/dapr/python-sdk) | In Development | ✔ | ✔ | ✔ | -| [Java](https://github.com/dapr/java-sdk) | In Development | ✔ | ✔ (Spring Boot) | ✔ | -| [Go](https://github.com/dapr/go-sdk) | In Development | ✔ | ✔ | | -| [C++](https://github.com/dapr/cpp-sdk) | Backlog | ✔ | | -| [Rust]() | Backlog | ✔ | | | -| [Javascript]() | Backlog | ✔ | | - -## Further reading - -- [Serialization in the Dapr SDKs]({{< ref sdk-serialization.md >}}) \ No newline at end of file From da5a61fa2f99f95a1ce86fc9974f002e7cfb67eb Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Fri, 8 Jan 2021 22:18:08 -0800 Subject: [PATCH 21/39] Update python version --- sdkdocs/python | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdkdocs/python b/sdkdocs/python index a0a68ca33..d87b257a4 160000 --- a/sdkdocs/python +++ b/sdkdocs/python @@ -1 +1 @@ -Subproject commit a0a68ca333d7432eba9847e955c50b284dec8a11 +Subproject commit d87b257a4ed945fd87c40bf95ec4a7bc986859a5 From 0f67a93eb5ebd932b3b2b049818ed165aa1f5870 Mon Sep 17 00:00:00 2001 From: xavier geerinck Date: Wed, 13 Jan 2021 16:15:13 +0100 Subject: [PATCH 22/39] Clarify Service Bus Queues Binding to illustrate that Endpoint= is required --- .../setup-bindings/supported-bindings/servicebusqueues.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/daprdocs/content/en/operations/components/setup-bindings/supported-bindings/servicebusqueues.md b/daprdocs/content/en/operations/components/setup-bindings/supported-bindings/servicebusqueues.md index f049f3057..b4b7b1bb7 100644 --- a/daprdocs/content/en/operations/components/setup-bindings/supported-bindings/servicebusqueues.md +++ b/daprdocs/content/en/operations/components/setup-bindings/supported-bindings/servicebusqueues.md @@ -18,7 +18,7 @@ spec: version: v1 metadata: - name: connectionString - value: "sb://************" + value: "Endpoint=sb://************" - name: queueName value: queue1 - name: ttlInSeconds @@ -66,4 +66,4 @@ curl -X POST http://localhost:3500/v1.0/bindings/myServiceBusQueue \ - [Bindings building block]({{< ref bindings >}}) - [How-To: Trigger application with input binding]({{< ref howto-triggers.md >}}) - [How-To: Use bindings to interface with external resources]({{< ref howto-bindings.md >}}) -- [Bindings API reference]({{< ref bindings_api.md >}}) \ No newline at end of file +- [Bindings API reference]({{< ref bindings_api.md >}}) From 924efe589fbf568daaa56ebdf70adcf4c0592825 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Thu, 14 Jan 2021 16:36:21 -0800 Subject: [PATCH 23/39] Update python doc references --- daprdocs/config.toml | 3 +++ sdkdocs/python | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/daprdocs/config.toml b/daprdocs/config.toml index ac2ea7bc0..6d82f9652 100644 --- a/daprdocs/config.toml +++ b/daprdocs/config.toml @@ -40,6 +40,9 @@ id = "UA-149338238-3" [[module.mounts]] source = "../sdkdocs/python/daprdocs/content/en/python-sdk-docs" target = "content/developing-applications/sdks/python" + [[module.mounts]] + source = "../sdkdocs/python/daprdocs/content/en/python-sdk-contributing" + target = "content/contributing/" # Markdown Engine - Allow inline html [markup] diff --git a/sdkdocs/python b/sdkdocs/python index d87b257a4..bb1afd5b8 160000 --- a/sdkdocs/python +++ b/sdkdocs/python @@ -1 +1 @@ -Subproject commit d87b257a4ed945fd87c40bf95ec4a7bc986859a5 +Subproject commit bb1afd5b8fb7dd4c445b05775b1374f17ae83c49 From 02681ef858094489e773e4003de58f649e5ab78b Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Fri, 15 Jan 2021 09:20:40 -0800 Subject: [PATCH 24/39] Update SDK page --- .../en/developing-applications/sdks/_index.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/daprdocs/content/en/developing-applications/sdks/_index.md b/daprdocs/content/en/developing-applications/sdks/_index.md index 5e7760eb2..ec5ac5393 100644 --- a/daprdocs/content/en/developing-applications/sdks/_index.md +++ b/daprdocs/content/en/developing-applications/sdks/_index.md @@ -18,22 +18,22 @@ The Dapr SDKs are the easiest way for you to get Dapr into your application. Cho - Interact with external resources through input and output [bindings]({{< ref bindings >}}) - Get [secrets]({{< ref secrets >}}) from secret stores - Interact with [virtual actors]({{< ref actors >}}) -- **Server SDK**: The Dapr server extensions allow you to create services that can: - - Be [invoked]({{< ref service-invocation >}}) by other services - - [Subscribe]({{< ref pubsub >}}) to topics - **Actor SDK**: The Dapr Actor SDK allows you to build virtual actors with: - Methods that can be [invoked]({{< ref "howto-actors.md#actor-method-invocation" >}}) by other services - [State]({{< ref "howto-actors.md#actor-state-management" >}}) that can be stored and retrieved - [Timers]({{< ref "howto-actors.md#actor-timers" >}}) with callbacks - Persistent [reminders]({{< ref "howto-actors.md#actor-reminders" >}}) +- **Service Extensions**: The Dapr service extensions allow you to create services that can: + - Be [invoked]({{< ref service-invocation >}}) by other services + - [Subscribe]({{< ref pubsub >}}) to topics ## SDK languages -| Language | State | Client SDK | Service SDK | Actor SDK | +| Language | State | Client SDK | Service Extensions | Actor SDK | |----------|:-----:|:----------:|:-----------:|:---------:| -| [.NET](https://github.com/dapr/dotnet-sdk) | In Development | ✔ | ✔ (ASP.NET Core) | ✔ | -| [Python](https://github.com/dapr/python-sdk) | In Development | ✔ | ✔ | ✔ | -| [Java](https://github.com/dapr/java-sdk) | In Development | ✔ | ✔ (Spring Boot) | ✔ | +| [.NET](https://github.com/dapr/dotnet-sdk) | In Development | ✔ | ASP.NET Core | ✔ | +| [Python](https://github.com/dapr/python-sdk) | In Development | ✔ | [gRPC]({{< ref python-grpc.md >}}) | [FastAPI]({{< ref python-fastapi.md >}})
[Flask]({{< ref python-flask.md >}}) | +| [Java](https://github.com/dapr/java-sdk) | In Development | ✔ | Spring Boot | ✔ | | [Go](https://github.com/dapr/go-sdk) | In Development | ✔ | ✔ | | | [C++](https://github.com/dapr/cpp-sdk) | Backlog | ✔ | | | [Rust]() | Backlog | ✔ | | | From c7444f41bc792648a5aae9dc839c980dd6f11e87 Mon Sep 17 00:00:00 2001 From: Radoslav Gatev Date: Sun, 17 Jan 2021 21:19:59 +0200 Subject: [PATCH 25/39] fix link in readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 056a4a9c8..aafd1edab 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ npm install ```sh hugo server --disableFastRender ``` -3. Navigate to `http://localhost:1313/docs` +3. Navigate to `http://localhost:1313/` ## Update docs 1. Fork repo into your account From f94f0a73e1084ec7db2c63031bfaba4d6bedba6a Mon Sep 17 00:00:00 2001 From: Radoslav Gatev Date: Sun, 17 Jan 2021 22:17:07 +0200 Subject: [PATCH 26/39] Add rate limit middleware --- .../middleware/middleware-rate-limit.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 daprdocs/content/en/developing-applications/middleware/middleware-rate-limit.md diff --git a/daprdocs/content/en/developing-applications/middleware/middleware-rate-limit.md b/daprdocs/content/en/developing-applications/middleware/middleware-rate-limit.md new file mode 100644 index 000000000..2bf9e1795 --- /dev/null +++ b/daprdocs/content/en/developing-applications/middleware/middleware-rate-limit.md @@ -0,0 +1,30 @@ +--- +type: docs +title: "How-To: Rate limiting" +linkTitle: "How-To: Rate limiting" +weight: 1000 +description: "Use Dapr rate limit middleware to limit requests per second" +type: docs +--- + +The Dapr Rate limit [HTTP middleware]({{< ref middleware-concept.md >}}) allows restricting the maximum number of allowed HTTP requests per second. + +## Middleware Component Definition + +In the following definition, the maximum requests per second are set to 10: +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: ratelimit +spec: + type: middleware.http.ratelimit + metadata: + - name: maxRequestsPerSecond + value: 10 +``` +Once the limit is reached, the request will return *HTTP Status code 429: Too Many Requests*. + +## Referencing the rate limit middleware + +To be applied, the middleware must be referenced in a [Dapr Configuration]({{< ref configuration-concept.md >}}). See [Middleware pipelines]({{< ref "middleware-concept.md#customize-processing-pipeline">}}). \ No newline at end of file From 222dfe982c95d87ee61d361b594c14e90212d458 Mon Sep 17 00:00:00 2001 From: Radoslav Gatev Date: Sun, 17 Jan 2021 22:29:56 +0200 Subject: [PATCH 27/39] update justification --- .../en/operations/configuration/control-concurrency.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/daprdocs/content/en/operations/configuration/control-concurrency.md b/daprdocs/content/en/operations/configuration/control-concurrency.md index 73279b685..454a0479b 100644 --- a/daprdocs/content/en/operations/configuration/control-concurrency.md +++ b/daprdocs/content/en/operations/configuration/control-concurrency.md @@ -9,9 +9,9 @@ description: "Control how many requests and events will invoke your application A common scenario in distributed computing is to only allow for a given number of requests to execute concurrently. Using Dapr, you can control how many requests and events will invoke your application simultaneously. -*Note that this rate limiting is guaranteed for every event that's coming from Dapr, meaning Pub/Sub events, direct invocation from other services, bindings events etc. Dapr can't enforce the concurrency policy on requests that are coming to your app externally.* +*Note that this rate limiing is guaranteed for every event that's coming from Dapr, meaning Pub/Sub events, direct invocation from other services, bindings events etc. Dapr can't enforce the concurrency policy on requests that are coming to your app externally.* -*Note that rate limitting can be achieved by using the **middleware.http.ratelimit**. However, there is an imporant difference between the two approaches. The ratelimit middlware is time bound and limits the number of requests per second, while the app-max-concurrency specifies the number of concurrent requests (and events) at any point of time.* +*Note that rate limiting per second can be achieved by using the **middleware.http.ratelimit** middleware. However, there is an imporant difference between the two approaches. The rate limit middlware is time bound and limits the number of requests per second, while the `app-max-concurrency` flag specifies the number of concurrent requests (and events) at any point of time. See [Rate limit middleware]({{< ref middleware-rate-limit.md >}}). * ## Setting app-max-concurrency From b5a2760ab0a0f5b85311439ba2deb77f214f06ba Mon Sep 17 00:00:00 2001 From: Tom Kerkhove Date: Mon, 18 Jan 2021 13:14:55 +0100 Subject: [PATCH 28/39] Fix broken link in common issues --- daprdocs/content/en/operations/troubleshooting/common_issues.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/operations/troubleshooting/common_issues.md b/daprdocs/content/en/operations/troubleshooting/common_issues.md index b9e19f66d..f904b9149 100644 --- a/daprdocs/content/en/operations/troubleshooting/common_issues.md +++ b/daprdocs/content/en/operations/troubleshooting/common_issues.md @@ -82,7 +82,7 @@ The most common cause of this failure is that a component (such as a state store To diagnose the root cause: -- Significantly increase the liveness probe delay - [link]{{< ref "kubernetes-overview.md" >}}) +- Significantly increase the liveness probe delay - [link]({{< ref "kubernetes-overview.md" >}}) - Set the log level of the sidecar to debug - [link]({{< ref "logs-troubleshooting.md#setting-the-sidecar-log-level" >}}) - Watch the logs for meaningful information - [link]({{< ref "logs-troubleshooting.md#viewing-logs-on-kubernetes" >}}) From 6de234e98cd7ad50b412e1375bdc19c68ddd2f3f Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Tue, 19 Jan 2021 10:21:53 -0800 Subject: [PATCH 29/39] Move Service extensions --- .../content/en/developing-applications/sdks/_index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/daprdocs/content/en/developing-applications/sdks/_index.md b/daprdocs/content/en/developing-applications/sdks/_index.md index ec5ac5393..088457511 100644 --- a/daprdocs/content/en/developing-applications/sdks/_index.md +++ b/daprdocs/content/en/developing-applications/sdks/_index.md @@ -18,21 +18,21 @@ The Dapr SDKs are the easiest way for you to get Dapr into your application. Cho - Interact with external resources through input and output [bindings]({{< ref bindings >}}) - Get [secrets]({{< ref secrets >}}) from secret stores - Interact with [virtual actors]({{< ref actors >}}) +- **Service Extensions**: The Dapr service extensions allow you to create services that can: + - Be [invoked]({{< ref service-invocation >}}) by other services + - [Subscribe]({{< ref pubsub >}}) to topics - **Actor SDK**: The Dapr Actor SDK allows you to build virtual actors with: - Methods that can be [invoked]({{< ref "howto-actors.md#actor-method-invocation" >}}) by other services - [State]({{< ref "howto-actors.md#actor-state-management" >}}) that can be stored and retrieved - [Timers]({{< ref "howto-actors.md#actor-timers" >}}) with callbacks - Persistent [reminders]({{< ref "howto-actors.md#actor-reminders" >}}) -- **Service Extensions**: The Dapr service extensions allow you to create services that can: - - Be [invoked]({{< ref service-invocation >}}) by other services - - [Subscribe]({{< ref pubsub >}}) to topics ## SDK languages | Language | State | Client SDK | Service Extensions | Actor SDK | |----------|:-----:|:----------:|:-----------:|:---------:| | [.NET](https://github.com/dapr/dotnet-sdk) | In Development | ✔ | ASP.NET Core | ✔ | -| [Python](https://github.com/dapr/python-sdk) | In Development | ✔ | [gRPC]({{< ref python-grpc.md >}}) | [FastAPI]({{< ref python-fastapi.md >}})
[Flask]({{< ref python-flask.md >}}) | +| [Python]({{< ref python >}}) | In Development | ✔ | [gRPC]({{< ref python-grpc.md >}}) | [FastAPI]({{< ref python-fastapi.md >}})
[Flask]({{< ref python-flask.md >}}) | | [Java](https://github.com/dapr/java-sdk) | In Development | ✔ | Spring Boot | ✔ | | [Go](https://github.com/dapr/go-sdk) | In Development | ✔ | ✔ | | | [C++](https://github.com/dapr/cpp-sdk) | Backlog | ✔ | | From 46cad82044e6c377ce81131c360a11ceef976e97 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Tue, 19 Jan 2021 10:22:32 -0800 Subject: [PATCH 30/39] Update python version --- sdkdocs/python | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdkdocs/python b/sdkdocs/python index bb1afd5b8..6630270f1 160000 --- a/sdkdocs/python +++ b/sdkdocs/python @@ -1 +1 @@ -Subproject commit bb1afd5b8fb7dd4c445b05775b1374f17ae83c49 +Subproject commit 6630270f172721a3a75105da8d46d3163a31ae2f From f685c24a0acde6199d29b9b9e4032207ea48e0a7 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Tue, 19 Jan 2021 11:08:48 -0800 Subject: [PATCH 31/39] Capitalization fix --- daprdocs/content/en/developing-applications/sdks/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/developing-applications/sdks/_index.md b/daprdocs/content/en/developing-applications/sdks/_index.md index 088457511..c051aba74 100644 --- a/daprdocs/content/en/developing-applications/sdks/_index.md +++ b/daprdocs/content/en/developing-applications/sdks/_index.md @@ -18,7 +18,7 @@ The Dapr SDKs are the easiest way for you to get Dapr into your application. Cho - Interact with external resources through input and output [bindings]({{< ref bindings >}}) - Get [secrets]({{< ref secrets >}}) from secret stores - Interact with [virtual actors]({{< ref actors >}}) -- **Service Extensions**: The Dapr service extensions allow you to create services that can: +- **Service extensions**: The Dapr service extensions allow you to create services that can: - Be [invoked]({{< ref service-invocation >}}) by other services - [Subscribe]({{< ref pubsub >}}) to topics - **Actor SDK**: The Dapr Actor SDK allows you to build virtual actors with: From 883d547f969b2112b3950925f6c132bd7d403f2f Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Tue, 19 Jan 2021 12:10:30 -0800 Subject: [PATCH 32/39] Update commit --- sdkdocs/python | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdkdocs/python b/sdkdocs/python index 6630270f1..69f570a20 160000 --- a/sdkdocs/python +++ b/sdkdocs/python @@ -1 +1 @@ -Subproject commit 6630270f172721a3a75105da8d46d3163a31ae2f +Subproject commit 69f570a207e48e52c87f9d622ce6c3a05c0a1220 From a24bb6aa97280bd80325de37bd46fee4b440d848 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Tue, 19 Jan 2021 12:55:37 -0800 Subject: [PATCH 33/39] Add components step --- .../getting-started/configure-state-pubsub.md | 2 +- .../en/getting-started/get-started-api.md | 8 +-- .../getting-started/get-started-component.md | 66 +++++++++++++++++++ .../install-dapr-kubernetes.md | 2 +- .../getting-started/install-dapr-selfhost.md | 4 +- 5 files changed, 75 insertions(+), 7 deletions(-) diff --git a/daprdocs/content/en/getting-started/configure-state-pubsub.md b/daprdocs/content/en/getting-started/configure-state-pubsub.md index bc64f2813..c3ee15a87 100644 --- a/daprdocs/content/en/getting-started/configure-state-pubsub.md +++ b/daprdocs/content/en/getting-started/configure-state-pubsub.md @@ -1,7 +1,7 @@ --- type: docs title: "How-To: Configure state store and pub/sub message broker" -linkTitle: "Configure state & pub/sub" +linkTitle: "(optional) Configure state & pub/sub" weight: 80 description: "Configure state store and pub/sub message broker components for Dapr" aliases: diff --git a/daprdocs/content/en/getting-started/get-started-api.md b/daprdocs/content/en/getting-started/get-started-api.md index ef3c7f075..1ace6fb54 100644 --- a/daprdocs/content/en/getting-started/get-started-api.md +++ b/daprdocs/content/en/getting-started/get-started-api.md @@ -9,7 +9,7 @@ After running the `dapr init` command in the previous step, your local environme You will now run the sidecar and call the API directly (simulating what an application would do). -### Step 1: Run the Dapr sidecar +## Step 1: Run the Dapr sidecar One the most useful Dapr CLI commands is [`dapr run`]({{< ref dapr-run.md >}}). This command launches an application together with a sidecar. For the purpose of this tutorial you'll run the sidecar without an application. @@ -19,7 +19,7 @@ Run the following command to launch a Dapr sidecar that will listen on port 3500 dapr run --app-id myapp --dapr-http-port 3500 ``` -### Step 2: Save state +## Step 2: Save state In a separate terminal run: @@ -40,7 +40,7 @@ Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '[{ "key": {{< /tabs >}} -### Step 2: Get state +## Step 2: Get state Now get the state you just stored using a key with the state management API: @@ -62,7 +62,7 @@ Invoke-RestMethod -Uri 'http://localhost:3500/v1.0/state/statestore/name' {{< /tabs >}} -### Step 3: See how the state is stored in Redis +## Step 3: See how the state is stored in Redis You can look in the Redis container and verify Dapr is using it as a state store. Run the following to use the Redis CLI: diff --git a/daprdocs/content/en/getting-started/get-started-component.md b/daprdocs/content/en/getting-started/get-started-component.md index 861af2575..73ed2e9a5 100644 --- a/daprdocs/content/en/getting-started/get-started-component.md +++ b/daprdocs/content/en/getting-started/get-started-component.md @@ -5,5 +5,71 @@ linkTitle: "Define a component" weight: 40 --- +After familiarizing yourself with the Dapr HTTP API and state building block in the previous step, you will now create your first Dapr component to try out the [secrets building block]({{< ref secrets >}}). + +In this guide you will: +- Create a local json secret store +- Register the secret store with Dapr using a component +- Obtain the secret using the Dapr HTTP API + +## Step 1: Create a json secret store + +While Dapr supports [many types of secret stores]({{< ref supported-secret-stores >}}), the easiest way to get started is a local json file with your secret. + +Begin by saving the following json contents into a file named `mysecrets.json`: + +```json +{ + "my-secret" : "I'm Batman" +} +``` + +## Step 2: Create a secret store Dapr component + +Within your default Dapr components directory create a file named `localSecretStore.yaml` with the following contents: +- Linux/MacOS: `$HOME/.dapr/components` +- Windows: `%USERPROFILE%\.dapr\components` + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: my-secret-store + namespace: default +spec: + type: secretstores.local.file + version: v1 + metadata: + - name: secretsFile + value: /secrets.json + - name: nestedSeparator + value: ":" +``` + +## Step 3: Run the Dapr sidecar + +Run the following command to 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 +``` + +## Step 4: Get a secret + +In a separate terminal run: + +{{< tabs "HTTP API (Bash)" "HTTP API (PowerShell)">}} +{{% codetab %}} + +```bash +curl http://localhost:3500/v1.0/secrets/my-secret-store/my-secret +``` +{{% /codetab %}} + +{{% codetab %}} +```powershell +Invoke-RestMethod -Uri 'http://localhost:3500/v1.0/secrets/my-secret-store/my-secret' +``` +{{% /codetab %}} Next step: Explore Dapr quickstarts >> diff --git a/daprdocs/content/en/getting-started/install-dapr-kubernetes.md b/daprdocs/content/en/getting-started/install-dapr-kubernetes.md index 591626cd0..523de1e0b 100644 --- a/daprdocs/content/en/getting-started/install-dapr-kubernetes.md +++ b/daprdocs/content/en/getting-started/install-dapr-kubernetes.md @@ -1,7 +1,7 @@ --- type: docs title: "How-To: Install Dapr into a Kubernetes cluster" -linkTitle: "Init Dapr on Kubernetes" +linkTitle: "(optional) Init Dapr on Kubernetes" weight: 70 description: "Install Dapr in a Kubernetes cluster" --- diff --git a/daprdocs/content/en/getting-started/install-dapr-selfhost.md b/daprdocs/content/en/getting-started/install-dapr-selfhost.md index 3df674abf..b750264f4 100644 --- a/daprdocs/content/en/getting-started/install-dapr-selfhost.md +++ b/daprdocs/content/en/getting-started/install-dapr-selfhost.md @@ -105,7 +105,9 @@ Open `%USERPROFILE%\.dapr\` in file explorer: ```powershell explorer "%USERPROFILE%\.dapr\" ``` - + +You will see the Dapr config, Dapr binaries directory, and the default components directory for Dapr: + {{% /codetab %}} From f1d00c9e6a286e0737ca47f15ff98f2c5eb6cc77 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Tue, 19 Jan 2021 13:56:57 -0800 Subject: [PATCH 34/39] Update python commit --- sdkdocs/python | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdkdocs/python b/sdkdocs/python index 69f570a20..abe7b25ef 160000 --- a/sdkdocs/python +++ b/sdkdocs/python @@ -1 +1 @@ -Subproject commit 69f570a207e48e52c87f9d622ce6c3a05c0a1220 +Subproject commit abe7b25ef50d0133f84b3a0553faccfafda43786 From f70e76f51548ac67606208826617de26e3412380 Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Tue, 19 Jan 2021 15:01:34 -0800 Subject: [PATCH 35/39] Editing components getting started --- .../en/getting-started/get-started-api.md | 4 +- .../getting-started/get-started-component.md | 38 ++++++++++++++----- .../getting-started/install-dapr-selfhost.md | 2 +- 3 files changed, 32 insertions(+), 12 deletions(-) diff --git a/daprdocs/content/en/getting-started/get-started-api.md b/daprdocs/content/en/getting-started/get-started-api.md index 1ace6fb54..a26424b82 100644 --- a/daprdocs/content/en/getting-started/get-started-api.md +++ b/daprdocs/content/en/getting-started/get-started-api.md @@ -5,7 +5,7 @@ linkTitle: "Use the Dapr API" weight: 30 --- -After running the `dapr init` command in the previous step, your local environment has the Dapr sidecar binaries as well as default component definitions for both state management and a message broker (both using Redis). You can now try out some of what Dapr has to offer by using the Dapr CLI to run a Dapr sidecar and try out the state API that will allow you to store and retrieve a state. You can learn more about the state building block and how it works in [these docs]({{< ref state-management >}}). +After running the `dapr init` command in the [previous step]({{}}), your local environment has the Dapr sidecar binaries as well as default component definitions for both state management and a message broker (both using Redis). You can now try out some of what Dapr has to offer by using the Dapr CLI to run a Dapr sidecar and try out the state API that will allow you to store and retrieve a state. You can learn more about the state building block and how it works in [these docs]({{< ref state-management >}}). You will now run the sidecar and call the API directly (simulating what an application would do). @@ -19,6 +19,8 @@ Run the following command to launch a Dapr sidecar that will listen on port 3500 dapr run --app-id myapp --dapr-http-port 3500 ``` +With this command, no custom component folder was defined so the Dapr uses the default component definitions that were created during the init flow (these can be found under `$HOME/.dapr/components` on Linux or MacOS and under `%USERPROFILE%\.dapr\components` on Windows). These tell Dapr to the local Redis Docker container as a state store and message broker. + ## Step 2: Save state In a separate terminal run: diff --git a/daprdocs/content/en/getting-started/get-started-component.md b/daprdocs/content/en/getting-started/get-started-component.md index 73ed2e9a5..b9bf65532 100644 --- a/daprdocs/content/en/getting-started/get-started-component.md +++ b/daprdocs/content/en/getting-started/get-started-component.md @@ -5,18 +5,22 @@ linkTitle: "Define a component" weight: 40 --- -After familiarizing yourself with the Dapr HTTP API and state building block in the previous step, you will now create your first Dapr component to try out the [secrets building block]({{< ref secrets >}}). +In the [previous step]({{}}) you called the Dapr HTTP API to store and retrieve a state from a Redis backed state store. Dapr knew to use the Redis instance that was configured locally on your machine through default component definition files that were created when Dapr was initialized. + +When building an app, you most likely would create your own component file definitions depending on the building block and specific component that you'd like to use. + +As an example of how to define custom components for your application, you will now create a component definition file to interact with the [secrets building block]({{< ref secrets >}}). In this guide you will: -- Create a local json secret store -- Register the secret store with Dapr using a component +- Create a local JSON secret store +- Register the secret store with Dapr using a component definition file - Obtain the secret using the Dapr HTTP API -## Step 1: Create a json secret store +## Step 1: Create a JSON secret store -While Dapr supports [many types of secret stores]({{< ref supported-secret-stores >}}), the easiest way to get started is a local json file with your secret. +While Dapr supports [many types of secret stores]({{< ref supported-secret-stores >}}), the easiest way to get started is a local JSON file with your secret (note this secret store is meant for development purposes and is not recommended for production use cases as it is not secured). -Begin by saving the following json contents into a file named `mysecrets.json`: +Begin by saving the following JSON contents into a file named `mysecrets.json`: ```json { @@ -26,9 +30,14 @@ Begin by saving the following json contents into a file named `mysecrets.json`: ## Step 2: Create a secret store Dapr component -Within your default Dapr components directory create a file named `localSecretStore.yaml` with the following contents: -- Linux/MacOS: `$HOME/.dapr/components` -- Windows: `%USERPROFILE%\.dapr\components` +Create a new directory named `my-components` to hold the new component file: + +```bash +mkdir my-components +``` + +Inside this directory create a new file `localSecretStore.yaml` with the following contents: + ```yaml apiVersion: dapr.io/v1alpha1 @@ -46,12 +55,14 @@ spec: value: ":" ``` +You can see that the above file definition has a `type: secretstores.local.file` which tells Dapr to use the local file component as a secret store. The metadata fields provide component specific information needed to work with this component (in this case, the path to the secret store JSON) + ## Step 3: Run the Dapr sidecar Run the following command to 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 +dapr run --app-id myapp --dapr-http-port 3500 --components-path ./my-components ``` ## Step 4: Get a secret @@ -71,5 +82,12 @@ curl http://localhost:3500/v1.0/secrets/my-secret-store/my-secret Invoke-RestMethod -Uri 'http://localhost:3500/v1.0/secrets/my-secret-store/my-secret' ``` {{% /codetab %}} +{{< /tabs >}} + +You should see output with the secret you stored in the JSON file. + +``` +"I'm Batman" +``` Next step: Explore Dapr quickstarts >> diff --git a/daprdocs/content/en/getting-started/install-dapr-selfhost.md b/daprdocs/content/en/getting-started/install-dapr-selfhost.md index b750264f4..5b2c14b9c 100644 --- a/daprdocs/content/en/getting-started/install-dapr-selfhost.md +++ b/daprdocs/content/en/getting-started/install-dapr-selfhost.md @@ -7,7 +7,7 @@ aliases: - /getting-started/install-dapr/ --- -Now that you have the Dapr CLI installed, it's time to initialize Dapr on your local machine using the CLI. +Now that you have the [Dapr CLI installed]({{}}), it's time to initialize Dapr on your local machine using the CLI. Dapr runs as a sidecar alongside your application, and in self-hosted mode this means it is a process on your local machine. Therefore, initializing Dapr includes fetching the Dapr sidecar binaries and installing them locally. From 28df158454e2a63d818028c84466cabb7cd109e8 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Tue, 19 Jan 2021 15:22:00 -0800 Subject: [PATCH 36/39] Switch to master branch --- sdkdocs/python | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdkdocs/python b/sdkdocs/python index abe7b25ef..3d610a4db 160000 --- a/sdkdocs/python +++ b/sdkdocs/python @@ -1 +1 @@ -Subproject commit abe7b25ef50d0133f84b3a0553faccfafda43786 +Subproject commit 3d610a4db9a589d85de7fa20c42be1934a1d6f0e From f5195969a3e0ed8d357d31efbb613619b4448d53 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Tue, 19 Jan 2021 22:30:15 -0800 Subject: [PATCH 37/39] Update title casing and weight --- .../middleware/middleware-opa-policies.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/daprdocs/content/en/developing-applications/middleware/middleware-opa-policies.md b/daprdocs/content/en/developing-applications/middleware/middleware-opa-policies.md index 0c6dd56b4..13e8dc445 100644 --- a/daprdocs/content/en/developing-applications/middleware/middleware-opa-policies.md +++ b/daprdocs/content/en/developing-applications/middleware/middleware-opa-policies.md @@ -1,15 +1,16 @@ --- type: docs -title: "How-To: Apply OPA policies" -linkTitle: "How-To: Apply OPA policies" -weight: 1000 +title: "How-To: Apply Open Policy Agent (OPA) policies" +linkTitle: "Apply OPA policies" +weight: 2000 description: "Use Dapr middleware to apply Open Policy Agent (OPA) policies on incoming requests" type: docs --- -The Dapr Open Policy Agent (OPA) [HTTP middleware](https://github.com/dapr/docs/blob/master/concepts/middleware/README.md) allows applying [OPA Policies](https://www.openpolicyagent.org/) to incoming Dapr HTTP requests. This can be used to apply reusable authorization policies to app endpoints. +The Dapr Open Policy Agent (OPA) [HTTP middleware]({{< ref middleware-concept.md >}}) allows applying [OPA Policies](https://www.openpolicyagent.org/) to incoming Dapr HTTP requests. This can be used to apply reusable authorization policies to app endpoints. + +## Middleware component definition -## Middleware Component Definition ```yaml apiVersion: dapr.io/v1alpha1 kind: Component @@ -59,7 +60,6 @@ spec: } { my_claim := jwt.payload["my-claim"] } - jwt = { "payload": payload } { auth_header := input.request.headers["authorization"] [_, jwt] := split(auth_header, " ") @@ -122,7 +122,7 @@ default allow = { } ``` -### Changing the Rejected Response Status Code +### Changing the rejected response status code When rejecting a request, you can override the status code the that gets returned. For example, if you wanted to return a `401` instead of a `403`, you could do the following: @@ -135,7 +135,7 @@ default allow = { } ``` -### Adding Response Headers +### Adding response headers To redirect, add headers and set the `status_code` to the returned result: @@ -151,7 +151,7 @@ default allow = { } ``` -### Adding Request Headers +### Adding request headers You can also set additional headers on the allowed request: @@ -162,12 +162,12 @@ default allow = false allow = { "allow": true, "additional_headers": { "X-JWT-Payload": payload } } { not input.path[0] == "forbidden" - # Where `jwt` is the result of another rule + // Where `jwt` is the result of another rule payload := base64.encode(json.marshal(jwt.payload)) } ``` -### Result Structure +### Result structure ```go type Result bool // or @@ -183,5 +183,5 @@ type Result struct { ## Related links -- Open Policy Agent: https://www.openpolicyagent.org -- HTTP API Example: https://www.openpolicyagent.org/docs/latest/http-api-authorization/ \ No newline at end of file +- [Open Policy Agent](https://www.openpolicyagent.org) +- [HTTP API Example](https://www.openpolicyagent.org/docs/latest/http-api-authorization/) \ No newline at end of file From 5babc5aefe8ae8b30f8878f1a0cb45b2c1ebfe75 Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Tue, 19 Jan 2021 22:30:21 -0800 Subject: [PATCH 38/39] Update title --- .../developing-applications/middleware/middleware-rate-limit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/developing-applications/middleware/middleware-rate-limit.md b/daprdocs/content/en/developing-applications/middleware/middleware-rate-limit.md index 2bf9e1795..9184852e3 100644 --- a/daprdocs/content/en/developing-applications/middleware/middleware-rate-limit.md +++ b/daprdocs/content/en/developing-applications/middleware/middleware-rate-limit.md @@ -1,7 +1,7 @@ --- type: docs title: "How-To: Rate limiting" -linkTitle: "How-To: Rate limiting" +linkTitle: "Rate limiting" weight: 1000 description: "Use Dapr rate limit middleware to limit requests per second" type: docs From cc10150e456cfff4d9ee932a05e6941494281a6b Mon Sep 17 00:00:00 2001 From: Aaron Crawfis Date: Tue, 19 Jan 2021 22:33:39 -0800 Subject: [PATCH 39/39] Title casing and related links --- .../middleware/middleware-rate-limit.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/daprdocs/content/en/developing-applications/middleware/middleware-rate-limit.md b/daprdocs/content/en/developing-applications/middleware/middleware-rate-limit.md index 9184852e3..59893979b 100644 --- a/daprdocs/content/en/developing-applications/middleware/middleware-rate-limit.md +++ b/daprdocs/content/en/developing-applications/middleware/middleware-rate-limit.md @@ -9,7 +9,7 @@ type: docs The Dapr Rate limit [HTTP middleware]({{< ref middleware-concept.md >}}) allows restricting the maximum number of allowed HTTP requests per second. -## Middleware Component Definition +## Middleware component definition In the following definition, the maximum requests per second are set to 10: ```yaml @@ -27,4 +27,8 @@ Once the limit is reached, the request will return *HTTP Status code 429: Too Ma ## Referencing the rate limit middleware -To be applied, the middleware must be referenced in a [Dapr Configuration]({{< ref configuration-concept.md >}}). See [Middleware pipelines]({{< ref "middleware-concept.md#customize-processing-pipeline">}}). \ No newline at end of file +To be applied, the middleware must be referenced in a [Dapr Configuration]({{< ref configuration-concept.md >}}). See [Middleware pipelines]({{< ref "middleware-concept.md#customize-processing-pipeline">}}). + +## Related links +- [Middleware concept]({{< ref middleware-concept.md >}}) +- [Dapr configuration]({{< ref configuration-concept.md >}}) \ No newline at end of file