From 7c4bbcf75c016033935c2bff54c5670d510954c8 Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Wed, 14 Jun 2023 11:20:45 -0400 Subject: [PATCH 01/10] initial edits Signed-off-by: Hannah Hunter --- .../components => reference/resource-specs}/component-schema.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename daprdocs/content/en/{operations/components => reference/resource-specs}/component-schema.md (100%) diff --git a/daprdocs/content/en/operations/components/component-schema.md b/daprdocs/content/en/reference/resource-specs/component-schema.md similarity index 100% rename from daprdocs/content/en/operations/components/component-schema.md rename to daprdocs/content/en/reference/resource-specs/component-schema.md From 76b869cb81e979e65c0a6690571e92b3e4cdb44b Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Wed, 14 Jun 2023 16:14:17 -0400 Subject: [PATCH 02/10] add resiliency schema doc - still in progress Signed-off-by: Hannah Hunter --- .../en/reference/resource-specs/component-schema.md | 2 +- .../en/reference/resource-specs/httpendpoints-reference.md | 2 +- .../en/reference/resource-specs/resiliency-schema.md | 7 +++++++ 3 files changed, 9 insertions(+), 2 deletions(-) create mode 100644 daprdocs/content/en/reference/resource-specs/resiliency-schema.md diff --git a/daprdocs/content/en/reference/resource-specs/component-schema.md b/daprdocs/content/en/reference/resource-specs/component-schema.md index bf60364cd..89cde4f4d 100644 --- a/daprdocs/content/en/reference/resource-specs/component-schema.md +++ b/daprdocs/content/en/reference/resource-specs/component-schema.md @@ -2,7 +2,7 @@ type: docs title: "Component schema" linkTitle: "Component schema" -weight: 100 +weight: 1000 description: "The basic schema for a Dapr component" --- diff --git a/daprdocs/content/en/reference/resource-specs/httpendpoints-reference.md b/daprdocs/content/en/reference/resource-specs/httpendpoints-reference.md index 66d4f5606..c4293debb 100644 --- a/daprdocs/content/en/reference/resource-specs/httpendpoints-reference.md +++ b/daprdocs/content/en/reference/resource-specs/httpendpoints-reference.md @@ -3,7 +3,7 @@ type: docs title: "HTTPEndpoint spec" linkTitle: "HTTPEndpoint spec" description: "The HTTPEndpoint resource spec" -weight: 300 +weight: 3000 aliases: - "/operations/httpEndpoints/" --- diff --git a/daprdocs/content/en/reference/resource-specs/resiliency-schema.md b/daprdocs/content/en/reference/resource-specs/resiliency-schema.md new file mode 100644 index 000000000..4dfefcc4d --- /dev/null +++ b/daprdocs/content/en/reference/resource-specs/resiliency-schema.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Resiliency schema" +linkTitle: "Resiliency schema" +weight: 2000 +description: "The basic schema for a Dapr component" +--- \ No newline at end of file From 3770cf0712436ce9025ce2cc7f75c8acbaff57c1 Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Mon, 19 Jun 2023 10:42:58 -0400 Subject: [PATCH 03/10] block out the other schemas Signed-off-by: Hannah Hunter --- .../resource-specs/component-schema.md | 6 +- .../resource-specs/httpendpoints-reference.md | 6 +- .../resource-specs/resiliency-schema.md | 146 +++++++++++++++++- 3 files changed, 147 insertions(+), 11 deletions(-) diff --git a/daprdocs/content/en/reference/resource-specs/component-schema.md b/daprdocs/content/en/reference/resource-specs/component-schema.md index 89cde4f4d..c36bded52 100644 --- a/daprdocs/content/en/reference/resource-specs/component-schema.md +++ b/daprdocs/content/en/reference/resource-specs/component-schema.md @@ -1,9 +1,9 @@ --- type: docs -title: "Component schema" -linkTitle: "Component schema" +title: "Component spec" +linkTitle: "Component" weight: 1000 -description: "The basic schema for a Dapr component" +description: "The basic spec for a Dapr component" --- Dapr defines and registers components using a [CustomResourceDefinition](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/). All components are defined as a CRD and can be applied to any hosting environment where Dapr is running, not just Kubernetes. diff --git a/daprdocs/content/en/reference/resource-specs/httpendpoints-reference.md b/daprdocs/content/en/reference/resource-specs/httpendpoints-reference.md index c4293debb..d2f5429e7 100644 --- a/daprdocs/content/en/reference/resource-specs/httpendpoints-reference.md +++ b/daprdocs/content/en/reference/resource-specs/httpendpoints-reference.md @@ -1,9 +1,9 @@ --- type: docs title: "HTTPEndpoint spec" -linkTitle: "HTTPEndpoint spec" -description: "The HTTPEndpoint resource spec" -weight: 3000 +linkTitle: "HTTPEndpoint" +description: "The basic spec for a Dapr HTTPEndpoint resource" +weight: 4000 aliases: - "/operations/httpEndpoints/" --- diff --git a/daprdocs/content/en/reference/resource-specs/resiliency-schema.md b/daprdocs/content/en/reference/resource-specs/resiliency-schema.md index 4dfefcc4d..c3ba272c9 100644 --- a/daprdocs/content/en/reference/resource-specs/resiliency-schema.md +++ b/daprdocs/content/en/reference/resource-specs/resiliency-schema.md @@ -1,7 +1,143 @@ --- type: docs -title: "Resiliency schema" -linkTitle: "Resiliency schema" -weight: 2000 -description: "The basic schema for a Dapr component" ---- \ No newline at end of file +title: "Resiliency spec" +linkTitle: "Resiliency spec" +weight: 3000 +description: "The basic spec for a Dapr resiliency resource" +--- + + +```yml +apiVersion: apiextensions.k8s.io/v1 +kind: CustomResourceDefinition +metadata: + annotations: + controller-gen.kubebuilder.io/version: v0.5.0 + creationTimestamp: null + name: resiliencies.dapr.io + labels: + app.kubernetes.io/part-of: "dapr" +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 From 72c84d40b3a70a3ec4672f054e07458b37acdff9 Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Mon, 19 Jun 2023 10:48:14 -0400 Subject: [PATCH 04/10] add new doc Signed-off-by: Hannah Hunter --- .../resource-specs/subscription-schema.md | 184 ++++++++++++++++++ 1 file changed, 184 insertions(+) create mode 100644 daprdocs/content/en/reference/resource-specs/subscription-schema.md diff --git a/daprdocs/content/en/reference/resource-specs/subscription-schema.md b/daprdocs/content/en/reference/resource-specs/subscription-schema.md new file mode 100644 index 000000000..6d79c7c77 --- /dev/null +++ b/daprdocs/content/en/reference/resource-specs/subscription-schema.md @@ -0,0 +1,184 @@ +--- +type: docs +title: "Subscription spec" +linkTitle: "Subscription spec" +weight: 2000 +description: "The basic spec for a Dapr subscription" +--- + + + +```yml +apiVersion: apiextensions.k8s.io/v1 +kind: CustomResourceDefinition +metadata: + name: subscriptions.dapr.io + labels: + app.kubernetes.io/part-of: "dapr" +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 From 377c92ff7185af1ff76da1ec6890932610f3e678 Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Mon, 19 Jun 2023 11:48:59 -0400 Subject: [PATCH 05/10] interrupted need to save Signed-off-by: Hannah Hunter --- .../content/en/reference/resource-specs/subscription-schema.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/resource-specs/subscription-schema.md b/daprdocs/content/en/reference/resource-specs/subscription-schema.md index 6d79c7c77..906be4a63 100644 --- a/daprdocs/content/en/reference/resource-specs/subscription-schema.md +++ b/daprdocs/content/en/reference/resource-specs/subscription-schema.md @@ -6,7 +6,7 @@ weight: 2000 description: "The basic spec for a Dapr subscription" --- - +The `Subscription` is a Dapr resource that is used to . ```yml apiVersion: apiextensions.k8s.io/v1 From bfa2a66a27b78cde2d60b6b37f542ddd467a1359 Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Mon, 19 Jun 2023 17:44:34 -0400 Subject: [PATCH 06/10] 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 From f3a5d4e4bdd7f5c15842720c953b29726bfd9630 Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Mon, 19 Jun 2023 17:48:53 -0400 Subject: [PATCH 07/10] fix Signed-off-by: Hannah Hunter --- .../content/en/reference/resource-specs/resiliency-schema.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/resource-specs/resiliency-schema.md b/daprdocs/content/en/reference/resource-specs/resiliency-schema.md index 8b2def056..546a1c5d6 100644 --- a/daprdocs/content/en/reference/resource-specs/resiliency-schema.md +++ b/daprdocs/content/en/reference/resource-specs/resiliency-schema.md @@ -57,4 +57,4 @@ targets: # Required | 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 +[Learn more about resiliency policies and targets]({{< ref resiliency-overview.md >}}) \ No newline at end of file From 55a9c26ab61239e081a2eb9dcc50e489a05884cc Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Tue, 20 Jun 2023 11:14:43 -0400 Subject: [PATCH 08/10] updates from mark pt 1 Signed-off-by: Hannah Hunter --- .../pubsub/pubsub-deadletter.md | 12 ++-- .../building-blocks/pubsub/pubsub-raw.md | 5 +- .../pubsub/subscription-methods.md | 5 +- .../resource-specs/resiliency-schema.md | 13 ++-- .../resource-specs/subscription-schema.md | 71 ++++++++++--------- daprdocs/package-lock.json | 6 +- 6 files changed, 62 insertions(+), 50 deletions(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-deadletter.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-deadletter.md index 1f46bf62b..97c9a0db4 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-deadletter.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-deadletter.md @@ -25,13 +25,14 @@ The diagram below is an example of how dead letter topics work. First a message The following YAML shows how to configure a subscription with a dead letter topic named `poisonMessages` for messages consumed from the `orders` topic. This subscription is scoped to an app with a `checkout` ID. ```yaml -apiVersion: dapr.io/v1alpha1 +apiVersion: dapr.io/v2alpha1 kind: Subscription metadata: name: order spec: topic: orders - route: /checkout + routes: + default: /checkout pubsubname: pubsub deadLetterTopic: poisonMessages scopes: @@ -86,13 +87,16 @@ spec: Remember to now configure a subscription to handling the dead letter topics. For example you can create another declarative subscription to receive these on the same or a different application. The example below shows the checkout application subscribing to the `poisonMessages` topic with another subscription and sending these to be handled by the `/failedmessages` endpoint. ```yaml -apiVersion: dapr.io/v1alpha1 +apiVersion: dapr.io/v2alpha1 kind: Subscription metadata: name: deadlettertopics spec: topic: poisonMessages - route: /failedMessages + routes: + rules: + - match: + path: /failedMessages pubsubname: pubsub scopes: - checkout diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-raw.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-raw.md index d5a0fbe61..6e518fa96 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-raw.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-raw.md @@ -141,13 +141,14 @@ $app->start(); Similarly, you can subscribe to raw events declaratively by adding the `rawPayload` metadata entry to your subscription specification. ```yaml -apiVersion: dapr.io/v1alpha1 +apiVersion: dapr.io/v2alpha1 kind: Subscription metadata: name: myevent-subscription spec: topic: deathStarStatus - route: /dsstatus + routes: + default: /dsstatus pubsubname: pubsub metadata: rawPayload: "true" diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md index 965647b92..52747ce9f 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/subscription-methods.md @@ -22,13 +22,14 @@ The examples below demonstrate pub/sub messaging between a `checkout` app and an You can subscribe declaratively to a topic using an external component file. This example uses a YAML component file named `subscription.yaml`: ```yaml -apiVersion: dapr.io/v1alpha1 +apiVersion: dapr.io/v2alpha1 kind: Subscription metadata: name: order spec: topic: orders - route: /checkout + routes: + default: /checkout pubsubname: pubsub scopes: - orderprocessing diff --git a/daprdocs/content/en/reference/resource-specs/resiliency-schema.md b/daprdocs/content/en/reference/resource-specs/resiliency-schema.md index 546a1c5d6..a17a9fccb 100644 --- a/daprdocs/content/en/reference/resource-specs/resiliency-schema.md +++ b/daprdocs/content/en/reference/resource-specs/resiliency-schema.md @@ -6,22 +6,24 @@ 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. +The `Resiliency` Dapr resource allows you to define and apply fault tolerance resiliency policies. Resiliency specs are applied when the Dapr sidecar starts. ```yml apiVersion: dapr.io/v1alpha1 kind: Resiliency metadata: name: +version: v1alpha1 scopes: - spec: policies: # Required - timeouts: # Replce with any unique name + timeouts: # Replace with any unique name timeoutName: retries: retryName: # Replace with any unique name - policy: exponential + policy: + duration: maxInterval: maxRetries: circuitBreakers: @@ -53,8 +55,9 @@ targets: # Required | 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. | | +| policies | Y | The configuration of resiliency policies, including:
  • `timeouts`
  • `retries`
  • `circuitBreakers`

