Kubernetes Gateway Traffic Splitting

Kubernetes Gateway Traffic Splitting refers to the capability, native to Gateway API's route resources, of distributing incoming requests matching a single rule across multiple backend destinations according to configured proportions, enabling progressive delivery patterns like canary releases and blue-green transitions without relying on external tooling or controller-specific extensions.

Mechanics of Weighted Distribution

Relative Weight Assignment

Traffic splitting works by assigning a numeric weight to each backend reference within a rule's backendRefs list, with the proportion of traffic each backend receives determined by its weight relative to the sum of all weights in that list, rather than requiring weights to represent absolute percentages.

Per-Request Distribution Behavior

The split is applied per new request or connection, with the controller's data plane selecting a backend according to the configured weight distribution at the time each request is routed, meaning the split is a statistical property observed over many requests rather than a guarantee for any individual small batch of traffic.

Progressive Delivery Patterns

Canary Release Progression

A typical canary pattern starts with a very small weight, often around one to five percent, directed to a new backend version, gradually increasing that share over a sequence of steps as monitoring confirms the new version behaves correctly, with the ability to immediately revert to zero weight if a problem is detected.

Blue-Green Cutover

A blue-green pattern instead uses traffic splitting as a discrete switch, moving from a fully weighted old backend to a fully weighted new backend in one step or a small number of large steps, favoring simplicity and fast rollback over the gradual exposure a canary pattern provides.

Automation Integration

Pipeline-Driven Weight Adjustment

Because manually editing weight values for every incremental step of a rollout is error-prone and slow, traffic splitting is commonly driven by progressive delivery automation tooling that adjusts weights based on observed metrics, automatically pausing or rolling back a rollout if error rates or latency for the new backend exceed defined thresholds.

Metric-Gated Progression

Effective automated traffic splitting requires reliable, low-latency metrics scoped specifically to the new backend's share of traffic, since conflating metrics across both backends during a split would mask problems specific to the newly introduced version.

Limitations and Considerations

No Native Session Affinity Guarantee

Standard weighted traffic splitting does not guarantee that a given client consistently reaches the same backend across multiple requests unless session affinity is separately configured, which matters for stateful interactions where inconsistent backend selection across a user's session could produce incorrect behavior.

Distinguishing From Header-Based Routing

Traffic splitting by weight is a distinct mechanism from routing based on request headers or cookies to deliberately target specific users to a specific backend version; the two approaches are often combined, using header-based rules to route internal testers to a new version deterministically while weighted splitting exposes it gradually to general traffic.

Rollback Behavior

Immediate Reversion Capability

Because traffic splitting is expressed declaratively through backend weights, rolling back a problematic rollout is as simple as setting the new backend's weight back to zero, taking effect as soon as the updated rule is reconciled by the controller, without requiring any change to the underlying application deployments themselves.