diff --git a/docs/eventing/README.md b/docs/eventing/README.md index c26eafd2b14..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) @@ -89,7 +91,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 +105,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) diff --git a/docs/eventing/filtering.md b/docs/eventing/filtering.md new file mode 100644 index 00000000000..28b7635f8bd --- /dev/null +++ b/docs/eventing/filtering.md @@ -0,0 +1,46 @@ +# 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 + +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 + +### 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