DeliverySpec.BackoffMax Experimental Feature

docs/versioned/.nav.yml

@@ -296,6 +296,7 @@ nav:
           - Serving Features: serving/configuration/feature-flags.md
           - Eventing Features:
             - Configuring Features: eventing/features/README.md
+            - DeliverySpec.BackoffMax field: eventing/features/delivery-backoff-max.md
             - DeliverySpec.Timeout field: eventing/features/delivery-timeout.md
             - DeliverySpec.RetryAfterMax field: eventing/features/delivery-retryafter.md
             - New APIServerSource Filters: eventing/features/new-apiserversource-filters.md

docs/versioned/eventing/features/README.md

@@ -75,6 +75,7 @@ Knative Eventing:
 
 | Feature                                                       | Flag                          | Description                                                                                                                                                                                                        | Maturity                   |
 |---------------------------------------------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|
+| [DeliverySpec.BackoffMax field](delivery-backoff-max.md)      | `delivery-backoff-max`        | Limit the interval calculated from `backoffDelay` and `backoffPolicy` when retrying event delivery.                                                                                                                 | Alpha, disabled by default |
 | [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.                                                          | 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 |

docs/versioned/eventing/features/delivery-backoff-max.md

@@ -0,0 +1,89 @@
+---
+audience: developer
+components:
+  - eventing
+function: how-to
+---
+
+# DeliverySpec.BackoffMax field
+
+**Flag name**: `delivery-backoff-max`
+
+**Stage**: Alpha, disabled by default
+
+**Tracking issue**: [#9278](https://github.com/knative/eventing/issues/9278)
+
+**Persona**: Developer
+
+Use the `backoffMax` field to limit the time between delivery attempts when a
+subscriber is unavailable. You can specify a `delivery` spec for Channels,
+Subscriptions, Brokers, Triggers, and other resources that accept the
+`delivery` field.
+
+Without a maximum, an exponential backoff that starts at one second reaches an
+interval of approximately 12 days after 20 retries and 34 years after 30
+retries. A maximum lets you configure a large retry count without allowing the
+interval between attempts to grow beyond an operationally useful value.
+
+The following fields control different sources of retry delay:
+
+| Field | Controls | Example |
+| --- | --- | --- |
+| `backoffMax` | The interval calculated from `backoffDelay` and `backoffPolicy` | `PT10M` limits normal retry intervals to ten minutes |
+| [`retryAfterMax`](delivery-retryafter.md) | A delay requested by a subscriber through an HTTP `Retry-After` response header | `PT2M` limits a requested delay to two minutes |
+
+## Before you begin
+
+Before a developer can configure `backoffMax`, Knative Eventing must be
+installed, and a cluster operator must [enable the Eventing
+feature](README.md#features-configuration) by setting `delivery-backoff-max` to
+`enabled` in the `config-features` ConfigMap in the `knative-eventing`
+namespace.
+
+## Configure a maximum retry interval
+
+Set `backoffMax` to a positive
+[ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations). The
+maximum applies to both linear and exponential backoff policies.
+
+`backoffMax` affects retry timing only when the `delivery` spec also configures
+`retry`, `backoffDelay`, and `backoffPolicy`.
+
+The following Subscription retries delivery up to 100 times. Its exponential
+backoff starts at one second and stops growing when it reaches ten minutes:
+
+```yaml
+apiVersion: messaging.knative.dev/v1
+kind: Subscription
+metadata:
+  name: orders-to-processor
+  namespace: default
+spec:
+  channel:
+    apiVersion: messaging.knative.dev/v1
+    kind: InMemoryChannel
+    name: orders
+  subscriber:
+    ref:
+      apiVersion: v1
+      kind: Service
+      name: order-processor
+  delivery:
+    retry: 100
+    backoffPolicy: exponential
+    backoffDelay: PT1S
+    backoffMax: PT10M
+```
+
+In this example, the normal intervals begin at one second and increase
+exponentially. After an interval reaches ten minutes, later normal intervals do
+not exceed ten minutes.
+
+If you omit `backoffMax`, Knative Eventing continues to calculate retry
+intervals from `backoffDelay` and `backoffPolicy` without a configured maximum.
+
+!!! note
+    The feature flag controls whether the API accepts the `backoffMax` field. It
+    does not guarantee that every Channel, Broker, or Source implementation
+    supports the field. Check the documentation for the implementation that
+    delivers your events.