Eventing: Event Registry

[nachocano]

Problem
We need to provide Event Consumers with a mechanism to discover what event types they can consume from the eventing mesh.

Persona:
Event Consumer

Exit Criteria
Executing kubectl get eventtypes -n <namespace> returns the event types available for consumption in that particular namespace.

Time Estimate (optional):
2 or 3 weeks. It will depend on how fast the design conversations move forward.

[duglin]

Do you have a suggestion for how Kn gets this information? Does each Kn EventSource have built-in knowledge of the event types coming from its event producers? Does it query the event producers periodically?

[vaikas]

In my opinion there are couple of things here that are at play.
Kn EventSource (CRD) is a Potential Source of events. Unless a Custom Resource is created (aka, CRD is reified and hence a dataplane is established), they are only that, potential events and they should not be listed in the Registry as available because without a configured CR, the events are not available for consumption.

Kn EventSource should publish what event types it is capable of producing. How it generates and how frequent this list is updated, should be discussed in a separate topic (fair?) I've been meaning to create / update an issue talking about the Event Sources in more depth, I'll get to this soon (promise :) )

Now, back to the registry. I think since Trigger is bound to a given Broker (and hence a namespace), a registry should be a list of available event types for that Broker. I can see value being able to list all event types for a given namespace, possibly listing the Broker that is able to provide them. So, at the very least, I could see the above command returning:
eventtype, broker

I think there are use cases obvs for things like source there as well, but at the very least I see the two entries above as necessary for being able to create a trigger without resorting to some other OOB mechanism.

If the registry has the ability to add new event types into it (as an example, just a CRD and creating a new CR to represent event type), then a Broker can be configured to (for example):

1. Add any new event type into the registry upon the first Ingress (this is handy for things like a function transforming an event and taking in Event Type A but creating Event Type B). It would be easier for the developer (at least in the testing cases to not have to register each event up front, but we can argue about this)
2. Require any Ingress event to be registered in the Registry before it's allowed in (@csantanapr use case)
3. There's others and other hybrid modes here, say, you could for example say Functions returning new events will be auto-added and so forth.

So, with those assumptions, one possible solution would be to have the Event Source (when a CR is created), add those events into the Event Registry for the Broker that it has been wired to send those events.

---

However, I could see also (at least) another mode where the registry would be more complex and in this world, the registry could contain also the list of potential EventTypes and in that case the Source would have to populate all the registries with all the potential EventTypes in the registry, and the Registry would have to have a backpointer to the CRD which can provide those event types. Then when a Trigger is created, Trigger Controller could consult the registry, and if not already configured to emit those events into the specified Broker, could create the CR representing the desired EventTypes. This model gets messy however because in addition to the Trigger spec, there are probably things like credentials that have to be involved here. While we could probably come up with a standard way to define these, I would like to punt on this issue for now.

So the flow that I'm proposing is that there are two high level operations the user performs:

1. Wire an external (to the mesh/broker) source to emit events into a Broker
   
   
   
   • This will then add the eventtypes subscribed into the Registry for that Broker. It should know what events it is subscribing to (see more below for caveats) and which broker it's sending to, so has all the information available to populate the Registry
   
   
2. Wire an EventType into a consuming function. Need Broker (can default, but...) / Eventtype for this operation.

By having a registry that contains available events for bullet 2 above is what this should be aiming to solve.

Caveats:

• EventSource could subscribe to a source with '*' and when that source is updated it could produce additional events. If we can come up with a real example of this, then we could revise how this could be solved. Either there needs to be an ability to list the set of eventtypes so that they can be then periodically re-listed (or notified that new types are available (so write a function for it ;) ) ) and the registry can still be updated
• By running in the 'auto add events when seen' mode or assuming that the only way to discover what event types are available is when they are seen is bad because it means you can't create the trigger until you have seen at least one event for that given type. this is bad user experience.

[nachocano]

Unless a Custom Resource is created (aka, CRD is reified and hence a dataplane is established), they are only that, potential events and they should not be listed in the Registry as available because without a configured CR, the events are not available for consumption.

I'm more into this idea but I think it may add more burden to Kn Source developers (I think we call them Receive Adapter authors), as their controllers will need to take care of creating the EventTypes.
Also, what if there are two CRs, e.g, GitHub_sample_1 that listens to pull_requests from user1 repo1, and GitHub_sample_2 that also listens to pull_requests but from user2 repo2. And they are both tied to the same broker. Shall the GitHub source controller create a single EventType pull_request for that broker or two?
In other words, shouldn't the EventType have some sort of 'owner', 'repo' information to be more "accurate"? If it doesn't have that info, by querying the registry, a consumer might think she can consume pull_requests from any GitHub repo, but she can actually consume from only two.
I guess adding that kind of info will blow up the registry.

I'm wondering what are your thoughts @vaikas-google.

[vaikas]

Sorry, are you saying that they should be listed in the registry or not by default? I do agree that Source should be part of this, that's what I _tried_ (but poorly) say here:
"
eventtype, broker

I think there are use cases obvs for things like source there as well, but at the very least I see the two entries above as necessary for being able to create a trigger without resorting to some other OOB mechanism."

And yes, in that case, I would expect in this version there to be two event types with two sources in the registry.

[nachocano]

Does each Kn EventSource have built-in knowledge of the event types coming from its event producers?

@duglin some Kn Sources have that info. For example, GitHubSource CRD has the list of event types that we can create webhooks for. I also have a PR pending for a BitBucket one, where we also have that list.
If you look at the AWS SQS adapter code, you can see that it only sends "aws.sqs.message" as event type, the CronJob one sends "dev.knative.cronjob.event", and so on.

I guess we might not know for all sources, but for the ones we do, IMO we should try to "standarize" how they advertise their event types, schemas, etc.

[nachocano]

Sorry, are you saying that they should be listed in the registry or not by default?

If we are going with the approach of creating the registry entries upon CR instantiation, then I think we should have that "source" information as part of the EventType data type. The downside is that the registry will grow pretty fast.

[vaikas]

My preference would be to add source there and add them to the registry when a CR is created. I am not sure I buy the argument that the registry will grow pretty fast, I think that populating all the namespaces with all the possible events would grow faster than only showing the events that have been created subscriptions to :)

[nachocano]

I think that populating all the namespaces with all the possible events would grow faster than only showing the events that have been created subscriptions to :)

Valid point, and you are probably right :) I guess I'm envisioning a system where plenty of CRs will be created.

[nachocano]

/assign

[nachocano]

Some design discussion going on in https://github.com/knative/eventing/pull/1015
If people think it might be better a doc instead of a markup, I can start a doc as well.

Need to give credit to @vaikas-google and @grantr for the good ideas in the proposal. Bad ones are all mine :)

[nachocano]

Done with first iteration of Registry!