You can use a custom domain rather than the default address that App Engine provides for your app.
To use a custom domain, map the domain to your app, then update your
DNS records. You can map a naked domain, such as
example.com or a subdomain,
subdomain.example.com. You can also use wildcards
to map subdomains.
By default, when you map a domain to your app, App Engine issues a managed certificate for SSL for HTTPS connections. For more information on using SSL with your custom domain, including how to use your own SSL certificates, see Securing your custom domains with SSL.
Using custom domains might add noticeable latency to responses that App Engine sends to your app's users in some regions. The regions are as follows:
App Engine custom domains use a pool of shared IP addresses for all applications. If you want to use an IP address that only maps to your domain then you should instead set up a load balancer with App Engine. This may mitigate a domain fronting issue in which a request to application A in the SNI certificate may be routed to application B in the HTTP Host header.
Before you begin
If you do not have a domain, purchase one. You can use any domain name registrar; if you use Google Domains, the domain is automatically verified for App Engine and you do not have to go through the domain verification process.
In order to add or edit a custom domain mapping, your account must have the App Engine Admin role (
roles/appengine.appAdmin) or a custom role that contains the
If you use Cloud Load Balancing and serverless NEGS to route traffic to your App Engine app, we recommend that you map your custom domain to the load balancer instead of directly to your app, and use SSL certificates that are created for the load balancer. This eliminates the need to manage separate SSL certificates for each serverless app. In addition, with Cloud Load Balancing you can set SSL policies that control the features of SSL that your load balancer negotiates with clients. For more information, see the following pages:
Note the following limitation:
- 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.
Mapping a custom domain to your app
In the Google Cloud console, go to the Application settings tab of the App Engine Settings page.
If you do not need to modify the default Google Accounts API Referrer, move to the next step.
If you need to enable Google Workspace authentication for your custom domain, click Edit to modify the Google Accounts API Referrer. In the Google Authentication drop-down menu, select Google Workspace domain, then add your domain such as
example.comin the empty field.
In the Google Cloud console, go to the Custom Domains tab of the App Engine Settings page.
Click Add a custom domain.
If your domain is already verified, the domain appears in the Select the domain you want to use section. Select the domain from the drop-down menu and click Continue.
If you haven't verified your domain yet, do the following:
- Select Verify a new domain from the drop-down menu.
Enter your naked domain name (such as "example.com") and click Verify.
Even if you only want to map a subdomain, such as "www.subdomain.example.com", enter the naked domain name to verify ownership.
Note that domain names must be shorter than 64 bytes.
Enter information in the Search Console window that appears. For help using Search Console, see Search Console help
After you complete the steps in Search Console, return to the Add a new custom domain page in the Google Cloud console.
In the Point your domain to [project-ID] section, specify the domain and subdomains that you want to map.
We recommend mapping the naked domain and the
wwwsubdomain. You can add more subdomains if you need them.
When you've added all the mappings you want, click Save mappings.
Click Continue to see your domain's DNS records.
You can retrieve these records any time on the Custom Domains tab of the App Engine Settings page.
Sign in to your domain registrar web site and update your DNS records with the records displayed in the previous step.
Updating DNS records at your domain registrar
After you've mapped your service to a custom domain in App Engine, you need to update your DNS records at your domain registrar. As a convenience, App Engine generates and displays the DNS records you need to enter.
Retrieve the DNS record information for your domain mappings:
In the Google Cloud console, go to the Custom Domains tab of the App Engine Settings page. The page lists DNS records for all of the domains you have mapped to your app.
Log in to your account at your domain registrar and open the DNS configuration page.
Locate the host records section of your domain's configuration page and add each of the DNS records that you retrieved when you mapped your domain to your app.
Enter the following information in the record fields:
- Record type: Enter the record type that is shown in the DNS record
Google created for you (
- Record name:
CNAMErecords, enter a third-level domain name. For example, enter
wwwto map the
- TTL: Specify a TTL depending on your needs.
- Data: Enter the record data (rrdata) that is shown in the DNS record
Google created for you.
AAAArecords, the record data is an IP address
CNAMErecords, the record data is a domain name
- Record type: Enter the record type that is shown in the DNS record Google created for you (
Save your changes in the DNS configuration page of your domain's account. In most cases, it takes only a few minutes for these changes to take effect, but in some cases it can take up to several hours, depending on the registrar and the Time-To-Live (TTL) of any previous DNS records for your domain. You can use a
digtool, such as this online
digversion, to confirm the DNS records have been successfully updated.
Test for success by browsing to your service at its new URL, for example
https://www.example.com. Note that it can take several minutes for the automatic SSL certificate to be issued.
Delegating ownership to other Google Cloud users or service accounts
If you need to delegate the ownership of your domain to other users or service accounts, you can add permission through the Search Console page:
Open the Search Console verification page.
Under Properties, click the domain for which you want to add a user or service account.
At the end of the Verified owners list, click Add an owner, then enter a Google Account email address or service account ID.
To view a list of your service accounts, open the Service Accounts page in the Google Cloud console:
If you set up a wildcard subdomain mapping for your custom domain, your application serves requests for any matching subdomain.
- If the user browses a domain that matches an application version name or service name, the application serves that version.
- If the user browses a domain that matches a service name, the application serves that service.
- There is a limit of 20 managed SSL certificates per week for each base domain. If you encounter the limit, App Engine keeps trying to issue managed certificates until all requests have been fulfilled.
You can use wildcards to map subdomains at any level, starting at third-level
subdomains. For example, if your domain is
example.com and you enter text in
the web address field:
*.example.commaps all subdomains of
example.comto your app.
*.private.example.commaps all subdomains of
private.example.comto your app.
*.nichol.sharks.nhl.example.commaps all subdomains of
nichol.sharks.nhl.example.comto your app.
*.excogitate.system.example.commaps all subdomains of
excogitate.system.example.comto your app.
You can use wildcard mappings with services in App Engine by using the
file to define request routing to specific services.
If you use Google Workspace with other subdomains
on your domain, such as
Some DNS providers might not work with wildcard subdomain mapping. In
particular, a DNS provider must permit wildcards in
CNAME host entries.
Wildcard routing rules apply to URLs that contain components for services, versions, and instances, following the service routing rules for App Engine.
Deleting custom domains from your app
In order to delete a custom domain mapping from your app, your account must have the
App Engine Admin role
roles/appengine.appAdmin) or a custom role that contains the
In the Google Cloud console, do the following:
Go to the Custom Domains tab of the App Engine Settings page.
Select the custom domain name and click Delete.
If your app shows authentication errors after configuring your custom domain with G Suite domain authentication, remove your custom domain mapping and redo the Mapping a custom domain to your app steps. Make sure to configure your G Suite domain authentication before configuring your custom domain mapping in App Engine.