From 08224ba92a89fd4ba0fcce7ecfd2f39744196c57 Mon Sep 17 00:00:00 2001 From: Ashleigh Brennan Date: Tue, 9 Mar 2021 13:33:22 -0600 Subject: [PATCH] Adding event delivery parameter docs --- _topic_map.yml | 12 +++-- .../serverless-creating-subscriptions-kn.adoc | 17 ++++--- .../serverless-deleting-subscriptions-kn.adoc | 17 +++++++ modules/serverless-describe-subs-kn.adoc | 49 +++++++++++++++++++ ...ss-event-delivery-component-behaviors.adoc | 20 ++++++++ modules/serverless-list-subs-kn.adoc | 35 +++++++++++++ ...ss-subscription-event-delivery-config.adoc | 34 +++++++++++++ .../serverless-update-subscriptions-kn.adoc | 39 +++++++++++++++ .../event_workflows/serverless-channels.adoc | 18 +++---- .../serverless-event-delivery.adoc | 33 +++++++++++++ .../event_workflows/serverless-subs.adoc | 32 ++++++++++++ .../serverless-using-brokers.adoc | 2 +- 12 files changed, 287 insertions(+), 21 deletions(-) create mode 100644 modules/serverless-deleting-subscriptions-kn.adoc create mode 100644 modules/serverless-describe-subs-kn.adoc create mode 100644 modules/serverless-event-delivery-component-behaviors.adoc create mode 100644 modules/serverless-list-subs-kn.adoc create mode 100644 modules/serverless-subscription-event-delivery-config.adoc create mode 100644 modules/serverless-update-subscriptions-kn.adoc create mode 100644 serverless/event_workflows/serverless-event-delivery.adoc create mode 100644 serverless/event_workflows/serverless-subs.adoc diff --git a/_topic_map.yml b/_topic_map.yml index 43592047e1..ad31d0f3f8 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -2828,15 +2828,21 @@ Topics: - Name: Splitting traffic between revisions File: splitting-traffic-between-revisions-knative # Knative Eventing -- Name: Event workflows +- Name: Knative Eventing workflows Dir: event_workflows Topics: # Brokers - - Name: Event delivery workflows using brokers and triggers + - Name: Broker and trigger workflows File: serverless-using-brokers # Channels - - Name: Event delivery workflows using channels + - Name: Channel workflows File: serverless-channels +# Subscriptions + - Name: Using subscriptions + File: serverless-subs +# Event delivery + - Name: Event delivery + File: serverless-event-delivery # Event sources - Name: Event sources Dir: event_sources diff --git a/modules/serverless-creating-subscriptions-kn.adoc b/modules/serverless-creating-subscriptions-kn.adoc index 2275ed7002..c264152207 100644 --- a/modules/serverless-creating-subscriptions-kn.adoc +++ b/modules/serverless-creating-subscriptions-kn.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * serverless/event_workflows/serverless-channels.adoc +// * serverless/event_workflows/serverless-subs.adoc [id="serverless-creating-subscriptions-kn_{context}"] = Creating subscriptions using the Knative CLI @@ -17,16 +17,21 @@ To create subscriptions using the `kn` CLI, ensure that: .Procedure -* Create a subscription to connect a sink to a channel. +* Create a subscription to connect a sink to a channel: + [source,terminal] ---- $ kn subscription create \ - --channel : \ - --sink : \ - --sink-reply : \ - --sink-dead-letter : + --channel : \ <1> + --sink : \ <2> + --sink-dead-letter : <3> ---- +<1> `--channel` specifies the source for cloud events that should be processed. You must provide the channel name. If you are not using the default `InMemoryChannel` channel that is backed by the `Channel` resource, you must prefix the channel name with the `` for the specified channel type. For example, this will be `messaging.knative.dev:v1beta1:KafkaChannel` for a Kafka backed channel. +<2> `--sink` specifies the target destination to which the event should be delivered. By default, the `` is interpreted as a Knative service of this name, in the same namespace as the subscription. You can specify the type of the sink by using one of the following prefixes: +`ksvc`:: A Knative service. +`channel`:: A channel that should be used as destination. Only default channel types can be referenced here. +`broker`:: An Eventing broker. +<3> Optional: `--sink-dead-letter` is an optional flag that can be used to specify a sink which events should be sent to in cases where events fail to be delivered. For more information, see the {ServerlessProductName} _Event delivery_ documentation. + .Example command [source,terminal] diff --git a/modules/serverless-deleting-subscriptions-kn.adoc b/modules/serverless-deleting-subscriptions-kn.adoc new file mode 100644 index 0000000000..12a228bb6a --- /dev/null +++ b/modules/serverless-deleting-subscriptions-kn.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * serverless/event_workflows/serverless-subs.adoc + +[id="serverless-deleting-subscriptions-kn_{context}"] += Deleting subscriptions using the Knative CLI + +You can delete a subscription by using the `kn` CLI. + +.Procedure + +* Delete a subscription: ++ +[source,terminal] +---- +$ kn subscription delete +---- diff --git a/modules/serverless-describe-subs-kn.adoc b/modules/serverless-describe-subs-kn.adoc new file mode 100644 index 0000000000..99266c6b3c --- /dev/null +++ b/modules/serverless-describe-subs-kn.adoc @@ -0,0 +1,49 @@ +// Module included in the following assemblies: +// +// * serverless/event_workflows/serverless-subs.adoc + +[id="serverless-describe-subs-kn_{context}"] += Describing subscriptions using the Knative CLI + +You can print information about a subscription in the terminal by using the `kn` CLI. + +.Prerequisites + +To describe subscriptions using the `kn` CLI, ensure that: + +* You have installed the `kn` CLI. +* You have created a subscription in your cluster. + +.Procedure + +* Describe a subscription: ++ +[source,terminal] +---- +$ kn subscription describe +---- ++ +.Example output +[source,terminal] +---- +Name: my-subscription +Namespace: default +Annotations: messaging.knative.dev/creator=openshift-user, messaging.knative.dev/lastModifier=min ... +Age: 43s +Channel: Channel:my-channel (messaging.knative.dev/v1) +Subscriber: + URI: http://edisplay.default.example.com +Reply: + Name: default + Resource: Broker (eventing.knative.dev/v1) +DeadLetterSink: + Name: my-sink + Resource: Service (serving.knative.dev/v1) + +Conditions: + OK TYPE AGE REASON + ++ Ready 43s + ++ AddedToChannel 43s + ++ ChannelReady 43s + ++ ReferencesResolved 43s +---- diff --git a/modules/serverless-event-delivery-component-behaviors.adoc b/modules/serverless-event-delivery-component-behaviors.adoc new file mode 100644 index 0000000000..08d5ac4576 --- /dev/null +++ b/modules/serverless-event-delivery-component-behaviors.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// serverless/event_workflows/serverless-event-delivery.adoc + +[id="serverless-event-delivery-component-behaviors_{context}"] += Event delivery behavior for Knative Eventing channels + +Different Knative Eventing channel types have their own behavior patterns that are followed for event delivery. Developers can set event delivery parameters in the subscription configuration to ensure that any events that fail to be delivered from channels to an event sink are retried. You must also configure a dead letter sink for subscriptions if you want to provide a sink where events that are not eventually delivered can be stored, otherwise undelivered events are dropped. + +== Event delivery behavior for Apache Kafka channels + +If an event is successfully delivered to a Kafka channel or broker receiver, the receiver responds with a `202` status code, which means that the event has been safely stored inside a Kafka topic and is not lost. If the receiver responds with any other status code, the event is not safely stored, and steps must be taken by the user to resolve this issue. + +== Delivery failure status codes + +The channel or broker receiver can respond with the following status codes if an event fails to be delivered: + +`500`:: This is a generic status code which means that the event was not delivered successfully. +`404`:: This status code means that the channel or broker the event is being delivered to does not exist, or that the `Host` header is incorrect. +`400`:: This status code means that the event being sent to the receiver is invalid. diff --git a/modules/serverless-list-subs-kn.adoc b/modules/serverless-list-subs-kn.adoc new file mode 100644 index 0000000000..c8a3fd1e43 --- /dev/null +++ b/modules/serverless-list-subs-kn.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * serverless/event_workflows/serverless-subs.adoc + +[id="serverless-list-subs-kn_{context}"] += Listing subscriptions using the Knative CLI + +You can list existing subscriptions on your cluster by using the `kn` CLI. + +.Prerequisites + +* You have installed the `kn` CLI. + +.Procedure + +* List subscriptions on your cluster: ++ +[source,terminal] +---- +$ kn subscription list +---- ++ +.Example output +[source,terminal] +---- +NAME CHANNEL SUBSCRIBER REPLY DEAD LETTER SINK READY REASON +mysubscription Channel:mychannel ksvc:event-display True +---- +// . Optional: List subscriptions in YAML format: +// + +// [source,terminal] +// ---- +// $ kn subscription list -o yaml +// ---- +// Add this step once I have an example output, optional so non urgent diff --git a/modules/serverless-subscription-event-delivery-config.adoc b/modules/serverless-subscription-event-delivery-config.adoc new file mode 100644 index 0000000000..1b37f1d5de --- /dev/null +++ b/modules/serverless-subscription-event-delivery-config.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// serverless/event_workflows/serverless-event-delivery.adoc + +[id="serverless-subscription-event-delivery-config_{context}"] += Configuring event delivery failure parameters using subscriptions + +Developers can configure event delivery parameters for individual subscriptions by modifying the `delivery` settings for a `Subscription` object. + +.Example subscription YAML +[source,yaml] +---- +apiVersion: messaging.knative.dev/v1 +kind: Subscription +metadata: + name: + namespace: +spec: + delivery: + deadLetterSink: <1> + ref: + apiVersion: serving.knative.dev/v1 + kind: Service + name: + backoffDelay: <2> + backoffPolicy: <3> + retry: <4> +---- +<1> Configuration settings to enable using a dead letter sink. This tells the subscription what happens to events that cannot be delivered to the subscriber. ++ +When this is configured, events that fail to be delivered are sent to the dead letter sink destination. The destination can be a Knative service or a URI. +<2> You can set the `backoffDelay` delivery parameter to specify the time delay before an event delivery retry is attempted after a failure. The duration of the `backoffDelay` parameter is specified using the https://en.wikipedia.org/wiki/ISO_8601#Durations[ISO 8601] format. For example, `PT1S` specifies a 1 second delay. +<3> The `backoffPolicy` delivery parameter can be used to specify the retry back off policy. The policy can be specified as either `linear` or `exponential`. When using the `linear` back off policy, the back off delay is the time interval specified between retries. When using the `exponential` back off policy, the back off delay is equal to `backoffDelay*2^`. +<4> The number of times that event delivery is retried before the event is sent to the dead letter sink. diff --git a/modules/serverless-update-subscriptions-kn.adoc b/modules/serverless-update-subscriptions-kn.adoc new file mode 100644 index 0000000000..4c0bd405d9 --- /dev/null +++ b/modules/serverless-update-subscriptions-kn.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * serverless/event_workflows/serverless-subs.adoc + +[id="serverless-update-subscriptions-kn_{context}"] += Updating subscriptions + +You can update a subscription by using the `kn` CLI. + +.Prerequisites + +To update subscriptions using the `kn` CLI, ensure that: + +* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. +* You have installed the `kn` CLI. +* You have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. +* You have created a subscription. + +.Procedure + +* Update a subscription: ++ +[source,terminal] +---- +$ kn subscription update \ + --sink : \ <1> + --sink-dead-letter : <2> +---- +<1> `--sink` specifies the updated target destination to which the event should be delivered. You can specify the type of the sink by using one of the following prefixes: +`ksvc`:: A Knative service. +`channel`:: A channel that should be used as destination. Only default channel types can be referenced here. +`broker`:: An Eventing broker. +<2> Optional: `--sink-dead-letter` is an optional flag that can be used to specify a sink which events should be sent to in cases where events fail to be delivered. For more information, see the {ServerlessProductName} _Event delivery_ documentation. ++ +.Example command +[source,terminal] +---- +$ kn subscription update mysubscription --sink ksvc:event-display +---- diff --git a/serverless/event_workflows/serverless-channels.adoc b/serverless/event_workflows/serverless-channels.adoc index ad6c389d24..00b402bfea 100644 --- a/serverless/event_workflows/serverless-channels.adoc +++ b/serverless/event_workflows/serverless-channels.adoc @@ -1,6 +1,6 @@ include::modules/serverless-document-attributes.adoc[] [id="serverless-channels"] -= Event delivery workflows using channels += Channel workflows include::modules/common-attributes.adoc[] :context: serverless-channels @@ -39,14 +39,10 @@ These events can then be forwarded to an event sink by using subscriptions. include::modules/serverless-connect-channel-source-odc.adoc[leveloffset=+2] -[id="serverless-channels-creating-subs"] -== Creating subscriptions - -Developers can create subscriptions that allow event sinks to subscribe to channels and receive events directly. - -include::modules/serverless-creating-subscriptions-odc.adoc[leveloffset=+2] -include::modules/serverless-creating-subscriptions-kn.adoc[leveloffset=+2] -include::modules/serverless-creating-subscriptions-yaml.adoc[leveloffset=+2] - -// delete channels +// deleting channels include::modules/serverless-delete-channel-kn.adoc[leveloffset=+1] + +[id="serverless-channels-next-steps"] +== Next steps + +* After you have created a channel, see xref:../../serverless/event_workflows/serverless-subs.adoc#serverless-subs[Using subscriptions] for information about creating and using subscriptions for event delivery. diff --git a/serverless/event_workflows/serverless-event-delivery.adoc b/serverless/event_workflows/serverless-event-delivery.adoc new file mode 100644 index 0000000000..16d30a0352 --- /dev/null +++ b/serverless/event_workflows/serverless-event-delivery.adoc @@ -0,0 +1,33 @@ +include::modules/serverless-document-attributes.adoc[] +[id="serverless-event-delivery"] += Event delivery +include::modules/common-attributes.adoc[] +:context: serverless-event-delivery + +toc::[] + +You can configure event delivery parameters for Knative Eventing that are applied in cases where an event fails to be delivered by a xref:../../serverless/event_workflows/serverless-subs.adoc#serverless-subs[subscription]. Event delivery parameters are configured individually per subscription. +// TODO: Update docs to add triggers once this is implemented. + +include::modules/serverless-event-delivery-component-behaviors.adoc[leveloffset=+1] + +[id="serverless-event-delivery-parameters"] +== Configurable parameters + +The following parameters can be configured for event delivery. + +Dead letter sink:: You can configure the `deadLetterSink` delivery parameter so that if an event fails to be delivered it is sent to the specified event sink. + +Retries:: You can set a minimum number of times that the delivery must be retried before the event is sent to the dead letter sink, by configuring the `retry` delivery parameter with an integer value. + +Back off delay:: You can set the `backoffDelay` delivery parameter to specify the time delay before an event delivery retry is attempted after a failure. The duration of the `backoffDelay` parameter is specified using the https://en.wikipedia.org/wiki/ISO_8601#Durations[ISO 8601] format. + +Back off policy:: The `backoffPolicy` delivery parameter can be used to specify the retry back off policy. The policy can be specified as either `linear` or `exponential`. When using the `linear` back off policy, the back off delay is the time interval specified between retries. When using the `exponential` backoff policy, the back off delay is equal to `backoffDelay*2^`. + +include::modules/serverless-subscription-event-delivery-config.adoc[leveloffset=+1] + +[id="serverless-event-delivery-additional-resources"] +== Additional resources + +* See xref:../../serverless/event_workflows/serverless-channels.adoc#serverless-channels[Knative Eventing workflows using channels] for more information about subscriptions. +* See xref:../../serverless/event_workflows/serverless-subs.adoc#serverless-subs-creating-subs[Creating subscriptions]. diff --git a/serverless/event_workflows/serverless-subs.adoc b/serverless/event_workflows/serverless-subs.adoc new file mode 100644 index 0000000000..4d56d336fc --- /dev/null +++ b/serverless/event_workflows/serverless-subs.adoc @@ -0,0 +1,32 @@ +include::modules/serverless-document-attributes.adoc[] +[id="serverless-subs"] += Using subscriptions +include::modules/common-attributes.adoc[] +:context: serverless-subs + +toc::[] + +After events have been sent to a channel from an event source or producer, these events can be sent to multiple Knative services, or other sinks, by using a subscription. + +image::serverless-event-channel-workflow.png[Channel workflow overview] + +If a subscriber rejects an event, there are no re-delivery attempts by default. Developers can configure xref:../../serverless/event_workflows/serverless-event-delivery.adoc#serverless-event-delivery[re-delivery attempts] by modifying the `delivery` spec in a `Subscription` object. + +[id="serverless-subs-creating-subs"] +== Creating subscriptions + +Developers can create subscriptions that allow event sinks to subscribe to channels and receive events. + +include::modules/serverless-creating-subscriptions-odc.adoc[leveloffset=+2] +include::modules/serverless-creating-subscriptions-kn.adoc[leveloffset=+2] +include::modules/serverless-creating-subscriptions-yaml.adoc[leveloffset=+2] +// config event delivery +include::modules/serverless-subscription-event-delivery-config.adoc[leveloffset=+1] +// describe subs +include::modules/serverless-describe-subs-kn.adoc[leveloffset=+1] +// list subs +include::modules/serverless-list-subs-kn.adoc[leveloffset=+1] +// update subs +include::modules/serverless-update-subscriptions-kn.adoc[leveloffset=+1] +// delete subs +include::modules/serverless-deleting-subscriptions-kn.adoc[leveloffset=+1] diff --git a/serverless/event_workflows/serverless-using-brokers.adoc b/serverless/event_workflows/serverless-using-brokers.adoc index 34adbaf76c..6a793e45a7 100644 --- a/serverless/event_workflows/serverless-using-brokers.adoc +++ b/serverless/event_workflows/serverless-using-brokers.adoc @@ -1,5 +1,5 @@ [id="serverless-using-brokers"] -= Event delivery workflows using brokers and triggers += Broker and trigger workflows include::modules/common-attributes.adoc[] include::modules/serverless-document-attributes.adoc[] :context: serverless-using-brokers