Merge pull request #40701 from abrennan89/kafkadocs

SRVKE-747: Broker docs clean up and add Kafka broker

Author: abrennan89

_topic_maps/_topic_map.yml

@@ -3210,6 +3210,8 @@ Topics:
     File: serverless-configuring-routes
   - Name: Event sinks
     File: serverless-event-sinks
+  - Name: Event delivery
+    File: serverless-event-delivery
   - Name: Using the API server source
     File: serverless-apiserversource
   - Name: Using a ping source
@@ -3220,6 +3222,12 @@ Topics:
     File: serverless-creating-channels
   - Name: Subscriptions
     File: serverless-subs
+# Brokers
+  - Name: Brokers
+    File: serverless-using-brokers
+# Triggers
+  - Name: Triggers
+    File: serverless-triggers
   - Name: Knative Kafka
     File: serverless-kafka-developer
 # Admin guide
@@ -3229,8 +3237,8 @@ Topics:
   - Name: Configuring OpenShift Serverless
     File: serverless-configuration
     # Eventing
-  - Name: Configuring channel defaults
-    File: serverless-configuring-channels
+  - Name: Configuring Knative Eventing defaults
+    File: serverless-configuring-eventing-defaults
   - Name: Knative Kafka
     File: serverless-kafka-admin
   - Name: Creating Knative Eventing components in the Administrator perspective
@@ -3289,19 +3297,6 @@ Topics:
     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
-  Topics:
-# Brokers
-  - Name: Brokers
-    File: serverless-using-brokers
-# Triggers
-  - Name: Triggers
-    File: serverless-triggers
-# Event delivery
-  - Name: Event delivery
-    File: serverless-event-delivery
 # Functions
 - Name: Functions
   Dir: functions

modules/serverless-broker-types.adoc

