knative
/
docs
mirror of https://github.com/knative/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

feat: documented new trigger filters are GA (#6060) 

* feat: documented new trigger filters are GA

Signed-off-by: Calum Murray <cmurray@redhat.com>

* fix: formatting

Signed-off-by: Calum Murray <cmurray@redhat.com>

* cleanup: remove trigger filters feature file

Signed-off-by: Calum Murray <cmurray@redhat.com>

* fix: redirect should work for experimental-features/new-trigger-filters

Signed-off-by: Calum Murray <cmurray@redhat.com>

---------

Signed-off-by: Calum Murray <cmurray@redhat.com>
This commit is contained in:
Calum Murray 2024-08-09 09:57:12 -04:00 committed by GitHub
parent 0ff0007a04
commit 3ba98cc699
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
5 changed files with 194 additions and 202 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
config/nav.yml
View File

@ -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

3
config/redirects.yml
View File

@ -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

1
docs/eventing/features/README.md
View File

@ -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 |

188
docs/eventing/features/new-trigger-filters.md
View File

@ -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.

203
docs/eventing/triggers/README.md
View File

@ -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 `<filename>` 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: