[SRVKE-1277]: Updating docs to add trigger event delivery spec

Author: abrennan89

modules/serverless-configuring-event-delivery-examples.adoc

@@ -0,0 +1,94 @@
+// Module included in the following assemblies:
+//
+// * /serverless/develop/serverless-event-delivery.adoc
+
+:_content-type: REFERENCE
+[id="serverless-configuring-event-delivery-examples_{context}"]
+= Examples of configuring event delivery parameters
+
+You can configure event delivery parameters for `Broker`, `Trigger`, `Channel`, and `Subscription` objects. If you configure event delivery parameters for a broker or channel, these parameters are propagated to triggers or subscriptions created for those objects. You can also set event delivery parameters for triggers or subscriptions to override the settings for the broker or channel.
+
+.Example `Broker` object
+[source,yaml]
+----
+apiVersion: eventing.knative.dev/v1
+kind: Broker
+metadata:
+...
+spec:
+  delivery:
+    deadLetterSink:
+      ref:
+        apiVersion: eventing.knative.dev/v1alpha1
+        kind: KafkaSink
+        name: <sink_name>
+    backoffDelay: <duration>
+    backoffPolicy: <policy_type>
+    retry: <integer>
+...
+----
+
+.Example `Trigger` object
+[source,yaml]
+----
+apiVersion: eventing.knative.dev/v1
+kind: Trigger
+metadata:
+...
+spec:
+  broker: <broker_name>
+  delivery:
+    deadLetterSink:
+      ref:
+        apiVersion: serving.knative.dev/v1
+        kind: Service
+        name: <sink_name>
+    backoffDelay: <duration>
+    backoffPolicy: <policy_type>
+    retry: <integer>
+...
+----
+
+.Example `Channel` object
+[source,yaml]
+----
+apiVersion: messaging.knative.dev/v1
+kind: Channel
+metadata:
+...
+spec:
+  delivery:
+    deadLetterSink:
+      ref:
+        apiVersion: serving.knative.dev/v1
+        kind: Service
+        name: <sink_name>
+    backoffDelay: <duration>
+    backoffPolicy: <policy_type>
+    retry: <integer>
+...
+----
+
+.Example `Subscription` object
+[source,yaml]
+----
+apiVersion: messaging.knative.dev/v1
+kind: Subscription
+metadata:
+...
+spec:
+  channel:
+    apiVersion: messaging.knative.dev/v1
+    kind: Channel
+    name: <channel_name>
+  delivery:
+    deadLetterSink:
+      ref:
+        apiVersion: serving.knative.dev/v1
+        kind: Service
+        name: <sink_name>
+    backoffDelay: <duration>
+    backoffPolicy: <policy_type>
+    retry: <integer>
+...
+----

modules/serverless-event-delivery-component-behaviors.adoc

@@ -4,20 +4,13 @@
 
 :_content-type: CONCEPT
 [id="serverless-event-delivery-component-behaviors_{context}"]
-= Event delivery behavior for Knative Eventing channels
+= Event delivery behavior patterns for channels and brokers
 
-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.
+Different channel and broker types have their own behavior patterns that are followed for event delivery.
 
-[id="serverless-event-delivery-component-behaviors-kafka-channels_{context}"]
-== Event delivery behavior for Knative Kafka channels
+[id="serverless-event-delivery-component-behaviors-kafka_{context}"]
+== Knative Kafka channels and brokers
 
-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.
+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.
 
-[id="serverless-event-delivery-component-behaviors-status-codes_{context}"]
-== 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.
+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 the issue.

modules/serverless-event-delivery-parameters.adoc

@@ -6,14 +6,12 @@
 [id="serverless-event-delivery-parameters_{context}"]
 = Configurable event delivery parameters
 
-Knative Eventing provides configuration parameters that can be used to control what happens to events in cases where events fail to be delivered. For example, you can configure Knative to retry sending events that failed to be consumed, or forward these events to a dead letter sink.
-
 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.
+Dead letter sink:: You can configure the `deadLetterSink` delivery parameter so that if an event fails to be delivered, it is stored in the specified event sink. Undelivered events that are not stored in a dead letter sink are dropped. The dead letter sink be any addressable object that conforms to the Knative Eventing sink contract, such as a Knative service, a Kubernetes service, or a URI.
 
 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 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. For example, `PT1S` specifies a 1 second delay.
 
