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
App Engine determines that an incoming request is intended for your app
by using the domain name of the request. A request whose domain name is
http://[YOUR_PROJECT_ID].appspot.com
is routed to the app whose ID is
[YOUR_PROJECT_ID]
. Every app gets an
appspot.com
domain name for free.
The appspot.com
domains also support subdomains of the form
[SUBDOMAIN]-dot-[YOUR_PROJECT_ID].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 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.
Requests for these URLs all go to the version of your app that you
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 appspot.com
domain name, for example:
http://[VERSION_ID]-dot-[YOUR_PROJECT_ID].appspot.com
.
You can also use subdomains with the version-specific URL:
http://[SUBDOMAIN]-dot-[VERSION_ID]-dot-[YOUR_PROJECT_ID].appspot.com
.
See Routing via URL for more information and examples.
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.
Routing via URL
You can target an HTTP request with varying degrees of specificity. In the
following examples, appspot.com
can be replaced with your app's
custom domain if you have one. The URL substrings
[VERSION_ID]
, [SERVICE_ID]
, and [MY_PROJECT_ID]
, each
represent the resource IDs of your app.
Tip: You can use the following tools to retrieve the IDs of your app's resources:
Console
In the GCP 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 GCP 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://[MY_PROJECT_ID].appspot.com http://[MY_CUSTOM_DOMAIN]
Requests are received by any version that is configured for traffic in the
default
service. - Sends the request to an available instance of the
-
- Sends a request to an available instance of a specific service:
https://[SERVICE_ID]-dot-[MY_PROJECT_ID].appspot.com http://[SERVICE_ID].[MY_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-[MY_PROJECT_ID].appspot.com http://[VERSION_ID].[MY_CUSTOM_DOMAIN]
When a service is not targeted, requests are sent to the
default
service.
Soft routing
If a request matches the [YOUR_PROJECT_ID].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-[MY_PROJECT_ID].appspot.com http://[VERSION_ID].[SERVICE_ID].[MY_PROJECT_ID].[MY_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-[MY_PROJECT_ID].appspot.com http://[INSTANCE_ID].[VERSION_ID].[SERVICE_ID].[MY_CUSTOM_DOMAIN]
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 GCP 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 GCP 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
.
To target specific services and versions, you can use the following URL patterns:
-
To target the version in the
default
service using HTTPS, you can use:https://vFrontend-dot-default-dot-requestsProject.appspot.com https://vFrontend-dot-requestsProject.appspot.com
-
To target the
vBackend
version using a custom domain without HTTPS, you can use:http://vBackend.service2.example.net http://vBackend.example.net
where
requestsProject.appspot.com
is mapped to theexample.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.
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
http://simple-sample.appspot.com/mobile/
to a mobile frontend, and route worker
requests like http://simple-sample.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
If you install the original App Engine SDK, you can run:
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 adispatch.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.