Event registry

Event registry

Knative Eventing defines an EventType object to make it easier for consumers to discover the types of events they can consume from Brokers.

The event registry maintains a catalog of event types that each Broker can consume. The event types stored in the registry contain all required information for a consumer to create a Trigger without resorting to some other out-of-band mechanism.

This topic provides information about how you can populate the event registry, how to discover events using the registry, and how to leverage that information to subscribe to events of interest.

Before you begin

It’s recommended that you have a basic understanding of the following:

Brokers
Triggers
The CloudEvents spec, particularly the Context Attributes section
Event sources

About EventType objects

EventType objects represent a type of event that can be consumed from a Broker, such as Kafka messages or GitHub pull requests. EventType objects are used to populate the event registry and persist event type information in the cluster datastore.

The following is an example EventType YAML that omits irrelevant fields:

apiVersion: eventing.knative.dev/v1beta1
kind: EventType
metadata:
  name: dev.knative.source.github.push-34cnb
  namespace: default
  labels:
    eventing.knative.dev/sourceName: github-sample
spec:
  type: dev.knative.source.github.push
  source: https://github.com/knative/eventing
  schema:
  description:
  broker: default
status:
  conditions:
    - status: "True"
      type: BrokerExists
    - status: "True"
      type: BrokerReady
    - status: "True"
      type: Ready

For the full specification for an EventType object, see the EventType API reference.

The metadata.name field is advisory, that is, non-authoritative. It is typically generated using generateName to avoid naming collisions. metadata.name is not needed when you create Triggers.

For consumers, the fields that matter the most are spec and status. This is because these fields provide the information you need to create Triggers, which is the source and type of event and whether the Broker is ready to receive events.

The following table has more information about the spec and status fields of EventType objects:

Field	Description	Required or optional
`spec.type`	Refers to the CloudEvent type as it enters into the event mesh. Event consumers can create Triggers filtering on this attribute. This field is authoritative.	Required
`spec.source`	Refers to the CloudEvent source as it enters into the event mesh. Event consumers can create Triggers filtering on this attribute.	Required
`spec.schema`	A valid URI with the EventType schema such as a JSON schema or a protobuf schema.	Optional
`spec.description`	A string describing what the EventType is about.	Optional
`spec.broker`	Refers to the Broker that can provide the EventType.	Required
`status`	Tells consumers, or cluster operators, whether the EventType is ready to be consumed or not. The readiness is based on the Broker being ready.	Optional

Populate the registry with events

You can populate the registry with EventType objects manually or automatically. Automatic registration can be the easier method, but it only supports a subset of event sources.

Manual registration

For manual registration, the cluster configurator applies EventTypes YAML files the same as with any other Kubernetes resource.

To apply EventTypes YAML files manually:

Create an EventType YAML file. For information about the required fields, see About EventType objects.
Apply the YAML by running the command:
```
kubectl apply -f <event-type.yaml>
```

Automatic registration

Because manual registration might be tedious and error-prone, Knative also supports registering EventTypes automatically. EventTypes are created automatically when an event source is instantiated.

Support for automatic registration

Knative supports automatic registration of EventTypes for the following event sources:

CronJobSource
ApiServerSource
GithubSource
GcpPubSubSource
KafkaSource
AwsSqsSource

Knative only supports automatic creation of EventTypes for sources that have a Broker as their sink.

Procedure for automatic registration

To register EventTypes automatically, apply your event source YAML file by running the command:
```
kubectl apply -f <event-source.yaml>
```

After your event source is instantiated, EventTypes are added to the registry.

Example: Automatic registration using KafkaSource

Given the following KafkaSource sample to populate the registry:

apiVersion: sources.knative.dev/v1beta1
kind: KafkaSource
metadata:
  name: kafka-sample
  namespace: default
spec:
  bootstrapServers:
   - my-cluster-kafka-bootstrap.kafka:9092
  topics:
   - knative-demo
   - news
  sink:
    apiVersion: eventing.knative.dev/v1
    kind: Broker
    name: default

The topics field in the above example is used to generate the EventType source field.

After running kubectl apply using the above YAML, the KafkaSource kafka-source-sample is instantiated, and two EventTypes are added to the registry because there are two topics.

Discover events using the registry

Using the registry, you can discover the different types of events that Broker event meshes can consume.

To see a list of event types in the registry that are available to subscribe to, run the command:

kubectl get eventtypes -n <namespace>

Example output using the default namespace in a testing cluster:

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

This example output shows seven different EventType objects in the registry of the default namespace. It assumes that the event sources emitting the events reference a Broker as their sink.

View the YAML for an EventType object

To see the YAML for an EventType object, run the command:
```
kubectl get eventtype <name> -o yaml
```
Where <name> is the name of an EventType object and can be found in the NAME column of the registry output. For example, dev.knative.source.github.push-34cnb.

For an example EventType YAML, see About EventType objects earlier on this page.

About subscribing to events

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

Here are a some example Triggers that subscribe to events using exact matching on type or source, based on the registry output mentioned earlier:

Subscribes to GitHub pushes from any source:

apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
 name: push-trigger
 namespace: default
spec:
 broker: default
 filter:
   attributes:
     type: dev.knative.source.github.push
 subscriber:
   ref:
     apiVersion: serving.knative.dev/v1
     kind: Service
     name: push-service

Note

As the example registry output mentioned, only two sources, the knative/eventing and knative/serving GitHub repositories, exist for that particular type of event. If later on new sources are registered for GitHub pushes, this Trigger is able to consume them.

Subscribes to GitHub pull requests from the knative/eventing GitHub repository:

apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
 name: gh-knative-eventing-pull-trigger
 namespace: default
spec:
 broker: default
 filter:
   attributes:
     type: dev.knative.source.github.pull_request
     source: https://github.com/knative/eventing
 subscriber:
   ref:
     apiVersion: serving.knative.dev/v1
     kind: Service
     name: gh-knative-eventing-pull-service

Subscribes to Kafka messages sent to the knative-demo topic:

apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
 name: kafka-knative-demo-trigger
 namespace: default
spec:
 broker: default
 filter:
   attributes:
     type: dev.knative.kafka.event
     source: /apis/v1/namespaces/default/kafkasources/kafka-sample#knative-demo
 subscriber:
   ref:
     apiVersion: serving.knative.dev/v1
     kind: Service
     name: kafka-knative-demo-service

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

apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
 name: gcp-pubsub-knative-testing-trigger
 namespace: default
spec:
 broker: dev
 filter:
   attributes:
     source: //pubsub.googleapis.com/knative/topics/testing
 subscriber:
   ref:
     apiVersion: serving.knative.dev/v1
     kind: Service
     name: gcp-pubsub-knative-testing-service