Event registry

Overview

The Event Registry maintains a catalog of the event types that can be consumed from the different Brokers. It introduces a new EventType CRD in order to persist the event type’s information in the cluster’s data store.

Before you begin

  1. Read about the Broker and Trigger objects.
  2. Be familiar with the CloudEvents spec, particularly the Context Attributes section.
  3. Be familiar with the Eventing sources.

Discovering events with the registry

Using the registry, you can discover the different types of events you can consume from the Brokers’ event meshes. The registry is designed for use with the Broker/Trigger model and aims to help you create Triggers.

To see the event types available to subscribe to, enter the following command:

kubectl get eventtypes -n <namespace>

Below, we show an example output of executing the above command using the default namespace in a testing cluster. We will address the question of how this registry was populated in a later section.

  1. NAME                                         TYPE                                    SOURCE                                                               SCHEMA        BROKER     DESCRIPTION     READY     REASON
  2. dev.knative.source.github.push-34cnb         dev.knative.source.github.push          https://github.com/knative/eventing                                                default                    True
  3. dev.knative.source.github.push-44svn         dev.knative.source.github.push          https://github.com/knative/serving                                                 default                    True
  4. dev.knative.source.github.pullrequest-86jhv  dev.knative.source.github.pull_request  https://github.com/knative/eventing                                                default                    True
  5. dev.knative.source.github.pullrequest-97shf  dev.knative.source.github.pull_request  https://github.com/knative/serving                                                 default                    True
  6. dev.knative.kafka.event-cjvcr                dev.knative.kafka.event                 /apis/v1/namespaces/default/kafkasources/kafka-sample#news                         default                    True
  7. dev.knative.kafka.event-tdt48                dev.knative.kafka.event                 /apis/v1/namespaces/default/kafkasources/kafka-sample#knative-demo                 default                    True
  8. google.pubsub.topic.publish-hrxhh            google.pubsub.topic.publish             //pubsub.googleapis.com/knative/topics/testing                                     dev                        False     BrokerIsNotReady

We can see that there are seven different EventTypes in the registry of the default namespace. Let’s pick the first one and see what the EventType yaml looks like:

kubectl get eventtype dev.knative.source.github.push-34cnb -o yaml

Omitting irrelevant fields:

  1. apiVersion: eventing.knative.dev/v1
  2. kind: EventType
  3. metadata:
  4.   name: dev.knative.source.github.push-34cnb
  5.   namespace: default
  6.   generateName: dev.knative.source.github.push-
  7. spec:
  8.   type: dev.knative.source.github.push
  9.   source: https://github.com/knative/eventing
  10.   schema:
  11.   description:
  12.   broker: default
  13. status:
  14.   conditions:
  15.     - status: "True"
  16.       type: BrokerExists
  17.     - status: "True"
  18.       type: BrokerReady
  19.     - status: "True"
  20.       type: Ready

From a consumer standpoint, the fields that matter the most are the spec fields as well as the status.

The name is advisory (i.e., non-authoritative), and we typically generate it (generateName) to avoid naming collisions (e.g., two EventTypes listening to pull requests on two different Github repositories). As name nor generateName are needed for consumers to create Triggers, we defer their discussion for later on.

Regarding status, its main purpose it to tell consumers (or cluster operators) whether the EventType is ready for consumption or not. That readiness is based on the Broker being ready. We can see from the example output that the PubSub EventType is not ready, as its dev Broker isn’t.

Let’s talk in more details about the spec fields:

  • type: is authoritative. This refers to the CloudEvent type as it enters into the event mesh. It is mandatory. Event consumers can (and in most cases would) create Triggers filtering on this attribute.

  • source: refers to the CloudEvent source as it enters into the event mesh. It is mandatory. Event consumers can (and in most cases would) create Triggers filtering on this attribute.

  • schema: is a valid URI with the EventType schema. It may be a JSON schema, a protobuf schema, etc. It is optional.

  • description: is a string describing what the EventType is about. It is optional.

  • broker refers to the Broker that can provide the EventType. It is mandatory.

Subscribing to events

Now that you know what events can be consumed from the Brokers’ event meshes, you can create Triggers to subscribe to particular events.

