Merge pull request #32365 from abrennan89/kafkaimprovement

kalexand-rh · web-flow · commit 82d2ea5438c2 · 2021-05-13T15:05:21.000-04:00
[SRVCOM-1245][srvls] Reorg Kafka docs
diff --git a/_topic_map.yml b/_topic_map.yml
@@ -2922,6 +2922,9 @@ Topics:
 # Event delivery
   - Name: Event delivery
     File: serverless-event-delivery
+# Knative Kafka
+  - Name: Knative Kafka
+    File: serverless-kafka
 # Event sources
 - Name: Event sources
   Dir: event_sources
@@ -2938,9 +2941,6 @@ Topics:
     File: serverless-sinkbinding
   - Name: Using a Kafka source
     File: serverless-kafka-source
-# Knative Kafka
-- Name: Using Apache Kafka with OpenShift Serverless
-  File: serverless-kafka
 # Functions - uncomment at tech preview
 # - Name: OpenShift Serverless Functions
 #   Dir: functions
diff --git a/modules/serverless-channels-creating-intro.adoc b/modules/serverless-channels-creating-intro.adoc
@@ -30,7 +30,6 @@ The `spec.channelTemplate` properties cannot be changed after creation, because
 
 The channel controller then creates the backing channel instance based on the `spec.channelTemplate` configuration.
 
-When this mechanism is used with the example above, two objects are created: a generic backing channel and an `InMemoryChannel` channel.
-If you are using a different default channel implementation, for example, Apache Kafka, a generic backing channel and `KafkaChannel` channel are created.
+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.
diff --git a/modules/serverless-creating-channel-admin-web-console.adoc b/modules/serverless-creating-channel-admin-web-console.adoc
@@ -20,6 +20,6 @@ If you have cluster administrator permissions, you can create a channel by using
 +
 [NOTE]
 ====
-Currently only `InMemoryChannel` channel objects are supported by default. Kafka channels are available if you have installed Apache Kafka on {ServerlessProductName}.
+Currently only `InMemoryChannel` channel objects are supported by default. Kafka channels are available if you have installed Knative Kafka on {ServerlessProductName}.
 ====
 . Click *Create*.
diff --git a/modules/serverless-event-delivery-component-behaviors.adoc b/modules/serverless-event-delivery-component-behaviors.adoc
@@ -7,10 +7,12 @@
 
 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
+[id="serverless-event-delivery-component-behaviors-kafka-channels_{context}"]
+== Event delivery behavior for Knative 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.
 
