How requests are routed

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

• Routing with URLs
• Routing with a dispatch file
• Routing with Cloud Load Balancing

These options apply only to deployed apps. When you are testing locally, the routing behavior depends on the particular runtime and development environment that you're using.

Note that if you use the legacy bundled services to 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.

Routing with URLs

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 your app's default service at the version that you have configured to receive traffic.

URLs for services and versions

If you create more than one service in your app, each service has its own URL. Each version of a service also has its own URL, so you can deploy and test a new version before configuring that version to receive traffic.

The URLs for specific services and versions are in the following form:

VERSION-dot-SERVICE-dot-PROJECT_ID.REGION_ID.r.appspot.com

You can omit VERSION-dot- if you don't need to target a specific version.

To retrieve the IDs of your app's services and versions, you can use any of the following tools:

Example URLs

Here are some examples of URLs for App Engine, showing both the appspot.com domain that App Engine assigns to your app and a custom domain, which you can set up for your app.

• 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-dot-SERVICE-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

Routing with a dispatch file

You can create a dispatch file to override App Engine's URL-based 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.

Creating a dispatch file

To create a dispatch file, do the following:

1. Create a file named dispatch.yaml either in the root of your project directory, or in the root directory of your default service.

2. Define routing rules in the file as described see the dispatch.yaml reference.

Note the following about the routing rules:

• You can define up to 20 routing rules. Each rule must contain the url and service elements.
• The rules must use HTTP URL patterns that include the "." notation for separating subdomains. URLs defined with the HTTPS "-dot-" notation are not supported.
• The rules also apply to the URLs that you define in your cron.yaml file.

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

Deploying the dispatch file

To deploy the dispatch file using gcloud, run the following command:

gcloud app deploy dispatch.yaml

Routing with Cloud Load Balancing

Cloud Load Balancing is a separate product that enables advanced network configurations for all of your applications running on Google Cloud.

When HTTP(S) Load Balancing is enabled for serverless apps, you can:

• Configure your serverless app to serve from a dedicated IPv4 and/or IPv6 IP address that is not shared with other services.

• Reuse the same SSL certificates and private keys that you use for Compute Engine, Google Kubernetes Engine and Cloud Storage. This eliminates the need to manage separate certificates for serverless apps.

The load balancer does not interfere or interact with routing rules in your dispatch.yaml file. The dispatch.yaml rules are not evaluated until a serverless NEG directs traffic to App Engine.

Note the following:

• We recommend that you use ingress controls so that your app only receives requests sent from the load balancer (and the VPC if you use it). Otherwise, users can use your app's App Engine URL to bypass the load balancer, Google Cloud Armor security policies, SSL certificates, and private keys that are passed through the load balancer.

Additional details about App Engine URLs

Understanding the Region ID in URLs

The REGION_ID is an abbreviated code that Google assigns based on the region you select when you create your app. The code does not correspond to a country or province, even though some region IDs may appear similar to commonly used country and province codes. For apps created after February 2020, REGION_ID.r is included in App Engine URLs. For existing apps created before this date, the region ID is optional in the URL.

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

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.