Merge pull request #45969 from abrennan89/SRVKE-1220

[SRVKE-1220 + SRVKE-1185]: Add docs for using an external topic with Kafka brokers, updating kafka left nav headings

Author: abrennan89

_topic_maps/_topic_map.yml

@@ -3459,7 +3459,7 @@ Topics:
 # Triggers
   - Name: Triggers
     File: serverless-triggers
-  - Name: Knative Kafka
+  - Name: Using Knative Kafka
     File: serverless-kafka-developer
 # Admin guide
 - Name: Administer
@@ -3468,7 +3468,7 @@ Topics:
   - Name: Global configuration
     File: serverless-configuration
     # Eventing
-  - Name: Knative Kafka
+  - Name: Configuring Knative Kafka
     File: serverless-kafka-admin
   - Name: Serverless components in the Administrator perspective
     File: serverless-admin-perspective

_topic_maps/_topic_map_osd.yml

@@ -275,14 +275,14 @@ Topics:
     File: serverless-using-brokers
   - Name: Triggers
     File: serverless-triggers
-  - Name: Knative Kafka
+  - Name: Using Knative Kafka
     File: serverless-kafka-developer
 - Name: Administer
   Dir: admin_guide
   Topics:
   - Name: Global configuration
     File: serverless-configuration
-  - Name: Knative Kafka
+  - Name: Configuring Knative Kafka
     File: serverless-kafka-admin
   - Name: Serverless components in the Administrator perspective
     File: serverless-admin-perspective

modules/serverless-broker-types.adoc

@@ -9,7 +9,7 @@
 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.
 
-[id="serverless-using-brokers-channel-based"]
+[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:
@@ -18,10 +18,10 @@ The channel-based broker implementation internally uses channels for event deliv
 
 * A broker using the `KafkaChannel` implementation provides the event delivery guarantees required for a production environment.
 
-[id="serverless-using-brokers-kafka"]
+[id="serverless-broker-types-kafka"]
 == Kafka broker
 
+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.
+
 :FeatureName: Kafka broker
 include::snippets/technology-preview.adoc[leveloffset=+2]
-
-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.

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

@@ -0,0 +1,44 @@
+// Module included in the following assemblies:
+//
+// * serverless/develop/serverless-kafka-developer.adoc
+// * serverless/develop/serverless-using-brokers.adoc
+
+:_content-type: PROCEDURE
+[id="serverless-kafka-broker-with-kafka-topic_{context}"]
+= Creating a Kafka broker that uses an externally managed Kafka topic
+
+If you want to use a Kafka broker without allowing it to create its own internal topic, you can use an externally managed Kafka topic instead. To do this, you must create a Kafka `Broker` object that uses the `kafka.eventing.knative.dev/external.topic` annotation.
+
+.Prerequisites
+
+* The {ServerlessOperatorName}, Knative Eventing, and the `KnativeKafka` custom resource are installed on your {product-title} cluster.
+
+* You have access to a Kafka instance such as 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], and have created a Kafka topic.
+
+* You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}.
+
+* You have installed the OpenShift (`oc`) CLI.
+
+.Procedure
+
+. Create a Kafka-based broker as a YAML file:
++
+[source,yaml]
+----
+apiVersion: eventing.knative.dev/v1
+kind: Broker
+metadata:
+  annotations:
+    eventing.knative.dev/broker.class: Kafka <1>
+    kafka.eventing.knative.dev/external.topic: <topic_name> <2>
+...
+----
+<1> The broker class. If not specified, brokers use the default class as configured by cluster administrators. To use the Kafka broker, this value must be `Kafka`.
+<2> The name of the Kafka topic that you want to use.
+
+. Apply the Kafka-based broker YAML file:
++
+[source,terminal]
+----
+$ oc apply -f <filename>
+----

modules/serverless-kafka-broker.adoc

@@ -12,8 +12,10 @@ Creating Knative resources by using YAML files uses a declarative API, which ena
 .Prerequisites
 
 * The {ServerlessOperatorName}, Knative Eventing, and the `KnativeKafka` custom resource are installed on your {product-title} cluster.
+
 * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}.
-* Install the OpenShift CLI (`oc`).
+
+* You have installed the OpenShift (`oc`) CLI.
 
 .Procedure
 

serverless/admin_guide/serverless-kafka-admin.adoc

@@ -1,6 +1,6 @@
 :_content-type: ASSEMBLY
 [id="serverless-kafka-admin"]
-= Knative Kafka
+= Configuring Knative Kafka
 include::_attributes/common-attributes.adoc[]
 :context: serverless-kafka-admin
 

serverless/develop/serverless-kafka-developer.adoc

@@ -1,6 +1,6 @@
 :_content-type: ASSEMBLY
 [id="serverless-kafka-developer"]
-= Knative Kafka
+= Using Knative Kafka
 include::_attributes/common-attributes.adoc[]
 :context: serverless-kafka-developer
 
@@ -45,7 +45,7 @@ include::modules/serverless-kafka-source-yaml.adoc[leveloffset=+2]
 [id="serverless-kafka-developer-broker"]
 == Kafka broker
 
-If a cluster administrator has configured your {ServerlessProductName} deployment to use Kafka broker as the default broker type, xref:../../serverless/develop/serverless-using-brokers.adoc#serverless-using-brokers-creating-brokers[creating a broker by using the default settings] creates a Kafka-based `Broker` object. If your {ServerlessProductName} deployment is not configured to use Kafka broker as the default broker type, you can still use the following procedure to create a Kafka-based broker.
+include::snippets/serverless-kafka-broker-intro.adoc[]
 
 :FeatureName: Kafka broker
 include::snippets/technology-preview.adoc[leveloffset=+2]
@@ -56,6 +56,7 @@ The Kafka broker, which is currently in Technology Preview, is not supported on
 ====
 
 include::modules/serverless-kafka-broker.adoc[leveloffset=+2]
+include::modules/serverless-kafka-broker-with-kafka-topic.adoc[leveloffset=+2]
 
 // Kafka channels
 include::modules/serverless-create-kafka-channel-yaml.adoc[leveloffset=+1]

serverless/develop/serverless-using-brokers.adoc

@@ -21,6 +21,22 @@ 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]
 
+[id="serverless-using-brokers-kafka"]
+== Kafka broker
+
+include::snippets/serverless-kafka-broker-intro.adoc[]
+
+:FeatureName: Kafka broker
+include::snippets/technology-preview.adoc[leveloffset=+2]
+
+[IMPORTANT]
+====
+The Kafka broker, which is currently in Technology Preview, is not supported on FIPS.
+====
+
+include::modules/serverless-kafka-broker.adoc[leveloffset=+2]
+include::modules/serverless-kafka-broker-with-kafka-topic.adoc[leveloffset=+2]
+
 [id="serverless-using-brokers-managing-brokers"]
 == Managing brokers
 

snippets/serverless-kafka-broker-intro.adoc

@@ -0,0 +1,7 @@
+// Text snippet included in the following modules:
+//
+// * /serverless/develop/serverless-using-brokers.adoc
+
+:_content-type: SNIPPET
+
+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` object. 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.