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 store 的名称,元数据中的 secretKeyRef 在此处查找组件中使用的密钥名称参见操作指南:在组件中引用密钥
scopesN组件限制的应用程序,由其应用 ID 指定order-processorcheckout
metadata-关于组件注册的信息
metadata.nameY组件的名称prod-statestore
metadata.namespaceN组件的命名空间,适用于具有命名空间的托管环境myapp-namespace
spec-关于组件资源的详细信息
spec.typeY组件的类型state.redis
spec.versionY组件的版本v1
spec.initTimeoutN组件初始化的超时时长。默认为 5s5m1h20s
spec.ignoreErrorsN告诉 Dapr 边车如果组件加载失败则继续初始化。默认为 falsefalse
spec.metadata-组件特定配置的键/值对。有关字段,请参阅您的组件定义
spec.metadata.nameY组件特定属性的名称及其值- name: secretsFile
value: 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 规范

Dapr subscription 的基本规范

Subscription Dapr 资源允许你使用外部组件 YAML 文件以声明方式订阅 topic。

本指南演示了两个 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 字段

字段必填详情示例
topicY组件订阅的 topic 名称。orders
routesY此 topic 的路由配置,包括指定将消息发送到特定路径的条件。包含以下字段:
  • match:用于匹配事件的 CEL 表达式。如果未指定,该路由被视为默认路由。
  • path:匹配此规则的事件的路径。
所有 topic 消息发送到的端点。
match: event.type == "widget"
path: /widgets
pubsubnameN你的发布订阅组件的名称。pubsub
deadLetterTopicN转发不可传递消息的死信 topic 名称。poisonMessages
bulkSubscribeN启用批量订阅属性。true, false
metadataN设置订阅元数据。{"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 字段

字段必填详情示例
topicY组件订阅的 topic 名称。orders
routeY所有 topic 消息发送到的端点。/checkout
pubsubnameN你的发布订阅组件的名称。pubsub
deadlettertopicN转发不可传递消息的死信 topic 名称。poisonMessages
metadataN设置订阅元数据。{"key": "value"}
bulksubscribeN启用批量订阅属性。true, false

相关链接

3 - 弹性规范

Dapr 弹性资源的基本规范

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>

规范字段

字段必填详情示例
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>

规范字段

字段必填说明示例
baseUrlY非 Dapr 端点的基础 URL"https://api.github.com""http://api.github.com"
headersN服务调用所用的 HTTP 请求头name: "Accept-Language" value: "en-US"
name: "Authorization" secretKeyRef.name: "my-secret" secretKeyRef.key: "myGithubToken"
clientTLSN启用对端点的 TLS 身份验证,支持根证书、客户端证书和私钥的任意标准组合

相关链接

了解如何调用非 Dapr 端点。

5 - 配置规范

Dapr Configuration 资源的基本规范

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>

规格字段

字段必需详情示例
accessControlN应用于被调用应用的 Dapr 边车。用于配置策略,限制调用应用通过服务调用在被调用应用上可以执行的操作。了解更多关于 accessControl 配置的信息。
apiN用于仅启用应用所使用的 Dapr 边车 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 配置的信息。

相关链接