-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^<numberOfRetries>`.
+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 equal to `backoffDelay * <numberOfRetries>`. When using the `exponential` backoff policy, the back off delay is equal to `backoffDelay*2^<numberOfRetries>`.

modules/serverless-subscription-event-delivery-config.adoc

@@ -17,3 +17,4 @@ include::modules/serverless-create-kafka-channel-yaml.adoc[leveloffset=+1]
 == Next steps
 
 * After you have created a channel, xref:../../serverless/develop/serverless-subs.adoc#serverless-subs[create a subscription] that allows event sinks to subscribe to channels and receive events.
+* Configure event delivery parameters that are applied in cases where an event fails to be delivered to an event sink. See xref:../../serverless/develop/serverless-event-delivery.adoc#serverless-configuring-event-delivery-examples_serverless-event-delivery[Examples of configuring event delivery parameters].

serverless/develop/serverless-creating-channels.adoc

@@ -6,9 +6,13 @@ include::_attributes/common-attributes.adoc[]
 
 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/develop/serverless-subs.adoc#serverless-subs[subscription] or xref:../../serverless/develop/serverless-triggers.adoc#serverless-triggers[trigger] to a subscriber. Event delivery parameters are configured individually per subscriber.
+You can configure event delivery parameters that are applied in cases where an event fails to be delivered to an event sink. Configuring event delivery parameters, including a dead letter sink, ensures that any events that fail to be delivered to an event sink are retried. Otherwise, undelivered events are dropped.
 
+// event delivery behavior of different component types, e.g. kafka
 include::modules/serverless-event-delivery-component-behaviors.adoc[leveloffset=+1]
+
+// event delivery configurable parameters
 include::modules/serverless-event-delivery-parameters.adoc[leveloffset=+1]
-include::modules/serverless-subscription-event-delivery-config.adoc[leveloffset=+1]
-// add docs for configuration in triggers
+
+// configuring parameters examples
+include::modules/serverless-configuring-event-delivery-examples.adoc[leveloffset=+1]

serverless/develop/serverless-event-delivery.adoc

@@ -6,7 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-After you have created a channel and an event sink, you can create a subscription to enable event delivery. Subscriptions are created by configuring a `Subscription` object, which specifies the channel and the sink (also known as a _subscriber_) to deliver events to. You can also specify some sink-specific options, such as how to handle failures.
+After you have created a channel and an event sink, you can create a subscription to enable event delivery. Subscriptions are created by configuring a `Subscription` object, which specifies the channel and the sink (also known as a _subscriber_) to deliver events to.
 
 include::modules/serverless-creating-subscriptions-odc.adoc[leveloffset=+1]
 include::modules/serverless-creating-subscriptions-yaml.adoc[leveloffset=+1]
@@ -17,5 +17,7 @@ include::modules/serverless-describe-subs-kn.adoc[leveloffset=+1]
 include::modules/serverless-list-subs-kn.adoc[leveloffset=+1]
 // update subs
 include::modules/serverless-update-subscriptions-kn.adoc[leveloffset=+1]
-// config event delivery
-include::modules/serverless-subscription-event-delivery-config.adoc[leveloffset=+1]
+
+[id="next-steps_serverless-subs"]
+== Next steps
+* Configure event delivery parameters that are applied in cases where an event fails to be delivered to an event sink. See xref:../../serverless/develop/serverless-event-delivery.adoc#serverless-configuring-event-delivery-examples_serverless-event-delivery[Examples of configuring event delivery parameters].

serverless/develop/serverless-subs.adoc

@@ -17,3 +17,7 @@ include::modules/kn-trigger-describe.adoc[leveloffset=+1]
 include::modules/kn-trigger-filtering.adoc[leveloffset=+1]
 include::modules/kn-trigger-update.adoc[leveloffset=+1]
 include::modules/delete-kn-trigger.adoc[leveloffset=+1]
+
+[id="next-steps_serverless-triggers"]
+== Next steps
+* Configure event delivery parameters that are applied in cases where an event fails to be delivered to an event sink. See xref:../../serverless/develop/serverless-event-delivery.adoc#serverless-configuring-event-delivery-examples_serverless-event-delivery[Examples of configuring event delivery parameters].

serverless/develop/serverless-triggers.adoc

@@ -40,6 +40,10 @@ The Knative (`kn`) CLI provides commands that can be used to list, describe, upd
 include::modules/serverless-list-broker-kn.adoc[leveloffset=+2]
 include::modules/serverless-describe-broker-kn.adoc[leveloffset=+2]
 
+[id="next-steps_serverless-using-brokers"]
+== Next steps
+* Configure event delivery parameters that are applied in cases where an event fails to be delivered to an event sink. See xref:../../serverless/develop/serverless-event-delivery.adoc#serverless-configuring-event-delivery-examples_serverless-event-delivery[Examples of configuring event delivery parameters].
+
 [id="additional-resources_serverless-using-brokers"]
 [role="_additional-resources"]
 == Additional resources

serverless/develop/serverless-using-brokers.adoc

@@ -50,5 +50,5 @@ For more information about Kafka channels, see the xref:../../serverless/develop
 [id="next-steps_serverless-channels"]
 == Next steps
 
-* xref:../../serverless/develop/serverless-creating-channels.adoc#serverless-creating-channels[Create a channel] and a xref:../../serverless/develop/serverless-subs.adoc#serverless-subs[subscription] that allows event sinks to subscribe to channels and receive events.
+* xref:../../serverless/develop/serverless-creating-channels.adoc#serverless-creating-channels[Create a channel].
 * If you are a cluster administrator, you can configure default settings for channels. See xref:../../serverless/admin_guide/serverless-configuration.adoc#serverless-channel-default_serverless-configuration[Configuring channel defaults].