knative
/
docs
mirror of https://github.com/knative/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Edit event registry docs (#4336) 

* Edit event registry docs

* Update the nav to match topic title

* Update docs/eventing/event-registry.md

Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>

* Apply suggestions from code review

Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>

* Update docs/eventing/event-registry.md

Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>

* Fix repo mentions

Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>
This commit is contained in:
Samia Nneji 2021-11-04 17:48:01 +00:00 committed by GitHub
parent 2cc9223484
commit 88b9c993ab
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 206 additions and 180 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
config/nav.yml
View File

@ -183,7 +183,7 @@ nav:
- Sugar Controller: eventing/sugar/README.md - Sugar Controller: eventing/sugar/README.md
- Brokers: - Brokers:
- Overview: eventing/broker/README.md - Overview: eventing/broker/README.md
- Event registry: eventing/event-registry.md # does this make sense here since it mentions being used with brokers and triggers? - Using the Event registry: eventing/event-registry.md # does this make sense here since it mentions being used with brokers and triggers?
- Creating a broker: eventing/broker/create-mtbroker.md - Creating a broker: eventing/broker/create-mtbroker.md
- Triggers: eventing/broker/triggers/README.md - Triggers: eventing/broker/triggers/README.md
- Broker configuration example: eventing/broker/example-mtbroker.md - Broker configuration example: eventing/broker/example-mtbroker.md

384
docs/eventing/event-registry.md
View File

