Skip to content

Commit

Permalink
feat: documented new trigger filters are GA (#6060) (#6093)
Browse files Browse the repository at this point in the history
* feat: documented new trigger filters are GA



* fix: formatting



* cleanup: remove trigger filters feature file



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



---------

Signed-off-by: Calum Murray <cmurray@redhat.com>
Cali0707 authored Aug 22, 2024
1 parent f55b5c7 commit 8a73b4e
Showing 5 changed files with 194 additions and 202 deletions.
1 change: 0 additions & 1 deletion config/nav.yml
Original file line number Diff line number Diff line change
@@ -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 changes: 2 additions & 1 deletion config/redirects.yml
Original file line number Diff line number Diff line change
@@ -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 change: 0 additions & 1 deletion docs/eventing/features/README.md
Original file line number Diff line number Diff line change
@@ -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 changes: 0 additions & 188 deletions docs/eventing/features/new-trigger-filters.md

This file was deleted.

203 changes: 192 additions & 11 deletions docs/eventing/triggers/README.md
Original file line number Diff line number Diff line change
@@ -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:

0 comments on commit 8a73b4e

Please sign in to comment.