Dapr 配置管理指南 on Dapr 文档库

Dapr 配置

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 配置通过一系列设置和策略，允许您调整单个 Dapr 应用程序的行为，或控制平面系统服务的整体行为。

欲了解更多信息，请阅读配置概念。

应用程序配置

设置应用程序配置

您可以在自托管模式或 Kubernetes 模式下设置应用程序配置。

在自托管模式下，Dapr 配置是一个配置文件，例如 config.yaml。默认情况下，Dapr sidecar 会在默认的 Dapr 文件夹中查找运行时配置：

Linux/MacOs: $HOME/.dapr/config.yaml
Windows: %USERPROFILE%\.dapr\config.yaml

您还可以在 dapr run CLI 命令中使用 --config 标志指定文件路径来应用配置。

在 Kubernetes 模式下，Dapr 配置是一个应用于集群的配置资源。例如：

kubectl apply -f myappconfig.yaml

您可以使用 Dapr CLI 列出应用程序的配置资源。

dapr configurations -k

Dapr sidecar 可以通过 dapr.io/config 注解来应用特定配置。例如：

操作指南：控制并发和限制应用程序的速率

Mon, 01 Jan 0001 00:00:00 +0000

在分布式计算中，通常您可能只希望允许一定数量的请求同时执行。通过使用 Dapr 的 app-max-concurrency，您可以控制同时调用您应用程序的请求和事件数量。

默认情况下，app-max-concurrency 设置为 -1，表示不限制并发数量。

不同的方法

本指南主要介绍 app-max-concurrency，但您也可以使用 middleware.http.ratelimit 中间件来限制每秒的请求速率。理解这两种方法的区别非常重要：

middleware.http.ratelimit：限制每秒的请求数量
app-max-concurrency：限制在任意时间点的最大并发请求（和事件）数量。

有关该方法的更多信息，请参见速率限制中间件。

演示

观看此视频以了解如何控制并发和速率限制。

配置 `app-max-concurrency`

如果不使用 Dapr，您需要在应用程序中创建某种信号量并负责获取和释放它。

使用 Dapr，您无需对应用程序进行任何代码更改。

选择您希望配置 app-max-concurrency 的方式。

要在本地开发环境中使用 Dapr CLI 设置并发限制，请添加 app-max-concurrency 标志：

dapr run --app-max-concurrency 1 --app-port 5000 python ./app.py

上述示例将您的应用程序变成一个顺序处理服务。

操作指南：限制从 secret 存储中读取的 secret

Mon, 01 Jan 0001 00:00:00 +0000

除了定义哪些应用程序可以访问特定组件之外，您还可以将命名的 secret 存储组件限制为应用程序的一个或多个 secret。通过定义 allowedSecrets 和/或 deniedSecrets 列表，可以限制应用程序仅访问特定的 secret。

有关配置资源的更多信息：

配置 secret 访问

Configuration 规范下的 secrets 部分包含以下属性：

secrets:
 scopes:
 - storeName: kubernetes
 defaultAccess: allow
 allowedSecrets: ["redis-password"]
 - storeName: localstore
 defaultAccess: allow
 deniedSecrets: ["redis-password"]

下表列出了 secret 范围的属性：

属性	类型	描述
storeName	string	secret 存储组件的名称。storeName 在列表中必须是唯一的
defaultAccess	string	访问修饰符。接受的值为 “allow”（默认）或 “deny”
allowedSecrets	list	可以访问的 secret 键列表
deniedSecrets	list	不能访问的 secret 键列表

当 allowedSecrets 列表中存在至少一个元素时，应用程序只能访问列表中定义的那些 secret。

操作指南：为服务调用配置应用访问控制列表

Mon, 01 Jan 0001 00:00:00 +0000

通过访问控制，您可以配置策略，限制调用应用程序在被调用应用程序上通过服务调用可以执行的操作。您可以在配置模式中定义访问控制策略规范，以限制访问：

从特定操作到被调用应用程序，以及
从调用应用程序到HTTP动词。

访问控制策略在配置中指定，并应用于被调用应用程序的Dapr sidecar。对被调用应用程序的访问基于匹配的策略操作。

您可以为所有调用应用程序提供一个默认的全局操作。如果未指定访问控制策略，默认行为是允许所有调用应用程序访问被调用应用程序。

查看访问策略示例。

术语

`trustDomain`

