diff --git a/config/nav.yml b/config/nav.yml index a9721a60381..bf41f544666 100644 --- a/config/nav.yml +++ b/config/nav.yml @@ -297,7 +297,6 @@ nav: - About Eventing features: eventing/features/README.md - DeliverySpec.Timeout field: eventing/features/delivery-timeout.md - DeliverySpec.RetryAfterMax field: eventing/features/delivery-retryafter.md - - New Trigger Filters: eventing/features/new-trigger-filters.md - New APIServerSource Filters: eventing/features/new-apiserversource-filters.md - KReference.Group field: eventing/features/kreference-group.md - Knative reference mapping: eventing/features/kreference-mapping.md diff --git a/config/redirects.yml b/config/redirects.yml index 45cad385e94..3f1be0a181b 100644 --- a/config/redirects.yml +++ b/config/redirects.yml @@ -5,12 +5,13 @@ plugins: eventing/experimental-features/README.md: eventing/features/README.md eventing/experimental-features/delivery-timeout.md: eventing/features/delivery-timeout.md eventing/experimental-features/delivery-retryafter.md: eventing/features/delivery-retryafter.md - eventing/experimental-features/new-trigger-filters.md: eventing/features/new-trigger-filters.md + eventing/experimental-features/new-trigger-filters.md: eventing/triggers/README.md eventing/experimental-features/kreference-group.md: eventing/features/kreference-group.md eventing/experimental-features/kreference-mapping.md: eventing/features/kreference-mapping.md eventing/experimental-features/eventtype-auto-creation.md: eventing/features/eventtype-auto-creation.md eventing/experimental-features/transport-encryption.md: eventing/features/transport-encryption.md eventing/experimental-features/sender-identity.md: eventing/features/sender-identity.md + eventing/features/new-trigger-filters.md: eventing/triggers/README.md eventing/broker/kafka-broker/kafka-configmap.md: eventing/configuration/kafka-channel-configuration.md eventing/broker/create-mtbroker.md: eventing/brokers/create-broker.md eventing/broker/example-mtbroker.md: eventing/brokers/broker-developer-config-options.md diff --git a/docs/eventing/features/README.md b/docs/eventing/features/README.md index 7d94c7cc8fa..90e87bdb368 100644 --- a/docs/eventing/features/README.md +++ b/docs/eventing/features/README.md @@ -72,7 +72,6 @@ Knative Eventing: | [DeliverySpec.Timeout field](delivery-timeout.md) | `delivery-timeout` | When using the `delivery` spec to configure event delivery parameters, you can use the`timeout` field to specify the timeout for each sent HTTP request. | Beta, enabled by default | | [KReference.Group field](kreference-group.md) | `kreference-group` | Specify the API `group` of `KReference` resources without the API version. | Alpha, disabled by default | | [Knative reference mapping](kreference-mapping.md) | `kreference-mapping` | Provide mappings from a [Knative reference](https://github.com/knative/specs/blob/main/specs/eventing/overview.md#destination) to a templated URI. | Alpha, disabled by default | -| [New trigger filters](new-trigger-filters.md) | `new-trigger-filters` | Enables a new Trigger `filters` field that supports a set of powerful filter expressions. | Beta, enabled by default | | [Transport encryption](transport-encryption.md) | `transport-encryption` | Enables components to encrypt traffic using TLS by exposing HTTPS URL. | Beta, disabled by default | | [Sender Identity](sender-identity.md) | `authentication-oidc` | Enables Eventing sources to send authenticated requests and addressables to require authenticated requests. | Alpha, disabled by default | | [Eventing with Istio](istio-integration.md) | `istio` | Enables Eventing components to communicate with workloads in an Istio mesh. | Beta, disabled by default | diff --git a/docs/eventing/features/new-trigger-filters.md b/docs/eventing/features/new-trigger-filters.md deleted file mode 100644 index e57c8839d2a..00000000000 --- a/docs/eventing/features/new-trigger-filters.md +++ /dev/null @@ -1,188 +0,0 @@ -# New trigger filters - -**Flag name**: `new-trigger-filters` - -**Stage**: Beta, enabled by default - -**Tracking issue**: [#5204](https://github.com/knative/eventing/issues/5204) -## Overview -This feature enables a new `filters` field in Triggers 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 Trigger using the new `filters` field: - -```yaml -apiVersion: eventing.knative.dev/v1 -kind: Trigger -metadata: - name: my-service-trigger -spec: - broker: default - filters: - - cesql: "source LIKE '%commerce%' AND type IN ('order.created', 'order.updated', 'order.canceled')" - subscriber: - ref: - apiVersion: serving.knative.dev/v1 - kind: Service - name: my-service -``` - -## 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 `subscriber`. -* 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: eventing.knative.dev/v1 -kind: Trigger -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: eventing.knative.dev/v1 -kind: Trigger -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: eventing.knative.dev/v1 -kind: Trigger -metadata: - ... -spec: - ... - filters: - - suffix: - type: .created -``` - -### `all` - -All nested filter expressions must evaluate to true. - -```yaml -apiVersion: eventing.knative.dev/v1 -kind: Trigger -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: eventing.knative.dev/v1 -kind: Trigger -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: eventing.knative.dev/v1 -kind: Trigger -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: eventing.knative.dev/v1 -kind: Trigger -metadata: - ... -spec: - ... - filters: - - cesql: "source LIKE '%commerce%' AND type IN ('order.created', 'order.updated', 'order.canceled')" -``` - -## Conflict with the current `filter` field - -The current `filter` field will continue to be supported. However, if you enable this feature and an object includes both `filter` and `filters`, the new `filters` field overrides the `filter` field. This allows you to try the new `filters` field without compromising existing filters, and you can introduce it to existing `Trigger` objects gradually. - -```yaml -apiVersion: eventing.knative.dev/v1 -kind: Trigger -metadata: - name: my-service-trigger -spec: - broker: default - # Current filter field. Will be ignored. - filter: - attributes: - type: dev.knative.foo.bar - myextension: my-extension-value - # Enhanced filters field. This will override the old filter field. - filters: - - cesql: "type = 'dev.knative.foo.bar' AND myextension = 'my-extension-value'" - subscriber: - ref: - apiVersion: serving.knative.dev/v1 - kind: Service - name: my-service -``` - -## FAQ - -### Why add yet another field? Why not make the current `filter` field more robust? - -The reason is twofold. First, at the time of developing `Trigger` APIs, there was no Subscriptions API in CloudEvents Project, so it makes sense to experiment with an API that is closer to the Subscriptions API. Second, we still want to support users workload with the old `filter` field, and give them the possibility to transition to the new `filters` field. - -### Why `filters` and not another name that wouldn't conflict with the `filter` field? - -We considered other names, such as `cefilters`, `subscriptionsAPIFilters`, or `enhancedFilters`, but we decided that this would be a step further from aligning with the Subscriptions API. Instead, we decided it is a good opportunity to conform with the Subscriptions API, at least at the field name level, and to leverage the safety of this being a feature. diff --git a/docs/eventing/triggers/README.md b/docs/eventing/triggers/README.md index 2915ceecaa3..f1daa2d89fa 100644 --- a/docs/eventing/triggers/README.md +++ b/docs/eventing/triggers/README.md @@ -62,16 +62,21 @@ delivers them to the custom path `/my-custom-path` for the Kubernetes service `m ## Trigger filtering -Exact match filtering on any number of CloudEvents attributes as well as -extensions are supported. If your filter sets multiple attributes, an event must -have all of the attributes for the trigger to filter it. Note that we only -support exact matching on string values. +Various forms of filtering based on any number of CloudEvents attributes and extensions +are supported. If multiple `filters` are provided, all of them must evaluate to true +in order for the event to be passed to the subscriber of the trigger. Note that we +do not support filtering on the `data` field of CloudEvents. + +!!! important + The filters described in this section are currently only supported in the Apache Kafka Broker + and the MTChannelBasedBroker. For other brokers, please refer to the [Legacy attribute filter](#legacy-attributes-filter). + ### Example This example filters events from the `default` broker that are of type -`dev.knative.foo.bar` and have the extension `myextension` with the value -`my-extension-value`. +`dev.knative.foo.bar` and have the extension `myextension` which ends +with `-extensions. 1. Create a YAML file using the following example: @@ -82,10 +87,11 @@ This example filters events from the `default` broker that are of type name: my-service-trigger spec: broker: default - filter: - attributes: + filters: + exact: type: dev.knative.foo.bar - myextension: my-extension-value + suffix: + myextension: -value subscriber: ref: apiVersion: serving.knative.dev/v1 @@ -100,9 +106,184 @@ This example filters events from the `default` broker that are of type ``` Where `` is the name of the file you created in the previous step. -### New trigger filters +### Supported filter dialects + +#### `exact` + +CloudEvent attribute String value must exactly match the specified String value. Matching is case-sensitive. +If the attribute is not a String, the filter will compare a String representation of the attribute to the +specified String value. + +```yaml +apiVersion: eventing.knative.dev/v1 +kind: Trigger +metadata: + ... +spec: + ... + filters: + - exact: + type: com.github.push +``` + +#### `prefix` + +CloudEvent attribute String value must start with the specified String value. Matching is case-sensitive. +If the attribute is not a String, the filter will compare a String representation of the attribute to the +specified String value. + +```yaml +apiVersion: eventing.knative.dev/v1 +kind: Trigger +metadata: + ... +spec: + ... + filters: + - prefix: + type: com.github. +``` + +#### `suffix` + +CloudEvent attribute String value must end with the specified String value. Matching is case-sensitive. +If the attribute is not a String, the filter will compare a String representation of the attribute to the +specified String value. + +```yaml +apiVersion: eventing.knative.dev/v1 +kind: Trigger +metadata: + ... +spec: + ... + filters: + - suffix: + type: .created +``` + +#### `all` + +All nested filter expressions must evaluate to true. + +```yaml +apiVersion: eventing.knative.dev/v1 +kind: Trigger +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: eventing.knative.dev/v1 +kind: Trigger +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: eventing.knative.dev/v1 +kind: Trigger +metadata: + ... +spec: + ... + filters: + - not: + exact: + type: com.github.push +``` +#### `cesql` + +The provided [CloudEvents SQL Expression](https://github.com/cloudevents/spec/blob/cesql/v1.0.0/cesql/spec.md) must evaluate to true. + +!!! important + Knative 1.15+ only supports the CloudEvents SQL v1.0 specification. Any CESQL expressions written prior to Knative v1.15 should + be verified, as there were some changes in the CESQL specification. + +```yaml +apiVersion: eventing.knative.dev/v1 +kind: Trigger +metadata: + ... +spec: + ... + filters: + - cesql: "source LIKE '%commerce%' AND type IN ('order.created', 'order.updated', 'order.canceled')" +``` + +### Legacy attributes filter + +The legacy attributes filter provides exact match filtering on any number of CloudEvents attributes as well as extensions. +It's semantics and behaviour are the same as the `exact` filter dialect and wherever possible users should move to the +`exact` filter. However, for backwards compatability the attributes filter will continue to work for all users. The following +example filters events from the `default` broker that are of type `dev.knative.foo.bar` and have the extension `myextension` +with the value `my-extension-value`. + +```yaml +apiVersion: eventing.knative.dev/v1 +kind: Trigger +metadata: + name: my-service-trigger +spec: + broker: default + filter: + attributes: + type: dev.knative.foo.bar + myextension: my-extension-value + subscriber: + ref: + apiVersion: serving.knative.dev/v1 + kind: Service + name: my-service +``` + +Whenver both the `filters` field and the `filter` field are both provided, the `filters` field will override the `filter` field. For example, +in the following trigger events with type `dev.knative.a` will be delivered, while events with type `dev.knative.b` will not. + +```yaml +apiVersion: eventing.knative.dev/v1 +kind: Trigger +metadata: + name: my-service-trigger +spec: + broker: default + filters: + exact: + type: dev.knative.a + filter: + attributes: + type: dev.knative.b + subscriber: + ref: + apiVersion: serving.knative.dev/v1 + kind: Service + name: my-service +``` -If you need more powerful filtering options, you can use the [new trigger filters](../features/new-trigger-filters.md). ## Trigger annotations You can modify a Trigger's behavior by setting the following two annotations: