dapr
/
docs
mirror of https://github.com/dapr/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'v0.11' into fix-otel-retry

This commit is contained in:
Nghia Tran 2021-01-27 14:54:42 -08:00 committed by GitHub
parent 14660142c7 3c4661ba9e
commit e9fe330ca0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
107 changed files with 2826 additions and 1547 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
.github/ISSUE_TEMPLATE/new-content-needed.md vendored
View File

@ -8,13 +8,13 @@ assignees: ''
---
**What content needs to be created or modified?**
A clear and concise description of what the problem is. Ex. There should be docs on how pub/sub works...
<!--A clear and concise description of what the problem is. Ex. There should be docs on how pub/sub works...-->
**Describe the solution you'd like**
A clear and concise description of what you want to happen.
<!--A clear and concise description of what you want to happen-->
**Where should the new material be placed?**
Please suggest where in the docs structure the new content should be created.
<!--Please suggest where in the docs structure the new content should be created-->
**Additional context**
Add any other context or screenshots about the feature request here.
<!--Add any other context or screenshots about the feature request here-->

10
.github/ISSUE_TEMPLATE/typo.md vendored
View File

@ -8,16 +8,16 @@ assignees: ''
---
**URL of the docs page**
The URL(s) on docs.dapr.io where the typo occurs
<!--The URL(s) on docs.dapr.io where the typo occurs-->
**How is it currently worded?**
Please copy and paste the sentence where the typo occurs.
<!--Please copy and paste the sentence where the typo occurs-->
**How should it be worded?**
Please correct the sentence
<!--Please correct the sentence-->
**Screenshots**
If applicable, add screenshots to help explain your problem.
<!--If applicable, add screenshots to help explain your problem-->
**Additional context**
Add any other context about the problem here.
<!--Add any other context about the problem here-->

26
.github/ISSUE_TEMPLATE/website-issue.md vendored
View File

@ -8,31 +8,33 @@ assignees: AaronCrawfis
---
**Describe the bug**
A clear and concise description of what the bug is.
<!--A clear and concise description of what the bug is.-->
**To Reproduce**
**Steps to reproduce**
<!--
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
-->
**Expected behavior**
A clear and concise description of what you expected to happen.
<!--A clear and concise description of what you expected to happen.-->
**Screenshots**
If applicable, add screenshots to help explain your problem.
<!--If applicable, add screenshots to help explain your problem.-->
**Desktop (please complete the following information):**
- OS: [e.g. iOS]
- Browser [e.g. chrome, safari]
- Version [e.g. 22]
- OS: <!--[e.g. iOS]-->
- Browser <!--[e.g. chrome, safari]-->
- Version <!--[e.g. 22]-->
**Smartphone (please complete the following information):**
- Device: [e.g. iPhone6]
- OS: [e.g. iOS8.1]
- Browser [e.g. stock browser, safari]
- Version [e.g. 22]
- Device: <!--[e.g. iPhone6]-->
- OS: <!--[e.g. iOS8.1]-->
- Browser <!--[e.g. stock browser, safari]-->
- Version <!--[e.g. 22]-->
**Additional context**
Add any other context about the problem here.
<!--Add any other context about the problem here-->

10
.github/ISSUE_TEMPLATE/wrong-information-code-steps.md vendored
View File

@ -8,16 +8,16 @@ assignees: ''
---
**Describe the issue**
A clear and concise description of what the bug is.
<!--A clear and concise description of what the bug is-->
**URL of the docs**
Paste the URL (docs.dapr.io/concepts/......) of the page
<!--Paste the URL (docs.dapr.io/concepts/......) of the page-->
**Expected content**
A clear and concise description of what you expected to happen.
<!--A clear and concise description of what you expected to happen-->
**Screenshots**
If applicable, add screenshots to help explain your problem.
<!--If applicable, add screenshots to help explain your problem-->
**Additional context**
Add any other context about the problem here.
<!--Add any other context about the problem here-->

13
.github/pull_request_template.md vendored
View File

@ -1,15 +1,20 @@
Thank you for helping make the Dapr documentation better!
If you are a new contributor, please see the [this contribution guidance](https://docs.dapr.io/contributing/contributing-docs/) which helps keep the Dapr documentation readable, consistent and useful for Dapr users.
**Please follow this checklist before submitting:**
Note that you must see that the suggested changes do not break the website [docs.dapr.io](https://docs.dapr.io). See [this overview](https://github.com/dapr/docs/blob/master/README.md#overview) on how to setup a local version of the website and make sure the website is built correctly.
- [ ] [Read the contribution guide](https://docs.dapr.io/contributing/contributing-docs/)
- [ ] Commands include options for Linux, MacOS, and Windows within codetabs
- [ ] New file and folder names are globally unique
- [ ] Page references use shortcodes instead of markdown or URL links
- [ ] Images use HTML style and have alternative text
- [ ] Places where multiple code/command options are given have codetabs
In addition, please fill out the following to help reviewers understand this pull request:
## Description
_Please explain the changes you've made_
<!--Please explain the changes you've made-->
## Issue reference
_Please reference the issue this PR will close: #[issue number]_
<!--Please reference the issue this PR will close: #[issue number]-->

4
.github/workflows/azure-static-web-apps-green-hill-0d7377310.yml vendored
View File

@ -3,11 +3,11 @@ name: Azure Static Web Apps CI/CD
on:
push:
branches:
- website
- v0.11
pull_request:
types: [opened, synchronize, reopened, closed]
branches:
- website
- v0.11
jobs:
build_and_deploy_job:

4
.gitmodules vendored
View File

@ -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

21
README.md
View File

@ -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-rc3+ 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.
@ -47,12 +61,13 @@ 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
1. Create new branch
1. Commit and push changes to content
1. Submit pull request to `master`
1. Commit and push changes to forked branch
1. Submit pull request from downstream branch to the upstream branch for the correct version you are targeting
1. Staging site will automatically get created and linked to PR to review and test
## Code of Conduct

36
daprdocs/config.toml
View File

@ -2,14 +2,13 @@
baseURL = "https://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,33 @@ 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/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]
[markup.goldmark]
@ -58,7 +84,7 @@ offlineSearch = false
github_repo = "https://github.com/dapr/docs"
github_project_repo = "https://github.com/dapr/dapr"
github_subdir = "daprdocs"
github_branch = "website"
github_branch = "v0.11"
# Versioning
version_menu = "v0.11 (latest)"
@ -66,8 +92,8 @@ version = "v0.11"
archived_version = false
[[params.versions]]
version = "v1.0-rc.1 (preview)"
url = "https://v1-rc1.docs.dapr.io"
version = "v1.0-rc.2 (preview)"
url = "https://v1-rc2.docs.dapr.io"
[[params.versions]]
version = "v0.11 (latest)"
url = "#"

4
daprdocs/content/en/_index.md
View File

@ -5,3 +5,7 @@ type: docs
# <img src="/images/home-title.png" alt="Dapr Docs" width=400>
Welcome to the Dapr documentation site!
{{% alert title="New release candidate" color="primary" %}}
v1.0-rc.2 preview is now available to download and test as part of the upcoming Dapr v1.0 release. Visit the [v1.0-rc.2 version of the docs](https://v1-rc2.docs.dapr.io) if you would like to upgrade and use the latest preview version.
{{% /alert %}}

2
daprdocs/content/en/concepts/faq.md
View File

@ -50,7 +50,7 @@ The Dapr runtime SDKs have language specific actor frameworks. The .NET SDK for
### Does Dapr have any SDKs if I want to work with a particular programming language or framework?
To make using Dapr more natural for different languages, it includes language specific SDKs for Go, Java, JavaScript, .NET, Python, RUST and C++.
To make using Dapr more natural for different languages, it includes language specific SDKs for Go, Java, JavaScript, .NET, Python, Rust and C++.
These SDKs expose the functionality in the Dapr building blocks, such as saving state, publishing an event or creating an actor, through a typed, language API rather than calling the http/gRPC API. This enables you to write a combination of stateless and stateful functions and actors all in the language of their choice. And because these SDKs share the Dapr runtime, you get cross-language actor and functions support.

6
daprdocs/content/en/concepts/middleware-concept.md
View File

@ -49,9 +49,9 @@ Your handler implementation can include any inbound logic, outbound logic, or bo
func GetHandler(metadata Metadata) fasthttp.RequestHandler {
return func(h fasthttp.RequestHandler) fasthttp.RequestHandler {
return func(ctx *fasthttp.RequestCtx) {
//inboud logic
h(ctx) //call the downstream handler
//outbound logic
// inboud logic
h(ctx) // call the downstream handler
// outbound logic
}
}
}

4
daprdocs/content/en/concepts/overview.md
View File

@ -7,7 +7,9 @@ description: >
Introduction to the Distributed Application Runtime
---
Dapr is a portable, event-driven runtime that makes it easy for enterprise developers to build resilient, stateless and stateful microservice applications that run on the cloud and edge and embraces the diversity of languages and developer frameworks.
Dapr is a portable, event-driven runtime that makes it easy for any developer to build resilient, stateless and stateful applications that run on the cloud and edge and embraces the diversity of languages and developer frameworks.
{{< youtube 9o9iDAgYBA8 >}}
## Any language, any framework, anywhere

24
daprdocs/content/en/contributing/contributing-docs.md
View File

@ -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.
@ -26,11 +34,12 @@ These conventions should be followed throughout all Dapr documentation to ensure
- **Use simple sentences** - Easy-to-read sentences mean the reader can quickly use the guidance you share.
- **Avoid the first person** - Use 2nd person "you", "your" instead of "I", "we", "our".
- **Assume a new developer audience** - Some obvious steps can seem hard. E.g. Now set an environment variable Dapr to a value X. It is better to give the reader the explicit command to do this, rather than having them figure this out.
- **Use present tense** - Avoid sentences like "this command will install redis", which implies the action is in the future. Instead use "This command installs redis" which is in the present tense.
## Contributing a new docs page
- Make sure the documentation you are writing is in the correct place in the hierarchy.
- Avoid creating new sections where possible, there is a good chance a proper place in the docs hierarchy already exists.
- Make sure to include a complete [Hugo front-matter](front-matter).
- Make sure to include a complete [Hugo front-matter](#front-matter).
### Contributing a new concept doc
- Ensure the reader can understand why they should care about this feature. What problems does it help them solve?
@ -104,8 +113,19 @@ This shortcode will link to a specific page:
```md
{{</* ref "page.md" */>}}
```
> Note that all pages and folders need to have globally unique names in order for the ref shortcode to work properly. If there are duplicate names the build will break and an error will be thrown.
> Note that all pages and folders need to have globally unique names in order for the ref shortcode to work properly.
#### Referencing sections in other pages
To reference a specific section in another page, add `#section-short-name` to the end of your reference.
As a general rule, the section short name is the text of the section title, all lowercase, with spaces changed to "-". You can check the section short name by visiting the website page, clicking the link icon (🔗) next to the section, and see how the URL renders in the nav bar. The content after the "#" is your section shortname.
As an example, for this specific section the complete reference to the page and section would be:
```md
{{</* ref "contributing-docs.md#referencing-sections-in-other-pages" */>}}
```
### Images
The markdown spec used by Docsy and Hugo does not give an option to resize images using markdown notation. Instead, raw HMTL is used.

104
daprdocs/content/en/developing-applications/building-blocks/actors/actors-background.md
View File

@ -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.
<img src="/images/actor_background_game_example.png" width=400>
## 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 register 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.
<img src="/images/actors_background_placement_service_registration.png" width=600>
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.
<img src="/images/actors_background_id_hashing_calling.png" width=600>
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 for example, self hosted, 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/<actorType>/<actorId>/<method/state/timers/reminders>
```
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.
<img src="/images/actors_background_communication.png" width=600>
### 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.
<img src="/images/actors_background_concurrency.png" width=600>

185
daprdocs/content/en/developing-applications/building-blocks/actors/actors-overview.md
View File

@ -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.
<img src="/images/actor_background_game_example.png" width=400>
## 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.
<img src="/images/actors_background_placement_service_registration.png" width=600>
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.
<img src="/images/actors_background_id_hashing_calling.png" width=600>
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/<actorType>/<actorId>/method/<method>
POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/<method/state/timers/reminders>
```
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
<img src="/images/actors_background_communication.png" width=600>
## 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.
<img src="/images/actors_background_concurrency.png" width=600>
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/<actorType>/<actorId>/timers/<name>
```
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/<actorType>/<actorId>/timers/<name>
```
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/<actorType>/<actorId>/reminders/<name>
```
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/<actorType>/<actorId>/reminders/<name>
```
#### Remove the actor reminder
You can remove the actor reminder by calling
```http
DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
```
Refer [api spec]({{< ref "actors_api.md#invoke-reminder" >}}) for more details.

137
daprdocs/content/en/developing-applications/building-blocks/actors/howto-actors.md Normal file
View File

@ -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/<actorType>/<actorId>/method/<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/<actorType>/<actorId>/timers/<name>
```
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/<actorType>/<actorId>/timers/<name>
```
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/<actorType>/<actorId>/reminders/<name>
```
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/<actorType>/<actorId>/reminders/<name>
```
#### Remove the actor reminder
You can remove the actor reminder by calling
```md
DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
```
Refer [api spec]({{< ref "actors_api.md#invoke-reminder" >}}) for more details.

2
daprdocs/content/en/developing-applications/building-blocks/bindings/howto-bindings.md
View File

@ -57,7 +57,7 @@ As seen above, you invoked the `/binding` endpoint with the name of the binding
The payload goes inside the mandatory `data` field, and can be any JSON serializable value.
You'll also notice that there's an `operation` field that tells the binding what you need it to do.
You can check [here]({{< ref bindings >}}) which operations are supported for every output binding.
You can check [here]({{< ref supported-bindings >}}) which operations are supported for every output binding.
## References

7
daprdocs/content/en/developing-applications/building-blocks/bindings/howto-triggers.md
View File

@ -97,6 +97,7 @@ Event delivery guarantees are controlled by the binding implementation. Dependin
## References
* Binding [API](https://github.com/dapr/docs/blob/master/reference/api/bindings_api.md)
* Binding [Components](https://github.com/dapr/docs/tree/master/concepts/bindings)
* Binding [Detailed specifications](https://github.com/dapr/docs/tree/master/reference/specs/bindings)
* [Bindings building block]({{< ref bindings >}})
* [Bindings API]({{< ref bindings_api.md >}})
* [Components concept]({{< ref components-concept.md >}})
* [Supported bindings]({{< ref supported-bindings >}})

24
daprdocs/content/en/developing-applications/building-blocks/observability/tracing.md
View File

@ -29,7 +29,7 @@ Read [W3C distributed tracing]({{< ref w3c-tracing >}}) for more background on W
Dapr uses [probabilistic sampling](https://opencensus.io/tracing/sampling/probabilistic/) as defined by OpenCensus. The sample rate defines the probability a tracing span will be sampled and can have a value between 0 and 1 (inclusive). The deafault sample rate is 0.0001 (i.e. 1 in 10,000 spans is sampled).
To change the default tracing behavior, use a configuration file (in self hosted mode) or a Kubernetes configuration object (in Kubernetes mode). For example, the following configuration object changes the sample rate to 1 (i.e. every span is sampled):
To change the default tracing behavior, use a configuration file (in self hosted mode) or a Kubernetes configuration object (in Kubernetes mode). For example, the following configuration object changes the sample rate to 1 (i.e. every span is sampled), and sends trace using Zipkin protocol to the Zipkin server at http://zipkin.default.svc.cluster.local
```yaml
apiVersion: dapr.io/v1alpha1
@ -40,30 +40,14 @@ metadata:
spec:
tracing:
samplingRate: "1"
zipkin:
endpointAddress: "http://zipkin.default.svc.cluster.local:9411/api/v2/spans"
```
Similarly, changing `samplingRate` to 0 will disable tracing altogether.
Changing `samplingRate` to 0 will disable tracing altogether.
See the [References](#references) section for more details on how to configure tracing on local environment and Kubernetes environment.
Dapr supports pluggable exporters, defined by configuration files (in self hosted mode) or a Kubernetes custom resource object (in Kubernetes mode). For example, the following manifest defines a Zipkin exporter:
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: zipkin
namespace: default
spec:
type: exporters.zipkin
version: v1
metadata:
- name: enabled
value: "true"
- name: exporterAddress
value: "http://zipkin.default.svc.cluster.local:9411/api/v2/spans"
```
## References
- [How-To: Setup Application Insights for distributed tracing with OpenTelemetry Collector]({{< ref open-telemetry-collector.md >}})

9
daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md
View File

@ -68,8 +68,13 @@ spec:
## Step 2: Subscribe to topics
Dapr allows two methods by which you can subscribe to topics:
- **Declaratively**, where subscriptions are are defined in an external file.
- **Programatically**, where subscriptions are defined in user code
- **Programmatically**, where subscriptions are defined in user code
{{% alert title="Note" color="primary" %}}
Both declarative and programmatic approaches support the same features. The declarative approach removes the Dapr dependancy from the user code and allows for the use of an existing application to subscribe to topics. The programmatic approach implements the subscription in user code.
{{% /alert %}}
### Declarative subscriptions
@ -308,7 +313,7 @@ Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '{"status":
{{< /tabs >}}
Dapr automatically wraps the user payload in a Cloud Events v1.0 compliant envelope.
Dapr automatically wraps the user payload in a Cloud Events v1.0 compliant envelope, using `Content-Type` header value for `datacontenttype` attribute.
## Step 4: ACK-ing a message

60
daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md
View File

@ -8,43 +8,30 @@ description: "Overview of the Dapr Pub/Sub building block"
## Introduction
The [publish/subscribe pattern](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) allows your microservices to communicate with each other purely by sending messages. In this system, the **producer** of a message sends it to a **topic**, with no knowledge of what service will receive the message. A messages can even be sent if there's no consumer for it.
The [publish/subscribe pattern](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) allows microservices to communicate with each other using messages. The **producer** sends messages to a **topic** without knowledge of what application will receive them. Similarly, a **consumer** will subscribe to the topic and receive its messages without any knowledge of what application produced these messages. This pattern is especially useful when you need to decouple microservices from one another.
Similarly, a **consumer** will receive messages from a topic without knowledge of what producer sent it. This pattern is especially useful when you need to decouple microservices from one another.
Dapr provides a publish/subscribe API that provides at-least-once guarantees and integrates with various message brokers implementations. These implementations are pluggable, and developed outside of the Dapr runtime in [components-contrib](https://github.com/dapr/components-contrib/tree/master/pubsub).
The publish/subscribe API in Dapr provides an at-least-once guarantee and integrates with various message brokers and queuing systems. The specific implementation to your application is pluggable and configured externally at runtime. This approach removes the dependency from your application and, as a result, makes your application more portable. The complete list of available publish/subscribe implementations is available [here]({{< ref supported-pubsub >}}).
## Features
### Publish/Subscribe API
The API for Publish/Subscribe can be found in the [spec repo]({{< ref pubsub_api.md >}}).
The publish/subscribe API is located in the [API reference]({{< ref pubsub_api.md >}}).
### At-Least-Once guarantee
### Message Format
Dapr guarantees At-Least-Once semantics for message delivery.
That means that when an application publishes a message to a topic using the Publish/Subscribe API, it can assume the message is delivered at least once to any subscriber when the response status code from that endpoint is `200`, or returns no error if using the gRPC client.
To enable message routing and to provide additional context with each message Dapr uses the [CloudEvents 1.0 specification](https://github.com/cloudevents/spec/tree/v1.0) as its message format. Any message sent by an application to a topic using Dapr will automatically be "wrapped" in Cloud Events envelope, using `Content-Type` header value for `datacontenttype` attribute.
### Consumer groups and multiple instances
Dapr implements the following Cloud Events fields:
The burden of dealing with concepts like consumer groups and multiple instances inside consumer groups is all catered for by Dapr.
When multiple instances of the same application ID subscribe to a topic, Dapr will make sure to deliver the message to only one instance. If two different applications with different IDs subscribe to a topic, at least one instance in each application receives a copy of the same message.
### Cloud events
Dapr follows the [CloudEvents 1.0 Spec](https://github.com/cloudevents/spec/tree/v1.0) and wraps any payload sent to a topic inside a Cloud Events envelope.
The following fields from the Cloud Events spec are implemented with Dapr:
- `id`
- `source`
- `specversion`
- `type`
- `datacontenttype` (Optional)
> Starting with Dapr v0.9, Dapr no longer wraps published content into CloudEvent if the published payload itself is already in CloudEvent format.
* `id`
* `source`
* `specversion`
* `type`
* `datacontenttype` (Optional)
The following example shows an XML content in CloudEvent v1.0 serialized as JSON:
```json
{
"specversion" : "1.0",
@ -58,11 +45,30 @@ The following example shows an XML content in CloudEvent v1.0 serialized as JSON
}
```
> Starting with v0.9 release, Dapr no longer wraps published content into CloudEvent if the published payload is already in the CloudEvent format.
### Message Subscription
Dapr allows two methods by which you can subscribe to topics: **declarative**, where a subscription is defined in an external file, and **programmatic**, where a subscription is defined in the user code. For more information see Dapr's documentation on [subscribing to a topic](https://docs.dapr.io/developing-applications/building-blocks/pubsub/howto-publish-subscribe/#step-2-subscribe-to-topics).
### Message Delivery
In principle, Dapr considers message successfully delivered when the subscriber responds with a non-error response after processing the message. For more granular control, Dapr's publish/subscribe API also provides explicit statuses, defined in the response payload, which the subscriber can use to indicate the specific handling instructions to Dapr (e.g. `RETRY` or `DROP`). For more information message routing see [Dapr publish/subscribe API documentation]({{< ref "pubsub_api.md#provide-routes-for-dapr-to-deliver-topic-events" >}})
### At-Least-Once guarantee
Dapr guarantees at-least-once semantics for message delivery. That means that when an application publishes a message to a topic using the publish/subscribe API, Dapr ensures that this message will be delivered at least once to every subscriber.
### Consumer groups and multiple instances
The burden of dealing with concepts like consumer groups and multiple application instances using a single consumer group is all handled automatically by Dapr. When multiple instances of the same application (same IDs) subscribe to a topic, Dapr delivers each message to only one instance of that application. Similarly, if two different applications (different IDs) subscribe to the same topic, Dapr will deliver each message to only one instance of each application.
### Topic scoping
Limit which topics applications are able to publish/subscibe to in order to limit access to potentially sensitive data streams. Read [Pub/Sub scoping]({{< ref pubsub-scopes.md >}}) for more information.
By default, all topics backing the Dapr publish/subscribe component (e.g. Kafka, Redis, RabbitMQ) are available to every application configured with that component. To limit which application can publish or subscribe to topics, Dapr provides topic scoping. See [publish/subscribe topic scoping]({{< ref pubsub-scopes.md >}}) for more information.
## Next steps
- Read the How-To guide on [publishing and subscribing]({{< ref howto-publish-subscribe.md >}})
- Learn about [Pub/Sub scopes]({{< ref pubsub-scopes.md >}})
- Learn about [Pub/Sub scopes]({{< ref pubsub-scopes.md >}})
- Read the [API reference]({{< ref pubsub_api.md >}})

108
daprdocs/content/en/developing-applications/building-blocks/secrets/howto-secrets.md
View File

@ -6,42 +6,66 @@ weight: 2000
description: "Use the secret store building block to securely retrieve a secret"
---
It's common for applications to store sensitive information such as connection strings, keys and tokens that are used to authenticate with databases, services and external systems in secrets by using a dedicated secret store.
This article provides guidance on using Dapr's secrets API in your code to leverage the [secrets store building block]({{<ref secrets-overview>}}). The secrets API allows you to easily retrieve secrets in your application code from a configured secret store.
Usually this involves setting up a secret store such as Azure Key Vault, Hashicorp Vault and others and storing the application level secrets there. To access these secret stores, the application needs to import the secret store SDK, and use it to access the secrets.
## Set up a secret store
This usually involves writing a fair amount of boilerplate code that is not related to the actual business domain of the app, and this becomes an even greater challenge in multi-cloud scenarios: if an app needs to deploy to two different environments and use two different secret stores, the amount of boilerplate code gets doubled, and the effort increases.
Before retrieving secrets in your application's code, you must have a secret store component configured. For the purposes of this guide, as an example you will configure a local secret store which uses a local JSON file to store secrets.
In addition, not all secret stores have native SDKs for all programming languages.
>Note: The component used in this example is not secured and is not recommended for production deployments. You can find other alternatives [here]({{<ref supported-secret-stores >}}).
To make it easier for developers everywhere to consume application secrets, Dapr has a dedicated secrets building block API that allows developers to get secrets from a secret store.
Create a file named `secrets.json` with the following contents:
## Setting up a secret store component
The first step involves setting up a secret store, either in the cloud or in the hosting environment such as a cluster. This is done by using the relevant instructions from the cloud provider or secret store implementation.
The second step is to configure the secret store with Dapr.
To deploy in Kubernetes, save the file above to `aws_secret_manager.yaml` and then run:
```bash
kubectl apply -f aws_secret_manager.yaml
```json
{
"my-secret" : "I'm Batman"
}
```
To run locally, create a `components` dir containing the YAML file and provide the path to the `dapr run` command with the flag `--components-path`.
Create a directory for your components file named `components` and inside it create a file named `localSecretStore.yaml` with the following contents:
Watch this [video](https://www.youtube.com/watch?v=OtbYCBt9C34&feature=youtu.be&t=1818) for an example on how to use the secrets API. Or watch this [video](https://www.youtube.com/watch?v=8W-iBDNvCUM&feature=youtu.be&t=1765) for an example on how to component scopes with secret components and the secrets API.
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: my-secrets-store
namespace: default
spec:
type: secretstores.local.file
version: v1
metadata:
- name: secretsFile
value: <PATH TO SECRETS FILE>/secrets.json
- name: nestedSeparator
value: ":"
```
## Calling the secrets API
Make sure to replace `<PATH TO SECRETS FILE>` with the path to the JSON file you just created.
Now that the secret store is set up, you can call Dapr to get the secrets for a given key for a specific secret store.
To configure a different kind of secret store see the guidance on [how to configure a secret store]({{<ref secret-stores-overview>}}) and review [supported secret stores]({{<ref supported-secret-stores >}}) to see specific details required for different secret store solutions.
## Get a secret
For a full API reference, go [here](https://github.com/dapr/docs/blob/master/reference/api/secrets_api.md).
Now run the Dapr sidecar (with no application)
Here are a few examples in different programming languages:
```bash
dapr run --app-id my-app --port 3500 --components-path ./components
```
### Go
And now you can get the secret by calling the Dapr sidecar using the secrets API:
```bash
curl http://localhost:3500/v1.0/secrets/my-secrets-store/my-secret
```
For a full API reference, go [here]({{< ref secrets_api.md >}}).
## Calling the secrets API from your code
Once you have a secret store set up, you can call Dapr to get the secrets from your application code. Here are a few examples in different programming languages:
{{< tabs "Go" "Javascript" "Python" "Rust" "C#" >}}
{{% codetab %}}
```Go
import (
"fmt"
@ -49,7 +73,7 @@ import (
)
func main() {
url := "http://localhost:3500/v1.0/secrets/kubernetes/my-secret"
url := "http://localhost:3500/v1.0/secrets/my-secrets-store/my-secret"
res, err := http.Get(url)
if err != nil {
@ -61,13 +85,16 @@ func main() {
fmt.Println(string(body))
}
```
### Javascript
{{% /codetab %}}
{{% codetab %}}
```javascript
require('isomorphic-fetch');
const secretsUrl = `http://localhost:3500/v1.0/secrets`;
fetch(`${secretsUrl}/kubernetes/my-secret`)
fetch(`${secretsUrl}/my-secrets-store/my-secret`)
.then((response) => {
if (!response.ok) {
throw "Could not get secret";
@ -78,16 +105,21 @@ fetch(`${secretsUrl}/kubernetes/my-secret`)
});
```
### Python
{{% /codetab %}}
{{% codetab %}}
```python
import requests as req
resp = req.get("http://localhost:3500/v1.0/secrets/kubernetes/my-secret")
resp = req.get("http://localhost:3500/v1.0/secrets/my-secrets-store/my-secret")
print(resp.text)
```
### Rust
{{% /codetab %}}
{{% codetab %}}
```rust
#![deny(warnings)]
@ -95,7 +127,7 @@ use std::{thread};
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let res = reqwest::get("http://localhost:3500/v1.0/secrets/kubernetes/my-secret").await?;
let res = reqwest::get("http://localhost:3500/v1.0/secrets/my-secrets-store/my-secret").await?;
let body = res.text().await?;
println!("Secret:{}", body);
@ -105,13 +137,27 @@ async fn main() -> Result<(), reqwest::Error> {
}
```
### C#
{{% /codetab %}}
{{% codetab %}}
```csharp
var client = new HttpClient();
var response = await client.GetAsync("http://localhost:3500/v1.0/secrets/kubernetes/my-secret");
var response = await client.GetAsync("http://localhost:3500/v1.0/secrets/my-secrets-store/my-secret");
response.EnsureSuccessStatusCode();
string secret = await response.Content.ReadAsStringAsync();
Console.WriteLine(secret);
```
{{% /codetab %}}
{{< /tabs >}}
## Related links
- [Dapr secrets overview]({{<ref secrets-overview>}})
- [Secrets API reference]({{<ref secrets_api>}})
- [Configure a secret store]({{<ref secret-stores-overview>}})
- [Supported secrets]({{<ref secret-stores-overview>}})
- [Using secrets in components]({{<ref component-secrets>}})
- [Secret stores quickstart](https://github.com/dapr/quickstarts/tree/master/secretstore)

34
daprdocs/content/en/developing-applications/building-blocks/secrets/secrets-overview.md
View File

@ -6,25 +6,20 @@ weight: 1000
description: "Overview of Dapr secrets management building block"
---
Almost all non-trivial applications need to _securely_ store secret data like API keys, database passwords, and more. By nature, these secrets should not be checked into the version control system, but they also need to be accessible to code running in production. This is generally a hard problem, but it's critical to get it right. Otherwise, critical production systems can be compromised.
It's common for applications to store sensitive information such as connection strings, keys and tokens that are used to authenticate with databases, services and external systems in secrets by using a dedicated secret store.
Dapr's solution to this problem is the secrets API and secrets stores.
Usually this involves setting up a secret store such as Azure Key Vault, Hashicorp Vault and others and storing the application level secrets there. To access these secret stores, the application needs to import the secret store SDK, and use it to access the secrets. This may require a fair amount of boilerplate code that is not related to the actual business domain of the app, and so becomes an even greater challenge in multi-cloud scenarios where different vendor specific secret stores may be used.
Here's how it works:
To make it easier for developers everywhere to consume application secrets, Dapr has a dedicated secrets building block API that allows developers to get secrets from a secret store.
- Dapr is set up to use a **secret store** - a place to securely store secret data
- Application code uses the standard Dapr secrets API to retrieve secrets.
Using Dapr's secret store building block typically involves the following:
1. Setting up a component for a specific secret store solution.
1. Retrieving secrets using the Dapr secrets API in the application code.
1. Optionally, referencing secrets in Dapr component files.
Some examples for secret stores include `Kubernetes`, `Hashicorp Vault`, `Azure KeyVault`. See [secret stores]({{< ref supported-secret-stores >}}) for the list of supported stores.
See [Setup secret stores]({{< ref howto-secrets.md >}}) for a HowTo guide for setting up and using secret stores.
## Referencing secret stores in Dapr components
Instead of including credentials directly within a Dapr component file, you can place the credentials within a Dapr supported secret store and reference the secret within the Dapr component. This is preferred approach and is a recommended best practice especially in production environments.
For more information read [Referencing Secret Stores in Components]({{< ref component-secrets.md >}})
## Setting up a secret store
See [Setup secret stores]({{< ref howto-secrets.md >}}) for guidance on how to setup a secret store with Dapr.
## Using secrets in your application
@ -47,9 +42,16 @@ Notice that in all of the examples above the application code did not have to ch
See [Access Application Secrets using the Secrets API]({{< ref howto-secrets.md >}}) for a How To guide to use secrets in your application.
For detailed API information read [Secrets API]({{< ref secrets_api.md >}}).
## Referencing secret stores in Dapr components
When configuring Dapr components such as state stores it is often required to include credentials in components files. Instead of doing that, you can place the credentials within a Dapr supported secret store and reference the secret within the Dapr component. This is preferred approach and is a recommended best practice especially in production environments.
For more information read [referencing secret stores in components]({{< ref component-secrets.md >}})
## Limiting access to secrets
To provide more granular control on access to secrets, Dapr provides the ability to define scopes and restricting access permissions. Learn more about [using secret scoping]({{<ref secrets-scopes>}})

378
daprdocs/content/en/developing-applications/building-blocks/state-management/howto-get-save-state.md
View File

@ -14,17 +14,23 @@ 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 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.
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 +39,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:
Begin by launching a Dapr sidecar:
```bash
dapr --app-id myapp --port 3500 run
dapr run --app-id myapp --dapr-http-port 3500
```
{{% 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:
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"}, { "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
curl -X POST -H "Content-Type: application/json" -d '{ "key": "key1", "value": "value1"}' http://localhost:3500/v1.0/state/statestore
```
{{% 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")
])
```
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 +160,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 >}})

95
daprdocs/content/en/developing-applications/building-blocks/state-management/howto-share-state.md Normal file
View File

@ -0,0 +1,95 @@
---
type: docs
title: "How-To: Share state between applications"
linkTitle: "How-To: Share state between applications"
weight: 400
description: "Choose different strategies for sharing state between different applications"
---
## Introduction
Dapr offers developers different ways to share state between applications.
Different architectures might have different needs when it comes to sharing state. For example, in one scenario you may want to encapsulate all state within a given application and have Dapr manage the access for you. In a different scenario, you may need to have two applications working on the same state be able to get and save the same keys.
To enable state sharing, Dapr supports the following key prefixes strategies:
* **`appid`** - This is the default strategy. the `appid` prefix allows state to be managed only by the app with the specified `appid`. All state keys will be prefixed with the `appid`, and are scoped for the application.
* **`name`** - This setting uses the name of the state store component as the prefix. Multiple applications can share the same state for a given state store.
* **`none`** - This setting uses no prefixing. Multiple applications share state across different state stores.
## Specifying a state prefix strategy
To specify a prefix strategy, add a metadata key named `keyPrefix` on a state component:
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: statestore
namespace: production
spec:
type: state.redis
version: v1
metadata:
- name: keyPrefix
value: <key-prefix-strategy>
```
## Examples
The following examples will show you how state retrieval looks like with each of the supported prefix strategies:
### `appid` (default)
A Dapr application with app id `myApp` is saving state into a state store named `redis`:
```shell
curl -X POST http://localhost:3500/v1.0/state/redis \
-H "Content-Type: application/json"
-d '[
{
"key": "darth",
"value": "nihilus"
}
]'
```
The key will be saved as `myApp||darth`.
### `name`
A Dapr application with app id `myApp` is saving state into a state store named `redis`:
```shell
curl -X POST http://localhost:3500/v1.0/state/redis \
-H "Content-Type: application/json"
-d '[
{
"key": "darth",
"value": "nihilus"
}
]'
```
The key will be saved as `redis||darth`.
### `none`
A Dapr application with app id `myApp` is saving state into a state store named `redis`:
```shell
curl -X POST http://localhost:3500/v1.0/state/redis \
-H "Content-Type: application/json"
-d '[
{
"key": "darth",
"value": "nihilus"
}
]'
```
The key will be saved as `darth`.

2
daprdocs/content/en/developing-applications/building-blocks/state-management/query-state-store/_index.md
View File

@ -2,7 +2,7 @@
type: docs
title: "Work with backend state stores"
linkTitle: "Backend stores"
weight: 400
weight: 500
description: "Guides for working with specific backend states stores"
---

2
daprdocs/content/en/developing-applications/building-blocks/state-management/query-state-store/query-redis-store.md
View File

@ -6,7 +6,7 @@ weight: 2000
description: "Use Redis as a backend state store"
---
Dapr doesn't transform state values while saving and retrieving states. Dapr requires all state store implementations to abide by a certain key format scheme (see [Dapr state management spec]({{<ref state_api.md>}}). You can directly interact with the underlying store to manipulate the state data, such querying states, creating aggregated views and making backups.
Dapr doesn't transform state values while saving and retrieving states. Dapr requires all state store implementations to abide by a certain key format scheme (see [Dapr state management spec]({{<ref state_api.md>}}). You can directly interact with the underlying store to manipulate the state data, such as querying states, creating aggregated views and making backups.
>**NOTE:** The following examples uses Redis CLI against a Redis store using the default Dapr state store implementation.

63
daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md
View File

@ -8,6 +8,8 @@ description: "Overview of the state management building block"
## Introduction
<img src="/images/state-management-overview.png" width=900>
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.
<img src="/images/state-management-overview.png" width=900>
## 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 '<app-id>||<thermometer>||*||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 >}})

26
daprdocs/content/en/developing-applications/middleware/middleware-opa-policies.md
View File

@ -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/
- [Open Policy Agent](https://www.openpolicyagent.org)
- [HTTP API Example](https://www.openpolicyagent.org/docs/latest/http-api-authorization/)

34
daprdocs/content/en/developing-applications/middleware/middleware-rate-limit.md Normal file
View File

@ -0,0 +1,34 @@
---
type: docs
title: "How-To: Rate limiting"
linkTitle: "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">}}).
## Related links
- [Middleware concept]({{< ref middleware-concept.md >}})
- [Dapr configuration]({{< ref configuration-concept.md >}})

44
daprdocs/content/en/developing-applications/sdks/_index.md
View File

@ -1,22 +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
---
### .NET
See the [.NET SDK repository](https://github.com/dapr/dotnet-sdk)
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.
### Java
See the [Java SDK repository](https://github.com/dapr/java-sdk)
## SDK packages
### Go
See the [Go SDK repository](https://github.com/dapr/go-sdk)
- **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 >}})
- **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" >}})
### Python
See the [Python SDK repository](https://github.com/dapr/python-sdk)
## SDK languages
### Javascript
See the [Javascript SDK repository](https://github.com/dapr/js-sdk)
| Language | State | Client SDK | Service Extensions | Actor SDK |
|----------|:-----:|:----------:|:-----------:|:---------:|
| [.NET](https://github.com/dapr/dotnet-sdk) | In Development | ✔ | ASP.NET Core | ✔ |
| [Python]({{< ref python >}}) | In Development | ✔ | [gRPC]({{< ref python-grpc.md >}}) | [FastAPI]({{< ref python-fastapi.md >}})<br />[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 | ✔ | | |
| [Javascript]() | Backlog | ✔ | |
## Further reading
- [Serialization in the Dapr SDKs]({{< ref sdk-serialization.md >}})

5
daprdocs/content/en/developing-applications/sdks/serialization.md → daprdocs/content/en/developing-applications/sdks/sdk-serialization.md
View File

@ -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.

21
daprdocs/content/en/getting-started/_index.md
View File

@ -3,7 +3,24 @@ type: docs
title: "Getting started with Dapr"
linkTitle: "Getting started"
weight: 20
description: "Get up and running with Dapr"
type: docs
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]({{<ref concepts>}}).
{{% /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, 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
1. Initialize Dapr
1. Use the Dapr API
1. Configure a component
1. Explore Dapr quickstarts
<a class="btn btn-primary" href="{{< ref install-dapr-cli.md >}}" role="button">First step: Install the Dapr CLI >></a>

228
daprdocs/content/en/getting-started/configure-redis.md
View File

@ -1,228 +0,0 @@
---
type: docs
title: "How-To: Setup a customized Redis store"
linkTitle: "(optional) Configure Redis"
weight: 40
description: "Configure Redis for Dapr state management or Pub/Sub"
---
Dapr can use Redis in two ways:
1. As state store component (state.redis) for persistence and restoration
2. As pub/sub component (pubsub.redis) for async style message delivery
## Create a Redis store
Dapr can use any Redis instance - containerized, running on your local dev machine, or a managed cloud service. If you already have a Redis store, move on to the [configuration](#configure-dapr-components) section.
{{< tabs "Self-Hosted" "Kubernetes (Helm)" "Azure Redis Cache" "AWS Redis" "GCP Memorystore" >}}
{{% codetab %}}
Redis is automatically installed in self-hosted environments by the Dapr CLI as part of the initialization process.
{{% /codetab %}}
{{% codetab %}}
You can use [Helm](https://helm.sh/) to quickly create a Redis instance in our Kubernetes cluster. This approach requires [Installing Helm v3](https://github.com/helm/helm#install).
1. Install Redis into your cluster:
```bash
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update
helm install redis bitnami/redis
```
Note that you will need a Redis version greater than 5, which is what Dapr's pub/sub functionality requires. If you're intending on using Redis as just a state store (and not for pub/sub) a lower version can be used.
2. Run `kubectl get pods` to see the Redis containers now running in your cluster:
```bash
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
redis-master-0 1/1 Running 0 69s
redis-slave-0 1/1 Running 0 69s
redis-slave-1 1/1 Running 0 22s
```
3. Add `redis-master.default.svc.cluster.local:6379` as the `redisHost` in your [redis.yaml](#configure-dapr-components) file. For example:
```yaml
metadata:
- name: redisHost
value: redis-master.default.svc.cluster.local:6379
```
4. Securely reference the redis passoword in your [redis.yaml](#configure-dapr-components) file. For example:
```yaml
- name: redisPassword
secretKeyRef:
name: redis
key: redis-password
```
5. (Alternative) It is **not recommended**, but you can use a hard code a password instead of using secretKeyRef. First you'll get the Redis password, which is slightly different depending on the OS you're using:
- **Windows**: In Powershell run:
```powershell
PS C:\> $base64pwd=kubectl get secret --namespace default redis -o jsonpath="{.data.redis-password}"
PS C:\> $redispassword=[System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($base64pwd))
PS C:\> $base64pwd=""
PS C:\> $redispassword
```
- **Linux/MacOS**: Run:
```bash
kubectl get secret --namespace default redis -o jsonpath="{.data.redis-password}" | base64 --decode
```
Add this password as the `redisPassword` value in your [redis.yaml](#configure-dapr-components) file. For example:
```yaml
metadata:
- name: redisPassword
value: lhDOkwTlp0
```
{{% /codetab %}}
{{% codetab %}}
This method requires having an Azure Subscription.
1. Open the [Azure Portal](https://ms.portal.azure.com/#create/Microsoft.Cache) to start the Azure Redis Cache creation flow. Log in if necessary.
1. Fill out the necessary information
1. Click "Create" to kickoff deployment of your Redis instance.
1. Once your instance is created, you'll need to grab your access key. Navigate to "Access Keys" under "Settings" and copy your key.
1. You'll need the hostname of your Redis instance, which you can retrieve from the "Overview" in Azure. It should look like `xxxxxx.redis.cache.windows.net:6380`.
1. Finally, you'll need to add our key and our host to a `redis.yaml` file that Dapr can apply to our cluster. If you're running a sample, you'll add the host and key to the provided `redis.yaml`. If you're creating a project from the ground up, you'll create a `redis.yaml` file as specified in [Configuration](#configure-dapr-components).
As the connection to Azure is encrypted, make sure to add the following block to the `metadata` section of your `redis.yaml` file.
```yaml
metadata:
- name: enableTLS
value: "true"
```
> **NOTE:** Dapr pub/sub uses [Redis streams](https://redis.io/topics/streams-intro) that was introduced by Redis 5.0, which isn't currently available on Azure Cache for Redis. Consequently, you can use Azure Cache for Redis only for state persistence.
{{% /codetab %}}
{{% codetab %}}
Visit [AWS Redis](https://aws.amazon.com/redis/).
{{% /codetab %}}
{{% codetab %}}
Visit [GCP Cloud MemoryStore](https://cloud.google.com/memorystore/).
{{% /codetab %}}
{{< /tabs >}}
## Configure Dapr components
Dapr can use Redis as a [`statestore` component]({{< ref setup-state-store >}}) for state persistence (`state.redis`) or as a [`pubsub` component]({{< ref setup-pubsub >}}) (`pubsub.redis`). The following yaml files demonstrates how to define each component using either a secretKey reference (which is preferred) or a plain text password.
### Create component files
#### State store component with secret reference
Create a file called redis-state.yaml, and paste the following:
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: statestore
namespace: default
spec:
type: state.redis
version: v1
metadata:
- name: redisHost
value: <HOST e.g. redis-master.default.svc.cluster.local:6379>
- name: redisPassword
secretKeyRef:
name: redis
key: redis-password
```
#### Pub/sub component with secret reference
Create a file called redis-pubsub.yaml, and paste the following:
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: pubsub
namespace: default
spec:
type: pubsub.redis
version: v1
metadata:
- name: redisHost
value: <HOST e.g. redis-master.default.svc.cluster.local:6379>
- name: redisPassword
secretKeyRef:
name: redis
key: redis-password
```
#### State store component with hard coded password (not recommended)
For development purposes only, create a file called redis-state.yaml, and paste the following:
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: statestore
namespace: default
spec:
type: state.redis
version: v1
metadata:
- name: redisHost
value: <HOST>
- name: redisPassword
value: <PASSWORD>
```
#### Pub/Sub component with hard coded password (not recommended)
For development purposes only, create a file called redis-pubsub.yaml, and paste the following:
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: pubsub
namespace: default
spec:
type: pubsub.redis
version: v1
metadata:
- name: redisHost
value: <HOST>
- name: redisPassword
value: <PASSWORD>
```
### Apply the configuration
{{< tabs "Self-Hosted" "Kubernetes">}}
{{% codetab %}}
By default the Dapr CLI creates a local Redis instance when you run `dapr init`. However, if you want to configure a different Redis instance, create a `components` dir containing the YAML file and provide the path to the `dapr run` command with the flag `--components-path`.
If you initialized Dapr using `dapr init --slim`, the Dapr CLI did not create a Redis instance or a default configuration file for it. Follow [the instructions above](#creat-a-redis-store) to create a Redis store. Create the `redis.yaml` following the configuration [instructions](#configure-dapr-components) in a `components` dir and provide the path to the `dapr run` command with the flag `--components-path`.
{{% /codetab %}}
{{% codetab %}}
Run `kubectl apply -f <FILENAME>` for both state and pubsub files:
```bash
kubectl apply -f redis-state.yaml
kubectl apply -f redis-pubsub.yaml
```
{{% /codetab %}}
{{< /tabs >}}

231
daprdocs/content/en/getting-started/configure-state-pubsub.md Normal file
View File

@ -0,0 +1,231 @@
---
type: docs
title: "How-To: Configure state store and pub/sub message broker"
linkTitle: "(optional) Configure state & pub/sub"
weight: 80
description: "Configure state store and pub/sub message broker components for Dapr"
aliases:
- /getting-started/configure-redis/
---
In order to get up and running with the state and pub/sub building blocks two components are needed:
1. A state store component for persistence and restoration
2. As pub/sub message broker component for async-style message delivery
A full list of supported components can be found here:
- [Supported state stores]({{< ref supported-state-stores >}})
- [Supported pub/sub message brokers]({{< ref supported-pubsub >}})
The rest of this page describes how to get up and running with Redis.
{{% alert title="Self-hosted mode" color="warning" %}}
When initialized in self-hosted mode, Dapr automatically runs a Redis container and sets up the required component yaml files. You can skip this page and go to [next steps](#next-steps)
{{% /alert %}}
## Create a Redis store
Dapr can use any Redis instance - either containerized on your local dev machine or a managed cloud service. If you already have a Redis store, move on to the [configuration](#configure-dapr-components) section.
{{< tabs "Self-Hosted" "Kubernetes" "Azure" "AWS" "GCP" >}}
{{% codetab %}}
Redis is automatically installed in self-hosted environments by the Dapr CLI as part of the initialization process. You are all set and can skip to the [next steps](next steps)
{{% /codetab %}}
{{% codetab %}}
You can use [Helm](https://helm.sh/) to quickly create a Redis instance in our Kubernetes cluster. This approach requires [Installing Helm v3](https://github.com/helm/helm#install).
1. Install Redis into your cluster:
```bash
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update
helm install redis bitnami/redis
```
Note that you will need a Redis version greater than 5, which is what Dapr's pub/sub functionality requires. If you're intending on using Redis as just a state store (and not for pub/sub) a lower version can be used.
2. Run `kubectl get pods` to see the Redis containers now running in your cluster:
```bash
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
redis-master-0 1/1 Running 0 69s
redis-slave-0 1/1 Running 0 69s
redis-slave-1 1/1 Running 0 22s
```
Note that the hostname is `redis-master.default.svc.cluster.local:6379`, and a Kubernetes secret, `redis`, is created automatically.
{{% /codetab %}}
{{% codetab %}}
This method requires having an Azure Subscription.
1. Open the [Azure Portal](https://ms.portal.azure.com/#create/Microsoft.Cache) to start the Azure Redis Cache creation flow. Log in if necessary.
1. Fill out the necessary information
- Dapr pub/sub uses [Redis streams](https://redis.io/topics/streams-intro) that was introduced by Redis 5.0. If you would like to use Azure Redis Cache for pub/sub make sure to set the version to (PREVIEW) 6.
1. Click "Create" to kickoff deployment of your Redis instance.
1. You'll need the hostname of your Redis instance, which you can retrieve from the "Overview" in Azure. It should look like `xxxxxx.redis.cache.windows.net:6380`. Note this for later.
1. Once your instance is created, you'll need to grab your access key. Navigate to "Access Keys" under "Settings" and create a Kubernetes secret to store your Redis password:
```bash
kubectl create secret generic redis --from-literal=redis-password=*********
```
{{% /codetab %}}
{{% codetab %}}
1. Visit [AWS Redis](https://aws.amazon.com/redis/) to deploy a Redis instance
1. Note the Redis hostname in the AWS portal for use later
1. Create a Kubernetes secret to store your Redis password:
```bash
kubectl create secret generic redis --from-literal=redis-password=*********
```
{{% /codetab %}}
{{% codetab %}}
1. Visit [GCP Cloud MemoryStore](https://cloud.google.com/memorystore/) to deploy a MemoryStore instance
1. Note the Redis hostname in the GCP portal for use later
1. Create a Kubernetes secret to store your Redis password:
```bash
kubectl create secret generic redis --from-literal=redis-password=*********
```
{{% /codetab %}}
{{< /tabs >}}
## Configure Dapr components
Dapr uses components to define what resources to use for building block functionality. These steps go through how to connect the resources you created above to Dapr for state and pub/sub.
In self-hosted mode, component files are automatically created under:
- **Windows**: `%USERPROFILE%\.dapr\components\`
- **Linux/MacOS**: `$HOME/.dapr/components`
For Kubernetes, files can be created in any directory, as they are applied with `kubectl`.
### Create State store component
Create a file named `redis-state.yaml`, and paste the following:
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: statestore
namespace: default
spec:
type: state.redis
version: v1
metadata:
- name: redisHost
value: <REPLACE WITH HOSTNAME FROM ABOVE - for Redis on Kubernetes it is redis-master.default.svc.cluster.local:6379>
- name: redisPassword
secretKeyRef:
name: redis
key: redis-password
```
This example uses the the kubernetes secret that was created when setting up a cluster with the above instructions.
{{% alert title="Other stores" color="primary" %}}
If using a state store other than Redis, refer to the [supported state stores]({{< ref supported-state-stores >}}) for information on what options to set.
{{% /alert %}}
### Create Pub/sub message broker component
Create a file called redis-pubsub.yaml, and paste the following:
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: pubsub
namespace: default
spec:
type: pubsub.redis
version: v1
metadata:
- name: redisHost
value: <REPLACE WITH HOSTNAME FROM ABOVE - for Redis on Kubernetes it is redis-master.default.svc.cluster.local:6379>
- name: redisPassword
secretKeyRef:
name: redis
key: redis-password
```
This example uses the the kubernetes secret that was created when setting up a cluster with the above instructions.
{{% alert title="Other stores" color="primary" %}}
If using a pub/sub message broker other than Redis, refer to the [supported pub/sub message brokers]({{< ref supported-pubsub >}}) for information on what options to set.
{{% /alert %}}
### Hard coded passwords (not recommended)
For development purposes only you can skip creating kubernetes secrets and place passwords directly into the Dapr component file:
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: statestore
namespace: default
spec:
type: state.redis
version: v1
metadata:
- name: redisHost
value: <HOST>
- name: redisPassword
value: <PASSWORD>
```
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: pubsub
namespace: default
spec:
type: pubsub.redis
version: v1
metadata:
- name: redisHost
value: <HOST>
- name: redisPassword
value: <PASSWORD>
```
## Apply the configuration
{{< tabs "Self-Hosted" "Kubernetes">}}
{{% codetab %}}
By default the Dapr CLI creates a local Redis instance when you run `dapr init`. However, if you want to configure a different Redis instance you can either:
- Update the existing component files or create new ones in the default components directory
- **Linux/MacOS:** `$HOME/.dapr/components`
- **Windows:** `%USERPROFILE%\.dapr\components`
- Create a new `components` directory in your app folder containing the YAML files and provide the path to the `dapr run` command with the flag `--components-path`
{{% alert title="Self-hosted slim mode" color="primary" %}}
If you initialized Dapr in [slim mode]({{< ref self-hosted-no-docker.md >}}) (without Docker) you need to manually create the default directory, or always specify a components directory using `--components-path`.
{{% /alert %}}
{{% /codetab %}}
{{% codetab %}}
Run `kubectl apply -f <FILENAME>` for both state and pubsub files:
```bash
kubectl apply -f redis-state.yaml
kubectl apply -f redis-pubsub.yaml
```
{{% /codetab %}}
{{< /tabs >}}
## Next steps
- [Try out a Dapr quickstart]({{< ref quickstarts.md >}})

104
daprdocs/content/en/getting-started/get-started-api.md Normal file
View File

@ -0,0 +1,104 @@
---
type: docs
title: "Use the Dapr API"
linkTitle: "Use the Dapr API"
weight: 30
---
After running the `dapr init` command in the [previous step]({{<ref install-dapr-selfhost.md>}}), 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).
## 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.
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
```
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:
{{< 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 >}}
## 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:
```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 >}}
## 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:
```bash
docker exec -it dapr_redis redis-cli
```
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 *
```
```
1) "myapp||name"
```
View the state value by running:
```bash
hgetall "myapp||name"
```
```
1) "data"
2) "\"Bruce Wayne\""
3) "version"
4) "1"
```
Exit the redis-cli with:
```bash
exit
```
<a class="btn btn-primary" href="{{< ref get-started-component.md >}}" role="button">Next step: Define a component >></a>

93
daprdocs/content/en/getting-started/get-started-component.md Normal file
View File

@ -0,0 +1,93 @@
---
type: docs
title: "Define a component"
linkTitle: "Define a component"
weight: 40
---
In the [previous step]({{<ref get-started-api.d>}}) 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 definition file
- 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 (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`:
```json
{
"my-secret" : "I'm Batman"
}
```
## Step 2: Create a secret store Dapr component
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
kind: Component
metadata:
name: my-secret-store
namespace: default
spec:
type: secretstores.local.file
version: v1
metadata:
- name: secretsFile
value: <PATH TO SECRETS FILE>/secrets.json
- name: nestedSeparator
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 --components-path ./my-components
```
## 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 %}}
{{< /tabs >}}
You should see output with the secret you stored in the JSON file.
```
"I'm Batman"
```
<a class="btn btn-primary" href="{{< ref quickstarts.md >}}" role="button">Next step: Explore Dapr quickstarts >></a>

78
daprdocs/content/en/getting-started/install-dapr-cli.md
View File

@ -1,38 +1,40 @@
---
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 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.
Begin by downloading and installing the Dapr CLI for v1.0.0-rc.2. This will be used to initialize your environment on your desired platform.
You can learn more about the CLI and available commands in the [CLI reference docs]( {{< ref cli >}}).
### Step 1: Run the installation script
Begin by downloading and installing the latest version of the Dapr CLI:
{{% alert title="Note" color="warning" %}}
This command will download and install Dapr v0.11. To install v1.0-rc.1, the release candidate for the [upcoming v1.0 release](https://blog.dapr.io/posts/2020/10/20/the-path-to-v.1.0-production-ready-dapr/), please visit the [v1.0-rc.1 docs](https://v1-rc1.docs.dapr.io/getting-started/install-dapr-cli).
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/).
{{% /alert %}}
{{< tabs Linux Windows MacOS Binaries>}}
{{% codetab %}}
This command will install the latest linux Dapr CLI to `/usr/local/bin`:
This command installs the latest linux Dapr CLI to `/usr/local/bin`:
```bash
wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash
```
{{% /codetab %}}
{{% codetab %}}
This command will install the latest windows Dapr cli to `%USERPROFILE%\.dapr\` and add this directory to User PATH environment variable:
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 `%USERPROFILE%\.dapr\` into the address bar. You should see folders for bin, componenets and a config file.
{{% /codetab %}}
{{% codetab %}}
This command will install the latest darwin Dapr CLI to `/usr/local/bin`:
This command installs the latest darwin Dapr CLI to `/usr/local/bin`:
```bash
curl -fsSL https://raw.githubusercontent.com/dapr/cli/master/install/install.sh | /bin/bash
```
@ -50,13 +52,59 @@ 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 >}}
Learn more about the CLI and available commands in the [CLI docs]( {{< ref cli >}}).
## Next steps
- [Init Dapr locally]({{< ref install-dapr.md >}})
- [Init Dapr on Kubernetes]({{< ref install-dapr-kubernetes.md >}})
- [Try a Dapr Quickstart]({{< ref quickstarts.md >}})
### Step 2: Verify the installation
You can verify the CLI is installed by restarting your terminal/command prompt and running the following:
```bash
dapr
```
The output should look like this:
```md
____/ /___ _____ _____
/ __ / __ '/ __ \/ ___/
/ /_/ / /_/ / /_/ / /
\__,_/\__,_/ .___/_/
/_/
===============================
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.
```
<a class="btn btn-primary" href="{{< ref install-dapr-selfhost.md >}}" role="button">Next step: Initialize Dapr >></a>

79
daprdocs/content/en/getting-started/install-dapr-kubernetes.md
View File

@ -1,21 +1,27 @@
---
type: docs
title: "How-To: Install Dapr into a Kubernetes cluster"
linkTitle: "Init Dapr on Kubernetes"
weight: 30
linkTitle: "(optional) Init Dapr on Kubernetes"
weight: 70
description: "Install Dapr in a Kubernetes cluster"
---
When setting up Kubernetes you can use either the Dapr CLI or Helm.
The following pods will be installed:
As part of the Dapr initialization the following pods are installed:
- dapr-operator: Manages component updates and Kubernetes services endpoints for Dapr (state stores, pub/subs, etc.)
- dapr-sidecar-injector: Injects Dapr into annotated deployment pods
- dapr-placement: Used for actors only. Creates mapping tables that map actor instances to pods
- dapr-sentry: Manages mTLS between services and acts as a certificate authority
- **dapr-operator:** Manages component updates and Kubernetes services endpoints for Dapr (state stores, pub/subs, etc.)
- **dapr-sidecar-injector:** Injects Dapr into annotated deployment pods
- **dapr-placement:** Used for actors only. Creates mapping tables that map actor instances to pods
- **dapr-sentry:** Manages mTLS between services and acts as a certificate authority
## Setup cluster
## Prerequisites
- Install [Dapr CLI]({{< ref install-dapr-cli.md >}})
- Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
- Kubernetes cluster (see below if needed)
### Create cluster
You can install Dapr on any Kubernetes cluster. Here are some helpful links:
@ -24,8 +30,8 @@ You can install Dapr on any Kubernetes cluster. Here are some helpful links:
- [Setup Google Cloud Kubernetes Engine](https://cloud.google.com/kubernetes-engine/docs/quickstart)
- [Setup Amazon Elastic Kubernetes Service](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html)
{{% alert title="Note" color="primary" %}}
Both the Dapr CLI and the Dapr Helm chart automatically deploy with affinity for nodes with the label `kubernetes.io/os=linux`. You can deploy Dapr to Windows nodes, but most users should not need to. For more information see [Deploying to a hybrid Linux/Windows Kubernetes cluster]({{<ref kubernetes-hybrid-clusters>}}).
{{% alert title="Hybrid clusters" color="primary" %}}
Both the Dapr CLI and the Dapr Helm chart automatically deploy with affinity for nodes with the label `kubernetes.io/os=linux`. You can deploy Dapr to Windows nodes if your application requires it. For more information see [Deploying to a hybrid Linux/Windows Kubernetes cluster]({{<ref kubernetes-hybrid-clusters>}}).
{{% /alert %}}
@ -33,17 +39,25 @@ Both the Dapr CLI and the Dapr Helm chart automatically deploy with affinity for
You can install Dapr to a Kubernetes cluster using the [Dapr CLI]({{< ref install-dapr-cli.md >}}).
{{% alert title="Note" color="warning" %}}
This command will download and install Dapr v0.11. To install v1.0-rc.1, the release candidate for the [upcoming v1.0 release](https://blog.dapr.io/posts/2020/10/20/the-path-to-v.1.0-production-ready-dapr/), please visit the [v1.0-rc.1 docs](https://v1-rc1.docs.dapr.io/getting-started/install-dapr-kubernetes).
{{% alert title="Release candidate" 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-kubernetes/). 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 %}}
### Install Dapr
The `-k` flag will initialize Dapr on the Kuberentes cluster in your current context.
The `-k` flag initializes Dapr on the Kubernetes cluster in your current context.
{{% alert title="Target cluster" color="primary" %}}
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 <CONTEXT>`.
{{% /alert %}}
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
@ -51,34 +65,35 @@ $ dapr init -k
✅ Success! Dapr has been installed to namespace dapr-system. To verify, run "dapr status -k" in your terminal. To get started, go here: https://aka.ms/dapr-getting-started
```
### Install to a custom namespace:
### Install in custom namespace
The default namespace when initializeing Dapr is `dapr-system`. You can override this with the `-n` flag.
The default namespace when initializing Dapr is `dapr-system`. You can override this with the `-n` flag.
```
```bash
dapr init -k -n mynamespace
```
### Install in highly available mode:
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
```
### Disable mTLS:
### Disable mTLS
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
### Uninstall Dapr on Kubernetes with CLI
```bash
$ dapr uninstall --kubernetes
dapr uninstall --kubernetes
```
## Install with Helm (advanced)
@ -90,10 +105,10 @@ You can install Dapr to Kubernetes cluster using a Helm 3 chart.
The latest Dapr helm chart no longer supports Helm v2. Please migrate from helm v2 to helm v3 by following [this guide](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/).
{{% /alert %}}
### Install Dapr on Kubernetes
### Add and install Dapr helm chart
1. Make sure Helm 3 is installed on your machine
2. Add Helm repo
1. Make sure [Helm 3](https://github.com/helm/helm/releases) is installed on your machine
2. Add Helm repo and update
```bash
helm repo add dapr https://dapr.github.io/helm-charts/
@ -114,11 +129,13 @@ The latest Dapr helm chart no longer supports Helm v2. Please migrate from helm
### Verify installation
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:
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
@ -133,8 +150,10 @@ dapr-sentry-9435776c7f-8f7yd 1/1 Running 0 40s
helm uninstall dapr -n dapr-system
```
> **Note:** See [this page](https://github.com/dapr/dapr/blob/master/charts/dapr/README.md) for details on Dapr helm charts.
### More information
## Sidecar annotations
See [this page](https://github.com/dapr/dapr/blob/master/charts/dapr/README.md) for details on Dapr helm charts.
To see all the supported annotations for the Dapr sidecar on Kubernetes, visit [this]({{<ref "kubernetes-annotations.md">}}) how to guide.
## Next steps
- [Configure state store & pubsub message broker]({{< ref configure-state-pubsub.md >}})

117
daprdocs/content/en/getting-started/install-dapr-selfhost.md Normal file
View File

@ -0,0 +1,117 @@
---
type: docs
title: "Initialize Dapr in your local environment"
linkTitle: "Init Dapr locally"
weight: 20
aliases:
- /getting-started/install-dapr/
---
Now that you have the [Dapr CLI installed]({{<ref install-dapr-cli.md>}}), 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.
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]({{<ref self-hosted-no-docker.md>}})) but next steps in this guide assume the recommended development environment.
{{% /alert %}}
### 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 will need to use `sudo` below.
{{% /codetab %}}
{{% codetab %}}
Make sure that you run Command Prompt as administrator (right click, run as administrator)
{{% /codetab %}}
{{< /tabs >}}
### Step 2: Run the init CLI command
Install the latest Dapr runtime binaries:
```bash
dapr init
```
### Step 3: Verify Dapr version
```bash
dapr --version
```
Output should look like this:
```
CLI version: 0.11
Runtime version: 0.11
```
### 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
```
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
```
### Step 5: Verify components directory has been initialized
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\`
{{< tabs "Linux/MacOS" "Windows">}}
{{% codetab %}}
Run:
```bash
ls $HOME/.dapr
```
You should see:
```
bin components config.yaml
```
{{% /codetab %}}
{{% codetab %}}
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:
<img src="/images/install-dapr-selfhost-windows.png" width=500>
{{% /codetab %}}
{{< /tabs >}}
<a class="btn btn-primary" href="{{< ref get-started-api.md >}}" role="button">Next step: Use the Dapr API >></a>

82
daprdocs/content/en/getting-started/install-dapr.md
View File

@ -1,82 +0,0 @@
---
type: docs
title: "How-To: Install Dapr into your local environment"
linkTitle: "Init Dapr locally"
weight: 20
description: "Install Dapr in your local environment for testing and self-hosting"
---
## 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.
By default Dapr will install with a developer environment using Docker containers to get you started easily. This getting started guide assumes Docker is installed to ensure the best experience. However, Dapr does not depend on Docker to run. Read [this page]({{< ref self-hosted-no-docker.md >}}) for instructions on installing Dapr locally without Docker using slim init.
### Initialize Dapr using the CLI
This step will install the latest Dapr Docker containers and setup a developer environment to help you get started easily with Dapr.
1. Ensure you are in an elevated terminal:
- **Linux/MacOS:** if you run your docker cmds with sudo or the install path is `/usr/local/bin`(default install path), you need to use `sudo`
- **Windows:** make sure that you run the cmd terminal in administrator mode
2. Run `dapr init`
```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
```
3. Verify installation
From a command prompt run the `docker ps` command and check that the `daprio/dapr`, `openzipkin/zipkin`, and `redis` container images are running:
```bash
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
67bc611a118c daprio/dapr "./placement" About a minute ago Up About a minute 0.0.0.0:6050->50005/tcp dapr_placement
855f87d10249 openzipkin/zipkin "/busybox/sh run.sh" About a minute ago Up About a minute 9410/tcp, 0.0.0.0:9411->9411/tcp dapr_zipkin
71cccdce0e8f redis "docker-entrypoint.s…" About a minute ago Up About a minute 0.0.0.0:6379->6379/tcp dapr_redis
```
4. Visit our [hello world quickstart](https://github.com/dapr/quickstarts/tree/master/hello-world) or dive into the [Dapr building blocks]({{< ref building-blocks >}})
## (optional) Install a specific runtime version
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
# Install v0.11.0 runtime
$ dapr init --runtime-version 0.11.0
# Check the versions of cli and runtime
$ dapr --version
cli version: v0.11.0
runtime version: v0.11.2
```
## Uninstall Dapr in self-hosted mode
This command will remove the placement Dapr container:
```bash
$ 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
```
{{% /alert %}}
> 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.
## Configure Redis
Unlike Dapr self-hosted, redis is not pre-installed out of the box on Kubernetes. To install Redis as a state store or as a pub/sub message bus in your Kubernetes cluster see [How-To: Setup Redis]({{< ref configure-redis.md >}})

27
daprdocs/content/en/getting-started/quickstarts.md
View File

@ -2,21 +2,26 @@
type: docs
title: "Try out Dapr quickstarts to learn core concepts"
linkTitle: "Dapr Quickstarts"
weight: 50
description: "Configure Redis for Dapr state management or Pub/Sub"
weight: 60
description: "Tutorials with code samples that are aimed to get you started quickly with Dapr"
---
The [Dapr Quickstarts](https://github.com/dapr/quickstarts) are a collection of tutorials with code samples that are aimed to get you started quickly with Dapr, each highlighting a different Dapr capability.
The [Dapr Quickstarts](https://github.com/dapr/quickstarts/tree/release-0.11) are a collection of tutorials with code samples that are aimed to get you started quickly with Dapr, each highlighting a different Dapr capability.
- A good place to start is the hello-world quickstart, it demonstrates how to run Dapr in standalone mode locally on your machine and demonstrates state management and service invocation in a simple application.
- Next, if you are familiar with Kubernetes and want to see how to run the same application in a Kubernetes environment, look for the hello-kubernetes quickstart. Other quickstarts such as pub-sub, bindings and the distributed-calculator quickstart explore different Dapr capabilities include instructions for running both locally and on Kubernetes and can be completed in any order. A full list of the quickstarts can be found below.
- At anytime, you can explore the Dapr documentation or SDK specific samples and come back to try additional quickstarts.
- When you're done, consider exploring the [Dapr samples repository](https://github.com/dapr/samples) for additional code samples contributed by the community that show more advanced or specific usages of Dapr.
## Quickstarts
| Quickstart | Description |
|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Hello-world](https://github.com/dapr/quickstarts/tree/master/hello-world) | Demonstrates how to run Dapr locally. Highlights service invocation and state management. |
| [Hello-kubernetes](https://github.com/dapr/quickstarts/tree/master/hello-kubernetes) | Demonstrates how to run Dapr in Kubernetes. Highlights service invocation and state management. |
| [Distributed-calculator](https://github.com/dapr/quickstarts/tree/master/distributed-calculator) | Demonstrates a distributed calculator application that uses Dapr services to power a React web app. Highlights polyglot (multi-language) programming, service invocation and state management. |
| [Pub-sub](https://github.com/dapr/quickstarts/tree/master/pub-sub) | Demonstrates how to use Dapr to enable pub-sub applications. Uses Redis as a pub-sub component. |
| [Bindings](https://github.com/dapr/quickstarts/tree/master/bindings) | Demonstrates how to use Dapr to create input and output bindings to other components. Uses bindings to Kafka. |
| [Middleware](https://github.com/dapr/quickstarts/tree/master/middleware) | Demonstrates use of Dapr middleware to enable OAuth 2.0 authorization. |
| [Observability](https://github.com/dapr/quickstarts/tree/master/observability) | Demonstrates Dapr tracing capabilities. Uses Zipkin as a tracing component. |
| [Secret Store](https://github.com/dapr/quickstarts/tree/master/secretstore) | Demonstrates the use of Dapr Secrets API to access secret stores. |
| [Hello World](https://github.com/dapr/quickstarts/tree/release-0.11/hello-world) | Demonstrates how to run Dapr locally. Highlights service invocation and state management. |
| [Hello Kubernetes](https://github.com/dapr/quickstarts/tree/release-0.11/hello-kubernetes) | Demonstrates how to run Dapr in Kubernetes. Highlights service invocation and state management. |
| [Distributed Calculator](https://github.com/dapr/quickstarts/tree/release-0.11/distributed-calculator) | Demonstrates a distributed calculator application that uses Dapr services to power a React web app. Highlights polyglot (multi-language) programming, service invocation and state management. |
| [Pub/Sub](https://github.com/dapr/quickstarts/tree/release-0.11/pub-sub) | Demonstrates how to use Dapr to enable pub-sub applications. Uses Redis as a pub-sub component. |
| [Bindings](https://github.com/dapr/quickstarts/tree/release-0.11/bindings) | Demonstrates how to use Dapr to create input and output bindings to other components. Uses bindings to Kafka. |
| [Middleware](https://github.com/dapr/quickstarts/tree/release-0.11/middleware) | Demonstrates use of Dapr middleware to enable OAuth 2.0 authorization. |
| [Observability](https://github.com/dapr/quickstarts/tree/release-0.11/observability) | Demonstrates Dapr tracing capabilities. Uses Zipkin as a tracing component. |
| [Secret Store](https://github.com/dapr/quickstarts/tree/release-0.11/secretstore) | Demonstrates the use of Dapr Secrets API to access secret stores. |

52
daprdocs/content/en/operations/components/component-schema.md Normal file
View File

@ -0,0 +1,52 @@
---
type: docs
title: "Component schema"
linkTitle: "Component schema"
weight: 100
description: "The basic schema for a Dapr component"
---
Dapr defines and registers components using a [CustomResourceDefinition](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/). All components are defined as a CRD and can be applied to any hosting environment where Dapr is running, not just Kubernetes.
## Format
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: [COMPONENT-NAME]
namespace: [COMPONENT-NAMESPACE]
spec:
type: [COMPONENT-TYPE]
version: v1
initTimeout: [TIMEOUT-DURATION]
ignoreErrors: [BOOLEAN]
metadata:
- name: [METADATA-NAME]
value: [METADATA-VALUE]
```
## Fields
| Field | Required | Details | Example |
|--------------------|:--------:|---------|---------|
| apiVersion | Y | The version of the Dapr (and Kubernetes if applicable) API you are calling | `dapr.io/v1alpha1`
| kind | Y | The type of CRD. For components is must always be `Component` | `Component`
| **metadata** | - | **Information about the component registration** |
| metadata.name | Y | The name of the component | `prod-statestore`
| metadata.namespace | N | The namespace for the component for hosting environments with namespaces | `myapp-namespace`
| **spec** | - | **Detailed information on the component resource**
| spec.type | Y | The type of the component | `state.redis`
| spec.version | Y | The version of the component | `v1`
| spec.initTimeout | N | The timeout duration for the initialization of the component. Default is 30s | `5m`, `1h`, `20s`
| spec.ignoreErrors | N | Tells the Dapr sidecar to continue initialization if the component fails to load. Default is false | `false`
| **spec.metadata** | - | **A key/value pair of component specific configuration. See your component definition for fields**|
## Further reading
- [Components concept]({{< ref components-concept.md >}})
- [Reference secrets in component definitions]({{< ref component-secrets.md >}})
- [Supported state stores]({{< ref supported-state-stores >}})
- [Supported pub/sub brokers]({{< ref supported-pubsub >}})
- [Supported secret stores]({{< ref supported-secret-stores >}})
- [Supported bindings]({{< ref supported-bindings >}})
- [Set component scopes]({{< ref component-scopes.md >}})

6
daprdocs/content/en/operations/components/component-scopes.md
View File

@ -2,7 +2,7 @@
type: docs
title: "How-To: Scope components to one or more applications"
linkTitle: "How-To: Set component scopes"
weight: 100
weight: 200
description: "Limit component access to particular Dapr instances"
---
@ -31,7 +31,7 @@ spec:
In this example, the Redis component is only accessible to Dapr instances running inside the `production` namespace.
### Example of component namsespacing in self-hosted mode
### Example of component namespacing in self-hosted mode
In self hosted mode, a developer can specify the namespace to a Dapr instance by setting the `NAMESPACE` environment variable.
If the `NAMESPACE` environment variable is set, Dapr will not load any component that does not specify the same namespace in its metadata.
@ -83,4 +83,4 @@ scopes:
## Example
<iframe width="560" height="315" src="https://www.youtube.com/embed/8W-iBDNvCUM?start=1763" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
<iframe width="560" height="315" src="https://www.youtube.com/embed/8W-iBDNvCUM?start=1763" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

174
daprdocs/content/en/operations/components/component-secrets.md
View File

@ -1,8 +1,8 @@
---
type: docs
title: "How-To: Reference secret stores in components"
title: "How-To: Reference secrets in components"
linkTitle: "How-To: Reference secrets"
weight: 200
weight: 300
description: "How to securly reference secrets from a component definition"
---
@ -18,9 +18,93 @@ When running in Kubernetes, if the `auth.secretStore` is empty, the Kubernetes s
Go to [this]({{< ref "howto-secrets.md" >}}) link to see all the secret stores supported by Dapr, along with information on how to configure and use them.
## Non default namespaces
## Referencing secrets
If your Dapr enabled apps are using components that fetch secrets from non-default namespaces, apply the following resources to the namespace:
While you have the option to use plain text secrets, this is not recommended for production:
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: statestore
namespace: default
spec:
type: state.redis
version: v1
metadata:
- name: redisHost
value: localhost:6379
- name: redisPassword
value: MyPassword
```
Instead create the secret in your secret store and reference it in the component definition:
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: statestore
namespace: default
spec:
type: state.redis
version: v1
metadata:
- name: redisHost
value: localhost:6379
- name: redisPassword
secretKeyRef:
name: redis-secret
key: redis-password
auth:
secretStore: <SECRET_STORE_NAME>
```
`SECRET_STORE_NAME` is the name of the configured [secret store component]({{< ref supported-secret-stores >}}). When running in Kubernetes and using a Kubernetes secret store, the field `auth.SecretStore` defaults to `kubernetes` and can be left empty.
The above component definition tells Dapr to extract a secret named `redis-secret` from the defined secret store and assign the value of the `redis-password` key in the secret to the `redisPassword` field in the Component.
## Example
### Referencing a Kubernetes secret
The following example shows you how to create a Kubernetes secret to hold the connection string for an Event Hubs binding.
1. First, create the Kubernetes secret:
```bash
kubectl create secret generic eventhubs-secret --from-literal=connectionString=*********
```
2. Next, reference the secret in your binding:
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: eventhubs
namespace: default
spec:
type: bindings.azure.eventhubs
version: v1
metadata:
- name: connectionString
secretKeyRef:
name: eventhubs-secret
key: connectionString
```
3. Finally, apply the component to the Kubernetes cluster:
```bash
kubectl apply -f ./eventhubs.yaml
```
## Kubernetes permissions
### Default namespace
When running in Kubernetes, Dapr, during installtion, defines default Role and RoleBinding for secrets access from Kubernetes secret store in the `default` namespace. For Dapr enabled apps that fetch secrets from `default` namespace, a secret can be defined and referenced in components as shown in the example above.
### Non-default namespaces
If your Dapr enabled apps are using components that fetch secrets from non-default namespaces, apply the following resources to that namespace:
```yaml
---
@ -49,82 +133,8 @@ roleRef:
apiGroup: rbac.authorization.k8s.io
```
## Examples
These resources grant Dapr permissions to get secrets from the Kubernetes secret store for the namespace defined in the Role and RoleBinding.
Using plain text:
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: statestore
namespace: default
spec:
type: state.redis
version: v1
metadata:
- name: redisHost
value: localhost:6379
- name: redisPassword
value: MyPassword
```
Using a Kubernetes secret:
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: statestore
namespace: default
spec:
type: state.redis
version: v1
metadata:
- name: redisHost
value: localhost:6379
- name: redisPassword
secretKeyRef:
name: redis-secret
key: redis-password
auth:
secretStore: kubernetes
```
The above example tells Dapr to use the `kubernetes` secret store, extract a secret named `redis-secret` and assign the value of the `redis-password` key in the secret to the `redisPassword` field in the Component.
### Creating a secret and referencing it in a Component
The following example shows you how to create a Kubernetes secret to hold the connection string for an Event Hubs binding.
First, create the Kubernetes secret:
```bash
kubectl create secret generic eventhubs-secret --from-literal=connectionString=*********
```
Next, reference the secret in your binding:
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: eventhubs
namespace: default
spec:
type: bindings.azure.eventhubs
version: v1
metadata:
- name: connectionString
secretKeyRef:
name: eventhubs-secret
key: connectionString
```
Finally, apply the component to the Kubernetes cluster:
```bash
kubectl apply -f ./eventhubs.yaml
```
All done!
{{% alert title="Note" color="warning" %}}
In production scenario to limit Dapr's access to certain secret resources alone, you can use the `resourceNames` field. See this [link](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#referring-to-resources) for further explanation.
{{% /alert %}}

9
daprdocs/content/en/operations/components/setup-bindings/supported-bindings/_index.md
View File

@ -20,14 +20,14 @@ Every binding has its own unique set of properties. Click the name link to see t
| [Kubernetes Events]({{< ref "kubernetes-binding.md" >}}) | ✅ | | Experimental |
| [MQTT]({{< ref mqtt.md >}}) | ✅ | ✅ | Experimental |
| [PostgreSql]({{< ref postgres.md >}}) | | ✅ | Experimental |
| [Postmark]({{< ref postmark.md >}}) | | ✅ | Experimental |
| [RabbitMQ]({{< ref rabbitmq.md >}}) | ✅ | ✅ | Experimental |
| [Redis]({{< ref redis.md >}}) | | ✅ | Experimental |
| [Twilio]({{< ref twilio.md >}}) | | ✅ | Experimental |
| [Twitter]({{< ref twitter.md >}}) | ✅ | ✅ | Experimental |
| [SendGrid]({{< ref sendgrid.md >}}) | | ✅ | Experimental |
### Amazon Web Service (AWS)
### Amazon Web Services (AWS)
| Name | Input<br>Binding | Output<br>Binding | Status |
|------|:----------------:|:-----------------:|--------|
@ -37,7 +37,6 @@ Every binding has its own unique set of properties. Click the name link to see t
| [AWS SQS]({{< ref sqs.md >}}) | ✅ | ✅ | Experimental |
| [AWS Kinesis]({{< ref kinesis.md >}}) | ✅ | ✅ | Experimental |
### Google Cloud Platform (GCP)
| Name | Input<br>Binding | Output<br>Binding | Status |
@ -50,9 +49,9 @@ Every binding has its own unique set of properties. Click the name link to see t
| Name | Input<br>Binding | Output<br>Binding | Status |
|------|:----------------:|:-----------------:|--------|
| [Azure Blob Storage]({{< ref blobstorage.md >}}) | | ✅ | Experimental |
| [Azure EventHubs]({{< ref eventhubs.md >}}) | ✅ | ✅ | Experimental |
| [Azure CosmosDB]({{< ref cosmosdb.md >}}) | | ✅ | Experimental |
| [Azure Event Grid]({{< ref eventgrid.md >}}) | ✅ | ✅ | Experimental |
| [Azure Event Hubs]({{< ref eventhubs.md >}}) | ✅ | ✅ | Experimental |
| [Azure Service Bus Queues]({{< ref servicebusqueues.md >}}) | ✅ | ✅ | Experimental |
| [Azure SignalR]({{< ref signalr.md >}}) | | ✅ | Experimental |
| [Azure Storage Queues]({{< ref storagequeues.md >}}) | ✅ | ✅ | Experimental |
| [Azure Event Grid]({{< ref eventgrid.md >}}) | ✅ | ✅ | Experimental |

1
daprdocs/content/en/operations/components/setup-bindings/supported-bindings/apns.md
View File

@ -1,4 +1,3 @@
---
type: docs
title: "Apple Push Notification Service binding spec"

2
daprdocs/content/en/operations/components/setup-bindings/supported-bindings/blobstorage.md
View File

@ -38,7 +38,7 @@ The above example uses secrets as plain strings. It is recommended to use a secr
### Create Blob
To perform a get blob operation, invoke the Azure Blob Storage binding with a `POST` method and the following JSON body:
To perform a create blob operation, invoke the Azure Blob Storage binding with a `POST` method and the following JSON body:
```json
{

4
daprdocs/content/en/operations/components/setup-bindings/supported-bindings/kubernetes-binding.md
View File

@ -63,7 +63,7 @@ Three different event types are available:
- Delete : Only the `oldVal` field is populated, `newVal` field is an empty `v1.Event`, `event` is `delete`
- Update : Both the `oldVal` and `newVal` fields are populated, `event` is `update`
## Required permisiions
## Required permissions
For consuming `events` from Kubernetes, permissions need to be assigned to a User/Group/ServiceAccount using [RBAC Auth] mechanism of Kubernetes.
@ -105,4 +105,4 @@ roleRef:
- [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 >}})
- [Bindings API reference]({{< ref bindings_api.md >}})

69
daprdocs/content/en/operations/components/setup-bindings/supported-bindings/postmark.md Normal file
View File

@ -0,0 +1,69 @@
---
type: docs
title: "Postmark binding spec"
linkTitle: "Postmark"
description: "Detailed documentation on the Postmark binding component"
---
## Setup Dapr component
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: postmark
namespace: default
spec:
type: bindings.postmark
metadata:
- name: accountToken
value: "YOUR_ACCOUNT_TOKEN" # required, this is your Postmark account token
- name: serverToken
value: "YOUR_SERVER_TOKEN" # required, this is your Postmark server token
- name: emailFrom
value: "testapp@dapr.io" # optional
- name: emailTo
value: "dave@dapr.io" # optional
- name: subject
value: "Hello!" # optional
```
- `accountToken` is your Postmark account token, this should be considered a secret value. Required.
- `serverToken` is your Postmark server token, this should be considered a secret value. Required.
- `emailFrom` If set this specifies the 'from' email address of the email message. Optional field, see below.
- `emailTo` If set this specifies the 'to' email address of the email message. Optional field, see below.
- `emailCc` If set this specifies the 'cc' email address of the email message. Optional field, see below.
- `emailBcc` If set this specifies the 'bcc' email address of the email message. Optional field, see below.
- `subject` If set this specifies the subject of the email message. Optional field, see below.
You can specify any of the optional metadata properties on the output binding request too (e.g. `emailFrom`, `emailTo`, `subject`, etc.)
Combined, the optional metadata properties in the component configuration and the request payload should at least contain the `emailFrom`, `emailTo` and `subject` fields, as these are required to send an email with success.
Example request payload
```json
{
"operation": "create",
"metadata": {
"emailTo": "changeme@example.net",
"subject": "An email from Dapr Postmark binding"
},
"data": "<h1>Testing Dapr Bindings</h1>This is a test.<br>Bye!"
}
```
{{% alert title="Warning" color="warning" %}}
The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described [here]({{< ref component-secrets.md >}}).
{{% /alert %}}
## Output Binding Supported Operations
- `create`
## Related links
- [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 >}})

4
daprdocs/content/en/operations/components/setup-bindings/supported-bindings/servicebusqueues.md
View File

@ -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 >}})
- [Bindings API reference]({{< ref bindings_api.md >}})

6
daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-nats-streaming.md
View File

@ -63,6 +63,8 @@ spec:
# blow are subscription configuration.
- name: subscriptionType
value: <REPLACE-WITH-SUBSCRIPTION-TYPE> # Required. Allowed values: topic, queue.
- name: deliverNew
value: true
# - name: ackWaitTime
# value: "" # Optional. See: https://docs.nats.io/developing-with-nats-streaming/acks#acknowledgements
# - name: maxInFlight
@ -74,9 +76,7 @@ spec:
# value: 1
# - name: startWithLastReceived
# value: false
- name: deliverAll
value: true
# - name: deliverNew
# - name: deliverAll
# value: false
# - name: startAtTimeDelta
# value: ""

48
daprdocs/content/en/operations/components/setup-secret-store/secret-stores-overview.md
View File

@ -7,11 +7,11 @@ weight: 10000
type: docs
---
Dapr integrates with secret stores to provide apps and other components with secure store and access to secrets such as access keys and passwords.. Each secret store component has a name and this name is used when accessing a secret.
Dapr integrates with secret stores to provide apps and other components with secure store and access to secrets such as access keys and passwords. Each secret store component has a name and this name is used when accessing a secret.
Secret stores are extensible and can be found in the [components-contrib repo](https://github.com/dapr/components-contrib).
As with other building block components, secret store components are extensible and can be found in the [components-contrib repo](https://github.com/dapr/components-contrib).
A secret store in Dapr is described using a `Component` file:
A secret store in Dapr is described using a `Component` file with the following fields:
```yaml
apiVersion: dapr.io/v1alpha1
@ -32,7 +32,47 @@ spec:
The type of secret store is determined by the `type` field, and things like connection strings and other metadata are put in the `.metadata` section.
Visit [this guide]({{< ref "howto-secrets.md#setting-up-a-secret-store-component" >}}) for instructions on configuring a secret store component.
Different [supported secret stores]({{< ref supported-secret-stores >}}) will have different specific fields that would need to be configured. For example, when configuring a secret store which uses AWS Secrets Manager the file would look like this:
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: awssecretmanager
namespace: default
spec:
type: secretstores.aws.secretmanager
version: v1
metadata:
- name: region
value: "[aws_region]"
- name: accessKey
value: "[aws_access_key]"
- name: secretKey
value: "[aws_secret_key]"
- name: sessionToken
value: "[aws_session_token]"
```
Once you have created the component's YAML file, follow these instructions to apply it based on your hosting environment:
{{< tabs "Self-Hosted" "Kubernetes" >}}
{{% codetab %}}
To run locally, create a `components` dir containing the YAML file and provide the path to the `dapr run` command with the flag `--components-path`.
{{% /codetab %}}
{{% codetab %}}
To deploy in Kubernetes, assuming your component file is named `secret-store.yaml`, run:
```bash
kubectl apply -f secret-store.yaml
```
{{% /codetab %}}
{{< /tabs >}}
## Related links

8
daprdocs/content/en/operations/components/setup-secret-store/supported-secret-stores/azure-keyvault-managed-identity.md
View File

@ -100,16 +100,16 @@ description: How to configure Azure Key Vault and Kubernetes to use Azure Manage
name: [you managed identity name]
spec:
type: 0
ResourceID: [you managed identity id]
ClientID: [you managed identity Client ID]
resourceID: [you managed identity id]
clientID: [you managed identity Client ID]
---
apiVersion: "aadpodidentity.k8s.io/v1"
kind: AzureIdentityBinding
metadata:
name: [you managed identity name]-identity-binding
spec:
AzureIdentity: [you managed identity name]
Selector: [you managed identity selector]
azureIdentity: [you managed identity name]
selector: [you managed identity selector]
```
10. Deploy the azure-identity-config.yaml:

2
daprdocs/content/en/operations/components/setup-state-store/supported-state-stores/setup-sqlserver.md
View File

@ -14,7 +14,7 @@ description: Detailed information on the SQL Server state store component
In order to setup SQL Server as a state store, you will need the following properties:
- **Connection String**: the SQL Server connection string. For example: server=localhost;user id=sa;password=your-password;port=1433;database=mydatabase;
- **Schema**: The database schema do use (default=dbo). Will be created if not exists
- **Schema**: The database schema to use (default=dbo). Will be created if not exists
- **Table Name**: The database table name. Will be created if not exists
- **Indexed Properties**: Optional properties from json data which will be indexed and persisted as individual column

4
daprdocs/content/en/operations/configuration/control-concurrency.md
View File

@ -9,7 +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 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

100
daprdocs/content/en/operations/configuration/invoke-allowlist.md
View File

@ -14,7 +14,7 @@ An access control policy is specified in configuration and be applied to Dapr si
**TrustDomain** - A "trust domain" is a logical group to manage trust relationships. Every application is assigned a trust domain which can be specified in the access control list policy spec. If no policy spec is defined or an empty trust domain is specified, then a default value "public" is used. This trust domain is used to generate the identity of the application in the TLS cert.
**App Identity** - Dapr generates a [SPIFFE](https://spiffe.io/) id for all applications which is attached in the TLS cert. The SPIFFE id is of the format: `**spiffe://\<trustdomain>/ns/\<namespace\>/\<appid\>**`. For matching policies, the trust domain, namespace and app ID values of the calling app are extracted from the SPIFFE id in the TLS cert of the calling app. These values are matched against the trust domain, namespace and app ID values specified in the policy spec. If all three of these match, then more specific policies are further matched.
**App Identity** - Dapr requests the sentry service to generate a [SPIFFE](https://spiffe.io/) id for all applications and this id is attached in the TLS cert. The SPIFFE id is of the format: `**spiffe://\<trustdomain>/ns/\<namespace\>/\<appid\>**`. For matching policies, the trust domain, namespace and app ID values of the calling app are extracted from the SPIFFE id in the TLS cert of the calling app. These values are matched against the trust domain, namespace and app ID values specified in the policy spec. If all three of these match, then more specific policies are further matched.
## Configuration properties
@ -189,10 +189,11 @@ spec:
namespace: "ns2"
```
## Hello world example
This scenario shows how to apply access control to the [hello world](https://github.com/dapr/quickstarts/blob/master/hello-world/README.md) or [hello kubernetes](https://github.com/dapr/quickstarts/blob/master/hello-world/README.md) samples where a python app invokes a node.js app. You can create and apply these configuration files `nodeappconfig.yaml` and `pythonappconfig.yaml` as described in the [configuration]({{< ref "configuration-concept.md" >}}) article.
## Hello world examples
These examples show how to apply access control to the [hello world](https://github.com/dapr/quickstarts#quickstarts) quickstart samples where a python app invokes a node.js app.
Access control lists rely on the Dapr [Sentry service]({{< ref "security-concept.md" >}}) to generate the TLS certificates with a SPIFFE id for authentication, which means the Sentry service either has to be running locally or deployed to your hosting enviroment such as a Kubernetes cluster.
The nodeappconfig example below shows how to deny access to the `neworder` method from the `pythonapp`, where the python app is in the `myDomain` trust domain and `default` namespace. The nodeapp is in the `public` trust domain.
The nodeappconfig example below shows how to **deny** access to the `neworder` method from the `pythonapp`, where the python app is in the `myDomain` trust domain and `default` namespace. The nodeapp is in the `public` trust domain.
**nodeappconfig.yaml**
@ -233,7 +234,96 @@ spec:
trustDomain: "myDomain"
```
For example, this is how the pythonapp is deployed to Kubernetes in the default namespace with this configuration file.
### Self-hosted mode
This example uses the [hello world](https://github.com/dapr/quickstarts/tree/master/hello-world/README.md) quickstart.
The following steps run the Sentry service locally with mTLS enabled, set up necessary environment variables to access certificates, and then launch both the node app and python app each referencing the Sentry service to apply the ACLs.
1. Follow these steps to run the [Sentry service in self-hosted mode]({{< ref "mtls.md" >}}) with mTLS enabled
2. In a command prompt, set these environment variables:
{{< tabs "Linux/MacOS" Windows >}}
{{% codetab %}}
```bash
export DAPR_TRUST_ANCHORS=`cat $HOME/.dapr/certs/ca.crt`
export DAPR_CERT_CHAIN=`cat $HOME/.dapr/certs/issuer.crt`
export DAPR_CERT_KEY=`cat $HOME/.dapr/certs/issuer.key`
export NAMESPACE=default
```
{{% /codetab %}}
{{% codetab %}}
```powershell
$env:DAPR_TRUST_ANCHORS=$(Get-Content $env:USERPROFILE\.dapr\certs\ca.crt)
$env:DAPR_CERT_CHAIN=$(Get-Content $env:USERPROFILE\.dapr\certs\issuer.crt)
$env:DAPR_CERT_KEY=$(Get-Content $env:USERPROFILE\.dapr\certs\issuer.key)
$env:NAMESPACE="default"
```
{{% /codetab %}}
{{< /tabs >}}
3. Run daprd to launch a Dapr sidecar for the node.js app with mTLS enabled, referencing the local Sentry service:
```bash
daprd --app-id nodeapp --dapr-grpc-port 50002 -dapr-http-port 3501 --log-level debug --app-port 3000 --enable-mtls --sentry-address localhost:50001 --config nodeappconfig.yaml
```
4. Run the node app in a separate command prompt:
```bash
node app.js
```
5. In another command prompt, set these environment variables:
{{< tabs "Linux/MacOS" Windows >}}
{{% codetab %}}
```bash
export DAPR_TRUST_ANCHORS=`cat $HOME/.dapr/certs/ca.crt`
export DAPR_CERT_CHAIN=`cat $HOME/.dapr/certs/issuer.crt`
export DAPR_CERT_KEY=`cat $HOME/.dapr/certs/issuer.key`
export NAMESPACE=default
```
{{% /codetab %}}
{{% codetab %}}
```powershell
$env:DAPR_TRUST_ANCHORS=$(Get-Content $env:USERPROFILE\.dapr\certs\ca.crt)
$env:DAPR_CERT_CHAIN=$(Get-Content $env:USERPROFILE\.dapr\certs\issuer.crt)
$env:DAPR_CERT_KEY=$(Get-Content $env:USERPROFILE\.dapr\certs\issuer.key)
$env:NAMESPACE="default"
```
{{% /codetab %}}
{{< /tabs >}}
6. Run daprd to launch a Dapr sidecar for the python app with mTLS enabled, referencing the local Sentry service:
```bash
daprd --app-id pythonapp --dapr-grpc-port 50003 --metrics-port 9092 --log-level debug --enable-mtls --sentry-address localhost:50001 --config pythonappconfig.yaml
```
7. Run the python app in a separate command prompt:
```bash
python app.py
```
8. You should see the calls to the node app fail in the python app command prompt based due to the **deny** operation action in the nodeappconfig file. Change this action to **allow** and re-run the apps and you should then see this call succeed.
### Kubernetes mode
This example uses the [hello kubernetes](https://github.com/dapr/quickstarts/tree/master/hello-kubernetes/README.md) quickstart.
You can create and apply the above configuration files `nodeappconfig.yaml` and `pythonappconfig.yaml` as described in the [configuration]({{< ref "configuration-concept.md" >}}) to the Kubernetes deployments.
For example, below is how the pythonapp is deployed to Kubernetes in the default namespace with this pythonappconfig configuration file.
Do the same for the nodeapp deployment and then look at the logs for the pythonapp to see the calls fail due to the **deny** operation action set in the nodeappconfig file. Change this action to **allow** and re-deploy the apps and you should then see this call succeed.
```yaml
apiVersion: apps/v1

2
daprdocs/content/en/operations/hosting/kubernetes/cluster/_index.md
View File

@ -2,7 +2,7 @@
type: docs
title: "Kubernetes cluster setup"
linkTitle: "How-to: Setup clusters"
weight: 50000
weight: 60000
description: >
How to setup dapr on a kubernetes cluster.
---

1
daprdocs/content/en/operations/hosting/kubernetes/kubernetes-annotations.md
View File

@ -17,6 +17,7 @@ The following table shows all the supported pod Spec annotations supported by Da
| `dapr.io/config` | Tells Dapr which Configuration CRD to use
| `dapr.io/log-as-json` | Setting this parameter to `true` outputs logs in JSON format. Default is `false`
| `dapr.io/enable-profiling` | Setting this paramater to `true` starts the Dapr profiling server on port `7777`. Default is `false`
| `dapr.io/api-token-secret` | Tells Dapr which Kubernetes secret to use for token based API authentication. By default this is not set.
| `dapr.io/app-protocol` | Tells Dapr which protocol your application is using. Valid options are `http` and `grpc`. Default is `http`
| `dapr.io/app-max-concurrency` | Limit the concurrency of your application. A valid value is any number larger than `0`
| `dapr.io/app-ssl` | Tells Dapr to invoke the app over an insecure SSL connection. Applies to both HTTP and gRPC. Default is `false`.

2
daprdocs/content/en/operations/hosting/kubernetes/kubernetes-hybrid-clusters.md
View File

@ -34,7 +34,7 @@ akswin000001 Ready agent 6d v1.17.9 10.240.0.
## Installing the Dapr Control Plane
If you are installing using the Dapr CLI or via a helm chart, simply follow the normal deployment procedures:
[Installing Dapr on a Kubernetes cluster]({{< ref "install-dapr.md#installing-Dapr-on-a-kubernetes-cluster" >}})
[Installing Dapr on a Kubernetes cluster]({{< ref "install-dapr-selfhost.md#installing-Dapr-on-a-kubernetes-cluster" >}})
Affinity will be automatically set for kubernetes.io/os=linux. This will be sufficient for most users, as Kubernetes requires at least one Linux node pool.

20
daprdocs/content/en/operations/hosting/kubernetes/kubernetes-production.md
View File

@ -54,7 +54,7 @@ The CPU and memory limits above account for the fact that Dapr is intended to do
## Deploying Dapr with Helm
When deploying to a production cluster, it's recommended to use Helm. The Dapr CLI installation into a Kubernetes cluster is for a development and test only setup.
You can find information [here]({{< ref "install-dapr.md#using-helm-advanced" >}}) on how to deploy Dapr using Helm.
You can find information [here]({{< ref "install-dapr-selfhost.md#using-helm-advanced" >}}) on how to deploy Dapr using Helm.
When deploying Dapr in a production-ready configuration, it's recommended to deploy with a highly available configuration of the control plane:
@ -76,10 +76,7 @@ Dapr supports zero downtime upgrades. The upgrade path includes the following st
### Upgrading the CLI
To upgrade the Dapr CLI, [download a release version](https://github.com/dapr/cli/releases) of the CLI that matches the Dapr runtime version.
For example, if upgrading to Dapr 1.0.0-rc.x, download a CLI version of 1.0.0-rc.x.
After you downloaded the binary, it's recommended you put the CLI binary in your path.
To upgrade the Dapr CLI, [download the latest version](https://github.com/dapr/cli/releases) of the CLI. After you downloaded the binary, it's recommended you put the CLI binary in your path.
### Updating the control plane
@ -141,12 +138,19 @@ NAME CHART VERSION APP VERSION DESCRIPTION
dapr/dapr 1.0.0-rc.1 1.0.0-rc.1 A Helm chart for Dapr on Kubernetes
```
The APP VERSION column tells us which Dapr runtime version is installed by the chart.
The APP VERSION column tells us which Dapr runtime version is installed by the chart. Now, use the following command to upgrade Dapr to your desired runtime version providing a path to the certificate files you saved before:
Use the following command to upgrade Dapr to your desired runtime version providing a path to the certificate files you saved:
> Remove `--set global.ha.enabled=true` if current Dapr installation has not been deployed in HA mode.
```bash
helm upgrade dapr dapr/dapr --version <Dapr chart version> --namespace dapr-system --reset-values --set-file dapr_sentry.tls.root.certPEM=ca.crt --set-file dapr_sentry.tls.issuer.certPEM=issuer.crt --set-file dapr_sentry.tls.issuer.keyPEM=issuer.key
helm upgrade dapr dapr/dapr \
--version <Dapr chart version> \
--namespace dapr-system \
--reset-values \
--set-file dapr_sentry.tls.root.certPEM=certs/ca.crt \
--set-file dapr_sentry.tls.issuer.certPEM=certs/issuer.crt \
--set-file dapr_sentry.tls.issuer.keyPEM=certs/issuer.key \
--set global.ha.enabled=true
```
Kubernetes now performs a rolling update. Wait until all the new pods appear as running:

149
daprdocs/content/en/operations/hosting/kubernetes/kubernetes-upgrade.md Normal file
View File

@ -0,0 +1,149 @@
---
type: docs
title: "Steps to upgrade Dapr on a Kubernetes cluster"
linkTitle: "Upgrade Dapr"
weight: 50000
description: "Follow these steps to upgrade Dapr on Kubernetes and ensure a smooth upgrade."
---
## Prerequisites
- Latest [Dapr CLI]({{< ref install-dapr-cli.md >}})
- [Helm 3](https://github.com/helm/helm/releases)
## Upgrade existing cluster running 0.11.x
1. Run these two commands to prevent `helm upgrade` from uninstalling `0.11.x` placement service:
```bash
kubectl annotate deployment dapr-placement helm.sh/resource-policy=keep -n dapr-system
```
```bash
kubectl annotate svc dapr-placement helm.sh/resource-policy=keep -n dapr-system
```
1. Export certificates:
```bash
dapr mtls export -o ./certs
```
1. Upgrade Dapr to 1.0.0-rc.2:
```bash
helm repo update
```
```bash
helm upgrade dapr dapr/dapr --version 1.0.0-rc.2 --namespace dapr-system --reset-values --set-file dapr_sentry.tls.root.certPEM=./certs/ca.crt --set-file dapr_sentry.tls.issuer.certPEM=./certs/issuer.crt --set-file dapr_sentry.tls.issuer.keyPEM=./certs/issuer.key --set global.ha.enabled=true --wait
```
1. Upgrade CRDs:
```bash
kubectl replace -f https://raw.githubusercontent.com/dapr/dapr/21636a9237f2dcecd9c80f329e99b512e8377739/charts/dapr/crds/configuration.yaml
```
```bash
kubectl replace -f https://raw.githubusercontent.com/dapr/dapr/21636a9237f2dcecd9c80f329e99b512e8377739/charts/dapr/crds/components.yaml
```
1. Ensure 0.11.x dapr-placement service is still running and wait until all pods are running:
```bash
kubectl get pods -n dapr-system -w
NAME READY STATUS RESTARTS AGE
dapr-dashboard-69f5c5c867-mqhg4 1/1 Running 0 42s
dapr-operator-5cdd6b7f9c-9sl7g 1/1 Running 0 41s
dapr-operator-5cdd6b7f9c-jkzjs 1/1 Running 0 29s
dapr-operator-5cdd6b7f9c-qzp8n 1/1 Running 0 34s
dapr-placement-5dcb574777-nlq4t 1/1 Running 0 76s <---- 0.11.x placement
dapr-placement-server-0 1/1 Running 0 41s
dapr-placement-server-1 1/1 Running 0 41s
dapr-placement-server-2 1/1 Running 0 41s
dapr-sentry-84565c747b-7bh8h 1/1 Running 0 35s
dapr-sentry-84565c747b-fdlls 1/1 Running 0 41s
dapr-sentry-84565c747b-ldnsf 1/1 Running 0 29s
dapr-sidecar-injector-68f868668f-6xnbt 1/1 Running 0 41s
dapr-sidecar-injector-68f868668f-j7jcq 1/1 Running 0 29s
dapr-sidecar-injector-68f868668f-ltxq4 1/1 Running 0 36s
```
1. Restart your application deployments to update the Dapr runtime.
```bash
kubectl rollout restart deploy/<DEPLOYMENT-NAME>
```
1. Once the deployment is completed, delete the 0.11.x dapr-placement service:
```bash
kubectl delete deployment dapr-placement -n dapr-system
```
```bash
kubectl delete svc dapr-placement -n dapr-system
```
1. All done!
## Upgrade existing cluster running 1.0.0-rc.1
1. Export certs:
```bash
dapr mtls export -o ./certs
```
1. Upgrade Dapr to 1.0.0-rc.2:
```bash
helm repo update
```
```bash
helm upgrade dapr dapr/dapr --version 1.0.0-rc.2 --namespace dapr-system --reset-values --set-file dapr_sentry.tls.root.certPEM=./certs/ca.crt --set-file dapr_sentry.tls.issuer.certPEM=./certs/issuer.crt --set-file dapr_sentry.tls.issuer.keyPEM=./certs/issuer.key --set global.ha.enabled=true --wait
```
1. Upgrade CRDs:
```bash
kubectl replace -f https://raw.githubusercontent.com/dapr/dapr/21636a9237f2dcecd9c80f329e99b512e8377739/charts/dapr/crds/configuration.yaml
```
```bash
kubectl replace -f https://raw.githubusercontent.com/dapr/dapr/21636a9237f2dcecd9c80f329e99b512e8377739/charts/dapr/crds/components.yaml
```
1. Ensure all pods are running:
```bash
kubectl get pods -n dapr-system -w
NAME READY STATUS RESTARTS AGE
dapr-dashboard-69f5c5c867-mqhg4 1/1 Running 0 42s
dapr-operator-5cdd6b7f9c-9sl7g 1/1 Running 0 41s
dapr-operator-5cdd6b7f9c-jkzjs 1/1 Running 0 29s
dapr-operator-5cdd6b7f9c-qzp8n 1/1 Running 0 34s
dapr-placement-server-0 1/1 Running 0 41s
dapr-placement-server-1 1/1 Running 0 41s
dapr-placement-server-2 1/1 Running 0 41s
dapr-sentry-84565c747b-7bh8h 1/1 Running 0 35s
dapr-sentry-84565c747b-fdlls 1/1 Running 0 41s
dapr-sentry-84565c747b-ldnsf 1/1 Running 0 29s
dapr-sidecar-injector-68f868668f-6xnbt 1/1 Running 0 41s
dapr-sidecar-injector-68f868668f-j7jcq 1/1 Running 0 29s
dapr-sidecar-injector-68f868668f-ltxq4 1/1 Running 0 36s
```
1. Restart your application deployments to update the Dapr runtime:
```bash
kubectl rollout restart deploy/<DEPLOYMENT-NAME>
```
1. All done!
## Next steps
- [Dapr on Kubernetes]({{< ref kubernetes-overview.md >}})
- [Dapr production guidelines]({{< ref kubernetes-production.md >}})

4
daprdocs/content/en/operations/hosting/self-hosted/self-hosted-no-docker.md
View File

@ -10,7 +10,7 @@ This article provides guidance on running Dapr in self-hosted mode without Docke
## Prerequisites
- [Dapr CLI]({{< ref "install-dapr.md#installing-dapr-cli" >}})
- [Dapr CLI]({{< ref "install-dapr-selfhost.md#installing-dapr-cli" >}})
## Initialize Dapr without containers
@ -63,4 +63,4 @@ Update the state store configuration files to have the Redis host and password m
## Cleanup
Follow the uninstall [instructions]({{< ref "install-dapr.md#uninstall-dapr-in-a-self-hosted-mode" >}}) to remove the binaries.
Follow the uninstall [instructions]({{< ref "install-dapr-selfhost.md#uninstall-dapr-in-a-self-hosted-mode" >}}) to remove the binaries.

22
daprdocs/content/en/operations/hosting/self-hosted/self-hosted-uninstall.md Normal file
View File

@ -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 %}}

35
daprdocs/content/en/operations/hosting/self-hosted/self-hosted-upgrade.md Normal file
View File

@ -0,0 +1,35 @@
---
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"
---
1. Uninstall the current Dapr deployment:
{{% alert title="Note" color="warning" %}}
This will remove the default `$HOME/.dapr` directory, binaries and all containers (dapr_redis, dapr_placement and dapr_zipkin). Linux users need to run `sudo` if docker command needs sudo.
{{% /alert %}}
```bash
dapr uninstall --all
```
1. Download and install the latest CLI by visiting [this guide]({{< ref install-dapr-cli.md >}}).
1. Initialize the Dapr runtime:
```bash
dapr init --runtime-version=1.0.0-rc.2
```
1. Ensure you are using the latest version of Dapr (1.0.0-rc.2) with:
```bash
$ dapr --version
CLI version: 1.0.0-rc.3
Runtime version: 1.0.0-rc.2
```

107
daprdocs/content/en/operations/monitoring/grafana.md
View File

@ -1,11 +1,35 @@
---
type: docs
title: "How-To: Observe metrics with Grafana"
linkTitle: "Grafana"
linkTitle: "Metrics dashboards with Grafana"
weight: 5000
description: "How to view Dapr metrics in a Grafana dashboard."
---
## Available dashboards
{{< tabs "System Service" "Sidecars" "Actors" >}}
{{% codetab %}}
The `grafana-system-services-dashboard.json` template shows Dapr system component status, dapr-operator, dapr-sidecar-injector, dapr-sentry, and dapr-placement:
<img src="/images/grafana-system-service-dashboard.png" alt="Screenshot of the system service dashboard" width=1200>
{{% /codetab %}}
{{% codetab %}}
The `grafana-sidecar-dashboard.json` template shows Dapr sidecar status, including sidecar health/resources, throughput/latency of HTTP and gRPC, Actor, mTLS, etc.:
<img src="/images/grafana-sidecar-dashboard.png" alt="Screenshot of the sidecar dashboard" width=1200>
{{% /codetab %}}
{{% codetab %}}
The `grafana-actor-dashboard.json` template shows Dapr Sidecar status, actor invocation throughput/latency, timer/reminder triggers, and turn-based concurrnecy:
<img src="/images/grafana-actor-dashboard.png" alt="Screenshot of the actor dashboard" width=1200>
{{% /codetab %}}
{{< /tabs >}}
## Pre-requisites
- [Setup Prometheus]({{<ref prometheus.md>}})
@ -14,40 +38,36 @@ description: "How to view Dapr metrics in a Grafana dashboard."
### Install Grafana
1. Install Grafana
Add the Grafana Helm repo:
1. Add the Grafana Helm repo:
```bash
helm repo add grafana https://grafana.github.io/helm-charts
```
Install the chart:
1. Install the chart:
```bash
helm install grafana grafana/grafana -n dapr-monitoring
```
If you are Minikube user or want to disable persistent volume for development purpose, you can disable it by using the following command:
{{% alert title="Note" color="primary" %}}
If you are Minikube user or want to disable persistent volume for development purpose, you can disable it by using the following command instead:
```bash
helm install grafana grafana/grafana -n dapr-monitoring --set persistence.enabled=false
```
{{% /alert %}}
2. Retrieve the admin password for Grafana login
1. Retrieve the admin password for Grafana login:
```bash
kubectl get secret --namespace dapr-monitoring grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo
cj3m0OfBNx8SLzUlTx91dEECgzRlYJb60D2evof1%
```
{{% alert title="Note" color="info" %}}
Remove the `%` character from the password that this command returns. For example, the admin password is `cj3m0OfBNx8SLzUlTx91dEECgzRlYJb60D2evof1`.
{{% /alert %}}
You will get a password similar to `cj3m0OfBNx8SLzUlTx91dEECgzRlYJb60D2evof1%`. Remove the `%` character from the password to get `cj3m0OfBNx8SLzUlTx91dEECgzRlYJb60D2evof1` as the admin password.
3. Validation
Ensure Grafana is running in your cluster (see last line below)
1. Validation Grafana is running in your cluster:
```bash
kubectl get pods -n dapr-monitoring
@ -66,31 +86,37 @@ description: "How to view Dapr metrics in a Grafana dashboard."
### Configure Prometheus as data source
First you need to connect Prometheus as a data source to Grafana.
1. Port-forward to svc/grafana
1. Port-forward to svc/grafana:
```bash
$ kubectl port-forward svc/grafana 8080:80 -n dapr-monitoring
kubectl port-forward svc/grafana 8080:80 -n dapr-monitoring
Forwarding from 127.0.0.1:8080 -> 3000
Forwarding from [::1]:8080 -> 3000
Handling connection for 8080
Handling connection for 8080
```
2. Browse `http://localhost:8080`
1. Open a browser to `http://localhost:8080`
3. Login with admin and password
1. Login to Grafana
- Username = `admin`
- Password = Password from above
4. Click Configuration Settings -> Data Sources
1. Select `Configuration` and `Data Sources`
![data source](/images/grafana-datasources.png)
<img src="/images/grafana-datasources.png" alt="Screenshot of the Grafana add Data Source menu" width=200>
5. Add Prometheus as a data source.
![add data source](/images/grafana-add-datasources.png)
1. Add Prometheus as a data source.
6. Enter Promethesus server address in your cluster.
<img src="/images/grafana-add-datasources.png" alt="Screenshot of the Prometheus add Data Source" width=600>
You can get the Prometheus server address by running the following command.
1. Get your Prometheus HTTP URL
The Prometheus HTTP URL follows the format `http://<prometheus service endpoint>.<namespace>`
Start by getting the Prometheus server endpoint by running the following command:
```bash
kubectl get svc -n dapr-monitoring
@ -108,40 +134,43 @@ First you need to connect Prometheus as a data source to Grafana.
```
In this Howto, the server is `dapr-prom-prometheus-server`.
In this guide the server name is `dapr-prom-prometheus-server` and the namespace is `dapr-monitoring`, so the HTTP URL will be `http://dapr-prom-prometheus-server.dapr-monitoring`.
You now need to set up Prometheus data source with the following settings:
1. Fill in the following settings:
- Name: `Dapr`
- HTTP URL: `http://dapr-prom-prometheus-server.dapr-monitoring`
- Default: On
![prometheus server](/images/grafana-prometheus-dapr-server-url.png)
7. Click `Save & Test` button to verify that the connection succeeded.
<img src="/images/grafana-prometheus-dapr-server-url.png" alt="Screenshot of the Prometheus Data Source configuration" width=600>
1. Click `Save & Test` button to verify that the connection succeeded.
## Import dashboards in Grafana
Next you import the Dapr dashboards into Grafana.
In the upper left, click the "+" then "Import".
1. In the upper left corner of the Grafana home screen, click the "+" option, then "Import".
You can now import built-in [Grafana dashboard templates](https://github.com/dapr/dapr/tree/master/grafana).
You can now import [Grafana dashboard templates](https://github.com/dapr/dapr/tree/master/grafana) from [release assets](https://github.com/dapr/dapr/releases) for your Dapr version:
The Grafana dashboards are part of [release assets](https://github.com/dapr/dapr/releases) with this URL https://github.com/dapr/dapr/releases/
You can find `grafana-actor-dashboard.json`, `grafana-sidecar-dashboard.json` and `grafana-system-services-dashboard.json` in release assets location.
<img src="/images/grafana-uploadjson.png" alt="Screenshot of the Grafana dashboard upload option" width=700>
![upload json](/images/grafana-uploadjson.png)
1. Find the dashboard that you imported and enjoy
8. Find the dashboard that you imported and enjoy!
<img src="/images/system-service-dashboard.png" alt="Screenshot of Dapr service dashbaord" width=900>
![upload json](/images/system-service-dashboard.png)
{{% alert title="Tip" color="primary" %}}
Hover your mouse over the `i` in the corner to the description of each chart:
<img src="/images/grafana-tooltip.png" alt="Screenshot of the tooltip for graphs" width=700>
{{% /alert %}}
## References
* [Set up Prometheus and Grafana]({{< ref grafana.md >}})
* [Dapr Observability]({{<ref observability-concept.md >}})
* [Prometheus Installation](https://github.com/prometheus-community/helm-charts)
* [Prometheus on Kubernetes](https://github.com/coreos/kube-prometheus)
* [Prometheus Query Language](https://prometheus.io/docs/prometheus/latest/querying/basics/)
* [Supported Dapr metrics](https://github.com/dapr/dapr/blob/master/docs/development/dapr-metrics.md)
## Example
<iframe width="560" height="315" src="https://www.youtube.com/embed/8W-iBDNvCUM?start=2577" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
<iframe width="560" height="315" src="https://www.youtube.com/embed/8W-iBDNvCUM?start=2577" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

51
daprdocs/content/en/operations/monitoring/jaeger.md
View File

@ -28,30 +28,29 @@ docker run -d --name jaeger \
Next, create the following YAML files locally:
* **jaeger.yaml**: Note that because we are using the Zipkin protocol to talk to Jaeger,
the type of the exporter in the YAML file below is `exporter.zipkin`,
while the `exporterAddress` is the address of the Jaeger instance.
* **config.yaml**: Note that because we are using the Zipkin protocol
to talk to Jaeger, we specify the `zipkin` section of tracing
configuration set the `endpointAddress` to address of the Jaeger
instance.
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
kind: Configuration
metadata:
name: zipkin
name: tracing
namespace: default
spec:
type: exporters.zipkin
metadata:
- name: enabled
value: "true"
- name: exporterAddress
value: "http://localhost:9412/api/v2/spans"
tracing:
samplingRate: "1"
zipkin:
endpointAddress: "http://localhost:9412/api/v2/spans"
```
To launch the application referring to the new YAML file, you can use
`--components-path`. Assuming that, the **jaeger.yaml** file is in the
current directory, you can use
`--config` option:
```bash
dapr run --app-id mynode --app-port 3000 node app.js --components-path .
dapr run --app-id mynode --app-port 3000 node app.js --config config.yaml
```
### Viewing Traces
@ -92,26 +91,7 @@ kubectl apply -f jaeger-operator.yaml
kubectl wait deploy --selector app.kubernetes.io/name=jaeger --for=condition=available
```
Next, create the following YAML files locally:
* **jaeger.yaml**: Note that because we are using the Zipkin protocol to talk to Jaeger,
the type of the exporter in the YAML file below is `exporter.zipkin`,
while the `exporterAddress` is the address of the Jaeger instance.
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: zipkin
spec:
type: exporters.zipkin
metadata:
- name: enabled
value: "true"
- name: exporterAddress
value: "http://jaeger-collector.default.svc.cluster.local:9411/api/v2/spans"
```
Next, create the following YAML file locally:
* **tracing.yaml**
@ -124,13 +104,14 @@ metadata:
spec:
tracing:
samplingRate: "1"
zipkin:
endpointAddress: "http://jaeger-collector.default.svc.cluster.local:9411/api/v2/spans"
```
Finally, deploy the the Dapr component and configuration files:
```bash
kubectl apply -f tracing.yaml
kubectl apply -f jaeger.yaml
```
In order to enable this configuration for your Dapr sidecar, add the following annotation to your pod spec template:

20
daprdocs/content/en/operations/monitoring/newrelic.md
View File

@ -10,25 +10,23 @@ description: "Set-up New Relic for Dapr observability"
- Perpetually [free New Relic account](https://newrelic.com/signup), 100 GB/month of free data ingest, 1 free full access user, unlimited free basic users
## Configure Zipkin Exporter
## Configure Dapr tracing
Dapr natively captures metrics and traces that can be send directly to New Relic. The easiest way to export these is by providing a Zipkin exporter configured to send the traces to [New Relic's Trace API](https://docs.newrelic.com/docs/understand-dependencies/distributed-tracing/trace-api/report-zipkin-format-traces-trace-api#existing-zipkin).
Dapr natively captures metrics and traces that can be send directly to New Relic. The easiest way to export these is by configuring Dapr to send the traces to [New Relic's Trace API](https://docs.newrelic.com/docs/understand-dependencies/distributed-tracing/trace-api/report-zipkin-format-traces-trace-api#existing-zipkin) using the Zipkin trace format.
In order for the integration to send data to New Relic [Telemetry Data Platform](https://newrelic.com/platform/telemetry-data-platform), you need a [New Relic Insights Insert API key](https://docs.newrelic.com/docs/apis/get-started/intro-apis/types-new-relic-api-keys#insights-insert-key).
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
kind: Configuration
metadata:
name: zipkin
name: appconfig
namespace: default
spec:
type: exporters.zipkin
metadata:
- name: enabled
value: "true"
- name: exporterAddress
value: "https://trace-api.newrelic.com/trace/v1?Api-Key=<NR-INSIGHTS-INSERT-API-KEY>&Data-Format=zipkin&Data-Format-Version=2"
tracing:
samplingRate: "1"
zipkin:
endpointAddress: "https://trace-api.newrelic.com/trace/v1?Api-Key=<NR-INSIGHTS-INSERT-API-KEY>&Data-Format=zipkin&Data-Format-Version=2"
```
### Viewing Traces
@ -114,4 +112,4 @@ All the data that is collected from Dapr, Kubernetes or any services that run on
* [New Relic Metric API](https://docs.newrelic.com/docs/telemetry-data-platform/get-data/apis/introduction-metric-api)
* [Types of New Relic API keys](https://docs.newrelic.com/docs/apis/get-started/intro-apis/types-new-relic-api-keys)
* [New Relic OpenTelemetry User Experience](https://blog.newrelic.com/product-news/opentelemetry-user-experience/)
* [Alerts and Applied Intelligence](https://docs.newrelic.com/docs/alerts-applied-intelligence)
* [Alerts and Applied Intelligence](https://docs.newrelic.com/docs/alerts-applied-intelligence)

54
daprdocs/content/en/operations/monitoring/zipkin.md
View File

@ -9,28 +9,9 @@ type: docs
## Configure self hosted mode
For self hosted mode, on running `dapr init` the following YAML files are created by default and they are referenced by default on `dapr run` calls unless otherwise overridden.
For self hosted mode, on running `dapr init`:
1. The following file in `$HOME/dapr/components/zipkin.yaml` or `%USERPROFILE%\dapr\components\zipkin.yaml`:
* zipkin.yaml
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: zipkin
namespace: default
spec:
type: exporters.zipkin
version: v1
metadata:
- name: enabled
value: "true"
- name: exporterAddress
value: "http://localhost:9411/api/v2/spans"
```
2. The following file in `$HOME/dapr/config.yaml` or `%USERPROFILE%\dapr\config.yaml`:
1. The following YAML file is created by default in `$HOME/.dapr/config.yaml` (on Linux/Mac) or `%USERPROFILE%\.dapr\config.yaml` (on Windows) and it is referenced by default on `dapr run` calls unless otherwise overridden `:
* config.yaml
@ -43,9 +24,11 @@ metadata:
spec:
tracing:
samplingRate: "1"
zipkin:
endpointAddress: "http://localhost:9411/api/v2/spans"
```
3. The [openzipkin/zipkin](https://hub.docker.com/r/openzipkin/zipkin/) docker container is launched on running `dapr init` or it can be launched with the following code.
2. The [openzipkin/zipkin](https://hub.docker.com/r/openzipkin/zipkin/) docker container is launched on running `dapr init` or it can be launched with the following code.
Launch Zipkin using Docker:
@ -53,7 +36,7 @@ Launch Zipkin using Docker:
docker run -d -p 9411:9411 openzipkin/zipkin
```
4. The applications launched with `dapr run` will by default reference the config file in `$HOME/dapr/config.yaml` or `%USERPROFILE%\dapr\config.yaml` and can be overridden with the Dapr CLI using the `--config` param:
3. The applications launched with `dapr run` will by default reference the config file in `$HOME/.dapr/config.yaml` or `%USERPROFILE%\.dapr\config.yaml` and can be overridden with the Dapr CLI using the `--config` param:
```bash
dapr run --app-id mynode --app-port 3000 node app.js
@ -79,25 +62,7 @@ Create a Kubernetes service for the Zipkin pod:
kubectl expose deployment zipkin --type ClusterIP --port 9411
```
Next, create the following YAML files locally:
* zipkin.yaml component
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: zipkin
namespace: default
spec:
type: exporters.zipkin
version: v1
metadata:
- name: enabled
value: "true"
- name: exporterAddress
value: "http://zipkin.default.svc.cluster.local:9411/api/v2/spans"
```
Next, create the following YAML file locally:
* tracing.yaml configuration
@ -110,13 +75,14 @@ metadata:
spec:
tracing:
samplingRate: "1"
zipkin:
endpointAddress: "http://zipkin.default.svc.cluster.local:9411/api/v2/spans"
```
Finally, deploy the the Dapr component and configuration files:
Now, deploy the the Dapr configuration file:
```bash
kubectl apply -f tracing.yaml
kubectl apply -f zipkin.yaml
```
In order to enable this configuration for your Dapr sidecar, add the following annotation to your pod spec template:

4
daprdocs/content/en/operations/security/api-token.md
View File

@ -1,6 +1,6 @@
---
type: docs
title: "Enable API token based authentication"
title: "Enable token based API authentication"
linkTitle: "API token auth"
weight: 3000
description: "Require every incoming API request to include an authentication token before allowing that request to pass through"
@ -14,7 +14,7 @@ Dapr uses [JWT](https://jwt.io/) tokens for API authentication.
> Note, while Dapr itself is actually not the JWT token issuer in this implementation, being explicit about the use of JWT standard enables federated implementations in the future (e.g. OAuth2).
To configure APIs authentication, start by generating your token using any JWT token compatible tool (e.g. https://jwt.io/) and your secret.
To configure API authentication, start by generating your token using any JWT token compatible tool (e.g. https://jwt.io/) and your secret.
> Note, that secret is only necessary to generate the token, and Dapr doesn't need to know about or store it

2
daprdocs/content/en/operations/troubleshooting/common_issues.md
View File

@ -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" >}})

40
daprdocs/content/en/operations/troubleshooting/setup-tracing.md
View File

@ -6,8 +6,6 @@ weight: 3000
description: "Configure Dapr to send distributed tracing data"
---
Dapr integrates with Open Census for telemetry and tracing.
It is recommended to run Dapr with tracing enabled for any production scenario.
Since Dapr uses Open Census, you can configure various exporters for tracing and telemetry data based on your environment, whether it is running in the cloud or on-premises.
@ -17,22 +15,18 @@ The `tracing` section under the `Configuration` spec contains the following prop
```yml
tracing:
enabled: true
exporterType: zipkin
exporterAddress: ""
expandParams: true
includeBody: true
tracing:
samplingRate: "1"
zipkin:
endpointAddress: "https://..."
```
The following table lists the different properties.
The following table lists the properties for tracing:
| Property | Type | Description |
|----------|------|-------------|
| enabled | bool | Set tracing to be enabled or disabled
| exporterType | string | Name of the Open Census exporter to use. For example: Zipkin, Azure Monitor, etc
| exporterAddress | string | URL of the exporter
| expandParams | bool | When true, expands parameters passed to HTTP endpoints
| includeBody | bool | When true, includes the request body in the tracing event
| Property | Type | Description |
|--------------|--------|-------------|
| `samplingRate` | string | Set sampling rate for tracing to be enabled or disabled.
| `zipkin.endpointAddress` | string | Set the Zipkin server address.
## Zipkin in stand-alone mode
@ -51,11 +45,9 @@ For Standalone mode, create a Dapr configuration file locally and reference it w
namespace: default
spec:
tracing:
enabled: true
exporterType: zipkin
exporterAddress: "http://localhost:9411/api/v2/spans"
expandParams: true
includeBody: true
samplingRate: "1"
zipkin:
endpointAddress: "http://localhost:9411/api/v2/spans"
```
2. Launch Zipkin using Docker:
@ -99,11 +91,9 @@ metadata:
namespace: default
spec:
tracing:
enabled: true
exporterType: zipkin
exporterAddress: "http://zipkin.default.svc.cluster.local:9411/api/v2/spans"
expandParams: true
includeBody: true
samplingRate: "1"
zipkin:
endpointAddress: "http://zipkin.default.svc.cluster.local:9411/api/v2/spans"
```
Finally, deploy the Dapr configuration:

19
daprdocs/content/en/reference/api/actors_api.md
View File

@ -27,7 +27,7 @@ Code | Description
---- | -----------
200 | Request successful
500 | Request failed
XXX | Status code from upstream call
404 | Actor not found
#### URL Parameters
@ -84,7 +84,7 @@ POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state
Code | Description
---- | -----------
204 | Request successful
201 | Request successful
400 | Actor not found
500 | Request failed
@ -208,9 +208,9 @@ To configure the reminder to fire once only, the period should be set to empty s
Code | Description
---- | -----------
204 | Request successful
200 | Request successful
500 | Request failed
400 | Actor not found or malformed request
404 | Actor not found
#### URL Parameters
@ -251,6 +251,7 @@ Code | Description
---- | -----------
200 | Request successful
500 | Request failed
404 | Actor not found
#### URL Parameters
@ -294,8 +295,9 @@ DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<
Code | Description
---- | -----------
204 | Request successful
200 | Request successful
500 | Request failed
404 | Actor not found
#### URL Parameters
@ -347,9 +349,9 @@ A `dueTime` of 0 means to fire immediately. The following body means to fire im
Code | Description
---- | -----------
204 | Request successful
200 | Request successful
500 | Request failed
400 | Actor not found or malformed request
404 | Actor not found
#### URL Parameters
@ -389,8 +391,9 @@ DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<nam
Code | Description
---- | -----------
204 | Request successful
200 | Request successful
500 | Request failed
404 | Actor not found
#### URL Parameters

4
daprdocs/content/en/reference/api/bindings_api.md
View File

@ -23,7 +23,6 @@ metadata:
namespace: <NAMESPACE>
spec:
type: bindings.<TYPE>
version: v1
metadata:
- name: <NAME>
value: <VALUE>
@ -59,7 +58,6 @@ metadata:
namespace: default
spec:
type: bindings.kafka
version: v1
metadata:
- name: brokers
value: "http://localhost:5050"
@ -173,8 +171,6 @@ POST/PUT http://localhost:<daprPort>/v1.0/bindings/<name>
Code | Description
---- | -----------
200 | Request successful
204 | Empty Response
400 | Malformed request
500 | Request failed
### Payload

58
daprdocs/content/en/reference/api/error_codes.md
View File

@ -16,34 +16,30 @@ For http calls made to Dapr runtime, when an error is encountered, an error json
Following table lists the error codes returned by Dapr runtime:
| Error Code | Description |
|-----------------------------------|-------------|
| ERR_ACTOR_INSTANCE_MISSING | Error getting an actor instance. This means that actor is now hosted in some other service replica.
| ERR_ACTOR_RUNTIME_NOT_FOUND | Error getting the actor instance.
| ERR_ACTOR_REMINDER_CREATE | Error creating a reminder for an actor.
| ERR_ACTOR_REMINDER_DELETE | Error deleting a reminder for an actor.
| ERR_ACTOR_TIMER_CREATE | Error creating a timer for an actor.
| ERR_ACTOR_TIMER_DELETE | Error deleting a timer for an actor.
| ERR_ACTOR_REMINDER_GET | Error getting a reminder for an actor.
| ERR_ACTOR_INVOKE_METHOD | Error invoking a method on an actor.
| ERR_ACTOR_STATE_DELETE | Error deleting the state for an actor.
| ERR_ACTOR_STATE_GET | Error getting the state for an actor.
| ERR_ACTOR_STATE_TRANSACTION_SAVE | Error storing actor state transactionally.
| ERR_PUBSUB_NOT_FOUND | Error referencing the Pub/Sub component in Dapr runtime.
| ERR_PUBSUB_PUBLISH_MESSAGE | Error publishing a message.
| ERR_PUBSUB_FORBIDDEN | Error message forbidden by access controls.
| ERR_PUBSUB_CLOUD_EVENTS_SER | Error serializing Pub/Sub event envelope.
| ERR_STATE_STORE_NOT_FOUND | Error referencing a state store not found.
| ERR_STATE_STORES_NOT_CONFIGURED | Error no state stores configured.
| ERR_NOT_SUPPORTED_STATE_OPERATION | Error transaction requested on a state store with no transaction support.
| ERR_STATE_GET | Error getting a state for state store.
| ERR_STATE_DELETE | Error deleting a state from state store.
| ERR_STATE_SAVE | Error saving a state in state store.
| ERR_INVOKE_OUTPUT_BINDING | Error invoking an output binding.
| ERR_MALFORMED_REQUEST | Error with a malformed request.
| ERR_DIRECT_INVOKE | Error in direct invocation.
| ERR_DESERIALIZE_HTTP_BODY | Error deserializing an HTTP request body.
| ERR_SECRET_STORES_NOT_CONFIGURED | Error that no secret store is configured.
| ERR_SECRET_STORE_NOT_FOUND | Error that specified secret store is not found.
| ERR_HEALTH_NOT_READY | Error that Dapr is not ready.
| ERR_METADATA_GET | Error parsing the Metadata information.
| Error Code | Description |
|----------------------------------|-------------|
| ERR_ACTOR_INSTANCE_MISSING | Error getting an actor instance. This means that actor is now hosted in some other service replica.
| ERR_ACTOR_RUNTIME_NOT_FOUND | Error getting the actor instance.
| ERR_ACTOR_REMINDER_CREATE | Error creating a reminder for an actor.
| ERR_ACTOR_REMINDER_DELETE | Error deleting a reminder for an actor.
| ERR_ACTOR_TIMER_CREATE | Error creating a timer for an actor.
| ERR_ACTOR_TIMER_DELETE | Error deleting a timer for an actor.
| ERR_ACTOR_REMINDER_GET | Error getting a reminder for an actor.
| ERR_ACTOR_INVOKE_METHOD | Error invoking a method on an actor.
| ERR_ACTOR_STATE_DELETE | Error deleting the state for an actor.
| ERR_ACTOR_STATE_GET | Error getting the state for an actor.
| ERR_ACTOR_STATE_TRANSACTION_SAVE | Error storing actor state transactionally.
| ERR_PUBSUB_NOT_FOUND | Error referencing the Pub/Sub component in Dapr runtime.
| ERR_PUBSUB_PUBLISH_MESSAGE | Error publishing a message.
| ERR_PUBSUB_CLOUD_EVENTS_SER | Error serializing Pub/Sub event envelope.
| ERR_STATE_STORE_NOT_FOUND | Error referencing a state store not found.
| ERR_STATE_GET | Error getting a state for state store.
| ERR_STATE_DELETE | Error deleting a state from state store.
| ERR_STATE_SAVE | Error saving a state in state store.
| ERR_INVOKE_OUTPUT_BINDING | Error invoking an output binding.
| ERR_MALFORMED_REQUEST | Error with a malformed request.
| ERR_DIRECT_INVOKE | Error in direct invocation.
| ERR_DESERIALIZE_HTTP_BODY | Error deserializing an HTTP request body.
| ERR_SECRET_STORE_NOT_CONFIGURED | Error that no secret store is configured.
| ERR_SECRET_STORE_NOT_FOUND | Error that specified secret store is not found.
| ERR_HEALTH_NOT_READY | Error that Dapr is not ready.

4
daprdocs/content/en/reference/api/health_api.md
View File

@ -3,7 +3,7 @@ type: docs
title: "Health API reference"
linkTitle: "Health API"
description: "Detailed documentation on the health API"
weight: 700
weight: 900
---
Dapr provides health checking probes that can be used as readiness or liveness of Dapr.
@ -22,7 +22,7 @@ GET http://localhost:<daprPort>/v1.0/healthz
Code | Description
---- | -----------
204 | dapr is healthy
200 | dapr is healthy
500 | dapr is not healthy
### URL Parameters

191
daprdocs/content/en/reference/api/metadata_api.md
View File

@ -1,191 +0,0 @@
---
type: docs
title: "Metadata API reference"
linkTitle: "Metadata API"
description: "Detailed documentation on the Metadata API"
weight: 800
---
Dapr has a metadata API that returns information about the sidecar allowing runtime discoverability. The metadata endpoint returns among other things, a list of the components loaded and the activated actors (if present).
The Dapr metadata API also allows you to store additional information in the format of key-value pairs.
Note: The Dapr metatada endpoint is for instance being used by the Dapr CLI when running dapr in standalone mode to store the PID of the process hosting the sidecar and the command used to run the application.
## Get the Dapr sidecar information
Gets the Dapr sidecar information provided by the Metadata Endpoint.
### HTTP Request
```http
GET http://localhost:<daprPort>/v1.0/metadata
```
### URL Parameters
Parameter | Description
--------- | -----------
daprPort | The Dapr port.
### HTTP Response Codes
Code | Description
---- | -----------
200 | Metadata information returned
500 | Dapr could not return the metadata information
### HTTP Response Body
**Metadata API Response Object**
Name | Type | Description
---- | ---- | -----------
id | string | Application ID
actors | [Metadata API Response Registered Actor](#metadataapiresponseactor)[] | A json encoded array of Registered Actors metadata.
extended.attributeName | string | List of custom attributes as key-value pairs, where key is the attribute name.
components | [Metadata API Response Component](#metadataapiresponsecomponent)[] | A json encoded array of loaded components metadata.
<a id="metadataapiresponseactor"></a>**Metadata API Response Registered Actor**
Name | Type | Description
---- | ---- | -----------
type | string | The registered actor type.
count | integer | Number of actors running.
<a id="metadataapiresponsecomponent"></a>**Metadata API Response Component**
Name | Type | Description
---- | ---- | -----------
name | string | Name of the component.
type | string | Component type.
version | string | Component version.
### Examples
Note: This example is based on the Actor sample provided in the [Dapr SDK for Python](https://github.com/dapr/python-sdk/tree/master/examples/demo_actor).
```shell
curl http://localhost:3500/v1.0/metadata
```
```json
{
"id":"demo-actor",
"actors":[
{
"type":"DemoActor",
"count":1
}
],
"extended": {
"cliPID":"1031040",
"appCommand":"uvicorn --port 3000 demo_actor_service:app"
},
"components":[
{
"name":"pubsub",
"type":"pubsub.redis",
"version":""
},
{
"name":"statestore",
"type":"state.redis",
"version":""
},
{
"name":"zipkin",
"type":"exporters.zipkin",
"version":""
}
]
}
```
## Add a custom attribute to the Dapr sidecar information
Adds a custom attribute to the Dapr sidecar information stored by the Metadata Endpoint.
### HTTP Request
```http
PUT http://localhost:<daprPort>/v1.0/metadata/attributeName
```
### URL Parameters
Parameter | Description
--------- | -----------
daprPort | The Dapr port.
attributeName | Custom attribute name. This is they key name in the key-value pair.
### HTTP Request Body
In the request you need to pass the custom attribute value as RAW data:
```json
{
"Content-Type": "text/plain"
}
```
Within the body of the request place the custom attribute value you want to store:
```
attributeValue
```
### HTTP Response Codes
Code | Description
---- | -----------
204 | Custom attribute added to the metadata information
### Examples
Note: This example is based on the Actor sample provided in the [Dapr SDK for Python](https://github.com/dapr/python-sdk/tree/master/examples/demo_actor).
Add a custom attribute to the metadata endpoint:
```shell
curl -X PUT -H "Content-Type: text/plain" --data "myDemoAttributeValue" http://localhost:3500/v1.0/metadata/myDemoAttribute
```
Get the metadata information to confirm your custom attribute was added:
```json
{
"id":"demo-actor",
"actors":[
{
"type":"DemoActor",
"count":1
}
],
"extended": {
"myDemoAttribute": "myDemoAttributeValue",
"cliPID":"1031040",
"appCommand":"uvicorn --port 3000 demo_actor_service:app"
},
"components":[
{
"name":"pubsub",
"type":"pubsub.redis",
"version":""
},
{
"name":"statestore",
"type":"state.redis",
"version":""
},
{
"name":"zipkin",
"type":"exporters.zipkin",
"version":""
}
]
}
```

10
daprdocs/content/en/reference/api/pubsub_api.md
View File

@ -21,9 +21,7 @@ POST http://localhost:<daprPort>/v1.0/publish/<pubsubname>/<topic>
Code | Description
---- | -----------
204 | Message delivered
403 | Message forbidden by access controls
404 | No pubsub name or topic given
200 | Message delivered
500 | Delivery failed
### URL Parameters
@ -103,8 +101,7 @@ path | route path from the subscription configuration
#### Expected HTTP Response
An HTTP 2xx response denotes successful processing of message.
For richer response handling, a JSON encoded payload body with the processing status can be sent:
An HTTP 200 response with JSON encoded payload body with the processing status:
```json
{
@ -117,9 +114,8 @@ Status | Description
SUCCESS | message is processed successfully
RETRY | message to be retried by Dapr
DROP | warning is logged and message is dropped
Others | error, message to be retried by Dapr
Dapr assumes a JSON encoded payload response without `status` field or an empty payload responses with HTTP 2xx, as `SUCCESS`.
For empty payload responses in HTTP 2xx, Dapr assumes `SUCCESS`.
The HTTP response might be different from HTTP 2xx, the following are Dapr's behavior in different HTTP statuses:

5
daprdocs/content/en/reference/api/secrets_api.md
View File

@ -3,7 +3,7 @@ type: docs
title: "Secrets API reference"
linkTitle: "Secrets API"
description: "Detailed documentation on the secrets API"
weight: 600
weight: 700
---
## Get Secret
@ -89,8 +89,7 @@ Code | Description
200 | OK
204 | Secret not found
400 | Secret store is missing or misconfigured
403 | Access denied
500 | Failed to get secret or no secret stores defined
500 | Failed to get secret
### Examples

5
daprdocs/content/en/reference/api/service_invocation_api.md
View File

@ -28,9 +28,6 @@ In case a user invokes Dapr over HTTP to talk to a gRPC enabled service, an erro
Code | Description
---- | -----------
XXX | Upstream status returned
400 | Method name not given
403 | Invocation forbidden by access control
500 | Request failed
### URL Parameters
@ -121,4 +118,4 @@ In case you are invoking `mathService` on a different namespace, you can use the
In this URL, `testing` is the namespace that `mathService` is running in.
## Next Steps
- [How-To: Invoke and discover services]({{< ref howto-invoke-discover-services.md >}})
- [How-To: Invoke and discover services]({{< ref howto-invoke-discover-services.md >}})

22
daprdocs/content/en/reference/api/state_api.md
View File

@ -18,7 +18,6 @@ metadata:
namespace: <NAMESPACE>
spec:
type: state.<TYPE>
version: v1
metadata:
- name:<KEY>
value:<VALUE>
@ -87,8 +86,8 @@ options | (optional) state operation options, see [state operation options](#opt
Code | Description
---- | -----------
204 | State saved
400 | State store is missing or misconfigured or malformed request
201 | State saved
400 | State store is missing or misconfigured
500 | Failed to save state
#### Response Body
@ -184,7 +183,7 @@ This endpoint lets you get a list of values for a given list of keys.
### HTTP Request
```
POST/PUT http://localhost:<daprPort>/v1.0/state/<storename>/bulk
POST http://localhost:<daprPort>/v1.0/state/<storename>/bulk
```
#### URL Parameters
@ -217,7 +216,7 @@ curl http://localhost:3500/v1.0/state/myRedisStore/bulk \
-H "Content-Type: application/json" \
-d '{
"keys": [ "key1", "key2" ],
"parallelism": 10
"parallelism": 10,
}'
```
@ -234,7 +233,7 @@ curl http://localhost:3500/v1.0/state/myRedisStore/bulk \
"key": "key2",
"data": "value2",
"etag": "1"
}
},
]
```
To pass metadata as query parammeter:
@ -278,7 +277,7 @@ If-Match | (Optional) ETag associated with the key to be deleted
Code | Description
---- | -----------
204 | Delete state successful
200 | Delete state successful
400 | State store is missing or misconfigured
500 | Delete state failed
@ -315,8 +314,8 @@ POST/PUT http://localhost:<daprPort>/v1.0/state/<storename>/transaction
Code | Description
---- | -----------
204 | Request successful
400 | State store is missing or misconfigured or malformed request
201 | Request successful
400 | State store is missing or misconfigured
500 | Request failed
#### URL Parameters
@ -388,7 +387,6 @@ metadata:
namespace: default
spec:
type: state.redis
version: v1
metadata:
- name: redisHost
value: <redis host>
@ -448,7 +446,7 @@ curl -X POST http://localhost:3500/v1.0/state/starwars \
"etag": "xxxxx",
"options": {
"concurrency": "first-write",
"consistency": "strong"
"consistency": "strong",
}
}
]'
@ -456,4 +454,4 @@ curl -X POST http://localhost:3500/v1.0/state/starwars \
## Next Steps
- [State management overview]({{< ref state-management-overview.md >}})
- [How-To: Save & get state]({{< ref howto-get-save-state.md >}})
- [How-To: Save & get state]({{< ref howto-get-save-state.md >}})

39
daprdocs/content/en/reference/cli/cli-overview.md
View File

@ -9,14 +9,13 @@ weight: 10
The Dapr CLI allows you to setup Dapr on your local dev machine or on a Kubernetes cluster, provides debugging support, and launches and manages Dapr instances.
```bash
__
____/ /___ _____ _____
/ __ / __ '/ __ \/ ___/
/ /_/ / /_/ / /_/ / /
\__,_/\__,_/ .___/_/
/_/
/ /_/ / /_/ / /_/ / /
\__,_/\__,_/ .___/_/
/_/
===============================
Distributed Application Runtime
@ -25,20 +24,20 @@ Usage:
Available Commands:
completion Generates shell completion scripts
components List all Dapr components
configurations List all Dapr configurations
dashboard Start Dapr dashboard
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, currently: Kubernetes and self-hosted
invoke Invoke a method on a given Dapr application
list List all Dapr instances
logs Get Dapr sidecar logs for an application
mtls Check if mTLS is enabled
publish Publish a pub-sub event
run Run Dapr and (optionally) your application side by side
status Show the health status of Dapr services
stop Stop Dapr instances and their associated apps in self-hosted mode
uninstall Uninstall Dapr runtime
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
@ -60,7 +59,7 @@ You can learn more about each Dapr command from the links below.
- [`dapr invoke`]({{< ref dapr-invoke.md >}})
- [`dapr list`]({{< ref dapr-list.md >}})
- [`dapr logs`]({{< ref dapr-logs.md >}})
- [`dapr mtls`]({{< ref dapr-mtls.md >}})
- [`dapr mtls`]({{< ref dapr-mtls >}})
- [`dapr publish`]({{< ref dapr-publish.md >}})
- [`dapr run`]({{< ref dapr-run.md >}})
- [`dapr status`]({{< ref dapr-status.md >}})

17
daprdocs/content/en/reference/cli/dapr-completion.md
View File

@ -12,10 +12,16 @@ Generates shell completion scripts
## Usage
```bash
dapr completion [flags]
dapr completion [command]
dapr completion [flags]
dapr completion [command]
```
## Flags
| Name | Environment Variable | Default | Description |
|------|----------------------|---------|-------------|
| `--help`, `-h` | | | Prints this help message |
## Examples
### Installing bash completion on macOS using Homebrew
@ -96,10 +102,3 @@ bash Generates bash completion scripts
powershell Generates powershell completion scripts
zsh Generates zsh completion scripts
```
## Flags
| Name | Environment Variable | Default | Description
| --- | --- | --- | --- |
| `--help`, `-h` | | | Prints this help message |
|

13
daprdocs/content/en/reference/cli/dapr-components.md
View File

@ -7,7 +7,11 @@ description: "Detailed information on the components CLI command"
## Description
List all Dapr components
List all Dapr components.
## Supported platforms
- [Kubernetes]({{< ref kubernetes >}})
## Usage
@ -21,3 +25,10 @@ dapr components [flags]
| --- | --- | --- | --- |
| `--help`, `-h` | | | Print this help message |
| `--kubernetes`, `-k` | | `false` | List all Dapr components in a Kubernetes cluster |
## Examples
### List Kubernetes components
```bash
dapr components -k
```

17
daprdocs/content/en/reference/cli/dapr-configurations.md
View File

@ -7,7 +7,11 @@ description: "Detailed information on the configurations CLI command"
## Description
List all Dapr configurations
List all Dapr configurations.
## Supported platforms
- [Kubernetes]({{< ref kubernetes >}})
## Usage
@ -19,5 +23,14 @@ dapr configurations [flags]
| Name | Environment Variable | Default | Description
| --- | --- | --- | --- |
| `--kubernetes`, `-k` | | `false` | List all Dapr configurations in a Kubernetes cluster
| `--name`, `-n` | | | The configuration name to be printed (optional)
| `--output`, `-o` | | `list`| Output format (options: json or yaml or list)
| `--help`, `-h` | | | Print this help message |
| `--kubernetes`, `-k` | | `false` | List all Dapr configurations in a Kubernetes cluster |
## Examples
### List Kubernetes Dapr configurations
```bash
dapr configurations -k
```

44
daprdocs/content/en/reference/cli/dapr-dashboard.md
View File

@ -7,20 +7,46 @@ description: "Detailed information on the dashboard CLI command"
## Description
Start Dapr dashboard
Start [Dapr dashboard](https://github.com/dapr/dashboard).
## Supported platforms
- [Self-Hosted]({{< ref self-hosted >}})
- [Kubernetes]({{< ref kubernetes >}})
## Usage
```bash
dapr dashboard [flags]
```
## Flags
| Name | Environment Variable | Default | Description
| --- | --- | --- | --- |
| `--help`, `-h` | | | Prints this help message |
| `--kubernetes`, `-k` | | `false` | Opens Dapr dashboard in local browser via local proxy to Kubernetes cluster |
| `--namespace`, `-n` | | `dapr-system` | The namespace where Dapr dashboard is running |
| `--port`, `-p` | | `8080` | The local port on which to serve Dapr dashboard |
| `--version`, `-v` | | `false` | Print the version for Dapr dashboard |
| Name | Environment Variable | Default | Description |
|------|----------------------|---------|-------------|
| `--help`, `-h` | | | Prints this help message |
| `--kubernetes`, `-k` | | `false` | Opens Dapr dashboard in local browser via local proxy to Kubernetes cluster |
| `--namespace`, `-n` | | `dapr-system` | The namespace where Dapr dashboard is running |
| `--port`, `-p` | | `8080` | The local port on which to serve Dapr dashboard |
| `--version`, `-v` | | `false` | Print the version for Dapr dashboard |
## Examples
### Start dashboard locally
```bash
dapr dashboard
```
### Start dashboard service locally on a specified port
```bash
dapr dashboard -p 9999
```
### Port forward to dashboard service running in Kubernetes
```bash
dapr dashboard -k
```
### Port forward to dashboard service running in Kubernetes on a specified port
```bash
dapr dashboard -k -p 9999
```

36
daprdocs/content/en/reference/cli/dapr-init.md
View File

@ -7,10 +7,14 @@ description: "Detailed information on the init CLI command"
## Description
Install Dapr on supported hosting platforms, currently: Kubernetes and self-hosted
Install Dapr on supported hosting platforms.
## Supported platforms
- [Self-Hosted]({{< ref self-hosted >}})
- [Kubernetes]({{< ref kubernetes >}})
## Usage
```bash
dapr init [flags]
```
@ -25,6 +29,32 @@ dapr init [flags]
| `--kubernetes`, `-k` | | `false` | Deploy Dapr to a Kubernetes cluster |
| `--namespace`, `-n` | | `dapr-system` | The Kubernetes namespace to install Dapr in |
| `--network` | `DAPR_NETWORK` | | The Docker network on which to deploy the Dapr runtime |
| `--redis-host` | `DAPR_REDIS_HOST` | `localhost` | The host on which the Redis service resides |
| `--runtime-version` | | `latest` | The version of the Dapr runtime to install, for example: `1.0.0` |
| `--slim`, `-s` | | `false` | Exclude placement service, Redis and Zipkin containers from self-hosted installation |
## Examples
### Initialize Dapr in self-hosted mode
```bash
dapr init
```
### Initialize Dapr in Kubernetes
```bash
dapr init -k
```
### Initialize specified version of Dapr runtime in self-hosted mode
```bash
dapr init --runtime-version 0.10.0
```
### Initialize specified version of Dapr runtime in Kubernetes
```bash
dapr init -k --runtime-version 0.10.0
```
### Initialize Dapr in [slim self-hosted mode]({{< ref self-hosted-no-docker.md >}})
```bash
dapr init -s
```

21
daprdocs/content/en/reference/cli/dapr-invoke.md
View File

@ -7,10 +7,13 @@ description: "Detailed information on the invoke CLI command"
## Description
Invoke a method on a given Dapr application
Invoke a method on a given Dapr application.
## Supported platforms
- [Self-Hosted]({{< ref self-hosted >}})
## Usage
```bash
dapr invoke [flags]
```
@ -22,5 +25,17 @@ dapr invoke [flags]
| `--app-id`, `-a` | | | The application id to invoke |
| `--help`, `-h` | | | Print this help message |
| `--method`, `-m` | | | The method to invoke |
| `--payload`, `-p` | | | The JSON payload (optional) |
| `--data`, `-d` | | | The JSON serialized data string (optional) |
| `--verb`, `-v` | | `POST` | The HTTP verb to use |
## Examples
### Invoke a sample method on target app with POST Verb
```bash
dapr invoke --app-id target --method sample --data '{"key":"value"}'
```
### Invoke a sample method on target app with GET Verb
```bash
dapr invoke --app-id target --method sample --verb GET
```

24
daprdocs/content/en/reference/cli/dapr-invokeGet.md
View File

@ -1,24 +0,0 @@
---
type: docs
title: "invokeGet CLI command reference"
linkTitle: "invokeGet"
description: "Detailed information on the invokeGet CLI command"
---
## Description
Issue HTTP GET to Dapr app
## Usage
```bash
dapr invokeGet [flags]
```
## Flags
| Name | Environment Variable | Default | Description
| --- | --- | --- | --- |
| `--app-id`, `-a` | | | The app ID to invoke |
| `--help`, `-h` | | | Help for invokeGet |
| `--method`, `-m` | | | The method to invoke |

25
daprdocs/content/en/reference/cli/dapr-invokePost.md
View File

@ -1,25 +0,0 @@
---
type: docs
title: "invokePost CLI command reference"
linkTitle: "invokePost"
description: "Detailed information on the invokePost CLI command"
---
## Description
Issue HTTP POST to Dapr app with an optional payload
## Usage
```bash
dapr invokePost [flags]
```
## Flags
| Name | Environment Variable | Default | Description
| --- | --- | --- | --- |
| `--app-id`, `-a` | | | The app ID to invoke |
| `--help`, `-h` | | | Help for invokePost |
| `--method`, `-m` | | | The method to invoke |
| `--payload`, `-p` | | | (optional) a json payload |

20
daprdocs/content/en/reference/cli/dapr-list.md
View File

@ -7,10 +7,14 @@ description: "Detailed information on the list CLI command"
## Description
List all Dapr instances
List all Dapr instances.
## Supported platforms
- [Self-Hosted]({{< ref self-hosted >}})
- [Kubernetes]({{< ref kubernetes >}})
## Usage
```bash
dapr list [flags]
```
@ -21,3 +25,15 @@ dapr list [flags]
| --- | --- | --- | --- |
| `--help`, `-h` | | | Print this help message |
| `--kubernetes`, `-k` | | `false` | List all Dapr pods in a Kubernetes cluster |
## Examples
### List Dapr instances in self-hosted mode
```bash
dapr list
```
### List Dapr instances in Kubernetes mode
```bash
dapr list -k
```

15
daprdocs/content/en/reference/cli/dapr-logs.md
View File

@ -7,10 +7,13 @@ description: "Detailed information on the logs CLI command"
## Description
Gets Dapr sidecar logs for an app in Kubernetes
Get Dapr sidecar logs for an application.
## Supported platforms
- [Kubernetes]({{< ref kubernetes >}})
## Usage
```bash
dapr logs [flags]
```
@ -24,3 +27,11 @@ dapr logs [flags]
| `--kubernetes`, `-k` | | `true` | Get logs from a Kubernetes cluster |
| `--namespace`, `-n` | | `default` | The Kubernetes namespace in which your application is deployed |
| `--pod-name`, `-p` | | | The name of the pod in Kubernetes, in case your application has multiple pods (optional) |
## Examples
### Get logs of sample app from target pod in custom namespace
```bash
dapr logs -k --app-id sample --pod-name target --namespace custom
```

30
daprdocs/content/en/reference/cli/dapr-mtls.md → daprdocs/content/en/reference/cli/dapr-mtls/_index.md
View File

@ -7,7 +7,11 @@ description: "Detailed information on the mtls CLI command"
## Description
Check if mTLS is enabled
Check if mTLS is enabled.
## Supported platforms
- [Kubernetes]({{< ref kubernetes >}})
## Usage
@ -16,6 +20,13 @@ dapr mtls [flags]
dapr mtls [command]
```
## Flags
| Name | Environment Variable | Default | Description
| --- | --- | --- | --- |
| `--help`, `-h` | | | Print this help message |
| `--kubernetes`, `-k` | | `false` | Check if mTLS is enabled in a Kubernetes cluster |
## Available Commands
```txt
@ -23,9 +34,16 @@ expiry Checks the expiry of the root certificate
export Export the root CA, issuer cert and key from Kubernetes to local files
```
## Flags
## Command Reference
| Name | Environment Variable | Default | Description
| --- | --- | --- | --- |
| `--help`, `-h` | | | Print this help message |
| `--kubernetes`, `-k` | | `false` | Check if mTLS is enabled in a Kubernetes cluster |
You can learn more about each sub command from the links below.
- [`dapr mtls expiry`]({{< ref dapr-mtls-expiry.md >}})
- [`dapr mtls export`]({{< ref dapr-mtls-export.md >}})
## Examples
### Check if mTLS is enabled
```bash
dapr mtls -k
```

33
daprdocs/content/en/reference/cli/dapr-mtls/dapr-mtls-expiry.md Normal file
View File

@ -0,0 +1,33 @@
---
type: docs
title: "mtls expiry CLI command reference"
linkTitle: "mtls expiry"
description: "Detailed information on the mtls expiry CLI command"
weight: 2000
---
## Description
Checks the expiry of the root certificate
## Supported platforms
- [Kubernetes]({{< ref kubernetes >}})
## Usage
```bash
dapr mtls expiry [flags]
```
## Flags
| Name | Environment Variable | Default | Description
| --- | --- | --- | --- |
| `--help`, `-h` | | | help for expiry |
## Examples
### Check expiry of Kubernetes certs
```bash
dapr mtls expiry
```

34
daprdocs/content/en/reference/cli/dapr-mtls/dapr-mtls-export.md Normal file
View File

@ -0,0 +1,34 @@
---
type: docs
title: "mtls export CLI command reference"
linkTitle: "mtls export"
description: "Detailed information on the mtls export CLI command"
weight: 1000
---
## Description
Export the root CA, issuer cert and key from Kubernetes to local files
## Supported platforms
- [Kubernetes]({{< ref kubernetes >}})
## Usage
```bash
dapr mtls export [flags]
```
## Flags
| Name | Environment Variable | Default | Description
| --- | --- | --- | --- |
| `--help`, `-h` | | | help for export |
| `--out`, `-o` | | current directory | The output directory path to save the certs |
## Examples
### Check expiry of Kubernetes certs
```bash
dapr mtls export -o ./certs
```

19
daprdocs/content/en/reference/cli/dapr-publish.md
View File

@ -7,7 +7,11 @@ description: "Detailed information on the publish CLI command"
## Description
Publish an event to multiple consumers
Publish a pub-sub event.
## Supported platforms
- [Self-Hosted]({{< ref self-hosted >}})
## Usage
@ -19,7 +23,16 @@ dapr publish [flags]
| Name | Environment Variable | Default | Description
| --- | --- | --- | --- |
| `--publish-app-id` | `-i`| | The ID that represents the app from which you are publishing
| `--pubsub` | `-p` | | The name of the pub/sub component
| `--topic`, `-t` | | | The topic to be published to |
| `--data`, `-d` | | | The JSON serialized string (optional) |
| `--help`, `-h` | | | Print this help message |
| `--pubsub` | | | The name of the pub/sub component
| `--topic`, `-t` | | | The topic to be published to |
## Examples
### Publish to sample topic in target pubsub
```bash
dapr publish --publish-app-id appId --topic sample --pubsub target --data '{"key":"value"}'
```

60
daprdocs/content/en/reference/cli/dapr-run.md
View File

@ -7,7 +7,11 @@ description: "Detailed information on the run CLI command"
## Description
Run Dapr's sidecar and (optionally) an application.
Run Dapr and (optionally) your application side by side.
## Supported platforms
- [Self-Hosted]({{< ref self-hosted >}})
## Usage
@ -15,30 +19,11 @@ Run Dapr's sidecar and (optionally) an application.
dapr run [flags] [command]
```
## Examples
Run a Java application:
```bash
dapr run --app-id myapp -- java -jar myapp.jar
```
Run a NodeJs application that listens to port 3000:
```bash
dapr run --app-id myapp --app-port 3000 -- node myapp.js
```
Run a Python application:
```bash
dapr run --app-id myapp -- python myapp.py
```
Run sidecar only:
```bash
dapr run --app-id myapp
```
## Flags
| Name | Environment Variable | Default | Description
| --- | --- | --- | --- |
| `--app-id`, `-i` | | | The id for your application, used for service discovery |
| `--app-id`, `-a` | | | The id for your application, used for service discovery |
| `--app-max-concurrency` | | `unlimited` | The concurrency level of the application, otherwise is unlimited |
| `--app-port`, `-p` | | | The port your application is listening on
| `--app-protocol`, `-P` | | `http` | The protocol (gRPC or HTTP) Dapr uses to talk to the application. Valid values are: `http` or `grpc` |
@ -50,7 +35,38 @@ dapr run --app-id myapp
| `--enable-profiling` | | `false` | Enable `pprof` profiling via an HTTP endpoint
| `--help`, `-h` | | | Print this help message |
| `--image` | | | The image to build the code in. Input is: `repository/image` |
| `--log-level` | | `info` | The log verbosity. Valid values are: `debug`, `info`, `warning`, `error`, `fatal`, or `panic` |
| `--log-level` | | `info` | The log verbosity. Valid values are: `debug`, `info`, `warn`, `error`, `fatal`, or `panic` |
| `--placement-host-address` | `DAPR_PLACEMENT_HOST` | `localhost` | The host on which the placement service resides |
| `--profile-port` | | `7777` | The port for the profile server to listen on |
## Examples
### Run a .NET application
```bash
dapr run --app-id myapp --app-port 5000 -- dotnet run
```
### Run a Java application
```bash
dapr run --app-id myapp -- java -jar myapp.jar
```
### Run a NodeJs application that listens to port 3000
```bash
dapr run --app-id myapp --app-port 3000 -- node myapp.js
```
### Run a Python application
```bash
dapr run --app-id myapp -- python myapp.py
```
### Run sidecar only
```bash
dapr run --app-id myapp
```

15
daprdocs/content/en/reference/cli/dapr-status.md
View File

@ -7,12 +7,14 @@ description: "Detailed information on the status CLI command"
## Description
Show the health status of Dapr services
Show the health status of Dapr services.
## Supported platforms
- [Kubernetes]({{< ref kubernetes >}})
## Usage
This command only works for Kubernetes mode.
```bash
dapr status -k
```
@ -23,3 +25,10 @@ dapr status -k
| --- | --- | --- | --- |
| `--help`, `-h` | | | Print this help message |
| `--kubernetes`, `-k` | | `false` | Show the health status of Dapr services on Kubernetes cluster |
## Examples
### Get status of Dapr services from Kubernetes
```bash
dapr status -k
```

15
daprdocs/content/en/reference/cli/dapr-stop.md
View File

@ -7,7 +7,11 @@ description: "Detailed information on the stop CLI command"
## Description
Stop Dapr instances and their associated apps in self-hosted mode
Stop Dapr instances and their associated apps.
## Supported platforms
- [Self-Hosted]({{< ref self-hosted >}})
## Usage
@ -19,5 +23,12 @@ dapr stop [flags]
| Name | Environment Variable | Default | Description
| --- | --- | --- | --- |
| `--app-id` | | | The application id to be stopped |
| `--app-id`, `-a` | | | The application id to be stopped |
| `--help`, `-h` | | | Print this help message |
## Examples
### Stop Dapr application
```bash
dapr stop --app-id <ID>
```

Some files were not shown because too many files have changed in this diff Show More