From bfa2a66a27b78cde2d60b6b37f542ddd467a1359 Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Mon, 19 Jun 2023 17:44:34 -0400 Subject: [PATCH] update examples Signed-off-by: Hannah Hunter --- .../howto-invoke-non-dapr-endpoints.md | 4 +- ...s-reference.md => httpendpoints-schema.md} | 0 .../resource-specs/resiliency-schema.md | 179 ++++--------- .../resource-specs/subscription-schema.md | 245 ++++++------------ 4 files changed, 123 insertions(+), 305 deletions(-) rename daprdocs/content/en/reference/resource-specs/{httpendpoints-reference.md => httpendpoints-schema.md} (100%) diff --git a/daprdocs/content/en/developing-applications/building-blocks/service-invocation/howto-invoke-non-dapr-endpoints.md b/daprdocs/content/en/developing-applications/building-blocks/service-invocation/howto-invoke-non-dapr-endpoints.md index 8196bd0b1..4d365c733 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/service-invocation/howto-invoke-non-dapr-endpoints.md +++ b/daprdocs/content/en/developing-applications/building-blocks/service-invocation/howto-invoke-non-dapr-endpoints.md @@ -47,7 +47,7 @@ The diagram below is an overview of how Dapr's service invocation works when inv ## Using an HTTPEndpoint resource or FQDN URL for non-Dapr endpoints There are two ways to invoke a non-Dapr endpoint when communicating either to Dapr applications or non-Dapr applications. A Dapr application can invoke a non-Dapr endpoint by providing one of the following: -- A named `HTTPEndpoint` resource, including defining an `HTTPEndpoint` resource type. See the [HTTPEndpoint reference]({{< ref httpendpoints-reference.md >}}) guide for an example. +- A named `HTTPEndpoint` resource, including defining an `HTTPEndpoint` resource type. See the [HTTPEndpoint reference]({{< ref httpendpoints-schema.md >}}) guide for an example. ```sh localhost:3500/v1.0/invoke//method/ @@ -81,7 +81,7 @@ curl http://localhost:3602/v1.0/invoke/orderprocessor/method/checkout ## Related Links -- [HTTPEndpoint reference]({{< ref httpendpoints-reference.md >}}) +- [HTTPEndpoint reference]({{< ref httpendpoints-schema.md >}}) - [Service invocation overview]({{< ref service-invocation-overview.md >}}) - [Service invocation API specification]({{< ref service_invocation_api.md >}}) diff --git a/daprdocs/content/en/reference/resource-specs/httpendpoints-reference.md b/daprdocs/content/en/reference/resource-specs/httpendpoints-schema.md similarity index 100% rename from daprdocs/content/en/reference/resource-specs/httpendpoints-reference.md rename to daprdocs/content/en/reference/resource-specs/httpendpoints-schema.md diff --git a/daprdocs/content/en/reference/resource-specs/resiliency-schema.md b/daprdocs/content/en/reference/resource-specs/resiliency-schema.md index c3ba272c9..8b2def056 100644 --- a/daprdocs/content/en/reference/resource-specs/resiliency-schema.md +++ b/daprdocs/content/en/reference/resource-specs/resiliency-schema.md @@ -6,138 +6,55 @@ weight: 3000 description: "The basic spec for a Dapr resiliency resource" --- +The `Resiliency` Dapr resource allows you to define and apply fault tolerance resiliency polcies. Resiliency specs are applied with the Dapr sidecar starts. ```yml -apiVersion: apiextensions.k8s.io/v1 -kind: CustomResourceDefinition +apiVersion: dapr.io/v1alpha1 +kind: Resiliency metadata: - annotations: - controller-gen.kubebuilder.io/version: v0.5.0 - creationTimestamp: null - name: resiliencies.dapr.io - labels: - app.kubernetes.io/part-of: "dapr" + name: +scopes: + - spec: - group: dapr.io - names: - kind: Resiliency - listKind: ResiliencyList - plural: resiliencies - singular: resiliency - categories: - - dapr - scope: Namespaced - versions: - - name: v1alpha1 - schema: - openAPIV3Schema: - properties: - apiVersion: - description: 'APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources' - type: string - kind: - description: 'Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds' - type: string - metadata: - type: object - scopes: - items: - type: string - type: array - spec: - properties: - policies: - properties: - circuitBreakers: - additionalProperties: - properties: - interval: - type: string - maxRequests: - type: integer - timeout: - type: string - trip: - type: string - type: object - type: object - retries: - additionalProperties: - properties: - duration: - type: string - maxInterval: - type: string - maxRetries: - type: integer - policy: - type: string - type: object - type: object - timeouts: - additionalProperties: - type: string - type: object - type: object - targets: - properties: - actors: - additionalProperties: - properties: - circuitBreaker: - type: string - circuitBreakerCacheSize: - type: integer - circuitBreakerScope: - type: string - retry: - type: string - timeout: - type: string - type: object - type: object - apps: - additionalProperties: - properties: - circuitBreaker: - type: string - circuitBreakerCacheSize: - type: integer - retry: - type: string - timeout: - type: string - type: object - type: object - components: - additionalProperties: - properties: - inbound: - properties: - circuitBreaker: - type: string - retry: - type: string - timeout: - type: string - type: object - outbound: - properties: - circuitBreaker: - type: string - retry: - type: string - timeout: - type: string - type: object - type: object - type: object - type: object - required: - - policies - - targets - type: object - type: object - served: true - storage: true -``` \ No newline at end of file + policies: # Required + timeouts: # Replce with any unique name + timeoutName: + retries: + retryName: # Replace with any unique name + policy: exponential + maxInterval: + maxRetries: + circuitBreakers: + circuitBreakerName: # Replace with any unique name + maxRequests: + timeout: + trip: +targets: # Required + apps: + appID: # Replace with scoped app ID + timeout: + retry: + circuitBreaker: + actors: + myActorType: + timeout: + retry: + circuitBreaker: + circuitBreakerCacheSize: + components: + componentName: # Replace with your component name + outbound: + timeout: + retry: + circuitBreaker: +``` + +## Spec fields + +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| policies | Y | The configuration of resiliency policies, including:
  • `timeouts`
  • `retries`
  • `circuitBreakers`
