You can use a custom domain rather than the default address that App Engineprovides for your app.

To use a custom domain, map the domain to your app, then update yourDNS records. You can map a naked domain, such asexample.com or a subdomain,such assubdomain.example.com. You can alsouse wildcardsto map subdomains.

By default, when you map a domain to your app, App Engineissues a managed certificate for SSL for HTTPS connections. For more informationon using SSL with your custom domain, including how to use your own SSLcertificates, seeSecuring your custom domains with SSL.

Using custom domains might add noticeable latency to responses thatApp Engine sends to your app's users in some regions. The regionsare as follows:

• us-west2
• us-east4
• northamerica-northeast1
• southamerica-east1
• europe-west2
• europe-west3
• asia-south1
• asia-northeast1
• australia-southeast1

App Engine custom domains use a pool of shared IP addresses for allapplications. If you want to use an IP address that only maps to your domainthen you should insteadset up a load balancer withApp Engine. This maymitigate a domain fronting issue in which a request to application A in the SNIcertificate 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 nameregistrar; if you useGoogle Domains, thedomain is automatically verified for App Engine and you do not have togo through the domain verification process.

• In order to add or edit a custom domain mapping, your account must havetheApp Engine Admin role(roles/appengine.appAdmin) or a custom role that contains theappengine.applications.get permission.

• If you useCloud Load Balancing andserverless NEGS toroute traffic to your App Engine app, we recommend that you map yourcustom domain to the load balancer instead of directly to your app, and useSSL certificates that are created for the load balancer. This eliminates theneed to manage separate SSL certificates for each serverless app. In addition,with Cloud Load Balancing you can set SSL policies that control the featuresof SSL that your load balancer negotiates with clients.For more information, see the following pages:

  • Using Google-managed SSL certificates
  • Using self-managed SSL certificates
  • SSL policies

  Note the following limitation:

  • We recommend that youuse ingress controlsso that your app only receives requests sent from the load balancer(and the VPC if you use it). Otherwise, users can use your app'sApp Engine URL to bypass the load balancer, Cloud Armorsecurity policies, SSL certificates, and private keys that are passed throughthe load balancer.

Mapping a custom domain to your app

1. In the Google Cloud console, go to theApplication settings tab of theApp EngineSettings page.

   Go to the Application settings page

   If you do not need to modify the defaultGoogle Accounts API Referrer,move to the next step.

   If you need to enable Google Workspace authentication for your custom domain, clickEdit to modify theGoogle Accounts API Referrer. In theGoogle Authentication drop-down menu, selectGoogle Workspace domain, then addyour domain such asexample.com in the empty field.

2. In the Google Cloud console, go to theCustom Domains tab of theApp EngineSettings page.

   Go to the Custom Domains page

3. ClickAdd a custom domain.

4. If your domain is already verified, the domain appears in theSelect the domain you want to use section. Select the domain from thedrop-down menu and clickContinue.

   If you haven't verified your domain yet, do the following:

   1. SelectVerify a new domain from the drop-down menu.

   2. Enter your naked domain name (such as "example.com") and clickVerify.

      Even if you only want to map a subdomain, such as"www.subdomain.example.com", enter the naked domain name to verifyownership.

      Note that domain names must be shorter than 64 bytes.

   3. Enter information in the Search Console window that appears.For help using Search Console, seeSearch Console help

   4. After you complete the steps in Search Console, return to theAdd a new custom domain page in the Google Cloud console.

5. In thePoint your domain to [project-ID] section, specify the domainand subdomains that you want to map.

   We recommend mapping the naked domain and thewww subdomain. You canadd more subdomains if you need them.

   When you've added all the mappings you want, clickSave mappings.

6. ClickContinue to see your domain's DNS records.

   You can retrieve these records any time on theCustom Domains tab of theApp EngineSettings page.

7. Sign in to your domain registrar web site andupdate your DNS records with the records displayedin the previous step.

