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 or Channels.

The event registry maintains a catalog of event types that each Broker or Channel 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.

About EventType objects¶

EventType objects represent a type of event that can be consumed from a Broker or Channel, such as Apache 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/v1beta2
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:
  reference:
    apiVersion: eventing.knative.dev/v1
    kind: Broker
    name: default
status:
  conditions:
    - status: "True"
      type: ReferenceExists
    - 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 Reference is present to receive events.

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

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:

1. Create an EventType YAML file. For information about the required fields, see About EventType objects.

2. 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 supports automatic creation of EventTypes for sources, that are compliant to the Sources Duck type.

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.

View all event types you can subscribe to¶

• 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
  

  Note

  The example registry output mentioned earlier lists this Broker's readiness as false. This Trigger's subscriber cannot consume events until the Broker becomes ready.

Next steps¶

Knative code samples is a useful resource to better understand some of the event sources. Remember, you must point the sources to a Broker if you want automatic registration of EventTypes in the registry.