From d9471db455149d24922c3ce7a6554e6c517f5f57 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Thu, 28 Jun 2018 17:02:12 -0700 Subject: [PATCH 1/6] 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 2/6] 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 3/6] 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 4/6] 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 5/6] 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 6/6] 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