Configuring gradual rollout of traffic to Revisions

If your traffic configuration points to a Configuration target instead of a Revision target, when a new Revision is created and ready, 100% of the traffic from the target is immediately shifted to the new Revision.

This might make the request queue too long, either at the QP or Activator, and cause the requests to expire or be rejected by the QP.

Knative provides a rollout-duration parameter, which can be used to gradually shift traffic to the latest Revision, preventing requests from being queued or rejected. Affected Configuration targets are rolled out to 1% of traffic first, and then in equal incremental steps for the rest of the assigned traffic.

Note

rollout-duration is time-based, and does not interact with the autoscaling subsystem.

This feature is available for tagged and untagged traffic targets, configured for either Knative Services or Routes without a service.

Procedure

You can configure the rollout-duration parameter through the config-network ConfigMap, or the Operator's authoritative custom resource. This key is an integer number of seconds encoded as a string, not a duration string such as "380s"; see the v1.24 network configuration parser.

For Operator-managed Serving, inspect spec.config in the live resource and authoritative manifest before using the shortened network fragment below. If config-network exists, it wins even when empty; change that entry instead of adding a shadow network entry or deleting the full entry to bypass precedence. Use the ConfigMap mapping reference to select the entry, then the generic Serving Operator apply/verify workflow, inspecting active config-network.data.rollout-duration. Do not follow the separate domain example's guards. Matching configuration confirms propagation, not observed rollout behavior.

For YAML-managed Serving, merge the value into the authoritative config-network manifest through your existing workflow; do not directly edit an Operator-managed ConfigMap. Preserve unrelated values in either route.

ConfigMap configurationOperator configuration

apiVersion: v1
kind: ConfigMap
metadata:
 name: config-network
 namespace: knative-serving
data:
  rollout-duration: "380"  # Value in seconds.

apiVersion: operator.knative.dev/v1beta1
kind: KnativeServing
metadata:
  name: knative-serving
spec:
  config:
    network:
       rollout-duration: "380"

Route status updates

During a rollout, the system updates the Route and Knative Service status conditions. Both the traffic and conditions status parameters are affected.

For example, for the following traffic configuration:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
...
spec:
...
  traffic:
  - percent: 55
    configurationName: config # Pinned to latest ready Revision
  - percent: 45
    revisionName: config-00005 # Pinned to a specific Revision.

Initially 1% of the traffic is rolled out to the Revisions:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
...
spec:
...
  traffic:
  - percent: 54
    revisionName: config-00008
  - percent: 1
    revisionName: config-00009
  - percent: 45
    revisionName: config-00005 # Pinned to a specific Revision.

Then the rest of the traffic is rolled out in increments of 18%:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
...
spec:
...
  traffic:
  - percent: 36
    revisionName: config-00008
  - percent: 19
    revisionName: config-00009
  - percent: 45
    revisionName: config-00005 # Pinned to a specific Revision.

The rollout continues until the target traffic configuration is reached:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
...
spec:
...
  traffic:
  - percent: 55
    revisionName: config-00009
  - percent: 45
    revisionName: config-00005 # Pinned to a specific Revision.

During the rollout, the Route and Knative Service status conditions are as follows:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
...
spec:
...
status:
  conditions:
  ...
  - lastTransitionTime: "..."
    message: A gradual rollout of the latest revision(s) is in progress.
    reason: RolloutInProgress
    status: Unknown
    type: Ready

Multiple rollouts

If a new revision is created while a rollout is in progress, the system begins to shift traffic immediately to the newest Revision, and drains the incomplete rollouts from newest to oldest.