Documenting use of channels with Serverless

_topic_map.yml

@@ -1593,13 +1593,13 @@ Name: Serverless applications
 Dir: serverless
 Distros: openshift-enterprise,openshift-webscale
 Topics:
-### Release notes
+# Release notes
 - Name: Release Notes
   File: serverless-release-notes
-### Intro / getting started
+# Intro / getting started
 - Name: Getting started with OpenShift Serverless
   File: serverless-getting-started
-### Installing OpenShift Serverless
+# Installing OpenShift Serverless
 - Name: Installing OpenShift Serverless
   Dir: installing_serverless
   Topics:
@@ -1609,19 +1609,19 @@ Topics:
     File: upgrading-serverless
   - Name: Installing Knative Serving
     File: installing-knative-serving
-###  - Name: Installing Knative Eventing
-###    File: installing-knative-eventing
+#  - Name: Installing Knative Eventing
+#    File: installing-knative-eventing
   - Name: Installing the Knative CLI
     File: installing-kn
   - Name: Removing OpenShift Serverless
     File: removing-openshift-serverless
-### Knative CLI
+# Knative CLI
 - Name: Knative CLI
   Dir: knative_cli
   Topics:
   - Name: Getting started with Knative CLI
     File: knative-cli
-### Knative Serving
+# Knative Serving
 - Name: Knative Serving
   Dir: knative_serving
   Topics:
@@ -1639,34 +1639,37 @@ Topics:
     File: cluster-logging-serverless
   - Name: Splitting traffic between revisions
     File: splitting-traffic-between-revisions
-### Knative Eventing
-### - Name: Knative Eventing
-###  Dir: knative_eventing
-###  Topics:
-###  - Name: How Knative Eventing works
-###    File: serverless-knative-eventing
-### Event sources
-###  - Name: Using the kn CLI to list event sources and event source types
-###    File: serverless-kn-source
-###  - Name: Using ApiServerSource
-###    File: serverless-apiserversource
-###  - Name: Using PingSource
-###    File: serverless-pingsource
-###  - Name: Using SinkBinding
-###    File: serverless-sinkbinding
-### Triggers
-###  - Name: Using triggers with Knative Eventing
-###    File: serverless-kn-trigger
-### Brokers
-###  - Name: Using the broker
-###    File: serverless-using-brokers
-### HA
-### - Name: Configuring high availability components
-###  File: serverless-config-HA
-### Monitoring
+# Knative Eventing
+# - Name: Knative Eventing
+#  Dir: knative_eventing
+#  Topics:
+#  - Name: How Knative Eventing works
+#    File: serverless-knative-eventing
+# Event sources
+#  - Name: Using the kn CLI to list event sources and event source types
+#    File: serverless-kn-source
+#  - Name: Using ApiServerSource
+#    File: serverless-apiserversource
+#  - Name: Using PingSource
+#    File: serverless-pingsource
+#  - Name: Using SinkBinding
+#    File: serverless-sinkbinding
+# Triggers
+#  - Name: Using triggers
+#    File: serverless-kn-trigger
+# Brokers
+#  - Name: Using the broker
+#    File: serverless-using-brokers
+# Channels
+#  - Name: Using channels
+#    File: serverless-channels
+# HA
+# - Name: Configuring high-availability components
+#  File: serverless-config-HA
+# Monitoring
 - Name: Monitoring OpenShift Serverless components
   File: monitoring-serverless
-### Metering
+# Metering
 - Name: Using metering with OpenShift Serverless
   File: serverless-metering
 #---

modules/serverless-create-default-channel.adoc

