# Knative Eventing Sugar Controller

Knative Eventing Sugar Controller will react to special labels and annotations
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
longer needed.

## Installing

The following command installs the Eventing Sugar Controller:

```bash
kubectl apply --filename {{ artifact( repo="eventing", file="eventing-sugar-controller.yaml") }}
```

## Automatic Broker Creation

One way to create a Broker is to manually apply a resource to a cluster using
the default settings:

1. Copy the following YAML into a file:

    ```yaml
    apiVersion: eventing.knative.dev/v1
    kind: Broker
    metadata:
      name: default
      namespace: default
    ```

1. Apply the YAML file by running the command:

    ```bash
    kubectl apply -f <filename>.yaml
    ```
    Where `<filename>` is the name of the file you created in the previous step.

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:

- When a Namespace is labeled with `eventing.knative.dev/injection=enabled`, the
  sugar controller will create a default Broker named "default" in that
  namespace.
- When a Trigger is annotated with `eventing.knative.dev/injection=enabled`, the
  controller will create a Broker named by that Trigger in the Trigger's
  Namespace.

When a Broker is deleted and the mentioned labels or annotations are in use, the
Sugar Controller will automatically recreate a default Broker.

### Namespace Examples

Creating a "default" Broker when creating a Namespace:

1. Copy the following YAML into a file:

    ```yaml
    apiVersion: v1
    kind: Namespace
    metadata:
      name: example
      labels:
        eventing.knative.dev/injection: enabled
    ```

1. Apply the YAML file by running the command:

    ```bash
    kubectl apply -f <filename>.yaml
    ```
    Where `<filename>` is the name of the file you created in the previous step.

To automatically create a Broker after a namespace exists, label the Namespace:

```bash
kubectl label namespace default eventing.knative.dev/injection=enabled
```

If the Broker named "default" already exists in the Namespace, the Sugar
Controller will do nothing.

### Trigger Example

Create a "default" Broker in the Trigger's Namespace when creating a Trigger:

```bash
kubectl apply -f - << EOF
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
  name: hello-sugar
  namespace: hello
  annotations:
    eventing.knative.dev/injection: enabled
spec:
  broker: default
  subscriber:
    ref:
      apiVersion: v1
      kind: Service
      name: event-display
EOF
```

This will make a Broker called "default" in the Namespace "hello", and attempt to send events to the "event-display" service.

If the Broker named "default" already exists in the Namespace, the Sugar Controller will do nothing and the Trigger will not own the existing Broker.
