Python 2 is no longer supported by the community. We recommend that you migrate Python 2 apps to Python 3.

Mapping Custom Domains

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, such as 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:

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

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.

  • 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

  1. In the Google Cloud Console, go to the Custom Domains tab of the App Engine Settings page.

    Go to the Custom Domains page

  2. Click Add a custom domain.

  3. 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:

    1. Select Verify a new domain from the drop-down menu.
    2. Enter your naked domain name (such as "example.com") and click Verify.

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

    3. Enter information in the Webmaster Central window that appears. For help using Webmaster Central, see Webmaster Central help

    4. After you complete the steps in Webmaster Central, return to the Add a new custom domain page in the Google Cloud Console.

  4. 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 www subdomain. You can add more subdomains if you need them.

    When you've added all the mappings you want, click Save mappings.

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

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

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

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

  3. 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 (A, or AAAA, or CNAME).
    • Record name:
      • In A or AAAA records, enter @
      • In CNAME records, enter a third-level domain name. For example, enter www to map the www.example.com subdomain.
    • 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.
      • In A or AAAA records, the record data is an IP address
      • In CNAME 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, 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 dig tool, such as this online dig version, to confirm the DNS records have been successfully updated.

  5. 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 Webmaster Central page:

  1. Open the Webmaster Central verification page.

  2. Under Properties, click the domain for which you want to add a user or service account.

  3. 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 Cloud Console:

    Go to Service Accounts page

Using subdomains

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.

Wildcard mappings

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:

  • Entering *.example.com maps all subdomains of example.com to your app.
  • Entering *.private.example.com maps all subdomains of private.example.com to your app.
  • Entering *.nichol.sharks.nhl.example.com maps all subdomains of nichol.sharks.nhl.example.com to your app.
  • Entering *.excogitate.system.example.com maps all subdomains of excogitate.system.example.com to your app.

You can use wildcard mappings with services in App Engine by using the dispatch.yaml file to define request routing to specific services.

If you use Google Workspace with other subdomains on your domain, such as sites and mail, those mappings have higher priority and are matched first, before any wildcard mapping takes place. In addition, if you have other App Engine apps mapped to other subdomains, those mappings also have higher priority than any wildcard mapping.

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.

What's next

Secure your custom domains with SSL.