Migration overview

This page gives you an overview of the differences between theglobal external Application Load Balancer and classic Application Load Balancer, and a detailed overview of howyou can migrate your existing classic Application Load Balancer resources to theglobal external Application Load Balancer.

To take advantage of theadvanced trafficmanagement features ofthe global external Application Load Balancer, we recommend that you migrate yourclassic Application Load Balancer resources to the global external Application Load Balancer infrastructure.

Compare classic Application Load Balancers and global external Application Load Balancers

Before you migrate resources, understand the differences betweenclassic Application Load Balancers and global external Application Load Balancers.

Feature differences

The following features are not supported with the global external Application Load Balancer. Theyare only available with the classic Application Load Balancer:

Data plane differences

The following table highlights differences in the data plane between theclassic Application Load Balancer and the global external Application Load Balancer. These differencesaffect how the load balancers respond to some common events.

EventClassic Application Load Balancer responseGlobal external Application Load Balancer response
Status/error codes
All backends are unhealthyReturns HTTP 502Returns HTTP 503
Request uses a banned SSL cipherReturns HTTP 502Returns HTTP 503
Early upstream connection reset by the backendReturns HTTP 502Returns HTTP 503
Failed connection upgrade (for example, while upgrading to Websockets)Returns HTTP 400Returns HTTP 403
Header is too largeReturns HTTP 413Returns HTTP 431
Quotas and limits
URL map configurationThere are significant differences in the URL map configuration limits between the two load balancers. For details, see theQuotas: URL maps documentation.
Header handling
Request uses a custom HTTP method with no bodyAdds theTransfer Encoding: Chunked header to request sent to backendAdds theContent-Length: 0 header to request sent to backend
Format of theX-Forwarded-For header added to requests sent to backendUses ',' delimiter between IPsUses ',' delimiter between IPs (no space after the comma)
Header case preservationHeader case is preservedAll header keys are transformed to lowercase
Repeated headers with the same nameAllowedRepeated headers may be combined into a single header, with the values appended in order and comma separated, as allowed byRFC 7230.
(HTTP/1.1 only) Invalid header name (for example, unsupported characters in header)Allowed (for HTTP/1.1)Returns HTTP 502 (for HTTP/1.1)
(HTTP/1.1 only) Repeated (but same)Content-Length header in requestAllowed (for HTTP/1.1)Returns HTTP 502 (for HTTP/1.1)
(HTTP/1.1 only) Multiple hosts in headerWhen 2 or more hosts are added, and the first one is valid, the header is acceptedWhen 2 or more hosts are added, and any are invalid, the load balancer returns HTTP 502
(HTTP/1.1 only)Connection: Keep-Alive headerAdds theKeep-Alive header in requests sent to backend by defaultDoes not add this header by default
Request handling
Backwards slashes in requestURL left unchangedConverts to forward slash
Merge duplicate slashes in requestLeaves slashes unmergedMerges slashes
`#` in request pathAllowedReturns HTTP 400
(HTTP/1.1 only) Illegal characters in request path (for example, `\\x7f\\x7f`)Allowed (for HTTP/1.1)Returns HTTP 502 (for HTTP/1.1)
Traffic distribution (URL map configuration)
Client request includes a port numberThe port number is ignored even if you have configured hosts with ports in the URL map. Only the hostname is considered. For example, requests forexample.com:5000 are matched to the backend service forexample.com.Both the hostname and the port number are considered. For example, requests forexample.com:5000 are matched to the backend service forexample.com:5000. If there isn't a match, the default backend service is used.

Due to architectural differences, when migrating to the global external Application Load Balancer, you might see anincrease in the number of connections to your backends, especially when using the HTTP/1.1 protocol.This can lead to increased memory consumption on the backend instances. Monitor your backendresource usage during and after migration.

To learn more about the differences and supported features, seeLoad balancer feature comparison andApplication Load Balancer overview.

Migrate from classic to global external Application Load Balancer

To migrate to the global external Application Load Balancer, you change the load balancingscheme of your load balancing resources—specifically, the backend servicesand forwarding rules—fromEXTERNAL toEXTERNAL_MANAGED. To do this,you perform a series of migration steps where you can test partsof your network traffic with the new load balancing schemebefore actually finalizing the migration. During resource migration, youcontrol what percentage of requests is sent to either the classic Application Load Balancerinfrastructure or the global external Application Load Balancer infrastructure.

The following diagram shows the load balancing schemes of your load balancingresources before and after the migration.

Migration process for classic Application Load Balancer resources.
Migration process for classic Application Load Balancer resources (click to enlarge).