| timeout: `general`
retry: `retryForever`
circuit breaker: `simpleCB` | +| targets | Y | The configuration for the applications, actors, or components that use the resiliency policies. | | + +## Related links +[Learn more about resiliency policies and targets]({{< ref resiliency >}}) \ No newline at end of file diff --git a/daprdocs/content/en/reference/resource-specs/subscription-schema.md b/daprdocs/content/en/reference/resource-specs/subscription-schema.md index 906be4a63..c18dd43cb 100644 --- a/daprdocs/content/en/reference/resource-specs/subscription-schema.md +++ b/daprdocs/content/en/reference/resource-specs/subscription-schema.md @@ -6,179 +6,80 @@ weight: 2000 description: "The basic spec for a Dapr subscription" --- -The `Subscription` is a Dapr resource that is used to . +The `Subscription` Dapr resource allows you to subscribe declaratively to a topic using an external component YAML file. + +## `v1alpha1` + +The following is the basic version `v1alpha1` spec for a `Subscription` resource. ```yml -apiVersion: apiextensions.k8s.io/v1 -kind: CustomResourceDefinition +apiVersion: dapr.io/v1alpha1 +kind: Subscription metadata: - name: subscriptions.dapr.io - labels: - app.kubernetes.io/part-of: "dapr" + name: spec: - group: dapr.io - conversion: - strategy: Webhook - webhook: - clientConfig: - service: - namespace: replaceme # Patched by post-install webhook - name: dapr-webhook - path: /convert - #caBundle: Patched by post-install webhook - conversionReviewVersions: - - v1 - - v2alpha1 - versions: - - name: v1alpha1 - schema: - openAPIV3Schema: - description: Subscription describes an pub/sub event subscription. - properties: - apiVersion: - description: 'APIVersion defines the versioned schema of this representation - of an object. Servers should convert recognized schemas to the latest - internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources' - type: string - kind: - description: 'Kind is a string value representing the REST resource this - object represents. Servers may infer this from the endpoint the client - submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds' - type: string - metadata: - type: object - scopes: - items: - type: string - type: array - spec: - description: SubscriptionSpec is the spec for an event subscription. - properties: - pubsubname: - type: string - route: - type: string - topic: - type: string - deadLetterTopic: - type: string - bulkSubscribe: - description: Represents bulk subscribe properies - properties: - enabled: - type: boolean - maxMessagesCount: - type: integer - maxAwaitDurationMs: - type: integer - required: - - enabled - type: object - metadata: - additionalProperties: - type: string - type: object - required: - - pubsubname - - route - - topic - type: object - type: object - served: true - storage: false - - name: v2alpha1 - schema: - openAPIV3Schema: - description: Subscription describes an pub/sub event subscription. - properties: - apiVersion: - description: 'APIVersion defines the versioned schema of this representation - of an object. Servers should convert recognized schemas to the latest - internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources' - type: string - kind: - description: 'Kind is a string value representing the REST resource this - object represents. Servers may infer this from the endpoint the client - submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds' - type: string - metadata: - type: object - scopes: - items: - type: string - type: array - spec: - description: SubscriptionSpec is the spec for an event subscription. - properties: - metadata: - additionalProperties: - type: string - description: The optional metadata to provide the subscription. - type: object - pubsubname: - description: The PubSub component name. - type: string - routes: - description: The Routes configuration for this topic. - properties: - default: - type: string - rules: - description: The list of rules for this topic. - items: - description: Rule is used to specify the condition for sending - a message to a specific path. - properties: - match: - description: The optional CEL expression used to match the - event. If the match is not specified, then the route is - considered the default. The rules are tested in the order - specified, so they should be define from most-to-least - specific. The default route should appear last in the - list. - type: string - path: - description: The path for events that match this rule. - type: string - required: - - match - - path - type: object - type: array - type: object - topic: - description: The topic name to subscribe to. - type: string - deadLetterTopic: - description: The optional dead letter queue for this topic to send events to. - type: string - bulkSubscribe: - description: Represents bulk subscribe properies - properties: - enabled: - type: boolean - maxMessagesCount: - type: integer - maxAwaitDurationMs: - type: integer - required: - - enabled - type: object - required: - - pubsubname - - routes - - topic - type: object - type: object - served: true - storage: true - names: - kind: Subscription - listKind: SubscriptionList - plural: subscriptions - singular: subscription - categories: - - all - - dapr - scope: Namespaced -``` \ No newline at end of file + version: v1alpha1 + topic: # Required + route: # Required + pubsubname: # Required + deadLetterTopic: # Optional + bulkSubscribe: # Optional + - enabled: + - maxmessages: + - maxawaitduration: +scopes: +- +``` + +### Spec fields + +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| topic | Y | The name of the topic to which your component subscribes. | `orders` | +| route | Y | The endpoint to which all topic messages are sent. | `/checkout` | +| pubsubname | N | The name of your pub/sub component. | `pubsub` | +| deadlettertopic | N | The name of the dead letter topic that forwards undeliverable messages. | `poisonMessages` | +| bulksubscribe | N | Enable bulk subscribe properties. | `true`, `false` | + +## `v2alpha1` + +The following the basic `v2alpha1` spec for a `Subscription` resource. + +```yml +apiVersion: dapr.io/v2alpha1 +kind: Subscription +metadata: + name: +spec: + version: v2alpha1 + topic: # Required + routes: # Required + - rules: + - match: + path: + pubsubname: # Required + deadlettertopic: # Optional + bulksubscribe: # Optional + - enabled: + - maxmessages: + - maxawaitduration: +scopes: +- +``` + +### Spec fields + +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| topic | Y | The name of the topic to which your component subscribes. | `orders` | +| routes | Y | The routes configuration for this topic, including specifying the condition for sending a message to a specific path. Includes the following fields:
  • match: _Optional._ The CEL expression used to match the event. If not specified, the route is considered the default.
  • path: The path for events that match this rule.
The endpoint to which all topic messages are sent. | `match: event.type == "widget"`
`path: /widgets` | +| pubsubname | N | The name of your pub/sub component. | `pubsub` | +| deadlettertopic | N | The name of the dead letter topic that forwards undeliverable messages. | `poisonMessages` | +| bulksubscribe | N | Enable bulk subscribe properties. | `true`, `false` | + + +## Related links +- [Learn more about the declarative subscription method]({{< ref "subscription-methods.md#declarative-subscriptions" >}}) +- [Learn more about dead letter topics]({{< ref pubsub-deadletter.md >}}) +- [Learn more about routing messages]({{< ref "howto-route-messages.md#declarative-subscription" >}}) +- [Learn more about bulk subscribing]({{< ref pubsub-bulk.md >}}) \ No newline at end of file