From 445e1724bb004cd6144809ba832b36156521ff4c Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Wed, 6 Mar 2019 17:03:07 -0800 Subject: [PATCH 1/4] Initial definitions of Broker and Trigger based on decision docs Signed-off-by: Evan Anderson --- docs/decisions/broker-trigger.md | 137 +++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 docs/decisions/broker-trigger.md diff --git a/docs/decisions/broker-trigger.md b/docs/decisions/broker-trigger.md new file mode 100644 index 00000000000..90b78d294ed --- /dev/null +++ b/docs/decisions/broker-trigger.md @@ -0,0 +1,137 @@ +# Broker and Trigger model (for 0.5.0) + +Decision date: 6 March 2019 + +## Define High-Level Objects Related to Eventing + +The goal of eventing is to provide an abstract "bucket of events" which event +consumers can sample from using filters on CloudEvent +[context attributes](https://github.com/cloudevents/spec/blob/master/spec.md#context-attributes). +Event producers can deliver events into the bucket without needing to understand +the exact mechanics of routing to specific consumers. Event producers and +consumers are decoupled temporally but also through a deliberately black-box +abstraction which can optimize the underlying routing layer dynamically. + +## Objects + +The following objects are the minimum set needed to experiment and collect +customer feedback on the Eventing object model, aka an MVP (including rough YAML +definitions; final naming and field definitions subject to change based on +implementation experience). + +### Broker + +A Broker represents a "bucket of events". It is a namespaced object, with +automation provided to provision a Broker named `default` in +appropriately-labelled namespaces. It is expected that most users will not need +to explicitly create a Broker and simply enabling eventing in the namespace to +create the `default` Broker will be sufficient. Assuming that the Broker model +is successful, future recommendations for Source CRD authors would be to default +the Source's `spec.sink` attribute to point to the `default` Broker in the +namespace. + +Historical storage and replay of events is not part of the Broker design or MVP. + +Broker implements the "Addressable" duck type to allow Source custom resources +to target the Broker. Broker DNS names should also be predictable (e.g. +`default-broker` for the `default` Broker), to enable whitebox event producers +to target the Broker without needing to reconcile against the "Addressable" duck +type. + +#### Broker Object definition + +```golang +type Broker struct { + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + Spec BrokerSpec `json:"spec,omitempty"` + Status BrokerStatus `json:"status,omitempty"` +} + +type BrokerSpec struct { + // Empty for now +} + +type BrokerStatus struct { + Conditions duckv1alpha1.Conditions `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type"` + + Address duckv1alpha1.Addressable `json:"address,omitempty"` +} +``` + +### Trigger + +A Trigger represents a registration of interest (request for delivery to an +Addressable object or URL) in a filtered selection of events delivered to a +Broker. For the MVP, Triggers may only target Addressable objects in the same +namespace. + +#### Buffering + +Triggers are assumed to buffer (durably queue) filtered events from the Broker +from the time they are created, and to deliver the buffered events to the target +Addressable as it is able to receive them. + +#### Filtering + +An event consumer which is interested in several sets of events may need to +create multiple Triggers, each with an ANDed set of filter conditions which +select the events. In the case of multiple Triggers with the same target whose +filter conditions select an overlapping set of events, events will be delivered +once for each Trigger which selects the event (i.e. Trigger selection criteria +are independent, not aggregated in the Broker). + +At some later point, we expect that a more complex set of filtering expressions +will be supported. For the initial MVP, exact match on the CloudEvents +[`type`](https://github.com/cloudevents/spec/blob/master/spec.md#type) and +[`source`](https://github.com/cloudevents/spec/blob/master/spec.md#source) +attributes will be supported. + +#### Trigger Object Definition + +```golang +type Trigger struct { + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + Spec TriggerSpec `json:"spec,omitempty"` + Status TriggerStatus `json:"status,omitempty"` +} + +type TriggerSpec struct { + // Defaults to 'default'. + Broker string `json:"broker,omitempty"` + Filter *TriggerFilter `json:"filter,omitempty"` + // As from Subscription's `spec.subscriber` + Target *SubscriberSpec `json:"target,omitempty"` +} + +type TriggerFilter struct { + // Exact match expressions; if empty, all values are matched. + Type string `json:"type,omitempty"` + Source string `json:"source,omitempty"` +} + +type TriggerStatus struct { + Conditions duckv1alpha1.Conditions `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type"` + SubscriberURI string `json:"subscriberURI,omitempty"` +} +``` + +## Backing documents + +[2019-02-22 Decision Making -- UX targets](https://docs.google.com/spreadsheets/d/16aOhfRnkaGcQIOR5kiumld-GmrgGBIm9fppvAXx3mgc/edit) + +Accepted decisions (2+ votes) + +- Have a "Broker" object + - Default sink on sources + - Enable with namespace/default Broker +- Have a "Trigger" object + - "filter" subfield (not top-level filters) + - "filter" has exact type match + - "filter" has exact source match + - target is same-namespace +- Registry requirements are not clear enough to include in MVP + +[UX Proposals Comparision](https://docs.google.com/document/d/1fRpM4u4mP2fGUBmScKQ9_e77rKz_7xh_Thwxp8QXhUA/edit#) +(includes background and discussion) From 82d807b03b10c07ca66aa8b91b834b3aff9148d9 Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Wed, 6 Mar 2019 17:03:07 -0800 Subject: [PATCH 2/4] Interim commit to proxy content home. --- docs/decisions/broker-trigger.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 docs/decisions/broker-trigger.md diff --git a/docs/decisions/broker-trigger.md b/docs/decisions/broker-trigger.md new file mode 100644 index 00000000000..fb29cf1e020 --- /dev/null +++ b/docs/decisions/broker-trigger.md @@ -0,0 +1,23 @@ +# Broker and Trigger model (for 0.5.0) + +Decision date: 6 March 2019 + +## + +## Backing documents: + +[2019-02-22 Decision Making -- UX targets](https://docs.google.com/spreadsheets/d/16aOhfRnkaGcQIOR5kiumld-GmrgGBIm9fppvAXx3mgc/edit) + +Accepted decisions (2+ votes) + +- Have a "Broker" object + - Default sink on sources + - Enable with namespace/default Broker +- Have a "Trigger" object + - "filter" subfield (not top-level filters) + - "filter" has exact type match + - "filter" has exact source match + - target is same-namespace + +[UX Proposals Comparision](https://docs.google.com/document/d/1fRpM4u4mP2fGUBmScKQ9_e77rKz_7xh_Thwxp8QXhUA/edit#) +(includes background and discussion) From 2a581735b6de208653fd72fb4c0023cfe507d47e Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Tue, 12 Mar 2019 14:06:28 -0700 Subject: [PATCH 3/4] Address @vaikas-google comments. --- docs/decisions/broker-trigger.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/decisions/broker-trigger.md b/docs/decisions/broker-trigger.md index 56abf97329e..2aae29ab803 100644 --- a/docs/decisions/broker-trigger.md +++ b/docs/decisions/broker-trigger.md @@ -17,15 +17,15 @@ abstraction which can optimize the underlying routing layer dynamically. - **Event Producer**: a system which creates events based on occurrences. E.g. GitHub (the hosted service). - **Event Consumer**: a destination which receives events. E.g. the application - processing an event. Typically, this is the final "sink" in the processing - flow of an Event, but could be a data processing system like Spark. + processing an event. Typically, this is the "sink" in the processing flow of + an Event, but could be a data processing system like Spark. - **Sink**: a generic term to mean the destination for an event being sent from a component. Synonym for Event Consumer. - **Event Source**: a helper object that can be used to connect an Event Producer to the Knative eventing system by routing events to an Event Consumer. E.g. the [GitHub Knative Source](https://github.com/knative/eventing-sources/tree/master/pkg/reconciler/githubsource) -- **Receieve Adapter**: a data plane entity (Knative Service, Deployment, etc) +- **Receive Adapter**: a data plane entity (Knative Service, Deployment, etc) which performs the event routing from outside the Knative cluster to the Knative eventing system. Receive Adapters are created by Event Sources to perform the actual event routing. @@ -158,7 +158,7 @@ Accepted decisions (2+ votes) - "filter" has exact type match - "filter" has exact source match - target is same-namespace -- Registry requirements are not clear enough to include in MVP +- Registry requirements are not clear enough to include in this decision. - Future user stories could change this and motivate a particular implementation. From 85bf85fda9e16d641a8c47d20bcaaa7d293e3d64 Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Thu, 14 Mar 2019 11:10:41 -0700 Subject: [PATCH 4/4] Update with @katfang wording --- docs/decisions/broker-trigger.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/decisions/broker-trigger.md b/docs/decisions/broker-trigger.md index 2aae29ab803..069925f4ff8 100644 --- a/docs/decisions/broker-trigger.md +++ b/docs/decisions/broker-trigger.md @@ -83,9 +83,9 @@ type BrokerStatus struct { ### Trigger -A Trigger represents a registration of interest (request for delivery to an -Addressable object or URL) in a filtered selection of events delivered to a -Broker. For the MVP, Triggers may only target Addressable objects in the same +A Trigger represents a registration of interest in a filtered selection of +events delivered to a Broker which should be forwarded to an Addressable Object +or a URL. For the MVP, Triggers may only target Addressable objects in the same namespace. #### Buffering