Updating DNS records at your domain registrar

1. Retrieve the DNS record information for your domain mappings:

   In the Google Cloud console, go to theCustom Domains tab of theApp EngineSettings page. The page lists DNS records for allof the domains you have mapped to your app.

2. Log in to your account at your domain registrar and open the DNSconfiguration page.

3. Locate the host records section of your domain's configuration page andadd each of the DNS records that you retrieved when you mappedyour domain to your app.

   Enter the following information in the record fields:

   • Record type: Enter the record type that is shown in the DNS recordGoogle created for you (A, orAAAA, orCNAME).
   • Record name:
     • InA orAAAA records, enter@
     • InCNAME records, enter a third-level domain name. For example,enterwww to map thewww.example.com subdomain.
   • TTL: Specify a TTL depending on your needs.
   • Data: Enter the record data (rrdata) that is shown in the DNS recordGoogle created for you.
     • InA orAAAA records, the record data is an IP address
     • InCNAME records, the record data is a domain name

4. 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, butin some cases it can take up to several hours, depending on the registrar andtheTime-To-Live (TTL) of anyprevious DNS records for your domain. You can use adig tool, such asthis onlinedig version,to confirm the DNS records have been successfully updated.

5. Test for success by browsing to your service at its new URL, forexamplehttps://www.example.com. Note that it can take several minutes forthe 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 serviceaccounts, you can add permission through theSearch Console page:

1. Open theSearch Console verification page.

2. UnderProperties, click the domain for which you want to add a useror service account.

3. At the end of theVerified owners list, clickAdd an owner, thenenter a Google Account email address or service account ID.

   To view a list of your service accounts, open the Service Accounts page inthe Google Cloud console:

   Go to Service Accounts page

Using subdomains

If you set up a wildcard subdomain mapping for your custom domain, yourapplication serves requests for any matching subdomain.

• If the user browses a domain that matches an application version name orservice name, the application serves that version.
• If the user browses a domain that matches a service name, the applicationserves 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 managedcertificates until all requests have been fulfilled.

Wildcard mappings

You can use wildcards to map subdomains at any level, starting at third-levelsubdomains. For example, if your domain isexample.com and you enter text inthe web address field:

• Entering*.example.com maps all subdomains ofexample.com to your app.
• Entering*.private.example.com maps all subdomains ofprivate.example.comto your app.
• Entering*.nichol.sharks.nhl.example.com maps all subdomains ofnichol.sharks.nhl.example.com to your app.
• Entering*.excogitate.system.example.com maps all subdomains ofexcogitate.system.example.com to your app.

You can use wildcard mappings with services in App Engine by using thedispatch.yamlfile to define request routing to specific services.

If you useGoogle Workspace with other subdomainson your domain, such assites andmail, those mappings have higher priorityand are matched first, before any wildcard mapping takes place. In addition, ifyou have other App Engine apps mapped to other subdomains, thosemappings also have higher priority than any wildcard mapping.

Some DNS providers might not work with wildcard subdomain mapping. Inparticular, a DNS provider must permit wildcards inCNAME host entries.

Wildcard routing rules apply to URLs that contain components for services,versions, and instances, following theservice 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 theApp Engine Admin role(roles/appengine.appAdmin) or a custom role that contains theappengine.applications.update permission.

In the Google Cloud console, do the following:

1. Go to theCustom Domains tab of theApp EngineSettings page.

   Go to the Custom Domains page

2. Select the custom domain name and clickDelete.

Alternatively, you can usegcloud commands or theAdmin API to delete custom domains.

Troubleshooting

If your app shows authentication errors after configuring your custom domainwith G Suite domain authentication, remove your custom domain mapping and redotheMapping a custom domain to your appsteps. Make sure to configure your G Suite domain authenticationbeforeconfiguring your custom domain mapping in App Engine.

What's next

Secure your custom domains with SSL.