@@ -0,0 +1,42 @@
+// Module is included in the following assemblies:
+//
+// serverless/knative_eventing/serverless-channels.adoc
+
+[id="serverless-create-default-channel_{context}"]
+= Creating a channel with cluster default configuration
+
+To create a channel using the cluster default configuration set by the cluster administrator, you must create a generic `Channel` custom object.
+
+.Example `Channel` object
+[source,yaml]
+----
+apiVersion: messaging.knative.dev/v1beta1
+kind: Channel
+metadata:
+  name: example-channel
+  namespace: default
+----
+
+When the above `Channel` object is created, a mutating admission webhook adds a set of `spec.channelTemplate` properties for the `Channel` object based on the default channel implementation chosen by the cluster administrator.
+
+.Example `Channel` object with `spec.channelTemplate` properties
+[source,yaml]
+----
+apiVersion: messaging.knative.dev/v1beta1
+kind: Channel
+metadata:
+  name: example-channel
+  namespace: default
+spec:
+  channelTemplate:
+    apiVersion: messaging.knative.dev/v1beta1
+    kind: InMemoryChannel
+----
+
+The channel controller will then create the backing channel instance based on that `spec.channelTemplate` configuration. The `spec.channelTemplate` properties cannot be changed after creation, because they are set by the default channel mechanism rather than by the user.
+
+When this mechanism is used, two objects are created, a generic channel, and an InMemoryChannel channel.
+
+The generic channel acts as a proxy that copies its subscriptions to the InMemoryChannel, and sets its status to reflect the status of the backing InMemoryChannel channel.
+
+Because the channel in this example is created in the default namespace, the channel uses the cluster default, which is InMemoryChannel.

modules/serverless-eventing-components.adoc

@@ -1,64 +0,0 @@
-// Module included in the following assemblies:
-//
-// * serverless-knative-eventing.adoc
-
-[id="serverless-eventing-components_{context}"]
-= Knative Eventing components
-
-Event source:: Event sources are Kubernetes custom resources that provide a mechanism for registering interest in a class of events from an event producer.
-
-// Add 'Channel' / 'Sinks / consumers'
-
-Broker:: A broker represents an event mesh. Events are sent to the broker's ingress and are then sent to any event consumers that are subscribed to that broker.
-After the event is in the broker, metadata for the event is stripped away so that there is no information about how the event entered the broker.
-+
-.Example broker YAML definition
-----
-apiVersion: eventing.knative.dev/v1alpha1
-kind: Broker
-metadata:
-  name: default <1>
-spec:
-  channelTemplateSpec: <2>
-    apiVersion: messaging.knative.dev/v1alpha1
-    kind: InMemoryChannel
-----
-
-<1> The `default` broker is provided with your {ServerlessProductName} Knative Eventing installation.
-<2> Event channels can be specified in the `channelTemplateSpec`.
-
-// NOTE: this is being replaced. Update when details are available upstream.
-
-
-Trigger:: A trigger enables a Knative service to subscribe to events from a specific broker.
-+
-.Example trigger YAML definition
-----
-apiVersion: eventing.knative.dev/v1alpha1
-kind: Trigger
-metadata:
-  name: my-service-trigger <1>
-spec:
-  broker: default <2>
-  subscriber: <3>
-    ref:
-      apiVersion: serving.knative.dev/v1
-      kind: Service
-      name: my-service
-----
-
-<1> The name of the trigger.
-<2> Specifies the name of the broker that the trigger will listen for events from.
-<3> The `subscriber` section defines the Knative service that the broker sends events to.
-
-// == Next steps
-
-// * Install Knative Eventing
-// * Using event sources
-// * Using brokers
-// * Using channels
-// * Using triggers
-// add links: * For more details on writing assemblies, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
-// * Install the Kafka event source
-// * Install the Camel K event source
-// * Integrate your AMQ Streams deployment with Knative Eventing using {ServerlessProductName}.

serverless/knative_eventing/serverless-channels.adoc

@@ -0,0 +1,26 @@
+include::modules/serverless-document-attributes.adoc[]
+[id="serverless-channels"]
+= Using channels
+include::modules/common-attributes.adoc[]
+:context: serverless-channels
+
+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.
+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.
+
+== Supported channel types
+Currently, {ServerlessProductName} only supports the use of InMemoryChannel channels as part of the Knative Eventing Technology Preview.
+
+The following are limitations of InMemoryChannel channels:
+
+* No event persistence is available. If a Pod is goes down, events on that Pod will be lost.
+* InMemoryChannel channels do not implement event ordering, so two events that are received in the channel at the same time may be delivered to a subscriber in any order.
+* If a subscriber rejects an event, there are no redelivery attempts. Instead, the rejected event will be sent to a _dead letter sink_ if this exists, or is otherwise dropped.
+
+// TODO: Add link for dead letter sink docs once these are added.
+
+include::modules/serverless-create-default-channel.adoc[leveloffset=+1]

serverless/knative_eventing/serverless-kn-source.adoc

@@ -10,9 +10,8 @@ You can use the `kn` CLI to list and manage available event sources or event sou
 
 Currently, `kn` supports management of the following event source types:
 
