Add SubscriptionsAPI filters to APIServerSource (#5916)

* Add SubscriptionsAPI filters to APIServerSource This MR adds a page for the experimental feature that add `filters` to the APIServerSource kind. Related to #7799 and #7791 Signed-off-by: Hector Martinez <[email protected]> * MR suggestion Co-authored-by: Pierangelo Di Pilato <[email protected]> --------- Signed-off-by: Hector Martinez <[email protected]> Co-authored-by: Pierangelo Di Pilato <[email protected]>
knative · May 13, 2024 · 84776e2 · 84776e2
1 parent 872e83e
commit 84776e2
Show file tree

Hide file tree

Showing 2 changed files with 168 additions and 0 deletions.
diff --git a/config/nav.yml b/config/nav.yml
@@ -282,6 +282,7 @@ nav:
         - DeliverySpec.Timeout field: eventing/experimental-features/delivery-timeout.md
         - DeliverySpec.RetryAfterMax field: eventing/experimental-features/delivery-retryafter.md
         - New Trigger Filters: eventing/experimental-features/new-trigger-filters.md
+        - New APIServerSource Filters: eventing/experimental-features/new-apiserversource-filters.md
         - KReference.Group field: eventing/experimental-features/kreference-group.md
         - Knative reference mapping: eventing/experimental-features/kreference-mapping.md
         - EventType auto creation: eventing/experimental-features/eventtype-auto-creation.md

diff --git a/docs/eventing/experimental-features/new-apiserversource-filters.md b/docs/eventing/experimental-features/new-apiserversource-filters.md
@@ -0,0 +1,167 @@
+# New trigger filters
+
+**Flag name**: `new-apiserversource-filters`
+
+**Stage**: Alpha, disabled by default
+
+**Tracking issue**: [#7791](https://github.com/knative/eventing/issues/7791)
+## Overview
+This experimental feature enables a new `filters` field in APIServerSource that conforms to the filters API field defined in the [`CloudEvents Subscriptions API`](https://github.com/cloudevents/spec/blob/main/subscriptions/spec.md#324-filters). It allows users to specify a set of powerful filter expressions, where each expression evaluates to either true or false for each event.
+
+The following example shows a APIServerSource using the new `filters` field:
+
+```yaml
+---
+apiVersion: sources.knative.dev/v1
+kind: ApiServerSource
+metadata:
+ name: my-apiserversource
+ namespace: default
+spec:
+  filters:
+  - any:
+    - exact:
+        type: dev.knative.apiserver.ref.add
+
+  serviceAccountName: apiserversource
+  mode: Reference
+  resources: ...
+  sink: ...
+
+```
+
+## About the filters field
+* An array of filter expressions that evaluates to true or false. If any filter expression in the array evaluates to false, the event will not be sent to the `sink`.
+* Each filter expression follows a dialect that defines the type of filter and the set of additional properties that are allowed within the filter expression.
+
+## Supported filter dialects
+
+The `filters` field supports the following dialects:
+
+### `exact`
+
+CloudEvent attribute String value must exactly match the specified String value. Matching is case-sensitive.
+
+```yaml
+apiVersion: sources.knative.dev/v1
+kind: APIServerSource
+metadata:
+  ...
+spec:
+  ...
+  filters:
+    - exact:
+        type: com.github.push
+```
+
+### `prefix`
+
+CloudEvent attribute String value must start with the specified String value. Matching is case-sensitive.
+
+```yaml
+apiVersion: sources.knative.dev/v1
+kind: APIServerSource
+metadata:
+  ...
+spec:
+  ...
+  filters:
+    - prefix:
+        type: com.github.
+```
+
+### `suffix`
+
+CloudEvent attribute String value must end with the specified String value. Matching is case-sensitive.
+
+```yaml
+apiVersion: sources.knative.dev/v1
+kind: APIServerSource
+metadata:
+  ...
+spec:
+  ...
+  filters:
+    - suffix:
+        type: .created
+```
+
+### `all`
+
+All nested filter expressions must evaluate to true.
+
+```yaml
+apiVersion: sources.knative.dev/v1
+kind: APIServerSource
+metadata:
+  ...
+spec:
+  ...
+  filters:
+    - all:
+        - exact:
+            type: com.github.push
+        - exact:
+            subject: https://github.com/cloudevents/spec
+```
+
+### `any`
+
+At least one nested filter expression must evaluate to true.
+
+```yaml
+apiVersion: sources.knative.dev/v1
+kind: APIServerSource
+metadata:
+  ...
+spec:
+  ...
+  filters:
+    - any:
+        - exact:
+            type: com.github.push
+        - exact:
+            subject: https://github.com/cloudevents/spec
+```
+
+### `not`
+
+The nested expression evaluated must evaluate to false.
+
+```yaml
+apiVersion: sources.knative.dev/v1
+kind: APIServerSource
+metadata:
+  ...
+spec:
+  ...
+  filters:
+      - not:
+          exact:
+              type: com.github.push
+```
+### `cesql`
+
+The provided [CloudEvents SQL Expression](https://github.com/cloudevents/spec/blob/main/cesql/spec.md) must evaluate to true.
+
+```yaml
+apiVersion: sources.knative.dev/v1
+kind: APIServerSource
+metadata:
+  ...
+spec:
+  ...
+  filters:
+    - cesql: "source LIKE '%commerce%' AND type IN ('order.created', 'order.updated', 'order.canceled')"
+```
+
+## FAQ
+
+## Which are the event types APIServerSource provide?
+
+* `dev.knative.apiserver.resource.add`
+* `dev.knative.apiserver.resource.update`
+* `dev.knative.apiserver.resource.delete`
+* `dev.knative.apiserver.ref.add`
+* `dev.knative.apiserver.ref.update`
+* `dev.knative.apiserver.ref.delete`