Adding docs/spec shell. by n3wscott · Pull Request #147 · knative/eventing

n3wscott · 2018-06-29T00:03:05Z

The serving/docs/spec dir is an awesome resource. Eventing should have one too.

n3wscott · 2018-06-29T00:03:37Z

/assign mattmoor

evankanderson

More comments later, have several hours of meetings next.

evankanderson · 2018-06-29T20:57:32Z

+
+This directory contains the specification of the Knative Eventing API, which is
+implemented in [`pkg/apis/channels/v1alpha1`](/pkg/apis/channels/v1alpha1) and
+[`pkg/apis/feeds/v1alpha1`](/pkg/apis/feeds/v1alpha1) and verified via [the e2e


Prefer to specify the k8s apiversion paths, rather than the repo paths.

evankanderson · 2018-06-29T20:59:53Z

+# Motivation
+
+The goal of the Knative Eventing project is to provide a common toolkit and API
+framework for producing and consuming events, primarily inside of serverless


I'd stress that this is intended to complement serverless workloads, but should work independently of any particular serverless implementation.

It's probably also worth referencing the CloudEvents spec.

Feel free to also lift text from the Eventing Glossary.

ok, linked and reworded. Left off the serverless aspect.

evankanderson

More notes, almost done.

I may send you a PR or two as well.

evankanderson · 2018-06-29T23:58:19Z

+workloads.
+
+Kubernetes has no primitives related to event processing, yet this is an
+essential component in serverless workloads. Eventing will introduce high-level


essential component (citation needed)

I don't have a citation... hm

evankanderson · 2018-06-29T23:58:55Z

+workloads.
+
+Kubernetes has no primitives related to event processing, yet this is an
+essential component in serverless workloads. Eventing will introduce high-level


Prefer active voice "Eventing introduces"

evankanderson · 2018-06-29T23:59:45Z

+integrate with existing message consumers.
+
+The Knative Eventing APIs consist of Eventing API (these documents),
+[Compute API](https://github.com/knative/serving) and


Eventing should be able to operate independently of serving and build, but those may be the best targets for eventing delivery (in terms of cost & observability).

evankanderson · 2018-06-30T00:01:07Z

+
+Kubernetes has no primitives related to event processing, yet this is an
+essential component in serverless workloads. Eventing will introduce high-level
+primitives for event production and delivery in forms that are extensible. If a


We should scope the extensibility of production and delivery. My personal $0.02 given the architecture of knative/serving and Istio is that event delivery should be push (retried if needed), and that delivery should be done using HTTP-compatible framing (because that works nearly everywhere), and provides nice mechanisms for multiplexing.

evankanderson · 2018-06-30T00:01:35Z

@@ -0,0 +1,61 @@
+# Resource Groups
+
+Knative Eventing API is grouped into _Channels_ and _Feeds_:


Slight preference for "Delivery" over "Channels", but @scothis may have sharper opinions than I.

I am just basing this on the k8s grouping currently being used in the CRDs

evankanderson · 2018-06-30T00:05:19Z

+
+The primary resources in the Knative Eventing _Feeds_ API are EventSource, EventType and Bind:
+
+* An **EventSource** wraps an event producer and is able to produce multiple definitions of


Slight preference for standardizing on terms in the Eventing Glossary and/or in the CloudEvents spec. If the current names are terrible, propose new ones in the glossary as well as here.

I am attempting to document what is implemented. I have tried to suggest changes to the glossary to bring it closer to what has been implemented.

evankanderson · 2018-06-30T00:05:35Z

+
+The primary resources in the Knative Eventing _Feeds_ API are EventSource, EventType and Bind:
+
+* An **EventSource** wraps an event producer and is able to produce multiple definitions of


The end of this sentence got lost.

I was following the serving/docs/spec overview where they string the definitions of each type into a paragraph flow...

evankanderson · 2018-06-30T00:05:48Z

+
+The primary resources in the Knative Eventing _Feeds_ API are EventSource, EventType and Bind:
+
+* An **EventSource** wraps an event producer and is able to produce multiple definitions of


Thoughts on calling this just a "Source"?

EventSource.feeds.knative.dev vs Source.feeds.knative.dev

hmm... I do like that EventType matches, because these are tied together.

EventType.feeds.knative.dev

But type is a reserved word in golang.

Cloudevents uses eventType and source. so... I am in favor of changing to Source.

evankanderson · 2018-06-30T00:06:11Z

+
+* An **EventSource** wraps an event producer and is able to produce multiple definitions of
+
+* **EventType**, which describes the schema for the shape of the event and Subscription. 


s/Subscription/Bind/ ?

evankanderson · 2018-06-30T00:12:02Z

+
+The primary resources in the Knative Eventing _Channels_ API are Channel, Subscription and Bus:
+
+* A **Channel** is a logical endpoint to allow events to flow into a


I'd prefer to see this be a complete sentence. Bonus points if the object reference graph is acyclic, but that may not be possible.

I think it would be more clear as real sentences too. Let me just rework it and not try to copy the style of serving.

…eds more work.

n3wscott

I moved over the glossary terms here, I think it needs more work and reading the glossary showed me that there might be some concepts that are not backed by a CR directly, but are properties in those CRs.

n3wscott · 2018-07-02T21:43:16Z

+workloads.
+
+Kubernetes has no primitives related to event processing, yet this is an
+essential component in serverless workloads. Eventing will introduce high-level


I don't have a citation... hm

n3wscott · 2018-07-02T21:43:37Z

+# Motivation
+
+The goal of the Knative Eventing project is to provide a common toolkit and API
+framework for producing and consuming events, primarily inside of serverless


ok, linked and reworded. Left off the serverless aspect.

n3wscott · 2018-07-02T21:53:17Z

@@ -0,0 +1,61 @@
+# Resource Groups
+
+Knative Eventing API is grouped into _Channels_ and _Feeds_:


I am just basing this on the k8s grouping currently being used in the CRDs

n3wscott · 2018-07-02T21:59:50Z

+
+The primary resources in the Knative Eventing _Feeds_ API are EventSource, EventType and Bind:
+
+* An **EventSource** wraps an event producer and is able to produce multiple definitions of


I was following the serving/docs/spec overview where they string the definitions of each type into a paragraph flow...

n3wscott · 2018-07-02T22:03:22Z

+
+The primary resources in the Knative Eventing _Feeds_ API are EventSource, EventType and Bind:
+
+* An **EventSource** wraps an event producer and is able to produce multiple definitions of


I am attempting to document what is implemented. I have tried to suggest changes to the glossary to bring it closer to what has been implemented.

n3wscott · 2018-07-02T22:08:43Z

+
+The primary resources in the Knative Eventing _Feeds_ API are EventSource, EventType and Bind:
+
+* An **EventSource** wraps an event producer and is able to produce multiple definitions of


EventSource.feeds.knative.dev vs Source.feeds.knative.dev

hmm... I do like that EventType matches, because these are tied together.

EventType.feeds.knative.dev

But type is a reserved word in golang.

Cloudevents uses eventType and source. so... I am in favor of changing to Source.

n3wscott · 2018-07-02T22:15:47Z

+
+The primary resources in the Knative Eventing _Channels_ API are Channel, Subscription and Bus:
+
+* A **Channel** is a logical endpoint to allow events to flow into a


I think it would be more clear as real sentences too. Let me just rework it and not try to copy the style of serving.

evankanderson

At what point do you want to commit some part of this and leave the others with TODOs for a future PR?

We should also review this at an eventing WG at some point.

evankanderson · 2018-07-02T23:27:48Z

+# Motivation
+
+Knative Eventing implements the common components for an event delivery
+ecosystem. These common components enable producing and consuming events,


I don't think you need the commas here, assuming you're attempting to say "(producing and consuming) (events adhering to the CloudEvents Specification) in a decoupled way."

evankanderson · 2018-07-02T23:29:15Z

+integrate with existing message consumers.
+
+The Knative Eventing APIs is intended to operate independently, and interop
+well with the [Compute API](https://github.com/knative/serving) and [Build


Prefer "Serving API", since that's the package and repo name.

evankanderson · 2018-07-02T23:30:08Z

+primitives for event production and delivery with a focus on push over HTTP. If a
+new event source or type is required of your application, the effort required
+to plumb them into the existing eventing framework will be minimal and will
+integrate with existing message consumers.


I think it's also worth calling out middleware as well as consumers.

You might want to say "CloudEvents" rather than "existing", because CloudEvents is still quite young.

evankanderson · 2018-07-02T23:32:10Z

+* **Subscription**, an expressed interest in events to be delivered to a
+  service.
+
+![TODO:: Object model](images/object_model.png)


This will be a broken image tag. Put it in comments?

evankanderson · 2018-07-02T23:33:54Z

+
+* **EventType**, the schema for an event.
+
+* **Bind**, ties the output of an event producer to the input of an event


No comma here on Bind between subject and verb. If you want the same construction as above, try:

** Bind **, the association between the output ...

I think the EventSource in many cases is not actually the source of the event. If you look at the Pub/Sub EventSource, the topics will most likely not be the sources. In the case of CloudEvents, the source attribute will contain something different. Pub/Sub is then the infrastructure propagating the events of potentially many different sources.

evankanderson · 2018-07-02T23:37:27Z

+
+# Eventing
+
+TODO an overview of how these objects are created and perhaps the persona


TAL at https://www.draw.io/#G1EgWHszjc8tO-5hW6_yoFBrWDt4F9TJcn / https://drive.google.com/open?id=1EgWHszjc8tO-5hW6_yoFBrWDt4F9TJcn if you want a sample picture of things working together.

I'm trying to find a good format to actually check that image into a repo. Sadly, UML does not have quite the layout control needed. I may end up doing SVG/PNG + the draw.io XML, which would make me slightly sad.

markfisher · 2018-07-03T15:23:03Z

+
+Kubernetes has no primitives related to event processing, yet this is an
+essential component in serverless workloads. Eventing introduces high-level
+primitives for event production and delivery with a focus on push over HTTP. If a


If we're going to emphasize HTTP here, perhaps we should qualify with a "currently". We hope to have gRPC support soon, and it might be the preferred approach for many use-cases since that would enable the use of streams.

markfisher · 2018-07-03T15:27:35Z

+
+## Channel
+
+A named endpoint on a Bus which accepts events delivered from an outside system.


Currently Channels are only exposed as in-cluster Services. We have a PoC for a "gateway" (another naming conflict we'll have to resolve) that is exposed as an ingress, but in general, Channels may be used for app-to-app (or function-to-function) interacts within the cluster as well.

markfisher · 2018-07-03T15:28:38Z

+
+## Bus
+
+A system which routes events from Channels to Actions. The Broker MAY (RFC


I would prefer "to subscribed Service endpoints" rather than "to Actions" here.

deissnerk · 2018-07-03T15:51:15Z

+
+* **Subscription**, an expressed interest in events to be delivered to a
+  service.
+


This definition of Subscription might cause confusion in combination with Bind.

This is another reason I prefer "Feed" since that would then emphasize its role as the manifestation of events from a source, and if it simply has a target (k8s) Service, that could be a direct connection to a Knative workload via the Service created by its Route, or it could be the Service that corresponds to a Channel. Only when using a Channel would there be something to "subscribe" to.

google-prow-robot · 2018-07-03T22:14:08Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: n3wscott
To fully approve this pull request, please assign additional approvers.
We suggest the following additional approver: evankanderson

If they are not already assigned, you can assign the PR to them by writing /assign @evankanderson in a comment when ready.

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

grantr

/lgtm
Thanks @n3wscott, would love to see this in the repo.

@markfisher @deissnerk I think your comments are resolved (hold if not). @evankanderson I'll let you approve when you're ready.

grantr · 2018-07-23T19:32:53Z

+
+# Resource Types
+
+The primary resources in the Knative Eventing _Feeds_ API are EventSource, EventType and Bind:


Bind -> Feed

grantr · 2018-07-23T19:37:05Z

+to plumb them into the existing eventing framework will be minimal and will
+integrate with CloudEvents middleware and message consumers.
+
+The Knative Eventing APIs is intended to operate independently, and interop


Nit: APIs is should be changed to either API is or APIs are.

Is "intended to operate independently" an accurate description of the relationship between serving and eventing? My understanding is that the API definition and control plane are intended to be independent of serving, but the data plane (bus, channel, and feed implementations) have no such intent.

Adding base spec dir with shell of files.

d9471db

google-prow-robot added the size/S Denotes a PR that changes 10-29 lines, ignoring generated files. label Jun 29, 2018

google-prow-robot assigned mattmoor Jun 29, 2018

Adding words to Motivation.

18af19e

google-prow-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Jun 29, 2018

First crack at an overview, but expanded definitions are needed.

ee428b3

evankanderson reviewed Jun 29, 2018

View reviewed changes

evankanderson reviewed Jun 30, 2018

View reviewed changes

n3wscott mentioned this pull request Jul 2, 2018

Adding a list of CRDs added by eventing #129

Merged

REword based on feedback and copied some of the glossary terms in. Ne…

88d7500

…eds more work.

google-prow-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Jul 2, 2018

n3wscott commented Jul 2, 2018

View reviewed changes

evankanderson reviewed Jul 2, 2018

View reviewed changes

mattmoor assigned evankanderson Jul 3, 2018

markfisher reviewed Jul 3, 2018

View reviewed changes

deissnerk reviewed Jul 3, 2018

View reviewed changes

Adding a simple image for object model.

acbf960

mattmoor assigned vaikas and unassigned mattmoor Jul 13, 2018

Scott Nichols added 2 commits July 23, 2018 08:52

Merge remote-tracking branch 'upstream/master' into spec

8950a8f

Clean up the docs, take in feedback from the PR.

93ee630

grantr approved these changes Jul 23, 2018

View reviewed changes

google-prow-robot assigned grantr Jul 23, 2018

google-prow-robot added the lgtm Indicates that a PR is ready to be merged. label Jul 23, 2018

n3wscott mentioned this pull request Jul 25, 2018

Adding docs/spec shell (v2). #286

Merged

n3wscott closed this Jul 25, 2018

grantr mentioned this pull request Aug 21, 2018

Add grantr to list of approvers #387

Merged

		@@ -0,0 +1,61 @@
		# Resource Groups

		Knative Eventing API is grouped into _Channels_ and _Feeds_:


		The primary resources in the Knative Eventing _Feeds_ API are EventSource, EventType and Bind:

		* An EventSource wraps an event producer and is able to produce multiple definitions of


		* An EventSource wraps an event producer and is able to produce multiple definitions of

		* EventType, which describes the schema for the shape of the event and Subscription.


		The primary resources in the Knative Eventing _Channels_ API are Channel, Subscription and Bus:

		* A Channel is a logical endpoint to allow events to flow into a


		* EventType, the schema for an event.

		* Bind, ties the output of an event producer to the input of an event


		# Eventing

		TODO an overview of how these objects are created and perhaps the persona


		## Channel

		A named endpoint on a Bus which accepts events delivered from an outside system.


		## Bus

		A system which routes events from Channels to Actions. The Broker MAY (RFC


		* Subscription, an expressed interest in events to be delivered to a
		service.


		# Resource Types

		The primary resources in the Knative Eventing _Feeds_ API are EventSource, EventType and Bind:

Conversation

n3wscott commented Jun 29, 2018

Uh oh!

n3wscott commented Jun 29, 2018

Uh oh!

evankanderson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

evankanderson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

n3wscott left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

evankanderson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment