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.

• 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 use Cloud Load Balancing andserverless network endpoint group (NEGS)to route traffic to your App Engine app, we recommend that youmap your custom domain to the load balancer instead of directly to your app, anduse Google-managed SSL certificates that are created for the load balancer. Thiseliminates the need to manage separate SSL certificates for each serverless app.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

Note: These instructions describe using the Google Cloud console to mapcustom domains. If you prefer, you can usegcloud commands or theAdmin API.

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

   Go to Application settings

   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 Custom Domains

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

Note: If you have a custom domain set up for your App Engine app andwant to move it to a different Google Cloud project, you do not need toupdate your custom domain DNS records as these will remain fixed for the domainwhen you switch projects.

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.

Note: Some third party CDN providers might inadvertently intercept validationrequests, preventing them from reaching the App Engine app and causingthe domain mapping to fail or its certificate to fail to renew. For example, ifyou are using Cloudflare CDN, you should turn off the "Always use https"option in the "Edge Certificates" tab of theSSL/TLS tab.

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.

   • Note that if you are using Cloud DNS, there is no need to add an @ symbol when creating anA record for your parent custom domain (example.com). However, you might need to specify an @ symbol for other DNS providers like GoDaddy.

   • 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.

Note: According toRFC 1912, section 2.4,aCNAME record cannot coexist with any other data. In other words, if thesubdomainwww.example.com is an alias forexample.com, you cannot also haveanMX record, anA record, or even aTXT record forwww.example.com.

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. To view a listof service accounts, open theService Accounts page in the Google Cloud console

To add permissions through theSearch Console:

1. Open theSearch Console verification.

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

3. Go toSettings from the side panel.

4. UnderGeneral Settings, clickUsers and Permissions to find the owners of your domain.

5. ClickAdd User and enter the email ID of the user. Select the required permission to grant theuser. For details on permissions, seeManaging owners, users and permissions.

6. ClickAdd to delegate ownership to the user.

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.

Note: Wildcard mappings are not supported for managed SSL certificates.

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 Custom Domains

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 Google Workspace domain authentication, remove your custom domain mapping and redothe steps formapping a custom domain to your app. Make sure to configure your Google Workspace domain authenticationbeforeconfiguring your custom domain mapping in App Engine.

What's next

• Learn how tosecure your custom domains with SSL.
• If you want Cloud Load Balancing to manage incoming requests to your custom domain, seeMigrate App Engine custom domain to Cloud Load Balancing.