Merge pull request #40560 from abrennan89/kafkareorg

SRVKE-747: Split knative kafka docs into different personas

Author: abrennan89

_topic_maps/_topic_map.yml

@@ -3186,26 +3186,25 @@ Topics:
     File: serverless-apiserversource
   - Name: Using a ping source
     File: serverless-pingsource
-  - Name: Using a Kafka source
-    File: serverless-kafka-source
   - File: serverless-custom-event-sources
     Name: Custom event sources
   - Name: Creating and deleting channels
     File: serverless-creating-channels
   - Name: Subscriptions
     File: serverless-subs
+  - Name: Knative Kafka
+    File: serverless-kafka-developer
 # Admin guide
 - Name: Administer
   Dir: admin_guide
   Topics:
   - Name: Configuring OpenShift Serverless
     File: serverless-configuration
+    # Eventing
   - Name: Configuring channel defaults
     File: serverless-configuring-channels
-    # Ingress options
-  - Name: Integrating Service Mesh with OpenShift Serverless
-    File: serverless-ossm-setup
-    # Eventing
+  - Name: Knative Kafka
+    File: serverless-kafka-admin
   - Name: Creating Knative Eventing components in the Administrator perspective
     File: serverless-cluster-admin-eventing
 #  - Name: Configuring the Knative Eventing custom resource
@@ -3216,6 +3215,9 @@ Topics:
     File: serverless-cluster-admin-serving
   - Name: Configuring the Knative Serving custom resource
     File: knative-serving-CR-config
+    # Ingress options
+  - Name: Integrating Service Mesh with OpenShift Serverless
+    File: serverless-ossm-setup
     # Monitoring
   - Name: Monitoring serverless components
     File: serverless-admin-monitoring
@@ -3255,6 +3257,8 @@ Topics:
     File: serverless-custom-domains
   - Name: Using a custom TLS certificate for domain mapping
     File: serverless-custom-tls-cert-domain-mapping
+  - Name: Security configuration for Knative Kafka
+    File: serverless-kafka-security
 # Knative Eventing
 - Name: Knative Eventing
   Dir: knative_eventing
@@ -3268,9 +3272,6 @@ Topics:
 # Event delivery
   - Name: Event delivery
     File: serverless-event-delivery
-# Knative Kafka
-  - Name: Knative Kafka
-    File: serverless-kafka
 # Functions
 - Name: Functions
   Dir: functions

modules/serverless-install-kafka-odc.adoc

@@ -1,18 +1,37 @@
 // Module is included in the following assemblies:
 //
-// serverless/knative_eventing/serverless-kafka.adoc
+// serverless/admin_guide/serverless-kafka-admin.adoc
 
 [id="serverless-install-kafka-odc_{context}"]
-= Installing Knative Kafka components by using the web console
+= Installing Knative Kafka
 
-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.
+The {ServerlessOperatorName} provides the Knative Kafka API that can be used to create a `KnativeKafka` custom resource:
+
+.Example `KnativeKafka` custom resource
+[source,yaml]
+----
+apiVersion: operator.serverless.openshift.io/v1alpha1
+kind: KnativeKafka
+metadata:
+    name: knative-kafka
+    namespace: knative-eventing
+spec:
+    channel:
+        enabled: true <1>
+        bootstrapServers: <bootstrap_servers> <2>
+    source:
+        enabled: true <3>
+----
+<1> Enables developers to use the `KafkaChannel` channel type in the cluster.
+<2> A comma-separated list of bootstrap servers from your AMQ Streams cluster.
+<3> Enables developers to use the `KafkaSource` event source type in the cluster.
 
 .Prerequisites
 
 * You have installed {ServerlessProductName}, including Knative Eventing, in your {product-title} cluster.
 * You have access to a Red Hat AMQ Streams cluster.
 * You have cluster administrator permissions on {product-title}.
-* You are logged in to the web console.
+* You are logged in to the {product-title} web console.
 
 .Procedure
 

modules/serverless-kafka-event-delivery.adoc

@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//
+// * serverless/develop/serverless-kafka-developer.adoc
+
+[id="serverless-kafka-delivery-retries_{context}"]
+= Event delivery and retries
+
+Using Kafka components in an event-driven architecture provides "at least once" event delivery. This means that operations are retried until a return code value is received. This makes applications more resilient to lost events; however, it might result in duplicate events being sent.
+
+For the Kafka event source, there is a fixed number of retries for event delivery by default. For Kafka channels, retries are only performed if they are configured in the Kafka channel `Delivery` spec.

