Broker and Trigger

Broker and Trigger are CRDs providing an event delivery mechanism that hides the details of event routing from the event producer and event consumer.

Broker

A Broker represents an ‘event mesh’. Events are sent to the Broker’s ingress and are then sent to any subscribers that are interested in that event. Once inside a Broker, all metadata other than the CloudEvent is stripped away (e.g. unless set as a CloudEvent attribute, there is no concept of how this event entered the Broker).

There can be different classes of Brokers providing different kinds of semantics around durability of events, performance, etc. The Broker that is part of the Knative Eventing repo is used for these examples, it uses Knative Channels for delivering events. You can read more details about MT Channel Based Broker. Simple example showing a Broker where the configuration is specified in a ConfigMap config-br-default-channel, which uses InMemoryChannel:

Example:

  1. apiVersion: eventing.knative.dev/v1
  2. kind: Broker
  3. metadata:
  4.   annotations:
  5.     eventing.knative.dev/broker.class: MTChannelBasedBroker
  6.   name: default
  7. spec:
  8.   # Configuration specific to this broker.
  9.   config:
  10.     apiVersion: v1
  11.     kind: ConfigMap
  12.     name: config-br-default-channel
  13.     namespace: knative-eventing

More complex example, showing the same Broker as above but with failed events being delivered to Knative Service called dlq-service

  1. apiVersion: eventing.knative.dev/v1
  2. kind: Broker
  3. metadata:
  4.   annotations:
  5.     eventing.knative.dev/broker.class: MTChannelBasedBroker
  6.   name: default
  7. spec:
  8.   # Configuration specific to this broker.
  9.   config:
  10.     apiVersion: v1
  11.     kind: ConfigMap
  12.     name: config-br-default-channel
  13.     namespace: knative-eventing
  14.   # Where to deliver Events that failed to be processed.
  15.   delivery:
  16.     deadLetterSink:
  17.       ref:
  18.         apiVersion: serving.knative.dev/v1
  19.         kind: Service
  20.         name: dlq-service

Creating a broker using defaults

Knative Eventing provides a ConfigMap which by default lives in knative-eventing namespace and is called default-br-config. Out of the box it comes configured to create MT Channel Based Brokers. If you are using a different Broker implementation, you should modify the ConfigMap accordingly. You can read more details on how to use default-br-config config map

  1. apiVersion: v1
  2. kind: ConfigMap
  3. metadata:
  4.   name: config-br-defaults
  5.   namespace: knative-eventing
  6.   labels:
  7.     eventing.knative.dev/release: v0.16.0
  8. data:
  9.   # Configuration for defaulting channels that do not specify CRD implementations.
  10.   default-br-config: |
  11.     clusterDefault:
  12.       brokerClass: MTChannelBasedBroker
  13.       apiVersion: v1
  14.       kind: ConfigMap
  15.       name: config-br-default-channel
  16.       namespace: knative-eventing

With this ConfigMap, any Broker created will be configured to use MTChannelBasedBroker and the Broker.Spec.Config will be configured as specified in the clusterDefault configuration. So, example below will create a Broker called default in default namespace and uses MTChannelBasedBroker as implementation.

  1. kubectl create -f - <<EOF
  2. apiVersion: eventing.knative.dev/v1
  3. kind: Broker
  4. metadata:
  5.   name: default
  6.   namespace: default
  7. EOF

The defaults specified in the defaults-br-config will result in a following Broker being created.

  1. apiVersion: eventing.knative.dev/v1
  2. kind: Broker
  3. metadata:
  4.   annotations:
  5.     eventing.knative.dev/broker.class: MTChannelBasedBroker
  6.   name: default
  7.   namespace: default
  8. spec:
  9.   config:
  10.     apiVersion: v1
  11.     kind: ConfigMap
  12.     name: config-br-default-channel
  13.     namespace: knative-eventing