In the previous diagram, note the following:

  • Before resources are migrated, all requests use the classic Application Load Balancerinfrastructure.
  • While the resources are migrated, some requests are sent to theglobal external Application Load Balancer infrastructure and the remaining requests are sent tothe classic Application Load Balancer infrastructure.
  • After resources are migrated, all requests use the global external Application Load Balancerinfrastructure.

To help ensure a smooth transition, migrate the following classic Application Load Balancerresources in the specified order:

  1. Migrate all backend services attached to the load balancer's forwardingrules.

  2. Migrate all backend buckets attached to the load balancer's forwardingrules. You do this at the forwarding rule level because backendbuckets don't have load balancing schemes.

  3. Migrate the load balancer's forwarding rules.

    You can only migrate a forwarding rule after all the backend services andbackend buckets attached to the forwarding rule have already been migrated.

Migration states

You migrate resources by setting them to different states before changing theirload balancing scheme toEXTERNAL_MANAGED.

  1. PREPARE: set a resource to this state to prepare it for migration.
  2. TEST_BY_PERCENTAGE: to test a prepared resource, set the resource to thisstate to send a percentage of the network traffic. This stage isoptional.
  3. TEST_ALL_TRAFFIC: set a resource to this state to send allnetwork traffic to the resource through the global external Application Load Balancerinfrastructure instead of the classic Application Load Balancer infrastructure.
Note: After you change a resource's state fromPREPARE toTEST_BY_PERCENTAGEorTEST_ALL_TRAFFIC, wait for some time (approximately six minutes) for theresource to be ready to accept traffic. The resource must be in theTEST_ALL_TRAFFIC state before you change the load balancing scheme.

Migration process

To help ensure no downtime, you migrate resources in a specific orderfrom the classic Application Load Balancer infrastructure to the global external Application Load Balancerinfrastructure, and then change the load balancing scheme fromEXTERNAL toEXTERNAL_MANAGED to finalize the migration.

  1. Migrate the load balancer's backend services.

    Repeat the following steps for each backend service.

    1. Prepare the backend service for migration.

      Before any traffic can be sent through the global external Application Load Balancerinfrastructure, set the state of the backend service toPREPARE. Thisprepares the backend service to handle global external Application Load Balancer infrastructurenetwork traffic. A backend service takes some time (approximately six minutes)to be ready to send traffic through the global external Application Load Balancerinfrastructure.

    2. Optional: Test the prepared backend service.

      After the backend service is in thePREPARE state, set its state toTEST_BY_PERCENTAGE and set a percentage of the classic Application Load Balancernetwork traffic to the global external Application Load Balancer infrastructure.

      Though this stage is optional, we recommend that you test the traffic beforemigrating a backend service. Start with a small percentage value andmonitor logs of the resources. If the backend service behaves asexpected, gradually increase the percentage to 100%.

      In theTEST_BY_PERCENTAGE state, you can't use the additional capabilitiesof the global external Application Load Balancer infrastructure.

    3. Send all classic Application Load Balancer network traffic to the prepared backendservice.

      After the testing of the backend service is successful, set its state toTEST_ALL_TRAFFIC and send all classic Application Load Balancer network trafficto the prepared backend service. A backend service takes some time(approximately six minutes) to be ready to handle the network traffic.

      In theTEST_ALL_TRAFFIC state, you can't use the additional capabilitiesof the global external Application Load Balancer infrastructure.

    4. Change the load balancing scheme of migrated backend service toEXTERNAL_MANAGED.

      After testing your prepared backend service on theglobal external Application Load Balancer infrastructure, change its load balancing schemetoEXTERNAL_MANAGED. A backend service takes some time (approximatelysix minutes) to be fully migrated. After the load balancing scheme of thebackend service changes toEXTERNAL_MANAGED, you can use the advancedfeatures of the global external Application Load Balancer infrastructure.

  2. Migrate the load balancer's backend buckets. You do this at the forwardingrule level because backend buckets don't have load balancing schemes.

    Repeat the following steps for each bucket.

    1. Prepare the backend bucket for migration.

      Before any traffic can be sent through the global external Application Load Balancerinfrastructure, set the state of the backend bucket toPREPARE, andwait for some time (approximately six minutes).

    2. Optional: Test the prepared backend service.

      After the backend bucket is in thePREPARE state, set its state toTEST_BY_PERCENTAGE and set a percentage of the classic Application Load Balancernetwork traffic to the global external Application Load Balancer infrastructure.

    3. Send all classic Application Load Balancer network traffic to the prepared backendbucket.

      Set the state of the backend bucket toTEST_ALL_TRAFFIC and send allclassic Application Load Balancer network traffic to it. A backend bucket takessome time (approximately six minutes) to be ready to handle the networktraffic.

      In theTEST_ALL_TRAFFIC state, you can't use the additional capabilitiesof the global external Application Load Balancer infrastructure.

  3. Migrate the forwarding rules.

    For each forwarding rule, change the load balancing scheme of the forwardingrule toEXTERNAL_MANAGED, and wait for some time (approximately six minutes).After the load balancing scheme of the forwarding rule changes toEXTERNAL_MANAGED, you can use the advanced features of theglobal external Application Load Balancer infrastructure.

