Region ID
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.
Learn more about region IDs.
This page describes how HTTP requests from users reach the appropriate version of a service. Requests can be routed in the following ways:
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
ModulesService.getVersionHostname
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:
Console
In the Google 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 Google Cloud project.
API
To programmatically retrieve resource IDs, see the list
methods in the
Admin API.
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 the request to an available instance of the
- 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:
Create a file named
dispatch.yaml
in the same directory used for the other configuration files, such as app.yaml.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
andservice
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 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 configuration file without otherwise altering the currently serving version, use one of the following commands in the directory containing your dispatch file, depending on your environment:gcloud
gcloud app deploy dispatch.yaml
Maven
mvn appengine:deployDispatch dispatch.yaml
Gradle
gradle appengineDeployDispatch dispatch.yaml
IDE
If you use IntelliJ or Eclipse, you select the individual configuration files to be deployed using the deployment form.
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.
Routing in the development server
Discovering instance addresses
The local development server creates all instances at startup. Note that at this time basic scaling instances are not supported on the local development server. Every instance that is created is assigned its own port. The port assignments appear in the server's log message stream. Web clients can communicate with a particular instance by targeting its port. Only one instance (and port) is created for automatic scaled services. It looks like this in the server log (note that services were previously called modules):
INFO: Module instance service-auto is running at http://localhost:37251/
A unique port is assigned to each instance of a manual scaled service:
INFO: Module instance service-manual instance 0 is running at http://localhost:43190/
INFO: Module instance service-manual instance 1 is running at http://localhost:52642/
In addition, each manual scaled service is assigned one extra port so clients can access the service without specifying a specific instance. Requests to this port are automatically routed to one of the configured instances:
INFO: Module instance service-manual is running at http://localhost:12361/
The following table shows how these services can be called in the development server and in the App Engine environment:
Service | Instance | Development server address | App Engine address |
---|---|---|---|
service-auto | (not used) | http://localhost:37251/ |
https://v1-dot-service-auto-dot-PROJECT_ID.REGION_ID.r.appspot.com/ |
service-manual | 0 | http://localhost:43190/ |
https://0-dot-v1-dot-service-manual-dot-PROJECT_ID.REGION_ID.r.appspot.com/ |
is used by the local development server. For details, see Apache Maven or Gradle.
Dispatch files
All dispatch files are ignored when running the local development server. The only way to target instances is through their ports.Restricting access to a service
All services are public by default. If you want to restrict access to a service,
add the <role-name>admin</role-name>
element to its
security constraint
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:
Console
In the Google 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:
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, entergcloud app versions list --service=default
.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, entergcloud app versions describe 20191023t101741 --service=default
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.