“信任域”是用于管理信任关系的逻辑分组。每个应用程序都被分配一个信任域，可以在访问控制列表策略规范中指定。如果未定义策略规范或指定了空的信任域，则使用默认值“public”。信任域用于在TLS证书中生成应用程序的身份。

应用程序身份

Dapr请求sentry服务为所有应用程序生成一个SPIFFE ID。此ID附加在TLS证书中。

SPIFFE ID的格式为：**spiffe://\<trustdomain>/ns/\<namespace\>/\<appid\>**。

对于匹配策略，从调用应用程序的TLS证书中提取调用应用程序的信任域、命名空间和应用程序ID值。这些值与策略规范中指定的信任域、命名空间和应用程序ID值进行匹配。如果这三者都匹配，则进一步匹配更具体的策略。

配置属性

下表列出了访问控制、策略和操作的不同属性：

访问控制

属性	类型	描述
`defaultAction`	string	当没有其他策略匹配时的全局默认操作
`trustDomain`	string	分配给应用程序的信任域。默认值为“public”。
`policies`	string	确定调用应用程序可以在被调用应用程序上执行哪些操作的策略

策略

属性	类型	描述
`app`	string	允许/拒绝服务调用的调用应用程序的AppId
`namespace`	string	需要与调用应用程序的命名空间匹配的命名空间值
`trustDomain`	string	需要与调用应用程序的信任域匹配的信任域。默认值为“public”
`defaultAction`	string	如果找到应用程序但没有匹配的特定操作，则应用程序级别的默认操作
`operations`	string	允许从调用应用程序进行的操作

操作

属性	类型	描述
`name`	string	允许在被调用应用程序上进行的操作的路径名称。通配符“”可以用于路径中进行匹配。通配符“*”可以用于匹配多个路径下的内容。
`httpVerb`	list	调用应用程序可以使用的特定HTTP动词列表。通配符“*”可以用于匹配任何HTTP动词。未用于grpc调用。
`action`	string	访问修饰符。接受的值为“allow”（默认）或“deny”

策略规则

如果未指定访问策略，默认行为是允许所有应用程序访问被调用应用程序上的所有方法。
如果未指定全局默认操作且未定义特定应用程序策略，则空访问策略被视为未指定访问策略。默认行为是允许所有应用程序访问被调用应用程序上的所有方法。
如果未指定全局默认操作但已定义了一些特定应用程序策略，则我们采用更安全的选项，假设全局默认操作为拒绝访问被调用应用程序上的所有方法。
如果定义了访问策略且无法验证传入应用程序凭据，则全局默认操作生效。
如果传入应用程序的信任域或命名空间与应用程序策略中指定的值不匹配，则忽略应用程序策略，全局默认操作生效。

策略优先级

最具体的匹配策略对应的操作生效，按以下顺序排列：

使用指南：选择性启用 Dapr Sidecar 的 API

Mon, 01 Jan 0001 00:00:00 +0000

在零信任网络环境中，或通过前端将 Dapr Sidecar 暴露给外部流量时，建议仅启用应用程序实际使用的 Dapr Sidecar API。这样可以减少潜在的攻击风险，并确保 Dapr API 仅限于应用程序的实际需求。

Dapr 允许您通过使用 Dapr 配置设置 API 白名单或黑名单来控制应用程序可以访问哪些 API。

默认设置

如果未指定 API 白名单或黑名单，默认情况下将允许访问所有 Dapr API。

如果只定义了黑名单，则除黑名单中定义的 API 外，所有 Dapr API 都被允许访问。
如果只定义了白名单，则仅允许白名单中列出的 Dapr API。
如果同时定义了白名单和黑名单，则黑名单中的 API 优先于白名单。
如果两者都未定义，则允许访问所有 API。

例如，以下配置为 HTTP 和 gRPC 启用所有 API：

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
 name: myappconfig
 namespace: default
spec:
 tracing:
 samplingRate: "1"

使用白名单

启用特定的 HTTP API

以下示例启用 state v1.0 HTTP API，并禁用所有其他 HTTP API：

操作指南：配置 Dapr 使用 gRPC

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 提供了用于本地调用的 HTTP 和 gRPC API。gRPC 适用于低延迟、高性能的场景，并支持通过 proto 客户端进行语言集成。您可以查看自动生成的客户端（Dapr SDKs）的完整列表。

Dapr 运行时提供了一个 proto 服务，应用程序可以通过 gRPC 与其进行通信。

