Adding Knative Eventing Object Model targeting 0.1 release. #482
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,30 +1,23 @@ | ||
| # Knative Eventing API spec | ||
|
|
||
| This directory contains the specification of the Knative Eventing API, which is | ||
| implemented in [`eventing.knative.dev`](/pkg/apis/eventing/v1alpha1) and | ||
| verified via [the e2e test](/test/e2e). | ||
|
|
||
| **Updates to this spec should include a corresponding change to the API | ||
| implementation for [eventing](/pkg/apis/eventing/v1alpha1) and [the e2e | ||
| test](/test/e2e).** | ||
|
|
||
| Docs in this directory: | ||
|
|
||
| - [Motivation and goals](motivation.md) | ||
| - [Resource type overview](overview.md) | ||
| - [Interface contracts](interfaces.md) | ||
| - [Object model specification](spec.md) | ||
|
|
||
| <!-- TODO(n3wscott): * [Error conditions and reporting](errors.md) --> | ||
| <!-- TODO(n3wscott): * [Sample API usage](normative_examples.md) --> | ||
|
|
||
| See the [Knative Eventing Docs | ||
| Architecture](https://github.com/knative/docs/blob/master/eventing/README.md#architecture) | ||
| for more high level details. <!-- TODO(#498): Update the docs/Architecture page. --> | ||
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,91 @@ | ||||||
| # Interface Contracts | ||||||
|
|
||||||
| ## Subscribable | ||||||
|
Contributor
There was a problem hiding this comment. I don't think Subscribable needs to be a public interface now that the only valid target of a Subscription is a Channel.
Member
There was a problem hiding this comment. I think we should document the interface but indicate that the only acceptable target is a Channel at the moment. (Since we agreed to revisit this with real-world experience in 3-6 months.)
Contributor
Author
There was a problem hiding this comment. This is already in the spec where subscribable is used, the limitation is channel only. |
||||||
|
|
||||||
| A **Subscribable** resource contains a list of subscribers and is responsible | ||||||
| for delivering events to each of them. Subscriptions only allow Channels to be | ||||||
| Subscribable (via `spec.from` on the Subscription) at the moment, but this may | ||||||
| be revisited with future experience. _Channel_ as the target of a | ||||||
| _Subscription_'s `from` field. | ||||||
|
|
||||||
|
|
||||||
| ### Control Plane | ||||||
|
|
||||||
| The **Subscribable** resource stores a list of resolved _Subscriptions_ in the | ||||||
| resource's `spec.subscribers` field. The Subscription Controller is responsible | ||||||
| for resolving any ObjectReferences (such as _call_ and _result_) in the | ||||||
| _Subscription_ to network addresses. | ||||||
|
|
||||||
| ### Data Plane | ||||||
|
|
||||||
| **Subscribable** resources will attempt delivery to each of the _subscribers_ | ||||||
| at least once, and retry if the subscriber returns errors. | ||||||
|
n3wscott marked this conversation as resolved.
|
||||||
|
|
||||||
| <!--TODO(https://github.com/knative/eventing/issues/502) Expand the data plane definitions. --> | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Targetable | ||||||
|
|
||||||
| A **Targetable** resource represents an endpoint that receives events and | ||||||
| optionally returns events to forward downstream. One example of a _Targetable_ | ||||||
| is a function. | ||||||
|
|
||||||
| ### Control Plane | ||||||
|
|
||||||
| A **Targetable** resource MUST expose a _status.targetable.domainInternal_ | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
Contributor
There was a problem hiding this comment. We want one level of indirection there for couple of reasons, one being that there will be less of a chance to have name collisions and is the standard for the other duck types.
Contributor
Author
There was a problem hiding this comment. fix this in a followup. |
||||||
| field. The _domainInternal_ value is an internal domain name that is capable of | ||||||
| receiving event deliveries. _Targetable_ resources may be referenced in the | ||||||
| _call_ section of a _Subscription_. | ||||||
|
|
||||||
| ### Data Plane | ||||||
|
|
||||||
| The **Targetable** resource receives one event and returns zero or more events | ||||||
| in response. The returned events are not required to be related to the received | ||||||
| event. The _Targetable_ should return a successful response if the event was | ||||||
| processed successfully. | ||||||
|
|
||||||
| The _Targetable_ is not responsible for ensuring successful delivery of any | ||||||
| received or returned event. It may receive the same event multiple times even | ||||||
| if it previously indicated success. | ||||||
|
n3wscott marked this conversation as resolved.
|
||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Sinkable | ||||||
|
|
||||||
| A **Sinkable** resource receives events and takes responsibility for further | ||||||
| delivery. Unlike _Targetable_, a _Sinkable_ cannot return events in its | ||||||
| response. One example of a _Sinkable_ is a _Channel_ as the target of a | ||||||
|
n3wscott marked this conversation as resolved.
|
||||||
| _Subscription_'s _result_ field. | ||||||
|
|
||||||
| <!-- TODO(evankanderson): | ||||||
| I don't like this example, as it conflates two different things: | ||||||
|
|
||||||
| That Channel implements Sinkable. | ||||||
| That Subscription expects a Sinkable in its spec.from. | ||||||
| I think it would be clearer to separate the two (and possibly cover the second | ||||||
| item only in the object specs). | ||||||
| --> | ||||||
|
|
||||||
| ### Control Plane | ||||||
|
|
||||||
| A **Sinkable** resource MUST expose a _status.sinkable.domainInternal_ field. | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
| The _domainInternal_ value is an internal domain name that is capable of | ||||||
| receiving event deliveries. _Sinkable_ resources may be referenced in the | ||||||
| _result_ section of a _Subscription_, and also by other custom resources acting as an event Source. | ||||||
|
|
||||||
| ### Data Plane | ||||||
|
|
||||||
| A **Sinkable** resource will only respond to requests with success of failure. | ||||||
| Any payload (including a valid CloudEvent) returned to the sender will be | ||||||
| ignored. It may receive the same event multiple times even if it previously | ||||||
| indicated success. | ||||||
|
|
||||||
| --- | ||||||
|
Member
There was a problem hiding this comment. I think there is also a "performs Delivery" interface that we wanted Sources to have so that there was a consistent way to see what object a source was sending to? @vaikas-google proposed this in the meeting yesterday.
Member
There was a problem hiding this comment. @vaikas-google @n3wscott (since you've thought the most about sources as CRDs and have some implementation experience) Should we mandate that objects which want to act as sources need to implement both "performs Delivery" and be part of a specific named category?
Contributor
Author
There was a problem hiding this comment. yeah, added a todo knative/eventing-contrib#12 |
||||||
|
|
||||||
| _Navigation_: | ||||||
|
|
||||||
| - [Motivation and goals](motivation.md) | ||||||
| - [Resource type overview](overview.md) | ||||||
| - **Interface contracts** | ||||||
| - [Object model specification](spec.md) | ||||||
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,70 +1,93 @@ | ||||||
| # Resource Types | ||||||
|
|
||||||
| The API defines and provides a complete implementation for | ||||||
| [Subscription](spec.md#kind-subscription), and abstract resource definitions | ||||||
| for [Channels](spec.md#kind-channel) and | ||||||
| [ClusterChannelProvisioners](spec.md#kind-clusterchannelprovisioner) which may | ||||||
| be fulfilled by multiple backing implementations (much like the Kubernetes | ||||||
| Ingress resource). | ||||||
|
|
||||||
| With extendibility and compostability as a goal of Knative Eventing, the | ||||||
| eventing API defines several resources that can be reduced down to a well | ||||||
| understood contracts. These eventing resource interfaces may be fulfilled by | ||||||
| other Kubernetes objects and then composed in the same way as the concreate | ||||||
| objects. The interfaces are ([Sinkable](interfaces.md#sinkable), | ||||||
| [Subscribable](interfaces.md#Subscribable), | ||||||
| [Targetable](interfaces.md#targetable)). For more details, see | ||||||
| [Interface Contracts](interfaces.md). | ||||||
|
|
||||||
| - A **Subscription** describes the transformation of an event and optional | ||||||
| forwarding of a returned event. | ||||||
|
|
||||||
| - A **Channel** provides event persistance and fanout of events from a | ||||||
|
n3wscott marked this conversation as resolved.
|
||||||
| well-known input address to multiple outputs described by _Subscriptions_. | ||||||
|
|
||||||
| <!-- This image is sourced from https://drive.google.com/open?id=10mmXzDb8S_4_ZG_hcBr7s4HPISyBqcqeJLTXLwkilRc --> | ||||||
|
|
||||||
|  | ||||||
|
|
||||||
| - **ClusterChannelProvisioners** implement strategies for realizing backing resources | ||||||
| for different implementations of _Channels_ currently active in the eventing | ||||||
| system. | ||||||
|
|
||||||
| <!-- This image is sourced from https://drive.google.com/open?id=1o_0Xh5VjwpQ7Px08h_Q4qnaOdMjt4yCEPixRFwJQjh8 --> | ||||||
|
|
||||||
| <img alt="Resource Types ClusterChannelProvisioners" src="images/resource-types-provisioner.svg" width="200"> | ||||||
|
|
||||||
| Sources are defined by independent CRDs that can be installed into a cluster. | ||||||
| For more information see [Knative Eventing | ||||||
| Sources](https://github.com/knative/eventing-sources). | ||||||
|
|
||||||
| ## Subscription | ||||||
|
|
||||||
| **Subscriptions** describe a flow of events from one _Channel_) to the next | ||||||
|
evankanderson marked this conversation as resolved.
|
||||||
| Channel\* through transformations (such as a Knative Service which processes | ||||||
|
n3wscott marked this conversation as resolved.
|
||||||
| CloudEvents over HTTP). A _Subscription_ controller resolves the addresses of | ||||||
| transformations (`call`) and destination storage (`result`) through the | ||||||
| _Targetable_ and _Sinkable_ interface contracts, and writes the resolved | ||||||
| addresses to the _Channel_ in the `from` reference. _Subscriptions_ do not need | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
| to specify both a transformation and a storage destination, but at least one | ||||||
| must be provided. | ||||||
|
|
||||||
| All event delivery linkage from a **Subscription** is 1:1 – only a single | ||||||
| `from`, `call`, and `result` may be provided. | ||||||
|
|
||||||
| For more details, see [Kind: Subscription](spec.md#kind-subscription). | ||||||
|
n3wscott marked this conversation as resolved.
Contributor
There was a problem hiding this comment. Does this imply that only a linear pipeline of function calls can be supported (regardless of the level of abstraction of deployment units)? Even if I manually deploy a set of Subscription, I could not introduce any conditional logic or branching?
Contributor
There was a problem hiding this comment. That seems so to my eyes. I think the most important "building block" is missing in the spec: the spec is missing a "standard contract for a service to publish events on a bus channel, regardless of the bus implementation". "Callable" services are not necessarily functions and moreover they are not necessarily pure functions without side effects. I think a Service should be able to publish one, two or several events within the context of a invocation, provided that it has been given the permissions (e.g. via static resource configuration) to do so.
Contributor
There was a problem hiding this comment. I agree, that I would expect a Service to be able to publish a number of events. This would also be convenient for error handling and enabling a different component to respond to errors within a Service.
Contributor
Author
There was a problem hiding this comment. This has come up a couple times now. I think the correct answer is another spec that outlines the runtime contract spec for how subscribables, targetables and sinkables communicate at a protocol level and then how that maps to transports we support.
Member
There was a problem hiding this comment. Thanks for calling out this ambiguity. The intent is that Sinkable would be the interface for delivering an event (including to a function) which takes ownership of the event from a "chain of responsibility" pattern. I think there is a second document we need that describes the data plane transport contracts. For now, our baseline is HTTP POST of CloudEvents, but a protocol-negotiation scheme would be very interesting once we've shipped sufficient primitives.
Contributor
There was a problem hiding this comment. Thanks @n3wscott @evankanderson based on other comments I now understand how some of this could be achieved - a Service could produce CloudEvents with different EventType that would be sent along a common channel. Some other Services downstream could filter them. However, is it possible, in the current proposal, for a Service to produce multiple messages (for instance of the same type)? I'm thinking of
Member
There was a problem hiding this comment. @sjwoodman Thanks for your patience! At the moment, CloudEvents does not define how to deliver or return multiple messages in a single HTTP transaction. I think it would be feasible to extend the CloudEvents spec to support bundling multiple messages via multipart MIME using Structured Content Mode. Alternatively, your service might be able to also act as an independent source of events, by taking the address of a Channel and performing HTTP delivery directly to the destination. |
||||||
|
|
||||||
| ## Channel | ||||||
|
|
||||||
| **Channel** provides an at least once event delivery mechanism which can fan | ||||||
|
Contributor
There was a problem hiding this comment. We shouldn't be providing any delivery guarantees. That will be dependent on how the logical Channel is backed via its Provisioner. For example, an in-memory Channel implementation that fails between receiving and delivering an event would not conform to an "at least once" guarantee. |
||||||
| out received events to multiple destinations via _Subscriptions_. A _Channel_ | ||||||
| has a single inbound _Sinkable_ interface which may accept events from multiple | ||||||
| _Subscriptions_ or even direct delivery from external systems. Different | ||||||
| _Channels_ may implement different degrees of persistence. Event delivery order | ||||||
| is dependent on the backing implementation of the _Channel_ provided by the | ||||||
| _ClusterChannelProvisioner_. | ||||||
|
|
||||||
| Event selection on a _Channel_ is 1:N – a single _Channel_ may fan out to | ||||||
| multiple _Subscriptions_. | ||||||
|
|
||||||
| See [Kind: Channel](spec.md#kind-channel). | ||||||
|
|
||||||
| ## ClusterChannelProvisioner | ||||||
|
|
||||||
| **ClusterChannelProvisioner** catalogs available implementations of _Channels_. | ||||||
| _ClusterChannelProvisioners_ hold a JSON Schema that is used to validate the | ||||||
| _Channel_ input arguments. _ClusterChannelProvisioners_ make it possible to | ||||||
| provide cluster wide defaults for the _Channels_ they provision. | ||||||
|
|
||||||
| _ClusterChannelProvisioners_ do not directly handle events. They are 1:N with | ||||||
| _Channels_. | ||||||
|
|
||||||
| For more details, see [Kind: | ||||||
| ClusterChannelProvisioner](spec.md#kind-clusterchannelprovisioner). | ||||||
|
|
||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| _Navigation_: | ||||||
|
|
||||||
| - [Motivation and goals](motivation.md) | ||||||
| - **Resource type overview** | ||||||
| - [Interface contracts](interfaces.md) | ||||||
| - [Object model specification](spec.md) | ||||||
Uh oh!
There was an error while loading. Please reload this page.