[See more examples with all of the built-in policies]({{< ref policies.md >}}) | timeout: `general`
retry: `retryForever`
circuit breaker: `simpleCB` | +| targets | Y | The configuration for the applications, actors, or components that use the resiliency policies.
[See more examples in the resiliency targets guide]({{< ref targets.md >}}) | `apps`
`components`
`actors` | + ## Related links [Learn more about resiliency policies and targets]({{< ref resiliency-overview.md >}}) \ 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 c18dd43cb..a14aca415 100644 --- a/daprdocs/content/en/reference/resource-specs/subscription-schema.md +++ b/daprdocs/content/en/reference/resource-specs/subscription-schema.md @@ -6,44 +6,14 @@ weight: 2000 description: "The basic spec for a Dapr subscription" --- -The `Subscription` Dapr resource allows you to subscribe declaratively to a topic using an external component YAML file. +The `Subscription` Dapr resource allows you to subscribe declaratively to a topic using an external component YAML file. This guide demonstrates two subscription API versions: -## `v1alpha1` - -The following is the basic version `v1alpha1` spec for a `Subscription` resource. - -```yml -apiVersion: dapr.io/v1alpha1 -kind: Subscription -metadata: - name: -spec: - 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` | +- `v2alpha` (default spec) +- `v1alpha1` (deprecated) ## `v2alpha1` -The following the basic `v2alpha1` spec for a `Subscription` resource. +The following is the basic `v2alpha1` spec for a `Subscription` resource. `v2alpha1` is the default spec for the subscription API. ```yml apiVersion: dapr.io/v2alpha1 @@ -78,6 +48,39 @@ scopes: | bulksubscribe | N | Enable bulk subscribe properties. | `true`, `false` | +## `v1alpha1` + +The following is the basic version `v1alpha1` spec for a `Subscription` resource. `v1alpha1` is now deprecated. + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Subscription +metadata: + name: +spec: + 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` | + ## 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 >}}) diff --git a/daprdocs/package-lock.json b/daprdocs/package-lock.json index adc813bba..1a80bae53 100644 --- a/daprdocs/package-lock.json +++ b/daprdocs/package-lock.json @@ -90,9 +90,9 @@ "dev": true }, "node_modules/ansi-regex": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.0.tgz", - "integrity": "sha512-bY6fj56OUQ0hU1KjFNDQuJFezqKdrAyFdIevADiqrWHwSlbmBNMHp5ak2f40Pm8JTFyM2mqxkG6ngkHO11f/lg==", + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", "dev": true, "engines": { "node": ">=8" From 323d3a2ef779ec3ccf46a09d7256b2909ac29271 Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Wed, 21 Jun 2023 09:41:58 -0400 Subject: [PATCH 09/10] remove file from PR Signed-off-by: Hannah Hunter --- daprdocs/package-lock.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/daprdocs/package-lock.json b/daprdocs/package-lock.json index 1a80bae53..adc813bba 100644 --- a/daprdocs/package-lock.json +++ b/daprdocs/package-lock.json @@ -90,9 +90,9 @@ "dev": true }, "node_modules/ansi-regex": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", - "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.0.tgz", + "integrity": "sha512-bY6fj56OUQ0hU1KjFNDQuJFezqKdrAyFdIevADiqrWHwSlbmBNMHp5ak2f40Pm8JTFyM2mqxkG6ngkHO11f/lg==", "dev": true, "engines": { "node": ">=8" From 0ad633bf665a4f8e11cdf20f101541bc28287dae Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Wed, 21 Jun 2023 09:43:30 -0400 Subject: [PATCH 10/10] update toc Signed-off-by: Hannah Hunter --- .../content/en/reference/resource-specs/resiliency-schema.md | 2 +- .../content/en/reference/resource-specs/subscription-schema.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/daprdocs/content/en/reference/resource-specs/resiliency-schema.md b/daprdocs/content/en/reference/resource-specs/resiliency-schema.md index a17a9fccb..58d60cb20 100644 --- a/daprdocs/content/en/reference/resource-specs/resiliency-schema.md +++ b/daprdocs/content/en/reference/resource-specs/resiliency-schema.md @@ -1,7 +1,7 @@ --- type: docs title: "Resiliency spec" -linkTitle: "Resiliency spec" +linkTitle: "Resiliency" weight: 3000 description: "The basic spec for a Dapr resiliency resource" --- diff --git a/daprdocs/content/en/reference/resource-specs/subscription-schema.md b/daprdocs/content/en/reference/resource-specs/subscription-schema.md index a14aca415..b3a4e638a 100644 --- a/daprdocs/content/en/reference/resource-specs/subscription-schema.md +++ b/daprdocs/content/en/reference/resource-specs/subscription-schema.md @@ -1,7 +1,7 @@ --- type: docs title: "Subscription spec" -linkTitle: "Subscription spec" +linkTitle: "Subscription" weight: 2000 description: "The basic spec for a Dapr subscription" ---