[SRVKE-1271 + SRVKE-1272]: Updating Kafka broker docs for GA

Author: abrennan89

_topic_maps/_topic_map.yml

@@ -3499,6 +3499,8 @@ Topics:
     File: serverless-functions-about
   - Name: Event sources
     File: knative-event-sources
+  - Name: Brokers
+    File: serverless-brokers
   - Name: Channels and subscriptions
     File: serverless-channels
 - Name: Install
@@ -3556,7 +3558,7 @@ Topics:
   - Name: Creating and managing subscriptions
     File: serverless-subs
 # Brokers
-  - Name: Brokers
+  - Name: Creating brokers
     File: serverless-using-brokers
 # Triggers
   - Name: Triggers

_topic_maps/_topic_map_osd.yml

@@ -248,6 +248,8 @@ Topics:
     File: serverless-functions-about
   - Name: Event sources
     File: knative-event-sources
+  - Name: Brokers
+    File: serverless-brokers
   - Name: Channels and subscriptions
     File: serverless-channels
 - Name: Install
@@ -301,7 +303,7 @@ Topics:
     File: serverless-creating-channels
   - Name: Creating and managing subscriptions
     File: serverless-subs
-  - Name: Brokers
+  - Name: Creating brokers
     File: serverless-using-brokers
   - Name: Triggers
     File: serverless-triggers

_topic_maps/_topic_map_rosa.yml

@@ -451,6 +451,8 @@ Topics:
     File: serverless-functions-about
   - Name: Event sources
     File: knative-event-sources
+  - Name: Brokers
+    File: serverless-brokers
   - Name: Channels and subscriptions
     File: serverless-channels
 - Name: Install
@@ -504,7 +506,7 @@ Topics:
     File: serverless-creating-channels
   - Name: Creating and managing subscriptions
     File: serverless-subs
-  - Name: Brokers
+  - Name: Creating brokers
     File: serverless-using-brokers
   - Name: Triggers
     File: serverless-triggers

modules/serverless-broker-types.adoc

@@ -1,27 +1,24 @@
 // Module included in the following assemblies:
 //
-// * /serverless/develop/serverless-using-brokers.adoc
+// * /serverless/discover/serverless-brokers.adoc
 
 :_content-type: CONCEPT
 [id="serverless-broker-types_{context}"]
 = Broker types
 
-There are multiple broker implementations available for use with {ServerlessProductName}, each of which have different event delivery guarantees and use different underlying technologies. You can choose the broker implementation when creating a broker by specifying a broker class, otherwise the default broker class is used. The default broker class can be configured by cluster administrators.
-// TO DO: Need to add docs about setting default broker class.
+Cluster administrators can set the default broker implementation for a cluster. When you create a broker, the default broker implementation is used, unless you provide set configurations in the `Broker` object.
 
-[id="serverless-broker-types-channel-based"]
-== Channel-based broker
-
-The channel-based broker implementation internally uses channels for event delivery. Channel-based brokers provide different event delivery guarantees based on the channel implementation a broker instance uses, for example:
+:FeatureName: Kafka broker
+include::snippets/technology-preview.adoc[leveloffset=+2]
 
-* A broker using the `InMemoryChannel` implementation is useful for development and testing purposes, but does not provide adequate event delivery guarantees for production environments.
+[id="serverless-broker-types-default_{context}"]
+== Default broker implementation for development purposes
 
-* A broker using the `KafkaChannel` implementation provides the event delivery guarantees required for a production environment.
+Knative provides a default, channel-based broker implementation. This channel-based broker can be used for development and testing purposes, but does not provide adequate event delivery guarantees for production environments. The default broker is backed by the `InMemoryChannel` channel implementation by default.
 
-[id="serverless-broker-types-kafka"]
-== Kafka broker
+If you want to use Kafka to reduce network hops, use the Kafka broker implementation. Do not configure the channel-based broker to be backed by the `KafkaChannel` channel implementation.
 