+[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:
diff --git a/modules/serverless-install-kafka-odc.adoc b/modules/serverless-install-kafka-odc.adoc
@@ -3,9 +3,9 @@
 // serverless/serverless-kafka.adoc
 
 [id="serverless-install-kafka-odc_{context}"]
-= Installing Apache Kafka components by using the web console
+= Installing Knative Kafka components by using the web console
 
-Cluster administrators can enable the use of Apache Kafka functionality in an {ServerlessProductName} deployment by instantiating the `KnativeKafka` custom resource definition provided by the *Knative Kafka* {ServerlessOperatorName} API.
+Cluster administrators can enable the use of Knative Kafka functionality in an {ServerlessProductName} deployment by instantiating the `KnativeKafka` custom resource definition provided by the *Knative Kafka* {ServerlessOperatorName} API.
 
 .Prerequisites
 
diff --git a/modules/serverless-rn-1-11-0.adoc b/modules/serverless-rn-1-11-0.adoc
@@ -10,17 +10,14 @@
 == New features
 
 * Knative Eventing on {ServerlessProductName} is now Generally Available (GA).
-* Apache Kafka features such as Kafka channel and Kafka event source are now available as a Technology Preview on {ServerlessProductName}. Kafka integration is delivered through the {ServerlessOperatorName} and does not require a separate community Operator installation. For more information, see the documentation on _Using Apache Kafka with OpenShift Serverless_.
+* Knative Kafka features such as Kafka channel and Kafka event source are now available as a Technology Preview on {ServerlessProductName}. Kafka integration is delivered through the {ServerlessOperatorName} and does not require a separate community Operator installation.
 * {ServerlessProductName} Functions is now delivered as a Developer Preview through the standard Knative `kn` CLI installation. This feature is not yet supported by Red Hat for production deployments, but can be used for development and testing. For more information about using {ServerlessProductName} Functions through the `kn func` CLI, see the link:https://openshift-knative.github.io/docs/docs/functions/about-functions.html[{ServerlessProductName} Functions Developer Preview documentation].
 * {ServerlessProductName} now uses Knative Serving 0.17.3.
 * {ServerlessProductName} uses Knative Eventing 0.17.2.
 * {ServerlessProductName} now uses Kourier 0.17.0.
 * {ServerlessProductName} now uses Knative `kn` CLI 0.17.3.
 * {ServerlessProductName} now uses Knative Kafka 0.17.1.
 
-// [id="fixed-issues-1-11-0_{context}"]
-// == Fixed issues
-
 [id="known-issues-1-11-0_{context}"]
 == Known issues
 
diff --git a/modules/serverless-rn-1-14-0.adoc b/modules/serverless-rn-1-14-0.adoc
@@ -14,15 +14,15 @@
 * {ServerlessProductName} now uses Kourier 0.20.0.
 * {ServerlessProductName} now uses Knative `kn` CLI 0.20.0.
 * {ServerlessProductName} now uses Knative Kafka 0.20.0.
-* Apache Kafka on {ServerlessProductName} is now Generally Available (GA).
+* Knative Kafka on {ServerlessProductName} is now Generally Available (GA).
 +
 [IMPORTANT]
 ====
-Only the `v1beta1` version of the API for Apache Kafka on {ServerlessProductName} is supported. Do not use the `v1alpha1` version of the API, as this is deprecated.
+Only the `v1beta1` version of the API for Knative Kafka on {ServerlessProductName} is supported. Do not use the `v1alpha1` version of the API, as this is deprecated.
 ====
 * The Operator channel for installing and upgrading {ServerlessProductName} has been updated to `stable` for {product-title} 4.6 and newer versions.
 * {ServerlessProductName} is now supported on IBM Power Systems, IBM Z, and LinuxONE, except for the following features, which are not yet supported:
-** Apache Kafka functionality.
+** Knative Kafka functionality.
 ** {ServerlessProductName} Functions developer preview.
 // Not including Camel-K since we don't document or support that yet for serverless anyway.
 
diff --git a/serverless/admin_guide/serverless-cluster-admin-eventing.adoc b/serverless/admin_guide/serverless-cluster-admin-eventing.adoc
@@ -29,5 +29,4 @@ include::modules/serverless-creating-subscription-admin-web-console.adoc[levelof
 * See xref:../../serverless/event_workflows/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].
-* For information about using Apache Kafka components, see xref:../../serverless/serverless-kafka.adoc#serverless-kafka[
-Using Apache Kafka with {ServerlessProductName}].
+* See xref:../../serverless/event_workflows/serverless-kafka.adoc#serverless-kafka[Knative Kafka].
diff --git a/serverless/event_sources/knative-event-sources.adoc b/serverless/event_sources/knative-event-sources.adoc
@@ -13,7 +13,7 @@ Currently, {ServerlessProductName} supports the following event source types:
 API server source:: Connects a sink to the Kubernetes API server.
 Ping source:: Periodically sends ping events with a constant payload. It can be used as a timer.
 Sink binding:: Allows you to connect core Kubernetes resource objects, such as `Deployment`, `Job`, or `StatefulSet` objects, with a sink.