Dapr 不仅可以通过 gRPC 被调用，还可以通过 gRPC 与应用程序通信。为此，应用程序需要托管一个 gRPC 服务器并实现 Dapr appcallback 服务。

配置 Dapr 通过 gRPC 与应用程序通信

在自托管模式下运行时，使用 --app-protocol 标志告诉 Dapr 使用 gRPC 与应用程序通信：

dapr run --app-protocol grpc --app-port 5005 node app.js

这告诉 Dapr 通过端口 5005 使用 gRPC 与您的应用程序通信。

操作指南：如何处理大容量 HTTP 请求体

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 默认限制请求体大小为 4MB。您可以通过以下方法更改此限制：

使用 dapr.io/http-max-request-size 注解，或
使用 --dapr-http-max-request-size 参数。

在自托管模式下运行时，使用 --dapr-http-max-request-size 参数来设置 Dapr 的请求体大小限制：

dapr run --dapr-http-max-request-size 16 node app.js

这将把 Dapr 的最大请求体大小设置为 16 MB。

在 Kubernetes 中，您可以在部署的 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/http-max-request-size: "16"
#...

操作指南：处理大型HTTP头部大小

Mon, 01 Jan 0001 00:00:00 +0000

Dapr的HTTP头部读取缓冲区大小默认限制为4KB。如果您发送的HTTP头部超过4KB，可能会遇到请求头部过大的服务调用错误。

您可以通过以下方法增加HTTP头部大小：

使用dapr.io/http-read-buffer-size注解，或
在使用CLI时添加--dapr-http-read-buffer-size标志。

在自托管模式下运行时，使用--dapr-http-read-buffer-size标志来配置Dapr，以便使用非默认的HTTP头部大小：

dapr run --dapr-http-read-buffer-size 16 node app.js

这会将Dapr的最大读取缓冲区大小设置为16 KB。

在Kubernetes上，您可以在部署的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/http-read-buffer-size: "16"
#...

操作指南：在Dapr sidecar中安装证书

Mon, 01 Jan 0001 00:00:00 +0000

Dapr sidecar可以通过配置来信任与外部服务通信所需的证书。这在需要信任自签名证书的场景中非常有用，例如：

使用HTTP绑定
为sidecar配置出站代理

支持信任证书颁发机构（CA）证书和叶子证书。

当sidecar作为容器运行时，可以进行以下配置。

使用卷挂载将证书配置为可用于sidecar容器。
将sidecar容器中的环境变量SSL_CERT_DIR指向包含证书的目录。

注意： 对于Windows容器，请确保容器以管理员权限运行，以便可以安装证书。

以下示例展示了如何使用Docker Compose在sidecar容器中安装证书（证书位于本地的./certificates目录中）：

version: '3'
services:
 dapr-sidecar:
 image: "daprio/daprd:edge" # dapr版本必须至少为v1.8
 command: [
 "./daprd",
 "-app-id", "myapp",
 "-app-port", "3000",
 ]
 volumes:
 - "./components/:/components"
 - "./certificates:/certificates" # （步骤1）将证书文件夹挂载到sidecar容器
 environment:
 - "SSL_CERT_DIR=/certificates" # （步骤2）将环境变量设置为证书文件夹的路径
 # 对于Windows容器，取消注释下面的行
 # user: ContainerAdministrator

注意： 当sidecar不在容器内运行时，证书必须直接安装在主机操作系统上。

操作指南：启用预览功能

Mon, 01 Jan 0001 00:00:00 +0000

在 Dapr 中，预览功能在首次发布时被视为实验功能。这些预览功能需要您明确选择启用才能使用。您需要在 Dapr 的配置文件中进行此选择。

预览功能是通过在运行应用程序实例时设置配置来启用的。

配置属性

Configuration 规范下的 features 部分包含以下属性：

属性	类型	描述
`name`	字符串	启用/禁用的预览功能的名称
`enabled`	布尔值	指定功能是否启用或禁用的布尔值

启用预览功能

预览功能需要在配置中指定。以下是一个包含多个功能的完整配置示例：

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
 name: featureconfig
spec:
 tracing:
 samplingRate: "1"
 zipkin:
 endpointAddress: "http://zipkin.default.svc.cluster.local:9411/api/v2/spans"
 features:
 - name: Feature1
 enabled: true
 - name: Feature2
 enabled: true