For a detailed step-by-step process, seeMigrate resources from classic Application Load Balancer.

The following diagram shows the classic Application Load Balancer resources in thedifferent states of migration.

Migration states of classic Application Load Balancer resources.
Migration states of classic Application Load Balancer resources (click to enlarge).

After migrating a resource, if you want to roll it back toclassic Application Load Balancer, change its load balancing scheme within 90 days of itsmigration. You can't roll back a resource after the 90-day window has passed.

Using session affinity

Consider the following caveats when migrating classic Application Load Balancer backendservices with session affinity:

  • Setting a value forTEST_BY_PERCENTAGE redirects some traffic targetingthe classic Application Load Balancer to the global external Application Load Balancer. This breaks theclient IPaffinity.Changing the migration percentage (for example, increasing it by 10%)breaks the session affinity for the same percentage of client IP addresses(10% in this example), until the affinity is re-established on thenext request.

  • Setting a value forTEST_BY_PERCENTAGE redirects that percentage oftraffic without asession cookieto the global external Application Load Balancer. It also redirects all traffic with a sessioncookie to the load balancer fleet that generated the cookie.

  • Setting a value forTEST_BY_PERCENTAGE to 0%, or leaving it unset, orsetting the backend service to thePREPARE state, invalidates all existingcookies that are directed to the global external Application Load Balancer.

  • Changing the load balancing scheme of the backend service toEXTERNAL_MANAGED invalidates all cookies generated by theclassic Application Load Balancer fleet. Thislets you roll back traffic if there's an issue with your application usingthe global external Application Load Balancer. For example, if a client presents a cookie fromthe classic Application Load Balancer fleet, but the backend service schemeisEXTERNAL_MANAGED, the client's cookie is not honored. Theglobal external Application Load Balancer ignores the cookie and creates a new one.

Roll back migrated resources

After migrating a resource, if you want to roll it back from theglobal external Application Load Balancer infrastructure to the classic Application Load Balancerinfrastructure, you can do so within 90 days of changing its load balancingscheme.

Rolling back a backend service to theEXTERNAL schemerequires rolling back the forwarding rule. Rolling back a forwarding rule to theEXTERNAL scheme doesn't require rolling back the backend services.

To roll back resources, follow these steps:

  1. Remove any new advanced traffic management features of global external Application Load Balancerconfigured on the resource.

  2. Roll back the forwarding rules.

    Change the load balancing scheme of forwarding rules fromEXTERNAL_MANAGEDtoEXTERNAL.

  3. Roll back the backend buckets.

    1. Set the migration state of backend buckets toTEST_ALL_TRAFFIC, andwait for some time (approximately six minutes).
    2. Optional: To decrease the traffic, set the migration state of backendbuckets toTEST_BY_PERCENTAGE and set a percentage of the traffic.
    3. Set the migration state of backend buckets toPREPARE.
    4. Revert backend buckets to their pre-migration states.

  4. Roll back the backend services.

    1. Set the migration state of backend services toTEST_ALL_TRAFFIC, andwait for some time (approximately six minutes).
    2. Optional: To decrease the traffic, set the migration state of backendservices toTEST_BY_PERCENTAGE and set a percentage of the traffic.
    3. Set the migration state of backend services toPREPARE.
    4. Revert backend services to their pre-migration states.

For a detailed step-by-step process, seeRoll back migrated resources toclassic Application Load Balancer.

Track your migration process

While migrating your resources, you can check their load balancing schemes by viewing the following:

  • The logging and monitoring dashboards of the global external Application Load Balancer. For moreinformation, seeGlobal external Application Load Balancer logging andmonitoring.

  • The values of the following HTTP request and response headers:

    • X-External-Managed-Migration-Scheme-Override: this request headerroutes the request based on its value. If the header value isEXTERNAL, it directs the request to the classic Application Load Balancerinfrastructure. If the value isEXTERNAL_MANAGED, it routes therequest through the global external Application Load Balancer infrastructure.

      Use this header to direct a request to a particular load balancer fleet.

    • X-External-Managed-Migration-Selected-Scheme: this request andresponse header informs the backend and the client about the loadbalancing scheme used to route the request. The header is returned tothe client and passed to the customer's backend.

      If the request is routed through the classic Application Load Balancer infrastructure,its value isEXTERNAL. If the request is routed through theglobal external Application Load Balancer infrastructure, its value isEXTERNAL_MANAGED.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.