-Apache Kafka source:: Connect a Kafka cluster to a sink as an event source.
+Knative Kafka source:: Connect a Kafka cluster to a sink as an event source.
 
 You can create and manage Knative event sources using the **Developer** perspective in the {product-title} web console, the `kn` CLI, or by applying YAML files.
 
@@ -22,7 +22,8 @@ You can create and manage Knative event sources using the **Developer** perspect
 * Create a xref:../../serverless/event_sources/serverless-sinkbinding.adoc#serverless-sinkbinding[sink binding].
 * Create a xref:../../serverless/event_sources/serverless-kafka-source.adoc#serverless-kafka-source[Kafka source].
 
-[id="knative-event-sources-additional-resources"]
+[id="additional-resources_knative-event-sources"]
 == Additional resources
+
 * For more information about eventing workflows using {ServerlessProductName}, see xref:../../serverless/architecture/serverless-event-architecture.adoc#serverless-event-architecture[Knative Eventing architecture].
-* For more information about using Kafka event sources, see xref:../../serverless/serverless-kafka.adoc#serverless-kafka[Using Apache Kafka with {ServerlessProductName}].
+* See xref:../../serverless/event_workflows/serverless-kafka.adoc#serverless-kafka[Knative Kafka].
diff --git a/serverless/event_sources/serverless-kafka-source.adoc b/serverless/event_sources/serverless-kafka-source.adoc
@@ -6,13 +6,20 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-The Apache Kafka event source brings messages into Knative. It reads events from an Apache Kafka cluster and passes these events to an event sink so that they can be consumed. You can use the `KafkaSource` event source with {ServerlessProductName}.
+You can create a Knative Kafka event source that reads events from an Apache Kafka cluster and passes these events to a sink.
+
+[id="prerequisites_serverless-kafka-source"]
+== Prerequisites
+
+You can use the `KafkaSource` event source with {ServerlessProductName} after you have xref:../../serverless/admin_guide/installing-knative-eventing.adoc#installing-knative-eventing[Knative Eventing] and xref:../../serverless/event_workflows/serverless-kafka.adoc#serverless-kafka[Knative Kafka] installed on your cluster.
 
 include::modules/serverless-kafka-source-odc.adoc[leveloffset=+1]
 include::modules/serverless-kafka-source-kn.adoc[leveloffset=+1]
 include::modules/serverless-kafka-source-yaml.adoc[leveloffset=+1]
 
-[id="serverless-kafka-source-additional-resources"]
+[id="additional-resources_serverless-kafka-source"]
 == Additional resources
 
+* See xref:../../serverless/event_sources/knative-event-sources.adoc#knative-event-sources[Getting started with event sources].
+* See xref:../../serverless/event_workflows/serverless-kafka.adoc#serverless-kafka[Knative Kafka].
 * See the link:https://access.redhat.com/documentation/en-us/red_hat_amq/7.6/html/amq_streams_on_openshift_overview/kafka-concepts_str#kafka-concepts-key_str[Red Hat AMQ Streams] documentation for more information about Kafka concepts.
diff --git a/serverless/event_sources/serverless-listing-event-sources.adoc b/serverless/event_sources/serverless-listing-event-sources.adoc
@@ -13,7 +13,7 @@ Currently, {ServerlessProductName} supports the following event source types:
 API server source:: Connects a sink to the Kubernetes API server.
 Ping source:: Periodically sends ping events with a constant payload. It can be used as a timer.
 Sink binding:: Allows you to connect core Kubernetes resource objects, such as `Deployment`, `Job`, or `StatefulSet` objects, with a sink.
-Apache Kafka source:: Connect a Kafka cluster to a sink as an event source.
+Knative Kafka source:: Connect a Kafka cluster to a sink as an event source.
 
 // 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
