This document shows examples of using traffic management for some specific usecases. Many other use cases are possible.

The document contains examples for the following load balancers:

• Regional external Application Load Balancer
• Regional internal Application Load Balancer
• Cross-region internal Application Load Balancer

Regional external Application Load Balancer versus regional internal Application Load Balancer. For theregional load balancers' traffic management configuration, theregional URL map API and theregional backend service API documentation provides a full list of fields,including semantics regarding relationships, restrictions, and cardinality.

The onlydifference between these two load balancers is the load balancing scheme, asfollows:

• Regional external Application Load Balancers useEXTERNAL_MANAGED.
• Regional internal Application Load Balancers useINTERNAL_MANAGED.

Regional internal Application Load Balancer versus cross-region internal Application Load Balancer. For thetraffic management configuration:

• Regional internal Application Load Balancers use theregional URL map API, and theregional backend service API documentation provides a full list of fields,including semantics regarding relationships, restrictions, and cardinality.

• Cross-region internal Application Load Balancers useglobal URL map API, andglobal backend service API documentation provides a full list of fields,including semantics regarding relationships, restrictions, and cardinality.

In addition to the advanced routing features described on this page,supported Application Load Balancersintegrate with Service Extensions to let youinsert custom logicinto the load balancing data path.

Before you begin

Make sure that you understand how traffic management works.For more information, readTraffic managementoverview for regional external Application Load Balancers.

Configure traffic management

Within your chosen configuration environment,you set up traffic management by using YAML configurations. A URL map and abackend service each has its own YAML file. Depending on your desiredfunctionality, you need to write either a URL map YAML file, a backend serviceYAML file, or both.

For help writing these YAML files, you can use the examples on this pageand the Cloud Load Balancing API documentation.

For regional internal Application Load Balancers and regional external Application Load Balancers, theregional URL map API and theregional backend service API documentation provides a full list of fields,including semantics regarding relationships, restrictions, and cardinality.

Map traffic to a single service

Send all traffic to a single service. Make sure to replace the placeholders.

defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1hostRules:-hosts:-'*'pathMatcher:matcher1name:URL_MAP_NAMEpathMatchers:-defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1name:matcher1routeRules:-matchRules:-prefixMatch:/PREFIXpriority:1routeAction:weightedBackendServices:-backendService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1weight:100

Split traffic between two services

Split traffic between two or among multiple services. Make sure to replace theplaceholders.

defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1hostRules:-hosts:-'*'pathMatcher:matcher1name:URL_MAP_NAMEpathMatchers:-defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1name:matcher1routeRules:-matchRules:-prefixMatch:/PREFIXpriority:2routeAction:weightedBackendServices:-backendService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1weight:95-backendService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_2weight:5

Configure a URL redirect

The following example returns a configurable 3xx response code. The example alsosets theLocation response header with the appropriate URI, replacing the hostand path as specified in the redirect action.

defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1name:URL_MAP_NAMEhostRules:-hosts:-"HOSTTOREDIRECTFROM"# Use * for all hostspathMatcher:matcher1pathMatchers:-defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1name:matcher1defaultUrlRedirect:hostRedirect:"HOSTTOREDIRECTTO"# Omit to keep the requested hostpathRedirect:"PATHTOREDIRECTTO"# Omit to keep the requested pathredirectResponseCode:MOVED_PERMANENTLY_DEFAULTstripQuery:True

Mirror traffic

In addition to forwarding the request to the selected backend service, you cansend an identical request to the configured mirror backend service on afireand forget basis. This means that the load balancer doesn't wait for a responsefrom the backend to which it sends the mirrored request. Request mirroring isuseful for testing a new version of a backend service. You can also use it todebug production errors on a debug version of your backend service, rather thanon the production version.

By default, the mirrored backend service receivesall requests, even if theoriginal traffic is being split between multiple weighted backend services. Youcan configure the mirrored backend service to receive only a percentage of therequests by using the optionalmirrorPercent flag to specify the percentage ofrequests to be mirrored expressed as a value between 0 and 100.0.

defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1name:regional-lb-mapregion:region/REGIONhostRules:-hosts:-'*'pathMatcher:matcher1pathMatchers:-defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1name:matcher1routeRules:-matchRules:-prefixMatch:/PREFIXpriority:1routeAction:weightedBackendServices:-backendService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1weight:100requestMirrorPolicy:backendService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_2mirrorPercent:50.0

Note the following limitations when using traffic mirroring:

• Traffic mirroring is supported when both backend services have managed instance groups, zonal NEGs, or hybrid NEGs backends. It is not supported for internet NEGs, serverless NEGs, and Private Service Connect backends.
• Requests to the mirrored backend service do not generate any logs or metrics for Cloud Logging and Cloud Monitoring.

Rewrite the requested URL

Rewrite the hostname portion of the URL, the path portion of the URL, orboth, before sending a request to the selected backend service. Make sureto replace the placeholders.

defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1name:regional-lb-mapregion:region/REGIONhostRules:-hosts:-'*'pathMatcher:matcher1pathMatchers:-defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1name:matcher1routeRules:-matchRules:-prefixMatch:/PREFIXpriority:PRIORITY# 0 is highestrouteAction:weightedBackendServices:-backendService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1weight:100urlRewrite:hostRewrite:"new-host-name.com"# Omit to keep the requested hostpathPrefixRewrite:"/new-path/"# Omit to keep the requested path

Note: ThepathPrefixRewrite route action is best suited for use withprefixMatch rules where it can effectively modify the matched prefix only. We don't recommend usingfullPathMatch rules withpathPrefixRewrite.

Retry a request

Configure the conditions under which the load balancer retries failedrequests, how long the load balancer waits before retrying, and themaximum number of retries permitted.

defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1name:regional-lb-mapregion:region/REGIONhostRules:-hosts:-'*'pathMatcher:matcher1pathMatchers:-defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1name:matcher1routeRules:-matchRules:-prefixMatch:/PREFIXpriority:PRIORITY# 0 is highestrouteAction:weightedBackendServices:-backendService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1weight:100retryPolicy:retryConditions:502, 504numRetries:3perTryTimeout:seconds:1nanos:500000000

defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1name:regional-lb-mapregion:region/REGIONhostRules:-hosts:-'*'pathMatcher:matcher1pathMatchers:-defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1name:matcher1routeRules:-matchRules:-prefixMatch:/PREFIXpriority:PRIORITY# 0 is highestrouteAction:weightedBackendServices:-backendService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1weight:100timeout:seconds:30nanos:500000000

defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1name:regional-lb-mapregion:region/REGIONhostRules:-hosts:-'*'pathMatcher:matcher1pathMatchers:-defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1name:matcher1routeRules:-matchRules:-prefixMatch:/PREFIXpriority:PRIORITY# 0 is highestrouteAction:weightedBackendServices:-backendService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1weight:100faultInjectionPolicy:delay:fixedDelay:seconds:10nanos:500000000percentage:25abort:httpStatus:503percentage:50

defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1name:regional-lb-mapregion:region/REGIONhostRules:-hosts:-'*'pathMatcher:matcher1pathMatchers:-defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1name:matcher1routeRules:-matchRules:-prefixMatch:/PREFIXpriority:PRIORITY# 0 is highestrouteAction:weightedBackendServices:-backendService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1weight:100corsPolicy:allowOrigins:my-domain.comallowMethods:GET, POSTallowHeaders:Authorization, Content-TypemaxAge:1200allowCredentials:True

Regional external Application Load Balancers and internal Application Load Balancers also support the use ofvariables in custom headers. You can specify one or more variables in the customheader value (headerValue) fields that are then translated to theircorresponding per-request values. For a list of supported header values, seeCreate custom headers in URLmaps.

defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1name:regional-lb-mapregion:region/REGIONhostRules:-hosts:-'*'pathMatcher:matcher1pathMatchers:-defaultService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1name:matcher1routeRules:-matchRules:-prefixMatch:/PREFIXpriority:PRIORITY# 0 is highestrouteAction:weightedBackendServices:-backendService:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1weight:100headerAction:requestHeadersToAdd:-headerName:header-1-nameheaderValue:header-1-valuereplace:TruerequestHeadersToRemove:-header-2-name-header-3-nameresponseHeadersToAdd:-headerName:header-4-nameheaderValue:header-4-valuereplace:TrueresponseHeadersToRemove:-header-5-name-header-6-name

Configure outlier detection

Specify the criteria for eviction of unhealthy backend VMs or endpoints inNEGs, along with criteria defining when a backend or endpoint isconsidered healthy enough to receive traffic again. Make sure to replacethe placeholders.

loadBalancingScheme:LOAD_BALANCING_SCHEMElocalityLbPolicy:RANDOMname:projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1outlierDetection:baseEjectionTime:nanos:0seconds:'30'consecutiveErrors:5consecutiveGatewayFailure:3enforcingConsecutiveErrors:2enforcingConsecutiveGatewayFailure:100enforcingSuccessRate:100interval:nanos:0seconds:'1'maxEjectionPercent:50successRateMinimumHosts:5successRateRequestVolume:100successRateStdevFactor:1900region:region/REGION

Configure circuit breaking

Circuit breaking lets you set failure thresholds to prevent client requestsfrom overloading your backends. After requests reach a limit that you've set,the load balancer stops allowing new connections or sending additionalrequests, giving your backends time to recover. Thus, circuit breakingprevents cascading failures by returning an error to the client rather thanoverloading a backend. This allows some traffic to be served while providingtime for managing the overload situation, such as handling a traffic spikeby increasing capacity through autoscaling.

Set upper limits on requests per connection as well as the volume ofconnections to a backend service. Also limit the number of pending requestsand retries.