-`ApiServerSource`:: Connects a sink to the Kubernetes API server.
-`PingSource`:: Periodically sends ping events with a constant payload. It can be used as a timer.
-`SinkBinding`:: Connects core Kubernetes resources like `Deployment`, `Job`, or `StatefulSet` with a sink.
+ApiServerSource:: Connects a sink to the Kubernetes API server.
+PingSource:: Periodically sends ping events with a constant payload. It can be used as a timer.
 
 // Additional sources can be added by the cluster administrator. For example, {ServerlessProductName} can be used with Kafka and Camel K event sources, which are installed using the Operator Hub in the {product-title} web console.
 // For more information about adding event source types as a cluster administrator, see
@@ -24,4 +23,3 @@ include::modules/serverless-list-source.adoc[leveloffset=+1]
 .Next steps
 * See the documentation on xref:../knative_eventing/serverless-apiserversource.adoc#serverless-apiserversource[Using ApiServerSource].
 * See the documentation on xref:../knative_eventing/serverless-pingsource.adoc#serverless-pingsource[Using PingSource].
-* See the documentation on xref:../knative_eventing/serverless-sinkbinding.adoc#serverless-sinkbinding[Using SinkBinding].

serverless/knative_eventing/serverless-kn-trigger.adoc

@@ -1,10 +1,9 @@
 include::modules/serverless-document-attributes.adoc[]
 [id="serverless-kn-trigger"]
-= Using triggers with Knative Eventing
+= Using triggers
 :context: serverless-kn-trigger
 include::modules/common-attributes.adoc[]
 
-
 toc::[]
 
 All events which are sent to a channel or broker will be sent to all subscribers of that channel or broker by default.

serverless/knative_eventing/serverless-knative-eventing.adoc

@@ -12,12 +12,24 @@ Event-driven architecture is based on the concept of decoupled relationships bet
 
 For more information about event-driven architecture, see link:https://www.redhat.com/en/topics/integration/what-is-event-driven-architecture[What is event-driven architecture?]
 
-In a Knative Eventing workflow, event producers send information to an event source about changes to system state.
-Examples of event producers include a Kafka cluster or the Kubernetes API server.
-An event source is a resource object, which is the link between an event producer and a sink (or consumer) that receives those events.
-Examples of sinks are Knative services and channels.
-Events can also be sent to a broker, where they can be filtered using triggers before being sent to an event sink.
+== Knative Eventing workflows
 
-Using the broker and trigger together enables an event delivery mechanism that hides the details of event routing from the event producer and event consumer.
+In a Knative Eventing workflow, _event producers_ send information to an event source about changes to system state. Examples of event producers include a Kafka cluster or the Kubernetes API server.
 
-include::modules/serverless-eventing-components.adoc[leveloffset=+1]
+An _event source_ is a resource object, which is the link between an event producer and a _sink_ (or consumer) that receives those events. Currently, {ServerlessProductName} supports the following event source types:
+
+ApiServerSource:: Connects a sink to the Kubernetes API server.
+PingSource:: Periodically sends ping events with a constant payload. It can be used as a timer.
+
+SinkBinding is also supported, which allows you to connect core Kubernetes resources such as `Deployment`, `Job`, or `StatefulSet` with a sink.
+
+Examples of sinks are Knative services and channels. Events can also be sent to:
+
+* A _broker_, where they can be filtered using _triggers_ before being sent to a sink. Using the broker and trigger together enables an event delivery mechanism that hides the details of event routing from the event producer and event consumer.
+* A _channel_, where Knative services can "subscribe" to receive events of a certain type.
+
+== Additional resources
+
+* For more information about brokers, see xref:../serverless-using-brokers.adoc#serverless-using-brokers[Using brokers].
+* For more information about triggers, see xref:../serverless-kn-trigger.adoc#serverless-kn-trigger[Using triggers].
+* For more information about channels, see xref:../serverless-channels.adoc#serverless-channels[Using channels].

serverless/serverless-config-HA.adoc

@@ -1,6 +1,6 @@
 include::modules/serverless-document-attributes.adoc[]
 [id="serverless-config-HA"]
-= Configuring high availability {ServerlessProductName} components
+= Configuring high-availability {ServerlessProductName} components
 include::modules/common-attributes.adoc[]
 :context: serverless-config-HA