@@ -0,0 +1,19 @@
+[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.
+
+[id="serverless-using-brokers-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:
+
+* A broker using the `InMemoryChannel` implementation is useful for development and testing purposes, but does not provide adequate event delivery guarantees for production environments.
+
+* A broker using the `KafkaChannel` implementation provides the event delivery guarantees required for a production environment.
+
+[id="serverless-using-brokers-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.

modules/serverless-channel-default.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-//  * serverless/channels/serverless-channels.adoc
+//  * serverless/admin_guide/serverless-configuring-eventing-defaults.adoc
 
 [id="serverless-channel-default_{context}"]
 = Configuring the default channel implementation

modules/serverless-create-kafka-channel-yaml.adoc

@@ -1,7 +1,7 @@
 // Module included in the following assemblies:
 //
-//  * serverless/knative_eventing/serverless-creating-channels.adoc
-//  * serverless/knative_eventing/serverless-kafka.adoc
+//  * serverless/develop/serverless-creating-channels.adoc
+//  * serverless/develop/serverless-kafka-developer.adoc
 
 [id="serverless-create-kafka-channel-yaml_{context}"]
 = Creating a Kafka channel by using YAML

modules/serverless-event-delivery-component-behaviors.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// serverless/knative_eventing/serverless-event-delivery.adoc
+// serverless/develop/serverless-event-delivery.adoc
 
 [id="serverless-event-delivery-component-behaviors_{context}"]
 = Event delivery behavior for Knative Eventing channels

modules/serverless-install-kafka-odc.adoc

@@ -21,10 +21,25 @@ spec:
         bootstrapServers: <bootstrap_servers> <2>
     source:
         enabled: true <3>
+    broker:
+        enabled: true <4>
+        defaultConfig:
+            bootstrapServers: <bootstrap_servers> <5>
+            numPartitions: <num_partitions> <6>
+            replicationFactor: <replication_factor> <7>
 ----
 <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.
+<4> Enables developers to use the Knative Kafka broker implementation in the cluster.
+<5> A comma-separated list of bootstrap servers from your Red Hat AMQ Streams cluster.
+<6> Defines the number of partitions of the Kafka topics, backed by the `Broker` objects. The default is `10`.
+<7> Defines the replication factor of the Kafka topics, backed by the `Broker` objects. The default is `3`.
++
+[NOTE]
+====
+The `replicationFactor` value must be less than or equal to the number of nodes of your Red Hat AMQ Streams cluster.
+====
 
 .Prerequisites
 
@@ -42,7 +57,7 @@ spec:
 +
 [IMPORTANT]
 ====
-To use the Kafka channel or Kafka source on your cluster, you must toggle the *Enable* switch for the options you want to use to *true*. These switches are set to *false* by default. Additionally, to use the Kafka channel, you must specify the Boostrap Servers.
+To use the Kafka channel, source, or broker on your cluster, you must toggle the *enabled* switch for the options you want to use to *true*. These switches are set to *false* by default. Additionally, to use the Kafka channel or broker, you must specify the bootstrap servers.
 ====
 .. Using the form is recommended for simpler configurations that do not require full control of *KnativeKafka* object creation.
 .. Editing the YAML is recommended for more complex configurations that require full control of *KnativeKafka* object creation. You can access the YAML by clicking the *Edit YAML* link in the top right of the *Create Knative Kafka* page.

modules/serverless-kafka-broker-sasl-default-config.adoc

@@ -0,0 +1,57 @@
+// Module is included in the following assemblies:
+//
+// * serverless/admin_guide/serverless-kafka-admin.adoc
+
+[id="serverless-kafka-broker-sasl-default-config_{context}"]
+= Configuring SASL authentication for Kafka brokers
+
+As a cluster administrator, you can set up _Simple Authentication and Security Layer_ (SASL) authentication for Kafka brokers by modifying the `KnativeKafka` custom resource (CR).
+
+.Prerequisites
+
+* The {ServerlessOperatorName}, Knative Eventing, and the `KnativeKafka` CR 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}.
+* You have a username and password for a Kafka cluster.
+* You have chosen the SASL mechanism to use, for example `PLAIN`, `SCRAM-SHA-256`, or `SCRAM-SHA-512`.
+* If TLS is enabled, you also need the `ca.crt` certificate file for the Kafka cluster.
+
+[NOTE]
+====
+It is recommended to enable TLS in addition to SASL.
+====
+
+.Procedure
+
+. Create the certificate files as a secret in the `knative-eventing` namespace:
++
+[source,terminal]
+----
+$ oc create secret -n knative-eventing generic <secret_name> \
+  --from-literal=protocol=SASL_SSL \
+  --from-literal=sasl.mechanism=<sasl_mechanism> \
+  --from-file=ca.crt=caroot.pem \
+  --from-literal=password="SecretPassword" \
+  --from-literal=user="my-sasl-user"
+----
++
+[IMPORTANT]
+====
+Use the key names `ca.crt`, `password`, and `sasl.mechanism`. Do not change them.
+====
+
+. Edit the `KnativeKafka` CR and add a reference to your secret in the `broker` spec:
++
+[source,yaml]
+----
+apiVersion: operator.serverless.openshift.io/v1alpha1
+kind: KnativeKafka
+metadata:
+  namespace: knative-eventing
+  name: knative-kafka
+spec:
+  broker:
+    enabled: true
+    defaultConfig:
+      authSecretName: <secret_name>
+...
+----

modules/serverless-kafka-broker-tls-default-config.adoc

@@ -0,0 +1,50 @@
+// Module is included in the following assemblies:
+//
+// * serverless/admin_guide/serverless-kafka-admin.adoc
+
+[id="serverless-kafka-broker-tls-default-config_{context}"]
+= Configuring TLS authentication for Kafka brokers
+
+As a cluster administrator, you can set up _Transport Layer Security_ (TLS) authentication for Kafka brokers by modifying the `KnativeKafka` custom resource (CR).
+
+.Prerequisites
+
+* The {ServerlessOperatorName}, Knative Eventing, and the `KnativeKafka` CR 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}.
+* You have a Kafka cluster CA certificate stored as a `.pem` file.
+* You have a Kafka cluster client certificate and a key stored as `.pem` files.
+
+.Procedure
+
+. Create the certificate files as a secret in the `knative-eventing` namespace:
++
+[source,terminal]
+----
+$ oc create secret -n knative-eventing generic <secret_name> \
+  --from-literal=protocol=SSL \
+  --from-file=ca.crt=caroot.pem \
+  --from-file=user.crt=certificate.pem \
+  --from-file=user.key=key.pem
+----
++
+[IMPORTANT]
+====
+Use the key names `ca.crt`, `user.crt`, and `user.key`. Do not change them.
+====
+
+. Edit the `KnativeKafka` CR and add a reference to your secret in the `broker` spec:
++
+[source,yaml]
+----
+apiVersion: operator.serverless.openshift.io/v1alpha1
+kind: KnativeKafka
+metadata:
+  namespace: knative-eventing
+  name: knative-kafka
+spec:
+  broker:
+    enabled: true
+    defaultConfig:
+      authSecretName: <secret_name>
+...
+----

modules/serverless-kafka-broker.adoc

@@ -0,0 +1,40 @@
+// Module included in the following assemblies:
+//
+// * serverless/develop/serverless-kafka-developer.adoc
+// * serverless/develop/serverless-using-brokers.adoc
+
+[id="serverless-kafka-broker_{context}"]
+= Creating a Kafka broker
+
+.Prerequisites
+
+* The {ServerlessOperatorName}, Knative Eventing, and the `KnativeKafka` custom resource are installed on your {product-title} cluster.
+
+.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>
+  name: example-kafka-broker
+spec:
+  config:
+    apiVersion: v1
+    kind: ConfigMap
+    name: kafka-broker-config <2>
+    namespace: knative-eventing
+----
+<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 default config map for Knative Kafka brokers. This config map is created when the Kafka broker functionality is enabled on the cluster by a cluster administrator.
+
+. Apply the Kafka-based broker YAML file:
++
+[source,terminal]
+----
+$ oc apply -f <filename>
+----

modules/serverless-kafka-event-delivery.adoc

@@ -3,7 +3,7 @@
 // * serverless/develop/serverless-kafka-developer.adoc
 
 [id="serverless-kafka-delivery-retries_{context}"]
-= Event delivery and retries
+= Kafka 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.