Merge pull request #32453 from abrennan89/RHDEVDOCS-2749

bmcelvee · web-flow · commit 16b425c1200b · 2021-05-18T10:50:58.000-04:00
[srvls][RHDEVDOCS-2749] Updating sink, channels, sources documentation
diff --git a/_topic_map.yml b/_topic_map.yml
@@ -2912,15 +2912,9 @@ Topics:
 # Brokers
   - Name: Brokers
     File: serverless-using-brokers
-# Subscriptions
-  - Name: Subscriptions
-    File: serverless-subs
 # Triggers
   - Name: Triggers
     File: serverless-triggers
-# Channels
-  - Name: Channels
-    File: serverless-channels
 # Event delivery
   - Name: Event delivery
     File: serverless-event-delivery
@@ -2943,6 +2937,22 @@ Topics:
     File: serverless-sinkbinding
   - Name: Using a Kafka source
     File: serverless-kafka-source
+  - Name: Connecting event sources to sinks
+    File: srvls-connecting-source-sinks
+# Channels
+- Name: Channels
+  Dir: channels
+  Topics:
+  - Name: Understanding channels
+    File: serverless-channels
+  - Name: Creating and deleting channels
+    File: serverless-creating-channels
+  - Name: Subscriptions
+    File: serverless-subs
+  - Name: Connecting a channel to an event source
+    File: connect-channels-event-source
+  - Name: Configuring channel defaults
+    File: serverless-configuring-channels
 # Functions - uncomment at tech preview
 #- Name: Functions
 #  Dir: functions
@@ -2991,5 +3001,7 @@ Topics:
   Topics:
   - Name: Advanced kn configuration
     File: advanced-kn-config
+  - Name: kn flags reference
+    File: kn-flags-reference
   - Name: kn service
     File: kn-services-ref
