HTTP requests from users can reach the appropriate services, versions, or instance in one of two ways:
- A request with a URL that ends at the domain level can be routed according to App Engine's default address routing rules.
- You can declare routes in a dispatch file that routes specific URL patterns according to your own rules.
If you test your app using the local development
the available routing and dispatch features are slightly different.
To programmatically create URLs that work with both production and
development servers, use the
See routing in the development server
to learn more.
Routing via URL
You can target an HTTP request with varying degrees of specificity. In the
appspot.com can be replaced with your app's custom domain
if you have one. The URL substrings "instance", "version", "service", and
"app-id" represent application and service attributes that you have defined
These address forms are guaranteed to reach their target (if it exists). They will never be intercepted and rerouted by a pattern in the dispatch file:
If you are using backends or manually scaled front-ends you can send a request to a specific instance by specifying the instance. The instance is an integer in the range of [0, total_instances) and can be specified as follows:
- Sends a request to the named service, version, and instance:
- Sends a request to an available instance of the named service and version:
These address forms have a default routing behavior. Note that the default routing is overridden if there is a matching pattern in the dispatch file:
- Sends a request to an available instance of the versions in the named service
- that are configured to receive traffic:
- Sends a request to an available instance of a specific version in the
- Sends the request to an available instance of the versions in the
- service that are configured to receive traffic:
default service is created when you deploy the initial version of your app
to App Engine. Requests that specify no service or include 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
service. See the Versions
in the Cloud Platform Console to view which versions are configured for traffic.
If a request matches the
app-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
Restricting access to a service
All services are public by default. If you want to restrict access to a service, add the “login: admin” parameter to its handlers.
Routing with a dispatch file
For certain URLs (described above), you can create the
which overrides the default address routing rules. This file lets you send
incoming requests to a specific service based on the path or hostname in the
URL. For example, say that you want to route mobile requests like
http://simple-sample.appspot.com/mobile/ to a mobile frontend, route worker
http://simple-sample.appspot.com/work/ to a static backend, and
serve all static content from the default service.
Uploading the dispatch file
To upload the
dispatch.yaml file, use the following command. Before you
upload your dispatch file, you must ensure that all the services defined in that
file have already been deployed to App Engine.
gcloud app deploy command from
the directory that contains the
gcloud app deploy dispatch.yaml
command from the directory that contains the
dispatch.yaml file and use
-A option to specify your Cloud Platform project ID:
appcfg.py -A [YOUR_PROJECT_ID] update_dispatch .
Note that the
dispatch.yaml file is also uploaded when you update a
service with the
appcfg.py update command.
For more information about the deployment commands, see Deploying a Go App.
Routing in the development server
Discovering instance addresses
The 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
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 filesIf your app includes a
dispatch.yamlfile, 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
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.