-The Kafka broker is a broker implementation that uses Kafka internally to provide at-least once delivery guarantees. It supports multiple Kafka versions, and has a native integration with Kafka for storing and routing events.
+[id="serverless-broker-types-production_{context}"]
+== Production-ready Kafka broker implementation
 
-:FeatureName: Kafka broker
-include::snippets/technology-preview.adoc[leveloffset=+2]
+include::snippets/serverless-about-kafka-broker.adoc[]

modules/serverless-kafka-broker-with-kafka-topic.adoc

@@ -1,6 +1,5 @@
 // Module included in the following assemblies:
 //
-// * serverless/develop/serverless-kafka-developer.adoc
 // * serverless/develop/serverless-using-brokers.adoc
 
 :_content-type: PROCEDURE

modules/serverless-kafka-broker.adoc

@@ -1,6 +1,5 @@
 // Module included in the following assemblies:
 //
-// * serverless/develop/serverless-kafka-developer.adoc
 // * serverless/develop/serverless-using-brokers.adoc
 
 :_content-type: PROCEDURE

serverless/develop/serverless-kafka-developer.adoc

@@ -45,13 +45,12 @@ include::modules/serverless-kafka-source-yaml.adoc[leveloffset=+2]
 [id="serverless-kafka-developer-broker"]
 == Kafka broker
 
-include::snippets/serverless-kafka-broker-intro.adoc[]
-
 :FeatureName: Kafka broker
 include::snippets/technology-preview.adoc[leveloffset=+2]
 
-include::modules/serverless-kafka-broker.adoc[leveloffset=+2]
-include::modules/serverless-kafka-broker-with-kafka-topic.adoc[leveloffset=+2]
+include::snippets/serverless-about-kafka-broker.adoc[]
+
+For information about using Kafka brokers, see xref:../../serverless/develop/serverless-using-brokers.adoc#serverless-using-brokers[Creating brokers].
 
 // Kafka channels
 include::modules/serverless-create-kafka-channel-yaml.adoc[leveloffset=+1]

serverless/develop/serverless-using-brokers.adoc

@@ -1,30 +1,30 @@
 :_content-type: ASSEMBLY
 [id="serverless-using-brokers"]
-= Brokers
+= Creating brokers
 include::_attributes/common-attributes.adoc[]
 :context: serverless-using-brokers
 
 toc::[]
 
-include::snippets/serverless-brokers-intro.adoc[]
+Knative provides a default, channel-based broker implementation. This channel-based broker can be used for development and testing purposes, but does not provide adequate event delivery guarantees for production environments.
 
-include::modules/serverless-broker-types.adoc[leveloffset=+1]
+If a cluster administrator has configured your {ServerlessProductName} deployment to use Kafka as the default broker type, creating a broker by using the default settings creates a Kafka-based broker.
 
-[id="serverless-using-brokers-creating-brokers"]
-== Creating a broker that uses default settings
+If your {ServerlessProductName} deployment is not configured to use Kafka broker as the default broker type, the channel-based broker is created when you use the default settings in the following procedures.
 
-{ServerlessProductName} provides a `default` Knative broker that you can create by using the Knative (`kn`) CLI. You can also create the `default` broker by adding the `eventing.knative.dev/injection: enabled` annotation to a trigger, or by adding the `eventing.knative.dev/injection=enabled` label to a namespace.
+:FeatureName: Kafka broker
+include::snippets/technology-preview.adoc[leveloffset=+2]
 
