From d9471db455149d24922c3ce7a6554e6c517f5f57 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Thu, 28 Jun 2018 17:02:12 -0700 Subject: [PATCH 01/12] Adding base spec dir with shell of files. --- docs/spec/README.md | 18 ++++++++++++++++++ docs/spec/errors.md | 1 + docs/spec/motivation.md | 1 + docs/spec/normative_examples.md | 1 + docs/spec/overview.md | 1 + docs/spec/spec.md | 1 + 6 files changed, 23 insertions(+) create mode 100644 docs/spec/README.md create mode 100644 docs/spec/errors.md create mode 100644 docs/spec/motivation.md create mode 100644 docs/spec/normative_examples.md create mode 100644 docs/spec/overview.md create mode 100644 docs/spec/spec.md diff --git a/docs/spec/README.md b/docs/spec/README.md new file mode 100644 index 00000000000..d8e7b60258a --- /dev/null +++ b/docs/spec/README.md @@ -0,0 +1,18 @@ +# Knative Eventing API spec + +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 +test](/test/e2e). + +**Updates to this spec should include a corresponding change to the +API implementation for [channels](/pkg/apis/channels/v1alpha1) or +in [feeds](/pkg/apis/feeds/v1alpha1) and [the e2e test](/test/e2e).** + +Docs in this directory: + +* [Motivation and goals](motivation.md) +* [Resource type overview](overview.md) +* [Knative Eventing API spec](spec.md) +* [Error conditions and reporting](errors.md) +* [Sample API usage](normative_examples.md) \ No newline at end of file diff --git a/docs/spec/errors.md b/docs/spec/errors.md new file mode 100644 index 00000000000..30404ce4c54 --- /dev/null +++ b/docs/spec/errors.md @@ -0,0 +1 @@ +TODO \ No newline at end of file diff --git a/docs/spec/motivation.md b/docs/spec/motivation.md new file mode 100644 index 00000000000..30404ce4c54 --- /dev/null +++ b/docs/spec/motivation.md @@ -0,0 +1 @@ +TODO \ No newline at end of file diff --git a/docs/spec/normative_examples.md b/docs/spec/normative_examples.md new file mode 100644 index 00000000000..30404ce4c54 --- /dev/null +++ b/docs/spec/normative_examples.md @@ -0,0 +1 @@ +TODO \ No newline at end of file diff --git a/docs/spec/overview.md b/docs/spec/overview.md new file mode 100644 index 00000000000..30404ce4c54 --- /dev/null +++ b/docs/spec/overview.md @@ -0,0 +1 @@ +TODO \ No newline at end of file diff --git a/docs/spec/spec.md b/docs/spec/spec.md new file mode 100644 index 00000000000..30404ce4c54 --- /dev/null +++ b/docs/spec/spec.md @@ -0,0 +1 @@ +TODO \ No newline at end of file From 18af19e99eb27b7c416eafa9f2fd04ae99e88f78 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Fri, 29 Jun 2018 11:39:30 -0700 Subject: [PATCH 02/12] Adding words to Motivation. --- docs/spec/motivation.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/spec/motivation.md b/docs/spec/motivation.md index 30404ce4c54..6aa13945467 100644 --- a/docs/spec/motivation.md +++ b/docs/spec/motivation.md @@ -1 +1,16 @@ -TODO \ No newline at end of file +# 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 +workloads. + +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 +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. + +The Knative Eventing APIs consist of Eventing API (these documents), +[Compute API](https://github.com/knative/serving) and +[Build API](https://github.com/knative/build). \ No newline at end of file From ee428b3a144429231ac79a647df79122891890eb Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Fri, 29 Jun 2018 12:25:16 -0700 Subject: [PATCH 03/12] First crack at an overview, but expanded definitions are needed. --- docs/spec/overview.md | 62 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 61 insertions(+), 1 deletion(-) diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 30404ce4c54..d2128e46405 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -1 +1,61 @@ -TODO \ No newline at end of file +# Resource Groups + +Knative Eventing API is grouped into _Channels_ and _Feeds_: + +* _Channels_ define an abstraction between the eventing infrastructure and the + consumption and production of the events. + +* _Feeds_ bridge the event source into the eventing framework. + +# Resource Types + +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 + +* **EventType**, which describes the schema for the shape of the event and Subscription. + +* A **Bind** connects an EventType to a Channel or Route. + + +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 + +* **Bus**, which implements delivery mechanisms allowing events to flow to a + +* **Subscription**, which allows events of interest to be delivered to a + service. + + +![TODO:: Object model](images/object_model.png) + + +## EventSource + +TODO + +## EventType + +TODO + +## Bind + +TODO + +## Channel + +TODO + +## Bus + +TODO + +## Subscription + +TODO + +# Eventing + +TODO an overview of how these objects are created and perhaps the persona +expected to make each. From 88d7500459fd6eedcc08ac589f865478a7242982 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 2 Jul 2018 15:30:14 -0700 Subject: [PATCH 04/12] REword based on feedback and copied some of the glossary terms in. Needs more work. --- docs/spec/README.md | 4 ++-- docs/spec/motivation.md | 17 +++++++++-------- docs/spec/overview.md | 35 +++++++++++++++++++++++------------ 3 files changed, 34 insertions(+), 22 deletions(-) diff --git a/docs/spec/README.md b/docs/spec/README.md index d8e7b60258a..d1358e5d3e2 100644 --- a/docs/spec/README.md +++ b/docs/spec/README.md @@ -1,8 +1,8 @@ # Knative Eventing API spec 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 +implemented in [`channels.knative.dev`](/pkg/apis/channels/v1alpha1) and +[`feeds.knative.dev`](/pkg/apis/feeds/v1alpha1) and verified via [the e2e test](/test/e2e). **Updates to this spec should include a corresponding change to the diff --git a/docs/spec/motivation.md b/docs/spec/motivation.md index 6aa13945467..7663df8880f 100644 --- a/docs/spec/motivation.md +++ b/docs/spec/motivation.md @@ -1,16 +1,17 @@ # 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 -workloads. +Knative Eventing implements the common components for an event delivery +ecosystem. These common components enable producing and consuming events, +adhering to the [CloudEvents +Specification](https://github.com/cloudevents/spec), in a decoupled way. 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 +essential component in serverless workloads. Eventing introduces high-level +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. -The Knative Eventing APIs consist of Eventing API (these documents), -[Compute API](https://github.com/knative/serving) and -[Build API](https://github.com/knative/build). \ No newline at end of file +The Knative Eventing APIs is intended to operate independently, and interop +well with the [Compute API](https://github.com/knative/serving) and [Build +API](https://github.com/knative/build). diff --git a/docs/spec/overview.md b/docs/spec/overview.md index d2128e46405..f4c4e75379c 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -7,33 +7,37 @@ Knative Eventing API is grouped into _Channels_ and _Feeds_: * _Feeds_ bridge the event source into the eventing framework. +Typically, _Feeds_ perform out-of-cluster provisioning, while _Channels_ are +within-cluster management of event delivery. + # Resource Types 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**, an archetype of an event producer. -* **EventType**, which describes the schema for the shape of the event and Subscription. +* **EventType**, the schema for an event. -* A **Bind** connects an EventType to a Channel or Route. +* **Bind**, ties the output of an event producer to the input of an event + consumer. 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 +* **Channel**, a named endpoint which accepts and forwards events. -* **Bus**, which implements delivery mechanisms allowing events to flow to a +* **Bus**, an implementation of an event delivery mechanism. -* **Subscription**, which allows events of interest to be delivered to a +* **Subscription**, an expressed interest in events to be delivered to a service. - ![TODO:: Object model](images/object_model.png) ## EventSource -TODO +A software system which wishes to make changes in state discoverable via +eventing, without prior knowledge of systems which might consume state changes. ## EventType @@ -41,19 +45,26 @@ TODO ## Bind -TODO +A configuration of event transmission from a single Source to a single Action. +A Binding may contain additional properties of the event transmission such as +filtering, timeouts, rate limits, and buffering. ## Channel -TODO +A named endpoint on a Bus which accepts events delivered from an outside system. ## Bus -TODO +A system which routes events from Channels to Actions. The Broker MAY (RFC +2119) provide durable, at-least-once semantics and buffering of events between +the Source and the Action. Brokers also perform event fan-out across multiple +actions which are subscribed to the same channel. + ## Subscription -TODO +A control plane construct which routes events received on a Channel to a URL or +DNS name # Eventing From acbf960a1e984b058035a49bef1023bdd41e90ff Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Tue, 3 Jul 2018 15:13:56 -0700 Subject: [PATCH 05/12] Adding a simple image for object model. --- docs/spec/images/overview-reference.dot | 32 ++++++++++++++++++++++++ docs/spec/images/overview-reference.png | Bin 0 -> 13267 bytes docs/spec/motivation.md | 10 ++++---- docs/spec/overview.md | 7 +++--- 4 files changed, 40 insertions(+), 9 deletions(-) create mode 100644 docs/spec/images/overview-reference.dot create mode 100644 docs/spec/images/overview-reference.png diff --git a/docs/spec/images/overview-reference.dot b/docs/spec/images/overview-reference.dot new file mode 100644 index 00000000000..5696ea44e9e --- /dev/null +++ b/docs/spec/images/overview-reference.dot @@ -0,0 +1,32 @@ +// This is the overview graph for object refrences in the control plane. +// +// To reproduce the PNG, run the following: +// $ dot -Tpng overview-reference.dot -o overview-reference.png +// +digraph G { + ordering = out; + rankdir = LR; + + node [shape=rectangle; width=1.25; height=.5; fixedsize=true;] + + subgraph cluster_A { + Source -> EventType; + color=white; + {rank = same; Source; EventType} + } + + subgraph cluster_B { + Channel + Subscription; + label = "Bus"; + color=black; + } + + EventType -> Feed [dir=back]; + Feed -> Channel; + + Subscription -> Service; + Channel -> Subscription [dir=back]; + + {rank = max; Service;} +} diff --git a/docs/spec/images/overview-reference.png b/docs/spec/images/overview-reference.png new file mode 100644 index 0000000000000000000000000000000000000000..08e3be1d5b72a805da640995eb522bab2f1927f2 GIT binary patch literal 13267 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 literal 0 HcmV?d00001 diff --git a/docs/spec/motivation.md b/docs/spec/motivation.md index 7663df8880f..191e235b454 100644 --- a/docs/spec/motivation.md +++ b/docs/spec/motivation.md @@ -1,17 +1,17 @@ # Motivation Knative Eventing implements the common components for an event delivery -ecosystem. These common components enable producing and consuming events, +ecosystem. These common components enable producing and consuming events adhering to the [CloudEvents Specification](https://github.com/cloudevents/spec), in a decoupled way. 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 -new event source or type is required of your application, the effort required +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. +integrate with CloudEvents middleware and 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 +well with the [Serving API](https://github.com/knative/serving) and [Build API](https://github.com/knative/build). diff --git a/docs/spec/overview.md b/docs/spec/overview.md index f4c4e75379c..3a74720576e 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -18,8 +18,8 @@ The primary resources in the Knative Eventing _Feeds_ API are EventSource, Event * **EventType**, the schema for an event. -* **Bind**, ties the output of an event producer to the input of an event - consumer. +* **Bind**, the association between the output of an event producer to the + input of an event consumer. The primary resources in the Knative Eventing _Channels_ API are Channel, Subscription and Bus: @@ -31,8 +31,7 @@ The primary resources in the Knative Eventing _Channels_ API are Channel, Subscr * **Subscription**, an expressed interest in events to be delivered to a service. -![TODO:: Object model](images/object_model.png) - +![Object Model](images/overview-reference.png) ## EventSource From 93ee63061fe214aad9af3a3c4565fd5eca633bf1 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 23 Jul 2018 09:02:10 -0700 Subject: [PATCH 06/12] Clean up the docs, take in feedback from the PR. --- docs/spec/README.md | 6 +++--- docs/spec/errors.md | 1 - docs/spec/normative_examples.md | 1 - docs/spec/overview.md | 27 +++++++++++++++++---------- docs/spec/spec.md | 1 - 5 files changed, 20 insertions(+), 16 deletions(-) delete mode 100644 docs/spec/errors.md delete mode 100644 docs/spec/normative_examples.md delete mode 100644 docs/spec/spec.md diff --git a/docs/spec/README.md b/docs/spec/README.md index d1358e5d3e2..fa32012aa55 100644 --- a/docs/spec/README.md +++ b/docs/spec/README.md @@ -13,6 +13,6 @@ Docs in this directory: * [Motivation and goals](motivation.md) * [Resource type overview](overview.md) -* [Knative Eventing API spec](spec.md) -* [Error conditions and reporting](errors.md) -* [Sample API usage](normative_examples.md) \ No newline at end of file + + + \ No newline at end of file diff --git a/docs/spec/errors.md b/docs/spec/errors.md deleted file mode 100644 index 30404ce4c54..00000000000 --- a/docs/spec/errors.md +++ /dev/null @@ -1 +0,0 @@ -TODO \ No newline at end of file diff --git a/docs/spec/normative_examples.md b/docs/spec/normative_examples.md deleted file mode 100644 index 30404ce4c54..00000000000 --- a/docs/spec/normative_examples.md +++ /dev/null @@ -1 +0,0 @@ -TODO \ No newline at end of file diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 3a74720576e..291e3d436af 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -7,6 +7,9 @@ Knative Eventing API is grouped into _Channels_ and _Feeds_: * _Feeds_ bridge the event source into the eventing framework. +* _Flows_ are the higher order abstractions for eventing that use _Channels_ + and _Feeds_. + Typically, _Feeds_ perform out-of-cluster provisioning, while _Channels_ are within-cluster management of event delivery. @@ -18,7 +21,7 @@ The primary resources in the Knative Eventing _Feeds_ API are EventSource, Event * **EventType**, the schema for an event. -* **Bind**, the association between the output of an event producer to the +* **Feed**, the association between the output of an event producer to the input of an event consumer. @@ -31,6 +34,10 @@ The primary resources in the Knative Eventing _Channels_ API are Channel, Subscr * **Subscription**, an expressed interest in events to be delivered to a service. +The primary resources in the Knative Eventing _Flows_ API are Flow: + +* **Flow**, the connection between an event producer to the event consumer. + ![Object Model](images/overview-reference.png) ## EventSource @@ -42,28 +49,28 @@ eventing, without prior knowledge of systems which might consume state changes. TODO -## Bind +## Feed A configuration of event transmission from a single Source to a single Action. -A Binding may contain additional properties of the event transmission such as +A Feed may contain additional properties of the event transmission such as filtering, timeouts, rate limits, and buffering. ## Channel -A named endpoint on a Bus which accepts events delivered from an outside system. +A named in-cluster Service on a Bus which accepts events delivered from a Feed. ## Bus -A system which routes events from Channels to Actions. The Broker MAY (RFC -2119) provide durable, at-least-once semantics and buffering of events between -the Source and the Action. Brokers also perform event fan-out across multiple -actions which are subscribed to the same channel. +A system which routes events from Channels to subscribed Service endpoints. The +Broker MAY (RFC 2119) provide durable, at-least-once semantics and buffering of +events between the Source and the Action. Brokers also perform event fan-out +across multiple actions which are subscribed to the same channel. ## Subscription -A control plane construct which routes events received on a Channel to a URL or -DNS name +A control plane construct which allows the Bus to route events received on a +Channel to the subscribed Service. # Eventing diff --git a/docs/spec/spec.md b/docs/spec/spec.md deleted file mode 100644 index 30404ce4c54..00000000000 --- a/docs/spec/spec.md +++ /dev/null @@ -1 +0,0 @@ -TODO \ No newline at end of file From 82a3ba7d6eb9644fd8cc2426eba40dc99061d64f Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Wed, 25 Jul 2018 09:58:47 -0700 Subject: [PATCH 07/12] fix wording, remove bind. --- docs/spec/motivation.md | 2 +- docs/spec/overview.md | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/spec/motivation.md b/docs/spec/motivation.md index 191e235b454..48f5669946c 100644 --- a/docs/spec/motivation.md +++ b/docs/spec/motivation.md @@ -12,6 +12,6 @@ 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 CloudEvents middleware and message consumers. -The Knative Eventing APIs is intended to operate independently, and interop +The Knative Eventing API is intended to operate independently, and interop well with the [Serving API](https://github.com/knative/serving) and [Build API](https://github.com/knative/build). diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 291e3d436af..dcf3ce19a5c 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -15,7 +15,8 @@ within-cluster management of event delivery. # Resource Types -The primary resources in the Knative Eventing _Feeds_ API are EventSource, EventType and Bind: +The primary resources in the Knative Eventing _Feeds_ API are EventSource, +EventType and Feed: * **EventSource**, an archetype of an event producer. @@ -25,7 +26,8 @@ The primary resources in the Knative Eventing _Feeds_ API are EventSource, Event input of an event consumer. -The primary resources in the Knative Eventing _Channels_ API are Channel, Subscription and Bus: +The primary resources in the Knative Eventing _Channels_ API are Channel, +Subscription and Bus: * **Channel**, a named endpoint which accepts and forwards events. From dc6501eac9d38b6d742c17ec8759bcda43bfc5cc Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Wed, 25 Jul 2018 11:57:04 -0700 Subject: [PATCH 08/12] Updated based on feedback. --- docs/spec/README.md | 24 +++++++++---- docs/spec/images/overview-reference.dot | 21 +++++++----- docs/spec/images/overview-reference.png | Bin 13267 -> 15111 bytes docs/spec/overview.md | 43 ++++-------------------- 4 files changed, 37 insertions(+), 51 deletions(-) diff --git a/docs/spec/README.md b/docs/spec/README.md index fa32012aa55..88c92d63953 100644 --- a/docs/spec/README.md +++ b/docs/spec/README.md @@ -1,13 +1,15 @@ # Knative Eventing API spec This directory contains the specification of the Knative Eventing API, which is -implemented in [`channels.knative.dev`](/pkg/apis/channels/v1alpha1) and -[`feeds.knative.dev`](/pkg/apis/feeds/v1alpha1) and verified via [the e2e +implemented in [`channels.knative.dev`](/pkg/apis/channels/v1alpha1), +[`feeds.knative.dev`](/pkg/apis/feeds/v1alpha1) and +[`flows.knative.dev`](/pkg/apis/flows/v1alpha1) and verified via [the e2e test](/test/e2e). -**Updates to this spec should include a corresponding change to the -API implementation for [channels](/pkg/apis/channels/v1alpha1) or -in [feeds](/pkg/apis/feeds/v1alpha1) and [the e2e test](/test/e2e).** +**Updates to this spec should include a corresponding change to the API +implementation for [channels](/pkg/apis/channels/v1alpha1), +[feeds](/pkg/apis/feeds/v1alpha1) or [flows](/pkg/apis/feeds/v1alpha1) and [the +e2e test](/test/e2e).** Docs in this directory: @@ -15,4 +17,14 @@ Docs in this directory: * [Resource type overview](overview.md) - \ No newline at end of file + + + \ No newline at end of file diff --git a/docs/spec/images/overview-reference.dot b/docs/spec/images/overview-reference.dot index 5696ea44e9e..97e089ae95d 100644 --- a/docs/spec/images/overview-reference.dot +++ b/docs/spec/images/overview-reference.dot @@ -8,20 +8,23 @@ digraph G { rankdir = LR; node [shape=rectangle; width=1.25; height=.5; fixedsize=true;] - + subgraph cluster_A { - Source -> EventType; + Source -> EventType [dir=back]; color=white; {rank = same; Source; EventType} } - - subgraph cluster_B { - Channel - Subscription; - label = "Bus"; - color=black; + + subgraph cluster_C { + Feed; + subgraph cluster_B { + Channel + Subscription; + label = "Bus"; + color=black; + } + label = "Flow"; } - EventType -> Feed [dir=back]; Feed -> Channel; diff --git a/docs/spec/images/overview-reference.png b/docs/spec/images/overview-reference.png index 08e3be1d5b72a805da640995eb522bab2f1927f2..c15a861e43b2a22df50fc45c4711d4704f8a6d3c 100644 GIT binary patch literal 15111 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 a?{mm1diJ`QBlxnFLQPrgW|89E;Qs+#(;xo; literal 13267 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 diff --git a/docs/spec/overview.md b/docs/spec/overview.md index dcf3ce19a5c..80034ceb2e1 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -1,6 +1,6 @@ # Resource Groups -Knative Eventing API is grouped into _Channels_ and _Feeds_: +Knative Eventing API is grouped into _Channels_, _Feeds_ and _Flows_: * _Channels_ define an abstraction between the eventing infrastructure and the consumption and production of the events. @@ -11,7 +11,9 @@ Knative Eventing API is grouped into _Channels_ and _Feeds_: and _Feeds_. Typically, _Feeds_ perform out-of-cluster provisioning, while _Channels_ are -within-cluster management of event delivery. +within-cluster management of event delivery. _Flows_ is a higher order wrapper +used to connect event producers directly with event consumers leveraging +_Feeds_ and _Channels_. # Resource Types @@ -42,39 +44,8 @@ The primary resources in the Knative Eventing _Flows_ API are Flow: ![Object Model](images/overview-reference.png) -## EventSource +See the [Knative Eventing Docs +Architecture](https://github.com/knative/docs/blob/master/eventing/README.md#architecture) +for more details. -A software system which wishes to make changes in state discoverable via -eventing, without prior knowledge of systems which might consume state changes. -## EventType - -TODO - -## Feed - -A configuration of event transmission from a single Source to a single Action. -A Feed may contain additional properties of the event transmission such as -filtering, timeouts, rate limits, and buffering. - -## Channel - -A named in-cluster Service on a Bus which accepts events delivered from a Feed. - -## Bus - -A system which routes events from Channels to subscribed Service endpoints. The -Broker MAY (RFC 2119) provide durable, at-least-once semantics and buffering of -events between the Source and the Action. Brokers also perform event fan-out -across multiple actions which are subscribed to the same channel. - - -## Subscription - -A control plane construct which allows the Bus to route events received on a -Channel to the subscribed Service. - -# Eventing - -TODO an overview of how these objects are created and perhaps the persona -expected to make each. From 3daacf0fc669cf3344fc36e8ea1c4e7d043d004b Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Thu, 26 Jul 2018 12:36:25 -0700 Subject: [PATCH 09/12] Update what a Flow is. --- docs/spec/overview.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 80034ceb2e1..6cb7f8e16b4 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -7,8 +7,7 @@ Knative Eventing API is grouped into _Channels_, _Feeds_ and _Flows_: * _Feeds_ bridge the event source into the eventing framework. -* _Flows_ are the higher order abstractions for eventing that use _Channels_ - and _Feeds_. +* _Flows_ abstract the path of an event from a source reaches an event consumer. Typically, _Feeds_ perform out-of-cluster provisioning, while _Channels_ are within-cluster management of event delivery. _Flows_ is a higher order wrapper From a25a23710e07085b2fc82ac6bbd61f9c6c2de1a3 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Thu, 26 Jul 2018 12:39:38 -0700 Subject: [PATCH 10/12] better wording. --- docs/spec/overview.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 6cb7f8e16b4..362d651addf 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -7,7 +7,8 @@ Knative Eventing API is grouped into _Channels_, _Feeds_ and _Flows_: * _Feeds_ bridge the event source into the eventing framework. -* _Flows_ abstract the path of an event from a source reaches an event consumer. +* _Flows_ abstract the path of an event from a source takes to reach an event + consumer. Typically, _Feeds_ perform out-of-cluster provisioning, while _Channels_ are within-cluster management of event delivery. _Flows_ is a higher order wrapper From 4fd65eedde1b11eb41e8dff6cc80e2d31a4f7053 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Fri, 3 Aug 2018 10:30:55 -0700 Subject: [PATCH 11/12] Clarify the roles of the resources a bit more. --- docs/spec/README.md | 6 ++--- docs/spec/images/overview-reference.dot | 12 ++++------ docs/spec/images/overview-reference.png | Bin 15111 -> 14651 bytes docs/spec/motivation.md | 26 +++++++++++++++++---- docs/spec/overview.md | 29 ++++++++++++++++++++---- 5 files changed, 54 insertions(+), 19 deletions(-) diff --git a/docs/spec/README.md b/docs/spec/README.md index 88c92d63953..1f1c33489dc 100644 --- a/docs/spec/README.md +++ b/docs/spec/README.md @@ -15,9 +15,9 @@ Docs in this directory: * [Motivation and goals](motivation.md) * [Resource type overview](overview.md) - - - + + + + +Knative Eventing has following principles: + +1. Services are loosely coupled during development and deployed independently + on a variety of platforms (Kubernetes, VMs, SaaS or FaaS). + +1. A producer can generate events before a consumer is listening, and a + consumer can express an interest in an event or class of events that is not + yet being produced. + +1. Services can be connected to create new applications + a. without modifying producer or consumer. + b. with the ability to select a specific subset of events from a particular + producer + +These primitives enable producing and consuming events adhering to the +[CloudEvents Specification](https://github.com/cloudevents/spec), in a +decoupled way. Kubernetes has no primitives related to event processing, yet this is an essential component in serverless workloads. Eventing introduces high-level diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 362d651addf..9dd1121e912 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -22,11 +22,15 @@ EventType and Feed: * **EventSource**, an archetype of an event producer. -* **EventType**, the schema for an event. +* **EventType**, the schema for an event. * **Feed**, the association between the output of an event producer to the input of an event consumer. +An example _Feeds_ setup: GitHub would be the _EventSource_, a Pull Request +notification would be the _EventType_ and the _Feed_ describes the _org/repo_, +credentials, the specific _EventType_ and the consumer of the _Feed_ events. + The primary resources in the Knative Eventing _Channels_ API are Channel, Subscription and Bus: @@ -35,12 +39,27 @@ Subscription and Bus: * **Bus**, an implementation of an event delivery mechanism. -* **Subscription**, an expressed interest in events to be delivered to a - service. +* **Subscription**, an expressed interest in events from a _Channel_ to be + delivered to an HTTP endpoint. + +An example _Channels_ setup: A _Channel_ has declared it is implemented by a +PubSubBusImpl. The PubSubBusImpl _Bus_ accepts input from an event producer +that is pushing events to the _Channel_. The _Bus_ also watches for +_Subscription_(s) on the _Channel_ and delivers the events accepted to the +consumer. + + +The _Flows_ API implements a single resource, Flow: + +* **Flow**, is an abstraction of the connection between an event producer to + the event consumer leveraging _Feed_s and _Channels_. + -The primary resources in the Knative Eventing _Flows_ API are Flow: +An example _Flows_ setup: The _Flow_ describes the same properties as the _Feed_ +except the target could be a _Service.serving.knative.dev_ and the _Flow_ will +create the _Channel_, _Feed_, and _Subscription_ for the event to flow from +event producer (GitHub) to event consumer (MyService). -* **Flow**, the connection between an event producer to the event consumer. ![Object Model](images/overview-reference.png) From ff909557bda56cf383a196b76e814168ed8af7d8 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Fri, 3 Aug 2018 10:31:58 -0700 Subject: [PATCH 12/12] Make the a. b. list work. --- docs/spec/motivation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/spec/motivation.md b/docs/spec/motivation.md index ce6e091a867..f1f6d4f2e58 100644 --- a/docs/spec/motivation.md +++ b/docs/spec/motivation.md @@ -15,9 +15,9 @@ Knative Eventing has following principles: yet being produced. 1. Services can be connected to create new applications - a. without modifying producer or consumer. - b. with the ability to select a specific subset of events from a particular - producer + * without modifying producer or consumer. + * with the ability to select a specific subset of events from a particular + producer These primitives enable producing and consuming events adhering to the [CloudEvents Specification](https://github.com/cloudevents/spec), in a