From 3bdd4449d760f72f2c16e739c1ee6969f0ad24ea Mon Sep 17 00:00:00 2001 From: Hector Martinez Date: Tue, 19 Mar 2024 12:16:50 +0100 Subject: [PATCH 1/2] 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 --- config/nav.yml | 1 + .../new-apiserversource-filters.md | 167 ++++++++++++++++++ 2 files changed, 168 insertions(+) create mode 100644 docs/eventing/experimental-features/new-apiserversource-filters.md diff --git a/config/nav.yml b/config/nav.yml index 5aada7b34c9..7caf10d6cef 100644 --- a/config/nav.yml +++ b/config/nav.yml @@ -280,6 +280,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 new file mode 100644 index 00000000000..7d7f0d504d8 --- /dev/null +++ b/docs/eventing/experimental-features/new-apiserversource-filters.md @@ -0,0 +1,167 @@ +# New trigger filters + +**Flag name**: `new-apiserversource-filters` + +**Stage**: Beta, enabled 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` From f67f0335acb2868f7a086dbcd62460c346ef658c Mon Sep 17 00:00:00 2001 From: Hector Martinez <87312991+rh-hemartin@users.noreply.github.com> Date: Wed, 8 May 2024 14:39:02 +0200 Subject: [PATCH 2/2] MR suggestion Co-authored-by: Pierangelo Di Pilato --- .../experimental-features/new-apiserversource-filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/eventing/experimental-features/new-apiserversource-filters.md b/docs/eventing/experimental-features/new-apiserversource-filters.md index 7d7f0d504d8..7a1469e6fde 100644 --- a/docs/eventing/experimental-features/new-apiserversource-filters.md +++ b/docs/eventing/experimental-features/new-apiserversource-filters.md @@ -2,7 +2,7 @@ **Flag name**: `new-apiserversource-filters` -**Stage**: Beta, enabled by default +**Stage**: Alpha, disabled by default **Tracking issue**: [#7791](https://github.com/knative/eventing/issues/7791) ## Overview