From 852e0fcbc9efab435fa45d8081ed7c5a8fd92a87 Mon Sep 17 00:00:00 2001
From: Ignacio Cano <nachoacano@gmail.com>
Date: Wed, 7 Aug 2019 12:02:56 -0700
Subject: [PATCH] Attributes Filter documentation in Trigger (#1653)

* Adding bitbucket source documentation.

* Adding README example for bitbucket source.

* Updating example.

* Missed to generate the README

* removing stuff, and updating link to bitbucket source in sources.yaml

* autogenerating README

* removing bitbucket one here.

* update

* updating broker/trigger based on filtering and new channel CRDs

* changes after code review
---
 docs/eventing/broker-trigger.md | 54 +++++++++++++++------------------
 1 file changed, 24 insertions(+), 30 deletions(-)

diff --git a/docs/eventing/broker-trigger.md b/docs/eventing/broker-trigger.md
index 3eadf5d4f..047a8f8eb 100644
--- a/docs/eventing/broker-trigger.md
+++ b/docs/eventing/broker-trigger.md
@@ -33,7 +33,7 @@ spec:
 ## Trigger
 
 A Trigger represents a desire to subscribe to events from a specific Broker.
-Basic filtering on the type and source of events is provided.
+Exact match filtering on CloudEvents attributes as well as extensions are supported.
 
 Example:
 
@@ -44,7 +44,7 @@ metadata:
   name: my-service-trigger
 spec:
   filter:
-    sourceAndType:
+    attributes:
       type: dev.knative.foo.bar
   subscriber:
     ref:
@@ -55,39 +55,38 @@ spec:
 
 ## Usage
 
-### ClusterChannelProvisioner
+### Channel
 
-`Broker`s use their `spec.channelTemplate` to create their internal `Channel`s,
+`Broker`s use their `spec.channelTemplateSpec` to create their internal [Channels](./channels/),
 which dictate the durability guarantees of events sent to that `Broker`. If
-`spec.channelTemplate` is not specified, then the
-[default provisioner](https://www.knative.dev/docs/eventing/channels/default-channels/)
+`spec.channelTemplateSpec` is not specified, then the
+[default channel](./channels/default-channels.md)
 for their namespace is used.
 
 #### Setup
 
-Have a `ClusterChannelProvisioner` installed and set as the
-[default provisioner](https://www.knative.dev/docs/eventing/channels/default-channels/)
-for the namespace you are interested in. For development, the
-[`in-memory` `ClusterChannelProvisioner`](https://github.com/knative/eventing/tree/master/config/provisioners/in-memory-channel#deployment-steps)
+Have a `Channel` CRD installed and set as the
+default channel for the namespace you are interested in. For development, the
+[InMemoryChannel](https://github.com/knative/eventing/tree/master/config/channels/in-memory-channel)
 is normally used.
 
 #### Changing
 
-**Note** changing the `ClusterChannelProvisioner` of a running `Broker` will
+**Note** changing the `Channel` of a running `Broker` will
 lose all in-flight events.
 
-If you want to change which `ClusterChannelProvisioner` is used by a given
-`Broker`, then determine if the `spec.channelTemplate` is specified or not.
+If you want to change which `Channel` is used by a given
+`Broker`, then determine if the `spec.channelTemplateSpec` is specified or not.
 
-If `spec.channelTemplate` is specified:
+If `spec.channelTemplateSpec` is specified:
 
 1. Delete the `Broker`.
-1. Create the `Broker` with the updated `spec.channelTemplate`.
+1. Create the `Broker` with the updated `spec.channelTemplateSpec`.
 
-If `spec.channelTemplate` is not specified:
+If `spec.channelTemplateSpec` is not specified:
 
 1. Change the
-   [default provisioner](https://github.com/knative/docs/blob/master/docs/eventing/channels/default-channels.md#setting-the-default-channel-configuration)
+   [default channel](./channels/default-channels.md#setting-the-default-channel-configuration)
    for the namespace that `Broker` is in.
 1. Delete and recreate the `Broker`.
 
@@ -226,7 +225,7 @@ metadata:
   namespace: default
 spec:
   filter:
-    sourceAndType:
+    attributes:
       type: dev.knative.foo.bar
   subscriber:
     ref:
@@ -237,11 +236,7 @@ spec:
 
 #### Defaulting
 
-The Webhook will default certain unspecified fields. For example if
-`spec.broker` is unspecified, it will default to `default`. If
-`spec.filter.sourceAndType.type` or `spec.filter.sourceAndType.Source` are
-unspecified, then they will default to the special value empty string, which
-matches everything.
+The Webhook will default the `spec.broker` field to `default`, if left unspecified. 
 
 The Webhook will default the YAML above to:
 
@@ -254,9 +249,8 @@ metadata:
 spec:
   broker: default # Defaulted by the Webhook.
   filter:
-    sourceAndType:
+    attributes:
       type: dev.knative.foo.bar
-      source: "" # Defaulted by the Webhook.
   subscriber:
     ref:
       apiVersion: serving.knative.dev/v1alpha1
@@ -265,7 +259,7 @@ spec:
 ```
 
 You can make multiple `Trigger`s on the same `Broker` corresponding to different
-types, sources, and subscribers.
+types, sources (or any other CloudEvents attribute), and subscribers.
 
 ### Source
 
@@ -285,10 +279,10 @@ While SSHed into a `Pod` and run:
 curl -v "http://default-broker.default.svc.cluster.local/" \
   -X POST \
   -H "X-B3-Flags: 1" \
-  -H "CE-CloudEventsVersion: 0.1" \
-  -H "CE-EventType: dev.knative.foo.bar" \
-  -H "CE-EventTime: 2018-04-05T03:56:24Z" \
-  -H "CE-EventID: 45a8b444-3213-4758-be3f-540bf93f85ff" \
+  -H "CE-SpecVersion: 0.2" \
+  -H "CE-Type: dev.knative.foo.bar" \
+  -H "CE-Time: 2018-04-05T03:56:24Z" \
+  -H "CE-ID: 45a8b444-3213-4758-be3f-540bf93f85ff" \
   -H "CE-Source: dev.knative.example" \
   -H 'Content-Type: application/json' \
   -d '{ "much": "wow" }'