loadBalancingScheme:LOAD_BALANCING_SCHEME# EXTERNAL_MANAGED or INTERNAL_MANAGEDlocalityLbPolicy:RANDOMaffinityCookieTtlSec:0backends:-balancingMode:UTILIZATIONcapacityScaler:1.0group:region/REGION/instanceGroups/INSTANCE_GROUPmaxUtilization:0.8circuitBreakers:maxConnections:1000maxPendingRequests:200maxRequests:1000maxRequestsPerConnection:100maxRetries:3connectionDraining:drainingTimeoutSec:0healthChecks:-region/REGION/healthChecks/HEALTH_CHECK

Set up traffic splitting: detailed steps

This example demonstrates the following steps:

1. Create distinct templates for different services.

2. Create instance groups for those templates.

3. Create routing rules that set up 95% / 5% traffic splitting.

4. Send curl commands showing that the traffic split percentages roughly matchthe configuration.

These instructions assume the following:

• The region isus-west1.

• A target proxy and forwarding rule have been created, along with a URL mapnamedregional-lb-map.

• The URL map sends all traffic to one backend service, calledred-service,which is the default backend service.

• You set up an alternate path that sends 5% of the traffic toblue-serviceand 95% of traffic togreen-service.

• A path matcher is used.

• You are usingCloud Shell or another environment with bashinstalled.

Define the services

The following bash function creates a backend service, including theinstance template and the managed instance group.

function make_service() {  local name="$1"  local region="$2"  local zone="$3"  local network="$4"  local subnet="$5"  local subdir="$6"  www_dir="/var/www/html/$subdir"  (set -x; \  gcloud compute instance-templates create "${name}-template" \    --region="$region" \    --network="$network" \    --subnet="$subnet" \    --tags=allow-ssh,load-balanced-backend \    --image-family=debian-12 \    --image-project=debian-cloud \    --metadata=startup-script="#! /bin/bash  apt-get update  apt-get install apache2 -y  a2ensite default-ssl  a2enmod ssl  sudo mkdir -p $www_dir  /bin/hostname | sudo tee ${www_dir}index.html  systemctl restart apache2"; \  gcloud compute instance-groups managed create \    "${name}-instance-group" \    --zone="$zone" \    --size=2 \    --template="${name}-template"; \  gcloud compute backend-services create "${name}-service" \    --load-balancing-scheme=LOAD_BALANCING_SCHEME\    --protocol=HTTP \    --health-checks=regional-lb-basic-check \    --health-checks-region="$region" \    --region="$region"; \  gcloud compute backend-services add-backend "${name}-service" \    --balancing-mode='UTILIZATION' \    --instance-group="${name}-instance-group" \    --instance-group-zone="$zone" \    --region="$region")}

Create the services

Call the function to make three services,red,green, andblue. Thered service acts as the default service for requests to/. Thegreen andblue services are both set up on/PREFIX to handle 95% and 5% of the traffic, respectively.

make_service red us-west1 us-west1-a lb-network backend-subnet ""make_service green us-west1 us-west1-a lb-network backend-subnet /PREFIXmake_service blue us-west1 us-west1-a lb-network backend-subnet /PREFIX

Create the URL map

Test the configuration

To test the configuration, first ensure that requests to theload balancer's IP address set up earlier are handled by the defaultredconfiguration.

Then check to make sure that requests sent toFORWARDING_RULE_IP_ADDRESS/PREFIX are split as expected.

Set up session affinity based onHTTP_COOKIE

Traffic control enables you to configure session affinity based on a providedcookie. To configure HTTP_COOKIE based session affinity for a backend servicenamedred-service, follow these directions.

1. Use thegcloud compute backend-servicesexport command toget the backend service configuration.

   gcloud compute backend-services export red-service \    --destination=red-service-config.yaml \    --region=us-west1

2. Update thered-service-config.yaml file as follows:

   sessionAffinity:'HTTP_COOKIE'localityLbPolicy:'RING_HASH'consistentHash:httpCookie:name:'http_cookie'path:'/cookie_path'ttl:seconds:100nanos:500000000minimumRingSize:10000

3. In thered-service-config.yaml file, delete the following line:

   sessionAffinity: NONE

4. Update the backend service configuration file:

   gcloud compute backend-services import red-service \    --source=red-service-config.yaml \    --region=us-west1

Troubleshooting

Use this information for troubleshooting when traffic is not being routedaccording to the route rules and traffic policies that you configured.

Symptoms:

• Increased traffic to services in rules above the rule in question.
• An unexpected increase in 4xx and 5xx HTTP responses for a given route rule.

Solution: Check the order of your route rules. Route rules are interpreted inthe order in which they are specified.

Route rules within a URL map are interpreted in the order in which they arespecified. This is different from the way that path rules are interpreted bylongest prefix match. For a path rule, internal Application Load Balancers will onlyselect a single path rule; however, when you use route rules, more than onemight apply.

When you define route rules, check to be sure that rules at the top of the listdo not inadvertently route traffic that would otherwise have been routed by asubsequent route rule. The service that receives misdirected traffic wouldlikely reject requests, and the service in your route ruleswould receive reduced traffic or no traffic at all.

What's next

• Clean up the load balancer setup.