diff --git a/docs/spec/README.md b/docs/spec/README.md new file mode 100644 index 00000000000..fa32012aa55 --- /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 [`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 +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) + + + \ No newline at end of file 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 00000000000..08e3be1d5b7 Binary files /dev/null and b/docs/spec/images/overview-reference.png differ diff --git a/docs/spec/motivation.md b/docs/spec/motivation.md new file mode 100644 index 00000000000..191e235b454 --- /dev/null +++ b/docs/spec/motivation.md @@ -0,0 +1,17 @@ +# Motivation + +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 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 CloudEvents middleware and message consumers. + +The Knative Eventing APIs 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 new file mode 100644 index 00000000000..291e3d436af --- /dev/null +++ b/docs/spec/overview.md @@ -0,0 +1,78 @@ +# 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. + +* _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. + +# Resource Types + +The primary resources in the Knative Eventing _Feeds_ API are EventSource, EventType and Bind: + +* **EventSource**, an archetype of an event producer. + +* **EventType**, the schema for an event. + +* **Feed**, 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: + +* **Channel**, a named endpoint which accepts and forwards events. + +* **Bus**, an implementation of an event delivery mechanism. + +* **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 + +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.