From d380cd4d270aa4259d738e7fa81121d215dddfac Mon Sep 17 00:00:00 2001 From: Grant Rodgers Date: Mon, 6 May 2019 15:27:21 -0700 Subject: [PATCH 1/4] Add Broker/Trigger to the list of delivery modes Most of this document is woefully out of date, but this part not mentioning Broker/Trigger seemed particularly egregious. --- docs/eventing/README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/eventing/README.md b/docs/eventing/README.md index c26eafd2b14..dc4a6b1a10f 100644 --- a/docs/eventing/README.md +++ b/docs/eventing/README.md @@ -89,7 +89,7 @@ cluster) services, you must enable it also for them to work. ## Architecture -The eventing infrastructure supports two forms of event delivery at the moment: +The eventing infrastructure supports three forms of event delivery at the moment: 1. Direct delivery from a source to a single Service (an Addressable endpoint, including a Knative Service or a core Kubernetes Service). In this case, the @@ -103,6 +103,9 @@ The eventing infrastructure supports two forms of event delivery at the moment: In this case, the Channel implementation ensures that messages are delivered to the requested destinations and should buffer the events if the destination Service is unavailable. +1. Selective delivery of events sent to a Broker via a Trigger specification + consisting of a filter and destination. This method provides the same + guarantees as the Channel and Subscription model. ![Control plane object model](./images/control-plane.png) From 29617b1465b43f55145e96a61df5bd541e8e3207 Mon Sep 17 00:00:00 2001 From: Grant Rodgers Date: Mon, 6 May 2019 15:28:18 -0700 Subject: [PATCH 2/4] Link to further filtering docs --- docs/eventing/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/eventing/README.md b/docs/eventing/README.md index dc4a6b1a10f..f018dc5616c 100644 --- a/docs/eventing/README.md +++ b/docs/eventing/README.md @@ -46,10 +46,12 @@ easier to filter events. A Broker provides a bucket of events which can be selected by attribute. It receives events and forwards them to subscribers defined by one or more matching -Triggers. +Triggers. Each Trigger operates in the context of a single Broker. You can +create as many Triggers as necessary. A Trigger describes a filter on event attributes which should be delivered to an -Addressable. You can create as many Triggers as necessary. +Addressable. See [Filtering][./filtering.md] for more information on specifying +filters. ![Broker Trigger Diagram](./images/broker-trigger-overview.svg) From 25be95a3db8170d1792823d2bbcc565a5ac62de4 Mon Sep 17 00:00:00 2001 From: Grant Rodgers Date: Tue, 7 May 2019 11:11:19 -0700 Subject: [PATCH 3/4] WIP on filtering docs Intro and prereqs sections. Other sections still TODO. --- docs/eventing/filtering.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 docs/eventing/filtering.md diff --git a/docs/eventing/filtering.md b/docs/eventing/filtering.md new file mode 100644 index 00000000000..3af6f846eb4 --- /dev/null +++ b/docs/eventing/filtering.md @@ -0,0 +1,32 @@ +# Event Filters in Triggers + +Filters are used in Triggers to specify the set of events that are interesting +to a subscriber. If you only want to receive some events, and you know which +attributes identify the events you're interested in, use a filter in your +Trigger to ensure the Trigger's subscriber will receive only events that match +the filter. + +## Before you begin + +1. Read about the [Broker and Trigger objects](./broker-trigger.md). +1. Be familiar with the + [CloudEvents spec](https://github.com/cloudevents/spec/blob/master/spec.md), + particularly the + [Context Attributes](https://github.com/cloudevents/spec/blob/master/spec.md#context-attributes) + section. +1. Read the + [Common Expression Language introduction](https://github.com/google/cel-spec/blob/master/doc/intro.md), + and optionally the + [language definition](https://github.com/google/cel-spec/blob/master/doc/langdef.md). + +## Filtering events + +TODO "how to" info (the "task-oriented" step by step details for creating an event filter in a trigger) -> use a gerund in title (for example Filtering event attributes) + +## Filter examples + +TODO Example(s) (show them how and where they would/can create a filter in their trigger) i see lots in the proposal and it would be most consumable if we could organize these to some degree + +## Next steps + +TODO Link to what the next logical step would be (and include links to related info) to keep the user moving forward \ No newline at end of file From a36a21551f9ceeb541c098feb5a11bcb77da881f Mon Sep 17 00:00:00 2001 From: Grant Rodgers Date: Mon, 13 May 2019 13:57:14 -0700 Subject: [PATCH 4/4] wip --- docs/eventing/filtering.md | 40 +++++++++++++++++++++++++------------- 1 file changed, 27 insertions(+), 13 deletions(-) diff --git a/docs/eventing/filtering.md b/docs/eventing/filtering.md index 3af6f846eb4..28b7635f8bd 100644 --- a/docs/eventing/filtering.md +++ b/docs/eventing/filtering.md @@ -8,25 +8,39 @@ the filter. ## Before you begin -1. Read about the [Broker and Trigger objects](./broker-trigger.md). -1. Be familiar with the - [CloudEvents spec](https://github.com/cloudevents/spec/blob/master/spec.md), - particularly the - [Context Attributes](https://github.com/cloudevents/spec/blob/master/spec.md#context-attributes) - section. -1. Read the - [Common Expression Language introduction](https://github.com/google/cel-spec/blob/master/doc/intro.md), - and optionally the - [language definition](https://github.com/google/cel-spec/blob/master/doc/langdef.md). +1. Read about the [Broker and Trigger objects](./broker-trigger.md). +1. Be familiar with the + [CloudEvents spec](https://github.com/cloudevents/spec/blob/master/spec.md), + particularly the + [Context Attributes](https://github.com/cloudevents/spec/blob/master/spec.md#context-attributes) + section. +1. Read the + [Common Expression Language introduction](https://github.com/google/cel-spec/blob/master/doc/intro.md), + and optionally the + [language definition](https://github.com/google/cel-spec/blob/master/doc/langdef.md). ## Filtering events -TODO "how to" info (the "task-oriented" step by step details for creating an event filter in a trigger) -> use a gerund in title (for example Filtering event attributes) +Events can be filtered in one of two ways: by **attributes** and by **expression**. Only +one of these filtering methods may be used per Trigger. + +### Filtering by attributes + + + +TODO "how to" info (the "task-oriented" step by step details for creating an +event filter in a trigger) -> use a gerund in title (for example Filtering event +attributes) ## Filter examples -TODO Example(s) (show them how and where they would/can create a filter in their trigger) i see lots in the proposal and it would be most consumable if we could organize these to some degree +### I want to receive events of a specific type + +TODO Example(s) (show them how and where they would/can create a filter in their +trigger) i see lots in the proposal and it would be most consumable if we could +organize these to some degree ## Next steps -TODO Link to what the next logical step would be (and include links to related info) to keep the user moving forward \ No newline at end of file +TODO Link to what the next logical step would be (and include links to related +info) to keep the user moving forward