要在本地运行 Dapr 时启用预览功能，可以更新默认配置或使用 dapr run 指定单独的配置文件。

操作指南：为 Dapr sidecar 配置 Secret 环境变量

Mon, 01 Jan 0001 00:00:00 +0000

在某些情况下，Dapr sidecar 需要注入环境变量。这可能是因为某个组件、第三方库或模块需要通过环境变量进行配置或自定义行为。这在生产和非生产环境中都很有用。

概述

在 Dapr 1.15 中，引入了新的 dapr.io/env-from-secret 注解，类似于 dapr.io/env。通过这个注解，你可以将环境变量注入到 Dapr sidecar 中，其值来自于一个 secret。

注解格式

注解的格式如下：

单个键的 secret: <ENV_VAR_NAME>=<SECRET_NAME>
多个键/值的 secret: <ENV_VAR_NAME>=<SECRET_NAME>:<SECRET_KEY>

<ENV_VAR_NAME> 必须符合 C_IDENTIFIER 格式，遵循 [A-Za-z_][A-Za-z0-9_]* 的正则表达式：

必须以字母或下划线开头
其余部分可以包含字母、数字或下划线

由于 secretKeyRef 的限制，name 字段是必需的，因此 name 和 key 必须同时设置。从 Kubernetes 文档的 “env.valueFrom.secretKeyRef.name” 部分了解更多信息。在这种情况下，Dapr 会将两者设置为相同的值。

配置单个键的 secret 环境变量

在以下示例中，dapr.io/env-from-secret 注解被添加到 Deployment 中。

apiVersion: apps/v1
kind: Deployment
metadata:
 name: nodeapp
spec:
 template:
 metadata:
 annotations:
 dapr.io/enabled: "true"
 dapr.io/app-id: "nodeapp"
 dapr.io/app-port: "3000"
 dapr.io/env-from-secret: "AUTH_TOKEN=auth-headers-secret"
 spec:
 containers:
 - name: node
 image: dapriosamples/hello-k8s-node:latest
 ports:
 - containerPort: 3000
 imagePullPolicy: Always

dapr.io/env-from-secret 注解的值为 "AUTH_TOKEN=auth-headers-secret" 被注入为：

Dapr 配置管理指南 on Dapr 文档库

Dapr 配置

应用程序配置

设置应用程序配置

操作指南：控制并发和限制应用程序的速率

不同的方法

演示

配置 `app-max-concurrency`

操作指南：限制从 secret 存储中读取的 secret

配置 secret 访问

操作指南：为服务调用配置应用访问控制列表

术语

`trustDomain`

应用程序身份

配置属性

访问控制

策略

操作

策略规则

策略优先级

使用指南：选择性启用 Dapr Sidecar 的 API

默认设置

使用白名单

启用特定的 HTTP API

操作指南：配置 Dapr 使用 gRPC

配置 Dapr 通过 gRPC 与应用程序通信

操作指南：如何处理大容量 HTTP 请求体

相关链接

操作指南：处理大型HTTP头部大小

相关链接

操作指南：在Dapr sidecar中安装证书

操作指南：启用预览功能

配置属性

启用预览功能

操作指南：为 Dapr sidecar 配置 Secret 环境变量

概述

注解格式

配置单个键的 secret 环境变量

Dapr 配置管理指南 on Dapr 文档库

Dapr 配置

应用程序配置

设置应用程序配置

操作指南：控制并发和限制应用程序的速率

不同的方法

演示

配置 app-max-concurrency

操作指南：限制从 secret 存储中读取的 secret

配置 secret 访问

操作指南：为服务调用配置应用访问控制列表

术语

trustDomain

应用程序身份

配置属性

访问控制

策略

操作

策略规则

策略优先级

使用指南：选择性启用 Dapr Sidecar 的 API

默认设置

使用白名单

启用特定的 HTTP API

操作指南：配置 Dapr 使用 gRPC

配置 Dapr 通过 gRPC 与应用程序通信

操作指南：如何处理大容量 HTTP 请求体

相关链接

操作指南：处理大型HTTP头部大小

相关链接

操作指南：在Dapr sidecar中安装证书

操作指南：启用预览功能

配置属性

启用预览功能

操作指南：为 Dapr sidecar 配置 Secret 环境变量

概述

注解格式

配置单个键的 secret 环境变量

配置 `app-max-concurrency`

`trustDomain`