Merge pull request #22407 from abrennan89/subs

Create subscription docs + deadlettersink for Serverless

Author: codyhoag

_topic_map.yml

@@ -2371,6 +2371,9 @@ Topics:
 # Channels
   - Name: Using channels
     File: serverless-channels
+# Subscriptions
+  - Name: Using subscriptions to send events from a channel to a sink
+    File: serverless-subscriptions
 # Triggers
   - Name: Using triggers
     File: serverless-kn-trigger

modules/serverless-creating-subscriptions.adoc

@@ -0,0 +1,60 @@
+// Module included in the following assemblies:
+//
+// <List assemblies here, each on a new line>
+// * serverless/knative_eventing/serverless-subscriptions.adoc
+
+[id="serverless-creating-subscriptions_{context}"]
+= Creating a subscription
+
+You can create a subscription to connect a service or other event sink to a channel.
+
+[IMPORTANT]
+====
+Knative Eventing is a Technology Preview feature. The InMemoryChannel type is provided for development use only, and should not be used in a production environment.
+====
+
+.Prerequisites
+
+* You must have a current installation of xref:../../serverless/installing_serverless/installing-openshift-serverless.adoc#serverless-install-web-console_installing-openshift-serverless[{ServerlessProductName}], including Knative Serving and Eventing, in your {product-title} cluster. This can be installed by a cluster administrator.
+* If you do not have an existing sink that you wish to use, create a Service to use as a sink by following the documentation on xref:../../serverless/serving-creating-managing-apps.adoc#serving-creating-managing-apps[Creating and managing serverless applications].
+* You must have a channel to connect your subscription to. See xref:../../serverless/knative_eventing/serverless-channels.adoc#serverless-channels[Using channels with Knative Eventing].
+
+.Procedure
+
+. Create a Subscription object to connect a channel to a service, by creating a YAML file containing the following:
++
+[source,yml]
+----
+apiVersion: messaging.knative.dev/v1beta1
+kind: Subscription
+metadata:
+  name: my-subscription <1>
+  namespace: default
+spec:
+  channel: <2>
+    apiVersion: messaging.knative.dev/v1beta1
+    kind: Channel
+    name: example-channel
+  delivery: <3>
+    deadLetterSink:
+      ref:
+        apiVersion: serving.knative.dev/v1
+        kind: Service
+        name: error-handler
+  subscriber: <4>
+    ref:
+      apiVersion: serving.knative.dev/v1
+      kind: Service
+      name: event-display
+----
++
+<1> Name of the subscription.
+<2> Configuration settings for the channel that the subscription connects to.
+<3> Configuration settings for event delivery. This tells the subscription what happens to events that cannot be delivered to the subscriber. When this is configured, events that failed to be consumed are sent to the `deadLetterSink`. The event is dropped, no re-delivery of the event is attempted, and an error is logged in the system. The `deadLetterSink` value must be a link:https://pkg.go.dev/knative.dev/pkg/apis/duck/v1?tab=doc#Destination[Destination].
+<4> Configuration settings for the subscriber. This is the event sink that events are delivered to from the channel.
+
+. Apply the YAML file by entering:
++
+----
+$ oc apply -f <FILENAME>
+----

modules/serverless-inmemorychannel.adoc

@@ -11,8 +11,8 @@ The following are limitations of InMemoryChannel type channels:
 
 * No event persistence is available. If a Pod goes down, events on that Pod are lost.
 * InMemoryChannel type channels do not implement event ordering, so two events that are received in the channel at the same time can be delivered to a subscriber in any order.
-* If a subscriber rejects an event, there are no re-delivery attempts. Instead, the rejected event is sent to a `deadLetterSink` if this sink exists, or is otherwise dropped.
-// add link to subscription docs after rebase on top of this
+* If a subscriber rejects an event, there are no re-delivery attempts. Instead, the rejected event is sent to a `deadLetterSink` if this sink exists, or is otherwise dropped. For more information about configuring event delivery and `deadLetterSink` settings for a channel, see xref:../../serverless/knative_eventing/serverless-subscriptions.adoc#serverless-subscriptions[Using subscriptions to send events from a channel to a sink].
+
 When you install Knative Eventing, the following custom resource definition (CRD) is created automatically:
 
 [source,yaml]

serverless/knative_eventing/serverless-channels.adoc

@@ -7,7 +7,7 @@ include::modules/common-attributes.adoc[]
 toc::[]
 
 It is possible to sink events from an event source to a Knative Eventing channel.
-Channels are Custom Resources (CRs) that define a single event-forwarding and persistence layer.
+Channels are custom resources (CRs) that define a single event-forwarding and persistence layer.
 After events have been sent to a channel, these events can be sent to multiple Knative services by using a subscription.
 
 The default configuration for channel instances is defined in the `default-ch-webhook` ConfigMap. However, developers can still create their own channels directly by instantiating a supported channel object.
@@ -17,4 +17,3 @@ The default configuration for channel instances is defined in the `default-ch-we
 Currently, {ServerlessProductName} only supports the use of InMemoryChannel type channels as part of the Knative Eventing Technology Preview.
 
 include::modules/serverless-inmemorychannel.adoc[leveloffset=+1]
-// TODO: Add docs for Kafka channels; separate Jira issue

serverless/knative_eventing/serverless-subscriptions.adoc

@@ -0,0 +1,11 @@
+include::modules/serverless-document-attributes.adoc[]
+[id="serverless-subscriptions"]
+= Using subscriptions to send events from a channel to a sink
+:context: serverless-subscriptions
+include::modules/common-attributes.adoc[]
+
+toc::[]
+
+Subscriptions deliver events to event sinks from a Channel.
+
+include::modules/serverless-creating-subscriptions.adoc[leveloffset=+1]