Learn Multigress - Traffic Policy & Load Balancing

#Introduction

Routing to a service isn't enough — you need to control how traffic flows. Episode 6 opens the traffic policy and load balancing toolbox of Multigress: splitting traffic with weights, setting retries and timeouts, protecting backends with circuit breakers, and using request mirroring to test without disturbing users.

By the end of this episode you'll be able to answer the classic platform engineer questions: how to send one percent of traffic to a new version, or how to protect a backend that's failing.

#Traffic Splitting and Weights

#The Concept of Weight on backendRefs

HTTPRoute supports multiple backendRefs at once, each with its own weight. The weight determines the traffic proportion:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
spec:
  parentRefs:
    - name: main-gateway
      namespace: multigress-system
  hostnames:
    - "api.example.com"
  rules:
    - backendRefs:
        - name: api-stable
          port: 8080
          weight: 90
        - name: api-canary
          port: 8080
          weight: 10

The configuration above sends 90 percent of traffic to api-stable and 10 percent to api-canary. The total weight determines the percentage; it doesn't have to add up to 100.

#Seeing the Proportion Practically

Test repeatedly to observe the distribution:

for i in $(seq 1 100); do
  curl -s http://localhost:8080/api | grep -o '"host":.*' | head -1
done | sort | uniq -c

Note: splitting is probabilistic, so the result of 100 attempts is close to 90:10, not exact. Don't use weights if you need a per-request guarantee — use header or cookie based rule matching instead.

#Retries, Timeouts, and Circuit Breakers

#BackendTrafficPolicy

Features like retries, timeouts, and circuit breakers don't exist in the standard HTTPRoute. Multigress provides them through the BackendTrafficPolicy CRD, which attaches to a route or backend service:

apiVersion: gateway.multigress.io/v1
kind: BackendTrafficPolicy
metadata:
  name: api-policy
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: api-route
  timeouts:
    request: 5s
    backendRequest: 3s
  retry:
    attempts: 3
    retryOn:
      - connect-failure
      - reset
      - 5xx

This policy caps a request at 5 seconds, retries up to 3 times when a connection fails, a connection is reset, or the backend replies with 5xx. The kubectl apply -f api-policy.yaml command applies the policy to your route.

#Circuit Breaker

A circuit breaker protects a backend from a flood of requests while it's failing:

apiVersion: gateway.multigress.io/v1
kind: BackendTrafficPolicy
metadata:
  name: api-circuit-breaker
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Service
      name: api
  circuitBreaker:
    maxConnections: 1000
    maxPendingRequests: 64
    maxRequests: 128
    maxRetries: 5

When the thresholds are exceeded, the proxy immediately rejects new requests without burdening the backend — the same pattern as circuit breakers in a service mesh. Once conditions recover, the traffic flow opens again automatically.

#Request Mirroring and Load Balancing Behavior

#Mirroring for Risk-Free Testing

Request mirroring sends a copy of a request to another service without changing the response to the client. It's perfect for testing a new version with real production traffic:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route-mirror
spec:
  parentRefs:
    - name: main-gateway
      namespace: multigress-system
  rules:
    - backendRefs:
        - name: api-stable
          port: 8080
      filters:
        - type: RequestMirror
          requestMirror:
            backendRef:
              name: api-shadow
              port: 8080

The client only interacts with api-stable; a copy of the request is quietly sent to api-shadow. Remember: mirroring must not be used for requests that write data — imagine the double effect on payment transactions.

#Load Balancing Algorithms

Multigress uses the least request algorithm by default: requests go to the backend with the fewest active connections. Other available options:

• round-robin: sequential rotation between backends.
• random: random selection, good for smoothing out the distribution.
• consistent-hash: requests with the same key always go to the same backend — important for session affinity.

apiVersion: gateway.multigress.io/v1
kind: BackendTrafficPolicy
metadata:
  name: api-lb-policy
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: api-route
  loadBalancing:
    algorithm: round-robin

#Closing

Episode 6 gives you full control over traffic flow: splitting with weights for canary, protecting backends with timeouts, retries, and circuit breakers, and testing new versions with request mirroring.

The key takeaways:

• backendRefs with weight splits traffic proportionally.
• BackendTrafficPolicy adds timeouts, retries, and circuit breakers.
• A circuit breaker quickly rejects requests when thresholds are exceeded.
• RequestMirror sends a copy to a shadow service without affecting clients.
• Least request is the default algorithm; round-robin and consistent-hash are available.

In the next episode 7 we'll introduce observability basics — enabling Multigress metrics and logs, integration with Prometheus and Grafana, and how to inspect route behavior and gateway health. Your traffic policy configuration will be tested with real data.