Traffic Splitting

How to split traffic between App Engine versions for A/B testing, canary deployments, and gradual rollouts.

What is Traffic Splitting?

Traffic splitting distributes a percentage of incoming requests across two or more versions of a service. Instead of sending all traffic to a single version, you control exactly what proportion goes where.

Common use cases

Use Case	Description
Canary deployment	Send 5% of traffic to a new version, monitor, then increase
A/B testing	Split traffic 50/50 to compare two feature implementations
Gradual rollout	Incrementally shift from old to new version (10% → 50% → 100%)
Instant rollback	Route all traffic back to the previous version if issues arise

Key Insight: Traffic splitting operates at the version level within a single service. You can’t split traffic between services — that’s handled by dispatch.yaml.

Splitting Methods

App Engine supports two methods for determining which version receives a request:

IP Address Splitting

Hashes the sender’s IP address to a value between 0-999. Each version is assigned a range of values proportional to its traffic percentage.

gcloud app services set-traffic default \
  --splits v1=0.8,v2=0.2 \
  --split-by ip

Pros:

Simple to set up
Same user generally sees the same version (IP is “reasonably sticky”)

Cons:

Mobile users shift IPs frequently — they may see different versions across requests
Actual split percentages may differ from target (converges with more traffic)
Internal Google Cloud requests originate from a small number of IPs — all may route to the same version
Not recommended for inter-service communication

Uses an HTTP cookie named GOOGAPPUID with a value between 0-999. The cookie is created automatically if it doesn’t exist.

gcloud app services set-traffic default \
  --splits v1=0.8,v2=0.2 \
  --split-by cookie

Pros:

More precise — traffic routing accuracy approaches 0.1% of target
Users always see the same version (cookie persists across requests)
Better for A/B testing where consistency matters

Cons:

Mobile/desktop clients that don’t persist cookies will get inconsistent routing
Internal requests require forwarding the user’s cookie
You cannot predict which version a specific cookie value maps to

Tip: Use cookie splitting for A/B testing and canary deployments where you want users to consistently see the same version. Use IP splitting for simpler setups where perfect consistency isn’t critical.

Configuration

Via gcloud CLI

# 80/20 split using cookies
gcloud app services set-traffic default \
  --splits v1=0.8,v2=0.2 \
  --split-by cookie
 
# 50/25/25 split across three versions
gcloud app services set-traffic my-service \
  --splits v1=0.5,v2=0.25,v3=0.25 \
  --split-by ip
 
# Route all traffic to a single version (disables splitting)
gcloud app services set-traffic default --splits v2=1

Split percentages

All split values must sum to 1.0 (100%)
Values can be decimals: v1=0.95,v2=0.05
You can split across 2 or more versions
Only versions that exist can receive traffic

Via Console

Go to App Engine > Versions in the Google Cloud Console
Select the versions you want to split traffic between
Click Split traffic
Choose the splitting method (IP or Cookie)
Enter the percentage for each version
Click Save

Gradual Rollout Example

A step-by-step canary deployment using traffic splitting:

# Step 1: Deploy new version without traffic
gcloud app deploy --no-promote --version v2
 
# Step 2: Send 5% to v2
gcloud app services set-traffic default \
  --splits v1=0.95,v2=0.05 \
  --split-by cookie
 
# Step 3: Monitor. If OK, increase to 25%
gcloud app services set-traffic default \
  --splits v1=0.75,v2=0.25 \
  --split-by cookie
 
# Step 4: Monitor. If OK, go to 50%
gcloud app services set-traffic default \
  --splits v1=0.5,v2=0.5 \
  --split-by cookie
 
# Step 5: Full rollout
gcloud app services set-traffic default --splits v2=1
 
# Step 6: Delete old version
gcloud app versions delete v1 --service=default

If something goes wrong

# Instant rollback — all traffic back to v1
gcloud app services set-traffic default --splits v1=1

Caching Gotchas

When splitting traffic, cached resources can cause inconsistent behavior:

Problem	Cause	Solution
Old CSS/JS served to v2 users	Browser caches assets from v1	Change static asset URLs between versions
Different HTML, same assets	Cached resources don’t match new version	Set `Cache-Control` and `Expires` headers appropriately
Cookie-based splitting + CDN	CDN ignores cookies	Use `Vary: Cookie` header (increases cache burden)

Warning: Pay attention to caching when splitting traffic. A user assigned to v2 might still see v1’s cached CSS/JS. Use cache-busting techniques for static assets (e.g., append a version hash to filenames).