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

Add documentation for new trigger filters (#4635) 

* Add documentation for new trigger filters

Signed-off-by: Ahmed Abdalla <aabdelre@redhat.com>

* fix a conflict

Signed-off-by: Ahmed Abdalla <aabdelre@redhat.com>

* Add new trigger filters to the overview table

Signed-off-by: Ahmed Abdalla <aabdelre@redhat.com>

* fix wrong formatting and add missing docs

Signed-off-by: Ahmed Abdalla <aabdelre@redhat.com>

* fixes dialect formatting

Signed-off-by: Ahmed Abdalla <aabdelre@redhat.com>

* fix new trigger filter docs

Signed-off-by: Ahmed Abdalla <aabdelre@redhat.com>

* Apply suggestions from code review

Co-authored-by: Samia Nneji <snneji@vmware.com>

* fix formatting

Signed-off-by: Ahmed Abdalla <aabdelre@redhat.com>

Co-authored-by: Samia Nneji <snneji@vmware.com>
This commit is contained in:
Ahmed Abdalla Abdelrehim 2022-01-19 16:10:53 +01:00 committed by GitHub
parent aaed06197c
commit a932249bf7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 517 additions and 303 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
config/nav.yml
View File

@ -209,7 +209,14 @@ nav:
# Eventing - troubleshooting
- Troubleshooting:
- Debugging: eventing/troubleshooting/README.md
- Experimental Features: eventing/experimental-features.md
- Experimental Features:
- About Eventing experimental features: eventing/experimental-features/README.md
- 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
- KReference.Group field: eventing/experimental-features/kreference-group.md
- Knative reference mapping: eventing/experimental-features/kreference-mapping.md
- Strict Subscriber: eventing/experimental-features/strict-subscriber.md
###############################################################################
# Code samples
###############################################################################

302
docs/eventing/experimental-features.md
View File

@ -1,302 +0,0 @@
# Experimental features
In order to keep Knative innovative, the maintainers of this project have
developed an
[experimental features process](https://github.com/knative/eventing/blob/main/docs/experimental-features.md),
that allows new, experimental features to be delivered and tested by users,
without affecting the stability of the core project.
<!--TODO: Add note about HOW / where users can provide feedback, otherwise there's not much point mentioning that-->
!!! warning
Experimental features are unstable and may cause issues in your Knative setup or even your cluster setup.
These features should be used with caution, and should never be tested on a production environment. For more
information about quality guarantees for features at different stages of
development, see the
[Feature stage definition](https://github.com/knative/eventing/blob/main/docs/experimental-features.md#stage-definition)
documentation.
This document explains how to enable experimental features and which ones are
available today.
## Before you begin
You must have a Knative cluster running with Knative Eventing installed.
## Experimental features configuration
When you install Knative Eventing, the `config-features` ConfigMap is added to
your cluster in the `knative-eventing` namespace.
In order to enable a feature, you must add it to the `config-features` ConfigMap
under the `data` spec, and set the value for the feature to `enabled`. For example,
to enable a feature called `new-cool-feature`, you would add the following ConfigMap
entry:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: config-features
namespace: knative-eventing
labels:
eventing.knative.dev/release: devel
knative.dev/config-propagation: original
knative.dev/config-category: eventing
data:
new-cool-feature: enabled
```
In order to disable it, you can either remove the flag or set it to `disabled`:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: config-features
namespace: knative-eventing
labels:
eventing.knative.dev/release: devel
knative.dev/config-propagation: original
knative.dev/config-category: eventing
data:
new-cool-feature: disabled
```
## Features list
### KReference.Group field
**Flag name**: `kreference-group`
**Stage**: Alpha, disabled by default
**Tracking issue**: [#5086](https://github.com/knative/eventing/issues/5086)
**Persona**: Developer
When using the `KReference` type to refer to another Knative resource, you can
just specify the API `group` of the resource, instead of the full `APIVersion`.
For example, in order to refer to an `InMemoryChannel`, instead of the following
spec:
```yaml
apiVersion: messaging.knative.dev/v1
kind: InMemoryChannel
name: my-channel
```
You can use the following:
```yaml
group: messaging.knative.dev
kind: InMemoryChannel
name: my-channel
```
With this feature you can allow Knative to resolve the full `APIVersion` and
further upgrades, deprecations and removals of the referred CRD without
affecting existing resources.
!!! note
At the moment this feature is implemented only for
`Subscription.Spec.Subscriber.Ref` and `Subscription.Spec.Channel`.
### DeliverySpec.RetryAfterMax field
**Flag name**: `delivery-retryafter`
**Stage**: Alpha, disabled by default
**Tracking issue**: [#5811](https://github.com/knative/eventing/issues/5811)
**Persona**: Developer
When using the `delivery` spec to configure event delivery parameters, you can
use the `retryAfterMax` field to specify how
HTTP [Retry-After](https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3)
headers are handled when calculating backoff times for retrying **429** and
**503** responses. You can specify a `delivery` spec for Channels,
Subscriptions, Brokers, Triggers, and any other resource spec that accepts the
`delivery` field.
The `retryAfterMax` field only takes effect if you configure the `delivery` spec
to perform retries, and only pertains to retry attempts on **429** and **503**
response codes. The field provides an override to prevent large **Retry-After**
durations from impacting throughput, and must be specified using
the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Times) format. The largest
of the normal backoff duration and the Retry-After header value will be used for
the subsequent retry attempt. Specifying a "zero" value of `PT0S` effectively
disables **Retry-After** support.
Prior to this experimental feature, Knative Eventing implementations have not
supported **Retry-After** headers, and this is an attempt to provide a path
for standardizing that support. To begin, the feature is **opt-in**, but the
final state will be **opt-out** as follows:
| Feature Stage | Feature Flag | retryAfterMax Field Absent | retryAfterMax Field Present |
| --- | --- | --- | --- |
| Alpha / Beta | Disabled | Accepted by Webhook Validation & Retry-After headers NOT enforced | Rejected by WebHook Validation |
| Alpha / Beta | Enabled | Accepted by Webhook Validation & Retry-After headers NOT enforced | Accepted by Webhook Validation & Retry-After headers enforced if max override > 0 |
| Stable / GA | n/a | Retry-After headers enforced without max override | Retry-After headers enforced if max override > 0 |
The following example shows a Subscription that retries sending an event three
times, and respects **Retry-After** headers while imposing a maximum backoff of
120 seconds:
```yaml
apiVersion: messaging.knative.dev/v1
kind: Subscription
metadata:
name: example-subscription
namespace: example-namespace
spec:
subscriber:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: example-sink
delivery:
backoffDelay: PT2S
backoffPolicy: linear
retry: 3
retryAfterMax: PT120S
```
!!! note
While the experimental feature flag enforces all DeliverySpec usage of the
`retryAfterMax` field through Webhook validation, it does not guarantee all
implementations, such as Channels or Sources, actually implement support
for the field. The shared `HTTPMessageSender.SendWithRetries()` logic has
been enhanced to support this feature, and all implementations using it to
perform retries will automatically benefit. Sandbox implementations not
based on this shared library, for example RabbitMQ or Google Pub/Sub, would
require additional development effort to respect the `retryAfterMax` field.
### DeliverySpec.Timeout field
**Flag name**: `delivery-timeout`
**Stage**: Alpha, disabled by default
**Tracking issue**: [#5148](https://github.com/knative/eventing/issues/5148)
**Persona**: Developer
When using the `delivery` spec to configure event delivery parameters, you can
use `timeout` field to specify the timeout for each sent HTTP request. The
duration of the `timeout` parameter is specified using the
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Times) format.
The following example shows a Subscription that retries sending an event 3
times, and on each retry the request timeout is 5 seconds:
```yaml
apiVersion: messaging.knative.dev/v1
kind: Subscription
metadata:
name: example-subscription
namespace: example-namespace
spec:
subscriber:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: example-sink
delivery:
backoffDelay: PT2S
backoffPolicy: linear
retry: 3
timeout: PT5S
```
You can specify a `delivery` spec for Channels, Subscriptions, Brokers,
Triggers, and any other resource spec that accepts the `delivery` field.
### Knative reference mapping
**Flag name**: `kreference-mapping`
**Stage**: Alpha, disabled by default
**Tracking issue**: [#5148](https://github.com/knative/eventing/issues/5593)
**Persona**: Administrator, Developer
When enabled, this feature allows you to provide mappings from a [Knative reference](https://github.com/knative/specs/blob/main/specs/eventing/overview.md#destination) to a templated URI.
!!! note
Currently only PingSource supports this experimental feature.
For example, you can directly reference non-addressable resources anywhere that Knative Eventing accepts a reference, such as for a PingSource sink, or a Trigger subscriber.
Mappings are defined by a cluster administrator in the `config-reference-mapping` ConfigMap.
The following example maps `JobDefinition` to a Job runner service:
{% raw %}
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: config-kreference-mapping
namespace: knative-eventing
data:
JobDefinition.v1.mygroup: "https://jobrunner.{{ .SystemNamespace }}.svc.cluster.local/{{ .Name }}"
```
{% endraw %}
The key must be of the form `<Kind>.<version>.<group>`. The value must resolved
to a valid URI. Currently, the following template data are supported:
- Name: The name of the referenced object
- Namespace: The namespace of the referenced object
- UID: The UID of the referenced object
- SystemNamespace: The namespace of where Knative Eventing is installed
Given the above mapping, the following example shows how you can directly reference
`JobDefinition` objects in a PingSource:
```yaml
apiVersion: sources.knative.dev/v1
kind: PingSource
metadata:
name: trigger-job-every-minute
spec:
schedule: "*/1 * * * *"
sink:
ref:
apiVersion: mygroup/v1
kind: JobDefinition
name: ajob
```
### Strict Subscriber
**Flag name**: `strict-subscriber`
**Stage**: Alpha, disabled by default
**Tracking issue**: [#5762](https://github.com/knative/eventing/pull/5762)
When defining a Subscription, if the `strict-subscriber` flag is enabled, validation fails if the field `spec.subscriber` is not defined. This flag was implemented to follow the latest version of the [Knative Eventing spec](https://github.com/knative/specs/tree/main/specs/eventing).
For example, the following Subscription will fail validation if the `strict-subscriber` flag is enabled:
```yaml
apiVersion: messaging.knative.dev/v1
kind: Subscription
metadata:
name: example-subscription
namespace: example-namespace
spec:
reply:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: example-reply
```
With the flag disabled (default behavior) the Subscription can define either a subscriber or a reply field, and validation will succeed. This is the default behavior in Knative v0.26 and earlier.

77
docs/eventing/experimental-features/README.md Normal file
View File

@ -0,0 +1,77 @@
# Eventing experimental features
To keep Knative innovative, the maintainers of this project have developed an
[experimental features process](https://github.com/knative/eventing/blob/main/docs/experimental-features.md)
that allows new, experimental features to be delivered and tested by users
without affecting the stability of the core project.
<!--TODO: Add note about HOW / where users can provide feedback, otherwise there's not much point mentioning that-->
!!! warning
Experimental features are unstable and may cause issues in your Knative setup or even your cluster setup.
These features should be used with caution, and should never be tested on a production environment. For more
information about quality guarantees for features at different stages of
development, see the
[Feature stage definition](https://github.com/knative/eventing/blob/main/docs/experimental-features.md#stage-definition)
documentation.
This document explains how to enable experimental features and which ones are
available today.
## Before you begin
You must have a Knative cluster running with Knative Eventing installed.
## Experimental features configuration
When you install Knative Eventing, the `config-features` ConfigMap is added to
your cluster in the `knative-eventing` namespace.
To enable a feature, you must add it to the `config-features` ConfigMap
under the `data` spec, and set the value for the feature to `enabled`. For
example, to enable a feature called `new-cool-feature`, you would add the
following ConfigMap entry:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: config-features
namespace: knative-eventing
labels:
eventing.knative.dev/release: devel
knative.dev/config-propagation: original
knative.dev/config-category: eventing
data:
new-cool-feature: enabled
```
To disable it, you can either remove the flag or set it to `disabled`:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: config-features
namespace: knative-eventing
labels:
eventing.knative.dev/release: devel
knative.dev/config-propagation: original
knative.dev/config-category: eventing
data:
new-cool-feature: disabled
```
## Available experimental features
The following table gives an overview of the available experimental features in
Knative Eventing:
| Feature | Flag | Description | Maturity |
| ------- | ---- | ----------- | -------- |
| [DeliverySpec.RetryAfterMax field](delivery-retryafter.md) | `delivery-retryafter` | Specify a maximum retry duration that overrides HTTP [Retry-After](https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3) headers when calculating backoff times for retrying **429** and **503** responses. | Alpha, disabled by default |
| [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. | Alpha, disabled 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. | Alpha, disabled by default |
| [Strict Subscriber](strict-subscriber.md) | `strict-subscriber` | Invalidates Subscriptions if the field `spec.subscriber` is not defined. | Alpha, disabled by default |

70
docs/eventing/experimental-features/delivery-retryafter.md Normal file
View File

@ -0,0 +1,70 @@
# DeliverySpec.RetryAfterMax field
**Flag name**: `delivery-retryafter`
**Stage**: Alpha, disabled by default
**Tracking issue**: [#5811](https://github.com/knative/eventing/issues/5811)
**Persona**: Developer
When using the `delivery` spec to configure event delivery parameters, you can
use the `retryAfterMax` field to specify how
HTTP [Retry-After](https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3)
headers are handled when calculating backoff times for retrying **429** and
**503** responses. You can specify a `delivery` spec for Channels,
Subscriptions, Brokers, Triggers, and any other resource spec that accepts the
`delivery` field.
The `retryAfterMax` field only takes effect if you configure the `delivery` spec
to perform retries, and only pertains to retry attempts on **429** and **503**
response codes. The field provides an override to prevent large **Retry-After**
durations from impacting throughput, and must be specified using
the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Times) format. The largest
of the normal backoff duration and the Retry-After header value will be used for
the subsequent retry attempt. Specifying a "zero" value of `PT0S` effectively
disables **Retry-After** support.
Prior to this experimental feature, Knative Eventing implementations have not
supported **Retry-After** headers, and this is an attempt to provide a path
for standardizing that support. To begin, the feature is **opt-in**, but the
final state will be **opt-out** as follows:
| Feature Stage | Feature Flag | retryAfterMax Field Absent | retryAfterMax Field Present |
| --- | --- | --- | --- |
| Alpha / Beta | Disabled | Accepted by Webhook Validation & Retry-After headers NOT enforced | Rejected by WebHook Validation |
| Alpha / Beta | Enabled | Accepted by Webhook Validation & Retry-After headers NOT enforced | Accepted by Webhook Validation & Retry-After headers enforced if max override > 0 |
| Stable / GA | n/a | Retry-After headers enforced without max override | Retry-After headers enforced if max override > 0 |
The following example shows a Subscription that retries sending an event three
times, and respects **Retry-After** headers while imposing a maximum backoff of
120 seconds:
```yaml
apiVersion: messaging.knative.dev/v1
kind: Subscription
metadata:
name: example-subscription
namespace: example-namespace
spec:
subscriber:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: example-sink
delivery:
backoffDelay: PT2S
backoffPolicy: linear
retry: 3
retryAfterMax: PT120S
```
!!! note
While the experimental feature flag enforces all DeliverySpec usage of the
`retryAfterMax` field through Webhook validation, it does not guarantee all
implementations, such as Channels or Sources, actually implement support
for the field. The shared `HTTPMessageSender.SendWithRetries()` logic has
been enhanced to support this feature, and all implementations using it to
perform retries will automatically benefit. Sandbox implementations not
based on this shared library, for example RabbitMQ or Google Pub/Sub, would
require additional development effort to respect the `retryAfterMax` field.

39
docs/eventing/experimental-features/delivery-timeout.md Normal file
View File

@ -0,0 +1,39 @@
# DeliverySpec.Timeout field
**Flag name**: `delivery-timeout`
**Stage**: Alpha, disabled by default
**Tracking issue**: [#5148](https://github.com/knative/eventing/issues/5148)
**Persona**: Developer
When using the `delivery` spec to configure event delivery parameters, you can
use `timeout` field to specify the timeout for each sent HTTP request. The
duration of the `timeout` parameter is specified using the
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Times) format.
The following example shows a Subscription that retries sending an event 3
times, and on each retry the request timeout is 5 seconds:
```yaml
apiVersion: messaging.knative.dev/v1
kind: Subscription
metadata:
name: example-subscription
namespace: example-namespace
spec:
subscriber:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: example-sink
delivery:
backoffDelay: PT2S
backoffPolicy: linear
retry: 3
timeout: PT5S
```
You can specify a `delivery` spec for Channels, Subscriptions, Brokers,
Triggers, and any other resource spec that accepts the `delivery` field.

37
docs/eventing/experimental-features/kreference-group.md Normal file
View File

@ -0,0 +1,37 @@
# KReference.Group field
**Flag name**: `kreference-group`
**Stage**: Alpha, disabled by default
**Tracking issue**: [#5086](https://github.com/knative/eventing/issues/5086)
**Persona**: Developer
When using the `KReference` type to refer to another Knative resource, you can
just specify the API `group` of the resource, instead of the full `APIVersion`.
For example, in order to refer to an `InMemoryChannel`, instead of the following
spec:
```yaml
apiVersion: messaging.knative.dev/v1
kind: InMemoryChannel
name: my-channel
```
You can use the following:
```yaml
group: messaging.knative.dev
kind: InMemoryChannel
name: my-channel
```
With this feature you can allow Knative to resolve the full `APIVersion` and
further upgrades, deprecations and removals of the referred CRD without
affecting existing resources.
!!! note
At the moment this feature is implemented only for
`Subscription.Spec.Subscriber.Ref` and `Subscription.Spec.Channel`.

64
docs/eventing/experimental-features/kreference-mapping.md Normal file
View File

@ -0,0 +1,64 @@
# Knative reference mapping
**Flag name**: `kreference-mapping`
**Stage**: Alpha, disabled by default
**Tracking issue**: [#5593](https://github.com/knative/eventing/issues/5593)
**Persona**: Administrator, Developer
When enabled, this feature allows you to provide mappings from
a [Knative reference](https://github.com/knative/specs/blob/main/specs/eventing/overview.md#destination)
to a templated URI.
!!! note
Currently only PingSource supports this experimental feature.
For example, you can directly reference non-addressable resources anywhere that
Knative Eventing accepts a reference, such as for a PingSource sink, or a
Trigger subscriber.
Mappings are defined by a cluster administrator in
the `config-reference-mapping` ConfigMap. The following example
maps `JobDefinition` to a Job runner service:
{% raw %}
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: config-kreference-mapping
namespace: knative-eventing
data:
JobDefinition.v1.mygroup: "https://jobrunner.{{ .SystemNamespace }}.svc.cluster.local/{{ .Name }}"
```
{% endraw %}
The key must be of the form `<Kind>.<version>.<group>`. The value must resolved
to a valid URI. Currently, the following template data are supported:
- Name: The name of the referenced object
- Namespace: The namespace of the referenced object
- UID: The UID of the referenced object
- SystemNamespace: The namespace of where Knative Eventing is installed
Given the above mapping, the following example shows how you can directly
reference
`JobDefinition` objects in a PingSource:
```yaml
apiVersion: sources.knative.dev/v1
kind: PingSource
metadata:
name: trigger-job-every-minute
spec:
schedule: "*/1 * * * *"
sink:
ref:
apiVersion: mygroup/v1
kind: JobDefinition
name: ajob
```

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

@ -0,0 +1,188 @@
# New trigger filters
**Flag name**: `new-trigger-filters`
**Stage**: Alpha, disabled by default
**Tracking issue**: [#5204](https://github.com/knative/eventing/issues/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`](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:
- 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.
```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 expessions 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 expession 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
```
### `sql`
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:
- 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.
```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:
- 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.

34
docs/eventing/experimental-features/strict-subscriber.md Normal file
View File

@ -0,0 +1,34 @@
# Strict Subscriber
**Flag name**: `strict-subscriber`
**Stage**: Alpha, disabled by default
**Tracking issue**: [#5762](https://github.com/knative/eventing/pull/5762)
When defining a Subscription, if the `strict-subscriber` flag is enabled,
validation fails if the field `spec.subscriber` is not defined. This flag was
implemented to follow the latest version of
the [Knative Eventing spec](https://github.com/knative/specs/tree/main/specs/eventing)
.
For example, the following Subscription will fail validation if
the `strict-subscriber` flag is enabled:
```yaml
apiVersion: messaging.knative.dev/v1
kind: Subscription
metadata:
name: example-subscription
namespace: example-namespace
spec:
reply:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: example-reply
```
With the flag disabled (default behavior) the Subscription can define either a
subscriber or a reply field, and validation will succeed. This is the default
behavior in Knative v0.26 and earlier.