This is the multi-page printable view of this section. Click here to print.
Dapr 资源规格
Dapr 资源的详细信息和规格说明
- 1: 组件规范
- 2: 订阅规范
- 3: 弹性说明
- 4: HTTPEndpoint 规范
- 5: 配置规范
1 - 组件规范
Dapr 组件的基本规范
Dapr 通过资源规范来定义和注册组件。所有组件都被定义为资源,可以应用于任何运行 Dapr 的托管环境,不仅限于 Kubernetes。
通常,组件会被限制在特定的命名空间内,并通过作用域来限制对特定应用程序的访问。命名空间可以在组件清单中显式指定,或者由 API 服务器根据 Kubernetes 的上下文来自动分配。
注意
在自托管模式下,如果省略命名空间字段,daprd 会自动加载组件资源。然而,安全配置文件不会生效,因为 daprd 无论如何都能访问清单,这与 Kubernetes 的行为不同。格式
apiVersion: dapr.io/v1alpha1
kind: Component
auth:
secretstore: <REPLACE-WITH-SECRET-STORE-NAME>
metadata:
name: <REPLACE-WITH-COMPONENT-NAME>
namespace: <REPLACE-WITH-COMPONENT-NAMESPACE>
spec:
type: <REPLACE-WITH-COMPONENT-TYPE>
version: v1
initTimeout: <REPLACE-WITH-TIMEOUT-DURATION>
ignoreErrors: <REPLACE-WITH-BOOLEAN>
metadata:
- name: <REPLACE-WITH-METADATA-NAME>
value: <REPLACE-WITH-METADATA-VALUE>
scopes:
- <REPLACE-WITH-APPID>
- <REPLACE-WITH-APPID>
规范字段
字段 | 必需 | 详情 | 示例 |
---|---|---|---|
apiVersion | Y | 您调用的 Dapr(和 Kubernetes 如果适用)API 的版本 | dapr.io/v1alpha1 |
kind | Y | 资源的类型。对于组件,必须始终是 Component | Component |
auth | N | secret 存储的名称,其中 secretKeyRef 在元数据中查找组件中使用的 secret 名称 | 参见 如何:在组件中引用 secret |
scopes | N | 组件限制的应用程序,由其应用程序 ID 指定 | order-processor , checkout |
metadata | - | 关于组件注册的信息 | |
metadata.name | Y | 组件的名称 | prod-statestore |
metadata.namespace | N | 具有命名空间的托管环境中组件的命名空间 | myapp-namespace |
spec | - | 关于组件资源的详细信息 | |
spec.type | Y | 组件的类型 | state.redis |
spec.version | Y | 组件的版本 | v1 |
spec.initTimeout | N | 组件初始化的超时时间。默认是 5s | 5m , 1h , 20s |
spec.ignoreErrors | N | 告诉 Dapr sidecar 如果组件加载失败继续初始化。默认是 false | false |
spec.metadata | - | 组件特定配置的键/值对。请参阅您的组件定义以获取字段 | |
spec.metadata.name | Y | 组件特定属性的名称及其值 | - name: secretsFile value: secrets.json |
模板化的元数据值
元数据值可以包含在 Dapr sidecar 启动时解析的模板标签。下表显示了可以在组件中使用的当前模板标签。
标签 | 详情 | 示例用例 |
---|---|---|
{uuid} | 随机生成的 UUIDv4 | 当您在自托管模式下需要唯一标识符时;例如,多个应用程序实例消费共享 MQTT 订阅 |
{podName} | 包含 Dapr sidecar 的 pod 的名称 | 用于持久化行为,当使用 StatefulSets 在 Kubernetes 中重启时 ConsumerID 不会改变 |
{namespace} | Dapr sidecar 所在的命名空间与其 appId 结合 | 当多个应用程序实例在 Kubernetes 中消费 Kafka 主题时使用共享的 clientId |
{appID} | 包含 Dapr sidecar 的资源的配置 appID | 当多个应用程序实例在自托管模式下消费 Kafka 主题时使用共享的 clientId |
下面是一个在 MQTT pubsub 组件中使用 {uuid}
标签的示例。请注意,在单个元数据值中可以使用多个模板标签。
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: messagebus
spec:
type: pubsub.mqtt3
version: v1
metadata:
- name: consumerID
value: "{uuid}"
- name: url
value: "tcp://admin:public@localhost:1883"
- name: qos
value: 1
- name: retain
value: "false"
- name: cleanSession
value: "false"
相关链接
2 - 订阅规范
Dapr 订阅的基本规范
Subscription
Dapr 资源允许您使用外部组件的 YAML 文件以声明方式订阅主题。
注意
任何订阅都可以限制在特定的命名空间内,并通过作用域限制访问特定的应用程序。本指南介绍了两种订阅 API 版本:
v2alpha
(默认规范)v1alpha1
(已弃用)
v2alpha1
格式
以下是 Subscription
资源的基本 v2alpha1
规范。v2alpha1
是订阅 API 的默认规范。
apiVersion: dapr.io/v2alpha1
kind: Subscription
metadata:
name: <REPLACE-WITH-NAME>
spec:
topic: <REPLACE-WITH-TOPIC-NAME> # 必需
routes: # 必需
rules:
- match: <REPLACE-WITH-CEL-FILTER>
path: <REPLACE-WITH-PATH>
pubsubname: <REPLACE-WITH-PUBSUB-NAME> # 必需
deadLetterTopic: <REPLACE-WITH-DEADLETTERTOPIC-NAME> # 可选
bulkSubscribe: # 可选
enabled: <REPLACE-WITH-BOOLEAN-VALUE>
maxMessagesCount: <REPLACE-WITH-VALUE>
maxAwaitDurationMs: <REPLACE-WITH-VALUE>
scopes:
- <REPLACE-WITH-SCOPED-APPIDS>
规范字段
字段 | 必需 | 详情 | 示例 |
---|---|---|---|
topic | Y | 您的组件订阅的主题名称。 | orders |
routes | Y | 此主题的路由配置,包括指定将消息发送到特定路径的条件。包括以下字段:
| match: event.type == "widget" path: /widgets |
pubsubname | N | 您的 pub/sub 组件的名称。 | pubsub |
deadLetterTopic | N | 转发无法投递消息的死信主题的名称。 | poisonMessages |
bulkSubscribe | N | 启用批量订阅功能。 | true , false |
v1alpha1
格式
以下是 Subscription
资源的基本 v1alpha1
规范。v1alpha1
现已弃用。
apiVersion: dapr.io/v1alpha1
kind: Subscription
metadata:
name: <REPLACE-WITH-RESOURCE-NAME>
spec:
topic: <REPLACE-WITH-TOPIC-NAME> # 必需
route: <REPLACE-WITH-ROUTE-NAME> # 必需
pubsubname: <REPLACE-WITH-PUBSUB-NAME> # 必需
deadLetterTopic: <REPLACE-WITH-DEAD-LETTER-TOPIC-NAME> # 可选
bulkSubscribe: # 可选
- enabled: <REPLACE-WITH-BOOLEAN-VALUE>
- maxMessagesCount: <REPLACE-WITH-VALUE>
- maxAwaitDurationMs: <REPLACE-WITH-VALUE>
scopes:
- <REPLACE-WITH-SCOPED-APPIDS>
规范字段
字段 | 必需 | 详情 | 示例 |
---|---|---|---|
topic | Y | 您的组件订阅的主题名称。 | orders |
route | Y | 所有主题消息发送到的端点。 | /checkout |
pubsubname | N | 您的 pub/sub 组件的名称。 | pubsub |
deadlettertopic | N | 转发无法投递消息的死信主题的名称。 | poisonMessages |
bulksubscribe | N | 启用批量订阅功能。 | true , false |
相关链接
3 - 弹性说明
Dapr 弹性资源的基本说明
Dapr 的弹性资源使您能够定义和应用容错策略。这些弹性说明会在 Dapr sidecar 启动时生效。
注意
任何弹性资源都可以限制在特定的命名空间中,并通过作用域限制对特定应用程序集的访问。格式
apiVersion: dapr.io/v1alpha1
kind: Resiliency
metadata:
name: <替换为资源名称>
version: v1alpha1
scopes:
- <替换为作用域应用程序ID>
spec:
policies: # 必需
timeouts:
timeoutName: <替换为时间值> # 使用唯一名称替换
retries:
retryName: # 使用唯一名称替换
policy: <替换为策略值>
duration: <替换为持续时间>
maxInterval: <替换为最大间隔>
maxRetries: <替换为最大重试次数>
matching:
httpStatusCodes: <替换为HTTP状态码>
gRPCStatusCodes: <替换为gRPC状态码>
circuitBreakers:
circuitBreakerName: # 使用唯一名称替换
maxRequests: <替换为最大请求数>
timeout: <替换为超时时间>
trip: <替换为连续失败次数>
targets: # 必需
apps:
appID: # 替换为应用程序ID
timeout: <替换为超时名称>
retry: <替换为重试名称>
circuitBreaker: <替换为断路器名称>
actors:
myActorType:
timeout: <替换为超时名称>
retry: <替换为重试名称>
circuitBreaker: <替换为断路器名称>
circuitBreakerCacheSize: <替换为缓存大小>
components:
componentName: # 替换为组件名称
outbound:
timeout: <替换为超时名称>
retry: <替换为重试名称>
circuitBreaker: <替换为断路器名称>
说明字段
字段 | 必需 | 详情 | 示例 |
---|---|---|---|
policies | Y | 弹性策略的配置,包括:
查看所有内置策略的更多示例 | timeout: general retry: retryForever circuit breaker: simpleCB |
targets | Y | 使用弹性策略的应用程序、actor 或组件的配置。 在弹性目标指南中查看更多示例 | apps components actors |
相关链接
4 - HTTPEndpoint 规范
Dapr HTTPEndpoint 资源的基本说明
HTTPEndpoint
是一种 Dapr 资源,用于让 Dapr 应用程序能够调用非 Dapr 的端点。
注意
HTTPEndpoint 资源可以被限制在特定的命名空间中,并通过作用域来限制对特定应用程序集的访问。格式
apiVersion: dapr.io/v1alpha1
kind: HTTPEndpoint
metadata:
name: <NAME>
spec:
baseUrl: <REPLACE-WITH-BASEURL> # 必填。需包含 "http://" 或 "https://" 前缀。
headers: # 可选
- name: <REPLACE-WITH-A-HEADER-NAME>
value: <REPLACE-WITH-A-HEADER-VALUE>
- name: <REPLACE-WITH-A-HEADER-NAME>
secretKeyRef:
name: <REPLACE-WITH-SECRET-NAME>
key: <REPLACE-WITH-SECRET-KEY>
clientTLS:
rootCA:
secretKeyRef:
name: <REPLACE-WITH-SECRET-NAME>
key: <REPLACE-WITH-SECRET-KEY>
certificate:
secretKeyRef:
name: <REPLACE-WITH-SECRET-NAME>
key: <REPLACE-WITH-SECRET-KEY>
privateKey:
secretKeyRef:
name: <REPLACE-WITH-SECRET-NAME>
key: <REPLACE-WITH-SECRET-KEY>
scopes: # 可选
- <REPLACE-WITH-SCOPED-APPIDS>
auth: # 可选
secretStore: <REPLACE-WITH-SECRETSTORE>
规范字段
字段 | 必填 | 详情 | 示例 |
---|---|---|---|
baseUrl | 是 | 非 Dapr 端点的基本 URL | "https://api.github.com" , "http://api.github.com" |
headers | 否 | 服务调用的 HTTP 请求头 | name: "Accept-Language" value: "en-US" name: "Authorization" secretKeyRef.name: "my-secret" secretKeyRef.key: "myGithubToken" |
clientTLS | 否 | 启用 TLS 认证到一个端点,支持使用根证书、客户端证书和私钥的标准组合 |
相关链接
5 - 配置规范
Dapr 配置资源的基本说明
Configuration
是一种 Dapr 资源,用于配置 Dapr sidecar、控制平面等。
Sidecar 配置格式
apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
name: <REPLACE-WITH-NAME>
namespace: <REPLACE-WITH-NAMESPACE>
spec:
api:
allowed:
- name: <REPLACE-WITH-API>
version: <VERSION>
protocol: <HTTP-OR-GRPC>
tracing:
samplingRate: <REPLACE-WITH-INTEGER>
stdout: true
otel:
endpointAddress: <REPLACE-WITH-ENDPOINT-ADDRESS>
isSecure: <TRUE-OR-FALSE>
protocol: <HTTP-OR-GRPC>
metrics:
enabled: <TRUE-OR-FALSE>
rules:
- name: <METRIC-NAME>
labels:
- name: <LABEL-NAME>
regex: {}
recordErrorCodes: <TRUE-OR-FALSE>
latencyDistributionBuckets:
- <BUCKET-VALUE-MS-0>
- <BUCKET-VALUE-MS-1>
http:
increasedCardinality: <TRUE-OR-FALSE>
pathMatching:
- <PATH-A>
- <PATH-B>
excludeVerbs: <TRUE-OR-FALSE>
httpPipeline: # 用于接收的 http 调用
handlers:
- name: <HANDLER-NAME>
type: <HANDLER-TYPE>
appHttpPipeline: # 用于发送的 http 调用
handlers:
- name: <HANDLER-NAME>
type: <HANDLER-TYPE>
nameResolution:
component: <NAME-OF-NAME-RESOLUTION-COMPONENT>
version: <NAME-RESOLUTION-COMPONENT-VERSION>
configuration:
<NAME-RESOLUTION-COMPONENT-METADATA-CONFIGURATION>
secrets:
scopes:
- storeName: <NAME-OF-SCOPED-STORE>
defaultAccess: <ALLOW-OR-DENY>
deniedSecrets: <REPLACE-WITH-DENIED-SECRET>
components:
deny:
- <COMPONENT-TO-DENY>
accessControl:
defaultAction: <ALLOW-OR-DENY>
trustDomain: <REPLACE-WITH-TRUST-DOMAIN>
policies:
- appId: <APP-NAME>
defaultAction: <ALLOW-OR-DENY>
trustDomain: <REPLACE-WITH-TRUST-DOMAIN>
namespace: "default"
operations:
- name: <OPERATION-NAME>
httpVerb: ['POST', 'GET']
action: <ALLOW-OR-DENY>
规范字段
字段 | 必需 | 详情 | 示例 |
---|---|---|---|
accessControl | N | 应用于 Dapr sidecar 的被调用应用程序。可以配置策略来限制调用应用程序通过服务调用对被调用应用程序执行的操作。 | 了解更多关于 accessControl 配置的信息。 |
api | N | 用于仅启用应用程序使用的 Dapr sidecar API。 | 了解更多关于 api 配置的信息。 |
httpPipeline | N | 配置 API 中间件管道 | 中间件管道配置概述 了解更多关于 httpPipeline 配置的信息。 |
appHttpPipeline | N | 配置应用程序中间件管道 | 中间件管道配置概述 了解更多关于 appHttpPipeline 配置的信息。 |
components | N | 用于指定不能初始化的组件类型的拒绝列表。 | 了解更多关于 components 配置的信息。 |
features | N | 定义启用/禁用的预览功能。 | 了解更多关于 features 配置的信息。 |
logging | N | 配置 Dapr 运行时中的日志记录方式。 | 了解更多关于 logging 配置的信息。 |
metrics | N | 启用或禁用应用程序的监控指标。 | 了解更多关于 metrics 配置的信息。 |
nameResolution | N | 服务调用模块的名称解析配置规范。 | 了解更多关于每个组件的 nameResolution 配置的信息。 |
secrets | N | 限制 Dapr 应用程序可以访问的密钥。 | 了解更多关于 secrets 配置的信息。 |
tracing | N | 为应用程序开启追踪。 | 了解更多关于 tracing 配置的信息。 |
控制平面格式
与 Dapr 一起安装的 daprsystem
配置文件应用全局设置,仅在 Dapr 部署到 Kubernetes 时生效。
apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
name: daprsystem
namespace: default
spec:
mtls:
enabled: true
allowedClockSkew: 15m
workloadCertTTL: 24h
规范字段
字段 | 必需 | 详情 | 示例 |
---|---|---|---|
mtls | N | 定义 mTLS 配置 | allowedClockSkew: 15m workloadCertTTL:24h 了解更多关于 mtls 配置的信息。 |