How Requests are Routed

Region ID

The REGION_ID is a code that Google assigns based on the region you select when you create your app. Including REGION_ID.r in App Engine URLs is optional for existing apps and will soon be required for all new apps.

To ensure a smooth transition, we are slowly updating App Engine to use region IDs. If we haven't updated your Google Cloud project yet, you won't see a region ID for your app. Since the ID is optional for existing apps, you don't need to update URLs or make other changes once the region ID is available for your existing apps.

Learn more about region IDs.

OK

Python 2.7/3.7 |Java 8/11 |PHP 5/7 |Ruby |Go 1.11/1.12+ |Node.js

This page describes how HTTP requests from users reach the appropriate version of a service. Requests can be routed two ways:

• App Engine's default routing rules apply to requests with a URL that ends at the domain level.

• Alternatively, you can use a dispatch file that routes specific URL patterns according to your own rules.

If you test your app using the local development server, the available routing and dispatch features are slightly different. To programmatically create URLs that work with both production and development servers, use the get_hostname method.

See routing in the development server to learn more.

Requests and domains

Once your app is running in App Engine, you can use the following URL to send HTTP requests to the app:
https://PROJECT_ID.REGION_ID.r.appspot.com

where PROJECT_ID is the ID of the Google Cloud project that contains the app.

This URL sends requests to the version of your app that you have configured to receive traffic.

Each version of your app also has its own URL, so you can deploy and test a new version before configuring that version to receive traffic. The version-specific URL uses the ID of a specific version in addition to the project ID, region ID, and appspot.com domain name. For example: https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com.

Note: We recommend using the HTTPS protocol to send requests to your app. HTTPS requests sent to the REGION_ID.r.appspot.com must use the string "-dot-" to separate subdomains instead of ".". You can use the simple "." URL notation with your own custom domains and with HTTP requests.

Subdomains

The appspot.com domains also support subdomains of the form SUBDOMAIN-dot-PROJECT_ID.REGION_ID.r.appspot.com, where SUBDOMAIN can be any string allowed in one part of a domain name, excluding the . character. Requests that are sent to any subdomain in this way are routed to your app.

You can also use subdomains with a version-specific URL:
https://SUBDOMAIN-dot-VERSION_ID-dot-PROJECT_ID.REGION_ID.r.appspot.com.

See Routing via URL for more information and examples.

Custom domains

You can set up a custom top-level domain using G Suite and then assign subdomains to various apps, such as Google Mail or Sites. You can also associate an App Engine app with a subdomain. For more information about mapping a custom domain to your app, see Securing Custom Domains with SSL.

Domain name is included in the request data

The domain name used for the request is included in the request data that is passed to your app. Therefore, you can use the request data to control how your app responds based on the domain name in the request. For example, if you want to redirect to an official domain, you can code your app to check the Host request header and then respond accordingly based on the domain name.

Region ID

The REGION_ID is a code that Google assigns based on the region you select when you create your app. Including REGION_ID.r in App Engine URLs is optional for existing apps and will soon be required for all new apps.

To ensure a smooth transition, we are slowly updating App Engine to use region IDs. If we haven't updated your Google Cloud project yet, you won't see a region ID for your app. Since the ID is optional for existing apps, you don't need to update URLs or make other changes once the region ID is available for your existing apps.

You can use the following tools to see the region ID of your app:

Console

In the Cloud Console, you can view the URLs for your app's Instances, Services, and Versions.

All of these URLs include the region ID.

gcloud

When you deploy an app or service, the gcloud app deploy command displays the URL after the deployment succeeds. This URL includes the region ID.

To view the URL for a service that is already deployed:

1. Enter the gcloud app versions list command to list the versions of a specific service. For example, to list the versions of the default service, enter gcloud app versions list --service=default.

2. Enter the gcloud app versions describe command. The output of that command includes the version URL with the app's region ID. For example, to describe version 20191023t101741 for the default service, enter gcloud app versions describe 20191023t101741 --service=default

Routing via URL

You can target an HTTP request with varying degrees of specificity. In the following examples, REGION_ID.r.appspot.com can be replaced with your app's custom domain if you have one. The URL substrings VERSION_ID, SERVICE_ID, and PROJECT_ID, each represent the resource IDs of your app.

You can use the following tools to retrieve the IDs of your app's resources:

Console

In the Cloud Console, you can view the corresponding Instances, Services, and Versions pages.

gcloud

Run the gcloud app instances list command to list the resource IDs within a specific Cloud project.

API

To programmatically retrieve resource IDs, see the list methods in the Admin API.

Default routing

The following URL patterns have a default routing behavior. Note that the default routing is overridden if there is a matching pattern that you have defined in your dispatch file:

• Sends the request to an available instance of the default service:

  
  https://PROJECT_ID.REGION_ID.r.appspot.com
  https://CUSTOM_DOMAIN

  Requests are received by any version that is configured for traffic in the default service.

• Sends a request to an available instance of a specific service:

  
  https://SERVICE_ID-dot-PROJECT_ID.REGION_ID.r.appspot.com
  https://SERVICE_ID.CUSTOM_DOMAIN

  Requests are received by any version that is configured for traffic in the targeted service. If the service that you are targeting does not exist, the request gets soft routed.

• Sends a request to an available instance of a specific version in the

  default service:

  
  https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com
  https://VERSION_ID.CUSTOM_DOMAIN

  When a service is not targeted, requests are sent to the default service.

Soft routing

If a request matches the PROJECT_ID.REGION_ID.r.appspot.com portion of the hostname, but includes a service, version, or instance name that does not exist, then the request is routed to the default service. Soft routing does not apply to custom domains; requests to them will return a HTTP 404 status code if the hostname is invalid.

Targeted routing

The following URL patterns are guaranteed to reach their target, if they exist. These requests are never intercepted and rerouted by the patterns that you have defined in your dispatch file:

• Sends the request to an available instance of a specific service and version:

  
  https://VERSION_ID-dot-SERVICE_ID-dot-PROJECT_ID.REGION_ID.r.appspot.com
  https://VERSION_ID.SERVICE_ID.PROJECT_ID.CUSTOM_DOMAIN

• If you are using manually-scaled services, you can target and send a request to a instance by including the instance ID. The instance ID is an integer in the range from 0 up to the total number of instances that are running, and can be specified as follows:

  Sends a request to a specific service and version within a specific instance:

  https://INSTANCE_ID-dot-VERSION_ID-dot-SERVICE_ID-dot-PROJECT_ID.REGION_ID.r.appspot.com
  https://INSTANCE_ID.VERSION_ID.SERVICE_ID.CUSTOM_DOMAIN

  Note: Targeting an instance is not supported in services that are configured for auto scaling or basic scaling. The instance ID must be an integer in the range from 0, up to the total number of instances running. Regardless of your scaling type or instance class, it is not possible to send a request to a specific instance without targeting a service or version within that instance.

Default service

The default service is created when you deploy the initial version of your app to App Engine. Requests that specify no service or an invalid service are routed to the default service. Those requests are then handled by the versions that you have configured to receive traffic within the default service. You can see which versions are configured for traffic in the Versions page of the Cloud Console.

Restricting access to a service

All services are public by default. If you want to restrict access to a service, add the login: admin element to its handlers.

Example

To help demonstrate the URL patterns, assume an example Cloud project with ID requestsProject exists and includes an app that is running two services and versions. The example app's default service includes version vFrontend, and the second service service2, includes version vBackend. Google has assigned uc as the region ID for both apps.

To target specific services and versions, you can use the following URL patterns:

1. To target the version in the default service using HTTPS, you can use:

       https://vFrontend-dot-default-dot-requestsProject.uc.r.appspot.com
       https://vFrontend-dot-requestsProject.uc.r.appspot.com
   

2. To target the vBackend version using a custom domain, you can use:

   https://vBackend.service2.example.net
   https://vBackend.example.net
   

   where requestsProject.uc.r.appspot.com is mapped to the example.net domain.

Routing with a dispatch file

For URLs that use the patterns described earlier, you can create a dispatch file to override App Engine's routing rules and define your own custom routing rules. With a dispatch file, you can send incoming requests to a specific service based on the path or host name in the request URL.

For details about creating a dispatch file, see the dispatch.yaml reference.

Notes:

• The rules that you define in your dispatch file must use HTTP URL patterns that include the "." notation for separating subdomains. URLs defined with the HTTPS "-dot-" notation are not supported.
• Dispatch rules also apply to the URLs that you define in your cron file.

Creating a dispatch file

The dispatch file should be placed either in the root of your project directory, or in the root directory of your default service. You can define up to 20 routing rules in the dispatch file and each rule consists of both the service and url elements.

For example, you can create a dispatch file to route mobile requests like https://simple-sample.uc.r.appspot.com/mobile/ to a mobile frontend, and route worker requests like https://simple-sample.uc.r.appspot.com/work/ to a static backend:

dispatch:
  # Send all mobile traffic to the mobile frontend.
  - url: "*/mobile/*"
    service: mobile-frontend

  # Send all work to the one static backend.
  - url: "*/work/*"
    service: static-backend

For details about how to define your dispatch.yaml, see the dispatch.yaml reference documentation.

Deploying the dispatch file

To deploy the dispatch configuration file, run the following command:

gcloud

gcloud app deploy dispatch.yaml

appcfg

Warning: The following describes using the appcfg tool. This tool is now deprecated and you should use the Cloud SDK tooling.

appcfg.py update_dispatch [YOUR_APP_DIR]

Routing in the development server

Discovering instance addresses

The local development server creates all manual scaling instances at startup. Instances for automatic and basic scaling services are managed dynamically. The server assigns a port to each service, and clients can depend on the server to load-balance and select an instance automatically. The port assignments for addressing each service appear in the server's log message stream. Here are the ports for an app that defines three services (the scaling type of each service is not relevant):

INFO Starting module "default" running at: http://localhost:8084
INFO Starting module "service1" running at: http://localhost:8082
INFO Starting module "service2" running at: http://localhost:8083

When you use a service's address (for example http://localhost:8082/), the server will select (or create) an instance of the service and send the request to that instance.

The server assigns unique ports to each instance of a service. To discover these ports you need to use the admin server. There is a unique port for the admin server, which appears in the message log:

INFO Starting admin server at: http://localhost:8000

This address takes you to the admin server console. From there you can click on Instances to see the dynamic state of your app's instances:

A separate entry will appear for each manual and basic instance. The instance numbers are links with unique port addresses for each instance. You can hover over a link to see the port assigned to that instance, or click on the link to send a request directly to that instance.

Dispatch files

If your app includes a dispatch.yaml file, the log messages stream will include a dispatcher port:

INFO Starting dispatcher running at: http://localhost:8080

Requests to this port are routed according to the rules in the dispatch file. The server does not support dispatch.yaml file rules that include hostnames (for example, url: "customer1.myapp.com/*"). Rules with relative path patterns (url: "*/fun") will work, so you can use URLs like http://localhost/fun/mobile to reach instances. The server will report an error in the log stream if you try to start an application with a dispatch.yaml file that contains host-based rules.