-include::modules/serverless-create-broker-kn.adoc[leveloffset=+2]
-include::modules/serverless-creating-broker-annotation.adoc[leveloffset=+2]
-include::modules/serverless-creating-broker-labeling.adoc[leveloffset=+2]
-include::modules/serverless-deleting-broker-injection.adoc[leveloffset=+2]
-include::modules/serverless-creating-a-broker-odc.adoc[leveloffset=+2]
+include::modules/serverless-create-broker-kn.adoc[leveloffset=+1]
+include::modules/serverless-creating-broker-annotation.adoc[leveloffset=+1]
+include::modules/serverless-creating-broker-labeling.adoc[leveloffset=+1]
+include::modules/serverless-deleting-broker-injection.adoc[leveloffset=+1]
+include::modules/serverless-creating-a-broker-odc.adoc[leveloffset=+1]
 
-[id="serverless-using-brokers-kafka"]
-== Kafka broker
+[id="serverless-using-brokers-kafka_{context}"]
+== Creating a Kafka broker when it is not configured as the default broker type
 
-include::snippets/serverless-kafka-broker-intro.adoc[]
+If your {ServerlessProductName} deployment is not configured to use Kafka broker as the default broker type, you can use one of the following procedures to create a Kafka-based broker.
 
 :FeatureName: Kafka broker
 include::snippets/technology-preview.adoc[leveloffset=+2]
@@ -35,7 +35,7 @@ include::modules/serverless-kafka-broker-with-kafka-topic.adoc[leveloffset=+2]
 [id="serverless-using-brokers-managing-brokers"]
 == Managing brokers
 
-The Knative (`kn`) CLI provides commands that can be used to list, describe, update, and delete brokers.
+The Knative (`kn`) CLI provides commands that can be used to describe and list existing brokers.
 
 include::modules/serverless-list-broker-kn.adoc[leveloffset=+2]
 include::modules/serverless-describe-broker-kn.adoc[leveloffset=+2]

serverless/discover/serverless-brokers.adoc

@@ -0,0 +1,14 @@
+:_content-type: ASSEMBLY
+[id="serverless-brokers"]
+= Brokers
+include::_attributes/common-attributes.adoc[]
+:context: serverless-brokers
+
+toc::[]
+
+include::snippets/serverless-brokers-intro.adoc[]
+include::modules/serverless-broker-types.adoc[leveloffset=+1]
+
+[id="next-steps_serverless-brokers"]
+== Next steps
+* xref:../../serverless/develop/serverless-using-brokers.adoc#serverless-using-brokers[Creating brokers]

snippets/serverless-about-kafka-broker.adoc

@@ -0,0 +1,22 @@
+// Text snippet included in the following modules and assemblies:
+//
+// * /modules/serverless-broker-types.adoc
+// * /serverless/develop/serverless-kafka-developer.adoc
+
+:_content-type: SNIPPET
+
+For production-ready Knative Eventing deployments, Red Hat recommends using the Knative Kafka broker implementation. The Kafka broker is an Apache Kafka native implementation of the Knative broker, which sends CloudEvents directly to the Kafka instance.
+
+[IMPORTANT]
+====
+The Federal Information Processing Standards (FIPS) mode is disabled for Kafka broker.
+====
+
+The Kafka broker has a native integration with Kafka for storing and routing events. This allows better integration with Kafka for the broker and trigger model over other broker types, and reduces network hops. Other benefits of the Kafka broker implementation include:
+
+* At-least-once delivery guarantees
+* Ordered delivery of events, based on the CloudEvents partitioning extension
+* Control plane high availability
+* A horizontally scalable data plane
+
+The Knative Kafka broker stores incoming CloudEvents as Kafka records, using the binary content mode. This means that all CloudEvent attributes and extensions are mapped as headers on the Kafka record, while the `data` spec of the CloudEvent corresponds to the value of the Kafka record.

snippets/serverless-brokers-intro.adoc

@@ -4,6 +4,7 @@
 // * /serverless/develop/serverless-triggers.adoc
 // * /modules/serverless-creating-broker-admin-web-console.adoc
 // * /modules/serverless-creating-trigger-admin-web-console.adoc
+// * /serverless/discover/serverless-brokers.adoc
 
 :_content-type: SNIPPET