This is the multi-page printable view of this section. Click here to print.
Dapr 资源规范
- 1: 组件规范
- 2: Subscription 规范
- 3: 弹性规范
- 4: HTTPEndpoint 规范
- 5: 配置规范
1 - 组件规范
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 store 的名称,元数据中的 secretKeyRef 在此处查找组件中使用的密钥名称 | 参见操作指南:在组件中引用密钥 |
| 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 边车如果组件加载失败则继续初始化。默认为 false | false |
| spec.metadata | - | 组件特定配置的键/值对。有关字段,请参阅您的组件定义 | |
| spec.metadata.name | Y | 组件特定属性的名称及其值 | - name: secretsFilevalue: secrets.json |
模板化元数据值
元数据值可以包含在 Dapr 边车启动时解析的模板标记。下表显示了可在组件中使用的当前模板标记。
| 标记 | 详情 | 示例用例 |
|---|---|---|
| {uuid} | 随机生成的 UUIDv4 | 当您在自托管模式下需要唯一标识符时;例如,多个应用实例消费共享的 MQTT 订阅 |
| {podName} | 包含 Dapr 边车的 Pod 的名称 | 用于实现持久化行为,即在 Kubernetes 中使用 StatefulSets 时,ConsumerID 在重启时不会更改 |
| {namespace} | Dapr 边车所在的命名空间与其 appId 组合 | 当多个应用实例在 Kubernetes 中消费 Kafka 主题时,使用共享的 clientId |
| {appID} | 包含 Dapr 边车的资源的已配置 appID | 当多个应用实例在自托管模式下消费 Kafka 主题时,拥有共享的 clientId |
下面是在 MQTT 发布订阅组件中使用 {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 - Subscription 规范
Subscription Dapr 资源允许你使用外部组件 YAML 文件以声明方式订阅 topic。
注意
任何 subscription 都可以限制到特定的 namespace,并通过 scopes 限制对特定应用程序集的访问。本指南演示了两个 subscription API 版本:
v2alpha1(默认规范)v1alpha1(已弃用)
v2alpha1 格式
以下是 Subscription 资源的基本 v2alpha1 规范。v2alpha1 是 subscription API 的默认规范。
apiVersion: dapr.io/v2alpha1
kind: Subscription
metadata:
name: <REPLACE-WITH-NAME>
spec:
topic: <REPLACE-WITH-TOPIC-NAME> # Required
routes: # Required
rules:
- match: <REPLACE-WITH-CEL-FILTER>
path: <REPLACE-WITH-PATH>
pubsubname: <REPLACE-WITH-PUBSUB-NAME> # Required
deadLetterTopic: <REPLACE-WITH-DEADLETTERTOPIC-NAME> # Optional
bulkSubscribe: # Optional
enabled: <REPLACE-WITH-BOOLEAN-VALUE>
maxMessagesCount: <REPLACE-WITH-VALUE>
maxAwaitDurationMs: <REPLACE-WITH-VALUE>
metadata: <REPLACE-WITH-METADATA-OBJECT> # Optional
scopes:
- <REPLACE-WITH-SCOPED-APPIDS>
Spec 字段
| 字段 | 必填 | 详情 | 示例 |
|---|---|---|---|
| topic | Y | 组件订阅的 topic 名称。 | orders |
| routes | Y | 此 topic 的路由配置,包括指定将消息发送到特定路径的条件。包含以下字段:
| match: event.type == "widget"path: /widgets |
| pubsubname | N | 你的发布订阅组件的名称。 | pubsub |
| deadLetterTopic | N | 转发不可传递消息的死信 topic 名称。 | poisonMessages |
| bulkSubscribe | N | 启用批量订阅属性。 | true, false |
| metadata | N | 设置订阅元数据。 | {"key": "value"} |
v1alpha1 格式
以下是 Subscription 资源的基本 v1alpha1 版本规范。v1alpha1 现已弃用。
apiVersion: dapr.io/v1alpha1
kind: Subscription
metadata:
name: <REPLACE-WITH-RESOURCE-NAME>
spec:
topic: <REPLACE-WITH-TOPIC-NAME> # Required
route: <REPLACE-WITH-ROUTE-NAME> # Required
pubsubname: <REPLACE-WITH-PUBSUB-NAME> # Required
deadLetterTopic: <REPLACE-WITH-DEAD-LETTER-TOPIC-NAME> # Optional
metadata: <REPLACE-WITH-METADATA-OBJECT> # Optional
bulkSubscribe: # Optional
- enabled: <REPLACE-WITH-BOOLEAN-VALUE>
- maxMessagesCount: <REPLACE-WITH-VALUE>
- maxAwaitDurationMs: <REPLACE-WITH-VALUE>
scopes:
- <REPLACE-WITH-SCOPED-APPIDS>
Spec 字段
| 字段 | 必填 | 详情 | 示例 |
|---|---|---|---|
| topic | Y | 组件订阅的 topic 名称。 | orders |
| route | Y | 所有 topic 消息发送到的端点。 | /checkout |
| pubsubname | N | 你的发布订阅组件的名称。 | pubsub |
| deadlettertopic | N | 转发不可传递消息的死信 topic 名称。 | poisonMessages |
| metadata | N | 设置订阅元数据。 | {"key": "value"} |
| bulksubscribe | N | 启用批量订阅属性。 | true, false |
相关链接
3 - 弹性规范
Resiliency Dapr 资源允许您定义和应用容错弹性策略。弹性规范在 Dapr 边车启动时应用。
注意
任何弹性资源都可以限制到特定的命名空间,并通过作用域限制对任何特定应用程序集的访问。格式
apiVersion: dapr.io/v1alpha1
kind: Resiliency
metadata:
name: <REPLACE-WITH-RESOURCE-NAME>
version: v1alpha1
scopes:
- <REPLACE-WITH-SCOPED-APPIDS>
spec:
policies: # Required
timeouts:
timeoutName: <REPLACE-WITH-TIME-VALUE> # Replace with any unique name
retries:
retryName: # Replace with any unique name
policy: <REPLACE-WITH-VALUE>
duration: <REPLACE-WITH-VALUE>
maxInterval: <REPLACE-WITH-VALUE>
maxRetries: <REPLACE-WITH-VALUE>
matching:
httpStatusCodes: <REPLACE-WITH-VALUE>
gRPCStatusCodes: <REPLACE-WITH-VALUE>
circuitBreakers:
circuitBreakerName: # Replace with any unique name
maxRequests: <REPLACE-WITH-VALUE>
timeout: <REPLACE-WITH-VALUE>
trip: <REPLACE-WITH-CONSECUTIVE-FAILURE-VALUE>
targets: # Required
apps:
appID: # Replace with scoped app ID
timeout: <REPLACE-WITH-TIMEOUT-NAME>
retry: <REPLACE-WITH-RETRY-NAME>
circuitBreaker: <REPLACE-WITH-CIRCUIT-BREAKER-NAME>
actors:
myActorType:
timeout: <REPLACE-WITH-TIMEOUT-NAME>
retry: <REPLACE-WITH-RETRY-NAME>
circuitBreaker: <REPLACE-WITH-CIRCUIT-BREAKER-NAME>
circuitBreakerCacheSize: <REPLACE-WITH-VALUE>
components:
componentName: # Replace with your component name
outbound:
timeout: <REPLACE-WITH-TIMEOUT-NAME>
retry: <REPLACE-WITH-RETRY-NAME>
circuitBreaker: <REPLACE-WITH-CIRCUIT-BREAKER-NAME>
规范字段
| 字段 | 必填 | 详情 | 示例 |
|---|---|---|---|
| policies | Y | 弹性策略的配置,包括:
查看包含所有内置策略的更多示例 | timeout: generalretry: retryForevercircuit breaker: simpleCB |
| targets | Y | 使用弹性策略的应用程序、Actor 或组件的配置。 在弹性目标指南中查看更多示例 | appscomponentsactors |
相关链接
4 - 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 | Y | 非 Dapr 端点的基础 URL | "https://api.github.com"、"http://api.github.com" |
| headers | N | 服务调用所用的 HTTP 请求头 | name: "Accept-Language" value: "en-US"name: "Authorization" secretKeyRef.name: "my-secret" secretKeyRef.key: "myGithubToken" |
| clientTLS | N | 启用对端点的 TLS 身份验证,支持根证书、客户端证书和私钥的任意标准组合 |
相关链接
5 - 配置规范
Configuration 是一个 Dapr 资源,用于配置 Dapr 边车、控制平面等。
边车格式
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>
headers:
- name: <HEADER-NAME>
value: <HEADER-VALUE>
- name: <HEADER-NAME>
secretKeyRef:
name: <SECRET-STORE-NAME>
key: <SECRET-KEY>
timeout: <DURATION>
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 边车。用于配置策略,限制调用应用通过服务调用在被调用应用上可以执行的操作。 | 了解更多关于 accessControl 配置的信息。 |
| api | N | 用于仅启用应用所使用的 Dapr 边车 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: 15mworkloadCertTTL:24h了解更多关于 mtls 配置的信息。 |