Mapping Custom Domains

Region ID

The REGION_ID is a code that Google assigns based on the region you select when you create your app. Including REGION_ID.r in App Engine URLs is optional for existing apps and will soon be required for all new apps.

To ensure a smooth transition, we are slowly updating App Engine to use region IDs. If we haven't updated your Google Cloud project yet, you won't see a region ID for your app. Since the ID is optional for existing apps, you don't need to update URLs or make other changes once the region ID is available for your existing apps.

Learn more about region IDs.

You can map your App Engine app URL to a custom domain, such as example.com, and serve it from that domain instead of the default REGION_ID.r.appspot.com address.

By default, when you map your custom 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 in the following regions might add noticeable latency to responses:

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

Before you begin

  1. If you do not have a domain, purchase one. You can use any domain name registrar, including Google Domains.

  2. Enable the Admin API in your project by doing one of the following, depending on which tool you prefer to use:

Adding a custom domain for your application

Step 1: Verifying your domain in Webmaster Central

Console

  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.

    The Cloud Console displays the Add a new custom domain form.

  3. In the Select the domain you want to use section, select Verify a new domain from the drop-down menu.

  4. Enter the name of your domain (such as "example.com"), then click Continue.

    Your browser opens the Webmaster Central page in a new tab.

gcloud

Run the following gcloud domains command to open Webmaster Central, where DOMAIN is the domain you want to verify:

gcloud domains verify DOMAIN

Follow the instructions on Webmaster Central to verify ownership of your domain.

If the verification methods for your domain do not offer the CNAME record option:

  1. Click Alternate methods, then click Domain name provider.
  2. In the menu, select Other.
  3. In the Having trouble section, click Add a CNAME record, then follow the instructions to verify ownership of your domain.

There might be a delay before your CNAME is set at your domain registrar.

For more information about adding a CNAME record, including host-specific instructions, see the support page.

Step 2: Ensuring that your domain is verified

Console

If your domain is not already listed, click Refresh domains.

gcloud

Run the following gcloud domains command to list your verified domains:

gcloud domains list-user-verified

API

To programmatically list your verified domains, use the apps.authorizedDomains.list method of the Admin API.

Step 3: Optional: 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

Step 4: Mapping your verified domain to your app

After you verify ownership of your domain, you can map that domain to your App Engine app:

Console

Continue to the next step of the Add new custom domain form to select the domain that you want to map to your App Engine app:

  1. Specify the domain and subdomains that you want to map. The naked domain and www subdomain are pre-populated in the form.

    • A naked domain, such as example.com, maps to http://example.com.
    • A subdomain, such as www, maps to http://www.example.com.
  2. Click Save mappings.

  3. Note the resource records that are listed, including the resource for the canonical name (CNAME). You need to add these details to your domain's DNS configuration.

gcloud

Run the following gcloud app domain-mappings command to map your domain to your App Engine app, replacing DOMAIN with your domain, such as *.example.com:

gcloud app domain-mappings create DOMAIN

If you get an error, try using quotes around your domain, as in '*.example.com'.

Note the resource records that are listed, including the resource for the canonical name (CNAME). You need to add these details to your domain's DNS configuration.

API

To programmatically map your domain to your App Engine app, use the app.domainMappings.create method of the Admin API.

After your domain is mapped to your App Engine app, use the apps.domainMappings.list method to list your resource records.

Step 5: Adding resource records to your DNS configuration

To add the resource records that you received to the DNS configuration of your domain registrar:

  1. Log in to your account at your domain registrar, then open the DNS configuration page.

  2. Locate the host records section of your domain's configuration page, then add each of the resource records that you received when you mapped your domain to your App Engine app.

    Typically, you list the host name along with the canonical name as the address. For example, if you registered a Google Domain, then one of the records that you add to your DNS configuration is the www host name, along with the ghs.googlehosted.com address. To specify a naked domain, you would instead use @ with the ghs.googlehosted.com address.

    If you are migrating from another provider, make sure that all DNS records point to your App Engine app.

  3. Save your changes in the DNS configuration page of your domain's account.

Step 6: Testing the mapping

Test for success by browsing to your app via its new domain URL, such as www.example.com.

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 G Suite 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.