To see the created Broker, you can get it like this:

  1. kubectl get brokers default
  1. kubectl get brokers default
  2. NAME      READY   REASON   URL                                                                        AGE
  3. default   True             http://broker-ingress.knative-eventing.svc.cluster.local/default/default   56m

Note the URL field where you can send CloudEvents andthen use Triggers to route them to your functions.

To delete the Broker:

  1. kubectl delete broker default

Trigger

A Trigger represents a desire to subscribe to events from a specific Broker.

Simple example which will receive all the events from the given (default) broker and deliver them to Knative Serving service my-service:

  1. kubectl create -f - <<EOF
  2. apiVersion: eventing.knative.dev/v1
  3. kind: Trigger
  4. metadata:
  5.   name: my-service-trigger
  6. spec:
  7.   broker: default
  8.   subscriber:
  9.     ref:
  10.       apiVersion: serving.knative.dev/v1
  11.       kind: Service
  12.       name: my-service
  13. EOF

Trigger Filtering

Exact match filtering on any number of CloudEvents attributes as well as extensions are supported. If your filter sets multiple attributes, an event must have all of the attributes for the Trigger to filter it. Note that we only support exact matching on string values.

Example:

  1. kubectl create -f - <<EOF
  2. apiVersion: eventing.knative.dev/v1
  3. kind: Trigger
  4. metadata:
  5.   name: my-service-trigger
  6. spec:
  7.   broker: default
  8.   filter:
  9.     attributes:
  10.       type: dev.knative.foo.bar
  11.       myextension: my-extension-value
  12.   subscriber:
  13.     ref:
  14.       apiVersion: serving.knative.dev/v1
  15.       kind: Service
  16.       name: my-service
  17. EOF

The example above filters events from the default Broker that are of type dev.knative.foo.bar AND have the extension myextension with the value my-extension-value.

Complete end-to-end example

Broker setup

We assume that you have installed a Broker in namespace default. If you haven’t done that yet, install it from here.

Subscriber

Create a function to receive events. This document uses a Knative Service, but it could be anything that is Callable.

  1. kubectl create -f - <<EOF
  2. apiVersion: serving.knative.dev/v1
  3. kind: Service
  4. metadata:
  5.   name: my-service
  6.   namespace: default
  7. spec:
  8.   template:
  9.     spec:
  10.       containers:
  11.       -  # This corresponds to
  12.          # https://github.com/knative/eventing-contrib/tree/master/cmd/event_display
  13.          image: gcr.io/knative-releases/knative.dev/eventing-contrib/cmd/event_display
  14. EOF

Trigger

Create a Trigger that sends only events of a particular type to the subscriber created above (my-service). For this example, we use Ping Source, and it emits events types dev.knative.sources.ping.

  1. kubectl create -f - <<EOF
  2. apiVersion: eventing.knative.dev/v1
  3. kind: Trigger
  4. metadata:
  5.   name: my-service-trigger
  6.   namespace: default
  7. spec:
  8.   broker: default
  9.   filter:
  10.     attributes:
  11.       type: dev.knative.sources.ping
  12.   subscriber:
  13.     ref:
  14.       apiVersion: serving.knative.dev/v1
  15.       kind: Service
  16.       name: my-service
  17. EOF

Emitting Events using Ping Source

Knative Eventing comes with a Ping Source which emits an event on a configured schedule. For this we’ll configure it to emit events once a minute, saying, yes, you guessed it Hello World!.

  1. kubectl create -f - <<EOF
  2. apiVersion: sources.knative.dev/v1alpha2
  3. kind: PingSource
  4. metadata:
  5.   name: test-ping-source
  6. spec:
  7.   schedule: "*/1 * * * *"
  8.   jsonData: '{"message": "Hello world!"}'
  9.   sink:
  10.     ref:
  11.       # Deliver events to Broker.
  12.       apiVersion: eventing.knative.dev/v1
  13.       kind: Broker
  14.       name: default
  15. EOF

Table of contents