@ -1,59 +1,33 @@
# Event registry # Using the event registry
## Overview The event registry maintains a catalog of event types that each Broker can consume.
It is designed for use with the Broker and Trigger model, and provides information
to help you create Triggers.
The event registry maintains a catalog of event types that can be consumed This topic introduces the EventType custom resource and provides information about
from different brokers. It introduces the EventType custom resource in order to persist the event how to populate the event registry, how to discover events using the registry,
type information in the cluster data store. and how to leverage that information to subscribe to events of interest.
## Before you begin ## Before you begin
1. Read about the [Broker](broker/README.md) and [Trigger](broker/triggers/README.md) objects. It's recommended that you have a basic understanding of the following:
1. Be familiar with the
[CloudEvents spec](https://github.com/cloudevents/spec/blob/master/spec.md), - [Brokers](broker/README.md)
- [Triggers](broker/triggers/README.md)
- The [CloudEvents spec](https://github.com/cloudevents/spec/blob/master/spec.md),
particularly the particularly the
[Context Attributes](https://github.com/cloudevents/spec/blob/master/spec.md#context-attributes) [Context Attributes](https://github.com/cloudevents/spec/blob/master/spec.md#context-attributes)
section. section
1. Be familiar with [event sources](../eventing/sources/README.md). - [Event sources](sources/README.md)
## Discovering events with the registry ## About EventType objects
Using the registry, you can discover different types of events that can be consumed by broker event meshes. The registry is designed for use with EventType objects represent a type of event that can be consumed from a Broker,
the broker and trigger model, and aims to help you create triggers. 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.
To see event types in the registry that are available to subscribe to, enter the following command: The following is an example EventType YAML that omits irrelevant fields:
```
kubectl get eventtypes -n <namespace>
```
The following example shows the output of executing the `kubectl get eventtypes` command using the
`default` namespace in a testing cluster. We will address the question of how
this registry was populated in a later section.
```
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
```
**NOTE:** This assumes that the event sources emitting the events reference a broker as their sink.
There are seven different EventType objects in the registry of the
`default` namespace.
Use the following command to see an example of what the YAML for an EventType object looks like:
```
kubectl get eventtype dev.knative.source.github.push-34cnb -o yaml
```
Omitting irrelevant fields:
```yaml ```yaml
apiVersion: eventing.knative.dev/v1beta1 apiVersion: eventing.knative.dev/v1beta1
@ -79,55 +53,174 @@ status:
type: Ready type: Ready
``` ```
From a consumer standpoint, the fields that matter the most are the `spec` For the full specification for an EventType object, see the
fields as well as the `status`. [EventType API reference](../reference/api/eventing-api.md#eventing.knative.dev/v1beta1.EventType).
The `name` is advisory (i.e., non-authoritative), and we typically generate it The `metadata.name` field is advisory, that is, non-authoritative.
(`generateName`) to avoid naming collisions (e.g., two EventTypes listening to It is typically generated using `generateName` to avoid naming collisions.
pull requests on two different Github repositories). As `name` nor `metadata.name` is not needed when you create Triggers.
`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) For consumers, the fields that matter the most are `spec` and `status`.
whether the EventType is ready for consumption or not. That _readiness_ is based This is because these fields provide the information you need to create Triggers,
on the Broker being ready. We can see from the example output that the PubSub which is the source and type of event and whether the Broker is ready to receive
EventType is not ready, as its `dev` Broker isn't. events.
Let's talk in more details about the `spec` fields: The following table has more information about the `spec` and `status` fields of
EventType objects:
<!-- info in table needs review for tech accuracy -->
- `type`: is authoritative. This refers to the CloudEvent type as it enters into | Field | Description | Required or optional |
the event mesh. It is mandatory. Event consumers can (and in most cases would) |-------|-------------|----------------------|
create Triggers filtering on this attribute. | `spec.type` | Refers to the [CloudEvent type](https://github.com/cloudevents/spec/blob/master/spec.md#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](https://github.com/cloudevents/spec/blob/master/spec.md#source-1) 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 |
- `source`: refers to the CloudEvent source as it enters into the event mesh. It ## Populate the registry with events
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 You can populate the registry with EventType objects manually or automatically.
protobuf schema, etc. It is optional. Automatic registration can be the easier method, but it only supports a subset of
event sources.
- `description`: is a string describing what the EventType is about. It is ### Manual registration
optional.
- `broker` refers to the Broker that can provide the EventType. It is mandatory. For manual registration, the cluster configurator applies EventTypes YAML files
the same as with any other Kubernetes resource.
<!-- does Knative support manual registration for all event sources? -->
## Subscribing to events To apply EventTypes YAML files manually:
Now that you know what events can be consumed from the Brokers' event meshes, 1. Create an EventType YAML file. For information about the required fields, see
[About EventType objects](#about-eventtype-objects).
1. Apply the YAML by running the command:
```bash
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:
```bash
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:
```yaml
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:
```bash
kubectl get eventtypes -n <namespace>
```
Example output using the `default` namespace in a testing cluster:
```bash
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:
```bash
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](#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. you can create Triggers to subscribe to particular events.
Here are a few example Triggers that subscribe to events using exact matching on Here are a some example Triggers that subscribe to events using exact matching on
`type` and/or `source`, based on the registry output mentioned earlier: `type` or `source`, based on the registry output mentioned earlier:
1. Subscribes to GitHub _pushes_ from any source. * Subscribes to GitHub _pushes_ from any source:
```yaml ```yaml
apiVersion: eventing.knative.dev/v1 apiVersion: eventing.knative.dev/v1
kind: Trigger kind: Trigger
metadata: metadata:
name: push-trigger name: push-trigger
namespace: default namespace: default
spec: spec:
broker: default broker: default
filter: filter:
attributes: attributes:
@ -137,22 +230,22 @@ Here are a few example Triggers that subscribe to events using exact matching on
apiVersion: serving.knative.dev/v1 apiVersion: serving.knative.dev/v1
kind: Service kind: Service
name: push-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.
As per the registry output mentioned, only two sources exist for that particular * Subscribes to GitHub _pull requests_ from the `knative/eventing` GitHub repository:
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.
1. Subscribes to GitHub _pull requests_ from _knative's eventing_ repository. ```yaml
apiVersion: eventing.knative.dev/v1
```yaml kind: Trigger
apiVersion: eventing.knative.dev/v1 metadata:
kind: Trigger
metadata:
name: gh-knative-eventing-pull-trigger name: gh-knative-eventing-pull-trigger
namespace: default namespace: default
spec: spec:
broker: default broker: default
filter: filter:
attributes: attributes:
@ -163,17 +256,17 @@ Here are a few example Triggers that subscribe to events using exact matching on
apiVersion: serving.knative.dev/v1 apiVersion: serving.knative.dev/v1
kind: Service kind: Service
name: gh-knative-eventing-pull-service name: gh-knative-eventing-pull-service
``` ```
1. Subscribes to Kafka messages sent to the _knative-demo_ topic * Subscribes to Kafka messages sent to the _knative-demo_ topic:
```yaml ```yaml
apiVersion: eventing.knative.dev/v1 apiVersion: eventing.knative.dev/v1
kind: Trigger kind: Trigger
metadata: metadata:
name: kafka-knative-demo-trigger name: kafka-knative-demo-trigger
namespace: default namespace: default
spec: spec:
broker: default broker: default
filter: filter:
attributes: attributes:
@ -184,18 +277,17 @@ Here are a few example Triggers that subscribe to events using exact matching on
apiVersion: serving.knative.dev/v1 apiVersion: serving.knative.dev/v1
kind: Service kind: Service
name: kafka-knative-demo-service name: kafka-knative-demo-service
``` ```
1. Subscribes to PubSub messages from GCP's _knative_ project sent to the * Subscribes to PubSub messages from GCP's _knative_ project sent to the _testing_ topic:
_testing_ topic
```yaml ```yaml
apiVersion: eventing.knative.dev/v1 apiVersion: eventing.knative.dev/v1
kind: Trigger kind: Trigger
metadata: metadata:
name: gcp-pubsub-knative-testing-trigger name: gcp-pubsub-knative-testing-trigger
namespace: default namespace: default
spec: spec:
broker: dev broker: dev
filter: filter:
attributes: attributes:
@ -205,80 +297,14 @@ Here are a few example Triggers that subscribe to events using exact matching on
apiVersion: serving.knative.dev/v1 apiVersion: serving.knative.dev/v1
kind: Service kind: Service
name: gcp-pubsub-knative-testing-service name: gcp-pubsub-knative-testing-service
``` ```
Note that events won't be able to be consumed by this Trigger's subscriber !!! note
until the Broker becomes ready. 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.
## 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. This is what the YAML looks
like:
```yaml
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
```
If you are interested in more information regarding configuration options of a
KafkaSource, please refer to the
[KafKaSource sample](samples/kafka/binding/README.md).
For this discussion, the relevant information from the YAML mentioned 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.
## Next steps ## Next steps
1. [Installing Knative](../install/README.md) [Knative code samples](samples/README.md) is a useful resource to better understand
some of the event sources. Remember, you must point the sources to a Broker if you want
1. [Knative code samples](samples/README.md) is a useful resource to better understand automatic registration of EventTypes in the registry.
some of the Event Sources (remember to point them to a Broker if you want
automatic registration of EventTypes in the registry).