New trigger filters

New trigger filters

Flag name: new-trigger-filters

Stage: Alpha, disabled by default

Tracking issue: #5204

Overview

This experimental feature enables a new filters field in Triggers that conforms to the filters API field defined in the CloudEvents Subscriptions API. 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:

apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
  name: my-service-trigger
spec:
  broker: default
  filters:
    - sql: "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.

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.

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.

apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
  ...
spec:
  ...
  filters:
    - suffix:
        type: .created

`all`

All nested filter expessions must evaluate to true.

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 expession must evaluate to true.

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.

apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
  ...
spec:
  ...
  filters:
    - not:
        - exact:
            type: com.github.push

`sql`

The provided CloudEvents SQL Expression must evaluate to true.

apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
  ...
spec:
  ...
  filters:
    - sql: "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.

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:
    - sql: "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 an experimental feature.

New Trigger Filters