-
-The following are the building blocks provided by Dapr:
-
-
-
-You can use the [Dapr CLI](https://github.com/dapr/cli#launch-dapr-and-your-app) to run a Dapr enabled application on your local machine.
-
-## Running Dapr in Kubernetes mode
-
-Dapr can be configured to run on any [Kubernetes cluster](https://github.com/dapr/quickstarts/tree/master/hello-kubernetes). In Kubernetes the `dapr-sidecar-injector` and `dapr-operator` services provide first class integration to launch Dapr as a sidecar container in the same pod as the service container and provide notifications of Dapr component updates provisioned into the cluster. Additionally, the `dapr-sidecar-injector` also injects the environment variables `DAPR_HTTP_PORT` and `DAPR_GRPC_PORT` into **all** the containers in the pod to enable user defined applications to easily communicate with Dapr without hardcoding Dapr port values.
-
-The `dapr-sentry` service is a certificate authority that enables mutual TLS between Dapr sidecar instances for secure data encryption. For more information on the `Sentry` service read the [security overview](../security/README.md#dapr-to-dapr-communication)
-
-
-
-Deploying and running a Dapr enabled application into your Kubernetes cluster is a simple as adding a few annotations to the deployment schemes. To give your service an `id` and `port` known to Dapr, turn on tracing through configuration and launch the Dapr sidecar container, you annotate your Kubernetes deployment like this.
-
-```yml
- annotations:
- dapr.io/enabled: "true"
- dapr.io/app-id: "nodeapp"
- dapr.io/app-port: "3000"
- dapr.io/config: "tracing"
-```
-You can see some examples [here](https://github.com/dapr/quickstarts/tree/master/hello-kubernetes/deploy) in the Kubernetes getting started sample.
-
-Read [Kubernetes how to topics](https://github.com/dapr/docs/tree/master/howto#kubernetes-configuration) for more information about setting up Kubernetes and Dapr.
diff --git a/concepts/observability/README.md b/concepts/observability/README.md
deleted file mode 100644
index 5b48a278e..000000000
--- a/concepts/observability/README.md
+++ /dev/null
@@ -1,39 +0,0 @@
-# Observability
-
-Observability is a term from control theory. Observability means you can answer questions about what's happening on the inside of a system by observing the outside of the system, without having to ship new code to answer new questions. Observability is critical in production environments and services to debug, operate and monitor Dapr system services, components and user applications.
-
-The observability capabilities enable users to monitor the Dapr system services, their interaction with user applications and understand how these monitored services behave. The observability capabilities are divided into the following areas;
-
-* **[Metrics](./metrics.md)**: are the series of measured values and counts that are collected and stored over time. Dapr metrics provide monitoring and understanding of the behavior of Dapr system services and user apps. For example, the service metrics between Dapr sidecars and user apps show call latency, traffic failures, error rates of requests etc. Dapr system services metrics show side car injection failures, health of the system services including CPU usage, number of actor placement made etc.
-* **[Logs](./logs.md)**: are records of events that occur and can be used to determine failures or another status. Logs events contain warning, error, info, and debug messages produced by Dapr system services. Each log event includes metadata such as message type, hostname, component name, App ID, ip address, etc.
-* **[Distributed tracing](./traces.md)**: is used to profile and monitor Dapr system services and user apps. Distributed tracing helps pinpoint where failures occur and what causes poor performance. Distributed tracing is particularly well-suited to debugging and monitoring distributed software architectures, such as microservices.
-
- You can use distributed tracing to help debug and optimize application code. Distributed tracing contains trace spans between the Dapr runtime, Dapr system services, and user apps across process, nodes, network, and security boundaries. It provides a detailed understanding of service invocations (call flows) and service dependencies.
-
- Dapr uses [W3C tracing context for distributed tracing](./W3C-traces.md)
-
- It is generally recommended to run Dapr in production with tracing.
-
-* **[Health](./health.md)**: Dapr provides a way for a hosting platform to determine it's health using an HTTP endpoint. With this endpoint, the Dapr process, or sidecar, can be probed to determine its readiness and liveness and action taken accordingly.
-
-## Open Telemetry
-Dapr integrates with OpenTelemetry for metrics, logs and tracing. With OpenTelemetry, you can configure various exporters for tracing and metrics based on your environment, whether it is running in the cloud or on-premises.
-
-## Monitoring tools
-
-The observability tools listed below are ones that have been tested to work with Dapr.
-
-### Metrics
-
-* [How-To: Set up Prometheus and Grafana](../../howto/setup-monitoring-tools/setup-prometheus-grafana.md)
-* [How-To: Set up Azure Monitor](../../howto/setup-monitoring-tools/setup-azure-monitor.md)
-
-### Logs
-
-* [How-To: Set up Fluentd, Elastic search and Kibana in Kubernetes](../../howto/setup-monitoring-tools/setup-fluentd-es-kibana.md)
-* [How-To: Set up Azure Monitor](../../howto/setup-monitoring-tools/setup-azure-monitor.md)
-
-### Distributed Tracing
-
-* [How-To: Set up Zipkin](../../howto/diagnose-with-tracing/zipkin.md)
-* [How-To: Set up Application Insights with Open Telemetry Collector](../../howto/diagnose-with-tracing/open-telemetry-collector.md)
diff --git a/contributing/README.md b/contributing/README.md
deleted file mode 100644
index 3db8846f5..000000000
--- a/contributing/README.md
+++ /dev/null
@@ -1,42 +0,0 @@
-# Contributing to Dapr documentation
-
-High quality documentation is a core tenant of the Dapr project. Some contribution guidelines are below.
-
-## Style and tone
-
-- Use sentence-casing for headers.
-- When referring to product names and technologies use capitalization (e.g. Kubernetes, Helm, Visual Studio Code, Azure Key Vault and of course Dapr).
-- Check the spelling and grammar in your articles.
-- Use a casual and friendly voice—like tone as if you're talking to another person one-on-one.
-- Use simple sentences. Easy-to-read sentences mean the reader can quickly use the guidance you share.
-- Use “you” rather than “users” or “developers” conveying friendliness.
-- Avoid the word “will”; write in present tense and not future where possible. E.g. Avoid “Next we will open the file and build”. Just say “Now open the file and build”
-- Avoid the word “we”. We is generally not meaningful. We who?
-- Avoid the word “please”. This is not a letter asking for any help, this is technical documentation.
-- 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.
-- Where possible give the reader links to next document/article for next steps or related topics (this can be relevant "how-to", samples for reference or concepts).
-
-# Contributing to `Concepts`
-
-- Ensure the reader can understand why they should care about this feature. What problems does it help them solve?
-- Ensure the doc references the spec for examples of using the API.
-- Ensure the spec is consistent with concept in terms of names, parameters and terminology. Update both the concept and the spec as needed.
-- Avoid just repeating the spec. The idea is to give the reader more information and background on the capability so that they can try this out. Hence provide more information and implementation details where possible.
-- Provide a link to the spec in the [Reference](/reference) section.
-- Where possible reference a practical [How-To](/howto) doc.
-
-# Contributing to `How-Tos`
-
-See [this template](./howto-template.md) for `How To` articles.
-
-- `How To` articles are meant to provide step-by-step practical guidance on to readers who wish to enable a feature, integrate a technology or use Dapr in a specific scenario.
-- Location - `How To` articles should all be under the [howto](../howto) directory in a relevant sub directories - make sure to see if the article you are contributed should be included in an existing sub directory.
-- Sub directory naming - the directory name should be descriptive and if referring to specific component or concept should begin with the relevant name. Example *pubsub-namespaces*.
-- When adding a new article make sure to add a link in the main [How To README.md](../howto/README.md) as well as other articles or samples that may be relevant.
-- Do not assume the reader is using a specific environment unless the article itself is specific to an environment. This include OS (Windows/Linux/MacOS), deployment target (Kubernetes, IoT etc.) or programming language. If instructions vary between operating systems, provide guidance for all.
-- How to articles should include the following sub sections:
- - **Pre-requesties**
- - **\
+
+Welcome to the Dapr documentation site!
\ No newline at end of file
diff --git a/daprdocs/content/en/concepts/_index.md b/daprdocs/content/en/concepts/_index.md
new file mode 100644
index 000000000..bcfdf00f6
--- /dev/null
+++ b/daprdocs/content/en/concepts/_index.md
@@ -0,0 +1,7 @@
+---
+type: docs
+title: "Dapr Concepts"
+linkTitle: "Concepts"
+weight: 10
+description: "Learn about Dapr including its main features and capabilities"
+---
\ No newline at end of file
diff --git a/daprdocs/content/en/concepts/building-blocks-concept.md b/daprdocs/content/en/concepts/building-blocks-concept.md
new file mode 100644
index 000000000..6ac19979a
--- /dev/null
+++ b/daprdocs/content/en/concepts/building-blocks-concept.md
@@ -0,0 +1,29 @@
+---
+type: docs
+title: "Building blocks"
+linkTitle: "Building blocks"
+weight: 200
+description: "Modular best practices accessible over standard HTTP or gRPC APIs"
+---
+
+A [building block]({{< ref building-blocks >}}) is as an HTTP or gRPC API that can be called from your code and uses one or more Dapr components.
+
+Building blocks address common challenges in building resilient, microservices applications and codify best practices and patterns. Dapr consists of a set of building blocks, with extensibility to add new building blocks.
+
+The diagram below shows how building blocks expose a public API that is called from your code, using components to implement the building blocks' capability.
+
+
+
+The following are the building blocks provided by Dapr:
+
+
+
+| Building Block | Endpoint | Description |
+|----------------|----------|-------------|
+| [**Service-to-service invocation**]({{}}) | `/v1.0/invoke` | Service invocation enables applications to communicate with each other through well-known endpoints in the form of http or gRPC messages. Dapr provides an endpoint that acts as a combination of a reverse proxy with built-in service discovery, while leveraging built-in distributed tracing and error handling.
+| [**State management**]({{}}) | `/v1.0/state` | Application state is anything an application wants to preserve beyond a single session. Dapr provides a key/value-based state API with pluggable state stores for persistence.
+| [**Publish and subscribe**]({{}}) | `/v1.0/publish` `/v1.0/subscribe`| Pub/Sub is a loosely coupled messaging pattern where senders (or publishers) publishes messages to a topic, to which subscribers subscribe. Dapr supports the pub/sub pattern between applications.
+| [**Resource bindings**]({{}}) | `/v1.0/bindings` | A binding provides a bi-directional connection to an external cloud/on-premise service or system. Dapr allows you to invoke the external service through the Dapr binding API, and it allows your application to be triggered by events sent by the connected service.
+| [**Actors**]({{}}) | `/v1.0/actors` | An actor is an isolated, independent unit of compute and state with single-threaded execution. Dapr provides an actor implementation based on the Virtual Actor pattern which provides a single-threaded programming model and where actors are garbage collected when not in use. See * [Actor Overview](./actors#understanding-actors)
+| [**Observability**]({{}}) | `N/A` | Dapr system components and runtime emit metrics, logs, and traces to debug, operate and monitor Dapr system services, components and user applications.
+| [**Secrets**]({{}}) | `/v1.0/secrets` | Dapr offers a secrets building block API and integrates with secret stores such as Azure Key Vault and Kubernetes to store the secrets. Service code can call the secrets API to retrieve secrets out of the Dapr supported secret stores.
diff --git a/daprdocs/content/en/concepts/components-concept.md b/daprdocs/content/en/concepts/components-concept.md
new file mode 100644
index 000000000..db1a2c0ba
--- /dev/null
+++ b/daprdocs/content/en/concepts/components-concept.md
@@ -0,0 +1,32 @@
+---
+type: docs
+title: "Components"
+linkTitle: "Components"
+weight: 300
+description: "Modular functionality used by building blocks and applications"
+---
+
+Dapr uses a modular design where functionality is delivered as a component. Each component has an interface definition. All of the components are pluggable so that you can swap out one component with the same interface for another. The [components contrib repo](https://github.com/dapr/components-contrib) is where you can contribute implementations for the component interfaces and extends Dapr's capabilities.
+
+ A building block can use any combination of components. For example the [actors]({{}}) building block and the [state management]({{}}) building block both use [state components](https://github.com/dapr/components-contrib/tree/master/state). As another example, the [Pub/Sub]({{}}) building block uses [Pub/Sub components](https://github.com/dapr/components-contrib/tree/master/pubsub).
+
+ You can get a list of current components available in the current hosting environment using the `dapr components` CLI command.
+
+ The following are the component types provided by Dapr:
+
+* [Bindings](https://github.com/dapr/components-contrib/tree/master/bindings)
+* [Pub/sub](https://github.com/dapr/components-contrib/tree/master/pubsub)
+* [Middleware](https://github.com/dapr/components-contrib/tree/master/middleware)
+* [Service discovery name resolution](https://github.com/dapr/components-contrib/tree/master/nameresolution)
+* [Secret stores](https://github.com/dapr/components-contrib/tree/master/secretstores)
+* [State](https://github.com/dapr/components-contrib/tree/master/state)
+* [Tracing exporters](https://github.com/dapr/components-contrib/tree/master/exporters)
+
+### Service invocation and service discovery components
+Service discovery components are used with the [service invocation]({{}}) building block to integrate with the hosting environment to provide service-to-service discovery. For example, the Kubernetes service discovery component integrates with the Kubernetes DNS service and self hosted uses mDNS.
+
+### Service invocation and middleware components
+Dapr allows custom [middleware]({{}}) to be plugged into the request processing pipeline. Middleware can perform additional actions on a request, such as authentication, encryption and message transformation before the request is routed to the user code, or before the request is returned to the client. The middleware components are used with the [service invocation]({{}}) building block.
+
+### Secret store components
+In Dapr, a [secret]({{}}) is any piece of private information that you want to guard against unwanted users. Secrets stores, used to store secrets, are Dapr components and can be used by any of the building blocks.
diff --git a/daprdocs/content/en/concepts/configuration-concept.md b/daprdocs/content/en/concepts/configuration-concept.md
new file mode 100644
index 000000000..e9f3a407e
--- /dev/null
+++ b/daprdocs/content/en/concepts/configuration-concept.md
@@ -0,0 +1,12 @@
+---
+type: docs
+title: "Configuration"
+linkTitle: "Configuration"
+weight: 400
+description: "Change the behavior of Dapr sidecars or globally on Dapr system services"
+---
+
+Dapr configurations are settings that enable you to change the behavior of individual Dapr application sidecars or globally on the system services in the Dapr control plane.
+An example of a per Dapr application sidecar setting is configuring trace settings. An example of a Dapr control plane setting is mutual TLS which is a global setting on the Sentry system service.
+
+Read [this page]({{}}) for a list of all configuration options.
diff --git a/FAQ.md b/daprdocs/content/en/concepts/faq.md
similarity index 94%
rename from FAQ.md
rename to daprdocs/content/en/concepts/faq.md
index 21be4bda0..a494c2a01 100644
--- a/FAQ.md
+++ b/daprdocs/content/en/concepts/faq.md
@@ -1,65 +1,66 @@
-# FAQ
-
-- **[Networking and service meshes](#networking-and-service-meshes)**
-- **[Performance Benchmarks](#performance-benchmarks)**
-- **[Actors](#actors)**
-- **[Developer language SDKs and frameworks](#developer-language-sdks-and-frameworks)**
-
-## Networking and service meshes
-
-### Understanding how Dapr works with service meshes
-
-Dapr is a distributed application runtime. Unlike a service mesh which is focused on networking concerns, Dapr is focused on providing building blocks that make it easier for developers to build microservices. Dapr is developer-centric versus service meshes being infrastructure-centric.
-
-Dapr can be used alongside any service mesh such as Istio and Linkerd. A service mesh is a dedicated network infrastructure layer designed to connect services to one another and provide insightful telemetry. A service mesh doesn’t introduce new functionality to an application.
-
-That is where Dapr comes in. Dapr is a language agnostic programming model built on http and gRPC that provides distributed system building blocks via open APIs for asynchronous pub-sub, stateful services, service discovery and invocation, actors and distributed tracing. Dapr introduces new functionality to an app’s runtime. Both service meshes and Dapr run as side-car services to your application, one giving network features and the other distributed application capabilities.
-
-Watch this [video](https://www.youtube.com/watch?v=xxU68ewRmz8&feature=youtu.be&t=140) on how Dapr and service meshes work together.
-
-### Understanding how Dapr interoperates with the service mesh interface (SMI)
-
-SMI is an abstraction layer that provides a common API surface across different service mesh technology. Dapr can leverage any service mesh technology including SMI.
-
-### Differences between Dapr, Istio and Linkerd
-
-Read [How does Dapr work with service meshes?](https://github.com/dapr/dapr/wiki/FAQ#how-does-dapr-work-with-service-meshes) Istio is an open source service mesh implementation that focuses on Layer7 routing, traffic flow management and mTLS authentication between services. Istio uses a sidecar to intercept traffic going into and out of a container and enforces a set of network policies on them.
-
-Istio is not a programming model and does not focus on application level features such as state management, pub-sub, bindings etc. That is where Dapr comes in.
-
-## Performance Benchmarks
-The Dapr project is focused on performance due to the inherent discussion of Dapr being a sidecar to your application. This [performance benchmark video](https://youtu.be/4kV3SHs1j2k?t=783) discusses and demos the work that has been done so far. The performance benchmark data is planned to be published on a regular basis. You can also run the perf tests in your own environment to get perf numbers.
-
-## Actors
-
-### What is the relationship between Dapr, Orleans and Service Fabric Reliable Actors?
-
-The actors in Dapr are based on the same virtual actor concept that [Orleans](https://www.microsoft.com/research/project/orleans-virtual-actors/) started, meaning that they are activated when called and deactivated after a period of time. If you are familiar with Orleans, Dapr C# actors will be familiar. Dapr C# actors are based on [Service Fabric Reliable Actors](https://docs.microsoft.com/azure/service-fabric/service-fabric-reliable-actors-introduction) (which also came from Orleans) and enable you to take Reliable Actors in Service Fabric and migrate them to other hosting platforms such as Kubernetes or other on-premise environments.
-Also Dapr is about more than just actors. It provides you with a set of best practice building blocks to build into any microservices application. See [Dapr overview](https://github.com/dapr/docs/blob/master/overview/README.md).
-
-### Differences between Dapr from an actor framework
-
-Virtual actors capabilities are one of the building blocks that Dapr provides in its runtime. With Dapr because it is programming language agnostic with an http/gRPC API, the actors can be called from any language. This allows actors written in one language to invoke actors written in a different language.
-
-Creating a new actor follows a local call like `http://localhost:3500/v1.0/actors/
## Customize processing pipeline
-When launched, a Dapr sidecar constructs a middleware processing pipeline. By default the pipeline consists of [tracing middleware](../observability/traces.md) and CORS middleware. Additional middleware, configured by a Dapr [configuration](../configuration/README.md), can be added to the pipeline in the order they are defined. The pipeline applies to all Dapr API endpoints, including state, pub/sub, service invocation, bindings, security and others.
+When launched, a Dapr sidecar constructs a middleware processing pipeline. By default the pipeline consists of [tracing middleware]({{< ref tracing.md >}}) and CORS middleware. Additional middleware, configured by a Dapr [configuration]({{< ref configuration-concept.md >}}), can be added to the pipeline in the order they are defined. The pipeline applies to all Dapr API endpoints, including state, pub/sub, service invocation, bindings, security and others.
> **NOTE:** Dapr provides a **middleware.http.uppercase** pre-registered component that changes all text in a request body to uppercase. You can use it to test/verify if your custom pipeline is in place.
-The following configuration example defines a custom pipeline that uses a [OAuth 2.0 middleware](../../howto/authorization-with-oauth/README.md) and an uppercase middleware component. In this case, all requests are authorized through the OAuth 2.0 protocol, and transformed to uppercase text, before they are forwarded to user code.
+The following configuration example defines a custom pipeline that uses a [OAuth 2.0 middleware]({{< ref oauth.md >}}) and an uppercase middleware component. In this case, all requests are authorized through the OAuth 2.0 protocol, and transformed to uppercase text, before they are forwarded to user code.
```yaml
apiVersion: dapr.io/v1alpha1
@@ -51,8 +57,10 @@ func GetHandler(metadata Metadata) fasthttp.RequestHandler {
}
```
-## Submitting middleware components
-Your middleware component can be contributed to the https://github.com/dapr/components-contrib repository, under the */middleware* folder. Then submit another pull request against the https://github.com/dapr/dapr repository to register the new middleware type. You'll need to modify the **Load()** method under https://github.com/dapr/dapr/blob/master/pkg/components/middleware/http/registry.go to register your middleware using the **Register** method.
+## Adding new middleware components
+Your middleware component can be contributed to the [components-contrib repository](https://github.com/dapr/components-contrib/tree/master/middleware).
-## References
-* [How-To: Configure API authorization with OAuth](../../howto/authorization-with-oauth/README.md)
+Then submit another pull request against the [Dapr runtime repository](https://github.com/dapr/dapr) to register the new middleware type. You'll need to modify the **Load()** method in [registry.go]( https://github.com/dapr/dapr/blob/master/pkg/components/middleware/http/registry.go) to register your middleware using the **Register** method.
+
+## Next steps
+* [How-To: Configure API authorization with OAuth({{< ref oauth.md >}})
diff --git a/daprdocs/content/en/concepts/observability-concept.md b/daprdocs/content/en/concepts/observability-concept.md
new file mode 100644
index 000000000..71df0de23
--- /dev/null
+++ b/daprdocs/content/en/concepts/observability-concept.md
@@ -0,0 +1,63 @@
+---
+type: docs
+title: "Observability"
+linkTitle: "Observability"
+weight: 500
+description: >
+ How to monitor applications through tracing, metrics, logs and health
+---
+
+Observability is a term from control theory. Observability means you can answer questions about what's happening on the inside of a system by observing the outside of the system, without having to ship new code to answer new questions. Observability is critical in production environments and services to debug, operate and monitor Dapr system services, components and user applications.
+
+The observability capabilities enable users to monitor the Dapr system services, their interaction with user applications and understand how these monitored services behave. The observability capabilities are divided into the following areas;
+
+## Distributed tracing
+
+[Distributed tracing]({{}}) is used to profile and monitor Dapr system services and user apps. Distributed tracing helps pinpoint where failures occur and what causes poor performance. Distributed tracing is particularly well-suited to debugging and monitoring distributed software architectures, such as microservices.
+
+You can use distributed tracing to help debug and optimize application code. Distributed tracing contains trace spans between the Dapr runtime, Dapr system services, and user apps across process, nodes, network, and security boundaries. It provides a detailed understanding of service invocations (call flows) and service dependencies.
+
+Dapr uses [W3C tracing context for distributed tracing]({{}})
+
+It is generally recommended to run Dapr in production with tracing.
+
+### Open Telemetry
+
+Dapr integrates with [OpenTelemetry](https://opentelemetry.io/) for tracing, metrics and logs. With OpenTelemetry, you can configure various exporters for tracing and metrics based on your environment, whether it is running in the cloud or on-premises.
+
+#### Next steps
+
+- [How-To: Set up Zipkin]({{< ref zipkin.md >}})
+- [How-To: Set up Application Insights with Open Telemetry Collector]({{< ref open-telemetry-collector.md >}})
+
+## Metrics
+
+[Metrics]({{}}) are the series of measured values and counts that are collected and stored over time. Dapr metrics provide monitoring and understanding of the behavior of Dapr system services and user apps.
+
+For example, the service metrics between Dapr sidecars and user apps show call latency, traffic failures, error rates of requests etc.
+
+Dapr system services metrics show side car injection failures, health of the system services including CPU usage, number of actor placement made etc.
+
+#### Next steps
+
+- [How-To: Set up Prometheus and Grafana]({{< ref prometheus.md >}})
+- [How-To: Set up Azure Monitor]({{< ref azure-monitor.md >}})
+
+## Logs
+
+[Logs]({{}}) are records of events that occur and can be used to determine failures or another status.
+
+Logs events contain warning, error, info, and debug messages produced by Dapr system services. Each log event includes metadata such as message type, hostname, component name, App ID, ip address, etc.
+
+#### Next steps
+
+- [How-To: Set up Fluentd, Elastic search and Kibana in Kubernetes]({{< ref fluentd.md >}})
+- [How-To: Set up Azure Monitor]({{< ref azure-monitor.md >}})
+
+## Health
+
+Dapr provides a way for a hosting platform to determine its [Health]({{}}) using an HTTP endpoint. With this endpoint, the Dapr process, or sidecar, can be probed to determine its readiness and liveness and action taken accordingly.
+
+#### Next steps
+
+- [Health API]({{< ref health_api.md >}})
\ No newline at end of file
diff --git a/overview/README.md b/daprdocs/content/en/concepts/overview.md
similarity index 59%
rename from overview/README.md
rename to daprdocs/content/en/concepts/overview.md
index df5003f7f..46e9cad18 100644
--- a/overview/README.md
+++ b/daprdocs/content/en/concepts/overview.md
@@ -1,22 +1,17 @@
-
-# Dapr overview
+---
+type: docs
+title: "Overview"
+linkTitle: "Overview"
+weight: 100
+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.
-## Contents:
-
-- [Any language, any framework, anywhere](#any-language-any-framework-anywhere)
-- [Microservice building blocks for cloud and edge](#microservice-building-blocks-for-cloud-and-edge)
-- [Sidecar architecture](#sidecar-architecture)
-- [Developer language SDKs and frameworks](#developer-language-sdks-and-frameworks)
-- [Designed for operations](#designed-for-operations)
-- [Run anywhere](#Run-anywhere)
- - [Running Dapr on a local developer machine in self hosted mode](#running-dapr-on-a-local-developer-machine-in-self-hosted-mode)
- - [Running Dapr in Kubernetes mode](#running-dapr-in-kubernetes-mode)
-
## Any language, any framework, anywhere
-
+
Today we are experiencing a wave of cloud adoption. Developers are comfortable with web + database application architectures (for example classic 3-tier designs) but not with microservice application architectures which are inherently distributed. It’s hard to become a distributed systems expert, nor should you have to. Developers want to focus on business logic, while leaning on the platforms to imbue their applications with scale, resiliency, maintainability, elasticity and the other attributes of cloud-native architectures.
@@ -28,7 +23,7 @@ Using Dapr you can easily build microservice applications using any language, an
## Microservice building blocks for cloud and edge
-
+
There are many considerations when architecting microservices applications. Dapr provides best practices for common capabilities when building microservice applications that developers can use in a standard way and deploy to any environment. It does this by providing distributed system building blocks.
@@ -36,13 +31,13 @@ Each of these building blocks is independent, meaning that you can use one, some
| Building Block | Description |
|----------------|-------------|
-| **[Service Invocation](../concepts/service-invocation)** | Resilient service-to-service invocation enables method calls, including retries, on remote services wherever they are located in the supported hosting environment.
-| **[State Management](../concepts/state-management)** | With state management for storing key/value pairs, long running, highly available, stateful services can be easily written alongside stateless services in your application. The state store is pluggable and can include Azure CosmosDB, Azure SQL Server, PostgreSQL, AWS DynamoDB or Redis among others.
-| **[Publish and Subscribe Messaging](../concepts/publish-subscribe-messaging)** | Publishing events and subscribing to topics | tween services enables event-driven architectures to simplify horizontal scalability and make them | silient to failure. Dapr provides at least once message delivery guarantee.
-| **[Resource Bindings](../concepts/bindings)** | Resource bindings with triggers builds further on event-driven architectures for scale and resiliency by receiving and sending events to and from any external source such as databases, queues, file systems, etc.
-| **[Actors](../concepts/actors)** | A pattern for stateful and stateless objects that make concurrency simple with method and state encapsulation. Dapr provides many capabilities in its actor runtime including concurrency, state, life-cycle management for actor activation/deactivation and timers and reminders to wake-up actors.
-| **[Observability](../concepts/observability)** | Dapr emit metrics, logs, and traces to debug and monitor both Dapr and user applications. Dapr supports distributed tracing to easily diagnose and serve inter-service calls in production using the W3C Trace Context standard and Open Telemetry to send to different monitoring tools.
-| **[Secrets](../concepts/secrets)** | Dapr provides secrets management and integrates with public cloud and local secret stores to retrieve the secrets for use in application code.
+| [**Service-to-service invocation**]({{}}) | Resilient service-to-service invocation enables method calls, including retries, on remote services wherever they are located in the supported hosting environment.
+| [**State management**]({{}}) | With state management for storing key/value pairs, long running, highly available, stateful services can be easily written alongside stateless services in your application. The state store is pluggable and can include Azure CosmosDB, Azure SQL Server, PostgreSQL, AWS DynamoDB or Redis among others.
+| [**Publish and subscribe**]({{}}) | Publishing events and subscribing to topics | tween services enables event-driven architectures to simplify horizontal scalability and make them | silient to failure. Dapr provides at least once message delivery guarantee.
+| [**Resource bindings**]({{}}) | Resource bindings with triggers builds further on event-driven architectures for scale and resiliency by receiving and sending events to and from any external source such as databases, queues, file systems, etc.
+| [**Actors**]({{}}) | A pattern for stateful and stateless objects that make concurrency simple with method and state encapsulation. Dapr provides many capabilities in its actor runtime including concurrency, state, life-cycle management for actor activation/deactivation and timers and reminders to wake-up actors.
+| [**Observability**]({{}}) | Dapr emit metrics, logs, and traces to debug and monitor both Dapr and user applications. Dapr supports distributed tracing to easily diagnose and serve inter-service calls in production using the W3C Trace Context standard and Open Telemetry to send to different monitoring tools.
+| [**Secrets**]({{}}) | Dapr provides secrets management and integrates with public cloud and local secret stores to retrieve the secrets for use in application code.
## Sidecar architecture
@@ -55,13 +50,13 @@ Dapr can be hosted in multiple environments, including self hosted for local dev
In self hosted mode Dapr runs as a separate side-car process which your service code can call via HTTP or gRPC. In self hosted mode, you can also deploy Dapr onto a set of VMs.
-
+
### Kubernetes hosted
In container hosting environments such as Kubernetes, Dapr runs as a side-car container with the application container in the same pod.
-
+
## Developer language SDKs and frameworks
@@ -74,9 +69,10 @@ To make using Dapr more natural for different languages, it also includes langua
- **[Java SDK](https://github.com/dapr/java-sdk)**
- **[Javascript SDK](https://github.com/dapr/js-sdk)**
- **[Python SDK](https://github.com/dapr/python-sdk)**
+- **[RUST SDK](https://github.com/dapr/rust-sdk)**
- **[.NET SDK](https://github.com/dapr/dotnet-sdk)**
-> Note: Dapr is language agnostic and provides a [RESTful HTTP API](../reference/api/README.md) in addition to the protobuf clients.
+> Note: Dapr is language agnostic and provides a [RESTful HTTP API]({{< ref api >}}) in addition to the protobuf clients.
### Developer frameworks
Dapr can be used from any developer framework. Here are some that have been integrated with Dapr.
@@ -86,10 +82,10 @@ Dapr can be used from any developer framework. Here are some that have been int
In the Dapr [Java SDK](https://github.com/dapr/java-sdk) you can find [Spring Boot](https://spring.io/) integration.
-Dapr integrates easily with Python [Flask](https://pypi.org/project/Flask/) and node [Express](http://expressjs.com/), which you can find in the [getting started samples](https://github.com/dapr/docs/tree/master/getting-started)
+Dapr integrates easily with Python [Flask](https://pypi.org/project/Flask/) and node [Express](http://expressjs.com/). See examples in the [Dapr quickstarts](https://github.com/dapr/quickstarts).
#### Actors
-Dapr SDKs support for [virtual actors](../concepts/actors) which are stateful objects that make concurrency simple, have method and state encapsulation, and are designed for scalable, distributed applications.
+Dapr SDKs support for [virtual actors]({{< ref actors >}}) which are stateful objects that make concurrency simple, have method and state encapsulation, and are designed for scalable, distributed applications.
#### Azure Functions
Dapr integrates with the Azure Functions runtime via an extension that lets a function seamlessly interact with Dapr. Azure Functions provides an event-driven programming model and Dapr provides cloud-native building blocks. With this extension, you can bring both together for serverless and event-driven apps. For more information read
@@ -100,26 +96,26 @@ To enable developers to easily build workflow applications that use Dapr’s cap
[cloud-native workflows using Dapr and Logic Apps](https://cloudblogs.microsoft.com/opensource/2020/05/26/announcing-cloud-native-workflows-dapr-logic-apps/) and visit the [Dapr workflow](https://github.com/dapr/workflows) repo to try out the samples.
## Designed for Operations
-Dapr is designed for operations. The [services dashboard](https://github.com/dapr/dashboard), installed via the Dapr CLI, provides a web-based UI enabling you to see information, view logs and more for the Dapr sidecars.
+Dapr is designed for [operations](/operations/). The [services dashboard](https://github.com/dapr/dashboard), installed via the Dapr CLI, provides a web-based UI enabling you to see information, view logs and more for the Dapr sidecars.
-The [monitoring dashboard](../reference/dashboard/README.md) provides deeper visibility into the Dapr system services and side-cars and the [observability capabilities](../concepts/observability) of Dapr provide insights into your application such as tracing and metrics.
+The [monitoring tools support](/operations/monitoring/) provides deeper visibility into the Dapr system services and side-cars and the [observability capabilities]({{}}) of Dapr provide insights into your application such as tracing and metrics.
## Run anywhere
### Running Dapr on a local developer machine in self hosted mode
-Dapr can be configured to run on your local developer machine in [self hosted mode](../concepts/hosting/). Each running service has a Dapr runtime process (or sidecar) which is configured to use state stores, pub/sub, binding components and the other building blocks.
+Dapr can be configured to run on your local developer machine in [self-hosted mode]({{< ref self-hosted >}}). Each running service has a Dapr runtime process (or sidecar) which is configured to use state stores, pub/sub, binding components and the other building blocks.
-You can use the [Dapr CLI](https://github.com/dapr/cli#launch-dapr-and-your-app) to run a Dapr enabled application on your local machine. Try this out with the [getting started samples](../getting-started).
+You can use the [Dapr CLI](https://github.com/dapr/cli#launch-dapr-and-your-app) to run a Dapr enabled application on your local machine. Try this out with the [getting started samples]({{< ref getting-started >}}).
-
+
### Running Dapr in Kubernetes mode
-Dapr can be configured to run on any [Kubernetes cluster](../concepts/hosting/). In Kubernetes the `dapr-sidecar-injector` and `dapr-operator` services provide first class integration to launch Dapr as a sidecar container in the same pod as the service container and provide notifications of Dapr component updates provisioned into the cluster.
+Dapr can be configured to run on any [Kubernetes cluster]({{< ref kubernetes >}}). In Kubernetes the `dapr-sidecar-injector` and `dapr-operator` services provide first class integration to launch Dapr as a sidecar container in the same pod as the service container and provide notifications of Dapr component updates provisioned into the cluster.
-The `dapr-sentry` service is a certificate authority that enables mutual TLS between Dapr sidecar instances for secure data encryption. For more information on the `Sentry` service read the [security overview](../concepts/security/README.md#dapr-to-dapr-communication)
+The `dapr-sentry` service is a certificate authority that enables mutual TLS between Dapr sidecar instances for secure data encryption. For more information on the `Sentry` service read the [security overview]({{< ref "security-concept.md#dapr-to-dapr-communication" >}})
-
+
-Deploying and running a Dapr enabled application into your Kubernetes cluster is a simple as adding a few annotations to the deployment schemes. You can see some examples [here](https://github.com/dapr/quickstarts/tree/master/hello-kubernetes/deploy) in the Kubernetes getting started sample. Try this out with the [Kubernetes getting started sample](https://github.com/dapr/quickstarts/tree/master/hello-kubernetes)
+Deploying and running a Dapr enabled application into your Kubernetes cluster is a simple as adding a few annotations to the deployment schemes. You can see some examples [here](https://github.com/dapr/quickstarts/tree/master/hello-kubernetes/deploy) in the Kubernetes getting started sample. Try this out with the [Kubernetes quickstart](https://github.com/dapr/quickstarts/tree/master/hello-kubernetes).
diff --git a/concepts/security/README.md b/daprdocs/content/en/concepts/security-concept.md
similarity index 85%
rename from concepts/security/README.md
rename to daprdocs/content/en/concepts/security-concept.md
index 0a495cb1d..328a57ebe 100644
--- a/concepts/security/README.md
+++ b/daprdocs/content/en/concepts/security-concept.md
@@ -1,18 +1,14 @@
-# Security
+---
+type: docs
+title: "Security"
+linkTitle: "Security"
+weight: 600
+description: >
+ How Dapr is designed with security in mind
+---
This article addresses multiple security considerations when using Dapr in a distributed application including:
-- [Sidecar-to-App Communication](#sidecar-to-app-communication)
-- [Sidecar-to-Sidecar Communication](#sidecar-to-sidecar-communication)
-- [Sidecar-to-system-services-communication](#sidecar-to-system-services-communication)
-- [Component namespace scopes and secrets](#component-namespace-scopes-and-secrets)
-- [Network Security](#network-security)
-- [Bindings Security](#bindings-security)
-- [State Store Security](#state-store-security)
-- [Management Security](#management-security)
-- [Threat Model](#threat-model)
-- [Security Audit June 2020](#security-audit-june-2020)
-
Several of the areas above are addressed through encryption of data in transit. One of the security mechanisms that Dapr employs for encrypting data in transit is [mutual authentication TLS](https://en.wikipedia.org/wiki/Mutual_authentication) or mTLS. mTLS offers a few key features for network traffic inside your application:
- Two way authentication - the client proving its identify to the server, and vice-versa
@@ -22,11 +18,11 @@ Mutual TLS is useful in almost all scenarios, but especially so for systems subj
Dapr enables mTLS and all the features described in this document in your application with little to no extra code or complex configuration inside your production systems
-## Sidecar-to-App communication
+## Sidecar-to-app communication
The Dapr sidecar runs close to the application through **localhost**, and is recommended to run under the same network boundary as the app. While many cloud-native systems today consider the pod level (on Kubernetes, for example) as a trusted security boundary, Dapr provides user with API level authentication using tokens. This feature guarantees that even on localhost, only an authenticated caller may call into Dapr.
-## Sidecar-to-Sidecar communication
+## Sidecar-to-sidecar communication
Dapr includes an "on by default", automatic mutual TLS that provides in-transit encryption for traffic between Dapr sidecars.
To achieve this, Dapr leverages a system service named `Sentry` which acts as a Certificate Authority (CA) and signs workload (app) certificate requests originating from the Dapr sidecar.
@@ -46,17 +42,17 @@ Dapr also supports strong identities when deployed on Kubernetes, relying on a p
By default, a workload cert is valid for 24 hours and the clock skew is set to 15 minutes.
Mutual TLS can be turned off/on by editing the default configuration that is deployed with Dapr via the `spec.mtls.enabled` field.
-This can be done for both Kubernetes and self hosted modes. Details for how to do this can be found [here](../../howto/configure-mtls).
+This can be done for both Kubernetes and self hosted modes. Details for how to do this can be found [here]({{< ref mtls.md >}}).
### mTLS self hosted
The diagram below shows how the Sentry system service issues certificates for applications based on the root/issuer certificate that is provided by an operator or generated by the Sentry service as stored in a file
-
+
### mTLS in Kubernetes
The diagram below shows how the Sentry system service issues certificates for applications based on the root/issuer certificate that is provided by an operator or generated by the Sentry service as stored as a Kubernetes secret
-
+
## Sidecar to system services communication
@@ -73,15 +69,15 @@ When the Dapr sidecar initializes, it authenticates with the system pods using t
### mTLS to system services in Kubernetes
The diagram below shows secure communication between the Dapr sidecar and the Dapr Sentry (Certificate Authority), Placement (actor placement) and the Kubernetes Operator system services
-
+
## Component namespace scopes and secrets
-Dapr components are namespaced. That means a Dapr runtime sidecar instance can only access the components that have been deployed to the same namespace. See the [components scope topic](../../howto/components-scopes) for more details.
+Dapr components are namespaced. That means a Dapr runtime sidecar instance can only access the components that have been deployed to the same namespace. See the [components scope documentation]({{}}) for more details.
-Dapr components uses Dapr's built-in secret management capability to manage secrets. See the [secret topic](../secrets/README.md) for more details.
+Dapr components uses Dapr's built-in secret management capability to manage secrets. See the [secret store overview]({{}}) for more details.
-In addition, Dapr offers application-level scoping for components by allowing users to specify which applications can consume given components.For more information about application level scoping, see [here](../../howto/components-scopes#application-access-to-components-with-scopes)
+In addition, Dapr offers application-level scoping for components by allowing users to specify which applications can consume given components.For more information about application level scoping, see [here]({{}}).
## Network security
@@ -107,12 +103,14 @@ When deploying on Kubernetes, you can use regular [Kubernetes RBAC]( https://kub
When deploying on Azure Kubernetes Service (AKS), you can use [Azure Active Directory (AD) service principals]( https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals) to control access to management activities and resource management.
-## Threat Model
+## Threat model
Threat modeling is a process by which potential threats, such as structural vulnerabilities or the absence of appropriate safeguards, can be identified, enumerated, and mitigations can be prioritized. The Dapr threat model is below.
-
+
-## Security Audit June 2020
+## Security audit
+
+### June 2020
In June 2020, Dapr has undergone a security audit from Cure53, a CNCF approved cybersecurity firm.
The test focused on the following:
@@ -129,7 +127,7 @@ The test focused on the following:
* DoS attacks
* Penetration testing
-The full report can be found [here](./audits/DAP-01-report.pdf).
+The full report can be found [here](/docs/Dapr-july-2020-security-audit-report.pdf).
Two issues, one critical and one high, were fixed during the test.
As of July 21st 2020, Dapr has 0 criticals, 2 highs, 2 mediums, 1 low, 1 info.
diff --git a/daprdocs/content/en/contributing/_index.md b/daprdocs/content/en/contributing/_index.md
new file mode 100644
index 000000000..90e65ff01
--- /dev/null
+++ b/daprdocs/content/en/contributing/_index.md
@@ -0,0 +1,8 @@
+---
+type: docs
+title: "Contributing to Dapr"
+linkTitle: "Contributing"
+weight: 100
+description: >
+ How to contribute to the Dapr project
+---
diff --git a/daprdocs/content/en/contributing/contributing-docs.md b/daprdocs/content/en/contributing/contributing-docs.md
new file mode 100644
index 000000000..b4969ae22
--- /dev/null
+++ b/daprdocs/content/en/contributing/contributing-docs.md
@@ -0,0 +1,214 @@
+---
+type: docs
+title: "Docs contributions"
+linkTitle: "Docs"
+weight: 2000
+description: >
+ Guidelines for contributing to the Dapr Docs
+---
+
+This guide contains information about contributions to the [Dapr docs repository](https://github.com/dapr/docs). Please review the guidelines below before making a contribution to the Dapr docs. This guide assumes you have already reviewed the [general guidance]({{< ref contributing-overview>}}) which applies to any Dapr project contributions.
+
+Dapr docs are published to [docs.dapr.io](https://docs.dapr.io). Therefore, any contribution must ensure docs can be compiled and published correctly.
+
+## Prerequisites
+The Dapr docs are built using [Hugo](https://gohugo.io/) with the [Docsy](https://docsy.dev) theme. To verify docs are built correctly before submitting a contribution, you should setup your local environment to build and display the docs locally.
+
+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.
+
+## Style and tone
+These conventions should be followed throughout all Dapr documentation to ensure a consistent experience across all docs.
+
+- **Casing** - Use upper case only at the start of a sentence or for proper nouns including names of technologies (Dapr, Redis, Kubernetes etc.).
+- **Headers and titles** - Headers and titles must be descriptive and clear, use sentence casing i.e. use the above casing guidance for headers and titles too
+- **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.
+
+## 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).
+
+### Contributing a new concept doc
+- Ensure the reader can understand why they should care about this feature. What problems does it help them solve?
+- Ensure the doc references the spec for examples of using the API.
+- Ensure the spec is consistent with concept in terms of names, parameters and terminology. Update both the concept and the spec as needed.
+- Avoid just repeating the spec. The idea is to give the reader more information and background on the capability so that they can try this out. Hence provide more information and implementation details where possible.
+- Provide a link to the spec in the [Reference]({{}}) section.
+- Where possible reference a practical How-To doc.
+
+### Contributing a new How-To guide
+
+- `How To` articles are meant to provide step-by-step practical guidance on to readers who wish to enable a feature, integrate a technology or use Dapr in a specific scenario.
+- Sub directory naming - the directory name should be descriptive and if referring to specific component or concept should begin with the relevant name. Example *pubsub-namespaces*.
+- Do not assume the reader is using a specific environment unless the article itself is specific to an environment. This include OS (Windows/Linux/MacOS), deployment target (Kubernetes, IoT etc.) or programming language. If instructions vary between operating systems, provide guidance for all.
+- Include code/sample/config snippets that can be easily copied and pasted.
+- At the end of the article, provide the reader with related links and next steps (this can be other relevant "how-to", samples for reference or related concepts).
+
+## Requirements for docs.dapr.io
+Any contribution must ensure not to break the website build. The way Hugo builds the website requires following the below guidance.
+
+### Files and folder names
+File and folder names should be globally unique.
+ - `\service-invocation`
+ - `service-invocation-overview.md`
+
+### Front-matter
+[Front-matter](https://www.docsy.dev/docs/adding-content/content/#page-frontmatter) is what takes regular markdown files and upgrades them into Hugo compatible docs for rendering into the nav bars and ToCs.
+
+Every page needs a section at the top of the document like this:
+```yaml
+---
+type: docs
+title: "TITLE FOR THE PAGE"
+linkTitle: "SHORT TITLE FOR THE NAV BAR"
+weight: (number)
+description: "1+ SENTENCES DESCRIBING THE ARTICLE"
+---
+```
+
+#### Example
+```yaml
+---
+type: docs
+title: "Service invocation overview"
+linkTitle: "Overview"
+weight: 10
+description: "A quick overview of Dapr service invocation and how to use it to invoke services within your application"
+---
+```
+
+> Weight determines the order of the pages in the left sidebar, with 0 being the top-most.
+
+Front-matter should be completed with all fields including type, title, linkTitle, weight, and description.
+- `title` should be 1 sentence, no period at the end
+- `linkTitle` should be 1-3 words, with the exception of How-to at the front.
+- `description` should be 1-2 sentences on what the reader will learn, accomplish, or do in this doc.
+
+As per the [styling conventions](#styling-conventions), titles should only capitalize the first word and proper nouns, with the exception of "How-To:"
+ - "Getting started with Dapr service invocation"
+ - "How-To: Setup a local Redis instance"
+
+### Referencing other pages
+Hugo `ref` and `relref` [shortcodes](https://gohugo.io/content-management/cross-references/) are used to reference other pages and sections. It also allows the build to break if a page is incorrectly renamed or removed.
+
+This shortcode, written inline with the rest of the markdown page, will link to the _index.md of the section/folder name:
+```md
+{{}}
+```
+
+This shortcode will link to a specific page:
+```md
+{{}}
+```
+
+> Note that all pages and folders need to have globally unique names in order for the ref shortcode to work properly.
+
+### 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.
+
+Begin by placing images under `/daprdocs/static/images` with the naming convention of `[page-name]-[image-name].[png|jpg|svg]`.
+
+Then link to the image using:
+```md
+
+```
+
+>Don't forget to set the alt attribute to keep the docs readable for our visually impaired users.
+
+#### Example
+
+This HTML will display the `dapr-overview.png` image on the `overview.md` page:
+```md
+
+```
+
+### Tabbed Content
+Tabs are made possible through [Hugo shortcodes](https://gohugo.io/content-management/shortcodes/).
+
+The overall format is:
+```
+{{}}
+
+{{% codetab %}}
+[Content for Tab1]
+{{% /codetab %}}
+
+{{% codetab %}}
+[Content for Tab2]
+{{% /codetab %}}
+
+{{< /tabs */>}}
+```
+
+All content you author will be rendered to Markdown, so you can include images, code blocks, YouTube videos, and more.
+
+#### Example
+````
+{{}}
+
+{{% codetab %}}
+```powershell
+powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex"
+```
+{{% /codetab %}}
+
+{{% codetab %}}
+```bash
+wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash
+```
+{{% /codetab %}}
+
+{{% codetab %}}
+```bash
+brew install dapr/tap/dapr-cli
+```
+{{% /codetab %}}
+
+{{< /tabs */>}}
+````
+
+This example will render to this:
+
+{{< tabs Windows Linux MacOS>}}
+
+{{% codetab %}}
+```powershell
+powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex"
+```
+{{% /codetab %}}
+
+{{% codetab %}}
+```bash
+wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash
+```
+{{% /codetab %}}
+
+{{% codetab %}}
+```bash
+brew install dapr/tap/dapr-cli
+```
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+### YouTube Videos
+Hugo can automatically embed YouTube videos using a shortcode:
+```
+{{}}
+```
+
+#### Example
+
+Given the video https://youtu.be/dQw4w9WgXcQ
+
+The shortcode would be:
+```
+{{}}
+```
+
+### References
+- [Docsy authoring guide](https://www.docsy.dev/docs/adding-content/)
diff --git a/daprdocs/content/en/contributing/contributing-overview.md b/daprdocs/content/en/contributing/contributing-overview.md
new file mode 100644
index 000000000..cc9c81cd2
--- /dev/null
+++ b/daprdocs/content/en/contributing/contributing-overview.md
@@ -0,0 +1,69 @@
+---
+type: docs
+title: "Contribution overview"
+linkTitle: "Overview"
+weight: 1000
+description: >
+ General guidance for contributing to any of the Dapr project repositories
+---
+
+Thank you for your interest in Dapr!
+This document provides the guidelines for how to contribute to the [Dapr project](https://github.com/dapr) through issues and pull-requests. Contributions can also come in additional ways such as engaging with the community in community calls, commenting on issues or pull requests and more.
+
+See the [Dapr community repository](https://github.com/dapr/community) for more information on community engagement and community membership.
+
+> If you are looking to contribute to the Dapr docs, please also see the specific guidelines for [docs contributions]({{< ref contributing-docs >}}).
+
+## Issues
+
+### Issue types
+
+In most Dapr repositories there are usually 4 types of issues:
+
+- Issue/Bug: You've found a bug with the code, and want to report it, or create an issue to track the bug.
+- Issue/Discussion: You have something on your mind, which requires input form others in a discussion, before it eventually manifests as a proposal.
+- Issue/Proposal: Used for items that propose a new idea or functionality. This allows feedback from others before code is written.
+- Issue/Question: Use this issue type, if you need help or have a question.
+
+### Before submitting
+
+Before you submit an issue, make sure you've checked the following:
+
+1. Is it the right repository?
+ - The Dapr project is distributed across multiple repositories. Check the list of [repositories](https://github.com/dapr) if you aren't sure which repo is the correct one.
+1. Check for existing issues
+ - Before you create a new issue, please do a search in [open issues](https://github.com/dapr/dapr/issues) to see if the issue or feature request has already been filed.
+ - If you find your issue already exists, make relevant comments and add your [reaction](https://github.com/blog/2119-add-reaction-to-pull-requests-issues-and-comments). Use a reaction:
+ - 👍 up-vote
+ - 👎 down-vote
+1. For bugs
+ - Check it's not an environment issue. For example, if running on Kubernetes, make sure prerequisites are in place. (state stores, bindings, etc.)
+ - You have as much data as possible. This usually comes in the form of logs and/or stacktrace. If running on Kubernetes or other environment, look at the logs of the Dapr services (runtime, operator, placement service). More details on how to get logs can be found [here](https://github.com/dapr/docs/tree/master/best-practices/troubleshooting/logs.md).
+1. For proposals
+ - Many changes to the Dapr runtime may require changes to the API. In that case, the best place to discuss the potential feature is the main [Dapr repo](https://github.com/dapr/dapr).
+ - Other examples could include bindings, state stores or entirely new components.
+
+## Pull Requests
+
+All contributions come through pull requests. To submit a proposed change, follow this workflow:
+
+1. Make sure there's an issue (bug or proposal) raised, which sets the expectations for the contribution you are about to make.
+1. Fork the relevant repo and create a new branch
+1. Create your change
+ - Code changes require tests
+1. Update relevant documentation for the change
+1. Commit and open a PR
+1. Wait for the CI process to finish and make sure all checks are green
+1. A maintainer of the project will be assigned, and you can expect a review within a few days
+
+#### Use work-in-progress PRs for early feedback
+
+A good way to communicate before investing too much time is to create a "Work-in-progress" PR and share it with your reviewers. The standard way of doing this is to add a "[WIP]" prefix in your PR's title and assign the **do-not-merge** label. This will let people looking at your PR know that it is not well baked yet.
+
+### Use of Third-party code
+
+- Third-party code must include licenses.
+
+## Code of Conduct
+
+Please see the [Dapr community code of conduct](https://github.com/dapr/community/blob/master/CODE-OF-CONDUCT.md).
diff --git a/daprdocs/content/en/developing-applications/_index.md b/daprdocs/content/en/developing-applications/_index.md
new file mode 100644
index 000000000..6e08c928b
--- /dev/null
+++ b/daprdocs/content/en/developing-applications/_index.md
@@ -0,0 +1,7 @@
+---
+type: docs
+title: "Developing applications with Dapr"
+linkTitle: "Developing applications"
+description: "Tools, tips, and information on how to build your application with Dapr"
+weight: 30
+---
diff --git a/daprdocs/content/en/developing-applications/building-blocks/_index.md b/daprdocs/content/en/developing-applications/building-blocks/_index.md
new file mode 100644
index 000000000..8117c1884
--- /dev/null
+++ b/daprdocs/content/en/developing-applications/building-blocks/_index.md
@@ -0,0 +1,11 @@
+---
+type: docs
+title: "Building blocks"
+linkTitle: "Building blocks"
+weight: 10
+description: "Dapr capabilities that solve common development challenges for distributed applications"
+---
+
+Get a high-level [overview of Dapr building blocks]({{< ref building-blocks-concept >}}) in the **Concepts** section.
+
+
\ No newline at end of file
diff --git a/daprdocs/content/en/developing-applications/building-blocks/actors/_index.md b/daprdocs/content/en/developing-applications/building-blocks/actors/_index.md
new file mode 100644
index 000000000..d3ae80d32
--- /dev/null
+++ b/daprdocs/content/en/developing-applications/building-blocks/actors/_index.md
@@ -0,0 +1,7 @@
+---
+type: docs
+title: "Actors"
+linkTitle: "Actors"
+weight: 50
+description: Encapsulate code and data in reusable actor objects as a common microservices design pattern
+---
diff --git a/concepts/actors/README.md b/daprdocs/content/en/developing-applications/building-blocks/actors/actors-background.md
similarity index 92%
rename from concepts/actors/README.md
rename to daprdocs/content/en/developing-applications/building-blocks/actors/actors-background.md
index 77c04b935..23efc59d1 100644
--- a/concepts/actors/README.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/actors/actors-background.md
@@ -1,4 +1,10 @@
-# Introduction to actors
+---
+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.
@@ -10,15 +16,8 @@ Dapr includes a runtime that specifically implements the [Virtual Actor pattern]
## Quick links
-- [Dapr Actor Features](./actors_features.md)
-- [Dapr Actor API Spec](../../reference/api/actors_api.md)
-
-## Contents
-
-- [Actors in Dapr](#actors-in-dapr)
-- [Actor Lifetime](#actor-lifetime)
-- [Distribution and Failover](#distribution-and-failover)
-- [Actor Communication](#actor-communication)
+- [Dapr Actor Features]({{< ref actors-overview.md >}})
+- [Dapr Actor API Spec]({{< ref actors_api.md >}} )
### When to use actors
@@ -34,7 +33,7 @@ The actor design pattern can be a good fit to a number of distributed systems pr
Every actor is defined as an instance of an actor type, identical to the way an object is an instance of a class. For example, there may be an actor type that implements the functionality of a calculator and there could be many actors of that type that are distributed on various nodes across a cluster. Each such actor is uniquely identified by an actor ID.
-
+
## Actor lifetime
@@ -57,11 +56,11 @@ Actors are distributed across the instances of the actor service, and those inst
### 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.
-
+
When a client calls an actor with a particular id (for example, actor id 123), the Dapr instance for the client hashes the actor type and id, and uses the information to call onto the corresponding Dapr instance that can serve the requests for that particular actor id. As a result, the same partition (or service instance) is always called for any given actor id. This is shown in the diagram below.
-
+
This simplifies some choices but also carries some consideration:
@@ -80,7 +79,7 @@ POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/
+
### Turn-based access
@@ -100,4 +100,5 @@ The Dapr actors runtime enforces turn-based concurrency by acquiring a per-actor
The following example illustrates the above concepts. Consider an actor type that implements two asynchronous methods (say, Method1 and Method2), a timer, and a reminder. The diagram below shows an example of a timeline for the execution of these methods and callbacks on behalf of two actors (ActorId1 and ActorId2) that belong to this actor type.
-
+
+
diff --git a/concepts/actors/actors_features.md b/daprdocs/content/en/developing-applications/building-blocks/actors/actors-overview.md
similarity index 90%
rename from concepts/actors/actors_features.md
rename to daprdocs/content/en/developing-applications/building-blocks/actors/actors-overview.md
index 71e1e05e4..a342db3d3 100644
--- a/concepts/actors/actors_features.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/actors/actors-overview.md
@@ -1,10 +1,12 @@
-# Dapr actors runtime
+---
+type: docs
+title: "Dapr actors overview"
+linkTitle: "Overview"
+weight: 10
+description: Overview of Dapr support for actors
+---
-The Dapr actors runtime provides following capabilities:
-
-- [Method Invocation](#actor-method-invocation)
-- [State Management](#actor-state-management)
-- [Timers and Reminders](#actor-timers-and-reminders)
+The Dapr actors runtime provides support for [virtual actors]({{< ref actors-background.md >}}) through following capabilities:
## Actor method invocation
@@ -16,7 +18,7 @@ POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/
### How to configure a liveness probe in Kubernetes
@@ -78,6 +84,6 @@ readinessProbe:
For more information refer to;
-- [ Endpoint health API](../../reference/api/health_api.md)
-- [Actor health API](../../reference/api/actors_api.md#health-check)
+- [ Endpoint health API]({{< ref health_api.md >}})
+- [Actor health API]({{< ref "actors_api.md#health-check" >}})
- [Kubernetes probe configuration parameters](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/)
diff --git a/concepts/observability/traces.md b/daprdocs/content/en/developing-applications/building-blocks/observability/tracing.md
similarity index 80%
rename from concepts/observability/traces.md
rename to daprdocs/content/en/developing-applications/building-blocks/observability/tracing.md
index c510b3fa0..c31e15e28 100644
--- a/concepts/observability/traces.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/observability/tracing.md
@@ -1,17 +1,14 @@
-# Distributed Tracing
+---
+type: docs
+title: "Distributed tracing"
+linkTitle: "Distributed tracing"
+weight: 1000
+description: "Use Dapr tracing to get visibility for distributed application"
+---
Dapr uses OpenTelemetry (previously known as OpenCensus) for distributed traces and metrics collection. OpenTelemetry supports various backends including [Azure Monitor](https://azure.microsoft.com/en-us/services/monitor/), [Datadog](https://www.datadoghq.com), [Instana](https://www.instana.com), [Jaeger](https://www.jaegertracing.io/), [SignalFX](https://www.signalfx.com/), [Stackdriver](https://cloud.google.com/stackdriver), [Zipkin](https://zipkin.io) and others.
-
-
-## Contents
-
-- [Distributed Tracing](#distributed-tracing)
- - [Contents](#contents)
- - [Tracing design](#tracing-design)
- - [W3C Correlation ID](#w3c-correlation-id)
- - [Configuration](#configuration)
- - [References](#references)
+
## Tracing design
@@ -26,7 +23,7 @@ Dapr adds a HTTP/gRPC middleware to the Dapr sidecar. The middleware intercepts
Dapr uses the standard W3C Trace Context headers. For HTTP requests, Dapr uses `traceparent` header. For gRPC requests, Dapr uses `grpc-trace-bin` header. When a request arrives without a trace ID, Dapr creates a new one. Otherwise, it passes the trace ID along the call chain.
-Read [W3C Tracing Context for distributed tracing](./W3C-traces.md) for more background on W3C Trace Context.
+Read [W3C distributed tracing]({{< ref w3c-tracing >}}) for more background on W3C Trace Context.
## Configuration
@@ -68,6 +65,6 @@ spec:
## References
-* [How-To: Set up Application Insights distributed tracing with OpenTelemetry Collector](../../howto/diagnose-with-tracing/open-telemetry-collector.md)
-* [How-To: Set up Zipkin for distributed tracing](../../howto/diagnose-with-tracing/zipkin.md)
-* [How-To: Use W3C Trace Context for distributed tracing](../../howto/use-w3c-tracecontext/README.md)
+- [How-To: Setup Application Insights for distributed tracing with OpenTelemetry Collector]({{< ref open-telemetry-collector.md >}})
+- [How-To: Set up Zipkin for distributed tracing]({{< ref zipkin.md >}})
+- [W3C distributed tracing]({{< ref w3c-tracing >}})
diff --git a/daprdocs/content/en/developing-applications/building-blocks/observability/w3c-tracing/_index.md b/daprdocs/content/en/developing-applications/building-blocks/observability/w3c-tracing/_index.md
new file mode 100644
index 000000000..0c18e1f2a
--- /dev/null
+++ b/daprdocs/content/en/developing-applications/building-blocks/observability/w3c-tracing/_index.md
@@ -0,0 +1,8 @@
+---
+type: docs
+title: "W3C trace context"
+linkTitle: "W3C trace context"
+weight: 1000
+description: Background and scenarios for using W3C tracing with Dapr
+type: docs
+---
\ No newline at end of file
diff --git a/howto/use-w3c-tracecontext/README.md b/daprdocs/content/en/developing-applications/building-blocks/observability/w3c-tracing/w3c-tracing-howto.md
similarity index 80%
rename from howto/use-w3c-tracecontext/README.md
rename to daprdocs/content/en/developing-applications/building-blocks/observability/w3c-tracing/w3c-tracing-howto.md
index b19bb7741..2cf0026bf 100644
--- a/howto/use-w3c-tracecontext/README.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/observability/w3c-tracing/w3c-tracing-howto.md
@@ -1,20 +1,16 @@
+---
+type: docs
+title: "How-To: Use W3C trace context with Dapr"
+linkTitle: "How-To: Use W3C trace context"
+weight: 20000
+description: Using W3C tracing standard with Dapr
+type: docs
+---
+
# How to use trace context
-Dapr uses W3C trace context for distributed tracing for both service invocation and pub/sub messaging. Dapr does all the heavy lifting of generating and propagating the trace context information and there are very few cases where you need to either propagate or create a trace context. First read scenarios in the [W3C trace context for distributed tracing](../../concepts/observability/W3C-traces.md) article to understand whether you need to propagate or create a trace context.
+Dapr uses W3C trace context for distributed tracing for both service invocation and pub/sub messaging. Dapr does all the heavy lifting of generating and propagating the trace context information and there are very few cases where you need to either propagate or create a trace context. First read scenarios in the [W3C distributed tracing]({{< ref w3c-tracing >}}) article to understand whether you need to propagate or create a trace context.
-To view traces, read the [how to diagnose with tracing](../diagnose-with-tracing) article.
-
-## Contents
-- [How to retrieve trace context from a response](#how-to-retrieve-trace-context-from-a-response)
-- [How to propagate trace context in a request](#how-to-propagate-trace-context-in-a-request)
-- [How to create trace context](#how-to-create-trace-context)
- - [Go](#create-trace-context-in-go)
- - [Java](#create-trace-context-in-java)
- - [Python](#create-trace-context-in-python)
- - [NodeJS](#create-trace-context-in-nodejs)
- - [C++](#create-trace-context-in-c++)
- - [C#](#create-trace-context-in-c#)
-- [Putting it all together with a Go Sample](#putting-it-all-together-with-a-go-sample)
-- [Related Links](#related-links)
+To view traces, read the [how to diagnose with tracing]({{< ref tracing.md >}}) article.
## How to retrieve trace context from a response
`Note: There are no helper methods exposed in Dapr SDKs to propagate and retrieve trace context. You need to use http/gRPC clients to propagate and retrieve trace headers through http headers and gRPC metadata.`
@@ -102,8 +98,8 @@ f.SpanContextToRequest(traceContext, req)
traceContext := span.SpanContext()
traceContextBinary := propagation.Binary(traceContext)
```
-
-You can then pass the trace context through [gRPC metadata]("google.golang.org/grpc/metadata") through `grpc-trace-bin` header.
+
+You can then pass the trace context through [gRPC metadata](https://google.golang.org/grpc/metadata) through `grpc-trace-bin` header.
```go
ctx = metadata.AppendToOutgoingContext(ctx, "grpc-trace-bin", string(traceContextBinary))
@@ -219,7 +215,7 @@ In Kubernetes, you can apply the configuration as below :
kubectl apply -f appconfig.yaml
```
-You then set the following tracing annotation in your deployment YAML. You can add the following annotaion in sample [grpc app](../create-grpc-app) deployment yaml.
+You then set the following tracing annotation in your deployment YAML. You can add the following annotaion in sample [grpc app]({{< ref grpc.md >}}) deployment yaml.
```yaml
dapr.io/config: "appconfig"
@@ -227,13 +223,13 @@ dapr.io/config: "appconfig"
### Invoking Dapr with trace context
-As mentioned in `Scenarios` section in [W3C Trace Context for distributed tracing](../../concepts/observability/W3C-traces.md) that Dapr covers generating trace context and you do not need to explicitly create trace context.
+Dapr covers generating trace context and you do not need to explicitly create trace context.
However if you choose to pass the trace context explicitly, then Dapr will use the passed trace context and propagate all across the HTTP/gRPC call.
-Using the [grpc app](../create-grpc-app) in the example and putting this all together, the following steps show you how to create a Dapr client and call the InvokeService method passing the trace context:
+Using the [grpc app]({{< ref grpc.md >}}) in the example and putting this all together, the following steps show you how to create a Dapr client and call the InvokeService method passing the trace context:
-The Rest code snippet and details, refer to the [grpc app](../create-grpc-app).
+The Rest code snippet and details, refer to the [grpc app]({{< ref grpc >}}).
### 1. Import the package
@@ -293,9 +289,9 @@ You can now correlate the calls in your app and across services with Dapr using
## Related Links
-* [Observability concepts](../../concepts/observability/traces.md)
-* [W3C Trace Context for distributed tracing](../../concepts/observability/W3C-traces.md)
-* [How to set up Application Insights distributed tracing with OpenTelemetry Collector](../../howto/diagnose-with-tracing/open-telemetry-collector.md)
-* [How to set up Zipkin for distributed tracing](../../howto/diagnose-with-tracing/zipkin.md)
-* [W3C trace context specification](https://www.w3.org/TR/trace-context/)
-* [Observability quickstart](https://github.com/dapr/quickstarts/tree/master/observability)
+- [Observability concepts]({{< ref observability-concept.md >}})
+- [W3C Trace Context for distributed tracing]({{< ref w3c-tracing >}})
+- [How To set up Application Insights for distributed tracing with OpenTelemetry]({{< ref open-telemetry-collector.md >}})
+- [How to set up Zipkin for distributed tracing]({{< ref zipkin.md >}})
+- [W3C trace context specification](https://www.w3.org/TR/trace-context/)
+- [Observability quickstart](https://github.com/dapr/quickstarts/tree/master/observability)
diff --git a/concepts/observability/W3C-traces.md b/daprdocs/content/en/developing-applications/building-blocks/observability/w3c-tracing/w3c-tracing-overview.md
similarity index 92%
rename from concepts/observability/W3C-traces.md
rename to daprdocs/content/en/developing-applications/building-blocks/observability/w3c-tracing/w3c-tracing-overview.md
index f365f0724..56ca62057 100644
--- a/concepts/observability/W3C-traces.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/observability/w3c-tracing/w3c-tracing-overview.md
@@ -1,8 +1,11 @@
-# W3C trace context for distributed tracing
-
-- [Background](#background)
-- [Trace scenarios](#scenarios)
-- [W3C trace headers](#w3c-trace-headers)
+---
+type: docs
+title: "W3C trace context overview"
+linkTitle: "Overview"
+weight: 10000
+description: Background and scenarios for using W3C tracing with Dapr
+type: docs
+---
## Introduction
Dapr uses W3C trace context for distributed tracing for both service invocation and pub/sub messaging. Largely Dapr does all the heavy lifting of generating and propogating the trace context information and this can be sent to many different diagnostics tools for visualization and querying. There are only a very few cases where you, as a developer, need to either propagate a trace header or generate one.
@@ -28,7 +31,7 @@ This transformation of modern applications called for a distributed tracing cont
A unified approach for propagating trace data improves visibility into the behavior of distributed applications, facilitating problem and performance analysis.
## Scenarios
-There are two scenarios where you need to understand how tracing is used;
+There are two scenarios where you need to understand how tracing is used:
1. Dapr generates and propagates the trace context between services.
2. Dapr generates the trace context and you need to propagate the trace context to another service **or** you generate the trace context and Dapr propagates the trace context to a service.
@@ -66,7 +69,7 @@ In these scenarios Dapr does some of the work for you and you need to either cre
In this case, when service A first calls service B, Dapr generates the trace headers in service A, and these trace headers are then propagated to service B. These trace headers are returned in the response from service B as part of response headers. However you need to propagate the returned trace context to the next services, service C and Service D, as Dapr does not know you want to reuse the same header.
- To understand how to extract the trace headers from a response and add the trace headers into a request, see the [how to use trace context](../../howto/use-w3c-tracecontext/README.md) article.
+ To understand how to extract the trace headers from a response and add the trace headers into a request, see the [how to use trace context]({{< ref w3c-tracing >}}) article.
2. You have chosen to generate your own trace context headers.
This is much more unusual. There may be occassions where you specifically chose to add W3C trace headers into a service call, for example if you have an existing application that does not currently use Dapr. In this case Dapr still propagates the trace context headers for you. If you decide to generate trace headers yourself, there are three ways this can be done :
@@ -102,8 +105,7 @@ The tracestate fields are detailed [here](https://www.w3.org/TR/trace-context/#t
In the gRPC API calls, trace context is passed through `grpc-trace-bin` header.
## Related Links
-* [How To set up Application Insights using OpenTelemetry Collector](../../howto/diagnose-with-tracing/open-telemetry-collector.md)
-* [How To set up Zipkin for distributed tracing](../../howto/diagnose-with-tracing/zipkin.md)
-* [How to use Trace Context](../../howto/use-w3c-tracecontext)
-* [W3C trace context specification](https://www.w3.org/TR/trace-context/)
-* [Observability sample](https://github.com/dapr/quickstarts/tree/master/observability)
+- [How To set up Application Insights for distributed tracing with OpenTelemetry]({{< ref open-telemetry-collector.md >}})
+- [How To set up Zipkin for distributed tracing]({{< ref zipkin.md >}})
+- [W3C trace context specification](https://www.w3.org/TR/trace-context/)
+- [Observability sample](https://github.com/dapr/quickstarts/tree/master/observability)
diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/_index.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/_index.md
new file mode 100644
index 000000000..a6c894a5a
--- /dev/null
+++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/_index.md
@@ -0,0 +1,7 @@
+---
+type: docs
+title: "Publish & subscribe messaging"
+linkTitle: "Publish & subscribe"
+weight: 30
+description: Secure, scalable messaging between services
+---
diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md
new file mode 100644
index 000000000..05a46f8fb
--- /dev/null
+++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md
@@ -0,0 +1,341 @@
+---
+type: docs
+title: "How-To: Publish a message and subscribe to a topic"
+linkTitle: "How-To: Publish & subscribe"
+weight: 2000
+description: "Learn how to send messages to a topic with one service and subscribe to that topic in another service"
+---
+
+## Introduction
+
+Pub/Sub is a common pattern in a distributed system with many services that want to utilize decoupled, asynchronous messaging.
+Using Pub/Sub, you can enable scenarios where event consumers are decoupled from event producers.
+
+Dapr provides an extensible Pub/Sub system with At-Least-Once guarantees, allowing developers to publish and subscribe to topics.
+Dapr provides different implementation of the underlying system, and allows operators to bring in their preferred infrastructure, for example Redis Streams, Kafka, etc.
+
+## Step 1: Setup the Pub/Sub component
+
+The first step is to setup the Pub/Sub component:
+
+{{< tabs "Self-Hosted (CLI)" Kubernetes >}}
+
+{{% codetab %}}
+Redis Streams is installed by default on a local machine when running `dapr init`.
+
+Verify by opening your components file under `%UserProfile%\.dapr\components\pubsub.yaml` on Windows or `~/.dapr/components/pubsub.yaml` on Linux/MacOS:
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+ name: pubsub
+spec:
+ type: pubsub.redis
+ metadata:
+ - name: redisHost
+ value: localhost:6379
+ - name: redisPassword
+ value: ""
+```
+
+You can override this file with another Redis instance or another [pubsub component]({{< ref setup-pubsub >}}) by creating a `components` directory containing the file and using the flag `--components-path` with the `dapr run` CLI command.
+{{% /codetab %}}
+
+{{% codetab %}}
+To deploy this into a Kubernetes cluster, fill in the `metadata` connection details of your [desired pubsub component]({{< ref setup-pubsub >}}) in the yaml below, save as `pubsub.yaml`, and run `kubectl apply -f pubsub.yaml`.
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+ name: pubsub
+ namespace: default
+spec:
+ type: pubsub.redis
+ metadata:
+ - name: redisHost
+ value: localhost:6379
+ - name: redisPassword
+ value: ""
+```
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+
+## 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
+
+### Declarative subscriptions
+
+You can subscribe to a topic using the following Custom Resources Definition (CRD). Create a file named `subscription.yaml` and paste the following:
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Subscription
+metadata:
+ name: myevent-subscription
+spec:
+ topic: deathStarStatus
+ route: /dsstatus
+ pubsubname: pubsub
+scopes:
+- app1
+- app2
+```
+
+The example above shows an event subscription to topic `deathStarStatus`, for the pubsub component `pubsub`.
+- The `route` field tells Dapr to send all topic messages to the `/dsstatus` endpoint in the app.
+- The `scopes` field enables this subscription for apps with IDs `app1` and `app2`.
+
+Set the component with:
+{{< tabs "Self-Hosted (CLI)" Kubernetes>}}
+
+{{% codetab %}}
+Place the CRD in your `./components` directory. When Dapr starts up, it will load subscriptions along with components.
+
+*Note: By default, Dapr loads components from `$HOME/.dapr/components` on MacOS/Linux and `%USERPROFILE%\.dapr\components` on Windows.*
+
+You can also override the default directory by pointing the Dapr CLI to a components path:
+
+```bash
+dapr run --app-id myapp --components-path ./myComponents -- python3 app1.py
+```
+
+*Note: If you place the subscription in a custom components path, make sure the Pub/Sub component is present also.*
+
+{{% /codetab %}}
+
+{{% codetab %}}
+In Kubernetes, save the CRD to a file and apply it to the cluster:
+
+```bash
+kubectl apply -f subscription.yaml
+```
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+#### Example
+
+{{< tabs Python Node>}}
+
+{{% codetab %}}
+Create a file named `app1.py` and paste in the following:
+```python
+import flask
+from flask import request, jsonify
+from flask_cors import CORS
+import json
+import sys
+
+app = flask.Flask(__name__)
+CORS(app)
+
+@app.route('/dsstatus', methods=['POST'])
+def ds_subscriber():
+ print(request.json, flush=True)
+ return json.dumps({'success':True}), 200, {'ContentType':'application/json'}
+
+app.run()
+```
+After creating `app1.py` ensute flask and flask_cors are installed:
+
+```bash
+pip install flask
+pip install flask_cors
+```
+
+Then run:
+
+```bash
+dapr --app-id app1 --app-port 5000 run python app1.py
+```
+{{% /codetab %}}
+
+{{% codetab %}}
+After setting up the subscription above, download this javascript (Node > 4.16) into a `app2.js` file:
+
+```javascript
+const express = require('express')
+const bodyParser = require('body-parser')
+const app = express()
+app.use(bodyParser.json({ type: 'application/*+json' }));
+
+const port = 3000
+
+app.post('/dsstatus', (req, res) => {
+ console.log(req.body);
+ res.sendStatus(200);
+});
+
+app.listen(port, () => console.log(`consumer app listening on port ${port}!`))
+```
+Run this app with:
+
+```bash
+dapr --app-id app2 --app-port 3000 run node app2.js
+```
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+### Programmatic subscriptions
+
+To subscribe to topics, start a web server in the programming language of your choice and listen on the following `GET` endpoint: `/dapr/subscribe`.
+The Dapr instance will call into your app at startup and expect a JSON response for the topic subscriptions with:
+- `pubsubname`: Which pub/sub component Dapr should use
+- `topic`: Which topic to subscribe to
+- `route`: Which endpoint for Dapr to call on when a message comes to that topic
+
+#### Example
+
+{{< tabs Python Node>}}
+
+{{% codetab %}}
+```python
+import flask
+from flask import request, jsonify
+from flask_cors import CORS
+import json
+import sys
+
+app = flask.Flask(__name__)
+CORS(app)
+
+@app.route('/dapr/subscribe', methods=['GET'])
+def subscribe():
+ subscriptions = [{'pubsubname': 'pubsub',
+ 'topic': 'deathStarStatus',
+ 'route': 'dsstatus'}]
+ return jsonify(subscriptions)
+
+@app.route('/dsstatus', methods=['POST'])
+def ds_subscriber():
+ print(request.json, flush=True)
+ return json.dumps({'success':True}), 200, {'ContentType':'application/json'}
+app.run()
+```
+After creating `app1.py` ensute flask and flask_cors are installed:
+
+```bash
+pip install flask
+pip install flask_cors
+```
+
+Then run:
+
+```bash
+dapr --app-id app1 --app-port 5000 run python app1.py
+```
+{{% /codetab %}}
+
+{{% codetab %}}
+```javascript
+const express = require('express')
+const bodyParser = require('body-parser')
+const app = express()
+app.use(bodyParser.json({ type: 'application/*+json' }));
+
+const port = 3000
+
+app.get('/dapr/subscribe', (req, res) => {
+ res.json([
+ {
+ pubsubname: "pubsub",
+ topic: "deathStarStatus",
+ route: "dsstatus"
+ }
+ ]);
+})
+
+app.post('/dsstatus', (req, res) => {
+ console.log(req.body);
+ res.sendStatus(200);
+});
+
+app.listen(port, () => console.log(`consumer app listening on port ${port}!`))
+```
+Run this app with:
+
+```bash
+dapr --app-id app2 --app-port 3000 run node app2.js
+```
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+The `/dsstatus` endpoint matches the `route` defined in the subscriptions and this is where Dapr will send all topic messages to.
+
+## Step 3: Publish a topic
+
+To publish a message to a topic, invoke the following endpoint on a Dapr instance:
+
+{{< tabs "Dapr CLI" "HTTP API (Bash)" "HTTP API (PowerShell)">}}
+
+{{% codetab %}}
+```bash
+dapr publish --pubsub pubsub --topic deathStarStatus --data '{"status": "completed"}'
+```
+{{% /codetab %}}
+
+{{% codetab %}}
+Begin by ensuring a Dapr sidecar is running:
+```bash
+dapr --app-id myapp --port 3500 run
+```
+Then publish a message to the `deathStarStatus` topic:
+```bash
+curl -X POST http://localhost:3500/v1.0/publish/pubsub/deathStarStatus -H "Content-Type: application/json" -d '{"status": "completed"}'
+```
+{{% /codetab %}}
+
+{{% codetab %}}
+Begin by ensuring a Dapr sidecar is running:
+```bash
+dapr --app-id myapp --port 3500 run
+```
+Then publish a message to the `deathStarStatus` topic:
+```powershell
+Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '{"status": "completed"}' -Uri 'http://localhost:3500/v1.0/publish/pubsub/deathStarStatus'
+```
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+Dapr automatically wraps the user payload in a Cloud Events v1.0 compliant envelope.
+
+## Step 4: ACK-ing a message
+
+In order to tell Dapr that a message was processed successfully, return a `200 OK` response. If Dapr receives any other return status code than `200`, or if your app crashes, Dapr will attempt to redeliver the message following At-Least-Once semantics.
+
+#### Example
+
+{{< tabs Python Node>}}
+
+{{% codetab %}}
+```python
+@app.route('/dsstatus', methods=['POST'])
+def ds_subscriber():
+ print(request.json, flush=True)
+ return json.dumps({'success':True}), 200, {'ContentType':'application/json'}
+```
+{{% /codetab %}}
+
+{{% codetab %}}
+```javascript
+app.post('/dsstatus', (req, res) => {
+ res.sendStatus(200);
+});
+```
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+## Next steps
+- [Scope access to your pub/sub topics]({{< ref pubsub-scopes.md >}})
+- [Pub/Sub quickstart](https://github.com/dapr/quickstarts/tree/master/pub-sub)
+- [Pub/sub components]({{< ref setup-pubsub >}})
\ No newline at end of file
diff --git a/concepts/publish-subscribe-messaging/README.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md
similarity index 74%
rename from concepts/publish-subscribe-messaging/README.md
rename to daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md
index 75874f7dd..78f98e01f 100644
--- a/concepts/publish-subscribe-messaging/README.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md
@@ -1,4 +1,12 @@
-# Publish/Subscribe Messaging
+---
+type: docs
+title: "Publish and subscribe overview"
+linkTitle: "Overview"
+weight: 1000
+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.
@@ -6,41 +14,37 @@ Similarly, a **consumer** will receive messages from a topic without knowledge o
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).
-## Publish/Subscribe API
+## Features
-The API for Publish/Subscribe can be found in the [spec repo](../../reference/api/pubsub_api.md).
+### Publish/Subscribe API
-## Behavior and guarantees
+The API for Publish/Subscribe can be found in the [spec repo]({{< ref pubsub_api.md >}}).
+
+### 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, 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.
+### Consumer groups and multiple instances
+
The burden of dealing with concepts like consumer groups and multiple instances inside consumer groups is all catered for by Dapr.
-### App ID
-
-Dapr has the concept of an `id`. This is specified in Kubernetes using the `dapr.io/app-id` annotation and with the `app-id` flag using the Dapr CLI. Dapr requires an ID to be assigned to every application.
-
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
+### 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)
-
+- `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.
The following example shows an XML content in CloudEvent v1.0 serialized as JSON:
-
-
```json
{
"specversion" : "1.0",
@@ -53,3 +57,12 @@ The following example shows an XML content in CloudEvent v1.0 serialized as JSON
"data" : "
+
Applications can use the secrets API to access secrets from a Kubernetes secret store. In the example below, the application retrieves the same secret "mysecret" from a Kubernetes secret store.
-
+
In Azure Dapr can be configured to use Managed Identities to authenticate with Azure Key Vault in order to retrieve secrets. In the example below, an Azure Kubernetes Service (AKS) cluster is configured to use managed identities. Then Dapr uses [pod identities](https://docs.microsoft.com/en-us/azure/aks/operator-best-practices-identity#use-pod-identities) to retrieve secrets from Azure Key Vault on behalf of the application.
-
+
Notice that in all of the examples above the application code did not have to change to get the same secret. Dapr did all the heavy lifting here via the secrets building block API and using the secret components.
diff --git a/howto/secrets-scopes/README.md b/daprdocs/content/en/developing-applications/building-blocks/secrets/secrets-scopes.md
similarity index 75%
rename from howto/secrets-scopes/README.md
rename to daprdocs/content/en/developing-applications/building-blocks/secrets/secrets-scopes.md
index ef1a307ef..465621fc0 100644
--- a/howto/secrets-scopes/README.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/secrets/secrets-scopes.md
@@ -1,10 +1,17 @@
-# Limit the secrets that can be read from secret stores
+---
+type: docs
+title: "How To: Use secret scoping"
+linkTitle: "How To: Use secret scoping"
+weight: 3000
+description: "Use scoping to limit the secrets that can be read from secret stores"
+type: docs
+---
-Follow [these instructions](../setup-secret-store) to configure secret store for an application. Once configured, any secret defined within that store will be accessible from the Dapr application.
+Follow [these instructions]({{< ref setup-secret-store >}}) to configure secret store for an application. Once configured, any secret defined within that store will be accessible from the Dapr application.
To limit the secrets to which the Dapr application has access, users can define secret scopes by augmenting existing configuration CRD with restrictive permissions.
-Follow [these instructions](../../concepts/configuration/README.md) to define a configuration CRD.
+Follow [these instructions]({{< ref configuration-concept.md >}}) to define a configuration CRD.
## Scenario 1 : Deny access to all secrets for a secret store
@@ -24,7 +31,7 @@ spec:
defaultAccess: deny
```
-For applications that need to be deined access to the Kubernetes secret store, follow [these instructions](../configure-k8s/README.md), and add the following annotation to the application pod.
+For applications that need to be deined access to the Kubernetes secret store, follow [these instructions]({{< ref kubernetes-overview.md >}}), and add the following annotation to the application pod.
```yaml
dapr.io/config: appconfig
@@ -49,7 +56,7 @@ spec:
allowedSecrets: ["secret1", "secret2"]
```
-This example defines configuration for secret store named vault. The default access to the secret store is `deny`, whereas some secrets are accessible by the application based on the `allowedSecrets` list. Follow [these instructions](../../concepts/configuration/README.md) to apply configuration to the sidecar.
+This example defines configuration for secret store named vault. The default access to the secret store is `deny`, whereas some secrets are accessible by the application based on the `allowedSecrets` list. Follow [these instructions]({{< ref configuration-concept.md >}}) to apply configuration to the sidecar.
## Scenario 3: Deny access to certain senstive secrets in a secret store
@@ -68,7 +75,7 @@ spec:
deniedSecrets: ["secret1", "secret2"]
```
-The above configuration explicitly denies access to `secret1` and `secret2` from the secret store named vault while allowing access to all other secrets. Follow [these instructions](../../concepts/configuration/README.md) to apply configuration to the sidecar.
+The above configuration explicitly denies access to `secret1` and `secret2` from the secret store named vault while allowing access to all other secrets. Follow [these instructions]({{< ref configuration-concept.md >}}) to apply configuration to the sidecar.
## Permission priority
diff --git a/daprdocs/content/en/developing-applications/building-blocks/service-invocation/_index.md b/daprdocs/content/en/developing-applications/building-blocks/service-invocation/_index.md
new file mode 100644
index 000000000..011c8b2e4
--- /dev/null
+++ b/daprdocs/content/en/developing-applications/building-blocks/service-invocation/_index.md
@@ -0,0 +1,7 @@
+---
+type: docs
+title: "Service invocation"
+linkTitle: "Service invocation"
+weight: 10
+description: Perform direct, secure, service-to-service method calls
+---
diff --git a/howto/invoke-and-discover-services/README.md b/daprdocs/content/en/developing-applications/building-blocks/service-invocation/howto-invoke-discover-services.md
similarity index 59%
rename from howto/invoke-and-discover-services/README.md
rename to daprdocs/content/en/developing-applications/building-blocks/service-invocation/howto-invoke-discover-services.md
index e0067cca4..8c81b689c 100644
--- a/howto/invoke-and-discover-services/README.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/service-invocation/howto-invoke-discover-services.md
@@ -1,15 +1,20 @@
-# Get started with HTTP service invocation
+---
+type: docs
+title: "How-To: Invoke and discover services"
+linkTitle: "How-To: Invoke services"
+description: "How-to guide on how to use Dapr service invocation in a distributed application"
+weight: 2000
+---
This article describe how to deploy services each with an unique application ID, so that other services can discover and call endpoints on them using service invocation API.
-## 1. Choose an ID for your service
+## Step 1: Choose an ID for your service
-Dapr allows you to assign a global, unique ID for your app.
+Dapr allows you to assign a global, unique ID for your app. This ID encapsulates the state for your application, regardless of the number of instances it may have.
-This ID encapsulates the state for your application, regardless of the number of instances it may have.
-
-### Setup an ID using the Dapr CLI
+{{< tabs "Self-Hosted (CLI)" Kubernetes >}}
+{{% codetab %}}
In self hosted mode, set the `--app-id` flag:
```bash
@@ -21,8 +26,9 @@ If your app uses an SSL connection, you can tell Dapr to invoke your app over an
```bash
dapr run --app-id cart --app-port 5000 --app-ssl python app.py
```
+{{% /codetab %}}
-*Note: the Kubernetes annotation can be found [here](../configure-k8s).*
+{{% codetab %}}
### Setup an ID using Kubernetes
@@ -51,14 +57,16 @@ spec:
dapr.io/app-port: "5000"
...
```
+*If your app uses an SSL connection, you can tell Dapr to invoke your app over an insecure SSL connection with the `app-ssl: "true"` annotation (full list [here]({{< ref kubernetes-annotations.md >}}))*
-## 2. Invoke a service
+{{% /codetab %}}
-Dapr uses a sidecar, decentralized architecture. To invoke an application using Dapr, you can use the `invoke` API on any Dapr instance.
+{{< /tabs >}}
-The sidecar programming model encourages each applications to talk to its own instance of Dapr. The Dapr instances discover and communicate with one another.
-*Note: The following is a Python example of a cart app. It can be written in any programming language*
+## Step 2: Setup a service
+
+The following is a Python example of a cart app. It can be written in any programming language.
```python
from flask import Flask
@@ -74,8 +82,16 @@ if __name__ == '__main__':
This Python app exposes an `add()` method via the `/add` endpoint.
-### Invoke with curl over HTTP
+## Step 3: Invoke the service
+Dapr uses a sidecar, decentralized architecture. To invoke an application using Dapr, you can use the `invoke` API on any Dapr instance.
+
+The sidecar programming model encourages each applications to talk to its own instance of Dapr. The Dapr instances discover and communicate with one another.
+
+{{< tabs curl CLI >}}
+
+{{% codetab %}}
+From a terminal or command prompt run:
```bash
curl http://localhost:3500/v1.0/invoke/cart/method/add -X POST
```
@@ -95,30 +111,35 @@ curl http://localhost:3500/v1.0/invoke/cart/method/add -X DELETE
```
Dapr puts any payload returned by the called service in the HTTP response's body.
+{{% /codetab %}}
+
+{{% codetab %}}
+```bash
+dapr invoke --app-id cart --method add
+```
+{{% /codetab %}}
+
+{{< /tabs >}}
### Namespaces
-When running on [namespace supported platforms](../../reference/api/service_invocation_api.md#namespace-supported-platforms), you include the namespace of the target app in the app ID:
+When running on [namespace supported platforms]({{< ref "service_invocation_api.md#namespace-supported-platforms" >}}), you include the namespace of the target app in the app ID: `myApp.production`
-```
-myApp.production
-```
-
-For example, invoking the example python service with a namespace would be;
+For example, invoking the example python service with a namespace would be:
```bash
curl http://localhost:3500/v1.0/invoke/cart.production/method/add -X POST
```
-See the [Cross namespace API spec](../../reference/api/service_invocation_api.md#cross-namespace-invocation) for more information on namespaces.
+See the [Cross namespace API spec]({{< ref "service_invocation_api.md#cross-namespace-invocation" >}}) for more information on namespaces.
-## 3. View traces and logs
+## Step 4: View traces and logs
The example above showed you how to directly invoke a different service running locally or in Kubernetes. Dapr outputs metrics, tracing and logging information allowing you to visualize a call graph between services, log errors and optionally log the payload body.
-For more information on tracing and logs see the [observability](../../concepts/observability) article.
+For more information on tracing and logs see the [observability]({{< ref observability-concept.md >}}) article.
## Related Links
-* [Service invocation concepts](../../concepts/service-invocation/README.md)
-* [Service invocation API specification](../../reference/api/service_invocation_api.md)
+* [Service invocation overview]({{< ref service-invocation-overview.md >}})
+* [Service invocation API specification]({{< ref service_invocation_api.md >}})
diff --git a/concepts/service-invocation/README.md b/daprdocs/content/en/developing-applications/building-blocks/service-invocation/service-invocation-overview.md
similarity index 52%
rename from concepts/service-invocation/README.md
rename to daprdocs/content/en/developing-applications/building-blocks/service-invocation/service-invocation-overview.md
index c9e0b72b7..1c5eed66d 100644
--- a/concepts/service-invocation/README.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/service-invocation/service-invocation-overview.md
@@ -1,12 +1,15 @@
-# Service Invocation
+---
+type: docs
+title: "Service invocation overview"
+linkTitle: "Overview"
+weight: 1000
+description: "Overview of the service invocation building block"
+---
+
+## Introduction
Using service invocation, your application can discover and reliably and securely communicate with other applications using the standard protocols of [gRPC](https://grpc.io) or [HTTP](https://www.w3.org/Protocols/).
-- [Overview](#overview)
-- [Features](#features)
-- [Next steps](#next-steps)
-
-## Overview
In many environments with multiple services that need to communicate with each other, developers often ask themselves the following questions:
* How do I discover and invoke methods on different services?
@@ -18,47 +21,32 @@ Dapr allows you to overcome these challenges by providing an endpoint that acts
Dapr uses a sidecar, decentralized architecture. To invoke an application using Dapr, you use the `invoke` API on any Dapr instance. The sidecar programming model encourages each applications to talk to its own instance of Dapr. The Dapr instances discover and communicate with one another.
+### Invoke logic
+
The diagram below is an overview of how Dapr's service invocation works.
-
+
-1. Service A makes an http/gRPC call meant for Service B. The call goes to the local Dapr sidecar.
-2. Dapr discovers Service B's location using the [name resolution component](https://github.com/dapr/components-contrib/tree/master/nameresolution) installed for the given hosting platform.
+1. Service A makes an http/gRPC call targeting Service B. The call goes to the local Dapr sidecar.
+2. Dapr discovers Service B's location using the [name resolution component](https://github.com/dapr/components-contrib/tree/master/nameresolution) which is running on the given [hosting platform]({{< ref "hosting" >}}).
3. Dapr forwards the message to Service B's Dapr sidecar
- * Note: All calls between Dapr sidecars go over gRPC for performance. Only calls between services and Dapr sidecars are either HTTP or gRPC
+
+ **Note**: All calls between Dapr sidecars go over gRPC for performance. Only calls between services and Dapr sidecars can be either HTTP or gRPC
+
4. Service B's Dapr sidecar forwards the request to the specified endpoint (or method) on Service B. Service B then runs its business logic code.
5. Service B sends a response to Service A. The response goes to Service B's sidecar.
6. Dapr forwards the response to Service A's Dapr sidecar.
7. Service A receives the response.
-### Example
-As an example for the above call sequence, suppose you have the applications as described in the [hello world sample](https://github.com/dapr/quickstarts/blob/master/hello-world/README.md), where a python app invokes a node.js app.
-
-In such a scenario, the python app would be "Service A" above, and the Node.js app would be "Service B".
-
-The diagram below shows sequence 1-7 again on a local machine showing the API call:
-
-
-
-1. Suppose the Node.js app has a Dapr app ID of `nodeapp`, as in the sample. The python app invokes the Node.js app's `neworder` method by posting `http://localhost:3500/v1.0/invoke/nodeapp/method/neworder`, which first goes to the python app's local Dapr sidecar.
-2. Dapr discovers the Node.js app's location using multicast DNS component which runs on your local machine.
-3. Dapr forwards the request to the Node.js app's sidecar.
-4. The Node.js app's sidecar forwards the request to the Node.js app. The Node.js app performs its business logic, which, as described in the sample, is to log the incoming message and then persist the order ID into Redis (not shown in the diagram above).
-
- Steps 5-7 are the same as above.
-
## Features
Service invocation provides several features to make it easy for you to call methods on remote applications.
-- [Namespaces scoping](#namespaces-scoping)
-- [Retries](#Retries)
-- [Service-to-service security](#service-to-service-security)
-- [Service access security](#service-access-security)
-- [Observability: Tracing, logging and metrics](#observability)
-- [Pluggable service discovery](#pluggable-service-discovery)
+### Service invocation API
+The API for Pservice invocation can be found in the [spec repo]({{< ref service_invocation_api.md >}}).
### Namespaces scoping
+
Service invocation supports calls across namespaces. On all supported hosting platforms, Dapr app IDs conform to a valid FQDN format that includes the target namespace.
For example, the following string contains the app ID `nodeapp` in addition to the namespace the app runs in `production`.
@@ -67,10 +55,14 @@ For example, the following string contains the app ID `nodeapp` in addition to t
localhost:3500/v1.0/invoke/nodeapp.production/method/neworder
```
-This is especially useful in cross namespace calls in a Kubernetes cluster. Watch this [video](https://youtu.be/LYYV_jouEuA?t=495) for a demo on how to use namespaces with service invocation.
+This is especially useful in cross namespace calls in a Kubernetes cluster. Watch this video for a demo on how to use namespaces with service invocation.
+
+
### Retries
+
Service invocation performs automatic retries with backoff time periods in the event of call failures and transient errors.
+
Errors that cause retries are:
* Network errors including endpoint unavailability and refused connections
@@ -80,29 +72,48 @@ Per call retries are performed with a backoff interval of 1 second up to a thres
Connection establishment via gRPC to the target sidecar has a timeout of 5 seconds.
### Service-to-service security
+
All calls between Dapr applications can be made secure with mutual (mTLS) authentication on hosted platforms, including automatic certificate rollover, via the Dapr Sentry service. The diagram below shows this for self hosted applications.
-For more information read the [service-to-service security](../security#mtls-self-hosted) article.
+For more information read the [service-to-service security]({{< ref "security-concept.md#sidecar-to-sidecar-communication" >}}) article.
-
+
### Service access security
+
Applications can control which other applications are allowed to call them and what they are authorized to do via access policies. This enables you to restrict sensitive applications, that say have personnel information, from being accessed by unauthorized applications, and combined with service-to-service secure communication, provides for soft multi-tenancy deployments.
-For more information read the [access control allow lists for service invocation](../configuration#access-control-allow-lists-for-service-invocation) article.
+For more information read the [access control allow lists for service invocation]({{< ref invoke-allowlist.md >}}) article.
### Observability
+
By default, all calls between applications are traced and metrics are gathered to provide insights and diagnostics for applications, which is especially important in production scenarios.
-For more information read the [observability](../concepts/observability) article.
+For more information read the [observability]({{< ref observability-concept.md >}}) article.
### Pluggable service discovery
-Dapr can run on any [hosting platform](../hosting). For the supported hosting platforms this means they have a [name resolution component](https://github.com/dapr/components-contrib/tree/master/nameresolution) developed for them that enables service discovery. For example, the Kubernetes name resolution component uses the Kubernetes DNS service to resolve the location of other applications running in the cluster.
+
+Dapr can run on any [hosting platform]({{< ref hosting >}}). For the supported hosting platforms this means they have a [name resolution component](https://github.com/dapr/components-contrib/tree/master/nameresolution) developed for them that enables service discovery. For example, the Kubernetes name resolution component uses the Kubernetes DNS service to resolve the location of other applications running in the cluster.
+
+## Example
+Following the above call sequence, suppose you have the applications as described in the [hello world quickstart](https://github.com/dapr/quickstarts/blob/master/hello-world/README.md), where a python app invokes a node.js app. In such a scenario, the python app would be "Service A" , and a Node.js app would be "Service B".
+
+The diagram below shows sequence 1-7 again on a local machine showing the API call:
+
+
+
+1. The Node.js app has a Dapr app ID of `nodeapp`. The python app invokes the Node.js app's `neworder` method by POSTing `http://localhost:3500/v1.0/invoke/nodeapp/method/neworder`, which first goes to the python app's local Dapr sidecar.
+2. Dapr discovers the Node.js app's location using name resolution component (in this case mDNS while self-hosted) which runs on your local machine.
+3. Dapr forwards the request to the Node.js app's sidecar using the location it just received.
+4. The Node.js app's sidecar forwards the request to the Node.js app. The Node.js app performs its business logic, logging the incoming message and then persist the order ID into Redis (not shown in the diagram)
+5. The Node.js app sends a response to the Python app through the Node.js sidecar.
+6. Dapr forwards the response to the Python Dapr sidecar
+7. The Python app receives the resposne.
## Next steps
-* Follow these guide on
- * [How-to: Get started with HTTP service invocation](../../howto/invoke-and-discover-services)
- * [How-to: Get started with Dapr and gRPC](../../howto/create-grpc-app)
-* Try out the [hello world sample](https://github.com/dapr/quickstarts/blob/master/hello-world/README.md) which shows how to use HTTP service invocation or visit the samples in each of the [Dapr SDKs](https://github.com/dapr/docs#further-documentation)
-* Read the [service invocation API specification](../../reference/api/service_invocation_api.md)
+* Follow these guide on:
+ * [How-to: Get started with HTTP service invocation]({{< ref howto-invoke-discover-services.md >}})
+ * [How-to: Get started with Dapr and gRPC]({{< ref grpc >}})
+* Try out the [hello world quickstart](https://github.com/dapr/quickstarts/blob/master/hello-world/README.md) which shows how to use HTTP service invocation or visit the samples in each of the [Dapr SDKs]({{< ref sdks >}})
+* Read the [service invocation API specification]({{< ref service_invocation_api.md >}})
diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/_index.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/_index.md
new file mode 100644
index 000000000..fd6f95bdb
--- /dev/null
+++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/_index.md
@@ -0,0 +1,7 @@
+---
+type: docs
+title: "State management"
+linkTitle: "State management"
+weight: 20
+description: Create long running stateful services
+---
diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-get-save-state.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-get-save-state.md
new file mode 100644
index 000000000..c7dcb577b
--- /dev/null
+++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-get-save-state.md
@@ -0,0 +1,168 @@
+---
+type: docs
+title: "How-To: Save and get state"
+linkTitle: "How-To: Save & get state"
+weight: 200
+description: "Use key value pairs to persist a state"
+---
+
+## Introduction
+
+State management is one of the most common needs of any application: new or legacy, monolith or microservice.
+Dealing with different databases libraries, testing them, handling retries and faults can be time consuming and hard.
+
+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.
+
+## 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.
+
+{{< 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`
+
+To change the state store being used, replace the YAML under `/components` with the file of your choice.
+{{% /codetab %}}
+
+{{% codetab %}}
+See the instructions [here]({{< ref "setup-state-store" >}}) on how to setup different state stores on Kubernetes.
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+## Step 2: Save state
+
+The following example shows how to save two key/value pairs in a single call using the state management API.
+
+{{< tabs "HTTP API (Bash)" "HTTP API (PowerShell)" "Python SDK">}}
+
+{{% codetab %}}
+Begin by ensuring a Dapr sidecar is running:
+```bash
+dapr --app-id myapp --port 3500 run
+```
+{{% alert title="Note" color="info" %}}
+It is important to set an app-id, as the state keys are prefixed with this value. If you don't set it one is generated for you at runtime, and the next time you run the command a new one will be generated and you will no longer be able to access previously saved state.
+
+{{% /alert %}}
+
+Then in a separate terminal run:
+```bash
+curl -X POST -H "Content-Type: application/json" -d '[{ "key": "key1", "value": "value1"}, { "key": "key2", "value": "value2"}]' http://localhost:3500/v1.0/state/statestore
+```
+{{% /codetab %}}
+
+{{% codetab %}}
+Begin by ensuring a Dapr sidecar is running:
+```bash
+dapr --app-id myapp --port 3500 run
+```
+
+{{% alert title="Note" color="info" %}}
+It is important to set an app-id, as the state keys are prefixed with this value. If you don't set it one is generated for you at runtime, and the next time you run the command a new one will be generated and you will no longer be able to access previously saved state.
+
+{{% /alert %}}
+
+Then in a separate terminal run:
+```powershell
+Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '[{ "key": "key1", "value": "value1"}, { "key": "key2", "value": "value2"}]' -Uri 'http://localhost:3500/v1.0/state/statestore'
+```
+{{% /codetab %}}
+
+{{% codetab %}}
+Make sure to install the Dapr Python SDK with `pip3 install dapr`. Then create a file named `state.py` with:
+```python
+from dapr.clients import DaprClient
+from dapr.clients.grpc._state import StateItem
+
+with DaprClient() as d:
+ d.save_states(store_name="statestore",
+ states=[
+ StateItem(key="key1", value="value1"),
+ StateItem(key="key2", value="value2")
+ ])
+
+```
+
+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:
+```bash
+curl http://localhost:3500/v1.0/state/statestore/key1
+```
+{{% /codetab %}}
+
+{{% codetab %}}
+With the same dapr instance running from above run:
+```powershell
+Invoke-RestMethod -Uri 'http://localhost:3500/v1.0/state/statestore/key1'
+```
+{{% /codetab %}}
+
+{{% codetab %}}
+Add the following code to `state.py` from above and run again:
+```python
+ data = d.get_state(store_name="statestore",
+ key="key1",
+ state_metadata={"metakey": "metavalue"}).data
+ print(f"Got value: {data}")
+```
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+## Step 4: Delete state
+
+The following example shows how to delete 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:
+```bash
+curl -X DELETE 'http://localhost:3500/v1.0/state/statestore/key1'
+```
+Try getting state again and note that no value is returned.
+{{% /codetab %}}
+
+{{% codetab %}}
+With the same dapr instance running from above run:
+```powershell
+Invoke-RestMethod -Method Delete -Uri 'http://localhost:3500/v1.0/state/statestore/key1'
+```
+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:
+```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
+ print(f"Got value after delete: {data}")
+```
+{{% /codetab %}}
+
+{{< /tabs >}}
diff --git a/howto/stateful-replicated-service/README.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-stateful-service.md
similarity index 92%
rename from howto/stateful-replicated-service/README.md
rename to daprdocs/content/en/developing-applications/building-blocks/state-management/howto-stateful-service.md
index 4ad312f2c..d25b7fbe6 100644
--- a/howto/stateful-replicated-service/README.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-stateful-service.md
@@ -1,15 +1,21 @@
-# Create a stateful replicated service
+---
+type: docs
+title: "How-To: Build a stateful service"
+linkTitle: "How-To: Build a stateful service"
+weight: 300
+description: "Use state management with a scaled, replicated service"
+---
-In this HowTo we'll show you how you can create a stateful service which can be horizontally scaled, using opt-in concurrency and consistency models.
+In this article you'll learn how you can create a stateful service which can be horizontally scaled, using opt-in concurrency and consistency models.
This frees developers from difficult state coordination, conflict resolution and failure handling, and allows them instead to consume these capabilities as APIs from Dapr.
-## 1. Setup a state store
+## Setup a state store
A state store component represents a resource that Dapr uses to communicate with a database.
For the purpose of this guide, we'll use a Redis state store.
-See a list of supported state stores [here](../setup-state-store/supported-state-stores.md)
+See a list of supported state stores [here]({{< ref supported-state-stores >}})
### Using the Dapr CLI
@@ -18,7 +24,7 @@ To change the state store being used, replace the YAML under `/components` with
### Kubernetes
-See the instructions [here](../setup-state-store) on how to setup different state stores on Kubernetes.
+See the instructions [here]({{}}) on how to setup different state stores on Kubernetes.
## Strong and Eventual consistency
diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/query-state-store/_index.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/query-state-store/_index.md
new file mode 100644
index 000000000..542bd4b9c
--- /dev/null
+++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/query-state-store/_index.md
@@ -0,0 +1,9 @@
+---
+type: docs
+title: "Work with backend state stores"
+linkTitle: "Backend stores"
+weight: 400
+description: "Guides for working with specific backend states stores"
+---
+
+Explore the **Operations** section to see a list of [supported state stores]({{}}) and how to setup [state store components]({{}}).
\ No newline at end of file
diff --git a/howto/query-state-store/query-cosmosdb-store.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/query-state-store/query-cosmosdb-store.md
similarity index 87%
rename from howto/query-state-store/query-cosmosdb-store.md
rename to daprdocs/content/en/developing-applications/building-blocks/state-management/query-state-store/query-cosmosdb-store.md
index ffce0f539..385968847 100644
--- a/howto/query-state-store/query-cosmosdb-store.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/query-state-store/query-cosmosdb-store.md
@@ -1,53 +1,59 @@
-# Query Azure Cosmos DB 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](../../reference/api/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.
-
-> **NOTE:** Azure Cosmos DB is a multi-modal database that supports multiple APIs. The default Dapr Cosmos DB state store implementation uses the [Azure Cosmos DB SQL API](https://docs.microsoft.com/en-us/azure/cosmos-db/sql-query-getting-started).
-
-## 1. Connect to Azure Cosmos DB
-
-The easiest way to connect to your Cosmos DB instance is to use the Data Explorer on [Azure Management Portal](https://portal.azure.com). Alternatively, you can use [various SDKs and tools](https://docs.microsoft.com/en-us/azure/cosmos-db/mongodb-introduction).
-
-> **NOTE:** The following samples use Cosmos DB [SQL API](https://docs.microsoft.com/en-us/azure/cosmos-db/sql-query-getting-started). When you configure an Azure Cosmos DB for Dapr, you need to specify the exact database and collection to use. The follow samples assume you've already connected to the right database and a collection named "states".
-
-## 2. List keys by App ID
-
-To get all state keys associated with application "myapp", use the query:
-
-```sql
-SELECT * FROM states WHERE CONTAINS(states.id, 'myapp||')
-```
-
-The above query returns all documents with id containing "myapp-", which is the prefix of the state keys.
-
-## 3. Get specific state data
-
-To get the state data by a key "balance" for the application "myapp", use the query:
-
-```sql
-SELECT * FROM states WHERE states.id = 'myapp||balance'
-```
-
-Then, read the **value** field of the returned document.
-
-To get the state version/ETag, use the command:
-
-```sql
-SELECT states._etag FROM states WHERE states.id = 'myapp||balance'
-```
-
-## 4. Read actor state
-
-To get all the state keys associated with an actor with the instance ID "leroy" of actor type "cat" belonging to the application with ID "mypets", use the command:
-
-```sql
-SELECT * FROM states WHERE CONTAINS(states.id, 'mypets||cat||leroy||')
-```
-
-And to get a specific actor state such as "food", use the command:
-
-```sql
-SELECT * FROM states WHERE states.id = 'mypets||cat||leroy||food'
-```
-
-> **WARNING:** You should not manually update or delete states in the store. All writes and delete operations should be done via the Dapr runtime.
+---
+type: docs
+title: "Azure Cosmos DB"
+linkTitle: "Azure Cosmos DB"
+weight: 1000
+description: "Use Azure Cosmos DB 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.
+
+> **NOTE:** Azure Cosmos DB is a multi-modal database that supports multiple APIs. The default Dapr Cosmos DB state store implementation uses the [Azure Cosmos DB SQL API](https://docs.microsoft.com/en-us/azure/cosmos-db/sql-query-getting-started).
+
+## 1. Connect to Azure Cosmos DB
+
+The easiest way to connect to your Cosmos DB instance is to use the Data Explorer on [Azure Management Portal](https://portal.azure.com). Alternatively, you can use [various SDKs and tools](https://docs.microsoft.com/en-us/azure/cosmos-db/mongodb-introduction).
+
+> **NOTE:** The following samples use Cosmos DB [SQL API](https://docs.microsoft.com/en-us/azure/cosmos-db/sql-query-getting-started). When you configure an Azure Cosmos DB for Dapr, you need to specify the exact database and collection to use. The follow samples assume you've already connected to the right database and a collection named "states".
+
+## 2. List keys by App ID
+
+To get all state keys associated with application "myapp", use the query:
+
+```sql
+SELECT * FROM states WHERE CONTAINS(states.id, 'myapp||')
+```
+
+The above query returns all documents with id containing "myapp-", which is the prefix of the state keys.
+
+## 3. Get specific state data
+
+To get the state data by a key "balance" for the application "myapp", use the query:
+
+```sql
+SELECT * FROM states WHERE states.id = 'myapp||balance'
+```
+
+Then, read the **value** field of the returned document.
+
+To get the state version/ETag, use the command:
+
+```sql
+SELECT states._etag FROM states WHERE states.id = 'myapp||balance'
+```
+
+## 4. Read actor state
+
+To get all the state keys associated with an actor with the instance ID "leroy" of actor type "cat" belonging to the application with ID "mypets", use the command:
+
+```sql
+SELECT * FROM states WHERE CONTAINS(states.id, 'mypets||cat||leroy||')
+```
+
+And to get a specific actor state such as "food", use the command:
+
+```sql
+SELECT * FROM states WHERE states.id = 'mypets||cat||leroy||food'
+```
+
+> **WARNING:** You should not manually update or delete states in the store. All writes and delete operations should be done via the Dapr runtime.
diff --git a/howto/query-state-store/query-redis-store.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/query-state-store/query-redis-store.md
similarity index 86%
rename from howto/query-state-store/query-redis-store.md
rename to daprdocs/content/en/developing-applications/building-blocks/state-management/query-state-store/query-redis-store.md
index 86b8356af..ab7632e09 100644
--- a/howto/query-state-store/query-redis-store.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/query-state-store/query-redis-store.md
@@ -1,60 +1,66 @@
-# Query Redis 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](../../reference/api/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.
-
->**NOTE:** The following examples uses Redis CLI against a Redis store using the default Dapr state store implementation.
-
-## 1. Connect to Redis
-
-You can use the official [redis-cli](https://redis.io/topics/rediscli) or any other Redis compatible tools to connect to the Redis state store to directly query Dapr states. If you are running Redis in a container, the easiest way to use redis-cli is to use a container:
-
-```bash
-docker run --rm -it --link 
## Features
-- [State Management API](#state-management-api)
-- [State Store Behaviors](#state-store-behaviors)
+- [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)
+- [Retry policies](#retry-policies)
+- [Bulk operations](#bulk-operations)
+- [Querying state store directly](#querying-state-store-directly)
-## State management API
+### State management API
Developers can use the state management API 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/).
+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/).
-Visit [State API](../../reference/api/state_api.md) for more information.
+Visit [State API]({{< ref state_api.md >}}) for more information.
> **NOTE:** Dapr prefixes state keys with the ID of the current Dapr instance. This allows multiple Dapr instances to share the same state store.
-## State store behaviors
+### State store behaviors
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.
@@ -50,50 +50,51 @@ Not all stores are created equal. To ensure portability of your application, you
The following table summarizes the capabilities of existing data store implementations.
-Store | Strong consistent write | Strong consistent read | ETag|
-----|----|----|----
-Cosmos DB | Yes | Yes | Yes
-PostgreSQL | Yes | Yes | Yes
-Redis | Yes | Yes | Yes
-Redis (clustered)| Yes | No | Yes
-SQL Server | Yes | Yes | Yes
+| Store | Strong consistent write | Strong consistent read | ETag |
+|-------------------|-------------------------|------------------------|------|
+| Cosmos DB | Yes | Yes | Yes |
+| PostgreSQL | Yes | Yes | Yes |
+| Redis | Yes | Yes | Yes |
+| Redis (clustered) | Yes | No | Yes |
+| SQL Server | Yes | Yes | Yes |
-## Concurrency
+### 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 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.
-## Consistency
+### Consistency
Dapr supports both **strong consistency** and **eventual consistency**, with eventual consistency as the default behavior.
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.
-## Retry policies
+### 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.
-## Bulk operations
+### 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
+### Querying state store directly
-Dapr saves and retrieves state values without any transformation. You can query and aggregate state directly from the underlying state store. For example, to get all state keys associated with an application ID "myApp" in Redis, use:
+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 >}}).
+
+For example, to get all state keys associated with an application ID "myApp" in Redis, use:
```bash
KEYS "myApp*"
```
-> **NOTE:** See [How to query Redis store](../../howto/query-state-store/query-redis-store.md) for details on how to query a Redis store.
->
+> **NOTE:** See [How to query Redis store]({{< ref query-redis-store.md >}} ) for details on how to query a Redis store.
-### Querying actor state
+#### Querying actor state
If the data store supports SQL queries, you can query an actor's state using SQL queries. For example use:
@@ -111,13 +112,6 @@ SELECT AVG(value) FROM StateTable WHERE Id LIKE 'Binding | Output
Binding | Status | +|------|:----------------:|:-----------------:|--------| +| [APNs]({{< ref apns.md >}}) | | ✅ | Experimental | +| [Cron (Scheduler)]({{< ref cron.md >}}) | ✅ | ✅ | Experimental | +| [HTTP]({{< ref http.md >}}) | | ✅ | Experimental | +| [InfluxDB]({{< ref influxdb.md >}}) | | ✅ | Experimental | +| [Kafka]({{< ref kafka.md >}}) | ✅ | ✅ | Experimental | +| [Kubernetes Events]({{< ref "kubernetes-binding.md" >}}) | ✅ | | Experimental | +| [MQTT]({{< ref mqtt.md >}}) | ✅ | ✅ | Experimental | +| [PostgreSql]({{< ref postgres.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) + +| Name | Input
Binding | Output
Binding | Status | +|------|:----------------:|:-----------------:|--------| +| [AWS DynamoDB]({{< ref dynamodb.md >}}) | | ✅ | Experimental | +| [AWS S3]({{< ref s3.md >}}) | | ✅ | Experimental | +| [AWS SNS]({{< ref sns.md >}}) | | ✅ | Experimental | +| [AWS SQS]({{< ref sqs.md >}}) | ✅ | ✅ | Experimental | +| [AWS Kinesis]({{< ref kinesis.md >}}) | ✅ | ✅ | Experimental | + + +### Google Cloud Platform (GCP) + +| Name | Input
Binding | Output
Binding | Status | +|------|:----------------:|:-----------------:|--------| +| [GCP Cloud Pub/Sub]({{< ref gcppubsub.md >}}) | ✅ | ✅ | Experimental | +| [GCP Storage Bucket]({{< ref gcpbucket.md >}}) | | ✅ | Experimental | + +### Microsoft Azure + +| Name | Input
Binding | Output
Binding | Status | +|------|:----------------:|:-----------------:|--------| +| [Azure Blob Storage]({{< ref blobstorage.md >}}) | | ✅ | Experimental | +| [Azure EventHubs]({{< ref eventhubs.md >}}) | ✅ | ✅ | Experimental | +| [Azure CosmosDB]({{< ref cosmosdb.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 | \ No newline at end of file diff --git a/reference/specs/bindings/apns.md b/daprdocs/content/en/operations/components/setup-bindings/supported-bindings/apns.md similarity index 90% rename from reference/specs/bindings/apns.md rename to daprdocs/content/en/operations/components/setup-bindings/supported-bindings/apns.md index ff413c8ab..b4ba62999 100644 --- a/reference/specs/bindings/apns.md +++ b/daprdocs/content/en/operations/components/setup-bindings/supported-bindings/apns.md @@ -1,4 +1,10 @@ -# Apple Push Notification Service Binding Spec + +--- +type: docs +title: "Apple Push Notification Service binding spec" +linkTitle: "Apple Push Notification Service" +description: "Detailed documentation on the Apple Push Notification Service binding component" +--- ## Configuration diff --git a/reference/specs/bindings/blobstorage.md b/daprdocs/content/en/operations/components/setup-bindings/supported-bindings/blobstorage.md similarity index 76% rename from reference/specs/bindings/blobstorage.md rename to daprdocs/content/en/operations/components/setup-bindings/supported-bindings/blobstorage.md index 94fe19dde..0e9a9327b 100644 --- a/reference/specs/bindings/blobstorage.md +++ b/daprdocs/content/en/operations/components/setup-bindings/supported-bindings/blobstorage.md @@ -1,4 +1,11 @@ -# Azure Blob Storage Binding Spec +--- +type: docs +title: "Azure Blob Storage binding spec" +linkTitle: "Azure Blob Storage" +description: "Detailed documentation on the Azure Blob Storage binding component" +--- + +## Setup Dapr component ```yaml apiVersion: dapr.io/v1alpha1 @@ -24,15 +31,13 @@ spec: - `container` is the name of the Blob Storage container to write to. - `decodeBase64` optional configuration to decode base64 file content before saving to Blob Storage. (In case of saving a file with binary content). "true" is the only allowed positive value. Other positive variations like "True" are not acceptable. -> **Note:** In production never place passwords or secrets within Dapr components. For information on securely storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store) +{{% 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](#create-blob) -* [get](#get-blob) - - -## Create Blob +### Create Blob To perform a get blob operation, invoke the Azure Blob Storage binding with a `POST` method and the following JSON body: @@ -45,7 +50,7 @@ To perform a get blob operation, invoke the Azure Blob Storage binding with a `P } ``` -Example: +#### Example: ```bash @@ -53,7 +58,7 @@ curl -d '{ "operation": "create", "data": { "field1": "value1" }}' \ http://localhost:
- -The following yaml file demonstrates how to define each. - -### Configuring Redis for State Persistence and Retrieval **TLS:** If the Redis instance supports TLS with public certificates it can be configured to enable or disable TLS `true` or `false`. **Failover:** When set to `true` enables the failover feature. The redisHost should be the sentinel host address. See [Redis Sentinel Documentation](https://redis.io/topics/sentinel) -**Note:** yaml files below illustrate secret management in plain text. In a production-grade application, follow [secret management](../../concepts/secrets/README.md) instructions to securely manage your secrets. - Create a file called redis.yaml, and paste the following: ```yaml @@ -88,6 +96,10 @@ spec: value:
+
+Deploying and running a Dapr enabled application into your Kubernetes cluster is a simple as adding a few annotations to the deployment schemes. To give your service an `id` and `port` known to Dapr, turn on tracing through configuration and launch the Dapr sidecar container, you annotate your Kubernetes deployment like this.
+
+```yml
+ annotations:
+ dapr.io/enabled: "true"
+ dapr.io/app-id: "nodeapp"
+ dapr.io/app-port: "3000"
+ dapr.io/config: "tracing"
+```
+You can see some examples [here](https://github.com/dapr/quickstarts/tree/master/hello-kubernetes/deploy) in the Kubernetes getting started sample.
+
+Read [Kubernetes how to topics](https://github.com/dapr/docs/tree/master/howto#kubernetes-configuration) for more information about setting up Kubernetes and Dapr.
\ No newline at end of file
diff --git a/howto/deploy-k8s-prod/README.md b/daprdocs/content/en/operations/hosting/kubernetes/kubernetes-production.md
similarity index 83%
rename from howto/deploy-k8s-prod/README.md
rename to daprdocs/content/en/operations/hosting/kubernetes/kubernetes-production.md
index 2e72be733..7cfde34c6 100644
--- a/howto/deploy-k8s-prod/README.md
+++ b/daprdocs/content/en/operations/hosting/kubernetes/kubernetes-production.md
@@ -1,15 +1,10 @@
-# Guidelines for production ready deployments on Kubernetes
-
-This section outlines recommendations and practices for deploying Dapr to a Kubernetes cluster in a production ready configuration.
-
-## Contents
-
-- [Cluster capacity requirements](#cluster-capacity-requirements)
-- [Sidecar resource requirements](#sidecar-resource-requirements)
-- [Deploying Dapr with Helm](#deploying-dapr-with-helm)
-- [Upgrading Dapr with Helm](#upgrading-dapr-with-helm)
-- [Recommended security configuration](#recommended-security-configuration)
-- [Tracing and metrics configuration](#tracing-and-metrics-configuration)
+---
+type: docs
+title: "Guidelines for production ready deployments on Kubernetes"
+linkTitle: "Production guidelines"
+weight: 10000
+description: "Recommendations and practices for deploying Dapr to a Kubernetes cluster in a production ready configuration"
+---
## Cluster capacity requirements
@@ -19,14 +14,14 @@ The Dapr control plane pods are designed to be lightweight and require the follo
*Note: For more info on CPU and Memory resource units and their meaning, see [this](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) link*
| Deployment | CPU | Memory
-| ------------| ---- | ------
-| Operator | Limit: 1, Request: 100m | Limit: 200Mi, Request: 20Mi
+|-------------|-----|-------
+| Operator | Limit: 1, Request: 100m | Limit: 200Mi, Request: 20Mi
| Sidecar Injector | Limit: 1, Request: 100m | Limit: 200Mi, Request: 20Mi
-| Sentry | Limit: 1, Request: 100m | Limit: 200Mi, Request: 20Mi
-| Placement | Limit: 1, Request: 250m | Limit: 500Mi, Request: 100Mi
-| Dashboard | Limit: 200m, Request: 50m | Limit: 200Mi, Request: 20Mi
+| Sentry | Limit: 1, Request: 100m | Limit: 200Mi, Request: 20Mi
+| Placement | Limit: 1, Request: 250m | Limit: 500Mi, Request: 100Mi
+| Dashboard | Limit: 200m, Request: 50m | Limit: 200Mi, Request: 20Mi
-To change the resource assignments for the Dapr sidecar, see the annotations [here](../configure-k8s/).
+To change the resource assignments for the Dapr sidecar, see the annotations [here]({{< ref "kubernetes-annotations.md" >}}).
The specific annotations related to resource constraints are:
* `dapr.io/sidecar-cpu-limit`
@@ -48,8 +43,8 @@ The following Dapr control plane deployments are optional:
The Dapr sidecar requires the following resources in a production-ready setup:
-| CPU | Memory
-| --------- | --------- |
+| CPU | Memory |
+|-----|--------|
| Limit: 4, Request: 100m | Limit: 4000Mi, Request: 250Mi
*Note: Since Dapr is intended to do much of the I/O heavy lifting for your app, it's expected that the resources given to Dapr enable you to drastically reduce the resource allocations for the application*
@@ -59,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](../../getting-started/environment-setup.md#using-helm-(advanced)) on how to deploy Dapr using Helm.
+You can find information [here]({{< ref "install-dapr.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:
@@ -69,7 +64,7 @@ helm install dapr dapr/dapr --namespace dapr-system --set global.ha.enabled=true
This command will run 3 replicas of each control plane pod with the exception of the Placement pod in the dapr-system namespace.
-*Note: The Dapr Helm chart automatically deploys with affinity for nodes with the label `kubernetes.io/os=linux`. You can deploy the Dapr control plane to Windows nodes, but most users should not need to. For more information see [Deploying to a Hybrid Linux/Windows K8s Cluster](../windows-k8s/)*
+*Note: The Dapr Helm chart automatically deploys with affinity for nodes with the label `kubernetes.io/os=linux`. You can deploy the Dapr control plane to Windows nodes, but most users should not need to. For more information see [Deploying to a Hybrid Linux/Windows K8s Cluster]({{< ref "kubernetes-hybrid-clusters.md" >}})*
## Upgrading Dapr with Helm
@@ -79,7 +74,7 @@ Dapr supports zero downtime upgrades. The upgrade path includes the following st
2. Updating the Dapr control plane
3. Updating the data plane (Dapr sidecars)
-### 1. Upgrading the CLI
+### 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 0.9.0, download a CLI version of 0.9.x.
@@ -204,24 +199,24 @@ Properly configured, Dapr not only be secured with regards to it's control plane
It is recommended that a production-ready deployment includes the following settings:
-1. Mutual Authentication (mTLS) should be enabled. Note that Dapr has mTLS on by default. For details on how to bring your own certificates, see [here](../configure-mtls/README.md#bringing-your-own-certificates)
+1. Mutual Authentication (mTLS) should be enabled. Note that Dapr has mTLS on by default. For details on how to bring your own certificates, see [here]({{< ref "mtls.md#bringing-your-own-certificates" >}})
-2. Dapr API authentication is enabled (this is the between your application and the Dapr sidecar). To secure the Dapr API from unauthorized access, it is recommended to enable Dapr's token based auth. See [here](../enable-dapr-api-token-based-authentication/README.md) for details
+2. Dapr API authentication is enabled (this is the between your application and the Dapr sidecar). To secure the Dapr API from unauthorized access, it is recommended to enable Dapr's token based auth. See [here]({{< ref "api-token.md" >}}) for details
-3. All component YAMLs should have secret data configured in a secret store and not hard-coded in the YAML file. See [here](../../concepts/secrets/component-secrets.md) on how to use secrets with Dapr components
+3. All component YAMLs should have secret data configured in a secret store and not hard-coded in the YAML file. See [here]({{< ref "component-secrets.md" >}}) on how to use secrets with Dapr components
4. The Dapr control plane is installed on a separate namespace such as `dapr-system`, and never into the `default` namespace
-Dapr also supports scoping components for certain applications. This is not a required practice, and can be enabled according to your Sec-Ops needs. See [here](../components-scopes/README.md) for more info.
+Dapr also supports scoping components for certain applications. This is not a required practice, and can be enabled according to your Sec-Ops needs. See [here]({{< ref "component-scopes.md" >}}) for more info.
## Tracing and metrics configuration
Dapr has tracing and metrics enabled by default.
-To configure a tracing backend for Dapr visit [this](../diagnose-with-tracing) link.
+To configure a tracing backend for Dapr visit [this]({{< ref "setup-tracing.md" >}}) link.
For metrics, Dapr exposes a Prometheus endpoint listening on port 9090 which can be scraped by Prometheus.
It is *recommended* that you set up distributed tracing and metrics for your applications and the Dapr control plane in production.
If you already have your own observability set-up, you can disable tracing and metrics for Dapr.
-To setup Prometheus, Grafana and other monitoring tools with Dapr, visit [this](../setup-monitoring-tools) link.
+To setup Prometheus, Grafana and other monitoring tools with Dapr, visit [this]({{< ref "monitoring" >}}) link.
diff --git a/daprdocs/content/en/operations/hosting/self-hosted/_index.md b/daprdocs/content/en/operations/hosting/self-hosted/_index.md
new file mode 100644
index 000000000..9c70df3ad
--- /dev/null
+++ b/daprdocs/content/en/operations/hosting/self-hosted/_index.md
@@ -0,0 +1,7 @@
+---
+type: docs
+title: "Run Dapr in Self Hosted Mode"
+linkTitle: "Self-Hosted"
+weight: 1000
+description: "How to get Dapr up and running in your local environment"
+---
\ No newline at end of file
diff --git a/howto/self-hosted-no-docker/README.md b/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-no-docker.md
similarity index 74%
rename from howto/self-hosted-no-docker/README.md
rename to daprdocs/content/en/operations/hosting/self-hosted/self-hosted-no-docker.md
index e429625f4..291178972 100644
--- a/howto/self-hosted-no-docker/README.md
+++ b/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-no-docker.md
@@ -1,10 +1,16 @@
-# Self hosted mode without containers
+---
+type: docs
+title: "How-To: Run Dapr in self-hosted mode without Docker"
+linkTitle: "Run without Docker"
+weight: 30000
+description: "How to deploy and run Dapr in self-hosted mode without Docker installed on the local machine"
+---
This article provides guidance on running Dapr in self-hosted mode without Docker.
## Prerequisites
-- [Dapr CLI](../../getting-started/environment-setup.md#installing-dapr-cli)
+- [Dapr CLI]({{< ref "install-dapr.md#installing-dapr-cli" >}})
## Initialize Dapr without containers
@@ -14,16 +20,16 @@ The Dapr CLI provides an option to initialize Dapr using slim init, without the
dapr init --slim
```
-In this mode two different binaries are installed `daprd` and `placement`. The `placement` binary is needed to enable [actors](../../concepts/actors/README.md) in a Dapr self-hosted installation.
+In this mode two different binaries are installed `daprd` and `placement`. The `placement` binary is needed to enable [actors]({{< ref "actors-overview.md" >}}) in a Dapr self-hosted installation.
-In this mode no default components such as Redis are installed for state management or pub/sub. This means, that aside from [Service Invocation](../../concepts/service-invocation/README.md), no other building block functionality is available on install out of the box. Users are free to setup their own environment and custom components. Furthermore, actor based service invocation is possible if a state store is configured as explained in the following sections.
+In this mode no default components such as Redis are installed for state management or pub/sub. This means, that aside from [Service Invocation]({{< ref "service-invocation-overview.md" >}}), no other building block functionality is available on install out of the box. Users are free to setup their own environment and custom components. Furthermore, actor based service invocation is possible if a state store is configured as explained in the following sections.
## Service invocation
See [this sample](https://github.com/dapr/samples/tree/master/hello-dapr-slim) for an example on how to perform service invocation in this mode.
## Enabling state management or pub/sub
-See configuring Redis in self hosted mode [without docker](../../howto/configure-redis/README.md#Self-Hosted-Mode-without-Containers) to enable a local state store or pub/sub broker for messaging.
+See configuring Redis in self hosted mode [without docker](https://redis.io/topics/quickstart) to enable a local state store or pub/sub broker for messaging.
## Enabling actors
@@ -60,4 +66,4 @@ INFO[0450] host removed: 192.168.1.6 instance=host.localhost
## Cleanup
-Follow the uninstall [instructions](../../getting-started/environment-setup.md#Uninstall-Dapr-in-self-hosted-mode-(without-docker)) to remove the binaries.
+Follow the uninstall [instructions]({{< ref "install-dapr.md#uninstall-dapr-in-a-self-hosted-mode" >}}) to remove the binaries.
diff --git a/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-overview.md b/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-overview.md
new file mode 100644
index 000000000..d149f91ea
--- /dev/null
+++ b/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-overview.md
@@ -0,0 +1,17 @@
+---
+type: docs
+title: "Overview of Dapr in self-hosted mode"
+linkTitle: "Overview"
+weight: 10000
+description: "Overview of how to get Dapr running on your local machine"
+---
+
+Dapr can be configured to run on your local developer machine in self hosted mode. Each running service has a Dapr runtime process (or sidecar) which is configured to use state stores, pub/sub, binding components and the other building blocks.
+
+In self hosted mode, Redis is running locally in a container and is configured to serve as both the default component for state store and for pub/sub. A Zipkin container is also configured for diagnostics and tracing. After running `dapr init`, see the `$HOME/.dapr/components` directory (Mac/Linux) or `%USERPROFILE%\.dapr\components` on Windows.
+
+The `dapr-placement` service is responsible for managing the actor distribution scheme and key range settings. This service is only required if you are using Dapr actors. For more information on the actor `Placement` service read [actor overview]({{< ref "actors-overview.md" >}}).
+
+
+
+You can use the [Dapr CLI](https://github.com/dapr/cli#launch-dapr-and-your-app) to run a Dapr enabled application on your local machine.
\ No newline at end of file
diff --git a/howto/run-with-docker/README.md b/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-with-docker.md
similarity index 86%
rename from howto/run-with-docker/README.md
rename to daprdocs/content/en/operations/hosting/self-hosted/self-hosted-with-docker.md
index 6aae859f7..28afed63b 100644
--- a/howto/run-with-docker/README.md
+++ b/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-with-docker.md
@@ -1,4 +1,11 @@
-# Run with Docker
+---
+type: docs
+title: "How-To: Run Dapr in self-hosted mode with Docker"
+linkTitle: "Run with Docker"
+weight: 20000
+description: "How to deploy and run Dapr in self-hosted mode using Docker"
+---
+
This article provides guidance on running Dapr with Docker outside of Kubernetes. There are a number of different configurations in which you may wish to run Dapr with Docker that are documented below.
## Prerequisites
@@ -28,7 +35,7 @@ There are published Docker images for each of the Dapr components available on [
- `major.minor.patch-arm`: A release version for ARM.
- `major.minor.patch-rc.iteration-arm`: A release candidate for ARM.
-## Run Dapr in a Docker container with an app as a process
+## Run app as a process
> For development purposes ONLY
If you are running Dapr in a Docker container and your app as a process on the host machine, then you need to configure
@@ -42,7 +49,7 @@ Then you can run your app on the host and they should connect over the localhost
However, if you are not running your Docker daemon on a Linux host, it is recommended you follow the steps below to run
both your app and the [Dapr runtime in Docker containers using Docker Compose](#run-dapr-in-a-docker-container-using-docker-compose).
-## Run Dapr and an app in a single Docker container
+## Run app and Dapr in a single Docker container
> For development purposes ONLY
It is not recommended to run both the Dapr runtime and an application inside the same container. However, it is possible to do so for local development scenarios.
@@ -71,7 +78,7 @@ CMD ["run", "--app-id", "nodeapp", "--app-port", "3000", "node", "app.js"]
Remember that if Dapr needs to communicate with other components i.e. Redis, these also need to
be made accessible to it.
-## Run Dapr in a Docker container on a Docker network
+## Run on a Docker network
If you have multiple instances of Dapr running in Docker containers and want them to be able to
communicate with each other i.e. for service invocation, then you'll need to create a shared Docker network
and make sure those Dapr containers are attached to it.
@@ -86,7 +93,7 @@ docker run --net=my-dapr-network ...
```
Each container will receive a unique IP on that network and be able to communicate with other containers on that network.
-## Run Dapr in a Docker container using Docker-Compose
+## Run using Docker-Compose
[Docker Compose](https://docs.docker.com/compose/) can be used to define multi-container application
configurations. If you wish to run multiple apps with Dapr sidecars locally without Kubernetes then it is recommended to use a Docker Compose definition (`docker-compose.yml`).
@@ -135,14 +142,8 @@ services:
To further learn how to run Dapr with Docker Compose, see the [Docker-Compose Sample](https://github.com/dapr/samples/tree/master/hello-docker-compose).
-## Run Dapr in a Docker container on Kubernetes
+## Run on Kubernetes
If your deployment target is Kubernetes then you're probably better of running your applicaiton and Dapr sidecars directly on
a Kubernetes platform. Running Dapr on Kubernetes is a first class experience and is documented separately. Please refer to the
-following references:
-- [Setup Dapr on a Kubernetes cluster](https://github.com/dapr/docs/blob/ea5b1918778a47555dbdccff0ed6c5b987ed10cf/getting-started/environment-setup.md#installing-dapr-on-a-kubernetes-cluster)
-- [Hello Kubernetes Sample](https://github.com/dapr/quickstarts/tree/master/hello-kubernetes)
-- [Configuring the Dapr sidecar on Kubernetes](https://github.com/dapr/docs/blob/c88d247a2611d6824d41bb5b6adfeb38152dbbc6/howto/configure-k8s/README.md)
-- [Running Dapr in Kubernetes mode](https://github.com/dapr/docs/blob/a7668cab5e16d12f364a42d2fe7d75933c6398e9/overview/README.md#running-dapr-in-kubernetes-mode)
+[Dapr on Kubernetes docs]({{< ref "kubernetes-overview.md" >}})
-## Related links
-- [Docker-Compose Sample](https://github.com/dapr/samples/hello-docker-compose)
diff --git a/daprdocs/content/en/operations/monitoring/_index.md b/daprdocs/content/en/operations/monitoring/_index.md
new file mode 100644
index 000000000..9f5489d92
--- /dev/null
+++ b/daprdocs/content/en/operations/monitoring/_index.md
@@ -0,0 +1,7 @@
+---
+type: docs
+title: "Monitor your application with Dapr"
+linkTitle: "Monitoring"
+weight: 400
+description: "How to monitor your application using Dapr integrations"
+---
\ No newline at end of file
diff --git a/howto/setup-monitoring-tools/setup-azure-monitor.md b/daprdocs/content/en/operations/monitoring/azure-monitor.md
similarity index 86%
rename from howto/setup-monitoring-tools/setup-azure-monitor.md
rename to daprdocs/content/en/operations/monitoring/azure-monitor.md
index 9bb9194e5..a15ce60ad 100644
--- a/howto/setup-monitoring-tools/setup-azure-monitor.md
+++ b/daprdocs/content/en/operations/monitoring/azure-monitor.md
@@ -1,6 +1,10 @@
-# Set up Azure Monitor to search logs and collect metrics
-
-This document describes how to enable Dapr metrics and logs with Azure Monitor for Azure Kubernetes Service (AKS).
+---
+type: docs
+title: "How-To: Set up Azure Monitor to search logs and collect metrics"
+linkTitle: "Azure Monitor"
+weight: 2000
+description: "Enable Dapr metrics and logs with Azure Monitor for Azure Kubernetes Service (AKS)"
+---
## Prerequisites
@@ -9,12 +13,6 @@ This document describes how to enable Dapr metrics and logs with Azure Monitor f
- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
- [Helm 3](https://helm.sh/)
-## Contents
-
- - [Enable Prometheus metric scrape using config map](#enable-prometheus-metric-scrape-using-config-map)
- - [Install Dapr with JSON formatted logs](#install-dapr-with-json-formatted-logs)
- - [Search metrics and logs with Azure Monitor](#Search-metrics-and-logs-with-azure-monitor)
-
## Enable Prometheus metric scrape using config map
1. Make sure that omsagnets are running
@@ -32,9 +30,9 @@ omsagent-smtk7 1/1 Runnin
2. Apply config map to enable Prometheus metrics endpoint scrape.
-You can use [azm-config-map.yaml](./azm-config-map.yaml) to enable prometheus metrics endpoint scrape.
+You can use [azm-config-map.yaml](/docs/azm-config-map.yaml) to enable prometheus metrics endpoint scrape.
-If you installed Dapr to the different namespace, you need to change the `monitor_kubernetes_pod_namespaces` array values. For example;
+If you installed Dapr to the different namespace, you need to change the `monitor_kubernetes_pod_namespaces` array values. For example:
```yaml
...
@@ -50,7 +48,7 @@ If you installed Dapr to the different namespace, you need to change the `monito
Apply config map:
-```
+```bash
kubectl apply -f ./azm-config.map.yaml
```
diff --git a/howto/setup-monitoring-tools/setup-fluentd-es-kibana.md b/daprdocs/content/en/operations/monitoring/fluentd.md
similarity index 71%
rename from howto/setup-monitoring-tools/setup-fluentd-es-kibana.md
rename to daprdocs/content/en/operations/monitoring/fluentd.md
index 041d7cf0e..134ec35a4 100644
--- a/howto/setup-monitoring-tools/setup-fluentd-es-kibana.md
+++ b/daprdocs/content/en/operations/monitoring/fluentd.md
@@ -1,6 +1,10 @@
-# Set up Fluentd, Elastic search and Kibana in Kubernetes
-
-This document descriebs how to install Fluentd, Elastic Search, and Kibana to search logs in Kubernetes
+---
+type: docs
+title: "How-To: Set up Fluentd, Elastic search and Kibana in Kubernetes"
+linkTitle: "FluentD"
+weight: 1000
+description: "How to install Fluentd, Elastic Search, and Kibana to search logs in Kubernetes"
+---
## Prerequisites
@@ -8,33 +12,27 @@ This document descriebs how to install Fluentd, Elastic Search, and Kibana to se
- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
- [Helm 3](https://helm.sh/)
-## Contents
-
- - [Install Fluentd, Elastic Search, and Kibana](#install-fluentd-elastic-search-and-kibana)
- - [Install Fluentd](#install-fluentd)
- - [Install Dapr with JSON formatted logs](#install-dapr-with-json-formatted-logs)
- - [Search logs](#search-logs)
## Install Elastic search and Kibana
1. Create namespace for monitoring tool and add Helm repo for Elastic Search
-```bash
-kubectl create namespace dapr-monitoring
-```
+ ```bash
+ kubectl create namespace dapr-monitoring
+ ```
2. Add Elastic helm repo
-```bash
-helm repo add elastic https://helm.elastic.co
-helm repo update
-```
+ ```bash
+ helm repo add elastic https://helm.elastic.co
+ helm repo update
+ ```
3. Install Elastic Search using Helm
By default the chart creates 3 replicas which must be on different nodes. If your cluster has less than 3 nodes, specify a lower number of replicas. For example, this sets it to 1:
-```
+```bash
helm install elasticsearch elastic/elasticsearch -n dapr-monitoring --set replicas=1
```
@@ -44,40 +42,41 @@ Otherwise:
helm install elasticsearch elastic/elasticsearch -n dapr-monitoring
```
-If you are using minikube or want to disable persistent volumes for development purposes, you can disable it by using the following command.
+If you are using minikube or want to disable persistent volumes for development purposes, you can disable it by using the following command:
+
```bash
helm install elasticsearch elastic/elasticsearch -n dapr-monitoring --set persistence.enabled=false --replicas=1
```
4. Install Kibana
-```bash
-helm install kibana elastic/kibana -n dapr-monitoring
-```
+ ```bash
+ helm install kibana elastic/kibana -n dapr-monitoring
+ ```
5. Validation
-Ensure Elastic Search and Kibana are running in your Kubernetes cluster.
-
-```bash
-kubectl get pods -n dapr-monitoring
-NAME READY STATUS RESTARTS AGE
-elasticsearch-master-0 1/1 Running 0 6m58s
-kibana-kibana-95bc54b89-zqdrk 1/1 Running 0 4m21s
-```
+ Ensure Elastic Search and Kibana are running in your Kubernetes cluster.
+
+ ```bash
+ kubectl get pods -n dapr-monitoring
+ NAME READY STATUS RESTARTS AGE
+ elasticsearch-master-0 1/1 Running 0 6m58s
+ kibana-kibana-95bc54b89-zqdrk 1/1 Running 0 4m21s
+ ```
## Install Fluentd
1. Install config map and Fluentd as a daemonset
-Navigate to the following path if you're not already there (the one this document is in):
-
-```
-docs/howto/setup-monitoring-tools
-```
+Download these config files:
+- [fluentd-config-map.yaml](/docs/fluentd-config-map.yaml)
+- [fluentd-dapr-with-rbac.yaml](/docs/fluentd-dapr-with-rbac.yaml)
> Note: If you already have Fluentd running in your cluster, please enable the nested json parser to parse JSON formatted log from Dapr.
+Apply the configurations to your cluster:
+
```bash
kubectl apply -f ./fluentd-config-map.yaml
kubectl apply -f ./fluentd-dapr-with-rbac.yaml
@@ -99,11 +98,11 @@ fluentd-sdrld 1/1 Running 0 14s
1. Install Dapr with enabling JSON-formatted logs
-```bash
-helm repo add dapr https://dapr.github.io/helm-charts/
-helm repo update
-helm install dapr dapr/dapr --namespace dapr-system --set global.logAsJson=true
-```
+ ```bash
+ helm repo add dapr https://dapr.github.io/helm-charts/
+ helm repo update
+ helm install dapr dapr/dapr --namespace dapr-system --set global.logAsJson=true
+ ```
2. Enable JSON formatted log in Dapr sidecar
@@ -152,37 +151,37 @@ Handling connection for 5601
3. Click Management -> Index Management
-
+
4. Wait until dapr-* is indexed.
-
+
5. Once dapr-* indexed, click Kibana->Index Patterns and Create Index Pattern
-
+
6. Define index pattern - type `dapr*` in index pattern
-
+
7. Select time stamp filed: `@timestamp`
-
+
8. Confirm that `scope`, `type`, `app_id`, `level`, etc are being indexed.
> Note: if you cannot find the indexed field, please wait. it depends on the volume of data and resource size where elastic search is running.
-
+
9. Click `discover` icon and search `scope:*`
> Note: it would take some time to make log searchable based on the data volume and resource.
-
+
-# References
+## References
* [Fluentd for Kubernetes](https://docs.fluentd.org/v/0.12/articles/kubernetes-fluentd)
* [Elastic search helm chart](https://github.com/elastic/helm-charts/tree/master/elasticsearch)
diff --git a/daprdocs/content/en/operations/monitoring/grafana.md b/daprdocs/content/en/operations/monitoring/grafana.md
new file mode 100644
index 000000000..d1c21917f
--- /dev/null
+++ b/daprdocs/content/en/operations/monitoring/grafana.md
@@ -0,0 +1,140 @@
+---
+type: docs
+title: "How-To: Observe metrics with Grafana"
+linkTitle: "Grafana"
+weight: 5000
+description: "How to view Dapr metrics in a Grafana dashboard."
+---
+
+## Pre-requisites
+
+- [Setup Prometheus]({{}})
+
+## Setup on Kubernetes
+
+### Install Grafana
+
+1. Install Grafana
+
+ ```bash
+ helm install grafana stable/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:
+
+ ```bash
+ helm install grafana stable/grafana -n dapr-monitoring --set persistence.enabled=false
+ ```
+
+2. Retrieve the admin password for Grafana login
+
+ ```bash
+ kubectl get secret --namespace dapr-monitoring grafana -o jsonpath="{. data.admin-password}" | base64 --decode
+ cj3m0OfBNx8SLzUlTx91dEECgzRlYJb60D2evof1%
+ ```
+
+ {{% alert title="Note" color="info" %}}
+ Remove the `%` character from the password that this command returns. For example, the admin password is `cj3m0OfBNx8SLzUlTx91dEECgzRlYJb60D2evof1`.
+ {{% /alert %}}
+
+3. Validation
+
+ Ensure Grafana is running in your cluster (see last line below)
+
+ ```bash
+ kubectl get pods -n dapr-monitoring
+
+ NAME READY STATUS RESTARTS AGE
+ dapr-prom-kube-state-metrics-9849d6cc6-t94p8 1/1 Running 0 4m58s
+ dapr-prom-prometheus-alertmanager-749cc46f6-9b5t8 2/2 Running 0 4m58s
+ dapr-prom-prometheus-node-exporter-5jh8p 1/1 Running 0 4m58s
+ dapr-prom-prometheus-node-exporter-88gbg 1/1 Running 0 4m58s
+ dapr-prom-prometheus-node-exporter-bjp9f 1/1 Running 0 4m58s
+ dapr-prom-prometheus-pushgateway-688665d597-h4xx2 1/1 Running 0 4m58s
+ dapr-prom-prometheus-server-694fd8d7c-q5d59 2/2 Running 0 4m58s
+ grafana-c49889cff-x56vj 1/1 Running 0 5m10s
+ ```
+
+### Configure Prometheus as data source
+First you need to connect Prometheus as a data source to Grafana.
+
+1. Port-forward to svc/grafana
+
+ ```bash
+ $ 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`
+
+3. Login with admin and password
+
+4. Click Configuration Settings -> Data Sources
+
+ 
+
+5. Add Prometheus as a data soruce.
+
+ 
+
+6. Enter Promethesus server address in your cluster.
+
+ You can get the Prometheus server address by running the following command.
+
+ ```bash
+ kubectl get svc -n dapr-monitoring
+
+ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
+ dapr-prom-kube-state-metrics ClusterIP 10.0.174.177 - "
- # authStyle:
- # "0" means to auto-detect which authentication
- # style the provider wants by trying both ways and caching
- # the successful way for the future.
-
- # "1" sends the "client_id" and "client_secret"
- # in the POST body as application/x-www-form-urlencoded parameters.
-
- # "2" sends the client_id and client_password
- # using HTTP Basic Authorization. This is an optional style
- # described in the OAuth2 RFC 6749 section 2.3.1.
- - name: authStyle
- value: "
- "
+ # authStyle:
+ # "0" means to auto-detect which authentication
+ # style the provider wants by trying both ways and caching
+ # the successful way for the future.
+
+ # "1" sends the "client_id" and "client_secret"
+ # in the POST body as application/x-www-form-urlencoded parameters.
+
+ # "2" sends the client_id and client_password
+ # using HTTP Basic Authorization. This is an optional style
+ # described in the OAuth2 RFC 6749 section 2.3.1.
+ - name: authStyle
+ value: "
+```yaml
annotations:
dapr.io/enabled: "true"
dapr.io/app-id: "nodeapp"
- dapr.io/app-port: "3000"
-
+ dapr.io/app-port: "3000"
+```
If using Dapr Standalone and the Dapr CLI, make sure you pass the `--app-port` flag to the `dapr run` command.
-### My Dapr-enabled app isn't behaving correctly
+## My Dapr-enabled app isn't behaving correctly
The first thing to do is inspect the HTTP error code returned from the Dapr API, if any.
-If you still can't find the issue, try enabling `debug` log levels for the Dapr runtime. See [here](logs.md) how to do so.
+If you still can't find the issue, try enabling `debug` log levels for the Dapr runtime. See [here]({{< ref "logs.md" >}}) how to do so.
You might also want to look at error logs from your own process. If running on Kubernetes, find the pod containing your app, and execute the following:
@@ -176,7 +180,7 @@ kubectl logs -annotations: - dapr.io/enabled: "true" - dapr.io/app-id: "rust-app" - dapr.io/enable-profiling: "true" -- -### Standalone - -To enable profiling in Standalone mode, pass the `enable-profiling` and the `profile-port` flags to the Dapr CLI: -Note that `profile-port` is not required, and Dapr will pick an available port. +To enable profiling in Standalone mode, pass the `--enable-profiling` and the `--profile-port` flags to the Dapr CLI: +Note that `profile-port` is not required, and if not provided Dapr will pick an available port. ```bash dapr run --enable-profiling true --profile-port 7777 python myapp.py ``` +### Kubernetes + +To enable profiling in Kubernetes, simply add the `dapr.io/enable-profiling` annotation to your Dapr annotated pod: + +```yml + annotations: + dapr.io/enabled: "true" + dapr.io/app-id: "rust-app" + dapr.io/enable-profiling: "true" +``` + ## Debug a profiling session After profiling is enabled, we can start a profiling session to investigate what's going on with the Dapr runtime. +### Stand-alone + +For Standalone mode, locate the Dapr instance that you want to profile: + +```bash +dapr list +APP ID DAPR PORT APP PORT COMMAND AGE CREATED PID +node-subscriber 3500 3000 node app.js 12s 2019-09-09 15:11.24 896 +``` + +Grab the DAPR PORT, and if profiling has been enabled as described above, you can now start using `pprof` to profile Dapr. +Look at the Kubernetes examples above for some useful commands to profile Dapr. + +More info on pprof can be found [here](https://github.com/google/pprof). + ### Kubernetes First, find the pod containing the Dapr runtime. If you don't already know the the pod name, type `kubectl get pods`: @@ -82,7 +103,7 @@ For memory related issues, you can profile the heap: go tool pprof --pdf your-binary-file http://localhost:7777/debug/pprof/heap > heap.pdf ``` - + Profiling allocated objects: @@ -99,19 +120,4 @@ To analyze, grab the file path above (its a dynamic file path, so pay attention go tool pprof -alloc_objects --pdf /Users/myusername/pprof/pprof.daprd.alloc_objects.alloc_space.inuse_objects.inuse_space.003.pb.gz > alloc-objects.pdf ``` - - -### Standalone - -For Standalone mode, locate the Dapr instance that you want to profile: - -```bash -dapr list -APP ID DAPR PORT APP PORT COMMAND AGE CREATED PID -node-subscriber 3500 3000 node app.js 12s 2019-09-09 15:11.24 896 -``` - -Grab the DAPR PORT, and if profiling has been enabled as described above, you can now start using `pprof` to profile Dapr. -Look at the Kubernetes examples above for some useful commands to profile Dapr. - -More info on pprof can be found [here](https://github.com/google/pprof). + diff --git a/best-practices/troubleshooting/tracing.md b/daprdocs/content/en/operations/troubleshooting/setup-tracing.md similarity index 65% rename from best-practices/troubleshooting/tracing.md rename to daprdocs/content/en/operations/troubleshooting/setup-tracing.md index a58193839..afdbc8eb7 100644 --- a/best-practices/troubleshooting/tracing.md +++ b/daprdocs/content/en/operations/troubleshooting/setup-tracing.md @@ -1,11 +1,77 @@ -# Tracing +--- +type: docs +title: "Tracing" +linkTitle: "Tracing" +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. -## Distributed Tracing with Zipkin on Kubernetes +## Tracing configuration + +The `tracing` section under the `Configuration` spec contains the following properties: + +```yml +tracing: + enabled: true + exporterType: zipkin + exporterAddress: "" + expandParams: true + includeBody: true +``` + +The following table lists the different properties. + +| 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 + + +## Zipkin in stand-alone mode + +The following steps show you how to configure Dapr to send distributed tracing data to Zipkin running as a container on your local machine and view them. + +For Standalone mode, create a Dapr configuration file locally and reference it with the Dapr CLI. + +1. Create the following YAML file: + + ```yaml + apiVersion: dapr.io/v1alpha1 + kind: Configuration + metadata: + name: zipkin + namespace: default + spec: + tracing: + enabled: true + exporterType: zipkin + exporterAddress: "http://localhost:9411/api/v2/spans" + expandParams: true + includeBody: true + ``` + +2. Launch Zipkin using Docker: + + ```bash + docker run -d -p 9411:9411 openzipkin/zipkin + ``` + +3. Launch Dapr with the `--config` param: + + ```bash + dapr run --app-id mynode --app-port 3000 --config ./config.yaml node app.js + ``` + + +## Zipkin in Kubernetes mode The following steps show you how to configure Dapr to send distributed tracing data to Zipkin running as a container in your Kubernetes cluster, and how to view them. @@ -65,62 +131,5 @@ kubectl port-forward svc/zipkin 9411:9411 On your browser, go to ```http://localhost:9411``` and you should see the Zipkin UI. - + -## Distributed Tracing with Zipkin - Standalone Mode - -The following steps show you how to configure Dapr to send distributed tracing data to Zipkin running as a container on your local machine and view them. - -For Standalone mode, create a Dapr configuration file locally and reference it with the Dapr CLI. - -1. Create the following YAML file: - -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Configuration -metadata: - name: zipkin - namespace: default -spec: - tracing: - enabled: true - exporterType: zipkin - exporterAddress: "http://localhost:9411/api/v2/spans" - expandParams: true - includeBody: true -``` - -2. Launch Zipkin using Docker: - -```bash -docker run -d -p 9411:9411 openzipkin/zipkin -``` - -3. Launch Dapr with the `--config` param: - -```bash -dapr run --app-id mynode --app-port 3000 --config ./config.yaml node app.js -``` - -## Tracing Configuration - -The `tracing` section under the `Configuration` spec contains the following properties: - -```yml -tracing: - enabled: true - exporterType: zipkin - exporterAddress: "" - expandParams: true - includeBody: true -``` - -The following table lists the different properties. - -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 diff --git a/daprdocs/content/en/reference/_index.md b/daprdocs/content/en/reference/_index.md new file mode 100644 index 000000000..7908b27c5 --- /dev/null +++ b/daprdocs/content/en/reference/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Dapr Reference Docs" +linkTitle: "Reference" +weight: 60 +description: "Detailed documentation on the Dapr API, CLI, bindings and more" +--- diff --git a/daprdocs/content/en/reference/api/_index.md b/daprdocs/content/en/reference/api/_index.md new file mode 100644 index 000000000..03c8a9be6 --- /dev/null +++ b/daprdocs/content/en/reference/api/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: Dapr API reference +linkTitle: "Dapr API" +weight: 100 +description: "Information on each api, the associated endpoints, and what capabilities are available" +--- diff --git a/reference/api/actors_api.md b/daprdocs/content/en/reference/api/actors_api.md similarity index 91% rename from reference/api/actors_api.md rename to daprdocs/content/en/reference/api/actors_api.md index 7f4da8f76..78c30d1e2 100644 --- a/reference/api/actors_api.md +++ b/daprdocs/content/en/reference/api/actors_api.md @@ -1,28 +1,14 @@ -# Dapr actors API reference +--- +type: docs +title: "Actors API reference" +linkTitle: "Actors API" +description: "Detailed documentation on the actors API" +weight: 500 +--- Dapr provides native, cross-platform and cross-language virtual actor capabilities. Besides the language specific Dapr SDKs, a developer can invoke an actor using the API endpoints below. -## Endpoints - -- [Service Code Calling to Dapr](#specifications-for-user-service-code-calling-to-dapr) - - [Invoke Actor Method](#invoke-actor-method) - - [Actor State Transactions](#actor-state-transactions) - - [Get Actor State](#get-actor-state) - - [Create Actor Reminder](#create-actor-reminder) - - [Get Actor Reminder](#get-actor-reminder) - - [Delete Actor Reminder](#delete-actor-reminder) - - [Create Actor Timer](#create-actor-timer) - - [Delete Actor Timer](#delete-actor-timer) -- [Dapr Calling to Service Code](#specifications-for-dapr-calling-to-user-service-code) - - [Get Registered Actors](#get-registered-actors) - - [Deactivate Actor](#deactivate-actor) - - [Invoke Actor Method](#invoke-actor-method-1) - - [Invoke Reminder](#invoke-reminder) - - [Invoke Timer](#invoke-timer) - - [Health Checks](#health-check) -- [Querying Actor State Externally](#querying-actor-state-externally) - ## User service code calling dapr ### Invoke actor method @@ -31,7 +17,7 @@ Invoke an actor method through Dapr. #### HTTP Request -```http +``` POST/GET/PUT/DELETE http://localhost: