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

Merge branch 'v1.8' into override_default_retries

This commit is contained in:
Mark Fussell 2022-07-06 13:06:03 -07:00 committed by GitHub
parent dbf836943a 8eeaf204dc
commit ac5a5371e5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
16 changed files with 496 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
daprdocs/content/en/concepts/dapr-services/operator.md
View File

@ -9,4 +9,43 @@ When running Dapr in [Kubernetes mode]({{< ref kubernetes >}}), a pod running th
## Running the operator service
The operator service is deployed as part of `dapr init -k`, or via the Dapr Helm charts. For more information on running Dapr on Kubernetes, visit the [Kubernetes hosting page]({{< ref kubernetes >}}).
The operator service is deployed as part of `dapr init -k`, or via the Dapr Helm charts. For more information on running Dapr on Kubernetes, visit the [Kubernetes hosting page]({{< ref kubernetes >}}).
## Additional configuration options
The operator service includes additional configuration options.
### Injector watchdog
The operator service includes an _injector watchdog_ feature which periodically polls all pods running in your Kubernetes cluster and confirms that the Dapr sidecar is injected in those which have the `dapr.io/enabled=true` annotation. It is primarily meant to address situations where the [Injector service]({{< ref sidecar-injector >}}) did not successfully inject the sidecar (the `daprd` container) into pods.
The injector watchdog can be useful in a few situations, including:
- Recovering from a Kubernetes cluster completely stopped. When a cluster is completely stopped and then restarted (including in the case of a total cluster failure), pods are restarted in a random order. If your application is restarted before the Dapr control plane (specifically the Injector service) is ready, the Dapr sidecar may not be injected into your application's pods, causing your application to behave unexpectedly.
- Addressing potential random failures with the sidecar injector, such as transient failures within the Injector service.
If the watchdog detects a pod that does not have a sidecar when it should have had one, it deletes it. Kubernetes will then re-create the pod, invoking the Dapr sidecar injector again.
The injector watchdog feature is **disabled by default**.
You can enable it by passing the `--watch-interval` flag to the `operator` command, which can take one of the following values:
- `--watch-interval=0`: disables the injector watchdog (default value if the flag is omitted).
- `--watch-interval=<interval>`: the injector watchdog is enabled and polls all pods at the given interval; the value for the interval is a string that includes the unit. For example: `--watch-interval=10s` (every 10 seconds) or `--watch-interval=2m` (every 2 minutes).
- `--watch-interval=once`: the injector watchdog runs only once when the operator service is started.
If you're using Helm, you can configure the injector watchdog with the [`dapr_operator.watchInterval` option](https://github.com/dapr/dapr/blob/master/charts/dapr/README.md#dapr-operator-options), which has the same values as the command line flags.
> The injector watchdog is safe to use when the operator service is running in HA (High Availability) mode with more than one replica. In this case, Kubernetes automatically elects a "leader" instance which is the only one that runs the injector watchdog service.
> However, when in HA mode, if you configure the injector watchdog to run "once", the watchdog polling is actually started every time an instance of the operator service is elected as leader. This means that, should the leader of the operator service crash and a new leader be elected, that would trigger the injector watchdog again.
Watch this video for an overview of the injector watchdog:
<div class="embed-responsive embed-responsive-16by9">
<iframe width="360" height="315" src="https://www.youtube-nocookie.com/embed/ecFvpp24lpo?start=1848" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

48
daprdocs/content/en/developing-applications/building-blocks/actors/howto-actors.md
View File

@ -288,22 +288,15 @@ Refer to the documentation and examples of the [Dapr SDKs]({{< ref "developing-a
## Partitioning reminders
{{% alert title="Preview feature" color="warning" %}}
Actor reminders partitioning is currently in [preview]({{< ref preview-features.md >}}). Use this feature if you are runnining into issues due to a high number of reminders registered.
{{% /alert %}}
Actor reminders are persisted and continue to be triggered after sidecar restarts. Applications with multiple reminders registered can experience the following issues:
Actor reminders are persisted and continue to be triggered after sidecar restarts. Prior to Dapr runtime version 1.3, reminders were persisted on a single record in the actor state store:
- Low throughput on reminders registration and de-registration
- Limit on the total number of reminders registered based on the single record size limit on the state store
| Key | Value |
| ----------- | ----------- |
| `actors\|\|<actor type>` | `[ <reminder 1>, <reminder 2>, ... , <reminder n> ]` |
Applications can enable partitioning of actor reminders while data is distributed in multiple keys in the state store.
Applications that register many reminders can experience the following issues:
* Low throughput on reminders registration and deregistration
* Limit on total number of reminders registered based on the single record size limit on the state store
Since version 1.3, applications can now enable partitioning of actor reminders in the state store. As data is distributed in multiple keys in the state store. First, there is a metadata record in `actors\|\|<actor type>\|\|metadata` that is used to store persisted configuration for a given actor type. Then, there are multiple records that stores subsets of the reminders for the same actor type.
1. A metadata record in `actors\|\|<actor type>\|\|metadata` is used to store persisted configuration for a given actor type.
1. Multiple records store subsets of the reminders for the same actor type.
| Key | Value |
| ----------- | ----------- |
@ -312,16 +305,18 @@ Since version 1.3, applications can now enable partitioning of actor reminders i
| `actors\|\|<actor type>\|\|<actor metadata identifier>\|\|reminders\|\|2` | `[ <reminder 1-1>, <reminder 1-2>, ... , <reminder 1-m> ]` |
| ... | ... |
If the number of partitions is not enough, it can be changed and Dapr's sidecar will automatically redistribute the reminders's set.
If you need to change the number of partitions, Dapr's sidecar will automatically redistribute the reminders's set.
### Enabling actor reminders partitioning
#### Actor runtime configuration for actor reminders partitioning
First, the actor runtime must provide the appropriate configuration to partition actor reminders. This is done by the actor's endpoint for `GET /dapr/config`, similar to other actor configuration elements.
Similar to other actor configuration elements, the actor runtime provides the appropriate configuration to partition actor reminders via the actor's endpoint for `GET /dapr/config`.
{{< tabs Java Dotnet Python Go >}}
{{% codetab %}}
```java
// import io.dapr.actors.runtime.ActorRuntime;
// import java.time.Duration;
@ -331,10 +326,11 @@ ActorRuntime.getInstance().getConfig().setActorScanInterval(Duration.ofSeconds(3
ActorRuntime.getInstance().getConfig().setRemindersStoragePartitions(7);
```
See [this example](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/actors/DemoActorService.java)
For more information, see [the Java actors example](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/actors/DemoActorService.java)
{{% /codetab %}}
{{% codetab %}}
```csharp
// In Startup.cs
public void ConfigureServices(IServiceCollection services)
@ -356,10 +352,12 @@ public void ConfigureServices(IServiceCollection services)
services.AddSingleton<BankService>();
}
```
See the .NET SDK [documentation](https://github.com/dapr/dotnet-sdk/blob/master/daprdocs/content/en/dotnet-sdk-docs/dotnet-actors/dotnet-actors-usage.md#registering-actors).
See the .NET SDK [documentation for registering actors](https://github.com/dapr/dotnet-sdk/blob/master/daprdocs/content/en/dotnet-sdk-docs/dotnet-actors/dotnet-actors-usage.md#registering-actors).
{{% /codetab %}}
{{% codetab %}}
```python
from datetime import timedelta
@ -371,9 +369,11 @@ ActorRuntime.set_actor_config(
)
)
```
{{% /codetab %}}
{{% codetab %}}
```go
type daprConfig struct {
Entities []string `json:"entities,omitempty"`
@ -399,11 +399,12 @@ func configHandler(w http.ResponseWriter, r *http.Request) {
json.NewEncoder(w).Encode(daprConfigResponse)
}
```
{{% /codetab %}}
{{< /tabs >}}
The following, is an example of a valid configuration for reminder partitioning:
The following is an example of a valid configuration for reminder partitioning:
```json
{
@ -413,7 +414,14 @@ The following, is an example of a valid configuration for reminder partitioning:
```
#### Handling configuration changes
To configure actor reminders partitioning, Dapr persists the actor type metadata in the actor's state store. This allows the configuration changes to be applied globally and not only in a single sidecar instance. Also the **number of partitions can only be increased and not decreased**. This allows Dapr to automatically redistribute the data on a rolling restart where one or more partition configurations might be active.
To configure actor reminders partitioning, Dapr persists the actor type metadata in the actor's state store. This allows the configuration changes to be applied globally, not just in a single sidecar instance.
Also, **you can only increase the number of partitions**, not decrease. This allows Dapr to automatically redistribute the data on a rolling restart where one or more partition configurations might be active.
#### Demo
* [Actor reminder partitioning presented in community call](https://youtu.be/ZwFOEUYe1WA?t=1493)
Watch [this video for a demo of actor reminder partitioning](https://youtu.be/ZwFOEUYe1WA?t=1493):
<div class="embed-responsive embed-responsive-16by9">
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/ZwFOEUYe1WA?start=1495" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

8
daprdocs/content/en/developing-applications/building-blocks/distributed-lock/distributed-lock-api-overview.md
View File

@ -37,7 +37,15 @@ At any given moment, only one instance of an application can hold a named lock.
### Deadlock free using leases
Dapr distributed locks use a lease-based locking mechanism. If an application acquires a lock, encounters an exception, and cannot free the lock, the lock is automatically released after a period of time using a lease. This prevents resource deadlocks in the event of application failures.
## Demo
Watch [this video for an overview of the distributed lock API](https://youtu.be/wLYYOJLt_KQ?t=583):
<div class="embed-responsive embed-responsive-16by9">
<iframe width="360" height="315" src="https://www.youtube-nocookie.com/embed/wLYYOJLt_KQ?start=583" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
## Next steps
Follow these guides on:
- [How-To: Use distributed locks in your application]({{< ref howto-use-distributed-lock.md >}})

151
daprdocs/content/en/developing-applications/building-blocks/distributed-lock/howto-use-distributed-lock.md
View File

@ -6,11 +6,19 @@ weight: 2000
description: "Learn how to use distributed locks to provide exclusive access to a resource"
---
Now that you've learned what the Dapr distributed lock API building block provides, learn how it can work in your service. The example below describes an application that aquires a lock. This example uses the Redis lock component to demonstrate how to lock resources.
Now that you've learned what the Dapr distributed lock API building block provides, learn how it can work in your service. The example below describes an application that aquires a lock. This example uses the Redis lock component to demonstrate how to lock resources. For a list of supported lock stores, see [this list](/reference/components-reference/supported-locks/).
The diagram below shows two instances of the same application acquiring a lock, where one instance is successful and the other is denied.
<img src="/images/building-block-lock-example.png" width=1000 alt="The diagram below shows two instances of the same application acquiring a lock, where one instance is successful and the other is denied">
The diagram below shows two instances of the same application, where one instance releases the lock and the other instance is then able to acquire the lock.
<img src="/images/building-block-lock-example.png" width=1000 alt="Diagram showing aquiring a lock from multiple instances of same application">
<img src="/images/building-block-lock-unlock-example.png" width=1000 alt="Diagram showing releasing a lock from multiple instances of same application">
<img src="/images/building-block-lock-multiple-example.png" width=1000 alt="Diagram showing aquiring multiple locks from different applications">
The diagram below shows two instances of different applications, acquiring different locks on the same resource.
<img src="/images/building-block-lock-multiple-example.png" width=1000 alt="The diagram below shows two instances of different applications, acquiring different locks on the same resource">
### Configure a lock component
@ -20,7 +28,7 @@ Save the following component file to the [default components folder]({{< ref "in
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: lock
name: lockstore
spec:
type: lock.redis
metadata:
@ -30,37 +38,154 @@ spec:
value: <PASSWORD>
```
### Get configuration items using Dapr SDKs
### Acquire lock
{{< tabs Dotnet Java Python>}}
{{< tabs HTTP Dotnet Go >}}
{{% codetab %}}
```bash
curl -X POST http://localhost:3500/v1.0-alpha1/lock/lockstore
-H 'Content-Type: application/json'
-d '{"resourceId":"my_file_name", "lockOwner":"random_id_abc123", "expiryInSeconds": 60}'
```
{{% /codetab %}}
{{% codetab %}}
```csharp
using System;
using Dapr.Client;
namespace LockService
{
class Program
{
static async Task Main(string[] args)
{
string DAPR_LOCK_NAME = "lockstore";
var client = new DaprClientBuilder().Build();
using (var fileLock = await client.Lock(DAPR_LOCK_NAME, "my_file_name", "random_id_abc123", 60))
{
if (fileLock.Success)
{
Console.WriteLine("Success");
}
else
{
Console.WriteLine($"Failed to lock {fileName}.");
}
}
}
}
}
```
{{% /codetab %}}
{{% codetab %}}
```java
```go
package main
```
import (
"fmt"
{{% /codetab %}}
dapr "github.com/dapr/go-sdk/client"
)
{{% codetab %}}
```python
func main() {
client, err := dapr.NewClient()
if err != nil {
panic(err)
}
defer client.Close()
resp, err := client.TryLockAlpha1(ctx, "lockstore", &dapr.LockRequest{
LockOwner: "random_id_abc123",
ResourceID: "my_file_name",
ExpiryInSeconds: 60,
})
fmt.Println(resp.Success)
}
```
{{% /codetab %}}
{{< /tabs >}}
### Unlock existing lock
{{< tabs HTTP Dotnet Go >}}
{{% codetab %}}
```bash
curl -X POST http://localhost:3500/v1.0-alpha1/unlock/lockstore
-H 'Content-Type: application/json'
-d '{"resourceId":"my_file_name", "lockOwner":"random_id_abc123"}'
```
{{% /codetab %}}
{{% codetab %}}
```csharp
using System;
using Dapr.Client;
namespace LockService
{
class Program
{
static async Task Main(string[] args)
{
string DAPR_LOCK_NAME = "lockstore";
var client = new DaprClientBuilder().Build();
var response = await client.Unlock(DAPR_LOCK_NAME, "my_file_name", "random_id_abc123"));
Console.WriteLine(response.LockStatus);
}
}
}
```
{{% /codetab %}}
{{% codetab %}}
```go
package main
import (
"fmt"
dapr "github.com/dapr/go-sdk/client"
)
func main() {
client, err := dapr.NewClient()
if err != nil {
panic(err)
}
defer client.Close()
resp, err := client.UnlockAlpha1(ctx, "lockstore", &UnlockRequest{
LockOwner: "random_id_abc123",
ResourceID: "my_file_name",
})
fmt.Println(resp.Status)
}
```
{{% /codetab %}}
{{< /tabs >}}
## Next steps
* Read [distributed lock API overview]({{< ref distributed-lock-api-overview.md >}})
* Read [distributed lock API overview]({{< ref distributed-lock-api-overview.md >}})

13
daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-deadletter.md
View File

@ -98,5 +98,14 @@ scopes:
- checkout
```
For more information on resiliency policies, read [Resiliency overview]({{< ref resiliency-overview.md >}}).
For more information on topic subscriptions, read [Declarative and programmatic subscription methods]({{< ref "pubsub-overview.md#message-subscription" >}}).
## Demo
Watch [this video for an overview of the dead letter topics](https://youtu.be/wLYYOJLt_KQ?t=69):
<iframe width="360" height="315" src="https://www.youtube-nocookie.com/embed/wLYYOJLt_KQ?start=69" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
## Next steps
- For more information on resiliency policies, read [Resiliency overview]({{< ref resiliency-overview.md >}}).
- For more information on topic subscriptions, read [Declarative and programmatic subscription methods]({{< ref "pubsub-overview.md#message-subscription" >}}).

97
daprdocs/content/en/operations/configuration/install-certificates.md Normal file
View File

@ -0,0 +1,97 @@
---
type: docs
title: "How-To: Install certificates in the Dapr sidecar"
linkTitle: "Install sidecar certificates"
weight: 6500
description: "Configure the Dapr sidecar container to trust certificates"
---
The Dapr sidecar can be configured to trust certificates for communicating with external services. This is useful in scenarios where a self-signed certificate needs to be trusted. For example, using an HTTP binding or configuring an outbound proxy for the sidecar. Both certificate authority (CA) certificates and leaf certificates are supported.
{{< tabs Self-hosted Kubernetes >}}
{{% codetab %}}
When the sidecar is not running inside a container, certificates must be directly installed on the host operating system.
When the sidecar is running as a container:
1. Certificates must be available to the sidecar container. This can be configured using volume mounts.
1. The environment variable `SSL_CERT_DIR` must be set in the sidecar container, pointing to the directory containing the certificates.
1. For Windows containers, the container needs to run with administrator privileges to be able to install the certificates.
Below is an example that uses Docker Compose to install certificates (present locally in the `./certificates` directory) in the sidecar container:
```yaml
version: '3'
services:
dapr-sidecar:
image: "daprio/daprd:edge" # dapr version must be at least v1.8
command: [
"./daprd",
"-app-id", "myapp",
"-app-port", "3000",
]
volumes:
- "./components/:/components"
- "./certificates:/certificates" # (STEP 1) Mount the certificates folder to the sidecar container
environment:
- "SSL_CERT_DIR=/certificates" # (STEP 2) Set the environment variable to the path of the certificates folder
# Uncomment the line below for Windows containers
# user: ContainerAdministrator
```
{{% /codetab %}}
{{% codetab %}}
On Kubernetes:
1. Certificates must be available to the sidecar container using a volume mount.
1. The environment variable `SSL_CERT_DIR` must be set in the sidecar container, pointing to the directory containing the certificates.
The YAML below is an example of a deployment that attaches a pod volume to the sidecar, and sets `SSL_CERT_DIR` to install the certificates.
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: myapp
namespace: default
labels:
app: myapp
spec:
replicas: 1
selector:
matchLabels:
app: myapp
template:
metadata:
labels:
app: myapp
annotations:
dapr.io/enabled: "true"
dapr.io/app-id: "myapp"
dapr.io/app-port: "8000"
dapr.io/volume-mounts: "certificates-vol:/tmp/certificates" # (STEP 1) Mount the certificates folder to the sidecar container
dapr.io/env: "SSL_CERT_DIR=/tmp/certificates" # (STEP 2) Set the environment variable to the path of the certificates folder
spec:
volumes:
- name: certificates-vol
hostPath:
path: /certificates
...
```
{{% alert title="Note" color="primary" %}}
When using Windows containers, the sidecar container is started with admin privileges, which is required to install the certificates. This does not apply to Linux containers.
{{% /alert %}}
Note, all the certificates in the directory pointed by `SSL_CERT_DIR` are installed.
1. On Linux containers, all the certificate extensions supported by OpenSSL are supported. For more information, see https://www.openssl.org/docs/man1.1.1/man1/openssl-rehash.html
1. On Windows container, all the certificate extensions supported by certoc.exe are supported. For more information, see certoc.exe present in [Windows Server Core](https://hub.docker.com/_/microsoft-windows-servercore)
{{% /codetab %}}
{{< /tabs >}}
## Related links
- [(Kubernetes) How-to: Mount Pod volumes to the Dapr sidecar]({{< ref kubernetes-volume-mounts.md >}})
- [Dapr Kubernetes pod annotations spec]({{< ref arguments-annotations-overview.md >}})

19
daprdocs/content/en/operations/hosting/kubernetes/kubernetes-deploy.md
View File

@ -171,6 +171,25 @@ dapr-sidecar-injector-8555576b6f-29cqm 1/1 Running 0 40s
dapr-sentry-9435776c7f-8f7yd 1/1 Running 0 40s
```
## Using Mariner-based images
When deploying Dapr, whether on Kubernetes or in Docker self-hosted, the default container images that are pulled are based on [*distroless*](https://github.com/GoogleContainerTools/distroless).
Alternatively, you can use Dapr container images based on Mariner 2 (minimal distroless). [Mariner](https://github.com/microsoft/CBL-Mariner/), officially known as CBL-Mariner, is a free and open-source Linux distribution and container base image maintained by Microsoft. For some Dapr users, leveraging container images based on Mariner can help you meet compliance requirements.
To use Mariner-based images for Dapr, you need to add `-mariner` to your Docker tags. For example, while `ghcr.io/dapr/dapr:latest` is the Docker image based on *distroless*, `ghcr.io/dapr/dapr:latest-mariner` is based on Mariner. Tags pinned to a specific version are also available, such as `{{% dapr-latest-version short="true" %}}-mariner`.
With Kubernetes and Helm, you can use Mariner-based images by setting the `global.tag` option and adding `-mariner`. For example:
```sh
helm upgrade --install dapr dapr/dapr \
--version={{% dapr-latest-version short="true" %}} \
--namespace dapr-system \
--create-namespace \
--set global.tag={{% dapr-latest-version long="true" %}}-mariner \
--wait
```
## Next steps
- [Configure state store & pubsub message broker]({{< ref "getting-started/tutorials/configure-state-pubsub.md" >}})

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

@ -8,8 +8,9 @@ description: "Recommendations and practices for deploying Dapr to a Kubernetes c
## Cluster capacity requirements
For a production-ready Kubernetes cluster deployment, it is recommended you run a cluster of at least 3 worker nodes to support a highly-available control plane installation.
Use the following resource settings as a starting point. Requirements will vary depending on cluster size and other factors, so perform individual testing to find the right values for your environment:
For a production-ready Kubernetes cluster deployment, we recommended you run a cluster of at least 3 worker nodes to support a highly-available control plane installation.
Use the following resource settings as a starting point. Requirements will vary depending on cluster size and other factors, so you should perform individual testing to find the right values for your environment:
| Deployment | CPU | Memory
|-------------|-----|-------
@ -21,20 +22,23 @@ Use the following resource settings as a starting point. Requirements will vary
{{% alert title="Note" color="primary" %}}
For more info, read the [concept article on CPU and Memory resource units and their meaning](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes).
{{% /alert %}}
### Helm
When installing Dapr using Helm, no default limit/request values are set. Each component has a `resources` option (for example, `dapr_dashboard.resources`), which you can use to tune the Dapr control plane to fit your environment. The [Helm chart readme](https://github.com/dapr/dapr/blob/master/charts/dapr/README.md) has detailed information and examples. For local/dev installations, you might simply want to skip configuring the `resources` options.
When installing Dapr using Helm, no default limit/request values are set. Each component has a `resources` option (for example, `dapr_dashboard.resources`), which you can use to tune the Dapr control plane to fit your environment.
The [Helm chart readme](https://github.com/dapr/dapr/blob/master/charts/dapr/README.md) has detailed information and examples.
For local/dev installations, you might simply want to skip configuring the `resources` options.
### Optional components
The following Dapr control plane deployments are optional:
- **Placement** - Needed for Dapr Actors
- **Sentry** - Needed for mTLS for service to service invocation
- **Dashboard** - Needed for operational view of the cluster
- **Placement**: needed to use Dapr Actors
- **Sentry**: needed for mTLS for service to service invocation
- **Dashboard**: needed to get an operational view of the cluster
## Sidecar resource settings
@ -58,14 +62,13 @@ Example settings for the Dapr sidecar in a production-ready setup:
{{% alert title="Note" color="primary" %}}
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.
{{% /alert %}}
The CPU and memory limits above account for the fact that Dapr is intended to a high number of I/O bound operations. It is strongly recommended that you use a monitoring tool to baseline the sidecar (and app) containers and tune these settings based on those baselines.
The CPU and memory limits above account for the fact that Dapr is intended to support a high number of I/O bound operations. It is strongly recommended that you use a monitoring tool to get a baseline for the sidecar (and app) containers and tune these settings based on those baselines.
## Highly-available mode
When deploying Dapr in a production-ready configuration, it's recommended to deploy with a highly available (HA) configuration of the control plane, which creates 3 replicas of each control plane pod in the dapr-system namespace. This configuration allows the Dapr control plane to retain 3 running instances and survive node failures and other outages.
When deploying Dapr in a production-ready configuration, it is recommend to deploy with a highly available (HA) configuration of the control plane, which creates 3 replicas of each control plane pod in the dapr-system namespace. This configuration allows the Dapr control plane to retain 3 running instances and survive individual node failures and other outages.
For a new Dapr deployment, the HA mode can be set with both the [Dapr CLI]({{< ref "kubernetes-deploy.md#install-in-highly-available-mode" >}}) and with [Helm charts]({{< ref "kubernetes-deploy.md#add-and-install-dapr-helm-chart" >}}).
@ -76,6 +79,7 @@ For an existing Dapr deployment, enabling the HA mode requires additional steps.
[Visit the full guide on deploying Dapr with Helm]({{< ref "kubernetes-deploy.md#install-with-helm-advanced" >}}).
### Parameters file
Instead of specifying parameters on the command line, it's recommended to create a values file. This file should be checked into source control so that you can track its changes.
For a full list of all available options you can set in the values file (or by using the `--set` command-line option), see https://github.com/dapr/dapr/blob/master/charts/dapr/README.md.
@ -119,7 +123,7 @@ The Dapr Helm chart automatically deploys with affinity for nodes with the label
## Upgrading Dapr with Helm
Dapr supports zero downtime upgrades. The upgrade path includes the following steps:
Dapr supports zero-downtime upgrades. The upgrade path includes the following steps:
1. Upgrading a CLI version (optional but recommended)
2. Updating the Dapr control plane
@ -189,7 +193,6 @@ It is recommended that a production-ready deployment includes the following sett
6. Dapr also supports **scoping components for certain applications**. This is not a required practice, and can be enabled according to your security needs. See [here]({{< ref "component-scopes.md" >}}) for more info.
## Tracing and metrics configuration
Dapr has tracing and metrics enabled by default. It is *recommended* that you set up distributed tracing and metrics for your applications and the Dapr control plane in production.
@ -197,15 +200,26 @@ Dapr has tracing and metrics enabled by default. It is *recommended* that you se
If you already have your own observability set-up, you can disable tracing and metrics for Dapr.
### Tracing
To configure a tracing backend for Dapr visit [this]({{< ref "setup-tracing.md" >}}) link.
### Metrics
For metrics, Dapr exposes a Prometheus endpoint listening on port 9090 which can be scraped by Prometheus.
To setup Prometheus, Grafana and other monitoring tools with Dapr, visit [this]({{< ref "monitoring" >}}) link.
## Injector watchdog
The Dapr Operator service includes an _injector watchdog_ which can be used to detect and remediate situations where your application's pods may be deployed without the Dapr sidecar (the `daprd` container) when they should have been. For example, it can assist with recovering the applications after a total cluster failure.
The injector watchdog is disabled by default when running Dapr in Kubernetes mode and it is recommended that you consider enabling it with values that are appropriate for your specific situation.
Refer to the documentation for the [Dapr operator]({{< ref operator >}}) service for more details on the injector watchdog and how to enable it.
## Best Practices
Watch this video for a deep dive into the best practices for running Dapr in production with Kubernetes
<div class="embed-responsive embed-responsive-16by9">
<iframe width="360" height="315" src="https://www.youtube.com/embed/_U9wJqq-H1g" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
<iframe width="360" height="315" src="https://www.youtube-nocookie.com/embed/_U9wJqq-H1g" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

2
daprdocs/content/en/operations/support/support-preview-features.md
View File

@ -15,7 +15,7 @@ For CLI there is no explicit opt-in, just the version that this was first made a
## Current preview features
| Feature | Description | Setting | Documentation | Version introduced |
| ---------- |-------------|---------|---------------|-----------------|
| **--image-registry** flag with Dapr CLI| In self hosted mode you can set this flag to specify any private registry to pull the container images required to install Dapr| N/A | [init CLI command reference]({{<ref "dapr-init.md#self-hosted-environment" >}}) | v1.7 |
| **--image-registry** flag in Dapr CLI| In self hosted mode you can set this flag to specify any private registry to pull the container images required to install Dapr| N/A | [CLI init command reference]({{<ref "dapr-init.md#self-hosted-environment" >}}) | v1.7 |
| **Resiliency** | Allows configuring of fine-grained policies for retries, timeouts and circuitbreaking. | `Resiliency` | [Configure Resiliency Policies]({{<ref "resiliency-overview">}}) | v1.7|
| **Service invocation without default `content-type`** | When enabled removes the default service invocation content-type header value `application/json` when no content-type is provided. This will become the default behavior in release v1.9.0. This requires you to explictly set content-type headers where required for your apps. | `ServiceInvocation.NoDefaultContentType` | [Service Invocation]({{<ref "service_invocation_api.md#request-contents" >}}) | v1.7 |

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

@ -24,6 +24,7 @@ Usage:
dapr [command]
Available Commands:
annotate Add dapr annotations to a Kubernetes configuration. Supported platforms: Kubernetes
build-info Print build info of Dapr CLI and runtime
completion Generates shell completion scripts
components List all Dapr components. Supported platforms: Kubernetes
@ -54,6 +55,7 @@ Use "dapr [command] --help" for more information about a command.
You can learn more about each Dapr command from the links below.
- [`dapr annotate`]({{< ref dapr-annotate.md >}})
- [`dapr build-info`]({{< ref dapr-build-info.md >}})
- [`dapr completion`]({{< ref dapr-completion.md >}})
- [`dapr components`]({{< ref dapr-components.md >}})

88
daprdocs/content/en/reference/cli/dapr-annotate.md Normal file
View File

@ -0,0 +1,88 @@
---
type: docs
title: "annotate CLI command reference"
linkTitle: "annotate"
description: "Add Dapr annotatations to a Kubernetes configuration"
---
### Description
Add Dapr annotations to a Kubernetes configuration. This enables you to add/change the Dapr annotations on a deployment files. See [Kubernetes annotations]({{< ref arguments-annotations-overview >}}) for a full description of each annotation available in the following list of flags.
### Supported platforms
- [Kubernetes]({{< ref kubernetes >}})
### Usage
```bash
dapr annotate [flags] CONFIG-FILE
```
### Flags
| Name | Environment Variable | Default | Description
| --- | --- | --- | --- |
| `--kubernetes, -k` | | | Apply annotations to Kubernetes resources. Required |
| `--api-token-secret` | | | The secret to use for the API token |
| `--app-id, -a` | | | The app id to annotate |
| `--app-max-concurrency` | | `-1` | The maximum number of concurrent requests to allow |
| `--app-port, -p` | | `-1` | The port to expose the app on |
| `--app-protocol` | | | The protocol to use for the app |
| `--app-ssl` | | `false` | Enable SSL for the app |
| `--app-token-secret` | | | The secret to use for the app token |
| `--config, -c` | | | The config file to annotate |
| `--cpu-limit` | | | The CPU limit to set for the sidecar. See valid values [here](https://kubernetes.io/docs/tasks/administer-cluster/manage-resources/quota-memory-cpu-namespace/). |
| `--cpu-request` | | | The CPU request to set for the sidecar. See valid values [here](https://kubernetes.io/docs/tasks/administer-cluster/manage-resources/quota-memory-cpu-namespace/). |
| `--dapr-image` | | | The image to use for the dapr sidecar container |
| `--enable-debug` | | `false` | Enable debug |
| `--enable-metrics` | | `false` | Enable metrics |
| `--enable-profile` | | `false` | Enable profiling |
| `--env` | | | Environment variables to set (key value pairs, comma separated) |
| `--graceful-shutdown-seconds` | | `-1` | The number of seconds to wait for the app to shutdown |
| `--help, -h` | | | help for annotate |
| `--http-stream-request-body` | | `false` | Enable streaming request body for HTTP |
| `--listen-addresses` | | | The addresses for sidecar to listen on. To listen to all IPv4 addresses, use `0.0.0.0`. To listen to all IPv6 addresses, use `[::]`. |
| `--liveness-probe-delay` | | `-1` | The delay for sidecar to use for the liveness probe. Read more [here](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#configure-probes). |
| `--liveness-probe-period` | | `-1` | The period used by the sidecar for the liveness probe. Read more [here](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#configure-probes). |
| `--liveness-probe-threshold` | | `-1` | The threshold used by the sidecar for the liveness probe. Read more [here](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#configure-probes). |
| `--liveness-probe-timeout` | | `-1` | The timeout used by the sidecar for the liveness probe. Read more [here](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#configure-probes). |
| `--log-level` | | | The log level to use |
| `--max-request-body-size` | | `-1` | The maximum request body size to use |
| `--http-read-buffer-size` | | `-1` | The maximum size of HTTP header read buffer in kilobytes |
| `--memory-limit` | | | The memory limit to set for the sidecar. See valid values [here](https://kubernetes.io/docs/tasks/administer-cluster/manage-resources/quota-memory-cpu-namespace/) |
| `--memory-request`| | | The memory request to set for the sidecar |
| `--metrics-port` | | `-1` | The port to expose the metrics on |
| `--namespace, -n` | | | The namespace the resource target is in (can only be set if `--resource` is also set) |
| `--readiness-probe-delay` | | `-1` | The delay to use for the readiness probe in the sidecar. Read more [here](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#configure-probes).|
| `--readiness-probe-period` | | `-1` | The period to use for the readiness probe in the sidecar. Read more [here](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#configure-probes). |
| `--readiness-probe-threshold` | | `-1` | The threshold to use for the readiness probe in the sidecar. Read more [here](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#configure-probes). |
| `--readiness-probe-timeout` | | `-1` | The timeout to use for the readiness probe in the sidecar. Read more [here](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#configure-probes). |
| `--resource, -r` | | | The Kubernetes resource target to annotate |
| `--enable-api-logging` | | | Enable API logging for the Dapr sidecar |
| `--unix-domain-socket-path` | | | Linux domain socket path to use for communicating with the Dapr sidecar |
| `--volume-mounts` | | | List of pod volumes to be mounted to the sidecar container in read-only mode |
| `--volume-mounts-rw` | | | List of pod volumes to be mounted to the sidecar container in read-write mode |
| `--disable-builtin-k8s-secret-store` | | | Disable the built-in Kubernetes secret store |
| `--placement-host-address` | | | Comma separated list of addresses for Dapr actor placement servers |
{{% alert title="Warning" color="warning" %}}
If an application ID is not provided using `--app-id, -a`, an ID is generated using the format `<namespace>-<kind>-<name>`.
{{% /alert %}}
### Examples
```bash
# Annotate the first deployment found in the input
kubectl get deploy -l app=node -o yaml | dapr annotate -k - | kubectl apply -f -
# Annotate multiple deployments by name in a chain
kubectl get deploy -o yaml | dapr annotate -k -r nodeapp - | dapr annotate -k -r pythonapp - | kubectl apply -f -
# Annotate deployment in a specific namespace from file or directory by name
dapr annotate -k -r nodeapp -n namespace mydeploy.yaml | kubectl apply -f -
# Annotate deployment from url by name
dapr annotate -k -r nodeapp --log-level debug https://raw.githubusercontent.com/dapr/quickstarts/master/tutorials/hello-kubernetes/deploy/node.yaml | kubectl apply -f -
```

4
daprdocs/content/en/reference/cli/dapr-build-info.md
View File

@ -2,12 +2,12 @@
type: docs
title: "build-info CLI command reference"
linkTitle: "build-info"
description: "Detailed build information on dapr-cli and daprd executables"
description: "Detailed build information on dapr CLI and daprd executables"
---
### Description
Get the version and git commit data for `dapr-cli` and `daprd` executables.
Get the version and git commit data for `dapr` and `daprd` executables.
### Supported platforms

9
daprdocs/content/en/reference/components-reference/supported-bindings/http.md
View File

@ -169,6 +169,14 @@ curl -d '{ "operation": "post", "data": "YOUR_BASE_64_CONTENT", "metadata": { "p
{{< /tabs >}}
## Using HTTPS
The HTTP binding can also be used with HTTPS endpoints by configuring the Dapr sidecar to trust the server's SSL certificate.
1. Update the binding component's YAML to use `https` instead of `http`
1. Refer [How-To: Install certificates in the Dapr sidecar]({{< ref install-certificates >}}), to install the SSL certificate in the sidecar.
## Related links
- [Basic schema for a Dapr component]({{< ref component-schema >}})
@ -176,3 +184,4 @@ curl -d '{ "operation": "post", "data": "YOUR_BASE_64_CONTENT", "metadata": { "p
- [How-To: Trigger application with input binding]({{< ref howto-triggers.md >}})
- [How-To: Use bindings to interface with external resources]({{< ref howto-bindings.md >}})
- [Bindings API reference]({{< ref bindings_api.md >}})
- [How-To: Install certificates in the Dapr sidecar]({{< ref install-certificates >}})

25
daprdocs/content/en/reference/components-reference/supported-bindings/s3.md
View File

@ -45,6 +45,8 @@ spec:
value: <bool>
- name: insecureSSL
value: <bool>
- name: filePath
value: <string>
```
{{% alert title="Warning" color="warning" %}}
@ -66,6 +68,7 @@ The above example uses secrets as plain strings. It is recommended to use a secr
| encodeBase64 | N | Output | Configuration to encode base64 file content before return the content. (In case of opening a file with binary content). `true` is the only allowed positive value. Other positive variations like `"True", "1"` are not acceptable. Defaults to `false` | `true`, `false` |
| disableSSL | N | Output | Allows to connect to non `https://` endpoints. Defaults to `false` | `true`, `false` |
| insecureSSL | N | Output | When connecting to `https://` endpoints, accepts invalid or self-signed certificates. Defaults to `false` | `true`, `false` |
| filePath | N | Output | If set, create operations that contain empty `data` fields will attempt to upload a file from the supplied path | `"/var/path/myFile.txt"` |
{{% alert title="Important" color="warning" %}}
When running the Dapr sidecar (daprd) with your application on EKS (AWS Kubernetes), if you're using a node/pod that has already been attached to an IAM policy defining access to AWS resources, you **must not** provide AWS access-key, secret-key, and tokens in the definition of the component spec you're using.
@ -193,6 +196,25 @@ Then you can upload it as you would normally:
{{< /tabs >}}
##### Upload from file path
{{< tabs Windows Linux >}}
{{% codetab %}}
```bash
curl -d '{ \"operation\": \"create\", \"metadata\": { \"filePath\": \"my-test-file.txt\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
```
{{% /codetab %}}
{{% codetab %}}
```bash
curl -d '{ "operation": "create", "metadata": { "filePath": "my-test-file.txt" }}' \
http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
```
{{% /codetab %}}
{{< /tabs >}}
#### Response
The response body will contain the following JSON:
@ -286,7 +308,7 @@ The metadata parameters are:
#### Response
An HTTP 204 (No Content) and empty body will be retuned if successful.
An HTTP 204 (No Content) and empty body will be returned if successful.
### List objects
@ -346,6 +368,7 @@ The list of objects will be returned as JSON array in the following form:
"Prefix": ""
}
```
## Related links
- [Basic schema for a Dapr component]({{< ref component-schema >}})

1
daprdocs/content/en/reference/environment/_index.md
View File

@ -20,3 +20,4 @@ The following table lists the environment variables used by the Dapr runtime, CL
| DAPR_API_TOKEN | Dapr sidecar | The token used for Dapr API authentication for requests from the application. [Enable API token authentication in Dapr]({{< ref api-token >}}). |
| NAMESPACE | Dapr sidecar | Used to specify a component's [namespace in self-hosted mode]({{< ref component-scopes >}}). |
| DAPR_DEFAULT_IMAGE_REGISTRY | Dapr CLI | In self-hosted mode, it is used to specify the default container registry to pull images from. When its value is set to `GHCR` or `ghcr`, it pulls the required images from Github container registry. To default to Docker hub, unset this environment variable. |
| SSL_CERT_DIR | Dapr sidecar | Specifies the location where the public certificates for all the trusted certificate authorities (CA) are located. Not applicable when the sidecar is running as a process in self-hosted mode.

2
sdkdocs/js

@ -1 +1 @@
Subproject commit 5f6fd57d28ecc676dce2c22530190af21ca7d63c
Subproject commit 0a0e9e810c9139e8b2a4ebdb7ee33ae893741e1b