Merge pull request #19667 from abrennan89/broker

Added details about creating brokers for Serverless GA

Author: adellape

_topic_map.yml

@@ -1234,15 +1234,15 @@ Topics:
     File: odo-architecture
   - Name: Installing odo
     File: installing-odo
-  - Name: Using odo in a restricted environment  
+  - Name: Using odo in a restricted environment
     Dir: using_odo_in_a_restricted_environment
-    Topics: 
+    Topics:
     - Name: About odo in a restricted environment
-      File: about-odo-in-a-restricted-environment  
+      File: about-odo-in-a-restricted-environment
     - Name: Pushing the odo init image to the restricted cluster registry
       File: pushing-the-odo-init-image-to-the-restricted-cluster-registry
     - Name: Creating and deploying a component to the disconnected cluster
-      File: creating-and-deploying-a-component-to-the-disconnected-cluster        
+      File: creating-and-deploying-a-component-to-the-disconnected-cluster
   - Name: Creating a single-component application with odo
     File: creating-a-single-component-application-with-odo
   - Name: Creating a multicomponent application with odo
@@ -1503,6 +1503,7 @@ Topics:
   File: installing-openshift-serverless
 - Name: Using Knative Client
   File: knative-client
+### Serving
 - Name: Knative Serving
   Dir: knative_serving
   Topics:
@@ -1520,13 +1521,16 @@ Topics:
     File: cluster-logging-serverless
   - Name: Splitting traffic between revisions
     File: splitting-traffic-between-revisions
+### Eventing
 ### - Name: Knative Eventing
 ###  Dir: knative_eventing
 ###  Topics:
 ###  - Name: How Knative Eventing works
 ###    File: serverless-knative-eventing
 ###  - Name: Using Knative Eventing sources
 ###    File: serverless-kn-source
+###  - Name: Using the broker
+###    File: serverless-using-brokers
 ### Monitoring
 - Name: Monitoring OpenShift Serverless components
   File: monitoring-serverless

modules/serverless-creating-broker-admin.adoc

@@ -0,0 +1,38 @@
+// Module included in the following assemblies:
+//
+// * serverless/knative_eventing/serverless-using-brokers.adoc
+
+[id="serverless-creating-broker-admin_{context}"]
+= Creating a broker for your namespace automatically using namespace annotation
+
+If you have cluster administrator permissions, you can create a broker automatically by annotating a namespace.
+
+.Prerequisites
+* Knative Eventing installed.
+* Cluster administrator permissions for {product-title}.
+
+.Procedure
+
+. Annotate your namespace:
++
+----
+$ oc label namespace default knative-eventing-injection=enabled <1>
+$ oc -n default get broker default
+----
+<1>  Replace `default` with the desired namespace.
++
+The line shown in this example will automatically create a broker named `default` in the `default` namespace.
+
+[id="serverless-deleting-broker-admin_{context}"]
+= Deleting a broker that was created using namespace annotation
+
+. Delete the injected broker from the selected namespace (in this example, the `default` namespace):
++
+----
+$ oc -n default delete broker default
+----
+
+[NOTE]
+====
+Brokers created due to annotation will not be removed if you remove the annotation. You must manually delete them.
+====

modules/serverless-creating-broker.adoc

@@ -0,0 +1,43 @@
+// Module included in the following assemblies:
+//
+// * serverless/knative_eventing/serverless-using-brokers.adoc
+
+[id="serverless-creating-broker_{context}"]
+= Creating a broker
+
+To create a broker, you must create a `ServiceAccount` for each namespace and give that `ServiceAccount` the required RBAC permissions.
+
+.Prerequisites
+* Knative Eventing installed, which includes the `ClusterRole`.
+
+.Procedure
+. Create the `ServiceAccount` objects:
++
+----
+$ oc -n default create serviceaccount eventing-broker-ingress
+$ oc -n default create serviceaccount eventing-broker-filter
+----
+
+. Give those objects RBAC permissions:
++
+----
+$ oc -n default create rolebinding eventing-broker-ingress \
+  --clusterrole=eventing-broker-ingress \
+  --serviceaccount=default:eventing-broker-ingress
+$ oc -n default create rolebinding eventing-broker-filter \
+  --clusterrole=eventing-broker-filter \
+  --serviceaccount=default:eventing-broker-filter
+----
+
+. Create the broker:
++
+----
+cat << EOF | oc apply -f -
+apiVersion: eventing.knative.dev/v1beta1
+kind: Broker
+metadata:
+  namespace: default
+  name: default <1>
+EOF
+----
+<1> This example uses the name `default`, but you can replace this with any other valid name.

serverless/knative_eventing/serverless-using-brokers.adoc

@@ -0,0 +1,12 @@
+[id="serverless-using-brokers"]
+= Using brokers with Knative Eventing
+include::modules/common-attributes.adoc[]
+include::modules/serverless-document-attributes.adoc[]
+:context: serverless-using-brokers
+
+toc::[]
+
+Knative Eventing uses the `default` broker unless otherwise specified. However, this section describes how you can create your own broker.
+
+include::modules/serverless-creating-broker.adoc[leveloffset=+1]
+include::modules/serverless-creating-broker-admin.adoc[leveloffset=+1]