diff --git a/modules/apiserversource-kn.adoc b/modules/apiserversource-kn.adoc
@@ -13,7 +13,7 @@ This section describes the steps required to create an API server source using `
 
 .Procedure
 
-. Create an API server source that uses a broker as an event sink:
+. Create an API server source that uses a broker as a sink:
 +
 [source,terminal]
 ----
@@ -34,7 +34,7 @@ $ kn service create <service_name> --image quay.io/openshift-knative/knative-eve
 $ kn trigger create <trigger_name> --sink ksvc:<service_name>
 ----
 
-. Create events by launching a Pod in the default namespace:
+. Create events by launching a pod in the default namespace:
 +
 [source,terminal]
 ----
diff --git a/modules/serverless-channel-default.adoc b/modules/serverless-channel-default.adoc
@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-//  * serverless/event_workflows/serverless-channels.adoc
+//  * serverless/channels/serverless-channels.adoc
 
 [id="serverless-channel-default_{context}"]
 = Configuring the default channel implementation
diff --git a/modules/serverless-connect-channel-source-odc.adoc b/modules/serverless-connect-channel-source-odc.adoc
@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-//  * serverless/event_workflows/serverless-channels.adoc
+//  * serverless/channels/serverless-channels.adoc
 
 [id="serverless-connect-channel-source-odc_{context}"]
 = Connect an event source to a channel using the Developer perspective
diff --git a/modules/serverless-create-channel-kn.adoc b/modules/serverless-create-channel-kn.adoc
@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-//  * serverless/event_workflows/serverless-channels.adoc
+//  * serverless/event_workflows/serverless-creating-channels.adoc
 
 [id="serverless-create-channel-kn_{context}"]
 = Creating a channel using the Knative CLI
diff --git a/modules/serverless-create-channel-odc.adoc b/modules/serverless-create-channel-odc.adoc
@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-//  * serverless/event_workflows/serverless-channels.adoc
+//  * serverless/event_workflows/serverless-creating-channels.adoc
 
 [id="serverless-create-channel-odc_{context}"]
 = Creating a channel using the Developer perspective
diff --git a/modules/serverless-create-default-channel-yaml.adoc b/modules/serverless-create-default-channel-yaml.adoc
@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-//  * serverless/event_workflows/serverless-channels.adoc
+//  * serverless/channels/serverless-creating-channels.adoc
 
 [id="serverless-create-default-channel-yaml_{context}"]
 = Creating a default implementation channel by using YAML
diff --git a/modules/serverless-create-kafka-channel-yaml.adoc b/modules/serverless-create-kafka-channel-yaml.adoc
@@ -1,7 +1,7 @@
 // Module included in the following assemblies:
 //
-//  * serverless/event_workflows/serverless-channels.adoc
-//  * serverless/serverless-kafka.adoc
+//  * serverless/event_workflows/serverless-creating-channels.adoc
+//  * serverless/event_workflows/serverless-kafka.adoc
 
 [id="serverless-create-kafka-channel-yaml_{context}"]
 = Creating a Kafka channel by using YAML
diff --git 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-subs.adoc
+//  * serverless/channels/serverless-subs.adoc
 
 [id="serverless-creating-subscriptions-kn_{context}"]
 = Creating subscriptions using the Knative CLI
diff --git a/modules/serverless-creating-subscriptions-odc.adoc b/modules/serverless-creating-subscriptions-odc.adoc
@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * serverless/event_workflows/serverless-channels.adoc
+// * serverless/channel/serverless-subs.adoc
 
 [id="serverless-creating-subscriptions-odc_{context}"]
 = Creating subscriptions in the Developer perspective
diff --git a/modules/serverless-creating-subscriptions-yaml.adoc b/modules/serverless-creating-subscriptions-yaml.adoc
@@ -1,7 +1,6 @@
 // Module included in the following assemblies:
 //
-// <List assemblies here, each on a new line>
-// * serverless/event_workflows/serverless-channels.adoc
+//  * serverless/channels/serverless-subs.adoc
 
 [id="serverless-creating-subscriptions-yaml_{context}"]
 = Creating subscriptions by using YAML
diff --git a/modules/serverless-delete-channel-kn.adoc b/modules/serverless-delete-channel-kn.adoc
@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-//  * serverless/event_workflows/serverless-channels.adoc
+//  * serverless/channels/serverless-creating-channels.adoc
 
 [id="serverless-delete-channel-kn_{context}"]
 = Deleting a channel using the Knative CLI
diff --git a/modules/serverless-deleting-subscriptions-kn.adoc b/modules/serverless-deleting-subscriptions-kn.adoc
@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-//  * serverless/event_workflows/serverless-subs.adoc
+//  * serverless/channels/serverless-subs.adoc
 
 [id="serverless-deleting-subscriptions-kn_{context}"]
 = Deleting subscriptions using the Knative CLI
diff --git a/modules/serverless-describe-subs-kn.adoc b/modules/serverless-describe-subs-kn.adoc
@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-//  * serverless/event_workflows/serverless-subs.adoc
+//  * serverless/channels/serverless-subs.adoc
 
 [id="serverless-describe-subs-kn_{context}"]
 = Describing subscriptions using the Knative CLI
diff --git a/modules/serverless-install-kafka-odc.adoc b/modules/serverless-install-kafka-odc.adoc
@@ -1,6 +1,6 @@
 // Module is included in the following assemblies:
 //
-// serverless/serverless-kafka.adoc
+// serverless/event_workflows/serverless-kafka.adoc
 
 [id="serverless-install-kafka-odc_{context}"]
 = Installing Knative Kafka components by using the web console
diff --git a/modules/serverless-kafka-sasl.adoc b/modules/serverless-kafka-sasl.adoc
@@ -1,6 +1,6 @@
 // Module is included in the following assemblies:
 //
-// serverless/serverless-kafka.adoc
+// serverless/event_workflows/serverless-kafka.adoc
 
 [id="serverless-configuring-sasl-authentication-against-an-apache-kafka_{context}"]
 = Configuring SASL authentication
@@ -87,4 +87,3 @@ spec:
 .Additional resources
 
 * link:https://access.redhat.com/documentation/en-us/red_hat_amq/7.5/html-single/using_amq_streams_on_rhel/index#assembly-kafka-encryption-and-authentication-str[TLS and SASL on Kafka]
-
diff --git a/modules/serverless-kafka-tls.adoc b/modules/serverless-kafka-tls.adoc
@@ -1,6 +1,6 @@
 // Module is included in the following assemblies:
 //
-// serverless/serverless-kafka.adoc
+// serverless/event_workflows/serverless-kafka.adoc
 
 [id="serverless-configuring-tls-authentication-against-an-apache-kafka_{context}"]
 = Configuring TLS authentication
@@ -79,4 +79,3 @@ spec:
 .Additional resources
 
 * link:https://access.redhat.com/documentation/en-us/red_hat_amq/7.5/html-single/using_amq_streams_on_rhel/index#assembly-kafka-encryption-and-authentication-str[TLS and SASL on Kafka]
-
diff --git a/modules/serverless-list-subs-kn.adoc b/modules/serverless-list-subs-kn.adoc
@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-//  * serverless/event_workflows/serverless-subs.adoc
+//  * serverless/channels/serverless-subs.adoc
 
 [id="serverless-list-subs-kn_{context}"]
 = Listing subscriptions using the Knative CLI
diff --git a/modules/serverless-update-subscriptions-kn.adoc b/modules/serverless-update-subscriptions-kn.adoc
@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-//  * serverless/event_workflows/serverless-subs.adoc
+//  * serverless/channels/serverless-subs.adoc
 
 [id="serverless-update-subscriptions-kn_{context}"]
 = Updating subscriptions
diff --git a/modules/specifying-sink-flag-kn.adoc b/modules/specifying-sink-flag-kn.adoc
@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * serverless/event_sources/srvls-connecting-source-consumers
+// * serverless/cli_reference/
+// * serverless/event_sources/serverless-pingsource
+// * serverless/event_sources/serverless-apiserversource
+// * serverless/event_sources/serverless-kafka-source
+// * serverless/event_sources/serverless-sinkbinding
+
+[id="specifying-sink-flag-kn_{context}"]
+= Knative CLI (kn) --sink flag
+
+When you create an event-producing custom resource by using the Knative (`kn`) CLI, you can specify a sink where events are sent to from that resource, by using the `--sink` flag.
+
+The following example creates a sink binding that uses a service, `http://event-display.svc.cluster.local`, as the sink:
+
+.Example command using the `--sink` flag
+[source,terminal]
+----
+$ kn source binding create bind-heartbeat \
+  --namespace sinkbinding-example \
+  --subject "Job:batch/v1:app=heartbeat-cron" \
+  --sink http://event-display.svc.cluster.local \ <1>
+  --ce-override "sink=bound"
+----
+
+<1> `svc` in `http://event-display.svc.cluster.local` determines that the sink is a Knative service. Other default sink prefixes include `channel`, and `broker`.
diff --git a/serverless/admin_guide/serverless-cluster-admin-eventing.adoc b/serverless/admin_guide/serverless-cluster-admin-eventing.adoc
@@ -22,11 +22,11 @@ include::modules/serverless-creating-channel-admin-web-console.adoc[leveloffset=
 // Subscription
 include::modules/serverless-creating-subscription-admin-web-console.adoc[leveloffset=+1]
 
-[id="serverless-cluster-admin-eventing-additional-resources"]
+[id="additional-resources_serverless-cluster-admin-eventing"]
 == Additional resources
 
 * See xref:../../serverless/event_workflows/serverless-using-brokers.adoc#serverless-using-brokers[Brokers].
-* See xref:../../serverless/event_workflows/serverless-subs.adoc#serverless-subs[Subscriptions].
+* See xref:../../serverless/channels/serverless-subs.adoc#serverless-subs[Subscriptions].
 * See xref:../../serverless/event_workflows/serverless-triggers.adoc#serverless-triggers[Triggers].
-* See xref:../../serverless/event_workflows/serverless-channels.adoc#serverless-channels[Channels].
+* See xref:../../serverless/channels/serverless-channels.adoc#serverless-channels[Channels].
 * See xref:../../serverless/event_workflows/serverless-kafka.adoc#serverless-kafka[Knative Kafka].
diff --git a/serverless/architecture/serverless-event-architecture.adoc b/serverless/architecture/serverless-event-architecture.adoc
@@ -14,8 +14,8 @@ These events conform to the link:https://cloudevents.io[CloudEvents specificatio
 
 You can propagate an event from an xref:../event_sources/knative-event-sources.adoc#knative-event-sources[event source] to multiple event sinks by using:
 
-* xref:../event_workflows/serverless-channels.adoc#serverless-channels[channels] and subscriptions, or
-* xref:../event_workflows/serverless-using-brokers.adoc#serverless-using-brokers[brokers] and triggers.
+* xref:../../serverless/channels/serverless-channels.adoc#serverless-channels[channels] and subscriptions, or
+* xref:../../serverless/event_workflows/serverless-using-brokers.adoc#serverless-using-brokers[brokers] and triggers.
 
 Events are buffered if the destination sink is unavailable.
 // For more information about creating an Event delivery system, see
diff --git a/serverless/channels/connect-channels-event-source.adoc b/serverless/channels/connect-channels-event-source.adoc
@@ -0,0 +1,12 @@
+include::modules/serverless-document-attributes.adoc[]
+[id="connect-channels-event-source"]
+= Connecting a channel to an event source
+include::modules/common-attributes.adoc[]
+:context: connect-channels-event-source
+
+toc::[]
+
+Connecting a channel to an event source allows the channel to receive events from that source. These events can then be forwarded to an event sink by using subscriptions.
+
+include::modules/serverless-connect-channel-source-odc.adoc[leveloffset=+1]
+// add kn, create module - modules/serverless-connect-channel-source-kn.adoc
diff --git a/serverless/channels/images b/serverless/channels/images
@@ -0,0 +1 @@
+../images
diff --git a/serverless/channels/modules b/serverless/channels/modules
@@ -0,0 +1 @@
+../modules
diff --git a/serverless/channels/serverless-channels.adoc b/serverless/channels/serverless-channels.adoc
@@ -0,0 +1,27 @@
+include::modules/serverless-document-attributes.adoc[]
+[id="serverless-channels"]
+= Understanding channels
+include::modules/common-attributes.adoc[]
+:context: serverless-channels
+
+toc::[]
+
+Channels are custom resources that define a single event-forwarding and persistence layer.
+
+image::serverless-event-channel-workflow.png[Channel workflow overview]
+
+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.
+
+`InMemoryChannel` and `KafkaChannel` channel implementations can be used with {ServerlessProductName} for development use.
+
+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` 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 by default. You can configure re-delivery attempts by modifying the `delivery` spec in the `Subscription` object.
+
+[id="next-steps_serverless-channels"]
+== Next steps
+
+* If you are a cluster administrator, you can configure default settings for channels. See xref:../../serverless/channels/serverless-configuring-channels.adoc#serverless-configuring-channels[Configuring channel defaults].
+* See xref:../../serverless/channels/serverless-creating-channels.adoc#serverless-creating-channels[Creating and deleting channels].
diff --git a/serverless/channels/serverless-configuring-channels.adoc b/serverless/channels/serverless-configuring-channels.adoc
@@ -0,0 +1,11 @@
+include::modules/serverless-document-attributes.adoc[]
+[id="serverless-configuring-channels"]
+= Configuring channel defaults
+include::modules/common-attributes.adoc[]
+:context: serverless-configuring-channels
+
+toc::[]
+
+If you have cluster administrator permissions, you can set default options for channels, either for the whole cluster or for a specific namespace. These options are modified using config maps.
+
+include::modules/serverless-channel-default.adoc[leveloffset=+1]
diff --git a/serverless/channels/serverless-creating-channels.adoc b/serverless/channels/serverless-creating-channels.adoc
@@ -1,9 +1,10 @@
-// Module included in the following assemblies:
-//
-//  * serverless/event_workflows/serverless-channels.adoc
+include::modules/serverless-document-attributes.adoc[]
+[id="serverless-creating-channels"]
+= Creating and deleting channels
+include::modules/common-attributes.adoc[]
+:context: serverless-creating-channels
 
-[id="serverless-channels-creating-intro_{context}"]
-= Creating channels
+toc::[]
 
 Developers can create channels by instantiating a supported `Channel` object.
 
@@ -33,3 +34,16 @@ The channel controller then creates the backing channel instance based on the `s
 When this mechanism is used with the preceding example, two objects are created: a generic backing channel and an `InMemoryChannel` channel. If you are using a different default channel implementation, the `InMemoryChannel` is replaced with one that is specific to your implementation. For example, with Knative Kafka, the `KafkaChannel` channel is created.
 
 The backing channel acts as a proxy that copies its subscriptions to the user-created channel object, and sets the user-created channel object status to reflect the status of the backing channel.
+
+include::modules/serverless-create-channel-odc.adoc[leveloffset=+1]
+include::modules/serverless-create-channel-kn.adoc[leveloffset=+1]
+include::modules/serverless-create-default-channel-yaml.adoc[leveloffset=+1]
+include::modules/serverless-create-kafka-channel-yaml.adoc[leveloffset=+1]
+// deleting channels
+include::modules/serverless-delete-channel-kn.adoc[leveloffset=+1]
+
+[id="next-steps_serverless-creating-channels"]
+== Next steps
+
+* See xref:../../serverless/channels/connect-channels-event-source.adoc#connect-channels-event-source[Connecting a channel to an event source].
+* After you have created a channel, see xref:../../serverless/channels/serverless-subs.adoc#serverless-subs[Using subscriptions] for information about creating and using subscriptions for event delivery.
diff --git a/serverless/channels/serverless-subs.adoc b/serverless/channels/serverless-subs.adoc
diff --git a/serverless/cli_reference/kn-flags-reference.adoc b/serverless/cli_reference/kn-flags-reference.adoc
@@ -0,0 +1,9 @@
+include::modules/serverless-document-attributes.adoc[]
+[id="kn-flags-reference"]
+= kn flags reference
+:context: kn-flags-reference
+include::modules/common-attributes.adoc[]
+
+toc::[]
+
+include::modules/specifying-sink-flag-kn.adoc[leveloffset=+1]
diff --git a/serverless/event_sources/knative-event-sources.adoc b/serverless/event_sources/knative-event-sources.adoc
@@ -26,4 +26,3 @@ You can create and manage Knative event sources using the **Developer** perspect
 == Additional resources
 
 * For more information about eventing workflows using {ServerlessProductName}, see xref:../../serverless/architecture/serverless-event-architecture.adoc#serverless-event-architecture[Knative Eventing architecture].
-* See xref:../../serverless/event_workflows/serverless-kafka.adoc#serverless-kafka[Knative Kafka].
diff --git a/serverless/event_sources/serverless-apiserversource.adoc b/serverless/event_sources/serverless-apiserversource.adoc
diff --git a/serverless/event_sources/serverless-kafka-source.adoc b/serverless/event_sources/serverless-kafka-source.adoc
diff --git a/serverless/event_sources/serverless-pingsource.adoc b/serverless/event_sources/serverless-pingsource.adoc
diff --git a/serverless/event_sources/serverless-sinkbinding.adoc b/serverless/event_sources/serverless-sinkbinding.adoc
diff --git a/serverless/event_sources/srvls-connecting-source-sinks.adoc b/serverless/event_sources/srvls-connecting-source-sinks.adoc
diff --git a/serverless/event_workflows/serverless-channels.adoc b/serverless/event_workflows/serverless-channels.adoc
diff --git a/serverless/event_workflows/serverless-event-delivery.adoc b/serverless/event_workflows/serverless-event-delivery.adoc
diff --git a/serverless/event_workflows/serverless-kafka.adoc b/serverless/event_workflows/serverless-kafka.adoc
diff --git a/serverless/event_workflows/serverless-using-brokers.adoc b/serverless/event_workflows/serverless-using-brokers.adoc

Original file line number	Diff line number	Diff line change
@@ -13,7 +13,7 @@ This section describes the steps required to create an API server source using `
`13`	`13`
`14`	`14`	`.Procedure`
`15`	`15`
`16`		`-. Create an API server source that uses a broker as an event sink:`
	`16`	`+. Create an API server source that uses a broker as a sink:`
`17`	`17`	`+`
`18`	`18`	`[source,terminal]`
`19`	`19`	`----`
`@@ -34,7 +34,7 @@ $ kn service create <service_name> --image quay.io/openshift-knative/knative-eve`
`34`	`34`	`$ kn trigger create <trigger_name> --sink ksvc:<service_name>`
`35`	`35`	`----`
`36`	`36`
`37`		`-. Create events by launching a Pod in the default namespace:`
	`37`	`+. Create events by launching a pod in the default namespace:`
`38`	`38`	`+`
`39`	`39`	`[source,terminal]`
`40`	`40`	`----`