modules/serverless-kafka-source-kn.adoc

@@ -1,3 +1,7 @@
+// Module included in the following assemblies:
+//
+// * serverless/develop/serverless-kafka-developer.adoc
+
 [id="serverless-kafka-source-kn_{context}"]
 = Creating a Kafka event source by using the Knative CLI
 

modules/serverless-kafka-source-odc.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * serverless/event_sources/serverless-kafka-source.adoc
+// * serverless/develop/serverless-kafka-developer.adoc
 
 [id="serverless-kafka-source-odc_{context}"]
 = Creating a Kafka event source by using the web console

modules/serverless-kafka-source-yaml.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * serverless/event_sources/serverless-kafka-source.adoc
+// * serverless/develop/serverless-kafka-developer.adoc
 
 [id="serverless-kafka-source-yaml_{context}"]
 = Creating a Kafka event source by using YAML

serverless/admin_guide/serverless-cluster-admin-eventing.adoc

@@ -29,4 +29,3 @@ include::modules/serverless-creating-subscription-admin-web-console.adoc[levelof
 * See xref:../../serverless/develop/serverless-subs.adoc#serverless-subs[Subscriptions].
 * See xref:../../serverless/knative_eventing/serverless-triggers.adoc#serverless-triggers[Triggers].
 * See xref:../../serverless/discover/serverless-channels.adoc#serverless-channels[Channels].
-* See xref:../../serverless/knative_eventing/serverless-kafka.adoc#serverless-kafka[Knative Kafka].

serverless/admin_guide/serverless-kafka-admin.adoc

@@ -0,0 +1,27 @@
+include::modules/serverless-document-attributes.adoc[]
+[id="serverless-kafka-admin"]
+= Knative Kafka
+include::modules/common-attributes.adoc[]
+:context: serverless-kafka-admin
+
+toc::[]
+
+In addition to the Knative Eventing components that are provided as part of a core {ServerlessProductName} installation, cluster administrators can install the `KnativeKafka` custom resource (CR).
+
+The `KnativeKafka` CR provides users with additional options, such as:
+
+* Kafka event source
+* Kafka channel
+// * Kafka broker
+
+[NOTE]
+====
+Knative Kafka is not currently supported for IBM Z and IBM Power Systems.
+====
+
+include::modules/serverless-install-kafka-odc.adoc[leveloffset=+1]
+
+[id="additional-resources_serverless-kafka-admin"]
+== Additional resources
+
+* 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.

serverless/develop/serverless-kafka-developer.adoc

@@ -0,0 +1,41 @@
+[id="serverless-kafka-developer"]
+= Knative Kafka
+include::modules/serverless-document-attributes.adoc[]
+include::modules/common-attributes.adoc[]
+:context: serverless-kafka-developer
+
+toc::[]
+
+Knative Kafka functionality is available in an {ServerlessProductName} installation xref:../../serverless/admin_guide/serverless-kafka-admin.adoc#serverless-kafka-admin[if a cluster administrator has installed the `KnativeKafka` custom resource].
+
+Knative Kafka provides additional options, such as:
+
+* Kafka event source
+* xref:../../serverless/develop/serverless-creating-channels.adoc#serverless-creating-channels[Kafka channel]
+// * Kafka broker
+
+[NOTE]
+====
+Knative Kafka is not currently supported for IBM Z and IBM Power Systems.
+====
+
+include::modules/serverless-kafka-event-delivery.adoc[leveloffset=+1]
+
+[id="serverless-kafka-developer-event-source"]
+== Using a Kafka event source
+
+You can create a Knative Kafka event source that reads events from an Apache Kafka cluster and passes these events to a sink.
+
+// dev console
+include::modules/serverless-kafka-source-odc.adoc[leveloffset=+2]
+// kn commands
+include::modules/serverless-kafka-source-kn.adoc[leveloffset=+2]
+include::modules/specifying-sink-flag-kn.adoc[leveloffset=+3]
+// YAML
+include::modules/serverless-kafka-source-yaml.adoc[leveloffset=+2]
+
+[id="additional-resources_serverless-kafka-developer"]
+== Additional resources
+
+* 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.
+* See xref:../../serverless/discover/knative-event-sources.adoc#knative-event-sources[Event sources].