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.

Note

Before using the event registry, it is recommended that you have a basic understanding of Brokers, Triggers, Event Sources, and the CloudEvents spec (particularly the Context Attributes section).

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:

  1. apiVersion: eventing.knative.dev/v1beta2
  2. kind: EventType
  3. metadata:
  4. name: dev.knative.source.github.push-34cnb
  5. namespace: default
  6. labels:
  7. eventing.knative.dev/sourceName: github-sample
  8. spec:
  9. type: dev.knative.source.github.push
  10. source: https://github.com/knative/eventing
  11. schema:
  12. description:
  13. reference:
  14. apiVersion: eventing.knative.dev/v1
  15. kind: Broker
  16. name: default
  17. status:
  18. conditions:
  19. - status: "True"
  20. type: ReferenceExists
  21. - status: "True"
  22. 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:

FieldDescriptionRequired or optional
spec.typeRefers 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.sourceRefers to the CloudEvent source as it enters into the event mesh. Event consumers can create Triggers filtering on this attribute.Required
spec.schemaA valid URI with the EventType schema such as a JSON schema or a protobuf schema.Optional
spec.descriptionA string describing what the EventType is about.Optional
spec.referenceRefers to the KResource that can provide the EventType.Required
statusTells consumers, or cluster operators, whether the EventType is ready to be consumed or not. The readiness is based on the KReference being present.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:

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

  2. Apply the YAML by running the command:

    1. 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:

    1. 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:

  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

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.

Note

With the feature for EventType auto creation you can see more event types in the registry. Learn here how to enable this feature.

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:

    1. kubectl get eventtypes -n <namespace>

    Example output using the default namespace in a testing cluster:

    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

    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:

    1. 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:

    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

    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:

    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
  • 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
  • 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

    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.