From d89a84e04c849e97c6df7ee77df62d24e712e491 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 09:49:49 -0700 Subject: [PATCH 01/60] First port of spec doc to markdown. --- docs/spec/raw.md | 1263 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1263 insertions(+) create mode 100644 docs/spec/raw.md diff --git a/docs/spec/raw.md b/docs/spec/raw.md new file mode 100644 index 00000000000..6e016fe639a --- /dev/null +++ b/docs/spec/raw.md @@ -0,0 +1,1263 @@ +# Eventing Specification - v1alpha1 + +# Overview + +In the serverless model, computation and storage can be intertwined by having +storage and compute systems publish events which are handled asynchronously by +further compute services. Event delivery provides common infrastructure for +decoupling event producers and consumers such that the linking between them can +be performed without change to either. Loosely coupled eventing systems enable +composable services which retain the ability to scale independently. +Declarative event binding reduces the effort to create a scalable system that +combines managed services and custom code. + +Knative eventing implements common components of an event delivery ecosystem: +enumeration and discovery of event sources, configuration and management of +event transport, and declarative binding of events (generated either by storage +services or earlier computation) to further event processing and persistence. + +The following is a detailed specification for the `eventing.knative.dev` API +surface, which provides control mechanism for Knative eventing. + + +# Resource Types + +The eventing API defines several resource types as well as interfaces which may +be fulfilled by other Kubernetes objects (Callable, Subscribable, Channelable). +The API defines and provides a complete implementation for Flow, and abstract +resource definitions for Sources, Channels, and Providers which may be +fulfilled by multiple backing implementations (much like the Kubernetes Ingress +resource). + + * A **Subscription** describes the transformation of an event (via a + _Callable_) and optional storage of a returned event. + + * A **Source** represents an ongoing selection of events from an external + system. A Flow is used to connect these events to subsequent processing + steps. + + * A **Channel** provides event storage and fanout of events from a well-known + input address to multiple outputs described by Flows. + + + + * **Provisioners** act as a catalog of the types of Sources and Channels + currently active in the eventing system. + + + +## Subscription + +**Subscriptions** define the transport of events from one storage location +(typically, **Source** or **Channel**) to the next (typically, a **Channel**) +through optional transformations (such as a Knative Service which processes +CloudEvents over HTTP). A **Subscription** resolves the addresses of +transformations (`call`) and destination storage (`result`) through the +_Callable_ and _Sinkable_ interface contracts, and writes the resolved +addresses to the _Subscribable_ `from` resource. A **Subscriptions** do not +need to specify both a transformation and a storage destination, but at least +one must be provided. + +All event transport over a **Subscription** is 1:1 – only a single `from`, +`call`, and `result` may be provided. + +## Source + +**Source** represents an ongoing selection of events from an external system, +such as object creation events in a specific storage bucket, database updates +in a particular table, or Kubernetes resource state changes. Because a +**Source** represents an external system, it only produces events (and is +therefore _Subscribable_ by **Subscriptions**). **Source** configures an +external system and may include parameters such as specific resource names, +event types, or credentials which should be used to establish the connection to +the external system. The set of allowed configuration parameters is described +by the **Provisioner** which is referenced by the **Source**. + +Event selection on a **Source** is 1:N – a single **Source** may fan out to +multiple **Subscriptions**. + +## Channel + +**Channel** provides a durable event storage mechanism which can fan 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, + +## Provisioner + +The eventing API has parallel constructs for event _sources_ (systems which +create events based on internal or external changes) and event _transports_ +(middleware which add value to the event delivery chain, such as persistence or +buffering). + + +# Interface Contracts + + + +## Subscribable + +A **Subscribable** resource will emit events that a _Subscription_ can direct +to a _Targetable_ or _Sinkable_ resource. + +### Control Plane + +A **Subscribable** resource may be referenced in the _from_ section of a +_Flow_. The **Subscribable** resource MUST expose a _channel_ field (an +ObjectReference) in its _status_ section. This _channel_ field MUST be +_Channelable_, and _channel_ MAY refer back to the **Subscribable** resource. + +### Data Plane + +A **Subscribable** resource is an event producer or forwarder, events that it +produces or forwards are delivered via its _status.channel _resource. + +## Channelable + +A **Channelable** resource owns a list of subscribers for delivery of events. + +### Control Plane + +The **Channelable** resource has a list of _subscribers_ within the resources +_spec_. In practice, the resolved _subscription_ _call_ and _result_ endpoints +populate the Channelable's list of _subscribers_. + +### Data Plane + +**Channelable** resources will attempt delivery to each of they _subscribers_ +at least once, and retry if the callie returns errors. + +## Targetable + +A **Targetable** resource represents a unit of work to be done on/to/with an +event. They allow for event modification and flow control without taking +ownership of the event. Typically a **Targetable** is a function. + +### Control Plane + +A **Targetable** resource MUST expose a _targetable.domainInternal_ field in +its _status_ section. 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 does not ownership of the event that was passed to +it, but it is allowed to modify the event by returning a response code of 200 +and a mutated version back to the caller. The **Targetable** can prevent the +event from continuing to the next stage by returning 200 and an empty body. All +other response codes are considered an error and the caller will attempt to +call again. + +## Sinkable + +A **Sinkable** resource takes ownership of an event. Typically a **Sinkable** +is a Channel. + +### Control Plane + +A **Sinkable** resource MUST expose a _targetable.domainInternal_ field in its +_status_ section. 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_. + +### Data Plane + +A **Sinkable** resource will only respond to requests by ACK/NACK. It must not +return events to the caller. + + +# kind: Source + +## group: eventing.knative.dev/v1alpha1 + +_Describes a specific configuration (credentials, etc) of a source system which +can be used to supply events. Sources emit events using a channel specified in +their status. They cannot receive events._ + +## Object Schema + +### Spec + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
provisioner* + ProvisionerReference + The provisioner used to create any backing resources and configuration. + Immutable. +
arguments + runtime.RawExtension (JSON object) + Arguments passed to the provisioner for this specific source. + Arguments must validate against provisioner's parameters. +
channel + ObjectRef + Specify an existing channel to use to emit events. If empty, create a new Channel using the cluster/namespace default. + Source will not emit events until channel exists. +
+ +### Metadata + +#### Owner References + +* Owned by a Flow if created by a Flow. + +### Status + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
channel + ObjectReference + The channel used to emit events. + +
Subscribable + Subscribable + Pointer to a channel which can be subscribed to in order to receive events from this source. + +
provisioned + []ProvisionedObjectStatus + Creation status of each Channel and errors therein. + It is expected that a Source list all produced Channels. +
+ +#### Conditions + +* **Ready.** True when the Source is provisioned and ready to emit events. +* ** Provisioned.** True when the Source has been provisioned by a controller. + +### Events + +* Provisioned - describes each resource that is provisioned. + +## Life Cycle + + + + + + + + + + + + + + + + + + + + + + +
Action + Reactions + Limitations +
Create + Provisioner controller watches for Sources and creates the backing resources depending on implementation. + +
Update + Provisioner controller synchronizes backing implementation on changes. + +
Delete + Provisioner controller will deprovision backing resources depending on implementation. + Flow controller will recreate a Source after deletion if the Source originated from a Flow. +
+ +# kind: Channel + +## group: eventing.knative.dev/v1alpha1 + +_A Channel logically receives events on its input domain and forwards them to +its subscribers. Additional behavior may be introduced by using the +Subscription's call parameter._ + +## Object Schema + +### Spec + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
provisioner* + ProvisionerReference + The name of the provisioner to create the resources that back the Channel. + Immutable. +
arguments + runtime.RawExtension (JSON object) + Arguments to be passed to the provisioner. + +
channelable + Channelable + Holds a list of downstream subscribers for the channel. + +
eventTypes + []String + An array of event types that will be passed on the Channel. + Must be objects with kind:EventType. +
+ +### Metadata + +#### Owner References + +* If the Pipeline controller created this Channel: Owned by the originating Pipeline. +* Owned by the Provisioner used to provision the Channel. + +### Status + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
Sinkable + Sinkable + Address to + +
Subscribable + Subscribable + + +
Conditions + Conditions + Standard Subscriptions + +
+ +#### Conditions + +* **Ready.** True when the Channel is provisioned and ready to accept events. +* **Provisioned.** True when the Channel has been provisioned by a controller. + +### Events + +* Provisioned +* Deprovisioned + +## Life Cycle + + + + + + + + + + + + + + + + + + + + + + +
Action + Reactions + Limitations +
Create + The Provisioner referenced will take ownership of the Channel and begin provisioning the backing resources required for the Channel depending on implementation. + Only one Provisioner is allowed to be the Owner for a given Channel. +
Update + The Provisioner will synchronize the Channel backing resources to reflect the update. + +
Delete + The Provisioner will deprovision the backing resources if no longer required depending on implementation. + +
+ +# kind: Provisioner + +## group: eventing.knative.dev/v1alpha1 + +_Describes an abstract configuration of a Source system which produces events +or a Channel system that receives and delivers events._ + +## Object Schema + +### Spec + + + + + + + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
type* + TypeMeta1 + The type of the resource to be provisioned. + Must be Source or Channel. +
parameters + []ParameterSpec + Parameters are used for validation of arguments. + +
+ +1: Kubernetes type. + +### Metadata + +#### Owner References + +* Owns EventTypes. + +### Status + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
provisioned + []ProvisionedObjectStatus + Status of creation or adoption of each EventType and errors therein. + It is expected that a provisioner list all produced EventTypes, if applicable. +
+ +### Events + +* Source created +* Source deleted +* Event types installed + +## Life Cycle + + + + + + + + + + + + + + + + + + + + + + +
Action + Reactions + Limitations +
Create + Creates and owns EventTypes produced, or adds Owner ref to existing EventTypes. + Verifies Json Schema provided by existing EventTypes; Not allowed to edit EventType if previously Owned; +
Update + Synchronizes EventTypes. + +
Delete + Removes Owner ref from EventTypes. + +
+ +# kind: Subscription + +## group: eventing.knative.dev/v1alpha1 + +_Describes a direct linkage between an event publisher and an action._ + +## Object Schema + +### Spec + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
from* + ObjectRef + The originating Channel for the link. + Must be a Channel. +
filter + FilterSpec + Optional filter + +
call1 + EndpointSpec + Optional processing on the event. The result of call will be sent to result. + +
result1 + ObjectRef + The continuation Channel for the link. + Must be a Channel. +
+ +1: At Least One(call, result) + +### Metadata + +#### Owner References + +* If a resource controller created this Subscription: Owned by the originating resource. + +### Status + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
resolutions + SubscriptionResolutionsStatus + Resolved targets for the spec's call and continue fields. + +
+ +#### Conditions + +* **Ready.** True ~~when the publisher resource is also ready. +* **FromReady.** +* **CallActive. **True if the call is sinking events without error. +* **Resolved** + +### Events + +* PublisherAcknowledged +* ActionFailed + +## Life Cycle + + + + + + + + + + + + + + + + + + + + + + +
Action + Reactions + Limitations +
Create + The publisher referenced needs to be watching for Subscriptions. + +
Update + + +
Delete + + +
+ + + +# Shared Object Schema + + +## ProvisionerReference + + + + + + + + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
ref1 + ObjectReference + + +
selector1 + LabelSelector + + +
+ + +1: One of (name, selector), Required. + + +## EndpointSpec + + + + + + + + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
targetRef1 + ObjectReference + + Must adhere to Targetable. +
dnsName1 + String + + +
+ + +1: One of (targetRef, dnsName), Required. + + +## FilterSpec + + + + + + + + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
by + String + Uses Filter Language to specify which event should be passed on the link. + +
eventType* + EventTypeTrigger + A single event type trigger. + +
+ + + +## EventTypeTrigger + + + + + + + + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
name1 + String + Name of an event type. + Must be the name of a kind:EventType in the same namespace. +
selector1 + LabelSelector + a label selector + Limited to kind:EventType. +
+ + +1: OneOf(name, selector), Required. + + +## ArgumentSpec + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
name* + String + Name of the key. + +
value1 + String + Value. + +
valueFrom1 + ArgumentValueReference + Value retrieved from an existing Secret or ConfigMap. + +
+ + +1: OneOf (value, valueFrom), Required. + + +## ParameterSpec + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
name* + String + The unique name of this template parameter. + +
description + String + A human-readable explanation of this template parameter. + +
required + Boolean + If the parameter is required. + If true, default / defaultFrom should not be provided. Immutable. +
default1 + String + Default value if not provided by arguments. + +
defaultFrom1 + ArgumentValueReference + Default value retrieved from an existing Secret or ConfigMap if not provided by arguments. + +
+ + +1: OneOf (default, defaultFrom) + + +## ArgumentValueReference + + + + + + + + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
secretKeyRef1 + SecretReference + A reference to a value contained in a Secret at the given key. + +
configMapRef1 + ConfigMapReference + A reference to a value contained in a ConfigMap at the given key. + +
+ + +1: OneOf (secretKeyRef, configMapRef), Required. + + +## ProvisionedObjectStatus + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
name* + String + Name of Object + +
type* + String + Fully Qualified Object type. + +
status* + String + Current relationship between Provisioner and Object + +
reason + String + Detailed description describing current relationship status. + +
+ + + +## SubscriptionResolutionsStatus + + + + + + + + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
call + String + Resolved target for the spec's call field. Empty string if spec.call is nil. + Must be a domain name +
continue + String + Resolved target for the spec's continue field. Empty string if spec.continue is nil. + Must be a domain name +
+ + + +## Subscribable + + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
channelable + ObjectReference + The channel used to emit events. + +
+ + + +## Channelable + + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
subscribers + ChannelSubscriberSpec[] + Information about subscriptions used to implement message forwarding. + Filled out by Subscription Controller. +
+ + + +## ChannelSubscriberSpec + + + + + + + + + + + + + + + + + + + + + +
Field + Type + Description + Limitations +
callableDomain + String + The domain name of the endpoint for the call. + +
sinkableDomain + String + The domain name of the endpoint for the result. + +
+ + From f0930b9ef5db65066f2694b7a23dd3fd49bc67fd Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 09:57:16 -0700 Subject: [PATCH 02/60] trim unused objects. --- docs/spec/raw.md | 165 +---------------------------------------------- 1 file changed, 2 insertions(+), 163 deletions(-) diff --git a/docs/spec/raw.md b/docs/spec/raw.md index 6e016fe639a..6848858d900 100644 --- a/docs/spec/raw.md +++ b/docs/spec/raw.md @@ -1,3 +1,5 @@ + + # Eventing Specification - v1alpha1 # Overview @@ -635,16 +637,6 @@ _Describes a direct linkage between an event publisher and an action._ Must be a Channel. - - filter - - FilterSpec - - Optional filter - - - - call1 @@ -753,10 +745,8 @@ _Describes a direct linkage between an event publisher and an action._ # Shared Object Schema - ## ProvisionerReference -
Field @@ -790,13 +780,10 @@ _Describes a direct linkage between an event publisher and an action._
- 1: One of (name, selector), Required. - ## EndpointSpec -
Field @@ -830,141 +817,10 @@ _Describes a direct linkage between an event publisher and an action._
- 1: One of (targetRef, dnsName), Required. - -## FilterSpec - - - - - - - - - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
by - String - Uses Filter Language to specify which event should be passed on the link. - -
eventType* - EventTypeTrigger - A single event type trigger. - -
- - - -## EventTypeTrigger - - - - - - - - - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
name1 - String - Name of an event type. - Must be the name of a kind:EventType in the same namespace. -
selector1 - LabelSelector - a label selector - Limited to kind:EventType. -
- - -1: OneOf(name, selector), Required. - - -## ArgumentSpec - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
name* - String - Name of the key. - -
value1 - String - Value. - -
valueFrom1 - ArgumentValueReference - Value retrieved from an existing Secret or ConfigMap. - -
- - -1: OneOf (value, valueFrom), Required. - - ## ParameterSpec -
Field @@ -1028,13 +884,10 @@ _Describes a direct linkage between an event publisher and an action._
- 1: OneOf (default, defaultFrom) - ## ArgumentValueReference -
Field @@ -1068,13 +921,10 @@ _Describes a direct linkage between an event publisher and an action._
- 1: OneOf (secretKeyRef, configMapRef), Required. - ## ProvisionedObjectStatus -
Field @@ -1128,8 +978,6 @@ _Describes a direct linkage between an event publisher and an action._
- - ## SubscriptionResolutionsStatus @@ -1166,11 +1014,8 @@ _Describes a direct linkage between an event publisher and an action._ - - ## Subscribable -
Field @@ -1194,11 +1039,8 @@ _Describes a direct linkage between an event publisher and an action._
- - ## Channelable -
Field @@ -1222,11 +1064,8 @@ _Describes a direct linkage between an event publisher and an action._
- - ## ChannelSubscriberSpec -
Field From 1e1607ad8877cb5ff2699739af19a0849caa2712 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 09:58:39 -0700 Subject: [PATCH 03/60] start using mrkdown tables. --- docs/spec/raw.md | 61 ++++++------------------------------------------ 1 file changed, 7 insertions(+), 54 deletions(-) diff --git a/docs/spec/raw.md b/docs/spec/raw.md index 6848858d900..ff89e2bb579 100644 --- a/docs/spec/raw.md +++ b/docs/spec/raw.md @@ -1041,62 +1041,15 @@ _Describes a direct linkage between an event publisher and an action._ ## Channelable - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
subscribers - ChannelSubscriberSpec[] - Information about subscriptions used to implement message forwarding. - Filled out by Subscription Controller. -
+|--- |--- |--- |--- | +|Field|Type|Description|Limitations| +|subscribers|ChannelSubscriberSpec[]|Information about subscriptions used to implement message forwarding.|Filled out by Subscription Controller.| ## ChannelSubscriberSpec - - - - - - - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
callableDomain - String - The domain name of the endpoint for the call. - -
sinkableDomain - String - The domain name of the endpoint for the result. - -
+|--- |--- |--- |--- | +|Field|Type|Description|Limitations| +|callableDomain|String|The domain name of the endpoint for the call.|| +|sinkableDomain|String|The domain name of the endpoint for the result.|| From 0558eab47f8f939bf3febcebd205e7c9c74e509c Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 09:59:40 -0700 Subject: [PATCH 04/60] more meta for tables. --- docs/spec/raw.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/spec/raw.md b/docs/spec/raw.md index ff89e2bb579..acdaa58c535 100644 --- a/docs/spec/raw.md +++ b/docs/spec/raw.md @@ -1041,12 +1041,14 @@ _Describes a direct linkage between an event publisher and an action._ ## Channelable +||||| |--- |--- |--- |--- | |Field|Type|Description|Limitations| |subscribers|ChannelSubscriberSpec[]|Information about subscriptions used to implement message forwarding.|Filled out by Subscription Controller.| ## ChannelSubscriberSpec +||||| |--- |--- |--- |--- | |Field|Type|Description|Limitations| |callableDomain|String|The domain name of the endpoint for the call.|| From f0fdc6950cd2dbb90e3d3a45f64ac1d85024fffd Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 10:11:44 -0700 Subject: [PATCH 05/60] passed at making tables md style. --- docs/spec/raw.md | 800 ++++++----------------------------------------- 1 file changed, 95 insertions(+), 705 deletions(-) diff --git a/docs/spec/raw.md b/docs/spec/raw.md index acdaa58c535..ee9f81edafd 100644 --- a/docs/spec/raw.md +++ b/docs/spec/raw.md @@ -182,48 +182,11 @@ their status. They cannot receive events._ ### Spec - - - - - - - - - - - - - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
provisioner* - ProvisionerReference - The provisioner used to create any backing resources and configuration. - Immutable. -
arguments - runtime.RawExtension (JSON object) - Arguments passed to the provisioner for this specific source. - Arguments must validate against provisioner's parameters. -
channel - ObjectRef - Specify an existing channel to use to emit events. If empty, create a new Channel using the cluster/namespace default. - Source will not emit events until channel exists. -
+| Field | Type | Description | Limitations | +| --- | --- | --- | --- | +|provisioner*|ProvisionerReference|The provisioner used to create any backing resources and configuration.|Immutable.| +|arguments|runtime.RawExtension (JSON object)|Arguments passed to the provisioner for this specific source.|Arguments must validate against provisioner's parameters.| +|channel|ObjectRef|Specify an existing channel to use to emit events. If empty, create a new Channel using the cluster/namespace default.|Source will not emit events until channel exists.| ### Metadata @@ -233,48 +196,12 @@ their status. They cannot receive events._ ### Status - - - - - - - - - - - - - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
channel - ObjectReference - The channel used to emit events. - -
Subscribable - Subscribable - Pointer to a channel which can be subscribed to in order to receive events from this source. - -
provisioned - []ProvisionedObjectStatus - Creation status of each Channel and errors therein. - It is expected that a Source list all produced Channels. -
+| Field | Type | Description | Limitations | +| --- | --- | --- | --- | +|channel|ObjectReference|The channel used to emit events.|| +|Subscribable|Subscribable|Pointer to a channel which can be subscribed to in order to receive events from this source.|| +|provisioned|[]ProvisionedObjectStatus|Creation status of each Channel and errors therein.|It is expected that a Source list all produced Channels.| + #### Conditions @@ -287,40 +214,11 @@ their status. They cannot receive events._ ## Life Cycle - - - - - - - - - - - - - - - - - - - - - -
Action - Reactions - Limitations -
Create - Provisioner controller watches for Sources and creates the backing resources depending on implementation. - -
Update - Provisioner controller synchronizes backing implementation on changes. - -
Delete - Provisioner controller will deprovision backing resources depending on implementation. - Flow controller will recreate a Source after deletion if the Source originated from a Flow. -
+| Action | Reactions | Limitations | +| --- | --- | --- | +|Create|Provisioner controller watches for Sources and creates the backing resources depending on implementation.|| +|Update|Provisioner controller synchronizes backing implementation on changes.|| +|Delete|Provisioner controller will deprovision backing resources depending on implementation.|Flow controller will recreate a Source after deletion if the Source originated from a Flow.| # kind: Channel @@ -334,58 +232,12 @@ Subscription's call parameter._ ### Spec - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
provisioner* - ProvisionerReference - The name of the provisioner to create the resources that back the Channel. - Immutable. -
arguments - runtime.RawExtension (JSON object) - Arguments to be passed to the provisioner. - -
channelable - Channelable - Holds a list of downstream subscribers for the channel. - -
eventTypes - []String - An array of event types that will be passed on the Channel. - Must be objects with kind:EventType. -
+| Field | Type | Description | Limitations | +| --- | --- | --- | --- | +|provisioner*|ProvisionerReference|The name of the provisioner to create the resources that back the Channel.|Immutable.| +|arguments|runtime.RawExtension (JSON object)|Arguments to be passed to the provisioner.|| +|channelable|Channelable|Holds a list of downstream subscribers for the channel.|| +|eventTypes|[]String|An array of event types that will be passed on the Channel.|Must be objects with kind:EventType.| ### Metadata @@ -396,48 +248,11 @@ Subscription's call parameter._ ### Status - - - - - - - - - - - - - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
Sinkable - Sinkable - Address to - -
Subscribable - Subscribable - - -
Conditions - Conditions - Standard Subscriptions - -
+| Field | Type | Description | Limitations | +| --- | --- | --- | --- | +|Sinkable|Sinkable|Address to|| +|Subscribable|Subscribable||| +|Conditions|Conditions|Standard Subscriptions|| #### Conditions @@ -451,40 +266,11 @@ Subscription's call parameter._ ## Life Cycle - - - - - - - - - - - - - - - - - - - - - -
Action - Reactions - Limitations -
Create - The Provisioner referenced will take ownership of the Channel and begin provisioning the backing resources required for the Channel depending on implementation. - Only one Provisioner is allowed to be the Owner for a given Channel. -
Update - The Provisioner will synchronize the Channel backing resources to reflect the update. - -
Delete - The Provisioner will deprovision the backing resources if no longer required depending on implementation. - -
+| Action | Reactions | Limitations | +| --- | --- | --- | +|Create|The Provisioner referenced will take ownership of the Channel and begin provisioning the backing resources required for the Channel depending on implementation.|Only one Provisioner is allowed to be the Owner for a given Channel.| +|Update|The Provisioner will synchronize the Channel backing resources to reflect the update.|| +|Delete|The Provisioner will deprovision the backing resources if no longer required depending on implementation.|| # kind: Provisioner @@ -497,38 +283,11 @@ or a Channel system that receives and delivers events._ ### Spec - - - - - - - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
type* - TypeMeta1 - The type of the resource to be provisioned. - Must be Source or Channel. -
parameters - []ParameterSpec - Parameters are used for validation of arguments. - -
+| Field | Type | Description | Limitations | +| --- | --- | --- | --- | +|Field|Type|Description|Limitations| +|type*|TypeMeta1|The type of the resource to be provisioned.|Must be Source or Channel.| +|parameters|[]ParameterSpec|Parameters are used for validation of arguments.|| 1: Kubernetes type. @@ -540,28 +299,9 @@ or a Channel system that receives and delivers events._ ### Status - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
provisioned - []ProvisionedObjectStatus - Status of creation or adoption of each EventType and errors therein. - It is expected that a provisioner list all produced EventTypes, if applicable. -
+| Field | Type | Description | Limitations | +| --- | --- | --- | --- | +|provisioned|[]ProvisionedObjectStatus|Status of creation or adoption of each EventType and errors therein.|It is expected that a provisioner list all produced EventTypes, if applicable.| ### Events @@ -571,40 +311,11 @@ or a Channel system that receives and delivers events._ ## Life Cycle - - - - - - - - - - - - - - - - - - - - - -
Action - Reactions - Limitations -
Create - Creates and owns EventTypes produced, or adds Owner ref to existing EventTypes. - Verifies Json Schema provided by existing EventTypes; Not allowed to edit EventType if previously Owned; -
Update - Synchronizes EventTypes. - -
Delete - Removes Owner ref from EventTypes. - -
+| Action | Reactions | Limitations | +| --- | --- | --- | +|Create|Creates and owns EventTypes produced, or adds Owner ref to existing EventTypes.|Verifies Json Schema provided by existing EventTypes; Not allowed to edit EventType if previously Owned;| +|Update|Synchronizes EventTypes.|| +|Delete|Removes Owner ref from EventTypes.|| # kind: Subscription @@ -616,48 +327,12 @@ _Describes a direct linkage between an event publisher and an action._ ### Spec - - - - - - - - - - - - - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
from* - ObjectRef - The originating Channel for the link. - Must be a Channel. -
call1 - EndpointSpec - Optional processing on the event. The result of call will be sent to result. - -
result1 - ObjectRef - The continuation Channel for the link. - Must be a Channel. -
+| Field | Type | Description | Limitations | +| --- | --- | --- | --- | +|Field|Type|Description|Limitations| +|from*|ObjectRef|The originating Channel for the link.|Must be a Channel.| +|call1|EndpointSpec|Optional processing on the event. The result of call will be sent to result.|| +|result1|ObjectRef|The continuation Channel for the link.|Must be a Channel.| 1: At Least One(call, result) @@ -669,28 +344,9 @@ _Describes a direct linkage between an event publisher and an action._ ### Status - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
resolutions - SubscriptionResolutionsStatus - Resolved targets for the spec's call and continue fields. - -
+| Field | Type | Description | Limitations | +| --- | --- | --- | --- | +|resolutions|SubscriptionResolutionsStatus|Resolved targets for the spec's call and continue fields.|| #### Conditions @@ -706,351 +362,85 @@ _Describes a direct linkage between an event publisher and an action._ ## Life Cycle - - - - - - - - - - - - - - - - - - - - - -
Action - Reactions - Limitations -
Create - The publisher referenced needs to be watching for Subscriptions. - -
Update - - -
Delete - - -
- - +| Action | Reactions | Limitations | +| --- | --- | --- | +|Create|The publisher referenced needs to be watching for Subscriptions.|| +|Update||| +|Delete||| # Shared Object Schema ## ProvisionerReference - - - - - - - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
ref1 - ObjectReference - - -
selector1 - LabelSelector - - -
+| Field | Type | Description | Limitations | +| --- | --- | --- | --- | +|ref1|ObjectReference||| +|selector1|LabelSelector||| 1: One of (name, selector), Required. ## EndpointSpec - - - - - - - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
targetRef1 - ObjectReference - - Must adhere to Targetable. -
dnsName1 - String - - -
+| Field | Type | Description | Limitations | +| --- | --- | --- | --- | +|targetRef1|ObjectReference||Must adhere to Targetable.| +|dnsName1|String||| 1: One of (targetRef, dnsName), Required. ## ParameterSpec - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
name* - String - The unique name of this template parameter. - -
description - String - A human-readable explanation of this template parameter. - -
required - Boolean - If the parameter is required. - If true, default / defaultFrom should not be provided. Immutable. -
default1 - String - Default value if not provided by arguments. - -
defaultFrom1 - ArgumentValueReference - Default value retrieved from an existing Secret or ConfigMap if not provided by arguments. - -
+| Field | Type | Description | Limitations | +| --- | --- | --- | --- | +|name*|String|The unique name of this template parameter.|| +|description|String|A human-readable explanation of this template parameter.|| +|required|Boolean|If the parameter is required.|If true, default / defaultFrom should not be provided. Immutable.| +|default1|String|Default value if not provided by arguments.|| +|defaultFrom1|ArgumentValueReference|Default value retrieved from an existing Secret or ConfigMap if not provided by arguments.|| 1: OneOf (default, defaultFrom) ## ArgumentValueReference - - - - - - - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
secretKeyRef1 - SecretReference - A reference to a value contained in a Secret at the given key. - -
configMapRef1 - ConfigMapReference - A reference to a value contained in a ConfigMap at the given key. - -
+| Field | Type | Description | Limitations | +| --- | --- | --- | --- | +|secretKeyRef1|SecretReference|A reference to a value contained in a Secret at the given key.|| +|configMapRef1|ConfigMapReference|A reference to a value contained in a ConfigMap at the given key.|| 1: OneOf (secretKeyRef, configMapRef), Required. ## ProvisionedObjectStatus - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
name* - String - Name of Object - -
type* - String - Fully Qualified Object type. - -
status* - String - Current relationship between Provisioner and Object - -
reason - String - Detailed description describing current relationship status. - -
+| Field | Type | Description | Limitations | +| --- | --- | --- | --- | +|name*|String|Name of Object|| +|type*|String|Fully Qualified Object type.|| +|status*|String|Current relationship between Provisioner and Object|| +|reason|String|Detailed description describing current relationship status.|| ## SubscriptionResolutionsStatus - - - - - - - - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
call - String - Resolved target for the spec's call field. Empty string if spec.call is nil. - Must be a domain name -
continue - String - Resolved target for the spec's continue field. Empty string if spec.continue is nil. - Must be a domain name -
+| Field | Type | Description | Limitations | +| --- | --- | --- | --- | +|call|String|Resolved target for the spec's call field. Empty string if spec.call is nil.|Must be a domain name| +|continue|String|Resolved target for the spec's continue field. Empty string if spec.continue is nil.|Must be a domain name| ## Subscribable - - - - - - - - - - - - - -
Field - Type - Description - Limitations -
channelable - ObjectReference - The channel used to emit events. - -
+| Field | Type | Description | Limitations | +| --- | --- | --- | --- | +|channelable|ObjectReference|The channel used to emit events.|| ## Channelable -||||| -|--- |--- |--- |--- | -|Field|Type|Description|Limitations| +| Field | Type | Description | Limitations | +| --- | --- | --- | --- | |subscribers|ChannelSubscriberSpec[]|Information about subscriptions used to implement message forwarding.|Filled out by Subscription Controller.| ## ChannelSubscriberSpec -||||| -|--- |--- |--- |--- | -|Field|Type|Description|Limitations| +| Field | Type | Description | Limitations | +| --- | --- | --- | --- | |callableDomain|String|The domain name of the endpoint for the call.|| |sinkableDomain|String|The domain name of the endpoint for the result.|| From e5d8eaa68f589a16364d73b6c5b41b947ce1bab8 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 10:30:16 -0700 Subject: [PATCH 06/60] Adding formatting to the markdown tables. --- docs/spec/raw.md | 110 +++++++++++++++++++++++------------------------ 1 file changed, 54 insertions(+), 56 deletions(-) diff --git a/docs/spec/raw.md b/docs/spec/raw.md index ee9f81edafd..af3893a766d 100644 --- a/docs/spec/raw.md +++ b/docs/spec/raw.md @@ -1,4 +1,4 @@ - + # Eventing Specification - v1alpha1 @@ -184,9 +184,9 @@ their status. They cannot receive events._ | Field | Type | Description | Limitations | | --- | --- | --- | --- | -|provisioner*|ProvisionerReference|The provisioner used to create any backing resources and configuration.|Immutable.| -|arguments|runtime.RawExtension (JSON object)|Arguments passed to the provisioner for this specific source.|Arguments must validate against provisioner's parameters.| -|channel|ObjectRef|Specify an existing channel to use to emit events. If empty, create a new Channel using the cluster/namespace default.|Source will not emit events until channel exists.| +| provisioner*| ProvisionerReference | The provisioner used to create any backing resources and configuration. | Immutable. | +| arguments | runtime.RawExtension (JSON object)| Arguments passed to the provisioner for this specific source. | Arguments must validate against provisioner's parameters. | +| channel | ObjectRef | Specify an existing channel to use to emit events. If empty, create a new Channel using the cluster/namespace default. | Source will not emit events until channel exists. | ### Metadata @@ -198,9 +198,9 @@ their status. They cannot receive events._ | Field | Type | Description | Limitations | | --- | --- | --- | --- | -|channel|ObjectReference|The channel used to emit events.|| -|Subscribable|Subscribable|Pointer to a channel which can be subscribed to in order to receive events from this source.|| -|provisioned|[]ProvisionedObjectStatus|Creation status of each Channel and errors therein.|It is expected that a Source list all produced Channels.| +| channel | ObjectReference | The channel used to emit events. | | +| Subscribable | Subscribable | Pointer to a channel which can be subscribed to in order to receive events from this source. | | +| provisioned |[]ProvisionedObjectStatus| Creation status of each Channel and errors therein. | It is expected that a Source list all produced Channels. | #### Conditions @@ -216,9 +216,9 @@ their status. They cannot receive events._ | Action | Reactions | Limitations | | --- | --- | --- | -|Create|Provisioner controller watches for Sources and creates the backing resources depending on implementation.|| -|Update|Provisioner controller synchronizes backing implementation on changes.|| -|Delete|Provisioner controller will deprovision backing resources depending on implementation.|Flow controller will recreate a Source after deletion if the Source originated from a Flow.| +| Create | Provisioner controller watches for Sources and creates the backing resources depending on implementation. | | +| Update | Provisioner controller synchronizes backing implementation on changes. | | +| Delete | Provisioner controller will deprovision backing resources depending on implementation. | Flow controller will recreate a Source after deletion if the Source originated from a Flow. | # kind: Channel @@ -234,10 +234,10 @@ Subscription's call parameter._ | Field | Type | Description | Limitations | | --- | --- | --- | --- | -|provisioner*|ProvisionerReference|The name of the provisioner to create the resources that back the Channel.|Immutable.| -|arguments|runtime.RawExtension (JSON object)|Arguments to be passed to the provisioner.|| -|channelable|Channelable|Holds a list of downstream subscribers for the channel.|| -|eventTypes|[]String|An array of event types that will be passed on the Channel.|Must be objects with kind:EventType.| +| provisioner*| ProvisionerReference | The name of the provisioner to create the resources that back the Channel. | Immutable. | +| arguments | runtime.RawExtension (JSON object)| Arguments to be passed to the provisioner. | | +| channelable | Channelable | Holds a list of downstream subscribers for the channel. | | +| eventTypes |[]String| An array of event types that will be passed on the Channel. | Must be objects with kind:EventType. | ### Metadata @@ -250,9 +250,9 @@ Subscription's call parameter._ | Field | Type | Description | Limitations | | --- | --- | --- | --- | -|Sinkable|Sinkable|Address to|| -|Subscribable|Subscribable||| -|Conditions|Conditions|Standard Subscriptions|| +| Sinkable | Sinkable | Address to the endpoint as top-level domain that will distribute traffic over the provided targets from inside the cluster. | | +| Subscribable | Subscribable | | | +| Conditions | Conditions | Standard Subscriptions| | #### Conditions @@ -268,9 +268,9 @@ Subscription's call parameter._ | Action | Reactions | Limitations | | --- | --- | --- | -|Create|The Provisioner referenced will take ownership of the Channel and begin provisioning the backing resources required for the Channel depending on implementation.|Only one Provisioner is allowed to be the Owner for a given Channel.| -|Update|The Provisioner will synchronize the Channel backing resources to reflect the update.|| -|Delete|The Provisioner will deprovision the backing resources if no longer required depending on implementation.|| +| Create | The Provisioner referenced will take ownership of the Channel and begin provisioning the backing resources required for the Channel depending on implementation. | Only one Provisioner is allowed to be the Owner for a given Channel. | +| Update | The Provisioner will synchronize the Channel backing resources to reflect the update. | | +| Delete | The Provisioner will deprovision the backing resources if no longer required depending on implementation. | | # kind: Provisioner @@ -285,9 +285,8 @@ or a Channel system that receives and delivers events._ | Field | Type | Description | Limitations | | --- | --- | --- | --- | -|Field|Type|Description|Limitations| -|type*|TypeMeta1|The type of the resource to be provisioned.|Must be Source or Channel.| -|parameters|[]ParameterSpec|Parameters are used for validation of arguments.|| +| type*| TypeMeta1 | The type of the resource to be provisioned. | Must be Source or Channel. | +| parameters |[]ParameterSpec| Parameters are used for validation of arguments. | | 1: Kubernetes type. @@ -301,7 +300,7 @@ or a Channel system that receives and delivers events._ | Field | Type | Description | Limitations | | --- | --- | --- | --- | -|provisioned|[]ProvisionedObjectStatus|Status of creation or adoption of each EventType and errors therein.|It is expected that a provisioner list all produced EventTypes, if applicable.| +| provisioned |[]ProvisionedObjectStatus| Status of creation or adoption of each EventType and errors therein. | It is expected that a provisioner list all produced EventTypes, if applicable. | ### Events @@ -313,9 +312,9 @@ or a Channel system that receives and delivers events._ | Action | Reactions | Limitations | | --- | --- | --- | -|Create|Creates and owns EventTypes produced, or adds Owner ref to existing EventTypes.|Verifies Json Schema provided by existing EventTypes; Not allowed to edit EventType if previously Owned;| -|Update|Synchronizes EventTypes.|| -|Delete|Removes Owner ref from EventTypes.|| +| Create | Creates and owns EventTypes produced, or adds Owner ref to existing EventTypes. | Verifies Json Schema provided by existing EventTypes; Not allowed to edit EventType if previously Owned; | +| Update | Synchronizes EventTypes. | | +| Delete | Removes Owner ref from EventTypes. | | # kind: Subscription @@ -329,10 +328,9 @@ _Describes a direct linkage between an event publisher and an action._ | Field | Type | Description | Limitations | | --- | --- | --- | --- | -|Field|Type|Description|Limitations| -|from*|ObjectRef|The originating Channel for the link.|Must be a Channel.| -|call1|EndpointSpec|Optional processing on the event. The result of call will be sent to result.|| -|result1|ObjectRef|The continuation Channel for the link.|Must be a Channel.| +| from*| ObjectRef | The originating Channel for the link. | Must be a Channel. | +| call1 | EndpointSpec | Optional processing on the event. The result of call will be sent to result. | | +| result1 | ObjectRef | The continuation Channel for the link. | Must be a Channel. | 1: At Least One(call, result) @@ -346,7 +344,7 @@ _Describes a direct linkage between an event publisher and an action._ | Field | Type | Description | Limitations | | --- | --- | --- | --- | -|resolutions|SubscriptionResolutionsStatus|Resolved targets for the spec's call and continue fields.|| +| resolutions | SubscriptionResolutionsStatus | Resolved targets for the spec's call and continue fields. | | #### Conditions @@ -364,9 +362,9 @@ _Describes a direct linkage between an event publisher and an action._ | Action | Reactions | Limitations | | --- | --- | --- | -|Create|The publisher referenced needs to be watching for Subscriptions.|| -|Update||| -|Delete||| +| Create | The publisher referenced needs to be watching for Subscriptions. | | +| Update | | | +| Delete | | | # Shared Object Schema @@ -374,8 +372,8 @@ _Describes a direct linkage between an event publisher and an action._ | Field | Type | Description | Limitations | | --- | --- | --- | --- | -|ref1|ObjectReference||| -|selector1|LabelSelector||| +| ref1 | ObjectReference | | | +| selector1 | LabelSelector | | | 1: One of (name, selector), Required. @@ -383,8 +381,8 @@ _Describes a direct linkage between an event publisher and an action._ | Field | Type | Description | Limitations | | --- | --- | --- | --- | -|targetRef1|ObjectReference||Must adhere to Targetable.| -|dnsName1|String||| +| targetRef1 | ObjectReference | | Must adhere to Targetable. | +| dnsName1 | String | | | 1: One of (targetRef, dnsName), Required. @@ -392,11 +390,11 @@ _Describes a direct linkage between an event publisher and an action._ | Field | Type | Description | Limitations | | --- | --- | --- | --- | -|name*|String|The unique name of this template parameter.|| -|description|String|A human-readable explanation of this template parameter.|| -|required|Boolean|If the parameter is required.|If true, default / defaultFrom should not be provided. Immutable.| -|default1|String|Default value if not provided by arguments.|| -|defaultFrom1|ArgumentValueReference|Default value retrieved from an existing Secret or ConfigMap if not provided by arguments.|| +| name*| String | The unique name of this template parameter. | | +| description | String | A human-readable explanation of this template parameter. | | +| required | Boolean | If the parameter is required. | If true, default / defaultFrom should not be provided. Immutable. | +| default1 | String | Default value if not provided by arguments. | | +| defaultFrom1 | ArgumentValueReference | Default value retrieved from an existing Secret or ConfigMap if not provided by arguments. | | 1: OneOf (default, defaultFrom) @@ -404,8 +402,8 @@ _Describes a direct linkage between an event publisher and an action._ | Field | Type | Description | Limitations | | --- | --- | --- | --- | -|secretKeyRef1|SecretReference|A reference to a value contained in a Secret at the given key.|| -|configMapRef1|ConfigMapReference|A reference to a value contained in a ConfigMap at the given key.|| +| secretKeyRef1 | SecretReference | A reference to a value contained in a Secret at the given key. | | +| configMapRef1 | ConfigMapReference | A reference to a value contained in a ConfigMap at the given key. | | 1: OneOf (secretKeyRef, configMapRef), Required. @@ -413,35 +411,35 @@ _Describes a direct linkage between an event publisher and an action._ | Field | Type | Description | Limitations | | --- | --- | --- | --- | -|name*|String|Name of Object|| -|type*|String|Fully Qualified Object type.|| -|status*|String|Current relationship between Provisioner and Object|| -|reason|String|Detailed description describing current relationship status.|| +| name*| String | Name of Object| | +| type*| String | Fully Qualified Object type. | | +| status*| String | Current relationship between Provisioner and Object| | +| reason | String | Detailed description describing current relationship status. | | ## SubscriptionResolutionsStatus | Field | Type | Description | Limitations | | --- | --- | --- | --- | -|call|String|Resolved target for the spec's call field. Empty string if spec.call is nil.|Must be a domain name| -|continue|String|Resolved target for the spec's continue field. Empty string if spec.continue is nil.|Must be a domain name| +| call | String | Resolved target for the spec's call field. Empty string if spec.call is nil. | Must be a domain name | +| continue | String | Resolved target for the spec's continue field. Empty string if spec.continue is nil. | Must be a domain name | ## Subscribable | Field | Type | Description | Limitations | | --- | --- | --- | --- | -|channelable|ObjectReference|The channel used to emit events.|| +| channelable | ObjectReference | The channel used to emit events. | | ## Channelable | Field | Type | Description | Limitations | | --- | --- | --- | --- | -|subscribers|ChannelSubscriberSpec[]|Information about subscriptions used to implement message forwarding.|Filled out by Subscription Controller.| +| subscribers | ChannelSubscriberSpec[]| Information about subscriptions used to implement message forwarding. | Filled out by Subscription Controller. | ## ChannelSubscriberSpec | Field | Type | Description | Limitations | | --- | --- | --- | --- | -|callableDomain|String|The domain name of the endpoint for the call.|| -|sinkableDomain|String|The domain name of the endpoint for the result.|| +| callableDomain | String | The domain name of the endpoint for the call. | | +| sinkableDomain | String | The domain name of the endpoint for the result. | | From ffaea554a0a0d230d3f64d93ce97d246ec05500c Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 10:38:10 -0700 Subject: [PATCH 07/60] minor formatting. --- docs/spec/raw.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/spec/raw.md b/docs/spec/raw.md index af3893a766d..2bb48d1179a 100644 --- a/docs/spec/raw.md +++ b/docs/spec/raw.md @@ -113,7 +113,7 @@ _Channelable_, and _channel_ MAY refer back to the **Subscribable** resource. ### Data Plane A **Subscribable** resource is an event producer or forwarder, events that it -produces or forwards are delivered via its _status.channel _resource. +produces or forwards are delivered via its _status.channel_ resource. ## Channelable @@ -202,7 +202,6 @@ their status. They cannot receive events._ | Subscribable | Subscribable | Pointer to a channel which can be subscribed to in order to receive events from this source. | | | provisioned |[]ProvisionedObjectStatus| Creation status of each Channel and errors therein. | It is expected that a Source list all produced Channels. | - #### Conditions * **Ready.** True when the Source is provisioned and ready to emit events. From 69eb6de2a294594c0ec4a829357550ed4a86b180 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 10:42:37 -0700 Subject: [PATCH 08/60] Make required clear. --- docs/spec/raw.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/spec/raw.md b/docs/spec/raw.md index 2bb48d1179a..d70a22276bf 100644 --- a/docs/spec/raw.md +++ b/docs/spec/raw.md @@ -140,8 +140,8 @@ ownership of the event. Typically a **Targetable** is a function. A **Targetable** resource MUST expose a _targetable.domainInternal_ field in its _status_ section. 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_. +that is capable of receiving event deliveries. **Targetable** resources may be +referenced in the _call_ section of a _Subscription_. ### Data Plane @@ -188,6 +188,8 @@ their status. They cannot receive events._ | arguments | runtime.RawExtension (JSON object)| Arguments passed to the provisioner for this specific source. | Arguments must validate against provisioner's parameters. | | channel | ObjectRef | Specify an existing channel to use to emit events. If empty, create a new Channel using the cluster/namespace default. | Source will not emit events until channel exists. | +\*: Required + ### Metadata #### Owner References @@ -238,6 +240,8 @@ Subscription's call parameter._ | channelable | Channelable | Holds a list of downstream subscribers for the channel. | | | eventTypes |[]String| An array of event types that will be passed on the Channel. | Must be objects with kind:EventType. | +\*: Required + ### Metadata #### Owner References @@ -287,6 +291,7 @@ or a Channel system that receives and delivers events._ | type*| TypeMeta1 | The type of the resource to be provisioned. | Must be Source or Channel. | | parameters |[]ParameterSpec| Parameters are used for validation of arguments. | | +\*: Required 1: Kubernetes type. ### Metadata @@ -331,6 +336,7 @@ _Describes a direct linkage between an event publisher and an action._ | call1 | EndpointSpec | Optional processing on the event. The result of call will be sent to result. | | | result1 | ObjectRef | The continuation Channel for the link. | Must be a Channel. | +\*: Required 1: At Least One(call, result) ### Metadata @@ -395,6 +401,7 @@ _Describes a direct linkage between an event publisher and an action._ | default1 | String | Default value if not provided by arguments. | | | defaultFrom1 | ArgumentValueReference | Default value retrieved from an existing Secret or ConfigMap if not provided by arguments. | | +\*: Required 1: OneOf (default, defaultFrom) ## ArgumentValueReference @@ -415,6 +422,8 @@ _Describes a direct linkage between an event publisher and an action._ | status*| String | Current relationship between Provisioner and Object| | | reason | String | Detailed description describing current relationship status. | | +\*: Required + ## SubscriptionResolutionsStatus | Field | Type | Description | Limitations | From 9b977cf2ec3532217f4e787adf2e6d5f14111fd8 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 10:47:20 -0700 Subject: [PATCH 09/60] Adding links. --- docs/spec/raw.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/spec/raw.md b/docs/spec/raw.md index d70a22276bf..19522100485 100644 --- a/docs/spec/raw.md +++ b/docs/spec/raw.md @@ -25,11 +25,12 @@ surface, which provides control mechanism for Knative eventing. # Resource Types The eventing API defines several resource types as well as interfaces which may -be fulfilled by other Kubernetes objects (Callable, Subscribable, Channelable). -The API defines and provides a complete implementation for Flow, and abstract -resource definitions for Sources, Channels, and Providers which may be -fulfilled by multiple backing implementations (much like the Kubernetes Ingress -resource). +be fulfilled by other Kubernetes objects ([Callable](#callable), [Subscribable](#subscribable), [Channelable](#channelable), [Targetable](#targetable)). +The API defines and provides a complete implementation for +[Subscription](#kind-subscription), and abstract resource definitions for +[Sources](#kind-source), [Channels](#kind-channel), and +[Providers](#kind-provisioner) which may be fulfilled by multiple backing +implementations (much like the Kubernetes Ingress resource). * A **Subscription** describes the transformation of an event (via a _Callable_) and optional storage of a returned event. From 469ea51f28a4d4d37d5c8158afb717ea3760db31 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 10:49:41 -0700 Subject: [PATCH 10/60] add spacing because markdown. --- docs/spec/raw.md | 56 +++++++++++++++++++++++++----------------------- 1 file changed, 29 insertions(+), 27 deletions(-) diff --git a/docs/spec/raw.md b/docs/spec/raw.md index 19522100485..02f96c788f7 100644 --- a/docs/spec/raw.md +++ b/docs/spec/raw.md @@ -25,10 +25,11 @@ surface, which provides control mechanism for Knative eventing. # Resource Types The eventing API defines several resource types as well as interfaces which may -be fulfilled by other Kubernetes objects ([Callable](#callable), [Subscribable](#subscribable), [Channelable](#channelable), [Targetable](#targetable)). -The API defines and provides a complete implementation for -[Subscription](#kind-subscription), and abstract resource definitions for -[Sources](#kind-source), [Channels](#kind-channel), and +be fulfilled by other Kubernetes objects ([Callable](#callable), +[Subscribable](#subscribable), [Channelable](#channelable), +[Targetable](#targetable)). The API defines and provides a complete +implementation for [Subscription](#kind-subscription), and abstract resource +definitions for [Sources](#kind-source), [Channels](#kind-channel), and [Providers](#kind-provisioner) which may be fulfilled by multiple backing implementations (much like the Kubernetes Ingress resource). @@ -195,7 +196,7 @@ their status. They cannot receive events._ #### Owner References -* Owned by a Flow if created by a Flow. + * Owned by a Flow if created by a Flow. ### Status @@ -207,12 +208,12 @@ their status. They cannot receive events._ #### Conditions -* **Ready.** True when the Source is provisioned and ready to emit events. -* ** Provisioned.** True when the Source has been provisioned by a controller. + * **Ready.** True when the Source is provisioned and ready to emit events. + * ** Provisioned.** True when the Source has been provisioned by a controller. ### Events -* Provisioned - describes each resource that is provisioned. + * Provisioned - describes each resource that is provisioned. ## Life Cycle @@ -247,8 +248,8 @@ Subscription's call parameter._ #### Owner References -* If the Pipeline controller created this Channel: Owned by the originating Pipeline. -* Owned by the Provisioner used to provision the Channel. + * If the Pipeline controller created this Channel: Owned by the originating Pipeline. + * Owned by the Provisioner used to provision the Channel. ### Status @@ -260,13 +261,13 @@ Subscription's call parameter._ #### Conditions -* **Ready.** True when the Channel is provisioned and ready to accept events. -* **Provisioned.** True when the Channel has been provisioned by a controller. + * **Ready.** True when the Channel is provisioned and ready to accept events. + * **Provisioned.** True when the Channel has been provisioned by a controller. ### Events -* Provisioned -* Deprovisioned + * Provisioned + * Deprovisioned ## Life Cycle @@ -293,13 +294,14 @@ or a Channel system that receives and delivers events._ | parameters |[]ParameterSpec| Parameters are used for validation of arguments. | | \*: Required + 1: Kubernetes type. ### Metadata #### Owner References -* Owns EventTypes. + * Owns EventTypes. ### Status @@ -309,9 +311,9 @@ or a Channel system that receives and delivers events._ ### Events -* Source created -* Source deleted -* Event types installed + * Source created + * Source deleted + * Event types installed ## Life Cycle @@ -338,13 +340,14 @@ _Describes a direct linkage between an event publisher and an action._ | result1 | ObjectRef | The continuation Channel for the link. | Must be a Channel. | \*: Required + 1: At Least One(call, result) ### Metadata #### Owner References -* If a resource controller created this Subscription: Owned by the originating resource. + * If a resource controller created this Subscription: Owned by the originating resource. ### Status @@ -354,15 +357,15 @@ _Describes a direct linkage between an event publisher and an action._ #### Conditions -* **Ready.** True ~~when the publisher resource is also ready. -* **FromReady.** -* **CallActive. **True if the call is sinking events without error. -* **Resolved** + * **Ready.** True ~~when the publisher resource is also ready. + * **FromReady.** + * **CallActive. **True if the call is sinking events without error. + * **Resolved** ### Events -* PublisherAcknowledged -* ActionFailed + * PublisherAcknowledged + * ActionFailed ## Life Cycle @@ -403,6 +406,7 @@ _Describes a direct linkage between an event publisher and an action._ | defaultFrom1 | ArgumentValueReference | Default value retrieved from an existing Secret or ConfigMap if not provided by arguments. | | \*: Required + 1: OneOf (default, defaultFrom) ## ArgumentValueReference @@ -450,5 +454,3 @@ _Describes a direct linkage between an event publisher and an action._ | --- | --- | --- | --- | | callableDomain | String | The domain name of the endpoint for the call. | | | sinkableDomain | String | The domain name of the endpoint for the result. | | - - From eb401b9ab1169902a7bd4886ed0246929eade1c3 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 11:23:10 -0700 Subject: [PATCH 11/60] Explode out the spec into components. --- docs/spec/README.md | 20 +-- docs/spec/interfaces.md | 74 +++++++++ docs/spec/overview.md | 126 ++++++++++------ docs/spec/{raw.md => spec.md} | 277 +++++++--------------------------- 4 files changed, 226 insertions(+), 271 deletions(-) create mode 100644 docs/spec/interfaces.md rename docs/spec/{raw.md => spec.md} (51%) diff --git a/docs/spec/README.md b/docs/spec/README.md index 1f1c33489dc..dac3f21ab35 100644 --- a/docs/spec/README.md +++ b/docs/spec/README.md @@ -1,21 +1,19 @@ # 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), -[`feeds.knative.dev`](/pkg/apis/feeds/v1alpha1) and -[`flows.knative.dev`](/pkg/apis/flows/v1alpha1) and verified via [the e2e -test](/test/e2e). +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 [channels](/pkg/apis/channels/v1alpha1), -[feeds](/pkg/apis/feeds/v1alpha1) or [flows](/pkg/apis/feeds/v1alpha1) and [the -e2e test](/test/e2e).** +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) @@ -27,4 +25,8 @@ Sources is probably worth highlighting somewhere.` The Parameters/ParametersFrom pattern for passing args to the images is probably also worth documenting. ---> \ No newline at end of file +--> + +See the [Knative Eventing Docs +Architecture](https://github.com/knative/docs/blob/master/eventing/README.md#architecture) +for more high level details. diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md new file mode 100644 index 00000000000..35dce66a4bc --- /dev/null +++ b/docs/spec/interfaces.md @@ -0,0 +1,74 @@ +# Interface Contracts + + + +## Subscribable + +A **Subscribable** resource will emit events that a _Subscription_ can direct +to a _Targetable_ or _Sinkable_ resource. + +### Control Plane + +A **Subscribable** resource may be referenced in the _from_ section of a +_Flow_. The **Subscribable** resource MUST expose a _channel_ field (an +ObjectReference) in its _status_ section. This _channel_ field MUST be +_Channelable_, and _channel_ MAY refer back to the **Subscribable** resource. + +### Data Plane + +A **Subscribable** resource is an event producer or forwarder, events that it +produces or forwards are delivered via its _status.channel_ resource. + +## Channelable + +A **Channelable** resource owns a list of subscribers for delivery of events. + +### Control Plane + +The **Channelable** resource has a list of _subscribers_ within the resources +_spec_. In practice, the resolved _subscription_ _call_ and _result_ endpoints +populate the Channelable's list of _subscribers_. + +### Data Plane + +**Channelable** resources will attempt delivery to each of they _subscribers_ +at least once, and retry if the callie returns errors. + +## Targetable + +A **Targetable** resource represents a unit of work to be done on/to/with an +event. They allow for event modification and flow control without taking +ownership of the event. Typically a **Targetable** is a function. + +### Control Plane + +A **Targetable** resource MUST expose a _targetable.domainInternal_ field in +its _status_ section. 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 does not ownership of the event that was passed to +it, but it is allowed to modify the event by returning a response code of 200 +and a mutated version back to the caller. The **Targetable** can prevent the +event from continuing to the next stage by returning 200 and an empty body. All +other response codes are considered an error and the caller will attempt to +call again. + +## Sinkable + +A **Sinkable** resource takes ownership of an event. Typically a **Sinkable** +is a Channel. + +### Control Plane + +A **Sinkable** resource MUST expose a _targetable.domainInternal_ field in its +_status_ section. 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_. + +### Data Plane + +A **Sinkable** resource will only respond to requests by ACK/NACK. It must not +return events to the caller. diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 9dd1121e912..6b53de1e5e9 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -1,70 +1,112 @@ -# Resource Groups +# Overview -Knative Eventing API is grouped into _Channels_, _Feeds_ and _Flows_: +In the serverless model, computation and storage can be intertwined by having +storage and compute systems publish events which are handled asynchronously by +further compute services. Event delivery provides common infrastructure for +decoupling event producers and consumers such that the linking between them can +be performed without change to either. Loosely coupled eventing systems enable +composable services which retain the ability to scale independently. +Declarative event binding reduces the effort to create a scalable system that +combines managed services and custom code. -* _Channels_ define an abstraction between the eventing infrastructure and the - consumption and production of the events. +Knative eventing implements common components of an event delivery ecosystem: +enumeration and discovery of event sources, configuration and management of +event transport, and declarative binding of events (generated either by storage +services or earlier computation) to further event processing and persistence. -* _Feeds_ bridge the event source into the eventing framework. +The following is a detailed specification for the `eventing.knative.dev` API +surface, which provides control mechanism for Knative eventing. -* _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 -used to connect event producers directly with event consumers leveraging -_Feeds_ and _Channels_. # Resource Types -The primary resources in the Knative Eventing _Feeds_ API are EventSource, -EventType and Feed: +The eventing API defines several resource types as well as interfaces which may +be fulfilled by other Kubernetes objects ([Callable](interfaces.md#callable), +[Subscribable](interfaces.md#subscribable), +[Channelable](interfaces.md#channelable), +[Targetable](interfaces.md#targetable)). The API defines and provides a +complete implementation for [Subscription](spec.md#kind-subscription), and +abstract resource definitions for [Sources](spec.md#kind-source), +[Channels](spec.md#kind-channel), and [Providers](spec.md#kind-provisioner) +which may be fulfilled by multiple backing implementations (much like the +Kubernetes Ingress resource). + + * A **Subscription** describes the transformation of an event (via a + _Callable_) and optional storage of a returned event. + + * A **Source** represents an ongoing selection of events from an external + system. A Flow is used to connect these events to subsequent processing + steps. + + * A **Channel** provides event storage and fanout of events from a well-known + input address to multiple outputs described by Subscriptions. -* **EventSource**, an archetype of an event producer. + -* **EventType**, the schema for an event. + * **Provisioners** act as a catalog of the types of Sources and Channels + currently active in the eventing system. -* **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. +## Subscription +**Subscriptions** define the transport of events from one storage location +(typically, **Source** or **Channel**) to the next (typically, a **Channel**) +through optional transformations (such as a Knative Service which processes +CloudEvents over HTTP). A **Subscription** resolves the addresses of +transformations (`call`) and destination storage (`result`) through the +_Callable_ and _Sinkable_ interface contracts, and writes the resolved +addresses to the _Subscribable_ `from` resource. A **Subscriptions** do not +need to specify both a transformation and a storage destination, but at least +one must be provided. -The primary resources in the Knative Eventing _Channels_ API are Channel, -Subscription and Bus: +All event transport over a **Subscription** is 1:1 – only a single `from`, +`call`, and `result` may be provided. -* **Channel**, a named endpoint which accepts and forwards events. +For more details, see [Kind: Subscription](spec.md#kind-subscription). -* **Bus**, an implementation of an event delivery mechanism. +## Source -* **Subscription**, an expressed interest in events from a _Channel_ to be - delivered to an HTTP endpoint. +**Source** represents an ongoing selection of events from an external system, +such as object creation events in a specific storage bucket, database updates +in a particular table, or Kubernetes resource state changes. Because a +**Source** represents an external system, it only produces events (and is +therefore _Subscribable_ by **Subscriptions**). **Source** configures an +external system and may include parameters such as specific resource names, +event types, or credentials which should be used to establish the connection to +the external system. The set of allowed configuration parameters is described +by the **Provisioner** which is referenced by the **Source**. -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. +Event selection on a **Source** is 1:N – a single **Source** may fan out to +multiple **Subscriptions**. +For more details, see [Kind: Source](spec.md#kind-source). -The _Flows_ API implements a single resource, Flow: +## Channel -* **Flow**, is an abstraction of the connection between an event producer to - the event consumer leveraging _Feed_s and _Channels_. +**Channel** provides a durable event storage mechanism which can fan 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. +See [Kind: Channel](spec.md#kind-channel). -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). +## Provisioner +The eventing API has parallel constructs for event _sources_ (systems which +create events based on internal or external changes) and event _transports_ +(middleware which add value to the event delivery chain, such as persistence or +buffering). + + + ![Object Model](images/overview-reference.png) -See the [Knative Eventing Docs -Architecture](https://github.com/knative/docs/blob/master/eventing/README.md#architecture) -for more details. + + + +For more details, see [Kind: Provider](spec.md#kind-provisioner). diff --git a/docs/spec/raw.md b/docs/spec/spec.md similarity index 51% rename from docs/spec/raw.md rename to docs/spec/spec.md index 02f96c788f7..f44a64ba3e6 100644 --- a/docs/spec/raw.md +++ b/docs/spec/spec.md @@ -1,188 +1,25 @@ - +# Object Model -# Eventing Specification - v1alpha1 +This is the detailed specification of the Knative Eventing Object Model. For +context, see the [overview](overview.md), [motivation](motivation.md), and the +[interface contract](interfaces.md) documents. -# Overview + * [Source](#kind-source) + * [Channel](#kind-channel) + * [Subscription](#kind-subscription) + * [Provider](#kind-provisioner) -In the serverless model, computation and storage can be intertwined by having -storage and compute systems publish events which are handled asynchronously by -further compute services. Event delivery provides common infrastructure for -decoupling event producers and consumers such that the linking between them can -be performed without change to either. Loosely coupled eventing systems enable -composable services which retain the ability to scale independently. -Declarative event binding reduces the effort to create a scalable system that -combines managed services and custom code. +## kind: Source -Knative eventing implements common components of an event delivery ecosystem: -enumeration and discovery of event sources, configuration and management of -event transport, and declarative binding of events (generated either by storage -services or earlier computation) to further event processing and persistence. - -The following is a detailed specification for the `eventing.knative.dev` API -surface, which provides control mechanism for Knative eventing. - - -# Resource Types - -The eventing API defines several resource types as well as interfaces which may -be fulfilled by other Kubernetes objects ([Callable](#callable), -[Subscribable](#subscribable), [Channelable](#channelable), -[Targetable](#targetable)). The API defines and provides a complete -implementation for [Subscription](#kind-subscription), and abstract resource -definitions for [Sources](#kind-source), [Channels](#kind-channel), and -[Providers](#kind-provisioner) which may be fulfilled by multiple backing -implementations (much like the Kubernetes Ingress resource). - - * A **Subscription** describes the transformation of an event (via a - _Callable_) and optional storage of a returned event. - - * A **Source** represents an ongoing selection of events from an external - system. A Flow is used to connect these events to subsequent processing - steps. - - * A **Channel** provides event storage and fanout of events from a well-known - input address to multiple outputs described by Flows. - - - - * **Provisioners** act as a catalog of the types of Sources and Channels - currently active in the eventing system. - - - -## Subscription - -**Subscriptions** define the transport of events from one storage location -(typically, **Source** or **Channel**) to the next (typically, a **Channel**) -through optional transformations (such as a Knative Service which processes -CloudEvents over HTTP). A **Subscription** resolves the addresses of -transformations (`call`) and destination storage (`result`) through the -_Callable_ and _Sinkable_ interface contracts, and writes the resolved -addresses to the _Subscribable_ `from` resource. A **Subscriptions** do not -need to specify both a transformation and a storage destination, but at least -one must be provided. - -All event transport over a **Subscription** is 1:1 – only a single `from`, -`call`, and `result` may be provided. - -## Source - -**Source** represents an ongoing selection of events from an external system, -such as object creation events in a specific storage bucket, database updates -in a particular table, or Kubernetes resource state changes. Because a -**Source** represents an external system, it only produces events (and is -therefore _Subscribable_ by **Subscriptions**). **Source** configures an -external system and may include parameters such as specific resource names, -event types, or credentials which should be used to establish the connection to -the external system. The set of allowed configuration parameters is described -by the **Provisioner** which is referenced by the **Source**. - -Event selection on a **Source** is 1:N – a single **Source** may fan out to -multiple **Subscriptions**. - -## Channel - -**Channel** provides a durable event storage mechanism which can fan 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, - -## Provisioner - -The eventing API has parallel constructs for event _sources_ (systems which -create events based on internal or external changes) and event _transports_ -(middleware which add value to the event delivery chain, such as persistence or -buffering). - - -# Interface Contracts - - - -## Subscribable - -A **Subscribable** resource will emit events that a _Subscription_ can direct -to a _Targetable_ or _Sinkable_ resource. - -### Control Plane - -A **Subscribable** resource may be referenced in the _from_ section of a -_Flow_. The **Subscribable** resource MUST expose a _channel_ field (an -ObjectReference) in its _status_ section. This _channel_ field MUST be -_Channelable_, and _channel_ MAY refer back to the **Subscribable** resource. - -### Data Plane - -A **Subscribable** resource is an event producer or forwarder, events that it -produces or forwards are delivered via its _status.channel_ resource. - -## Channelable - -A **Channelable** resource owns a list of subscribers for delivery of events. - -### Control Plane - -The **Channelable** resource has a list of _subscribers_ within the resources -_spec_. In practice, the resolved _subscription_ _call_ and _result_ endpoints -populate the Channelable's list of _subscribers_. - -### Data Plane - -**Channelable** resources will attempt delivery to each of they _subscribers_ -at least once, and retry if the callie returns errors. - -## Targetable - -A **Targetable** resource represents a unit of work to be done on/to/with an -event. They allow for event modification and flow control without taking -ownership of the event. Typically a **Targetable** is a function. - -### Control Plane - -A **Targetable** resource MUST expose a _targetable.domainInternal_ field in -its _status_ section. 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 does not ownership of the event that was passed to -it, but it is allowed to modify the event by returning a response code of 200 -and a mutated version back to the caller. The **Targetable** can prevent the -event from continuing to the next stage by returning 200 and an empty body. All -other response codes are considered an error and the caller will attempt to -call again. - -## Sinkable - -A **Sinkable** resource takes ownership of an event. Typically a **Sinkable** -is a Channel. - -### Control Plane - -A **Sinkable** resource MUST expose a _targetable.domainInternal_ field in its -_status_ section. 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_. - -### Data Plane - -A **Sinkable** resource will only respond to requests by ACK/NACK. It must not -return events to the caller. - - -# kind: Source - -## group: eventing.knative.dev/v1alpha1 +### group: eventing.knative.dev/v1alpha1 _Describes a specific configuration (credentials, etc) of a source system which can be used to supply events. Sources emit events using a channel specified in their status. They cannot receive events._ -## Object Schema +### Object Schema -### Spec +#### Spec | Field | Type | Description | Limitations | | --- | --- | --- | --- | @@ -192,13 +29,13 @@ their status. They cannot receive events._ \*: Required -### Metadata +#### Metadata -#### Owner References +##### Owner References * Owned by a Flow if created by a Flow. -### Status +#### Status | Field | Type | Description | Limitations | | --- | --- | --- | --- | @@ -206,16 +43,16 @@ their status. They cannot receive events._ | Subscribable | Subscribable | Pointer to a channel which can be subscribed to in order to receive events from this source. | | | provisioned |[]ProvisionedObjectStatus| Creation status of each Channel and errors therein. | It is expected that a Source list all produced Channels. | -#### Conditions +##### Conditions * **Ready.** True when the Source is provisioned and ready to emit events. * ** Provisioned.** True when the Source has been provisioned by a controller. -### Events +#### Events * Provisioned - describes each resource that is provisioned. -## Life Cycle +### Life Cycle | Action | Reactions | Limitations | | --- | --- | --- | @@ -223,17 +60,17 @@ their status. They cannot receive events._ | Update | Provisioner controller synchronizes backing implementation on changes. | | | Delete | Provisioner controller will deprovision backing resources depending on implementation. | Flow controller will recreate a Source after deletion if the Source originated from a Flow. | -# kind: Channel +## kind: Channel -## group: eventing.knative.dev/v1alpha1 +### group: eventing.knative.dev/v1alpha1 _A Channel logically receives events on its input domain and forwards them to its subscribers. Additional behavior may be introduced by using the Subscription's call parameter._ -## Object Schema +### Object Schema -### Spec +#### Spec | Field | Type | Description | Limitations | | --- | --- | --- | --- | @@ -244,14 +81,14 @@ Subscription's call parameter._ \*: Required -### Metadata +#### Metadata -#### Owner References +##### Owner References * If the Pipeline controller created this Channel: Owned by the originating Pipeline. * Owned by the Provisioner used to provision the Channel. -### Status +#### Status | Field | Type | Description | Limitations | | --- | --- | --- | --- | @@ -259,17 +96,17 @@ Subscription's call parameter._ | Subscribable | Subscribable | | | | Conditions | Conditions | Standard Subscriptions| | -#### Conditions +##### Conditions * **Ready.** True when the Channel is provisioned and ready to accept events. * **Provisioned.** True when the Channel has been provisioned by a controller. -### Events +#### Events * Provisioned * Deprovisioned -## Life Cycle +### Life Cycle | Action | Reactions | Limitations | | --- | --- | --- | @@ -277,16 +114,16 @@ Subscription's call parameter._ | Update | The Provisioner will synchronize the Channel backing resources to reflect the update. | | | Delete | The Provisioner will deprovision the backing resources if no longer required depending on implementation. | | -# kind: Provisioner +## kind: Provisioner -## group: eventing.knative.dev/v1alpha1 +### group: eventing.knative.dev/v1alpha1 _Describes an abstract configuration of a Source system which produces events or a Channel system that receives and delivers events._ -## Object Schema +### Object Schema -### Spec +#### Spec | Field | Type | Description | Limitations | | --- | --- | --- | --- | @@ -297,25 +134,25 @@ or a Channel system that receives and delivers events._ 1: Kubernetes type. -### Metadata +#### Metadata -#### Owner References +##### Owner References * Owns EventTypes. -### Status +#### Status | Field | Type | Description | Limitations | | --- | --- | --- | --- | | provisioned |[]ProvisionedObjectStatus| Status of creation or adoption of each EventType and errors therein. | It is expected that a provisioner list all produced EventTypes, if applicable. | -### Events +#### Events * Source created * Source deleted * Event types installed -## Life Cycle +### Life Cycle | Action | Reactions | Limitations | | --- | --- | --- | @@ -323,15 +160,15 @@ or a Channel system that receives and delivers events._ | Update | Synchronizes EventTypes. | | | Delete | Removes Owner ref from EventTypes. | | -# kind: Subscription +## kind: Subscription -## group: eventing.knative.dev/v1alpha1 +### group: eventing.knative.dev/v1alpha1 _Describes a direct linkage between an event publisher and an action._ -## Object Schema +### Object Schema -### Spec +#### Spec | Field | Type | Description | Limitations | | --- | --- | --- | --- | @@ -343,31 +180,31 @@ _Describes a direct linkage between an event publisher and an action._ 1: At Least One(call, result) -### Metadata +#### Metadata -#### Owner References +##### Owner References * If a resource controller created this Subscription: Owned by the originating resource. -### Status +#### Status | Field | Type | Description | Limitations | | --- | --- | --- | --- | | resolutions | SubscriptionResolutionsStatus | Resolved targets for the spec's call and continue fields. | | -#### Conditions +##### Conditions * **Ready.** True ~~when the publisher resource is also ready. * **FromReady.** * **CallActive. **True if the call is sinking events without error. * **Resolved** -### Events +#### Events * PublisherAcknowledged * ActionFailed -## Life Cycle +### Life Cycle | Action | Reactions | Limitations | | --- | --- | --- | @@ -375,9 +212,9 @@ _Describes a direct linkage between an event publisher and an action._ | Update | | | | Delete | | | -# Shared Object Schema +## Shared Object Schema -## ProvisionerReference +### ProvisionerReference | Field | Type | Description | Limitations | | --- | --- | --- | --- | @@ -386,7 +223,7 @@ _Describes a direct linkage between an event publisher and an action._ 1: One of (name, selector), Required. -## EndpointSpec +### EndpointSpec | Field | Type | Description | Limitations | | --- | --- | --- | --- | @@ -395,7 +232,7 @@ _Describes a direct linkage between an event publisher and an action._ 1: One of (targetRef, dnsName), Required. -## ParameterSpec +### ParameterSpec | Field | Type | Description | Limitations | | --- | --- | --- | --- | @@ -409,7 +246,7 @@ _Describes a direct linkage between an event publisher and an action._ 1: OneOf (default, defaultFrom) -## ArgumentValueReference +### ArgumentValueReference | Field | Type | Description | Limitations | | --- | --- | --- | --- | @@ -418,7 +255,7 @@ _Describes a direct linkage between an event publisher and an action._ 1: OneOf (secretKeyRef, configMapRef), Required. -## ProvisionedObjectStatus +### ProvisionedObjectStatus | Field | Type | Description | Limitations | | --- | --- | --- | --- | @@ -429,26 +266,26 @@ _Describes a direct linkage between an event publisher and an action._ \*: Required -## SubscriptionResolutionsStatus +### SubscriptionResolutionsStatus | Field | Type | Description | Limitations | | --- | --- | --- | --- | | call | String | Resolved target for the spec's call field. Empty string if spec.call is nil. | Must be a domain name | | continue | String | Resolved target for the spec's continue field. Empty string if spec.continue is nil. | Must be a domain name | -## Subscribable +### Subscribable | Field | Type | Description | Limitations | | --- | --- | --- | --- | | channelable | ObjectReference | The channel used to emit events. | | -## Channelable +### Channelable | Field | Type | Description | Limitations | | --- | --- | --- | --- | | subscribers | ChannelSubscriberSpec[]| Information about subscriptions used to implement message forwarding. | Filled out by Subscription Controller. | -## ChannelSubscriberSpec +### ChannelSubscriberSpec | Field | Type | Description | Limitations | | --- | --- | --- | --- | From bf169025750cc1103a47d192ef5ced3ce8e74124 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 11:31:11 -0700 Subject: [PATCH 12/60] Added images. --- .../images/interface-contracts-overview.svg | 1 + docs/spec/images/overview-reference.dot | 33 ------------------ docs/spec/images/overview-reference.png | Bin 14651 -> 0 bytes docs/spec/images/resource-types-overview.svg | 1 + .../images/resource-types-provisioner.svg | 1 + docs/spec/interfaces.md | 2 +- docs/spec/overview.md | 12 ++----- 7 files changed, 6 insertions(+), 44 deletions(-) create mode 100644 docs/spec/images/interface-contracts-overview.svg delete mode 100644 docs/spec/images/overview-reference.dot delete mode 100644 docs/spec/images/overview-reference.png create mode 100644 docs/spec/images/resource-types-overview.svg create mode 100644 docs/spec/images/resource-types-provisioner.svg diff --git a/docs/spec/images/interface-contracts-overview.svg b/docs/spec/images/interface-contracts-overview.svg new file mode 100644 index 00000000000..7a994743949 --- /dev/null +++ b/docs/spec/images/interface-contracts-overview.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/spec/images/overview-reference.dot b/docs/spec/images/overview-reference.dot deleted file mode 100644 index 5d049b11ee8..00000000000 --- a/docs/spec/images/overview-reference.dot +++ /dev/null @@ -1,33 +0,0 @@ -// 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 [dir=back]; - color=white; - {rank = same; Source; EventType;} - } - - subgraph cluster_C { - Feed; - Channel - Subscription; - label = "Flow"; - } - EventType -> Feed [dir=back]; - Feed -> Channel; - - Subscription -> Service; - Channel -> Subscription [dir=back]; - - Bus -> Channel [dir=back]; - - {rank = max; Service;} -} diff --git a/docs/spec/images/overview-reference.png b/docs/spec/images/overview-reference.png deleted file mode 100644 index 69d363eeeb267559963dabe56e693b4e2fcebd45..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 14651 zcmeHuWmuHo*DexD2%?mLlu{!CN_U8Kw}5~_cXx`2L4(rWEit5|($YhxbR#j;F!1hC zfByZQ>pCCKhx4B6T-W=BVfH++pS9Lr>)z|WpSLPX()hR(xM*l-__8vO)X>l{_`v_& z*q6cI^yfUe;Ny~`n)E}o;@(?pXlQ(J*+=3UZkM)_t|Ssm9=6ZkHc@FVeA?p2KP}5) zs>-h_E-tD1jX&9A#;|^f^SzGp)g03&N?48rH^sj3OMks3_AT!M&Qh}C5fqn{Je>?f z7WJ9Bdejya6g0rI^9_azMis>gxhOB86Z)ZH(xP3$7DEI7is52&@nbQ`i1Ra}|7Y~) z0UKx-zmEBHxH+BQ%czg>nYaFR2{abIjz5R|{3VKowhYf=B_a!-$(Xg2IZ=<38 zebvk$G+ZT*^~lJdv-y1)+I>tFI}Ubqw13Ui13UHq?M21f4~PRJ#ZnpkaflelGG(K5 zlNTxfc|wvq_s#lK-(@Mb5WbO5h1k*A7|n~PMqpp178;WZqn?)0VJ!J&HviX*O`por z3fQ^hOtF}_HD$$dulFmcIXXI~$tMQ!+n3PcVt&GWa2348e|t{m6)@cG zo3fby@@MW9bmsqS2Uou>4$`H)hI$H$#HMN2S!+YDUCB;0tA>+h9^)?Jx~LJa!(|v~GEY!{fB7BDneK%Vs-`Z-t>Ra`-|q zfu|?gYfqL^#H+ggbiLqkH6v^Shbi%?>x{c;a|IvHub?%%c1g=_LL$tQ4i&{sM6uv! z>#Z&Bo!?*+0*Jx56-lsG9nJ6mhP@%k_8_LBm$TBo%M|2$iT)W4vlVZvqX zSy1FrN8;Auq-~Y9fqQGM>y8bj?dQ@9SjaVz<5c1E;{}nB584LfBRZy3l-w54-WSND z^Cu}H-d0=C(MoVkQ*q7;|;67heYjs%^hs3H=? zlK1(}_aK@|;L7&p1ltC!6xJ|{y-y=`t~;c=JmW@0QG1SSSuv;kdxP2aBD$S8UlJXA z&4JaDr-9SXqd(Wc*N3|oVSc|7+xQ)jspqKFPCaLTI>Q-m4==w6!kN|Qo?TO z(7mMApL`2Tf7ZU8s(w74IHfa+DM4Y*<6!k!jJ``;ScW(M9jV|S?Z2(HiL#bKlKOL$ zwKSPNZ4}p4o+?1ZaTnUdY_Ho6NRq)l9nulzhZC0U2w=*sHcH!y@?L@NMptPQtJ8B3 zBc6fM2s`Yb5frWn;%U6lRSq9GJhd3RBU9noRJA?p9(?{i`$V7Uh1Fg->E*blHAI|g zvUy44c`dJW6gqs;w(&$*NO0$~1g`?QlqQ4e^-@!88Mp_ z#Nn3S-rJL|5F4=?$lH*go={Wvb3TJ-A+ln2U}p;d+Q~~Hryshy3R_QG9KNRUo^*eiIeGU z`EsHFeP*zjy1M$880-_PUxqr)**F^k@6I``^>u* zl|_+87w1QfTY+Q-pSGv#CgUxO&Gl=Yc9EW-WIrd896$vZ8*&{_7tNIlnbkNDpv)1B;VUa z_vJXA?tA59B8W{QCXX*|=3^v@n%erqj0&+&C4vZ`UkC)h!A{OkH%iWJCo0Sj7o(IX zetiG31?q93`%*53rU>+JW5HnKJx&sScYBRo&Yd2OC3ZF8%HqdNhZFy0Yyhed4!l$9X@zB#nI z?b?mIkv{=Z30!RM*e6^?go41Hn=FD$g4H_?n@skK~>coE!Ov@%y)6F zS^8K|n{E&M9Jd#FIww$&k9mc|%*ICPKu75Rb0pzuu5#(Ei}G zp5-%4P(409$L@O~uVbywy6+1g*1kd|=yG+6UhxO;qk^`fG>x~@{V!KJ7khUqhLjqD zYl!ge?%T~ZJ^da?R;;7coi}R%O<8IJcOGz>zH8W@CJ`iN{O&UEIN2?a)wBWi(oo)M zr=cc@bm_d-?LpHN?~!byjD)A&C+SH1w3=bYx0)JoL+38rso!m~ zipWfo1c1>-+wGDX0m`?Le15TW;4*2w60>~a$|x*t=yQ_AkJX!?*m?DP$DJ^)94{1# zNlbpIRZ3sfdH%$)$JiISVaW24l9%=Y^7@377)xbNvPV8Y)@*`XCk)`Y8B4wABn{p8 zpREAa+%MoJGjL1m5!(MYB)ki}x4%`WH9!KJ;nuaoP2}e09=5I=n(*m*vQjncQ;xz% zSf0ECWZjtct%}?4jY>Yk`TB(R7ftgPkIr@<9=xv1B&!z@4KW>s>y?lkt zLZhU59@mz)0Y0L)a@b%-u5q*xl<9r7EaGZFg8AOzGRGIY_^PU`Xx7@zz7LfG?o_j$ zJM}!XUi&9)TFbWz3d`hT9}OtSc^#|{d^v}g_@3}lC@>qI!ql>pnI;!Sk!#8#w!E`m z<-GV2?gSIu81^DA`@khl^@x2J|9+otm=2L-{Z17#% z6T06kn4sre;l7eo#U_^{jAbL)zoNROo_2pBnA4+N245pX+~Ky4#$=|8Vw8w#jXM%P zS|7Iy63Wh`PSv}}I{mGHLytVgVUep_&%D6C=3CF)#GpL;)B{xCb_Z=uGD3LDz+=pGzdn2k$qmz>Nu;6n z+a2E{k-cF3y`b~Dk?+|8jkhj^M8$|Q872F@>baK&yWPslZ!N;_sUM>DY&$wPBorxL zrzOrxx+!OP^T;8{m+qE#0}KnJUs*|VO-|v%Eur!H(VXqVMWJh1j@vnx?76+BNWT#5 z$Z%9O<593xyHPwKeOkH~`{0F_UfujVmI=lLtNHf+XPF~=#BF&6eHN^DY92D#q%R8y zHQtK1O<#T``q;7vie7cZpe-~y;K7Nj{jA1Opn5g^{Yy};cwLnkMRgxK9hQhR7MJ2a zkytLNdwtgqK6uIMnwkq(%lMOcE!B z&gVwYRaae89lzVQ;;#qb^G@Bji(>arc(tojta(11ygIJb91>y!c40VEXgyU0HcJ9_ zL>wacIro+ZRS-3xJY80T;3j@~DYn&wMfPN_L@;n7;b6VSrmQ2OjmmA#-+$6~dC0lf z_$8lxOVEc%`&M;5x}j#>z)wCKdB}S~lCc*K+p16Cu1fs7dua{BTX@W|kIYUN6U7#b zX?)Li&qZ>?R(h>LQ^S8UV-;acCCGGBBy_SV>3zoenDzD{qqq_|Htb`quvpE8O$(h} zLFCLUX=L^{&Lr+PjoXYg0U%fOqzD2?5`fzL=j;&QpKW{>ptp8lzi=?r+J?8DF>EM3 zq@LatM(K8$cgjv;?sDD?Oz#CTlmvI_jO`5n!9{D)?5E`CjCw8=QkJ6oc+7Fv<&pfY zLUy=zKExOGP@aO=s{(nK7-V|G^3%kWzNMHI39NAL+Ggol5NV!jWAR~uUnlf zN%t06RG&uSoY`fDC&mK~B_=$XX;J|u8jD#E6UcLvlH!NtxYaYrHL$Gth8ZQZau|g8 zIr=vNnjjrSuPyD)mSu`=2A1@v>?vNyK>Z)+$LFx6Po6X=-cQxBHf|^Wr3m)*&)d z^oWV$B9;7e`A*NBnR?{6d?UUC6ME^JA?w15$@LagiHhC>_o_qbj`Rj>4Sg-bDo%9i z5~26v#ahUsX^JRVI!Yz^#S45Kq^=iNnk^}F#@OscC@+H@`%!s-?tpz)NDAF(aC#z% zOtL=HCY6p^n@T~Wg)*$olKTngzRh!pRw5sVfl|%g>s1DmeR9#M7R03J`Aeu zx{%0C^Cih<$bEz5MQ$~5mO>CXVLP7259o*li(2wa3>`WdkaAUFtLL4Oca%i+%|6p| zzJRaj@?Q%$m4h$YT+1|s4!T1x9HdfRbQ&MnzuTY08M?Q^se~YJ%hO1il-V++tK>Ku zzNtzo7RlWid1?vWf5tp)0%Z)4%YfP!EAUNYMjKv_ar|)KEO?oiqVaAXi82=d&S15c zw_jm|E+wU9p-LDX32x}!N85B?QjM1$z6;dL+hsJjm~$%huRgD^%1t$10qupEP`>#$ z_aTVmg)roeL(s%A&;QzgCXcUs6P7D;z3ZB)WAK?}k+=2=>rufCFNlWR3P9MqA---Y z#P^*~(;PDPCq{2C$;fZ0**P^*2!G(dYH`4QEOR&4(S-oR%Yh<1kWRy_M(j1b%<$t|PYsnuFW(?tsIs}9c8A0?=A8SkVc z?k~1z^u?TnPw)rYg|n1I4ja_F${G zFaGoq+z~gD4$>1T90wq!>MZLJJ3i(xwT!zVXsmg8K?H4<+G&C=GL0TBi3S(Ura$B( zWv&oqRT8BVk#-MxeRhy}Pd2VAMknsNxtAU2d&Qpy@HM_)b)2V;8S>G}@3YQ4EWfF( z_^}(NR>mf&(v_#+p5**0W|Yrb>j628Q$ECzgvqedXfIbp_%4ED5_asC9cRK}z01ta zqg4whRZE*&lo-A?<$m~}hd?smvdL)_tt>Vy)#4+=RU4hL1B}7V=ltRUXg$PBL1&j) zE<8$iYWw1<+z~Q3$*+_U%!zSQrFv)XAGFI2;+OiRczS%KO#SrgYeLA3@304|*pxtT zWXG{1&5T8<^;;nyKU)<+)3x3b@|2bBvXM;aYG(}=9XdlQ)#T=3z7Y3oA1>i5Wu&R< z$P!dEW_=VdH_CcqwZWT}s*K;kML0CWKQ136Cl2kR&3af~X8U+RE7ph~L#j!PiCTL#lUo*{+sVX);){%W~yL42vXI(^=*21@e3Naw!k&e=p@S z-P(<4GG~-$XJsXU{pb`@#(2WLuImwFsm;nN6`*kNkTY!cBr_Cx2I=EbbI9D3S&Jb5 zAn@_ib-8t&O!Zi?#8Y;Loe9%yLT=%EXI#CNAH?{~>C|s2nwWjm!4Qng?jmR$5ogzr z=6_{?OXg8@H=4v9_(dQd|R<`jv=Av2Oa%o2VL@6qi zxwszSDVn#;zCEpS_`=yIw9rEXrO2mMXX{M(_R2}ovyST+#%V-RO!lTb%a+Tm(b7kh zqTZm_z9MDB+rAC&-DrU}ySE#WlkbmN-|riwE#8p>mgb@aOX;9wG5glzij~FC&tDWn+{7_{9S}XTLpcIcoc=>R!%=BUd`~; zA;mrQ9m|0>)wo+`&a%sB6J(FfX#7=txIWz@l^X^*V-z=Wvm1IOfv6?sLW@DxF3LGj z=~Jy5$6>-@)#QW>fw3G6GK5XK4Up7ShAx=M@7oeq?4_}ZM-Y-sH|_Fm6OV&8m0G) z@*FWfaiQ#p$Sad&g!M@pOBVEUw5z31-ff!bgT^{a(Z#7Ymeeyx3Sz-6Rk3s&t|N=x zA_MxbM|@-bLLwXY-Wocr<+CJXzIMb+-v25w+C#^Eb6(+%6Wh1R7mOhX2jY5G8&Z`alsjxr2I zezB{2l!(HIulp>m6ASnvS)uOFE{Ylq5Hkl8#4B;5JLWNOYqfZXx7$0_k2h;iokXYd zF|}78O+VV$nn=S_&tk0#v!UJ5537CMR97~90!R$Y+PzNJJWE)%UVikObLfwGt2aKYhoY}QyXv00lrM>#+xJ2f9?Ux%Gdo)1gKD>NPW6_Z5Kz5;ehFI^iqKRaOB&~8lU3)sr@SC!Q^bMN^l_`}&) z;rDnauk%S``s?Y$v(+CatDGv42PXwn#$M^Ad+8cTj>zV?lRcnVu}?_Mw<9nkSsmMr zZ$U>+md^*DjsMJokJL(3EQ!%Ho&TKi=q-a~BW=|&%eXVN!u+ZJL zWJxGv~9&xLtH7Tt*)i%XKW>8`j6sg=6hQks`} z-HEGvhwCb}Jr@PMck&Hwa;Nj5wqKTJX04mxyGbo%d{Jp)4karr_|P3C$X)Vw#pmu{ zi#n?pN1YdIW}|%cQUKSY+{`$>Fx8mLu$<4^5__r&UXeq zbC>O(aa};j25dBkx>KKw)xIU&nb2cPgr8z!Rh6*VVQ}x5=p#!{Wox_%5XP;lRCR9? znu;bcZQ3TfBMk7aU#?#k?^BI~Rc&bAc&0*~xK`b`tRU^}TWo1F%(OD1^Wt(<)wkIj zIVoCSLA#{%fWD;ntfNux;r7c9G&NsFY^9nZyrsTm=dWWg=0{4}(BA3g_2+KoxXJJg z$E=euQY6T*P3I@l*a|S|u!ciNOh}@dNpY&#*X#D%Yiu6U@vS5}I&77mrhlq;jQZ%W zr?>~^jECWKugLM48LRTML|t#vsJ<@Q=LWLxjcM6+hZ~l8lTWT`UAdvDuvZduTHI`` z!6(=hHe}JH37M)kJ4umw_9#Ga`mK-RS#@+U z(|Hrejl!5y);ry->6P3UHj;cXp{EZZ6h%;Win$<%1+AlZN+ag9WCW*<*N%6@b2rVN zu4uLFvm(((2@$uuBDTnve@ko6vYYl5?t?u8is4(dGTBP!%H!JK{T~gh-dt%@?x* z)$hLG#fOTYTe5aiWW2oU-Ou4@P2QcvhOTIE3h2xMd}%*&b6^+ zU7p?-oIN>VpSNq`xeuEtk81d+gT-VXE}O-qo##+jsAxFB%W3j0_N8pMi_T$GS(R~< z4&imC-((v19WhaT&I6&F=p+3~mj@sF+SCj-j*pLzo>uu-zA*L)mnN&1XenAfIqKt@ zmnYlr{_6URTNBg8?pMyqVuVO%+<1zW(`%u`ZXVfA#~QIwq7oicu}W#mVm+bCeC?00 zBK7{I)3uf-e0csAfYQw)UE@e5n!qNjlRT`#{D-bvk3vH_d5_@LbP@Qs$YYK}M1NB8 zzlk^$7x)Npfs!9&RsZIN!kqyZs1t+Mb?t91kQm%WR@GRI_@9fTPBBUXT;K?U-=4(Z zT%aV13)F}s#`>EJ)L{Z#pfgVD*}u5J>wpU+)?}3Q|C_cP!2z_TK034Lzi7+!vsebds7<_*4A8lU9&z}pv#Xoo; z?I$LDLri3&RI5W>2JPgk><^tV%4cB@w2$OKxo>4>z}tqhmQf zAobLjY+x-WiXxQINARodPmoE1V6+;yPO`r{I@uEEx3fP8GYOf#S8{_3UNj|4*JXT}( zH(+_{f@;fJzk}u!SSqtI6hend+fR$xaJDCpqJcJF;<0^_jbhZfI7e=6*X>k-)>MB9 zF0agk4#r<5P0a=_vUrygg!0?{DDnyZmBgWzt0;LyIkm8d-<98<^XC9Jh{g$CML8{! zmX@;u?1sl#cw*BS#G|=>2TdbjiN$ZAzGy_CnV4z5>dE-|3vCp*35U)WF$FqdF3+WJ z{rQTCE8?g?5z|6>7`hDM1$?(Xx|>7+-*f8UQ5hSGhTH2T!*>a#DDcL7$XNkew6h|| za~Pk~px2mOe@9x^?fyjrzvv=fyN`iP28-5J(<8~C6G0l$c)HG#;C(obe1Fn{2bhWq z`-Qgg7CiP_$@AqeF#)|{1(Xg|BHpJOKOpq@{ukF{fxe)Aw~g}f9I=BEfPl6jX*om8 zlStRmvuoF-!EEJlI-tl`I7GqEjOAFWo8PtKDxs59wozD)p?ZG$azojQmi9KSB-)Q^ z%*8Xy3{|Y|cE`YcnNoYb_7*!20YNwcwqzzrg07Vxv~)XJc;jKTC_=vj-5=0%3Fp{^ zK<-pHN3VhxU!?CeAgQM)i;<+R#NSH5zZkByU=PGQW>?VzzxAVNErYJ{o5RvL=}N9 z@yyv~gfw;Okh18sAmL4ZhfFvi$A=L$zpv{j21gOiUp@L$#U-_E58foX&hV!(MO+06 z15AH)W#M7anB@f;joD2gdx6Aee(NW;earCiK0nbKEH7#rbd6CuoJqha2JHL2g#DwG z%4NNz0K2i+2;4LYNGsd;t&rE`Cb7*T$OH9_38>`(S3B?%K6VGB35aiOOo6Uwdkt(j z%DoQ;q(`#k$$SYoD{fH`{Ek?BX*4oX9IbIB!7Zbs8Bg2y#931^yW%zG{($MDK`_ca6E$8*v1 z;|x@r7P!bu!0VTi3!4iiFM72h=W+^i0e25JOUJ>|d-jGO>_~-UReB(>`bvKvXw@dI z%6m3DnNq$XdGMw^0OdAe;JKx_dSm7HqY|1CqVti;_RmnbKe(4Q)sc8GVOhe;WIq3oszW6R^Kr9mwVKg92WaF?0)A>ky#c7StlqO$ z${a&}&VcR*h;5J2UeIl}x0z3ac>^9Yowf07FDu=i>Yo%Mz|e%N)IxG6s-ijI3PMBB zb=xYzs!X;;nU){uMhN^(lik}q;OoXq%)Aqv+TV0RX$v+cBx$$IBz`u?*RA_cJ zgLS-_l1YXgO3s-rr(A@5aeA=!V!GD3z*}k}Jm6lZDdi8YDOL~r6*<{H)&&5P2OGmo8 z_qFt_jghDD{hitYgw0~D@abEY)jhWxl)oNKr35p-^5q@05Fs?SDs({3Itc>Wnw14( zg)5p}2DJ1=`vf2%UjUV3t@Wqo%Pyn(uH!&i_;|=` z*ADwD!w*1VPhO$%>c8!QO8h|RSBlb00M>7Mp2F~-733#2fn(%?wbI2>QUM(`n5=c# zvOp<7fDm)Sp_|ndv01J>v5~l!^`_}=LE-bp^V0%+DgoGqH&Brsf~7gu!#j%#`M0b< z&*=iRkD0k&|H4KUO0-e9y(k3;O1p+C!65!m^J=A?2MPVNj?w&Gh&nP~?gQc8 zWQF;VRaZ2G70sg3GfepK(>2kvPp$3^VyVeET-@Ao#7SrOQEMG6>Yo}&;nUTOlb92N zKYmt|rH%5m`>10=t_RB079c>&0PEUUviu6_`J?&DBw){O`oL4vUfVPxT|AdQXrDE_ z2KtpT-}QOcs;TFox&6_39o7lJ(RUK2xJD#kD=Oz+;!S{}5F@`)+D^UCxvrL3447#> zkRYvr^y0@T)Pl?8+f7eE$XbC4d$26&*voIaZ2-{+3d@{X+kp~8(MCgN*9Z)3VmcI| ze998390)`l9X6oB%AP`LT@iuGNQX@r*Tw*%S}6gu7^&>I{r>nxT-`Ldb9NstsTB8hFDsOR$S72IbC0AOaLB7Fn|582v!$(W|BJtl60Jyr8IZ&wZEd=oFEjdsB5Jo4J_F;!b+Qiz@FLsjWRAbmtQMoMB8*&Oc7&R)i+SoCF4 zdxru8z9GJU5(03$ky^8ApxL$1XyT$svme=-B#^rUsYtwu98RE;9r||odB4{(h}t7} zcIXpIkkifH2pF{)v+&4rfHRks%%L)#w~49U7q8cSe@(dw73e|co6?$upK<7D7a{6e&?&_b&T#pblA-Sd5 zhN|fCr5^`rfmhxi&S8qrZOAb`tDQl~Z=IQTG}L_9>JJ7B}c<9f1~V%seM)Imxu+tyDD!5t%vw2U}@D)O&10qKHjSJ+Ix?`be51pZPyI+h6y3 z$0Bti^CqgT9-ok~1@uu>`Yz+GQXv$^K)h7WE03pb)`GpZ6m2;l7KC?z zmZ%ym^=TF%(Dn^R$g|fk_PpyAy*OJn4y99x_FL5C$QO;vkWGf$Fu7~KryMc#^=^!G zYa=&xiy6}Oza`@3HZ}S7mogg_0v1xVQ7n8wH(Sh$|6VO-JVwijxI$Snu%iwd3&wN7g{k}dXg4&}`5R3DBLeB~iFfq8Uo$ zRNpd?qfFzgi!fPySH&t$Jw#j#vK(oZFZj)1V9*B_B1Wd~r22ki0<+kg4->mWiq^@! znC#{2f}lw4z!4*@#%qw-Q$+y3IA<(V7%%^+@nWens5pAay| zzhqwWi{B-T&--XKAu~YuwFy@LJ^>cj3pREwU7hur`Z`{+!Qk3&^G0ep^$)+lQ|A&6 zEtj6F+i55VY5FUfP&B7^#GUtd!h{9|i}`*uVK_ehXy9Rv(jzGBu^EGvyJ)Q_-W5!o zz&qpiWxHmD+E=L&hrjua2iXDHZ)rWsf$QO7j7M`FSmiS-_COOJcR06N&qwi1mVCg| zI^AHP!XaH4UyX-A^vrHYS2y%h=9^atqs2@y>VeE?8JvjrJd~)9MQ|?`rAk9M=KDgJ z)IJ@Ko6^`WXX`i%t0O3*U!O0IXd4uoB)glib8rw1qN#^oKB#KJWpTS^7ih5kIEX{) z<6RjsC9H~x+c{*ox|-1s&ph<`M7B+?j{2 zRvu2SVg+@Xrrmd5*BE;3+qyPVq?g9bXsf;#noYZ((hnonI#ozaTyC(&g@-fLER$(kFU zWse)7CcXQ=n>x_j;hiM6;-+3bL%oc^`273P^Aw7?K+4MZtvDYj_1U#+2811ZxMM`# zUFPSd6{CfqM-HecEpgqUXz>=1>Y5vBm}hCaJaD8G#1_+r-rlo2eyAd<^w}ENZ zQOy(0X=2j9U9<+Ee$@79meb!(?jQzsRM6xNM7?J7yNlu{Rtr4wKU4j0vg+K$B}eW4 W#k&`1Uf^v=G+9ZdN5v1HzWgtl48!UG diff --git a/docs/spec/images/resource-types-overview.svg b/docs/spec/images/resource-types-overview.svg new file mode 100644 index 00000000000..aa95d9111f5 --- /dev/null +++ b/docs/spec/images/resource-types-overview.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/spec/images/resource-types-provisioner.svg b/docs/spec/images/resource-types-provisioner.svg new file mode 100644 index 00000000000..54ca5293ae5 --- /dev/null +++ b/docs/spec/images/resource-types-provisioner.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index 35dce66a4bc..6697d8ac31a 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -1,6 +1,6 @@ # Interface Contracts - +!Interface Contracts Overview](images/interface-contracts-overview.svg) ## Subscribable diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 6b53de1e5e9..7fbe271a5d4 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -41,12 +41,12 @@ Kubernetes Ingress resource). * A **Channel** provides event storage and fanout of events from a well-known input address to multiple outputs described by Subscriptions. - +![Resource Types Overview](images/resource-types-overview.svg) * **Provisioners** act as a catalog of the types of Sources and Channels currently active in the eventing system. - +![Resource Types Provisioners](images/resource-types-provisioner.svg) ## Subscription @@ -99,14 +99,6 @@ create events based on internal or external changes) and event _transports_ (middleware which add value to the event delivery chain, such as persistence or buffering). - - - -![Object Model](images/overview-reference.png) - - - - For more details, see [Kind: Provider](spec.md#kind-provisioner). From 6adb9f07f78dd20aa0824a11d9911c9d28d1f611 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 11:33:00 -0700 Subject: [PATCH 13/60] Adding a link back to the original image to allow for editing later. --- docs/spec/interfaces.md | 1 + docs/spec/overview.md | 2 ++ 2 files changed, 3 insertions(+) diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index 6697d8ac31a..1987f6714ef 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -1,5 +1,6 @@ # Interface Contracts + !Interface Contracts Overview](images/interface-contracts-overview.svg) ## Subscribable diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 7fbe271a5d4..c90085ed423 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -41,11 +41,13 @@ Kubernetes Ingress resource). * A **Channel** provides event storage and fanout of events from a well-known input address to multiple outputs described by Subscriptions. + ![Resource Types Overview](images/resource-types-overview.svg) * **Provisioners** act as a catalog of the types of Sources and Channels currently active in the eventing system. + ![Resource Types Provisioners](images/resource-types-provisioner.svg) ## Subscription From edf5caf30a4191de7d3f2a52eb9fd6c4ddb43a6c Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 11:37:41 -0700 Subject: [PATCH 14/60] adding nav links to the bottom. --- docs/spec/README.md | 2 +- docs/spec/interfaces.md | 9 +++++++++ docs/spec/motivation.md | 10 ++++++++++ docs/spec/overview.md | 8 ++++++++ 4 files changed, 28 insertions(+), 1 deletion(-) diff --git a/docs/spec/README.md b/docs/spec/README.md index dac3f21ab35..1bbba507411 100644 --- a/docs/spec/README.md +++ b/docs/spec/README.md @@ -13,7 +13,7 @@ Docs in this directory: * [Motivation and goals](motivation.md) * [Resource type overview](overview.md) * [Interface contracts](interfaces.md) -* [Object Model Specification](spec.md) +* [Object model specification](spec.md) diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index 1987f6714ef..c14ae2f2303 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -73,3 +73,12 @@ referenced in the _result_ section of a _Subscription_. A **Sinkable** resource will only respond to requests by ACK/NACK. It must not return events to the caller. + +--- + +*Next*: + +* [Motivation and goals](motivation.md) +* [Resource type overview](overview.md) +* [Interface contracts](interfaces.md) +* [Object model specification](spec.md) diff --git a/docs/spec/motivation.md b/docs/spec/motivation.md index f1f6d4f2e58..3b1504cd712 100644 --- a/docs/spec/motivation.md +++ b/docs/spec/motivation.md @@ -33,3 +33,13 @@ integrate with CloudEvents middleware and message consumers. 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). + + +--- + +*Next*: + +* [Motivation and goals](motivation.md) +* [Resource type overview](overview.md) +* [Interface contracts](interfaces.md) +* [Object model specification](spec.md) diff --git a/docs/spec/overview.md b/docs/spec/overview.md index c90085ed423..f1493121ab3 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -103,4 +103,12 @@ buffering). For more details, see [Kind: Provider](spec.md#kind-provisioner). +--- + +*Next*: + +* [Motivation and goals](motivation.md) +* [Resource type overview](overview.md) +* [Interface contracts](interfaces.md) +* [Object model specification](spec.md) From 7ca20b8c72e2e1f212fcc674211114e77ee6d415 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 11:39:18 -0700 Subject: [PATCH 15/60] next should not have this page. --- docs/spec/interfaces.md | 2 +- docs/spec/motivation.md | 2 +- docs/spec/overview.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index c14ae2f2303..8ffe509bcfc 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -80,5 +80,5 @@ return events to the caller. * [Motivation and goals](motivation.md) * [Resource type overview](overview.md) -* [Interface contracts](interfaces.md) + * [Object model specification](spec.md) diff --git a/docs/spec/motivation.md b/docs/spec/motivation.md index 3b1504cd712..dab93235595 100644 --- a/docs/spec/motivation.md +++ b/docs/spec/motivation.md @@ -39,7 +39,7 @@ API](https://github.com/knative/build). *Next*: -* [Motivation and goals](motivation.md) + * [Resource type overview](overview.md) * [Interface contracts](interfaces.md) * [Object model specification](spec.md) diff --git a/docs/spec/overview.md b/docs/spec/overview.md index f1493121ab3..1e7e0d0532d 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -108,7 +108,7 @@ For more details, see [Kind: Provider](spec.md#kind-provisioner). *Next*: * [Motivation and goals](motivation.md) -* [Resource type overview](overview.md) + * [Interface contracts](interfaces.md) * [Object model specification](spec.md) From 9c825b8cb384dbcf9c7699a89acc0351c54490d3 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 11:40:02 -0700 Subject: [PATCH 16/60] Fix interface image. --- docs/spec/interfaces.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index 8ffe509bcfc..9f6de195180 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -1,7 +1,7 @@ # Interface Contracts -!Interface Contracts Overview](images/interface-contracts-overview.svg) +![Interface Contracts Overview](images/interface-contracts-overview.svg) ## Subscribable From 806e9a190628f753e5a34aa3b74bf83d8ba0b0bb Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 11:44:44 -0700 Subject: [PATCH 17/60] scrub flow. --- docs/spec/interfaces.md | 2 +- docs/spec/overview.md | 4 ++-- docs/spec/spec.md | 8 +------- 3 files changed, 4 insertions(+), 10 deletions(-) diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index 9f6de195180..dac7bd4c686 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -11,7 +11,7 @@ to a _Targetable_ or _Sinkable_ resource. ### Control Plane A **Subscribable** resource may be referenced in the _from_ section of a -_Flow_. The **Subscribable** resource MUST expose a _channel_ field (an +_Subscription_. The **Subscribable** resource MUST expose a _channel_ field (an ObjectReference) in its _status_ section. This _channel_ field MUST be _Channelable_, and _channel_ MAY refer back to the **Subscribable** resource. diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 1e7e0d0532d..7e19b1e4d5c 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -35,8 +35,8 @@ Kubernetes Ingress resource). _Callable_) and optional storage of a returned event. * A **Source** represents an ongoing selection of events from an external - system. A Flow is used to connect these events to subsequent processing - steps. + system. A Subscription is used to connect these events to subsequent + processing steps. * A **Channel** provides event storage and fanout of events from a well-known input address to multiple outputs described by Subscriptions. diff --git a/docs/spec/spec.md b/docs/spec/spec.md index f44a64ba3e6..3ab23c41906 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -29,12 +29,6 @@ their status. They cannot receive events._ \*: Required -#### Metadata - -##### Owner References - - * Owned by a Flow if created by a Flow. - #### Status | Field | Type | Description | Limitations | @@ -58,7 +52,7 @@ their status. They cannot receive events._ | --- | --- | --- | | Create | Provisioner controller watches for Sources and creates the backing resources depending on implementation. | | | Update | Provisioner controller synchronizes backing implementation on changes. | | -| Delete | Provisioner controller will deprovision backing resources depending on implementation. | Flow controller will recreate a Source after deletion if the Source originated from a Flow. | +| Delete | Provisioner controller will deprovision backing resources depending on implementation. | | ## kind: Channel From 743b16492d0627a63638f3863098fe0909c61b55 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 11:52:45 -0700 Subject: [PATCH 18/60] fix image and update some bolds. --- docs/spec/images/interface-contracts-overview.svg | 2 +- docs/spec/spec.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/spec/images/interface-contracts-overview.svg b/docs/spec/images/interface-contracts-overview.svg index 7a994743949..0e81d6dc1f2 100644 --- a/docs/spec/images/interface-contracts-overview.svg +++ b/docs/spec/images/interface-contracts-overview.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 3ab23c41906..c321adb5e4f 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -40,7 +40,7 @@ their status. They cannot receive events._ ##### Conditions * **Ready.** True when the Source is provisioned and ready to emit events. - * ** Provisioned.** True when the Source has been provisioned by a controller. + * **Provisioned.** True when the Source has been provisioned by a controller. #### Events @@ -188,10 +188,10 @@ _Describes a direct linkage between an event publisher and an action._ ##### Conditions - * **Ready.** True ~~when the publisher resource is also ready. + * **Ready.** * **FromReady.** - * **CallActive. **True if the call is sinking events without error. - * **Resolved** + * **CallActive.** True if the call is sinking events without error. + * **Resolved.** #### Events From f7689d056b12298cce32eb949dd2b2623a0c6de9 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 11:56:25 -0700 Subject: [PATCH 19/60] Trying to make the documents read better. --- docs/spec/interfaces.md | 8 ++++++++ docs/spec/overview.md | 2 +- docs/spec/spec.md | 10 ++++++++++ 3 files changed, 19 insertions(+), 1 deletion(-) diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index dac7bd4c686..72900488342 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -3,6 +3,8 @@ ![Interface Contracts Overview](images/interface-contracts-overview.svg) +--- + ## Subscribable A **Subscribable** resource will emit events that a _Subscription_ can direct @@ -20,6 +22,8 @@ _Channelable_, and _channel_ MAY refer back to the **Subscribable** resource. A **Subscribable** resource is an event producer or forwarder, events that it produces or forwards are delivered via its _status.channel_ resource. +--- + ## Channelable A **Channelable** resource owns a list of subscribers for delivery of events. @@ -35,6 +39,8 @@ populate the Channelable's list of _subscribers_. **Channelable** resources will attempt delivery to each of they _subscribers_ at least once, and retry if the callie returns errors. +--- + ## Targetable A **Targetable** resource represents a unit of work to be done on/to/with an @@ -57,6 +63,8 @@ event from continuing to the next stage by returning 200 and an empty body. All other response codes are considered an error and the caller will attempt to call again. +--- + ## Sinkable A **Sinkable** resource takes ownership of an event. Typically a **Sinkable** diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 7e19b1e4d5c..d98baef198e 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -21,7 +21,7 @@ surface, which provides control mechanism for Knative eventing. # Resource Types The eventing API defines several resource types as well as interfaces which may -be fulfilled by other Kubernetes objects ([Callable](interfaces.md#callable), +be fulfilled by other Kubernetes objects ([Sinkable](interfaces.md#sinkable), [Subscribable](interfaces.md#subscribable), [Channelable](interfaces.md#channelable), [Targetable](interfaces.md#targetable)). The API defines and provides a diff --git a/docs/spec/spec.md b/docs/spec/spec.md index c321adb5e4f..9d0a9756351 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -9,6 +9,8 @@ context, see the [overview](overview.md), [motivation](motivation.md), and the * [Subscription](#kind-subscription) * [Provider](#kind-provisioner) +--- + ## kind: Source ### group: eventing.knative.dev/v1alpha1 @@ -54,6 +56,8 @@ their status. They cannot receive events._ | Update | Provisioner controller synchronizes backing implementation on changes. | | | Delete | Provisioner controller will deprovision backing resources depending on implementation. | | +--- + ## kind: Channel ### group: eventing.knative.dev/v1alpha1 @@ -108,6 +112,8 @@ Subscription's call parameter._ | Update | The Provisioner will synchronize the Channel backing resources to reflect the update. | | | Delete | The Provisioner will deprovision the backing resources if no longer required depending on implementation. | | +--- + ## kind: Provisioner ### group: eventing.knative.dev/v1alpha1 @@ -154,6 +160,8 @@ or a Channel system that receives and delivers events._ | Update | Synchronizes EventTypes. | | | Delete | Removes Owner ref from EventTypes. | | +--- + ## kind: Subscription ### group: eventing.knative.dev/v1alpha1 @@ -206,6 +214,8 @@ _Describes a direct linkage between an event publisher and an action._ | Update | | | | Delete | | | +--- + ## Shared Object Schema ### ProvisionerReference From 3fe9f297fdeb5a1a163a1cafc7a7b0f0580a6be4 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 13:20:13 -0700 Subject: [PATCH 20/60] Update based on feedback. --- docs/spec/spec.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 9d0a9756351..9d046d1187e 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -35,8 +35,7 @@ their status. They cannot receive events._ | Field | Type | Description | Limitations | | --- | --- | --- | --- | -| channel | ObjectReference | The channel used to emit events. | | -| Subscribable | Subscribable | Pointer to a channel which can be subscribed to in order to receive events from this source. | | +| subscribable | Subscribable | Pointer to a channel which can be subscribed to in order to receive events from this source. | | | provisioned |[]ProvisionedObjectStatus| Creation status of each Channel and errors therein. | It is expected that a Source list all produced Channels. | ##### Conditions @@ -91,7 +90,7 @@ Subscription's call parameter._ | Field | Type | Description | Limitations | | --- | --- | --- | --- | | Sinkable | Sinkable | Address to the endpoint as top-level domain that will distribute traffic over the provided targets from inside the cluster. | | -| Subscribable | Subscribable | | | +| subscribable | Subscribable | | | | Conditions | Conditions | Standard Subscriptions| | ##### Conditions From 5850ace6b8571d68b4d4479e4538282ec3eabc65 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 13:47:44 -0700 Subject: [PATCH 21/60] Feedback. --- docs/spec/interfaces.md | 23 ++++++++++++----------- docs/spec/overview.md | 6 +++--- docs/spec/spec.md | 37 ------------------------------------- 3 files changed, 15 insertions(+), 51 deletions(-) diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index 72900488342..58d5754d0a4 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -13,9 +13,10 @@ to a _Targetable_ or _Sinkable_ resource. ### Control Plane A **Subscribable** resource may be referenced in the _from_ section of a -_Subscription_. The **Subscribable** resource MUST expose a _channel_ field (an -ObjectReference) in its _status_ section. This _channel_ field MUST be -_Channelable_, and _channel_ MAY refer back to the **Subscribable** resource. +_Subscription_. The **Subscribable** resource MUST expose a +_subscribable.channelable_ field (an ObjectReference) in its _status_ section. +This _channelable_ field MUST be _Channelable_, and _channel_ MAY refer back to +the **Subscribable** resource. ### Data Plane @@ -31,8 +32,8 @@ A **Channelable** resource owns a list of subscribers for delivery of events. ### Control Plane The **Channelable** resource has a list of _subscribers_ within the resources -_spec_. In practice, the resolved _subscription_ _call_ and _result_ endpoints -populate the Channelable's list of _subscribers_. +_spec.channelable_. In practice, the resolved _subscription_ _call_ and +_result_ endpoints populate the Channelable's list of _subscribers_. ### Data Plane @@ -57,10 +58,10 @@ referenced in the _call_ section of a _Subscription_. ### Data Plane The **Targetable** resource does not ownership of the event that was passed to -it, but it is allowed to modify the event by returning a response code of 200 +it, but it is allowed to modify the event by returning a response code of *2XX* and a mutated version back to the caller. The **Targetable** can prevent the -event from continuing to the next stage by returning 200 and an empty body. All -other response codes are considered an error and the caller will attempt to +event from continuing to the next stage by returning *2XX* and an empty body. +All other response codes are considered an error and the caller will attempt to call again. --- @@ -72,10 +73,10 @@ is a Channel. ### Control Plane -A **Sinkable** resource MUST expose a _targetable.domainInternal_ field in its +A **Sinkable** resource MUST expose a _sinkable.domainInternal_ field in its _status_ section. 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_. +capable of receiving event deliveries. **Sinkable** resources may be referenced +in the _result_ section of a _Subscription_. ### Data Plane diff --git a/docs/spec/overview.md b/docs/spec/overview.md index d98baef198e..c23649ca052 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -58,9 +58,9 @@ through optional transformations (such as a Knative Service which processes CloudEvents over HTTP). A **Subscription** resolves the addresses of transformations (`call`) and destination storage (`result`) through the _Callable_ and _Sinkable_ interface contracts, and writes the resolved -addresses to the _Subscribable_ `from` resource. A **Subscriptions** do not -need to specify both a transformation and a storage destination, but at least -one must be provided. +addresses to the _Subscribable_ `from` resource. **Subscriptions** do not need +to specify both a transformation and a storage destination, but at least one +must be provided. All event transport over a **Subscription** is 1:1 – only a single `from`, `call`, and `result` may be provided. diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 9d046d1187e..8627571e25b 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -127,7 +127,6 @@ or a Channel system that receives and delivers events._ | Field | Type | Description | Limitations | | --- | --- | --- | --- | | type*| TypeMeta1 | The type of the resource to be provisioned. | Must be Source or Channel. | -| parameters |[]ParameterSpec| Parameters are used for validation of arguments. | | \*: Required @@ -187,12 +186,6 @@ _Describes a direct linkage between an event publisher and an action._ * If a resource controller created this Subscription: Owned by the originating resource. -#### Status - -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | -| resolutions | SubscriptionResolutionsStatus | Resolved targets for the spec's call and continue fields. | | - ##### Conditions * **Ready.** @@ -235,29 +228,6 @@ _Describes a direct linkage between an event publisher and an action._ 1: One of (targetRef, dnsName), Required. -### ParameterSpec - -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | -| name*| String | The unique name of this template parameter. | | -| description | String | A human-readable explanation of this template parameter. | | -| required | Boolean | If the parameter is required. | If true, default / defaultFrom should not be provided. Immutable. | -| default1 | String | Default value if not provided by arguments. | | -| defaultFrom1 | ArgumentValueReference | Default value retrieved from an existing Secret or ConfigMap if not provided by arguments. | | - -\*: Required - -1: OneOf (default, defaultFrom) - -### ArgumentValueReference - -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | -| secretKeyRef1 | SecretReference | A reference to a value contained in a Secret at the given key. | | -| configMapRef1 | ConfigMapReference | A reference to a value contained in a ConfigMap at the given key. | | - -1: OneOf (secretKeyRef, configMapRef), Required. - ### ProvisionedObjectStatus | Field | Type | Description | Limitations | @@ -269,13 +239,6 @@ _Describes a direct linkage between an event publisher and an action._ \*: Required -### SubscriptionResolutionsStatus - -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | -| call | String | Resolved target for the spec's call field. Empty string if spec.call is nil. | Must be a domain name | -| continue | String | Resolved target for the spec's continue field. Empty string if spec.continue is nil. | Must be a domain name | - ### Subscribable | Field | Type | Description | Limitations | From e12f1c5ecd15270c55e41bff75e2d6fc7e445f98 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 1 Oct 2018 14:37:32 -0700 Subject: [PATCH 22/60] adding event type for prosperity --- docs/spec/spec.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 8627571e25b..436862f1715 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -208,6 +208,56 @@ _Describes a direct linkage between an event publisher and an action._ --- + +## kind: EventType + +NOTE: EventType is out of scope for 0.1 release. This is future documentation. + +### group: eventing.knative.dev/v1alpha1 + +_Describes a particular schema of Events which may be produced by one or more +source systems._ + +### Object Schema + +#### Spec + +| Field | Type | Description | Limitations | +| --- | --- | --- | --- | +| jsonSchema | String | The Json Schema that represents an event in flight. | Only for JSON transport types. | + +#### Metadata + +##### Owner References + +EventType is owned by *Provisioners*. Each *Provisioner* creates a +non-controlling OwnerReference on the EventType resources it knows about. + +#### Status + +| Field | Type | Description | Limitations | +| --- | --- | --- | --- | +| referenceCount | Integer | Number of Owners for this EventType | | + +##### Conditions + + * **Pinned**. True when the EventType cannot be deleted. + +#### Events + + * **Owned.** When EventType has a new Provisioner Owner. + * **Released.** When a Provisioner removes Ownership from the EventType. + +### Life Cycle + +| Action | Reactions | Limitations | +| --- | --- | --- | +| Create | | | +| Update | | | +| Delete | | Blocked until all provisioners release it. | + +--- + ## Shared Object Schema ### ProvisionerReference From e4a6a3b99746f187bf4f02dd901029cf73d417c4 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 8 Oct 2018 10:06:36 -0700 Subject: [PATCH 23/60] checkpoint on feedback. --- docs/spec/README.md | 11 +- docs/spec/images/resource-types-overview.svg | 2 +- docs/spec/interfaces.md | 84 ++++++------ docs/spec/motivation.md | 17 ++- docs/spec/overview.md | 127 ++++++++++--------- docs/spec/spec.md | 2 +- 6 files changed, 134 insertions(+), 109 deletions(-) diff --git a/docs/spec/README.md b/docs/spec/README.md index 1bbba507411..81b85c46486 100644 --- a/docs/spec/README.md +++ b/docs/spec/README.md @@ -10,10 +10,11 @@ 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) +- [Motivation and goals](motivation.md) +- [Resource type overview](overview.md) +- [Interface contracts](interfaces.md) +- [Object model specification](spec.md) + @@ -29,4 +30,4 @@ probably also worth documenting. See the [Knative Eventing Docs Architecture](https://github.com/knative/docs/blob/master/eventing/README.md#architecture) -for more high level details. +for more high level details. diff --git a/docs/spec/images/resource-types-overview.svg b/docs/spec/images/resource-types-overview.svg index aa95d9111f5..58ef46e472e 100644 --- a/docs/spec/images/resource-types-overview.svg +++ b/docs/spec/images/resource-types-overview.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index 58d5754d0a4..355a45d0332 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -1,33 +1,36 @@ # Interface Contracts + ![Interface Contracts Overview](images/interface-contracts-overview.svg) --- ## Subscribable -A **Subscribable** resource will emit events that a _Subscription_ can direct -to a _Targetable_ or _Sinkable_ resource. +A **Subscribable** resource will emit events that one or more _Subscription_ +can direct to their configured destination. ### Control Plane -A **Subscribable** resource may be referenced in the _from_ section of a -_Subscription_. The **Subscribable** resource MUST expose a -_subscribable.channelable_ field (an ObjectReference) in its _status_ section. -This _channelable_ field MUST be _Channelable_, and _channel_ MAY refer back to -the **Subscribable** resource. +A **Subscribable** resource may be referenced in the _from_ field of a +_Subscription_. The _Subscribable_ resource MUST expose a +_status.subscribable.channelable_ field (an _ObjectReference_). The resource +referenced in the _status.subscribable.channelable_ field MUST be a +_Channelable_ resource; the field MAY refer back to this _Subscribable_ as a +self referenced resource. ### Data Plane -A **Subscribable** resource is an event producer or forwarder, events that it -produces or forwards are delivered via its _status.channel_ resource. +A **Subscribable** resource produces or forwards events via its +_status.subscribable.channelable_ resource. --- ## Channelable -A **Channelable** resource owns a list of subscribers for delivery of events. +A **Channelable** resource contains a list of subscribers and is responsible +for delivering events to each of them. ### Control Plane @@ -37,57 +40,60 @@ _result_ endpoints populate the Channelable's list of _subscribers_. ### Data Plane -**Channelable** resources will attempt delivery to each of they _subscribers_ -at least once, and retry if the callie returns errors. +**Channelable** resources will attempt delivery to each of the _subscribers_ +at least once, and retry if the subscriber returns errors. --- ## Targetable -A **Targetable** resource represents a unit of work to be done on/to/with an -event. They allow for event modification and flow control without taking -ownership of the event. Typically a **Targetable** is a function. +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 _targetable.domainInternal_ field in -its _status_ section. 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_. +A **Targetable** resource MUST expose a _status.targetable.domainInternal_ +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 does not ownership of the event that was passed to -it, but it is allowed to modify the event by returning a response code of *2XX* -and a mutated version back to the caller. The **Targetable** can prevent the -event from continuing to the next stage by returning *2XX* and an empty body. -All other response codes are considered an error and the caller will attempt to -call again. +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. --- ## Sinkable -A **Sinkable** resource takes ownership of an event. Typically a **Sinkable** -is a Channel. +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_. ### Control Plane -A **Sinkable** resource MUST expose a _sinkable.domainInternal_ field in its -_status_ section. 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_. +A **Sinkable** resource MUST expose a _status.sinkable.domainInternal_ field. +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_. ### Data Plane -A **Sinkable** resource will only respond to requests by ACK/NACK. It must not -return events to the caller. +A **Sinkable** resource will only respond to requests with success of failure. +Events returned to the caller will be reported or ignored. ---- +--- -*Next*: +_Navigation_: -* [Motivation and goals](motivation.md) -* [Resource type overview](overview.md) - -* [Object model specification](spec.md) +- [Motivation and goals](motivation.md) +- [Resource type overview](overview.md) +- **Interface contracts** +- [Object model specification](spec.md) diff --git a/docs/spec/motivation.md b/docs/spec/motivation.md index dab93235595..6c9e4564adc 100644 --- a/docs/spec/motivation.md +++ b/docs/spec/motivation.md @@ -30,16 +30,21 @@ 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 API is intended to operate independently, and interop +Knative eventing implements common components of an event delivery ecosystem: +enumeration and discovery of event sources, configuration and management of +event transport, and declarative binding of events (generated either by storage +services or earlier computation) to further event processing and persistence. + +The Knative Eventing API is intended to operate independently, and interoperate well with the [Serving API](https://github.com/knative/serving) and [Build API](https://github.com/knative/build). --- -*Next*: +_Navigation_: - -* [Resource type overview](overview.md) -* [Interface contracts](interfaces.md) -* [Object model specification](spec.md) +- **Motivation and goals** +- [Resource type overview](overview.md) +- [Interface contracts](interfaces.md) +- [Object model specification](spec.md) diff --git a/docs/spec/overview.md b/docs/spec/overview.md index c23649ca052..0aa4fb951ae 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -12,103 +12,116 @@ combines managed services and custom code. Knative eventing implements common components of an event delivery ecosystem: enumeration and discovery of event sources, configuration and management of event transport, and declarative binding of events (generated either by storage -services or earlier computation) to further event processing and persistence. +services or earlier computation) for further event processing and persistence. The following is a detailed specification for the `eventing.knative.dev` API surface, which provides control mechanism for Knative eventing. - # Resource Types -The eventing API defines several resource types as well as interfaces which may -be fulfilled by other Kubernetes objects ([Sinkable](interfaces.md#sinkable), -[Subscribable](interfaces.md#subscribable), -[Channelable](interfaces.md#channelable), -[Targetable](interfaces.md#targetable)). The API defines and provides a -complete implementation for [Subscription](spec.md#kind-subscription), and -abstract resource definitions for [Sources](spec.md#kind-source), -[Channels](spec.md#kind-channel), and [Providers](spec.md#kind-provisioner) -which may be fulfilled by multiple backing implementations (much like the -Kubernetes Ingress resource). +The API defines and provides a complete implementation for +[Subscription](spec.md#kind-subscription), and abstract resource definitions +for [Sources](spec.md#kind-source), [Channels](spec.md#kind-channel), and +[Providers](spec.md#kind-provisioner) which may be fulfilled by multiple +backing implementations (much like the Kubernetes Ingress resource). - * A **Subscription** describes the transformation of an event (via a - _Callable_) and optional storage of a returned event. +- A **Subscription** describes the transformation of an event and optional + forwarding of a returned event. - * A **Source** represents an ongoing selection of events from an external - system. A Subscription is used to connect these events to subsequent - processing steps. +- A **Source** allows an incoming events from an external system to be + _Subscribable_. A _Subscription_ is used to connect these events to + subsequent processing steps. - * A **Channel** provides event storage and fanout of events from a well-known - input address to multiple outputs described by Subscriptions. +- A **Channel** provides event persistance and fanout of events from a + well-known input address to multiple outputs described by _Subscriptions_. + ![Resource Types Overview](images/resource-types-overview.svg) - * **Provisioners** act as a catalog of the types of Sources and Channels - currently active in the eventing system. +- **Provisioners** implement strategies for realizing backing resources for + different implementations of _Sources_ and _Channels_ currently active in the + eventing system. + ![Resource Types Provisioners](images/resource-types-provisioner.svg) +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), +[Channelable](interfaces.md#channelable), +[Targetable](interfaces.md#targetable)). For more details, see +[Interface Contracts](interfaces.md). + ## Subscription -**Subscriptions** define the transport of events from one storage location -(typically, **Source** or **Channel**) to the next (typically, a **Channel**) -through optional transformations (such as a Knative Service which processes -CloudEvents over HTTP). A **Subscription** resolves the addresses of +**Subscriptions** describe a flow of events from one event producer or +forwarder (typically, _Source_ or _Channel_) to the next (typically, a +_Channel_) through transformations (such as a Knative Service which processes +CloudEvents over HTTP). A _Subscription_ controller resolves the addresses of transformations (`call`) and destination storage (`result`) through the -_Callable_ and _Sinkable_ interface contracts, and writes the resolved -addresses to the _Subscribable_ `from` resource. **Subscriptions** do not need -to specify both a transformation and a storage destination, but at least one -must be provided. +_Targetable_ and _Sinkable_ interface contracts, and writes the resolved +addresses to the _Subscribable_ `from` resource. _Subscriptions_ do not need to +specify both a transformation and a storage destination, but at least one must +be provided. -All event transport over a **Subscription** is 1:1 – only a single `from`, -`call`, and `result` may 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). ## Source -**Source** represents an ongoing selection of events from an external system, -such as object creation events in a specific storage bucket, database updates -in a particular table, or Kubernetes resource state changes. Because a -**Source** represents an external system, it only produces events (and is -therefore _Subscribable_ by **Subscriptions**). **Source** configures an -external system and may include parameters such as specific resource names, -event types, or credentials which should be used to establish the connection to -the external system. The set of allowed configuration parameters is described -by the **Provisioner** which is referenced by the **Source**. +**Source** represents incoming events from an external system, such as object +creation events in a specific storage bucket, database updates in a particular +table, or Kubernetes resource state changes. Because a _Source_ represents an +external system, it only produces events (and is therefore _Subscribable_ by +_Subscriptions_). _Source_ may include parameters such as specific resource +names, event types, or credentials which should be used to establish the +connection to the external system. The set of allowed configuration parameters +is described by the _Provisioner_ which is referenced by the _Source_. -Event selection on a **Source** is 1:N – a single **Source** may fan out to -multiple **Subscriptions**. +Event selection on a _Source_ is 1:N – a single _Source_ may fan out to +multiple _Subscriptions_. For more details, see [Kind: Source](spec.md#kind-source). ## Channel -**Channel** provides a durable event storage mechanism which can fan out -received events to multiple destinations via **Subscriptions**. A **Channel** +**Channel** provides an at least once event delivery mechanism which can fan +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. +_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 +_Provisioner_. + +Event selection on a _Channel_ is 1:N – a single _Channel_ may fan out to +multiple _Subscriptions_. See [Kind: Channel](spec.md#kind-channel). ## Provisioner -The eventing API has parallel constructs for event _sources_ (systems which -create events based on internal or external changes) and event _transports_ -(middleware which add value to the event delivery chain, such as persistence or -buffering). +**Provisioner** catalogs available implementations of event _Sources_ and +_Channels_. _Provisioners_ hold a JSON Schema that is used to validate the +_Source_ and _Channel_ input parameters. _Provisioners_ make it possible to +provide cluster wide defaults for the _Sources_ and _Channels_ they provision. -For more details, see [Kind: Provider](spec.md#kind-provisioner). +_Provisioners_ do not directly handle events. They are 1:N with _Sources_ and +_Channels_. ---- +For more details, see [Kind: Provider](spec.md#kind-provisioner). -*Next*: +--- -* [Motivation and goals](motivation.md) - -* [Interface contracts](interfaces.md) -* [Object model specification](spec.md) +_Navigation_: +- [Motivation and goals](motivation.md) +- **Resource type overview** +- [Interface contracts](interfaces.md) +- [Object model specification](spec.md) diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 436862f1715..69995d2eaf4 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -126,7 +126,7 @@ or a Channel system that receives and delivers events._ | Field | Type | Description | Limitations | | --- | --- | --- | --- | -| type*| TypeMeta1 | The type of the resource to be provisioned. | Must be Source or Channel. | +| type*| GroupKind1 | The type of the resource to be provisioned. | Must be Source or Channel. | \*: Required From fa7d76415850e53ca39259d5fa33361c0710b122 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 8 Oct 2018 10:26:33 -0700 Subject: [PATCH 24/60] Finished review. --- docs/spec/spec.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 69995d2eaf4..430ac2f0abf 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -82,8 +82,9 @@ Subscription's call parameter._ ##### Owner References - * If the Pipeline controller created this Channel: Owned by the originating Pipeline. - * Owned by the Provisioner used to provision the Channel. + * If the Source controller created this Channel: Owned by the originating + Source. + * Owned (non-controlling) by the Provisioner used to provision the Channel. #### Status @@ -164,7 +165,7 @@ or a Channel system that receives and delivers events._ ### group: eventing.knative.dev/v1alpha1 -_Describes a direct linkage between an event publisher and an action._ +_Describes a linkage between a Subscribable and a Targetable and/or Sinkable._ ### Object Schema @@ -265,7 +266,7 @@ non-controlling OwnerReference on the EventType resources it knows about. | Field | Type | Description | Limitations | | --- | --- | --- | --- | | ref1 | ObjectReference | | | -| selector1 | LabelSelector | | | +| selector1 | LabelSelector | | Must match only one resource. | 1: One of (name, selector), Required. @@ -284,7 +285,7 @@ non-controlling OwnerReference on the EventType resources it knows about. | --- | --- | --- | --- | | name*| String | Name of Object| | | type*| String | Fully Qualified Object type. | | -| status*| String | Current relationship between Provisioner and Object| | +| status*| String | Current relationship between Provisioner and Object. | | | reason | String | Detailed description describing current relationship status. | | \*: Required From 2765183362baabc6ad9d6d5dc7c5c616157cc08f Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 8 Oct 2018 10:28:02 -0700 Subject: [PATCH 25/60] ran prettier on spec. --- docs/spec/spec.md | 226 +++++++++++++++++++++++----------------------- 1 file changed, 113 insertions(+), 113 deletions(-) diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 430ac2f0abf..25914282154 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -4,10 +4,10 @@ This is the detailed specification of the Knative Eventing Object Model. For context, see the [overview](overview.md), [motivation](motivation.md), and the [interface contract](interfaces.md) documents. - * [Source](#kind-source) - * [Channel](#kind-channel) - * [Subscription](#kind-subscription) - * [Provider](#kind-provisioner) +- [Source](#kind-source) +- [Channel](#kind-channel) +- [Subscription](#kind-subscription) +- [Provider](#kind-provisioner) --- @@ -23,37 +23,37 @@ their status. They cannot receive events._ #### Spec -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | -| provisioner*| ProvisionerReference | The provisioner used to create any backing resources and configuration. | Immutable. | -| arguments | runtime.RawExtension (JSON object)| Arguments passed to the provisioner for this specific source. | Arguments must validate against provisioner's parameters. | -| channel | ObjectRef | Specify an existing channel to use to emit events. If empty, create a new Channel using the cluster/namespace default. | Source will not emit events until channel exists. | +| Field | Type | Description | Limitations | +| ------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | +| provisioner\* | ProvisionerReference | The provisioner used to create any backing resources and configuration. | Immutable. | +| arguments | runtime.RawExtension (JSON object) | Arguments passed to the provisioner for this specific source. | Arguments must validate against provisioner's parameters. | +| channel | ObjectRef | Specify an existing channel to use to emit events. If empty, create a new Channel using the cluster/namespace default. | Source will not emit events until channel exists. | \*: Required #### Status -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | -| subscribable | Subscribable | Pointer to a channel which can be subscribed to in order to receive events from this source. | | -| provisioned |[]ProvisionedObjectStatus| Creation status of each Channel and errors therein. | It is expected that a Source list all produced Channels. | +| Field | Type | Description | Limitations | +| ------------ | ------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------- | +| subscribable | Subscribable | Pointer to a channel which can be subscribed to in order to receive events from this source. | | +| provisioned | []ProvisionedObjectStatus | Creation status of each Channel and errors therein. | It is expected that a Source list all produced Channels. | ##### Conditions - * **Ready.** True when the Source is provisioned and ready to emit events. - * **Provisioned.** True when the Source has been provisioned by a controller. +- **Ready.** True when the Source is provisioned and ready to emit events. +- **Provisioned.** True when the Source has been provisioned by a controller. #### Events - * Provisioned - describes each resource that is provisioned. +- Provisioned - describes each resource that is provisioned. ### Life Cycle -| Action | Reactions | Limitations | -| --- | --- | --- | -| Create | Provisioner controller watches for Sources and creates the backing resources depending on implementation. | | -| Update | Provisioner controller synchronizes backing implementation on changes. | | -| Delete | Provisioner controller will deprovision backing resources depending on implementation. | | +| Action | Reactions | Limitations | +| ------ | --------------------------------------------------------------------------------------------------------- | ----------- | +| Create | Provisioner controller watches for Sources and creates the backing resources depending on implementation. | | +| Update | Provisioner controller synchronizes backing implementation on changes. | | +| Delete | Provisioner controller will deprovision backing resources depending on implementation. | | --- @@ -69,12 +69,12 @@ Subscription's call parameter._ #### Spec -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | -| provisioner*| ProvisionerReference | The name of the provisioner to create the resources that back the Channel. | Immutable. | -| arguments | runtime.RawExtension (JSON object)| Arguments to be passed to the provisioner. | | -| channelable | Channelable | Holds a list of downstream subscribers for the channel. | | -| eventTypes |[]String| An array of event types that will be passed on the Channel. | Must be objects with kind:EventType. | +| Field | Type | Description | Limitations | +| ------------- | ---------------------------------- | -------------------------------------------------------------------------- | ------------------------------------ | +| provisioner\* | ProvisionerReference | The name of the provisioner to create the resources that back the Channel. | Immutable. | +| arguments | runtime.RawExtension (JSON object) | Arguments to be passed to the provisioner. | | +| channelable | Channelable | Holds a list of downstream subscribers for the channel. | | +| eventTypes | []String | An array of event types that will be passed on the Channel. | Must be objects with kind:EventType. | \*: Required @@ -82,35 +82,35 @@ Subscription's call parameter._ ##### Owner References - * If the Source controller created this Channel: Owned by the originating - Source. - * Owned (non-controlling) by the Provisioner used to provision the Channel. +- If the Source controller created this Channel: Owned by the originating + Source. +- Owned (non-controlling) by the Provisioner used to provision the Channel. #### Status -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | -| Sinkable | Sinkable | Address to the endpoint as top-level domain that will distribute traffic over the provided targets from inside the cluster. | | -| subscribable | Subscribable | | | -| Conditions | Conditions | Standard Subscriptions| | +| Field | Type | Description | Limitations | +| ------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------- | ----------- | +| Sinkable | Sinkable | Address to the endpoint as top-level domain that will distribute traffic over the provided targets from inside the cluster. | | +| subscribable | Subscribable | | | +| Conditions | Conditions | Standard Subscriptions | | ##### Conditions - * **Ready.** True when the Channel is provisioned and ready to accept events. - * **Provisioned.** True when the Channel has been provisioned by a controller. +- **Ready.** True when the Channel is provisioned and ready to accept events. +- **Provisioned.** True when the Channel has been provisioned by a controller. #### Events - * Provisioned - * Deprovisioned +- Provisioned +- Deprovisioned ### Life Cycle -| Action | Reactions | Limitations | -| --- | --- | --- | +| Action | Reactions | Limitations | +| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | Create | The Provisioner referenced will take ownership of the Channel and begin provisioning the backing resources required for the Channel depending on implementation. | Only one Provisioner is allowed to be the Owner for a given Channel. | -| Update | The Provisioner will synchronize the Channel backing resources to reflect the update. | | -| Delete | The Provisioner will deprovision the backing resources if no longer required depending on implementation. | | +| Update | The Provisioner will synchronize the Channel backing resources to reflect the update. | | +| Delete | The Provisioner will deprovision the backing resources if no longer required depending on implementation. | | --- @@ -125,9 +125,9 @@ or a Channel system that receives and delivers events._ #### Spec -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | -| type*| GroupKind1 | The type of the resource to be provisioned. | Must be Source or Channel. | +| Field | Type | Description | Limitations | +| ------ | --------------------- | ------------------------------------------- | -------------------------- | +| type\* | GroupKind1 | The type of the resource to be provisioned. | Must be Source or Channel. | \*: Required @@ -137,27 +137,27 @@ or a Channel system that receives and delivers events._ ##### Owner References - * Owns EventTypes. +- Owns EventTypes. #### Status -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | -| provisioned |[]ProvisionedObjectStatus| Status of creation or adoption of each EventType and errors therein. | It is expected that a provisioner list all produced EventTypes, if applicable. | +| Field | Type | Description | Limitations | +| ----------- | ------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| provisioned | []ProvisionedObjectStatus | Status of creation or adoption of each EventType and errors therein. | It is expected that a provisioner list all produced EventTypes, if applicable. | #### Events - * Source created - * Source deleted - * Event types installed +- Source created +- Source deleted +- Event types installed ### Life Cycle -| Action | Reactions | Limitations | -| --- | --- | --- | +| Action | Reactions | Limitations | +| ------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | Create | Creates and owns EventTypes produced, or adds Owner ref to existing EventTypes. | Verifies Json Schema provided by existing EventTypes; Not allowed to edit EventType if previously Owned; | -| Update | Synchronizes EventTypes. | | -| Delete | Removes Owner ref from EventTypes. | | +| Update | Synchronizes EventTypes. | | +| Delete | Removes Owner ref from EventTypes. | | --- @@ -171,11 +171,11 @@ _Describes a linkage between a Subscribable and a Targetable and/or Sinkable._ #### Spec -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | -| from*| ObjectRef | The originating Channel for the link. | Must be a Channel. | -| call1 | EndpointSpec | Optional processing on the event. The result of call will be sent to result. | | -| result1 | ObjectRef | The continuation Channel for the link. | Must be a Channel. | +| Field | Type | Description | Limitations | +| ------------------ | ------------ | ---------------------------------------------------------------------------- | ------------------ | +| from\* | ObjectRef | The originating Channel for the link. | Must be a Channel. | +| call1 | EndpointSpec | Optional processing on the event. The result of call will be sent to result. | | +| result1 | ObjectRef | The continuation Channel for the link. | Must be a Channel. | \*: Required @@ -185,31 +185,31 @@ _Describes a linkage between a Subscribable and a Targetable and/or Sinkable._ ##### Owner References - * If a resource controller created this Subscription: Owned by the originating resource. +- If a resource controller created this Subscription: Owned by the originating + resource. ##### Conditions - * **Ready.** - * **FromReady.** - * **CallActive.** True if the call is sinking events without error. - * **Resolved.** +- **Ready.** +- **FromReady.** +- **CallActive.** True if the call is sinking events without error. +- **Resolved.** #### Events - * PublisherAcknowledged - * ActionFailed +- PublisherAcknowledged +- ActionFailed ### Life Cycle -| Action | Reactions | Limitations | -| --- | --- | --- | -| Create | The publisher referenced needs to be watching for Subscriptions. | | -| Update | | | -| Delete | | | +| Action | Reactions | Limitations | +| ------ | ---------------------------------------------------------------- | ----------- | +| Create | The publisher referenced needs to be watching for Subscriptions. | | +| Update | | | +| Delete | | | --- - ## kind: EventType NOTE: EventType is out of scope for 0.1 release. This is future documentation. @@ -223,39 +223,39 @@ source systems._ #### Spec -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | +| Field | Type | Description | Limitations | +| ---------- | ------ | --------------------------------------------------- | ------------------------------ | | jsonSchema | String | The Json Schema that represents an event in flight. | Only for JSON transport types. | #### Metadata ##### Owner References -EventType is owned by *Provisioners*. Each *Provisioner* creates a +EventType is owned by _Provisioners_. Each _Provisioner_ creates a non-controlling OwnerReference on the EventType resources it knows about. #### Status -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | -| referenceCount | Integer | Number of Owners for this EventType | | +| Field | Type | Description | Limitations | +| -------------- | ------- | ----------------------------------- | ----------- | +| referenceCount | Integer | Number of Owners for this EventType | | ##### Conditions - * **Pinned**. True when the EventType cannot be deleted. +- **Pinned**. True when the EventType cannot be deleted. #### Events - * **Owned.** When EventType has a new Provisioner Owner. - * **Released.** When a Provisioner removes Ownership from the EventType. +- **Owned.** When EventType has a new Provisioner Owner. +- **Released.** When a Provisioner removes Ownership from the EventType. ### Life Cycle -| Action | Reactions | Limitations | -| --- | --- | --- | -| Create | | | -| Update | | | -| Delete | | Blocked until all provisioners release it. | +| Action | Reactions | Limitations | +| ------ | --------- | ------------------------------------------ | +| Create | | | +| Update | | | +| Delete | | Blocked until all provisioners release it. | --- @@ -263,48 +263,48 @@ non-controlling OwnerReference on the EventType resources it knows about. ### ProvisionerReference -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | -| ref1 | ObjectReference | | | -| selector1 | LabelSelector | | Must match only one resource. | +| Field | Type | Description | Limitations | +| -------------------- | --------------- | ----------- | ----------------------------- | +| ref1 | ObjectReference | | | +| selector1 | LabelSelector | | Must match only one resource. | 1: One of (name, selector), Required. ### EndpointSpec -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | -| targetRef1 | ObjectReference | | Must adhere to Targetable. | -| dnsName1 | String | | | +| Field | Type | Description | Limitations | +| --------------------- | --------------- | ----------- | -------------------------- | +| targetRef1 | ObjectReference | | Must adhere to Targetable. | +| dnsName1 | String | | | 1: One of (targetRef, dnsName), Required. ### ProvisionedObjectStatus -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | -| name*| String | Name of Object| | -| type*| String | Fully Qualified Object type. | | -| status*| String | Current relationship between Provisioner and Object. | | -| reason | String | Detailed description describing current relationship status. | | +| Field | Type | Description | Limitations | +| -------- | ------ | ------------------------------------------------------------ | ----------- | +| name\* | String | Name of Object | | +| type\* | String | Fully Qualified Object type. | | +| status\* | String | Current relationship between Provisioner and Object. | | +| reason | String | Detailed description describing current relationship status. | | \*: Required ### Subscribable -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | -| channelable | ObjectReference | The channel used to emit events. | | +| Field | Type | Description | Limitations | +| ----------- | --------------- | -------------------------------- | ----------- | +| channelable | ObjectReference | The channel used to emit events. | | ### Channelable -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | -| subscribers | ChannelSubscriberSpec[]| Information about subscriptions used to implement message forwarding. | Filled out by Subscription Controller. | +| Field | Type | Description | Limitations | +| ----------- | ----------------------- | --------------------------------------------------------------------- | -------------------------------------- | +| subscribers | ChannelSubscriberSpec[] | Information about subscriptions used to implement message forwarding. | Filled out by Subscription Controller. | ### ChannelSubscriberSpec -| Field | Type | Description | Limitations | -| --- | --- | --- | --- | -| callableDomain | String | The domain name of the endpoint for the call. | | -| sinkableDomain | String | The domain name of the endpoint for the result. | | +| Field | Type | Description | Limitations | +| -------------- | ------ | ----------------------------------------------- | ----------- | +| callableDomain | String | The domain name of the endpoint for the call. | | +| sinkableDomain | String | The domain name of the endpoint for the result. | | From 9de5e7ef92e93289135e314033105f70f17e991a Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Tue, 9 Oct 2018 08:56:25 -0700 Subject: [PATCH 26/60] more feedback updates. --- docs/spec/interfaces.md | 6 +-- docs/spec/overview.md | 19 ------- docs/spec/spec.md | 110 +++++++++++++++++++++------------------- 3 files changed, 61 insertions(+), 74 deletions(-) diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index 355a45d0332..87ab5bcec9d 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -34,9 +34,9 @@ for delivering events to each of them. ### Control Plane -The **Channelable** resource has a list of _subscribers_ within the resources -_spec.channelable_. In practice, the resolved _subscription_ _call_ and -_result_ endpoints populate the Channelable's list of _subscribers_. +The **Channelable** resource stores a list of resolved _Subscriptions_. The +Subscription Controller is responsible for resolving any ObjectReferences (such +as _call_ and _result_) in the _Subscription_ to network addresses. ### Data Plane diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 0aa4fb951ae..017a90a3d7e 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -1,22 +1,3 @@ -# Overview - -In the serverless model, computation and storage can be intertwined by having -storage and compute systems publish events which are handled asynchronously by -further compute services. Event delivery provides common infrastructure for -decoupling event producers and consumers such that the linking between them can -be performed without change to either. Loosely coupled eventing systems enable -composable services which retain the ability to scale independently. -Declarative event binding reduces the effort to create a scalable system that -combines managed services and custom code. - -Knative eventing implements common components of an event delivery ecosystem: -enumeration and discovery of event sources, configuration and management of -event transport, and declarative binding of events (generated either by storage -services or earlier computation) for further event processing and persistence. - -The following is a detailed specification for the `eventing.knative.dev` API -surface, which provides control mechanism for Knative eventing. - # Resource Types The API defines and provides a complete implementation for diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 25914282154..9d1130c0922 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -1,8 +1,13 @@ # Object Model -This is the detailed specification of the Knative Eventing Object Model. For -context, see the [overview](overview.md), [motivation](motivation.md), and the -[interface contract](interfaces.md) documents. +Knative ships with several objects which implement useful sets of +[interfaces](interfaces.md). It is expected that additional objects which +implement other sets of interfaces will be added over time. For context, see +the [overview](overview.md) and [motivations](motivation.md) sections. + +These are Kubernetes resources that been introduced using Custom Resource +Definitions. They will have the expected _ObjectMeta_, _Spec_, _Status_ fields. +This document details our _Spec_ and _Status_ customizations. - [Source](#kind-source) - [Channel](#kind-channel) @@ -16,8 +21,9 @@ context, see the [overview](overview.md), [motivation](motivation.md), and the ### group: eventing.knative.dev/v1alpha1 _Describes a specific configuration (credentials, etc) of a source system which -can be used to supply events. Sources emit events using a channel specified in -their status. They cannot receive events._ +can be used to supply events. A common pattern is for Sources to emit events to +Channel to allow event delivery to be fanned-out within the cluster. They +cannot receive events._ ### Object Schema @@ -37,6 +43,7 @@ their status. They cannot receive events._ | ------------ | ------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | subscribable | Subscribable | Pointer to a channel which can be subscribed to in order to receive events from this source. | | | provisioned | []ProvisionedObjectStatus | Creation status of each Channel and errors therein. | It is expected that a Source list all produced Channels. | +| conditions | Conditions | Source conditions. | | ##### Conditions @@ -90,9 +97,9 @@ Subscription's call parameter._ | Field | Type | Description | Limitations | | ------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------- | ----------- | -| Sinkable | Sinkable | Address to the endpoint as top-level domain that will distribute traffic over the provided targets from inside the cluster. | | +| sinkable | Sinkable | Address to the endpoint as top-level domain that will distribute traffic over the provided targets from inside the cluster. | | | subscribable | Subscribable | | | -| Conditions | Conditions | Standard Subscriptions | | +| conditions | Conditions | Standard Subscriptions | | ##### Conditions @@ -114,99 +121,102 @@ Subscription's call parameter._ --- -## kind: Provisioner +## kind: Subscription ### group: eventing.knative.dev/v1alpha1 -_Describes an abstract configuration of a Source system which produces events -or a Channel system that receives and delivers events._ +_Describes a linkage between a Subscribable and a Targetable and/or Sinkable._ ### Object Schema #### Spec -| Field | Type | Description | Limitations | -| ------ | --------------------- | ------------------------------------------- | -------------------------- | -| type\* | GroupKind1 | The type of the resource to be provisioned. | Must be Source or Channel. | +| Field | Type | Description | Limitations | +| ------------------ | ------------ | ---------------------------------------------------------------------------- | ------------------ | +| from\* | ObjectRef | The originating Channel for the link. | Must be a Channel. | +| call1 | EndpointSpec | Optional processing on the event. The result of call will be sent to result. | | +| result1 | ObjectRef | The continuation Channel for the link. | Must be a Channel. | \*: Required -1: Kubernetes type. +1: At Least One(call, result) #### Metadata ##### Owner References -- Owns EventTypes. +- If a resource controller created this Subscription: Owned by the originating + resource. -#### Status +##### Conditions -| Field | Type | Description | Limitations | -| ----------- | ------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------ | -| provisioned | []ProvisionedObjectStatus | Status of creation or adoption of each EventType and errors therein. | It is expected that a provisioner list all produced EventTypes, if applicable. | +- **Ready.** +- **FromReady.** +- **CallActive.** True if the call is sinking events without error. +- **Resolved.** #### Events -- Source created -- Source deleted -- Event types installed +- PublisherAcknowledged +- ActionFailed ### Life Cycle -| Action | Reactions | Limitations | -| ------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| Create | Creates and owns EventTypes produced, or adds Owner ref to existing EventTypes. | Verifies Json Schema provided by existing EventTypes; Not allowed to edit EventType if previously Owned; | -| Update | Synchronizes EventTypes. | | -| Delete | Removes Owner ref from EventTypes. | | +| Action | Reactions | Limitations | +| ------ | ---------------------------------------------------------------- | ----------- | +| Create | The publisher referenced needs to be watching for Subscriptions. | | +| Update | | | +| Delete | | | --- -## kind: Subscription +## kind: Provisioner ### group: eventing.knative.dev/v1alpha1 -_Describes a linkage between a Subscribable and a Targetable and/or Sinkable._ +_Describes an abstract configuration of a Source system which produces events +or a Channel system that receives and delivers events._ ### Object Schema #### Spec -| Field | Type | Description | Limitations | -| ------------------ | ------------ | ---------------------------------------------------------------------------- | ------------------ | -| from\* | ObjectRef | The originating Channel for the link. | Must be a Channel. | -| call1 | EndpointSpec | Optional processing on the event. The result of call will be sent to result. | | -| result1 | ObjectRef | The continuation Channel for the link. | Must be a Channel. | +| Field | Type | Description | Limitations | +| ------ | ------------------------------------------------------------------------------- | ------------------------------------------- | -------------------------- | +| type\* | [GroupKind](https://godoc.org/k8s.io/apimachinery/pkg/runtime/schema#GroupKind) | The type of the resource to be provisioned. | Must be Source or Channel. | \*: Required -1: At Least One(call, result) - #### Metadata ##### Owner References -- If a resource controller created this Subscription: Owned by the originating - resource. +- Owns EventTypes. + +#### Status + +| Field | Type | Description | Limitations | +| ----------- | ------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| provisioned | []ProvisionedObjectStatus | Status of creation or adoption of each EventType and errors therein. | It is expected that a provisioner list all produced EventTypes, if applicable. | +| conditions | Conditions | Provisioner conditions | | ##### Conditions - **Ready.** -- **FromReady.** -- **CallActive.** True if the call is sinking events without error. -- **Resolved.** #### Events -- PublisherAcknowledged -- ActionFailed +- Source created +- Source deleted +- Event types installed ### Life Cycle -| Action | Reactions | Limitations | -| ------ | ---------------------------------------------------------------- | ----------- | -| Create | The publisher referenced needs to be watching for Subscriptions. | | -| Update | | | -| Delete | | | +| Action | Reactions | Limitations | +| ------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| Create | Creates and owns EventTypes produced, or adds Owner ref to existing EventTypes. | Verifies Json Schema provided by existing EventTypes; Not allowed to edit EventType if previously Owned; | +| Update | Synchronizes EventTypes. | | +| Delete | Removes Owner ref from EventTypes. | | --- @@ -240,10 +250,6 @@ non-controlling OwnerReference on the EventType resources it knows about. | -------------- | ------- | ----------------------------------- | ----------- | | referenceCount | Integer | Number of Owners for this EventType | | -##### Conditions - -- **Pinned**. True when the EventType cannot be deleted. - #### Events - **Owned.** When EventType has a new Provisioner Owner. From e811c5fc7c2ea7f68a05285b78e2927074064795 Mon Sep 17 00:00:00 2001 From: Scott Andrews Date: Thu, 11 Oct 2018 11:41:42 -0400 Subject: [PATCH 27/60] Remove ProvisionerReference label selector The requirement that the selector only match a single resource is impossible in enforce. Label selectors are typically used to query for a set of resources. For this field to be implemented, every Provisioner would need to test the selector on itself. --- docs/spec/spec.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 9d1130c0922..e88fed44e1a 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -269,12 +269,11 @@ non-controlling OwnerReference on the EventType resources it knows about. ### ProvisionerReference -| Field | Type | Description | Limitations | -| -------------------- | --------------- | ----------- | ----------------------------- | -| ref1 | ObjectReference | | | -| selector1 | LabelSelector | | Must match only one resource. | +| Field | Type | Description | Limitations | +| ----- | --------------- | ----------- | ----------- | +| ref\* | ObjectReference | | | -1: One of (name, selector), Required. +\*: Required ### EndpointSpec From b720910618c420f3e59cf69aa01da45350095e66 Mon Sep 17 00:00:00 2001 From: Scott Andrews Date: Thu, 11 Oct 2018 11:36:42 -0400 Subject: [PATCH 28/60] Remove EventType resource The EventType resource has been deferred from the initial implementation. As such it is dead code. Once we are ready to discuss the EventType resource it can be brought back. --- docs/spec/overview.md | 6 ++-- docs/spec/spec.md | 68 ++----------------------------------------- 2 files changed, 6 insertions(+), 68 deletions(-) diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 017a90a3d7e..23c21690f1b 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -62,9 +62,9 @@ creation events in a specific storage bucket, database updates in a particular table, or Kubernetes resource state changes. Because a _Source_ represents an external system, it only produces events (and is therefore _Subscribable_ by _Subscriptions_). _Source_ may include parameters such as specific resource -names, event types, or credentials which should be used to establish the -connection to the external system. The set of allowed configuration parameters -is described by the _Provisioner_ which is referenced by the _Source_. +names, or credentials which should be used to establish the connection to the +external system. The set of allowed configuration parameters is described by +the _Provisioner_ which is referenced by the _Source_. Event selection on a _Source_ is 1:N – a single _Source_ may fan out to multiple _Subscriptions_. diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 9d1130c0922..d297a69dab6 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -81,7 +81,6 @@ Subscription's call parameter._ | provisioner\* | ProvisionerReference | The name of the provisioner to create the resources that back the Channel. | Immutable. | | arguments | runtime.RawExtension (JSON object) | Arguments to be passed to the provisioner. | | | channelable | Channelable | Holds a list of downstream subscribers for the channel. | | -| eventTypes | []String | An array of event types that will be passed on the Channel. | Must be objects with kind:EventType. | \*: Required @@ -187,18 +186,11 @@ or a Channel system that receives and delivers events._ \*: Required -#### Metadata - -##### Owner References - -- Owns EventTypes. - #### Status -| Field | Type | Description | Limitations | -| ----------- | ------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------ | -| provisioned | []ProvisionedObjectStatus | Status of creation or adoption of each EventType and errors therein. | It is expected that a provisioner list all produced EventTypes, if applicable. | -| conditions | Conditions | Provisioner conditions | | +| Field | Type | Description | Limitations | +| ----------- | ------------------------- | ---------------------- | ----------- | +| conditions | Conditions | Provisioner conditions | | ##### Conditions @@ -208,60 +200,6 @@ or a Channel system that receives and delivers events._ - Source created - Source deleted -- Event types installed - -### Life Cycle - -| Action | Reactions | Limitations | -| ------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| Create | Creates and owns EventTypes produced, or adds Owner ref to existing EventTypes. | Verifies Json Schema provided by existing EventTypes; Not allowed to edit EventType if previously Owned; | -| Update | Synchronizes EventTypes. | | -| Delete | Removes Owner ref from EventTypes. | | - ---- - -## kind: EventType - -NOTE: EventType is out of scope for 0.1 release. This is future documentation. - -### group: eventing.knative.dev/v1alpha1 - -_Describes a particular schema of Events which may be produced by one or more -source systems._ - -### Object Schema - -#### Spec - -| Field | Type | Description | Limitations | -| ---------- | ------ | --------------------------------------------------- | ------------------------------ | -| jsonSchema | String | The Json Schema that represents an event in flight. | Only for JSON transport types. | - -#### Metadata - -##### Owner References - -EventType is owned by _Provisioners_. Each _Provisioner_ creates a -non-controlling OwnerReference on the EventType resources it knows about. - -#### Status - -| Field | Type | Description | Limitations | -| -------------- | ------- | ----------------------------------- | ----------- | -| referenceCount | Integer | Number of Owners for this EventType | | - -#### Events - -- **Owned.** When EventType has a new Provisioner Owner. -- **Released.** When a Provisioner removes Ownership from the EventType. - -### Life Cycle - -| Action | Reactions | Limitations | -| ------ | --------- | ------------------------------------------ | -| Create | | | -| Update | | | -| Delete | | Blocked until all provisioners release it. | --- From ae345a97cfd25df4a61931a072fef1c7b043dc5e Mon Sep 17 00:00:00 2001 From: Scott Andrews Date: Thu, 11 Oct 2018 12:25:40 -0400 Subject: [PATCH 29/60] Document ResultStrategy as implemented --- docs/spec/spec.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 9d1130c0922..5b111c806a4 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -131,11 +131,11 @@ _Describes a linkage between a Subscribable and a Targetable and/or Sinkable._ #### Spec -| Field | Type | Description | Limitations | -| ------------------ | ------------ | ---------------------------------------------------------------------------- | ------------------ | -| from\* | ObjectRef | The originating Channel for the link. | Must be a Channel. | -| call1 | EndpointSpec | Optional processing on the event. The result of call will be sent to result. | | -| result1 | ObjectRef | The continuation Channel for the link. | Must be a Channel. | +| Field | Type | Description | Limitations | +| ------------------ | -------------- | ---------------------------------------------------------------------------- | ------------------ | +| from\* | ObjectRef | The originating Channel for the link. | Must be a Channel. | +| call1 | EndpointSpec | Optional processing on the event. The result of call will be sent to result. | | +| result1 | ResultStrategy | The continuation for the link. | | \*: Required @@ -314,3 +314,11 @@ non-controlling OwnerReference on the EventType resources it knows about. | -------------- | ------ | ----------------------------------------------- | ----------- | | callableDomain | String | The domain name of the endpoint for the call. | | | sinkableDomain | String | The domain name of the endpoint for the result. | | + +### ResultStrategy + +| Field | Type | Description | Limitations | +| -------- | --------- | -------------------------------------- | ------------------ | +| target\* | ObjectRef | The continuation Channel for the link. | Must be a Channel. | + +\*: Required From 8746992d6a76f9ef3413ae4728b1b483d9bfc926 Mon Sep 17 00:00:00 2001 From: Scott Andrews Date: Thu, 11 Oct 2018 13:26:04 -0400 Subject: [PATCH 30/60] Clarify that only a Channel is subscribeable - remove Subscribeable interface - Source now requires a Channel ObjectRef - cleanup language arround the role of a Source --- docs/spec/interfaces.md | 21 --------------------- docs/spec/overview.md | 21 +++++++++------------ docs/spec/spec.md | 12 ++---------- 3 files changed, 11 insertions(+), 43 deletions(-) diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index 87ab5bcec9d..2831ae08157 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -6,27 +6,6 @@ --- -## Subscribable - -A **Subscribable** resource will emit events that one or more _Subscription_ -can direct to their configured destination. - -### Control Plane - -A **Subscribable** resource may be referenced in the _from_ field of a -_Subscription_. The _Subscribable_ resource MUST expose a -_status.subscribable.channelable_ field (an _ObjectReference_). The resource -referenced in the _status.subscribable.channelable_ field MUST be a -_Channelable_ resource; the field MAY refer back to this _Subscribable_ as a -self referenced resource. - -### Data Plane - -A **Subscribable** resource produces or forwards events via its -_status.subscribable.channelable_ resource. - ---- - ## Channelable A **Channelable** resource contains a list of subscribers and is responsible diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 017a90a3d7e..2bbc19addcc 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -9,9 +9,7 @@ backing implementations (much like the Kubernetes Ingress resource). - A **Subscription** describes the transformation of an event and optional forwarding of a returned event. -- A **Source** allows an incoming events from an external system to be - _Subscribable_. A _Subscription_ is used to connect these events to - subsequent processing steps. +- A **Source** emits incoming events to a _Channel_. - A **Channel** provides event persistance and fanout of events from a well-known input address to multiple outputs described by _Subscriptions_. @@ -33,7 +31,6 @@ 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), [Channelable](interfaces.md#channelable), [Targetable](interfaces.md#targetable)). For more details, see [Interface Contracts](interfaces.md). @@ -46,9 +43,9 @@ _Channel_) through transformations (such as a Knative Service which processes 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 _Subscribable_ `from` resource. _Subscriptions_ do not need to -specify both a transformation and a storage destination, but at least one must -be provided. +addresses to the _Channel_ in the `from` reference. _Subscriptions_ do not +need 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. @@ -60,11 +57,11 @@ For more details, see [Kind: Subscription](spec.md#kind-subscription). **Source** represents incoming events from an external system, such as object creation events in a specific storage bucket, database updates in a particular table, or Kubernetes resource state changes. Because a _Source_ represents an -external system, it only produces events (and is therefore _Subscribable_ by -_Subscriptions_). _Source_ may include parameters such as specific resource -names, event types, or credentials which should be used to establish the -connection to the external system. The set of allowed configuration parameters -is described by the _Provisioner_ which is referenced by the _Source_. +external system, it only emits events. _Source_ may include parameters such as +specific resource names, event types, or credentials which should be used to +establish the connection to the external system. The set of allowed +configuration parameters is described by the _Provisioner_ which is referenced +by the _Source_. Event selection on a _Source_ is 1:N – a single _Source_ may fan out to multiple _Subscriptions_. diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 9d1130c0922..2f9884e2d8d 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -33,7 +33,7 @@ cannot receive events._ | ------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | provisioner\* | ProvisionerReference | The provisioner used to create any backing resources and configuration. | Immutable. | | arguments | runtime.RawExtension (JSON object) | Arguments passed to the provisioner for this specific source. | Arguments must validate against provisioner's parameters. | -| channel | ObjectRef | Specify an existing channel to use to emit events. If empty, create a new Channel using the cluster/namespace default. | Source will not emit events until channel exists. | +| channel\* | ObjectRef | Specify a Channel to target. | Source will not emit events until channel exists. | \*: Required @@ -41,7 +41,6 @@ cannot receive events._ | Field | Type | Description | Limitations | | ------------ | ------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------- | -| subscribable | Subscribable | Pointer to a channel which can be subscribed to in order to receive events from this source. | | | provisioned | []ProvisionedObjectStatus | Creation status of each Channel and errors therein. | It is expected that a Source list all produced Channels. | | conditions | Conditions | Source conditions. | | @@ -98,7 +97,6 @@ Subscription's call parameter._ | Field | Type | Description | Limitations | | ------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------- | ----------- | | sinkable | Sinkable | Address to the endpoint as top-level domain that will distribute traffic over the provided targets from inside the cluster. | | -| subscribable | Subscribable | | | | conditions | Conditions | Standard Subscriptions | | ##### Conditions @@ -125,7 +123,7 @@ Subscription's call parameter._ ### group: eventing.knative.dev/v1alpha1 -_Describes a linkage between a Subscribable and a Targetable and/or Sinkable._ +_Describes a linkage between a Channel and a Targetable and/or Sinkable._ ### Object Schema @@ -296,12 +294,6 @@ non-controlling OwnerReference on the EventType resources it knows about. \*: Required -### Subscribable - -| Field | Type | Description | Limitations | -| ----------- | --------------- | -------------------------------- | ----------- | -| channelable | ObjectReference | The channel used to emit events. | | - ### Channelable | Field | Type | Description | Limitations | From de9e4f858535a8d1a31ba84a8abc13e4f4d76e47 Mon Sep 17 00:00:00 2001 From: Scott Andrews Date: Fri, 12 Oct 2018 11:10:08 -0400 Subject: [PATCH 31/60] Define Provisoner parameters Provisioned resources are able to define arguments to the provisioner. The provisioner needs to describe what arguments are valid in some way in order for tooling to provide any support for users beyond a black box. The overview already states that the provisioner is to define a JSON schema to validate the args, but does not say where that schema exists. --- docs/spec/overview.md | 2 +- docs/spec/spec.md | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 017a90a3d7e..05ec645fbc3 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -90,7 +90,7 @@ See [Kind: Channel](spec.md#kind-channel). **Provisioner** catalogs available implementations of event _Sources_ and _Channels_. _Provisioners_ hold a JSON Schema that is used to validate the -_Source_ and _Channel_ input parameters. _Provisioners_ make it possible to +_Source_ and _Channel_ input arguments. _Provisioners_ make it possible to provide cluster wide defaults for the _Sources_ and _Channels_ they provision. _Provisioners_ do not directly handle events. They are 1:N with _Sources_ and diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 5b111c806a4..b88cf9d1665 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -181,9 +181,10 @@ or a Channel system that receives and delivers events._ #### Spec -| Field | Type | Description | Limitations | -| ------ | ------------------------------------------------------------------------------- | ------------------------------------------- | -------------------------- | -| type\* | [GroupKind](https://godoc.org/k8s.io/apimachinery/pkg/runtime/schema#GroupKind) | The type of the resource to be provisioned. | Must be Source or Channel. | +| Field | Type | Description | Limitations | +| ---------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------- | +| type\* | [GroupKind](https://godoc.org/k8s.io/apimachinery/pkg/runtime/schema#GroupKind) | The type of the resource to be provisioned. | Must be Source or Channel. | +| parameters | runtime.RawExtension (JSON object) | Description of the arguments able to be passed by the provisioned resource. | JSON Schema | \*: Required From bda77a0f950ae76d1fb029f132216e099ca13d4b Mon Sep 17 00:00:00 2001 From: Matthias Wessendorf Date: Mon, 15 Oct 2018 12:14:00 +0200 Subject: [PATCH 32/60] remove reference that Source has subscriptions --- docs/spec/overview.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 2bbc19addcc..fc7e4c53ffe 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -63,9 +63,6 @@ establish the connection to the external system. The set of allowed configuration parameters is described by the _Provisioner_ which is referenced by the _Source_. -Event selection on a _Source_ is 1:N – a single _Source_ may fan out to -multiple _Subscriptions_. - For more details, see [Kind: Source](spec.md#kind-source). ## Channel From befda6fae550b5a6ea00a1b48940b8d66c21bba5 Mon Sep 17 00:00:00 2001 From: Matthias Wessendorf Date: Mon, 15 Oct 2018 13:30:48 +0200 Subject: [PATCH 33/60] Adding some clarification 1:1 Source/Channel, and adding fanout example desc. --- docs/spec/overview.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/spec/overview.md b/docs/spec/overview.md index fc7e4c53ffe..8ccd751d765 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -57,12 +57,18 @@ For more details, see [Kind: Subscription](spec.md#kind-subscription). **Source** represents incoming events from an external system, such as object creation events in a specific storage bucket, database updates in a particular table, or Kubernetes resource state changes. Because a _Source_ represents an -external system, it only emits events. _Source_ may include parameters such as -specific resource names, event types, or credentials which should be used to +external system, it only emits events to a _Channel_. A _Source_ may include `arguments` +such as specific resource names, event types, or credentials which should be used to establish the connection to the external system. The set of allowed configuration parameters is described by the _Provisioner_ which is referenced by the _Source_. +Every _Source_ has exactly one _Channel_, ensuring that each _Source_ is responsible for a _single_ event delivery. + +### Fanout Example + +If we take Cloud PubSub as an example, the _Source_ resource would reference the topic name it wants to bind to. The _Provisioner_ for the _Source_ would create a PubSub subscription for it and the _Source_ starts receiving messages. If we also want to bind the **same** PubSub topic to multiple destinations, we will create a new _Source_ for **each** destination. In this model each new _Source_ will create an **independent** PubSub subscription to the **same** topic, ensuring that each Source is responsible for a single event delivery. The actual fanout is now pushed into the Cloud PubSub, yet still is resilient to failed deliveries. + For more details, see [Kind: Source](spec.md#kind-source). ## Channel From e692af76e7be147bacf4ef91e3a7f5690b15de49 Mon Sep 17 00:00:00 2001 From: Matthias Wessendorf Date: Tue, 16 Oct 2018 14:23:37 +0200 Subject: [PATCH 34/60] It should not just be HTTP --- docs/spec/motivation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/spec/motivation.md b/docs/spec/motivation.md index 6c9e4564adc..6417f11b16c 100644 --- a/docs/spec/motivation.md +++ b/docs/spec/motivation.md @@ -25,10 +25,10 @@ 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. +primitives for event production and delivery with an initial 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. Knative eventing implements common components of an event delivery ecosystem: enumeration and discovery of event sources, configuration and management of From 60425d46667befeaf85f2b4a88be90b4c8250086 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Thu, 18 Oct 2018 13:01:20 -0700 Subject: [PATCH 35/60] fixed up overview, need to update the pictures. --- docs/spec/overview.md | 46 +++++++++++++------------------------------ 1 file changed, 14 insertions(+), 32 deletions(-) diff --git a/docs/spec/overview.md b/docs/spec/overview.md index fcfaf5c56cd..319efc1a83a 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -2,15 +2,13 @@ The API defines and provides a complete implementation for [Subscription](spec.md#kind-subscription), and abstract resource definitions -for [Sources](spec.md#kind-source), [Channels](spec.md#kind-channel), and -[Providers](spec.md#kind-provisioner) which may be fulfilled by multiple -backing implementations (much like the Kubernetes Ingress resource). +for [Channels](spec.md#kind-channel) and [Providers](spec.md#kind-provisioner) +which may be fulfilled by multiple backing implementations (much like the +Kubernetes Ingress resource). - A **Subscription** describes the transformation of an event and optional forwarding of a returned event. -- A **Source** emits incoming events to a _Channel_. - - A **Channel** provides event persistance and fanout of events from a well-known input address to multiple outputs described by _Subscriptions_. @@ -31,41 +29,26 @@ 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), -[Channelable](interfaces.md#channelable), +[Subscribable](interfaces.md#Subscribable), [Targetable](interfaces.md#targetable)). For more details, see [Interface Contracts](interfaces.md). ## Subscription -**Subscriptions** describe a flow of events from one event producer or -forwarder (typically, _Source_ or _Channel_) to the next (typically, a -_Channel_) through transformations (such as a Knative Service which processes +**Subscriptions** describe a flow of events from one _Channel_) to the next +Channel_ through transformations (such as a Knative Service which processes 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 to specify both a transformation and a storage destination, but at least -one must be provided. +addresses to the _Channel_ in the `from` reference. _Subscriptions_ do not need +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). -## Source - -**Source** represents incoming events from an external system, such as object -creation events in a specific storage bucket, database updates in a particular -table, or Kubernetes resource state changes. Because a _Source_ represents an - -Every _Source_ has exactly one _Channel_, ensuring that each _Source_ is responsible for a _single_ event delivery. - -### Fanout Example - -If we take Cloud PubSub as an example, the _Source_ resource would reference the topic name it wants to bind to. The _Provisioner_ for the _Source_ would create a PubSub subscription for it and the _Source_ starts receiving messages. If we also want to bind the **same** PubSub topic to multiple destinations, we will create a new _Source_ for **each** destination. In this model each new _Source_ will create an **independent** PubSub subscription to the **same** topic, ensuring that each Source is responsible for a single event delivery. The actual fanout is now pushed into the Cloud PubSub, yet still is resilient to failed deliveries. - -For more details, see [Kind: Source](spec.md#kind-source). - ## Channel **Channel** provides an at least once event delivery mechanism which can fan @@ -83,13 +66,12 @@ See [Kind: Channel](spec.md#kind-channel). ## Provisioner -**Provisioner** catalogs available implementations of event _Sources_ and -_Channels_. _Provisioners_ hold a JSON Schema that is used to validate the -_Source_ and _Channel_ input arguments. _Provisioners_ make it possible to -provide cluster wide defaults for the _Sources_ and _Channels_ they provision. +**Provisioner** catalogs available implementations of _Channels_. +_Provisioners_ hold a JSON Schema that is used to validate the _Source_ and +_Channel_ input arguments. _Provisioners_ make it possible to provide cluster +wide defaults for the _Channels_ they provision. -_Provisioners_ do not directly handle events. They are 1:N with _Sources_ and -_Channels_. +_Provisioners_ do not directly handle events. They are 1:N with _Channels_. For more details, see [Kind: Provider](spec.md#kind-provisioner). From f9923917a60e22597411d90a2678c239c0fceffd Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Thu, 18 Oct 2018 13:09:55 -0700 Subject: [PATCH 36/60] First pass scrub to remove source. --- docs/spec/interfaces.md | 6 +-- docs/spec/overview.md | 12 +++--- docs/spec/spec.md | 89 +++++++++-------------------------------- 3 files changed, 27 insertions(+), 80 deletions(-) diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index 2831ae08157..ea8c057d79c 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -6,14 +6,14 @@ --- -## Channelable +## Subscribable -A **Channelable** resource contains a list of subscribers and is responsible +A **Subscribable** resource contains a list of subscribers and is responsible for delivering events to each of them. ### Control Plane -The **Channelable** resource stores a list of resolved _Subscriptions_. The +The **Subscribable** resource stores a list of resolved _Subscriptions_. The Subscription Controller is responsible for resolving any ObjectReferences (such as _call_ and _result_) in the _Subscription_ to network addresses. diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 319efc1a83a..8c10564583a 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -17,8 +17,8 @@ Kubernetes Ingress resource). ![Resource Types Overview](images/resource-types-overview.svg) - **Provisioners** implement strategies for realizing backing resources for - different implementations of _Sources_ and _Channels_ currently active in the - eventing system. + different implementations of _Channels_ currently active in the eventing + system. @@ -36,7 +36,7 @@ objects. The interfaces are ([Sinkable](interfaces.md#sinkable), ## Subscription **Subscriptions** describe a flow of events from one _Channel_) to the next -Channel_ through transformations (such as a Knative Service which processes +Channel* through transformations (such as a Knative Service which processes 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 @@ -67,9 +67,9 @@ See [Kind: Channel](spec.md#kind-channel). ## Provisioner **Provisioner** catalogs available implementations of _Channels_. -_Provisioners_ hold a JSON Schema that is used to validate the _Source_ and -_Channel_ input arguments. _Provisioners_ make it possible to provide cluster -wide defaults for the _Channels_ they provision. +_Provisioners_ hold a JSON Schema that is used to validate the _Channel_ input +arguments. _Provisioners_ make it possible to provide cluster wide defaults for +the _Channels_ they provision. _Provisioners_ do not directly handle events. They are 1:N with _Channels_. diff --git a/docs/spec/spec.md b/docs/spec/spec.md index feb5404c49a..cc8c408035a 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -9,60 +9,10 @@ These are Kubernetes resources that been introduced using Custom Resource Definitions. They will have the expected _ObjectMeta_, _Spec_, _Status_ fields. This document details our _Spec_ and _Status_ customizations. -- [Source](#kind-source) - [Channel](#kind-channel) - [Subscription](#kind-subscription) - [Provider](#kind-provisioner) ---- - -## kind: Source - -### group: eventing.knative.dev/v1alpha1 - -_Describes a specific configuration (credentials, etc) of a source system which -can be used to supply events. A common pattern is for Sources to emit events to -Channel to allow event delivery to be fanned-out within the cluster. They -cannot receive events._ - -### Object Schema - -#### Spec - -| Field | Type | Description | Limitations | -| ------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | -| provisioner\* | ProvisionerReference | The provisioner used to create any backing resources and configuration. | Immutable. | -| arguments | runtime.RawExtension (JSON object) | Arguments passed to the provisioner for this specific source. | Arguments must validate against provisioner's parameters. | -| channel\* | ObjectRef | Specify a Channel to target. | Source will not emit events until channel exists. | - -\*: Required - -#### Status - -| Field | Type | Description | Limitations | -| ------------ | ------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------- | -| provisioned | []ProvisionedObjectStatus | Creation status of each Channel and errors therein. | It is expected that a Source list all produced Channels. | -| conditions | Conditions | Source conditions. | | - -##### Conditions - -- **Ready.** True when the Source is provisioned and ready to emit events. -- **Provisioned.** True when the Source has been provisioned by a controller. - -#### Events - -- Provisioned - describes each resource that is provisioned. - -### Life Cycle - -| Action | Reactions | Limitations | -| ------ | --------------------------------------------------------------------------------------------------------- | ----------- | -| Create | Provisioner controller watches for Sources and creates the backing resources depending on implementation. | | -| Update | Provisioner controller synchronizes backing implementation on changes. | | -| Delete | Provisioner controller will deprovision backing resources depending on implementation. | | - ---- - ## kind: Channel ### group: eventing.knative.dev/v1alpha1 @@ -75,11 +25,10 @@ Subscription's call parameter._ #### Spec -| Field | Type | Description | Limitations | -| ------------- | ---------------------------------- | -------------------------------------------------------------------------- | ------------------------------------ | -| provisioner\* | ProvisionerReference | The name of the provisioner to create the resources that back the Channel. | Immutable. | -| arguments | runtime.RawExtension (JSON object) | Arguments to be passed to the provisioner. | | -| channelable | Channelable | Holds a list of downstream subscribers for the channel. | | +| Field | Type | Description | Limitations | +| ------------- | ---------------------------------- | -------------------------------------------------------------------------- | ----------- | +| provisioner\* | ProvisionerReference | The name of the provisioner to create the resources that back the Channel. | Immutable. | +| arguments | runtime.RawExtension (JSON object) | Arguments to be passed to the provisioner. | | \*: Required @@ -87,16 +36,14 @@ Subscription's call parameter._ ##### Owner References -- If the Source controller created this Channel: Owned by the originating - Source. - Owned (non-controlling) by the Provisioner used to provision the Channel. #### Status -| Field | Type | Description | Limitations | -| ------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------- | ----------- | -| sinkable | Sinkable | Address to the endpoint as top-level domain that will distribute traffic over the provided targets from inside the cluster. | | -| conditions | Conditions | Standard Subscriptions | | +| Field | Type | Description | Limitations | +| ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | ----------- | +| sinkable | Sinkable | Address to the endpoint as top-level domain that will distribute traffic over the provided targets from inside the cluster. | | +| conditions | Conditions | Standard Subscriptions | | ##### Conditions @@ -178,18 +125,18 @@ or a Channel system that receives and delivers events._ #### Spec -| Field | Type | Description | Limitations | -| ---------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------- | -| type\* | [GroupKind](https://godoc.org/k8s.io/apimachinery/pkg/runtime/schema#GroupKind) | The type of the resource to be provisioned. | Must be Source or Channel. | -| parameters | runtime.RawExtension (JSON object) | Description of the arguments able to be passed by the provisioned resource. | JSON Schema | +| Field | Type | Description | Limitations | +| ---------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------- | +| type\* | [GroupKind](https://godoc.org/k8s.io/apimachinery/pkg/runtime/schema#GroupKind) | The type of the resource to be provisioned. | Must be Channel. | +| parameters | runtime.RawExtension (JSON object) | Description of the arguments able to be passed by the provisioned resource. | JSON Schema | \*: Required #### Status -| Field | Type | Description | Limitations | -| ----------- | ------------------------- | ---------------------- | ----------- | -| conditions | Conditions | Provisioner conditions | | +| Field | Type | Description | Limitations | +| ---------- | ---------- | ---------------------- | ----------- | +| conditions | Conditions | Provisioner conditions | | ##### Conditions @@ -197,8 +144,8 @@ or a Channel system that receives and delivers events._ #### Events -- Source created -- Source deleted +- Resource Created. +- Resource Removed. --- @@ -232,7 +179,7 @@ or a Channel system that receives and delivers events._ \*: Required -### Channelable +### Subscribable | Field | Type | Description | Limitations | | ----------- | ----------------------- | --------------------------------------------------------------------- | -------------------------------------- | From 27fb0aaf2189d3a06c128bec97ff262c55ecc015 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Thu, 18 Oct 2018 13:13:13 -0700 Subject: [PATCH 37/60] Formatting. --- docs/spec/interfaces.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index ea8c057d79c..9c7c6383c53 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -19,7 +19,7 @@ as _call_ and _result_) in the _Subscription_ to network addresses. ### Data Plane -**Channelable** resources will attempt delivery to each of the _subscribers_ +**Subscribable** resources will attempt delivery to each of the _subscribers_ at least once, and retry if the subscriber returns errors. --- @@ -39,8 +39,8 @@ _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 +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. From d1f392fa79f93be16225deb58a93b6f9b8b0167d Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Thu, 18 Oct 2018 13:20:38 -0700 Subject: [PATCH 38/60] updated the images. --- docs/spec/images/interface-contracts-overview.svg | 2 +- docs/spec/images/resource-types-overview.svg | 2 +- docs/spec/images/resource-types-provisioner.svg | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/spec/images/interface-contracts-overview.svg b/docs/spec/images/interface-contracts-overview.svg index 0e81d6dc1f2..5a013704dc0 100644 --- a/docs/spec/images/interface-contracts-overview.svg +++ b/docs/spec/images/interface-contracts-overview.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/docs/spec/images/resource-types-overview.svg b/docs/spec/images/resource-types-overview.svg index 58ef46e472e..6e6117aac70 100644 --- a/docs/spec/images/resource-types-overview.svg +++ b/docs/spec/images/resource-types-overview.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/docs/spec/images/resource-types-provisioner.svg b/docs/spec/images/resource-types-provisioner.svg index 54ca5293ae5..9626a211c04 100644 --- a/docs/spec/images/resource-types-provisioner.svg +++ b/docs/spec/images/resource-types-provisioner.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file From f82eb476d4c838f5f60df65b2984dd05b8d94bee Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Thu, 18 Oct 2018 13:31:24 -0700 Subject: [PATCH 39/60] Provisioner -> ClusterProvisioner. --- docs/spec/README.md | 10 ---------- docs/spec/interfaces.md | 6 ++++-- docs/spec/overview.md | 27 +++++++++++++++------------ docs/spec/spec.md | 23 ++++++++++++----------- 4 files changed, 31 insertions(+), 35 deletions(-) diff --git a/docs/spec/README.md b/docs/spec/README.md index 81b85c46486..06ebb54343c 100644 --- a/docs/spec/README.md +++ b/docs/spec/README.md @@ -18,16 +18,6 @@ Docs in this directory: - - See the [Knative Eventing Docs Architecture](https://github.com/knative/docs/blob/master/eventing/README.md#architecture) for more high level details. diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index 9c7c6383c53..bc4b764fd4a 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -9,7 +9,8 @@ ## Subscribable A **Subscribable** resource contains a list of subscribers and is responsible -for delivering events to each of them. +for delivering events to each of them. One example of a Subscribable is a +_Channel_ as the target of a _Subscription_'s _from_ field. ### Control Plane @@ -54,7 +55,8 @@ if it previously indicated success. 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_. +response. One example of a _Sinkable_ is a _Channel_ as the target of a +_Subscription_'s _result_ field. ### Control Plane diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 8c10564583a..6e6256400af 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -16,13 +16,13 @@ Kubernetes Ingress resource). ![Resource Types Overview](images/resource-types-overview.svg) -- **Provisioners** implement strategies for realizing backing resources for - different implementations of _Channels_ currently active in the eventing +- **ClusterProvisioners** implement strategies for realizing backing resources + for different implementations of _Channels_ currently active in the eventing system. -![Resource Types Provisioners](images/resource-types-provisioner.svg) +![Resource Types ClusterProvisioners](images/resource-types-provisioner.svg) With extendibility and compostability as a goal of Knative Eventing, the eventing API defines several resources that can be reduced down to a well @@ -36,7 +36,7 @@ objects. The interfaces are ([Sinkable](interfaces.md#sinkable), ## Subscription **Subscriptions** describe a flow of events from one _Channel_) to the next -Channel* through transformations (such as a Knative Service which processes +Channel\* through transformations (such as a Knative Service which processes 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 @@ -57,23 +57,26 @@ 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 -_Provisioner_. +_ClusterProvisioner_. Event selection on a _Channel_ is 1:N – a single _Channel_ may fan out to multiple _Subscriptions_. See [Kind: Channel](spec.md#kind-channel). -## Provisioner +## ClusterProvisioner -**Provisioner** catalogs available implementations of _Channels_. -_Provisioners_ hold a JSON Schema that is used to validate the _Channel_ input -arguments. _Provisioners_ make it possible to provide cluster wide defaults for -the _Channels_ they provision. +**ClusterProvisioner** catalogs available implementations of _Channels_. +_ClusterProvisioners_ hold a JSON Schema that is used to validate the _Channel_ +input arguments. _ClusterProvisioners_ make it possible to provide cluster wide +defaults for the _Channels_ they provision. -_Provisioners_ do not directly handle events. They are 1:N with _Channels_. +_ClusterProvisioners_ do not directly handle events. They are 1:N with +_Channels_. + +For more details, see [Kind: +ClusterProvisioner](spec.md#kind-cluster-provisioner). -For more details, see [Kind: Provider](spec.md#kind-provisioner). --- diff --git a/docs/spec/spec.md b/docs/spec/spec.md index cc8c408035a..e437bf47755 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -36,7 +36,8 @@ Subscription's call parameter._ ##### Owner References -- Owned (non-controlling) by the Provisioner used to provision the Channel. +- Owned (non-controlling) by the ClusterProvisioner used to provision the + Channel. #### Status @@ -57,11 +58,11 @@ Subscription's call parameter._ ### Life Cycle -| Action | Reactions | Limitations | -| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | -| Create | The Provisioner referenced will take ownership of the Channel and begin provisioning the backing resources required for the Channel depending on implementation. | Only one Provisioner is allowed to be the Owner for a given Channel. | -| Update | The Provisioner will synchronize the Channel backing resources to reflect the update. | | -| Delete | The Provisioner will deprovision the backing resources if no longer required depending on implementation. | | +| Action | Reactions | Limitations | +| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | +| Create | The ClusterProvisioner referenced will take ownership of the Channel and begin provisioning the backing resources required for the Channel depending on implementation. | Only one ClusterProvisioner is allowed to be the Owner for a given Channel. | +| Update | The ClusterProvisioner will synchronize the Channel backing resources to reflect the update. | | +| Delete | The ClusterProvisioner will deprovision the backing resources if no longer required depending on implementation. | | --- @@ -114,7 +115,7 @@ _Describes a linkage between a Channel and a Targetable and/or Sinkable._ --- -## kind: Provisioner +## kind: ClusterProvisioner ### group: eventing.knative.dev/v1alpha1 @@ -134,9 +135,9 @@ or a Channel system that receives and delivers events._ #### Status -| Field | Type | Description | Limitations | -| ---------- | ---------- | ---------------------- | ----------- | -| conditions | Conditions | Provisioner conditions | | +| Field | Type | Description | Limitations | +| ---------- | ---------- | ----------------------------- | ----------- | +| conditions | Conditions | ClusterProvisioner conditions | | ##### Conditions @@ -174,7 +175,7 @@ or a Channel system that receives and delivers events._ | -------- | ------ | ------------------------------------------------------------ | ----------- | | name\* | String | Name of Object | | | type\* | String | Fully Qualified Object type. | | -| status\* | String | Current relationship between Provisioner and Object. | | +| status\* | String | Current relationship between ClusterProvisioner and Object. | | | reason | String | Detailed description describing current relationship status. | | \*: Required From 300723ad676ff31de6c5269216603c8cc7039dca Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Thu, 18 Oct 2018 13:59:30 -0700 Subject: [PATCH 40/60] Set the width. --- docs/spec/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 6e6256400af..d86eab2fcc2 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -22,7 +22,7 @@ Kubernetes Ingress resource). -![Resource Types ClusterProvisioners](images/resource-types-provisioner.svg) +![Resource Types ClusterProvisioners](images/resource-types-provisioner.svg =350x) With extendibility and compostability as a goal of Knative Eventing, the eventing API defines several resources that can be reduced down to a well From fe158af1a4ff074360b6a3feb74b38a327f4839e Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Thu, 18 Oct 2018 14:01:44 -0700 Subject: [PATCH 41/60] width, try two. --- docs/spec/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/overview.md b/docs/spec/overview.md index d86eab2fcc2..ceae259e928 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -22,7 +22,7 @@ Kubernetes Ingress resource). -![Resource Types ClusterProvisioners](images/resource-types-provisioner.svg =350x) +![Resource Types ClusterProvisioners](images/resource-types-provisioner.svg | width=300) With extendibility and compostability as a goal of Knative Eventing, the eventing API defines several resources that can be reduced down to a well From 7136a18d8f1d72d22061c5257ecb5bc3bcd581fa Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Thu, 18 Oct 2018 14:04:53 -0700 Subject: [PATCH 42/60] width, first try. --- docs/spec/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/overview.md b/docs/spec/overview.md index ceae259e928..3710707eb01 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -22,7 +22,7 @@ Kubernetes Ingress resource). -![Resource Types ClusterProvisioners](images/resource-types-provisioner.svg | width=300) +Resource Types ClusterProvisioners With extendibility and compostability as a goal of Knative Eventing, the eventing API defines several resources that can be reduced down to a well From dcbb8a7df4d1875734a330a892ccb13380ec1e5f Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Thu, 18 Oct 2018 14:05:44 -0700 Subject: [PATCH 43/60] Width was too big at 300 --- docs/spec/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 3710707eb01..3a38576f7ca 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -22,7 +22,7 @@ Kubernetes Ingress resource). -Resource Types ClusterProvisioners +Resource Types ClusterProvisioners With extendibility and compostability as a goal of Knative Eventing, the eventing API defines several resources that can be reduced down to a well From 7c74ca8f53bfc5b0050cff55a35dedaa43e1548c Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Mon, 22 Oct 2018 10:10:12 -0700 Subject: [PATCH 44/60] Update docs/spec/interfaces.md Co-Authored-By: n3wscott --- docs/spec/interfaces.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index bc4b764fd4a..e0a2acc9e58 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -9,7 +9,7 @@ ## Subscribable A **Subscribable** resource contains a list of subscribers and is responsible -for delivering events to each of them. One example of a Subscribable is a +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 From abd44568a5cc2832616c08f48ff67e594c2734e3 Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Mon, 22 Oct 2018 10:11:51 -0700 Subject: [PATCH 45/60] Update docs/spec/interfaces.md Co-Authored-By: n3wscott --- docs/spec/interfaces.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index e0a2acc9e58..f1d47b73302 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -10,7 +10,7 @@ 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. +_Channel_ as the target of a _Subscription_'s `from` field. ### Control Plane From 6b7c28b4ea3083016e98db1ea8d4a11d6d0938dd Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Mon, 22 Oct 2018 10:23:32 -0700 Subject: [PATCH 46/60] Update docs/spec/interfaces.md Co-Authored-By: n3wscott --- docs/spec/interfaces.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index f1d47b73302..3eafcff71f2 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -63,7 +63,7 @@ _Subscription_'s _result_ field. A **Sinkable** resource MUST expose a _status.sinkable.domainInternal_ field. 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_. +_result_ section of a _Subscription_, and also by other custom resources acting as an event Source. ### Data Plane From c1b677a5b37e67a32dde92672a15eb8fea811817 Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Mon, 22 Oct 2018 10:23:48 -0700 Subject: [PATCH 47/60] Update docs/spec/interfaces.md Co-Authored-By: n3wscott --- docs/spec/interfaces.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index 3eafcff71f2..d2b48a8e9ca 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -68,7 +68,7 @@ _result_ section of a _Subscription_, and also by other custom resources acting ### Data Plane A **Sinkable** resource will only respond to requests with success of failure. -Events returned to the caller will be reported or ignored. +Any payload (including a valid CloudEvent) returned to the sender will be ignored. --- From cba6a6799e7d17c9354fb5d6c6599bffcbd0c9ca Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Mon, 22 Oct 2018 10:57:48 -0700 Subject: [PATCH 48/60] Update docs/spec/spec.md Co-Authored-By: n3wscott --- docs/spec/spec.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/spec/spec.md b/docs/spec/spec.md index e437bf47755..097cab3ce73 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -97,7 +97,6 @@ _Describes a linkage between a Channel and a Targetable and/or Sinkable._ - **Ready.** - **FromReady.** -- **CallActive.** True if the call is sinking events without error. - **Resolved.** #### Events From ce3fceb7912875e7ff04b99efd431e83bdbc9708 Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Mon, 22 Oct 2018 10:58:18 -0700 Subject: [PATCH 49/60] Update docs/spec/spec.md Co-Authored-By: n3wscott --- docs/spec/spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 097cab3ce73..955eab47ec1 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -97,7 +97,7 @@ _Describes a linkage between a Channel and a Targetable and/or Sinkable._ - **Ready.** - **FromReady.** -- **Resolved.** +- **Resolved.** True if `from`, `call`, and `result` all resolve into valid object references which implement the appropriate spec. #### Events From 63c5ff5e7762aeeea7a421f6e04b3081f67630ac Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Mon, 22 Oct 2018 11:03:28 -0700 Subject: [PATCH 50/60] Update docs/spec/spec.md Co-Authored-By: n3wscott --- docs/spec/spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 955eab47ec1..2bbf83b6688 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -128,7 +128,7 @@ or a Channel system that receives and delivers events._ | Field | Type | Description | Limitations | | ---------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------- | | type\* | [GroupKind](https://godoc.org/k8s.io/apimachinery/pkg/runtime/schema#GroupKind) | The type of the resource to be provisioned. | Must be Channel. | -| parameters | runtime.RawExtension (JSON object) | Description of the arguments able to be passed by the provisioned resource. | JSON Schema | +| parameters | runtime.RawExtension (JSON object) | Description of the arguments able to be passed by the provisioned resource (not enforced in 0.1). | JSON Schema | \*: Required From 07e654b70505cb9cbb551a8867254db30d5adf68 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 22 Oct 2018 10:10:31 -0700 Subject: [PATCH 51/60] applying sugestions --- .../images/interface-contracts-overview.svg | 1 - docs/spec/images/resource-types-overview.svg | 2 +- .../images/resource-types-provisioner.svg | 2 +- docs/spec/interfaces.md | 6 ---- docs/spec/overview.md | 20 +++++------ docs/spec/spec.md | 34 +++++++++---------- 6 files changed, 29 insertions(+), 36 deletions(-) delete mode 100644 docs/spec/images/interface-contracts-overview.svg diff --git a/docs/spec/images/interface-contracts-overview.svg b/docs/spec/images/interface-contracts-overview.svg deleted file mode 100644 index 5a013704dc0..00000000000 --- a/docs/spec/images/interface-contracts-overview.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/spec/images/resource-types-overview.svg b/docs/spec/images/resource-types-overview.svg index 6e6117aac70..943ac7d96f0 100644 --- a/docs/spec/images/resource-types-overview.svg +++ b/docs/spec/images/resource-types-overview.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/docs/spec/images/resource-types-provisioner.svg b/docs/spec/images/resource-types-provisioner.svg index 9626a211c04..53426f57f04 100644 --- a/docs/spec/images/resource-types-provisioner.svg +++ b/docs/spec/images/resource-types-provisioner.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index d2b48a8e9ca..40aa44395ef 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -1,11 +1,5 @@ # Interface Contracts - - -![Interface Contracts Overview](images/interface-contracts-overview.svg) - ---- - ## Subscribable A **Subscribable** resource contains a list of subscribers and is responsible diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 3a38576f7ca..95bc5406979 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -16,13 +16,13 @@ Kubernetes Ingress resource). ![Resource Types Overview](images/resource-types-overview.svg) -- **ClusterProvisioners** implement strategies for realizing backing resources +- **ClusterChannelProvisioners** implement strategies for realizing backing resources for different implementations of _Channels_ currently active in the eventing system. -Resource Types ClusterProvisioners +Resource Types ClusterChannelProvisioners With extendibility and compostability as a goal of Knative Eventing, the eventing API defines several resources that can be reduced down to a well @@ -57,25 +57,25 @@ 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 -_ClusterProvisioner_. +_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). -## ClusterProvisioner +## ClusterChannelProvisioner -**ClusterProvisioner** catalogs available implementations of _Channels_. -_ClusterProvisioners_ hold a JSON Schema that is used to validate the _Channel_ -input arguments. _ClusterProvisioners_ make it possible to provide cluster wide -defaults for the _Channels_ they provision. +**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. -_ClusterProvisioners_ do not directly handle events. They are 1:N with +_ClusterChannelProvisioners_ do not directly handle events. They are 1:N with _Channels_. For more details, see [Kind: -ClusterProvisioner](spec.md#kind-cluster-provisioner). +ClusterChannelProvisioner](spec.md#kind-cluster-channel-provisioner). --- diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 2bbf83b6688..388db0dfc95 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -36,8 +36,8 @@ Subscription's call parameter._ ##### Owner References -- Owned (non-controlling) by the ClusterProvisioner used to provision the - Channel. +- Owned (non-controlling) by the ClusterChannelProvisioner used to provision + the Channel. #### Status @@ -58,11 +58,11 @@ Subscription's call parameter._ ### Life Cycle -| Action | Reactions | Limitations | -| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| Create | The ClusterProvisioner referenced will take ownership of the Channel and begin provisioning the backing resources required for the Channel depending on implementation. | Only one ClusterProvisioner is allowed to be the Owner for a given Channel. | -| Update | The ClusterProvisioner will synchronize the Channel backing resources to reflect the update. | | -| Delete | The ClusterProvisioner will deprovision the backing resources if no longer required depending on implementation. | | +| Action | Reactions | Limitations | +| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | +| Create | The ClusterChannelProvisioner referenced will take ownership of the Channel and begin provisioning the backing resources required for the Channel depending on implementation. | Only one ClusterChannelProvisioner is allowed to be the Owner for a given Channel. | +| Update | The ClusterChannelProvisioner will synchronize the Channel backing resources to reflect the update. | | +| Delete | The ClusterChannelProvisioner will deprovision the backing resources if no longer required depending on implementation. | | --- @@ -114,7 +114,7 @@ _Describes a linkage between a Channel and a Targetable and/or Sinkable._ --- -## kind: ClusterProvisioner +## kind: ClusterChannelProvisioner ### group: eventing.knative.dev/v1alpha1 @@ -134,9 +134,9 @@ or a Channel system that receives and delivers events._ #### Status -| Field | Type | Description | Limitations | -| ---------- | ---------- | ----------------------------- | ----------- | -| conditions | Conditions | ClusterProvisioner conditions | | +| Field | Type | Description | Limitations | +| ---------- | ---------- | ------------------------------------ | ----------- | +| conditions | Conditions | ClusterChannelProvisioner conditions | | ##### Conditions @@ -170,12 +170,12 @@ or a Channel system that receives and delivers events._ ### ProvisionedObjectStatus -| Field | Type | Description | Limitations | -| -------- | ------ | ------------------------------------------------------------ | ----------- | -| name\* | String | Name of Object | | -| type\* | String | Fully Qualified Object type. | | -| status\* | String | Current relationship between ClusterProvisioner and Object. | | -| reason | String | Detailed description describing current relationship status. | | +| Field | Type | Description | Limitations | +| -------- | ------ | ------------------------------------------------------------------ | ----------- | +| name\* | String | Name of Object | | +| type\* | String | Fully Qualified Object type. | | +| status\* | String | Current relationship between ClusterChannelProvisioner and Object. | | +| reason | String | Detailed description describing current relationship status. | | \*: Required From 5b73ffca93ed860556e930de45660187305296ed Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 22 Oct 2018 10:15:11 -0700 Subject: [PATCH 52/60] syncing remote. --- docs/spec/spec.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 388db0dfc95..13042c6e874 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -25,10 +25,11 @@ Subscription's call parameter._ #### Spec -| Field | Type | Description | Limitations | -| ------------- | ---------------------------------- | -------------------------------------------------------------------------- | ----------- | -| provisioner\* | ProvisionerReference | The name of the provisioner to create the resources that back the Channel. | Immutable. | -| arguments | runtime.RawExtension (JSON object) | Arguments to be passed to the provisioner. | | +| Field | Type | Description | Limitations | +| ------------- | ---------------------------------- | -------------------------------------------------------------------------- | -------------------------------------- | +| provisioner\* | ProvisionerReference | The name of the provisioner to create the resources that back the Channel. | Immutable. | +| arguments | runtime.RawExtension (JSON object) | Arguments to be passed to the provisioner. | | +| subscribers | ChannelSubscriberSpec[] | Information about subscriptions used to implement message forwarding. | Filled out by Subscription Controller. | \*: Required From fbb8b6fe213ec423ebc4453844f0de4f702780a3 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 22 Oct 2018 10:18:33 -0700 Subject: [PATCH 53/60] add a todo. --- docs/spec/interfaces.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index 40aa44395ef..e1f9092f86a 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -3,20 +3,26 @@ ## Subscribable 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. +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_. The -Subscription Controller is responsible for resolving any ObjectReferences (such -as _call_ and _result_) in the _Subscription_ to network addresses. +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. + + --- ## Targetable From ae76ce058db8371f0d5896787d066016e54aa697 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 22 Oct 2018 10:43:05 -0700 Subject: [PATCH 54/60] sync. --- docs/spec/interfaces.md | 13 ++++++++++++- docs/spec/overview.md | 27 ++++++++++++++++----------- docs/spec/spec.md | 7 +++---- 3 files changed, 31 insertions(+), 16 deletions(-) diff --git a/docs/spec/interfaces.md b/docs/spec/interfaces.md index e1f9092f86a..3142554fb24 100644 --- a/docs/spec/interfaces.md +++ b/docs/spec/interfaces.md @@ -58,6 +58,15 @@ delivery. Unlike _Targetable_, a _Sinkable_ cannot return events in its response. One example of a _Sinkable_ is a _Channel_ as the target of a _Subscription_'s _result_ field. + + ### Control Plane A **Sinkable** resource MUST expose a _status.sinkable.domainInternal_ field. @@ -68,7 +77,9 @@ _result_ section of a _Subscription_, and also by other custom resources acting ### 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. +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. --- diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 95bc5406979..9224bf098a5 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -2,9 +2,19 @@ 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 [Providers](spec.md#kind-provisioner) -which may be fulfilled by multiple backing implementations (much like the -Kubernetes Ingress resource). +for [Channels](spec.md#kind-channel) and +[ClusterChannelProvisioners](spec.md#kind-cluster-channe-provisioner) 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. @@ -24,14 +34,9 @@ Kubernetes Ingress resource). Resource Types ClusterChannelProvisioners -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). +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 diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 13042c6e874..c42e8cc93cd 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -2,8 +2,8 @@ Knative ships with several objects which implement useful sets of [interfaces](interfaces.md). It is expected that additional objects which -implement other sets of interfaces will be added over time. For context, see -the [overview](overview.md) and [motivations](motivation.md) sections. +implement these interfaces will be added over time. For context, see the +[overview](overview.md) and [motivations](motivation.md) sections. These are Kubernetes resources that been introduced using Custom Resource Definitions. They will have the expected _ObjectMeta_, _Spec_, _Status_ fields. @@ -18,8 +18,7 @@ This document details our _Spec_ and _Status_ customizations. ### group: eventing.knative.dev/v1alpha1 _A Channel logically receives events on its input domain and forwards them to -its subscribers. Additional behavior may be introduced by using the -Subscription's call parameter._ +its subscribers._ ### Object Schema From a849d5093d15f8e4388f9ad0fffb100182d21f07 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 22 Oct 2018 11:02:26 -0700 Subject: [PATCH 55/60] updates. --- docs/spec/spec.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/spec/spec.md b/docs/spec/spec.md index c42e8cc93cd..a5bf84b3d11 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -44,7 +44,7 @@ its subscribers._ | Field | Type | Description | Limitations | | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | ----------- | | sinkable | Sinkable | Address to the endpoint as top-level domain that will distribute traffic over the provided targets from inside the cluster. | | -| conditions | Conditions | Standard Subscriptions | | +| conditions | Conditions | Channel conditions. | | ##### Conditions @@ -78,7 +78,7 @@ _Describes a linkage between a Channel and a Targetable and/or Sinkable._ | Field | Type | Description | Limitations | | ------------------ | -------------- | ---------------------------------------------------------------------------- | ------------------ | -| from\* | ObjectRef | The originating Channel for the link. | Must be a Channel. | +| from\* | ObjectRef | The originating _Subscribable_ for the link. | Must be a Channel. | | call1 | EndpointSpec | Optional processing on the event. The result of call will be sent to result. | | | result1 | ResultStrategy | The continuation for the link. | | @@ -106,11 +106,11 @@ _Describes a linkage between a Channel and a Targetable and/or Sinkable._ ### Life Cycle -| Action | Reactions | Limitations | -| ------ | ---------------------------------------------------------------- | ----------- | -| Create | The publisher referenced needs to be watching for Subscriptions. | | -| Update | | | -| Delete | | | +| Action | Reactions | Limitations | +| ------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | +| Create | The subscription controller adds the resolved URIs of `call` and `result` to the `subscribers` field in the `from` _Subscribable_ resource. | | +| Update | | | +| Delete | | | --- From 60e5cfc3e5351ce768ba02113e2bf7d975464e0c Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 22 Oct 2018 11:04:17 -0700 Subject: [PATCH 56/60] remove type from new bus. --- docs/spec/spec.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/spec/spec.md b/docs/spec/spec.md index a5bf84b3d11..94877bf815b 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -125,10 +125,9 @@ or a Channel system that receives and delivers events._ #### Spec -| Field | Type | Description | Limitations | -| ---------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------- | -| type\* | [GroupKind](https://godoc.org/k8s.io/apimachinery/pkg/runtime/schema#GroupKind) | The type of the resource to be provisioned. | Must be Channel. | -| parameters | runtime.RawExtension (JSON object) | Description of the arguments able to be passed by the provisioned resource (not enforced in 0.1). | JSON Schema | +| Field | Type | Description | Limitations | +| ---------- | ---------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------- | +| parameters | runtime.RawExtension (JSON object) | Description of the arguments able to be passed by the provisioned resource (not enforced in 0.1). | JSON Schema | \*: Required From 6f27fc0f995f69a7341449b0c2334e62ff2453d4 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 22 Oct 2018 11:15:18 -0700 Subject: [PATCH 57/60] domain to uri. --- docs/spec/spec.md | 25 ++++--------------------- 1 file changed, 4 insertions(+), 21 deletions(-) diff --git a/docs/spec/spec.md b/docs/spec/spec.md index 94877bf815b..e1b9a5d921f 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -167,29 +167,12 @@ or a Channel system that receives and delivers events._ 1: One of (targetRef, dnsName), Required. -### ProvisionedObjectStatus - -| Field | Type | Description | Limitations | -| -------- | ------ | ------------------------------------------------------------------ | ----------- | -| name\* | String | Name of Object | | -| type\* | String | Fully Qualified Object type. | | -| status\* | String | Current relationship between ClusterChannelProvisioner and Object. | | -| reason | String | Detailed description describing current relationship status. | | - -\*: Required - -### Subscribable - -| Field | Type | Description | Limitations | -| ----------- | ----------------------- | --------------------------------------------------------------------- | -------------------------------------- | -| subscribers | ChannelSubscriberSpec[] | Information about subscriptions used to implement message forwarding. | Filled out by Subscription Controller. | - ### ChannelSubscriberSpec -| Field | Type | Description | Limitations | -| -------------- | ------ | ----------------------------------------------- | ----------- | -| callableDomain | String | The domain name of the endpoint for the call. | | -| sinkableDomain | String | The domain name of the endpoint for the result. | | +| Field | Type | Description | Limitations | +| ----------- | ------ | -------------------------------------------- | -------------- | +| callableURI | String | The URI name of the endpoint for the call. | Must be a URL. | +| sinkableURI | String | The URI name of the endpoint for the result. | Must be a URL. | ### ResultStrategy From b08b089657efe76b16c463e50a75bfa0bf01162e Mon Sep 17 00:00:00 2001 From: Scott Andrews Date: Mon, 22 Oct 2018 11:53:20 -0700 Subject: [PATCH 58/60] Update docs/spec/spec.md Co-Authored-By: n3wscott --- docs/spec/spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/spec.md b/docs/spec/spec.md index e1b9a5d921f..2450d41cf5a 100644 --- a/docs/spec/spec.md +++ b/docs/spec/spec.md @@ -11,7 +11,7 @@ This document details our _Spec_ and _Status_ customizations. - [Channel](#kind-channel) - [Subscription](#kind-subscription) -- [Provider](#kind-provisioner) +- [ClusterChannelProvisioner](#kind-clusterchannelprovisioner) ## kind: Channel From 79536d708043b6430fea065900160c6ead88e1da Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 22 Oct 2018 11:55:58 -0700 Subject: [PATCH 59/60] typos. --- docs/spec/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 9224bf098a5..5acd1d1d83f 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -3,7 +3,7 @@ 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-cluster-channe-provisioner) which may +[ClusterChannelProvisioners](spec.md#kind-cluster-channel-provisioner) which may be fulfilled by multiple backing implementations (much like the Kubernetes Ingress resource). From 08913104bfc487d3e8037a06ee4e1cf68a0d2448 Mon Sep 17 00:00:00 2001 From: Scott Nichols Date: Mon, 22 Oct 2018 11:56:47 -0700 Subject: [PATCH 60/60] typos. --- docs/spec/overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 5acd1d1d83f..f111164d321 100644 --- a/docs/spec/overview.md +++ b/docs/spec/overview.md @@ -3,7 +3,7 @@ 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-cluster-channel-provisioner) which may +[ClusterChannelProvisioners](spec.md#kind-clusterchannelprovisioner) which may be fulfilled by multiple backing implementations (much like the Kubernetes Ingress resource). @@ -80,7 +80,7 @@ _ClusterChannelProvisioners_ do not directly handle events. They are 1:N with _Channels_. For more details, see [Kind: -ClusterChannelProvisioner](spec.md#kind-cluster-channel-provisioner). +ClusterChannelProvisioner](spec.md#kind-clusterchannelprovisioner). ---