Broker

Knative provides a multi-tenant, channel-based broker implementation that uses channels for event routing.

Before you can use the Knative Channel-based Broker, you must install a channel provider, such as InMemoryChannel, Kafka or Nats.

NOTE: InMemoryChannel channels are for development use only and must not be used in a production deployment.

For more information on which channels are available and how to install them, see the list of available channels.

How it works

When an Event is sent to the Broker, all request metadata other than the CloudEvent data and context attributes is stripped away. Unless the information existed as a CloudEvent attribute, no information is retained about how this Event entered the Broker.

Once an Event has entered the Broker, it can be forwarded to event Channels by using Triggers. This event delivery mechanism hides details of event routing from the event producer and event consumer.

Triggers register a subscriber’s interest in a particular class of events, so that the subscriber’s event sink will receive events that match the Trigger’s filter.

Default Broker configuration

Knative Eventing provides a config-br-defaults ConfigMap, which lives in the knative-eventing namespace, and provides default configuration settings to enable the creation of Brokers and Channels by using defaults. For more information, see the config-br-defaults ConfigMap documentation.

Create a Broker using the default settings:

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

Configuring broker classes

You can configure Knative Eventing so that when you create a broker, it uses a different type of broker than the default Knative channel-based broker. To configure a different broker type, or class, you must modify the eventing.knative.dev/broker.class annotation and spec.config for the Broker object. MTChannelBasedBroker is the broker class default.

Procedure

  1. Modify the eventing.knative.dev/broker.class annotation. Replace MTChannelBasedBroker with the class type you want to use:
  1. kind: Broker
  2. metadata:
  3.   annotations:
  4.     eventing.knative.dev/broker.class: MTChannelBasedBroker
  1. Configure the spec.config with the details of the ConfigMap that defines the backing channel for the broker class:
  1. kind: Broker
  2. spec:
  3.   config:
  4.     apiVersion: v1
  5.     kind: ConfigMap
  6.     name: config-br-default-channel
  7.     namespace: knative-eventing

A full example combined into a fully specified resource could look like this:

  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

Next steps

After you have created a Broker, you can complete the following tasks to finish setting up event delivery.

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/main/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/v1beta2
  3. kind: PingSource
  4. metadata:
  5.   name: test-ping-source
  6. spec:
  7.   schedule: "*/1 * * * *"
  8.   contentType: "application/json"
  9.   data: '{"message": "Hello world!"}'
  10.   sink:
  11.     ref:
  12.       # Deliver events to Broker.
  13.       apiVersion: eventing.knative.dev/v1
  14.       kind: Broker
  15.       name: default
  16. EOF

The following example is more complex, and demonstrates the use of deadLetterSink configuration to send failed events 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

See also: Delivery Parameters