diff --git a/serverless/event_workflows/serverless-channels.adoc b/serverless/event_workflows/serverless-channels.adoc
@@ -20,6 +20,12 @@ The following are limitations of `InMemoryChannel` type channels:
 * `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="prerequisites_serverless-channels"]
+== Prerequisites
+
+* You must have xref:../../serverless/admin_guide/installing-knative-eventing.adoc#installing-knative-eventing[Knative Eventing] installed on your cluster.
+* Optional: Install xref:../../serverless/event_workflows/serverless-kafka.adoc#serverless-kafka[Knative Kafka] to use Kafka channels.
+
 include::modules/serverless-channel-default.adoc[leveloffset=+1]
 include::modules/serverless-channels-creating-intro.adoc[leveloffset=+1]
 
@@ -39,7 +45,8 @@ include::modules/serverless-connect-channel-source-odc.adoc[leveloffset=+2]
 // deleting channels
 include::modules/serverless-delete-channel-kn.adoc[leveloffset=+1]
 
-[id="serverless-channels-next-steps"]
+[id="next-steps_serverless-channels"]
 == Next steps
 
+* See xref:../../serverless/event_workflows/serverless-kafka.adoc#serverless-kafka[Knative Kafka].
 * 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-kafka.adoc b/serverless/event_workflows/serverless-kafka.adoc
@@ -1,6 +1,6 @@
 include::modules/serverless-document-attributes.adoc[]
 [id="serverless-kafka"]
-= Using Apache Kafka with {ServerlessProductName}
+= Knative Kafka
 include::modules/common-attributes.adoc[]
 :context: serverless-kafka
 
@@ -11,7 +11,7 @@ To do this, you must install the Knative Kafka components, and configure the int
 
 [NOTE]
 ====
-Apache Kafka is not currently supported for IBM Z and IBM Power Systems.
+Knative Kafka is not currently supported for IBM Z and IBM Power Systems.
 ====
 
 The {ServerlessOperatorName} provides the Knative Kafka API that can be used to create a `KnativeKafka` custom resource:
@@ -38,7 +38,18 @@ spec:
 // Install Kafka
 include::modules/serverless-install-kafka-odc.adoc[leveloffset=+1]
 
+[id="serverless-kafka-channel-link"]
+== Using Kafka channels
+
+Create a xref:../../serverless/event_workflows/serverless-channels.adoc#serverless-channels[Kafka channel].
+
+[id="serverless-kafka-source-link"]
+== Using Kafka source
+
+Create a xref:../../serverless/event_sources/serverless-kafka-source.adoc#serverless-kafka-source[Kafka event source].
+
 // Configure TLS and SASL for Kafka
+[id="serverless-kafka-authentication"]
 == Configuring authentication for Kafka
 
 In production, Kafka clusters are often secured using the TLS or SASL authentication methods. This section shows how to configure the Kafka channel to work against a protected Red Hat AMQ Streams (Kafka) cluster using TLS or SASL.
@@ -50,9 +61,3 @@ If you choose to enable SASL, Red Hat recommends to also enable TLS.
 
 include::modules/serverless-kafka-tls.adoc[leveloffset=+2]
 include::modules/serverless-kafka-sasl.adoc[leveloffset=+2]
-
-[id="serverless-kafka-next-steps"]
-== Next steps
-
-* Create a xref:../serverless/event_sources/serverless-kafka-source.adoc#serverless-kafka-source[Kafka event source].
-* Create a xref:../serverless/event_workflows/serverless-channels.adoc#serverless-channels[Kafka channel].

Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,6 @@ If you have cluster administrator permissions, you can create a channel by using`
`20`	`20`	`+`
`21`	`21`	`[NOTE]`
`22`	`22`	`====`
`23`		-Currently only `InMemoryChannel` channel objects are supported by default. Kafka channels are available if you have installed Apache Kafka on {ServerlessProductName}.
	`23`	+Currently only `InMemoryChannel` channel objects are supported by default. Kafka channels are available if you have installed Knative Kafka on {ServerlessProductName}.
`24`	`24`	`====`
`25`	`25`	`. Click Create.`