Here are a few example Triggers that subscribe to events using exact matching on type and/or source, based on the above registry output:

  1. Subscribes to GitHub pushes from any source.

    1. apiVersion: eventing.knative.dev/v1
    2. kind: Trigger
    3. metadata:
    4.   name: push-trigger
    5.   namespace: default
    6. spec:
    7.   broker: default
    8.   filter:
    9.     attributes:
    10.       type: dev.knative.source.github.push
    11.   subscriber:
    12.     ref:
    13.       apiVersion: serving.knative.dev/v1
    14.       kind: Service
    15.       name: push-service

    As per the registry output above, only two sources exist for that particular type of event (knative’s eventing and serving repositories). If later on new sources are registered for GitHub pushes, this trigger will be able to consume them.

  2. Subscribes to GitHub pull requests from knative’s eventing repository.

    1. apiVersion: eventing.knative.dev/v1
    2. kind: Trigger
    3. metadata:
    4.   name: gh-knative-eventing-pull-trigger
    5.   namespace: default
    6. spec:
    7.   broker: default
    8.   filter:
    9.     attributes:
    10.       type: dev.knative.source.github.pull_request
    11.       source: https://github.com/knative/eventing
    12.   subscriber:
    13.     ref:
    14.       apiVersion: serving.knative.dev/v1
    15.       kind: Service
    16.       name: gh-knative-eventing-pull-service

  3. Subscribes to Kafka messages sent to the knative-demo topic

    1. apiVersion: eventing.knative.dev/v1
    2. kind: Trigger
    3. metadata:
    4.   name: kafka-knative-demo-trigger
    5.   namespace: default
    6. spec:
    7.   broker: default
    8.   filter:
    9.     attributes:
    10.       type: dev.knative.kafka.event
    11.       source: /apis/v1/namespaces/default/kafkasources/kafka-sample#knative-demo
    12.   subscriber:
    13.     ref:
    14.       apiVersion: serving.knative.dev/v1
    15.       kind: Service
    16.       name: kafka-knative-demo-service

  4. Subscribes to PubSub messages from GCP’s knative project sent to the testing topic

    1. apiVersion: eventing.knative.dev/v1
    2. kind: Trigger
    3. metadata:
    4.   name: gcp-pubsub-knative-testing-trigger
    5.   namespace: default
    6. spec:
    7.   broker: dev
    8.   filter:
    9.     attributes:
    10.       source: //pubsub.googleapis.com/knative/topics/testing
    11.   subscriber:
    12.     ref:
    13.       apiVersion: serving.knative.dev/v1
    14.       kind: Service
    15.       name: gcp-pubsub-knative-testing-service

    Note that events won’t be able to be consumed by this Trigger’s subscriber until the Broker becomes ready.

Populating the registry

Now that we know how to discover events using the registry and how we can leverage that information to subscribe to events of interest, let’s move on to the next topic: How do we actually populate the registry in the first place?

  • Manual Registration

    In order to populate the registry, a cluster configurator can manually register the EventTypes. This means that the configurator can simply apply EventTypes yaml files, just as with any other Kubernetes resource:

    kubectl apply -f <event_type.yaml>

  • Automatic Registration

    As Manual Registration might be tedious and error-prone, we also support automatic registration of EventTypes. The creation of the EventTypes is done upon instantiation of an Event Source. We currently support automatic registration of EventTypes for the following Event Sources:

    • CronJobSource
    • ApiServerSource
    • GithubSource
    • GcpPubSubSource
    • KafkaSource
    • AwsSqsSource

    Let’s look at an example, in particular, the KafkaSource sample we used to populate the registry in our testing cluster. Below is what the yaml looks like.

    1. apiVersion: sources.knative.dev/v1beta1
    2. kind: KafkaSource
    3. metadata:
    4.   name: kafka-sample
    5.   namespace: default
    6. spec:
    7.   bootstrapServers:
    8.    - my-cluster-kafka-bootstrap.kafka:9092
    9.   topics:
    10.    - knative-demo
    11.     - news
    12.   sink:
    13.     apiVersion: eventing.knative.dev/v1
    14.     kind: Broker
    15.     name: default

    If you are interested in more information regarding configuration options of a KafkaSource, please refer to the KafKaSource sample.

    For this discussion, the relevant information from the yaml above are the sink and the topics. We observe that the sink is of kind Broker. We currently only support automatic creation of EventTypes for Sources instances that point to Brokers. Regarding topics, this is what we use to generate the EventTypes source field, which is equal to the CloudEvent source attribute.

    When you kubectl apply this yaml, the KafkaSource kafka-source-sample will be instantiated, and two EventTypes will be added to the registry (as there are two topics). You can see that in the registry example output from the previous sections.

What’s next

To get started, install Knative Eventing if you haven’t yet, and try experimenting with different Event Sources in your Knative cluster.

  1. Installing Knative in case you haven’t already done so.
  2. Getting started with eventing in case you haven’t read it.
  3. Knative code samples is a useful resource to better understand some of the Event Sources (remember to point them to a Broker if you want automatic registration of EventTypes in the registry).