Update Sugar Controller docs (#4925)

* Fixes #4896 Update Sugar Controller docs

- Update existing Sugar Controller page to reference LabelSelector Changes
- Add Configuration page for "config-sugar" ConfigMap

* Apply suggestions from code review

- fix code block identation
- remove incorrect comments in example config-sugar
- clarify default wording to be more clear

Co-authored-by: Carlos Santana <csantana23@gmail.com>

* Update config/nav.yml with Sugar Config entry

* update sugar/README with more practical example

* Update sugar

- fix code block rendering

Co-authored-by: Carlos Santana <csantana23@gmail.com>

config/nav.yml

@@ -206,6 +206,7 @@ nav:
           - Configure Broker defaults: eventing/configuration/broker-configuration.md
           - Configure Kafka Channel defaults: eventing/configuration/kafka-channel-configuration.md
           - Configure event source defaults: eventing/configuration/sources-configuration.md
+          - Configure Sugar Controller: eventing/configuration/sugar-configuration.md
       # Eventing - observability
       - Observability:
         - Collecting logs: eventing/observability/logging/collecting-logs.md

docs/eventing/configuration/sugar-configuration.md

@@ -0,0 +1,45 @@
+# Configure Sugar Controller
+
+This topic describes how to configure the Sugar Controller. You can configure the Sugar controller to create a Broker when a Namespace or Trigger is created with configured labels. See [Knative Eventing Sugar Controller](../sugar/README.md) for an example.
+
+
+The default `config-sugar` ConfigMap disables Sugar Controller, by setting `namespace-selector` and `trigger-selector` to an empty string.
+
+To enable the Sugar Controller
+
+* for Namespaces, the LabelSelector `namespace-selector` can be configured.
+* for Triggers, the LabelSelector `trigger-selector` can be configured.
+
+
+Sample configuration to enable Sugar Controller on selected Namespaces and Triggers
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+name: config-sugar
+namespace: knative-eventing
+labels:
+    eventing.knative.dev/release: devel
+data:
+  namespace-selector: |
+    matchExpressions:
+    - key: "eventing.knative.dev/injection"
+      operator: "In"
+      values: ["enabled"]
+
+  trigger-selector: |
+    matchExpressions:
+    - key: "eventing.knative.dev/injection"
+      operator: "In"
+      values: ["enabled"]
+```
+
+The Sugar Controller will only operate on Namespaces or Triggers with the label `eventing.knative.dev/injection: enabled`. This also emulates the legacy Sugar Controller behavior for Namespaces.
+
+
+You can edit this ConfigMap by running the command:
+
+```bash
+kubectl edit cm config-sugar -n knative-eventing
+```

docs/eventing/sugar/README.md

@@ -1,6 +1,6 @@
 # Knative Eventing Sugar Controller
 
-Knative Eventing Sugar Controller will react to special labels and annotations
+Knative Eventing Sugar Controller will react to configured labels
 to produce or control eventing resources in a cluster or namespace. This allows
 cluster operators and developers to focus on creating fewer resources, and the
 underlying eventing infrastructure is created on-demand, and cleaned up when no
@@ -8,11 +8,8 @@ longer needed.
 
 ## Installing
 
-The following command installs the Eventing Sugar Controller:
+The Sugar Controller is `disabled` by default and can be enabled by configuring `config-sugar` ConfigMap.
-
+See below for a simple example and [Configure Sugar Controller](../configuration/sugar-configuration.md) for more details.
-```bash
-kubectl apply --filename {{ artifact( repo="eventing", file="eventing-sugar-controller.yaml") }}
-```
 
 ## Automatic Broker Creation
 
@@ -38,16 +35,35 @@ the default settings:
 
 There might be cases where automated Broker creation is desirable, such as on
 namespace creation, or on Trigger creation. The Sugar controller enables those
-use-cases:
+use-cases. The following sample configuration of the `sugar-config` ConfigMap
+enables Sugar Controller for select Namespaces & all Triggers.
 
-- When a Namespace is labeled with `eventing.knative.dev/injection=enabled`, the
+```yaml
-  sugar controller will create a default Broker named "default" in that
+apiVersion: v1
+kind: ConfigMap
+metadata:
+name: config-sugar
+namespace: knative-eventing
+labels:
+    eventing.knative.dev/release: devel
+data:
+  # Specify a label selector to selectively apply sugaring to certain namespaces
+  namespace-selector: |
+    matchExpressions:
+    - key: "my.custom.injection.key"
+      operator: "In"
+      values: ["enabled"]
+  # Use an empty object to enable for all triggers
+  trigger-selector: |
+    {}
+```
+
+- When a Namespace is created with label `my.custom.injection.key: enabled` , the Sugar controller will create a Broker named "default" in that
   namespace.
-- When a Trigger is annotated with `eventing.knative.dev/injection=enabled`, the
+- When a Trigger is created, the Sugar controller will create a Broker named "default" in the
-  controller will create a Broker named by that Trigger in the Trigger's
+  Trigger's namespace.
-  Namespace.
 
-When a Broker is deleted and the mentioned labels or annotations are in use, the
+When a Broker is deleted and but the referenced label selectors are in use, the
 Sugar Controller will automatically recreate a default Broker.
 
 ### Namespace Examples
@@ -62,7 +78,7 @@ Creating a "default" Broker when creating a Namespace:
     metadata:
       name: example
       labels:
-        eventing.knative.dev/injection: enabled
+        my.custom.injection.key: enabled
     ```
 
 1. Apply the YAML file by running the command:
@@ -75,7 +91,7 @@ Creating a "default" Broker when creating a Namespace:
 To automatically create a Broker after a namespace exists, label the Namespace:
 
 ```bash
-kubectl label namespace default eventing.knative.dev/injection=enabled
+kubectl label namespace default my.custom.injection.key=enabled
 ```
 
 If the Broker named "default" already exists in the Namespace, the Sugar
@@ -92,8 +108,6 @@ kind: Trigger
 metadata:
   name: hello-sugar
   namespace: hello
-  annotations:
-    eventing.knative.dev/injection: enabled
 spec:
   broker: default
   subscriber: