This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Dapr 资源规格

Dapr 资源的详细信息和规格说明

1 - 组件规范

Dapr 组件的基本规范

Dapr 通过资源规范来定义和注册组件。所有组件都被定义为资源,可以应用于任何运行 Dapr 的托管环境,不仅限于 Kubernetes。

通常,组件会被限制在特定的命名空间内,并通过作用域来限制对特定应用程序的访问。命名空间可以在组件清单中显式指定,或者由 API 服务器根据 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>

规范字段

字段必需详情示例
apiVersionY您调用的 Dapr(和 Kubernetes 如果适用)API 的版本dapr.io/v1alpha1
kindY资源的类型。对于组件,必须始终是 ComponentComponent
authNsecret 存储的名称,其中 secretKeyRef 在元数据中查找组件中使用的 secret 名称参见 如何:在组件中引用 secret
scopesN组件限制的应用程序,由其应用程序 ID 指定order-processor, checkout
metadata-关于组件注册的信息
metadata.nameY组件的名称prod-statestore
metadata.namespaceN具有命名空间的托管环境中组件的命名空间myapp-namespace
spec-关于组件资源的详细信息
spec.typeY组件的类型state.redis
spec.versionY组件的版本v1
spec.initTimeoutN组件初始化的超时时间。默认是 5s5m, 1h, 20s
spec.ignoreErrorsN告诉 Dapr sidecar 如果组件加载失败继续初始化。默认是 falsefalse
spec.metadata-组件特定配置的键/值对。请参阅您的组件定义以获取字段
spec.metadata.nameY组件特定属性的名称及其值- 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>

规范字段

字段必需详情示例
topicY您的组件订阅的主题名称。orders
routesY此主题的路由配置,包括指定将消息发送到特定路径的条件。包括以下字段:
  • match: 用于匹配事件的 CEL 表达式。如果未指定,则该路由被视为默认路由。
  • path: 匹配此规则的事件的路径。
所有主题消息发送到的端点。
match: event.type == "widget"
path: /widgets
pubsubnameN您的 pub/sub 组件的名称。pubsub
deadLetterTopicN转发无法投递消息的死信主题的名称。poisonMessages
bulkSubscribeN启用批量订阅功能。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>

规范字段

字段必需详情示例
topicY您的组件订阅的主题名称。orders
routeY所有主题消息发送到的端点。/checkout
pubsubnameN您的 pub/sub 组件的名称。pubsub
deadlettertopicN转发无法投递消息的死信主题的名称。poisonMessages
bulksubscribeN启用批量订阅功能。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: <替换为断路器名称>

说明字段

字段必需详情示例
policiesY弹性策略的配置,包括:
  • timeouts
  • retries
  • circuitBreakers

查看所有内置策略的更多示例
timeout: general
retry: retryForever
circuit breaker: simpleCB
targetsY使用弹性策略的应用程序、actor 或组件的配置。
在弹性目标指南中查看更多示例
apps
components
actors

相关链接

了解更多关于弹性策略和目标的信息

4 - HTTPEndpoint 规范

Dapr HTTPEndpoint 资源的基本说明

HTTPEndpoint 是一种 Dapr 资源,用于让 Dapr 应用程序能够调用非 Dapr 的端点。

格式

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 认证到一个端点,支持使用根证书、客户端证书和私钥的标准组合

相关链接

了解如何调用非 Dapr 端点。

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>

规范字段

字段必需详情示例
accessControlN应用于 Dapr sidecar 的被调用应用程序。可以配置策略来限制调用应用程序通过服务调用对被调用应用程序执行的操作。了解更多关于 accessControl 配置的信息。
apiN用于仅启用应用程序使用的 Dapr sidecar API。了解更多关于 api 配置的信息。
httpPipelineN配置 API 中间件管道中间件管道配置概述
了解更多关于 httpPipeline 配置的信息。
appHttpPipelineN配置应用程序中间件管道中间件管道配置概述
了解更多关于 appHttpPipeline 配置的信息。
componentsN用于指定不能初始化的组件类型的拒绝列表。了解更多关于 components 配置的信息。
featuresN定义启用/禁用的预览功能。了解更多关于 features 配置的信息。
loggingN配置 Dapr 运行时中的日志记录方式。了解更多关于 logging 配置的信息。
metricsN启用或禁用应用程序的监控指标。了解更多关于 metrics 配置的信息。
nameResolutionN服务调用模块的名称解析配置规范。了解更多关于每个组件的 nameResolution 配置的信息。
secretsN限制 Dapr 应用程序可以访问的密钥。了解更多关于 secrets 配置的信息。
tracingN为应用程序开启追踪。了解更多关于 tracing 配置的信息。

控制平面格式

与 Dapr 一起安装的 daprsystem 配置文件应用全局设置,仅在 Dapr 部署到 Kubernetes 时生效。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: daprsystem
  namespace: default
spec:
  mtls:
    enabled: true
    allowedClockSkew: 15m
    workloadCertTTL: 24h

规范字段

字段必需详情示例
mtlsN定义 mTLS 配置allowedClockSkew: 15m
workloadCertTTL:24h
了解更多关于 mtls 配置的信息。

相关链接