Mapping custom domains

You can set up a custom domain rather than the default address that Cloud Run provides for a deployed service.

There are a couple of ways to set up a custom domain for a Cloud Run service:

You can map multiple custom domains to the same Cloud Run service.

Before you begin

Purchase a new domain, unless you already have one that you want to use. You can use any domain name registrar.

Map a custom domain using a global external Application Load Balancer

With this option, you add a global external Application Load Balancer in front of your Cloud Run service and configure a custom domain at the load balancer level.

One advantage of using a global external Application Load Balancer is that it gives you a lot of control around your custom domain setup. For example, it allows you to use your own TLS certificate or route specific URL paths to the Cloud Run service. It also allows you to configure Cloud CDN for caching and Google Cloud Armor for additional security.

Note that you can also map multiple services to a dynamic hostname or path in your custom domain URL pattern for a single load balancer, for example, <service>.example.com, using URL Masks.

If you aren't currently using a global external Application Load Balancer, you can use the Cloud Run integrations feature to quickly set up a load balancer for your Cloud Run service. Refer to the integration page for custom domains on Cloud Run using a global external Application Load Balancer. If you already are using a global external Application Load Balancer, refer to the documentation on setting up a global external Application Load Balancer with Cloud Run. Note that using the integrations feature can overwrite some existing load balancer configurations such as CDN enablement.

Map a custom domain using Firebase Hosting

The easiest and recommended way to use Firebase Hosting to map a custom domain is by using the Cloud Run integrations feature for Firebase Hosting. If you don't want to use the Firebase Hosting integrations feature, you can alternatively use a manual approach to configure Firebase Hosting.

With this option, you configure Firebase Hosting in front of your Cloud Run service and connect a configure domain to Firebase Hosting.

Using Firebase Hosting has a low price and optionally allows you to host and serve static content alongside the dynamic content served by your Cloud Run service.

To map a custom domain using Firebase Hosting:

  1. Add Firebase to your Google Cloud project
  2. Install the Firebase CLI
  3. In a folder different from the source code of your service, create a firebase.json file with the following content:

      {
        "hosting": {
          "rewrites": [{
            "source": "**",
            "run": {
              "serviceId": "SERVICE_NAME",
              "region": "REGION"
            }
          }]
        }
      }
    

    Replace SERVICE_NAME and REGION with the name and region of your Cloud Run service.

  4. Deploy the Firebase Hosting configuration:

    firebase deploy --only hosting --project PROJECT_ID
  5. Connect a custom domain to Firebase Hosting

Read more about Firebase Hosting and Cloud Run.

Map a custom domain using Cloud Run domain mapping (Limited availability and Preview)

Cloud Run domain mapping limitations

The following considerations apply to Cloud Run domain mappings:

  • Cloud Run domain mappings are in the preview launch stage. Due to latency issues, they are not production-ready and are not supported at General Availability. At the moment, this option is not recommended for production services.
  • A Google-managed certificate for HTTPS connections is automatically issued and renewed when you map a service to a custom domain.
  • Provisioning the SSL certificate usually takes about 15 minutes but can take up to 24 hours.
  • You cannot disable TLS 1.0 and 1.1. If this is an issue, you can use Firebase Hosting or Cloud Load Balancing to enable TLS 1.2-only traffic.
  • You cannot upload and use your own (self-managed) certificates.
  • Cloud Run domain mappings are limited to 64 characters.
  • Domain mapping is available in the following regions:
    • asia-east1
    • asia-northeast1
    • asia-southeast1
    • europe-north1
    • europe-west1
    • europe-west4
    • us-central1
    • us-east1
    • us-east4
    • us-west1
  • To map custom domains in other regions, you must use one of the other mapping options.
  • When you use Cloud Run domain mappings, you map a custom domain to your service, then update your DNS records.
  • You can map a domain, such as example.com or a subdomain, such as subdomain.example.com.
  • You can only map a domain to /, not to a specific URL path like /users.
  • You cannot use wildcard certificates with this feature.

Map a custom domain to a service

You can use the Google Cloud console, gcloud CLI, or Terraform to map a custom domain to a service.

Console

  1. Open the domain mappings page in the Google Cloud console:
    Domain mappings page

  2. Click Add Mapping.

    Note that if your display window is too small, the Add Mapping button isn't displayed and you must click the 3-dot vertical ellipse icon at the right corner of the page.

  3. From the drop-down list, select the service you are mapping the custom domain to.

  4. Depending on the region that is set for the selected service, the form shows the available options for adding a custom domain:

    • Firebase Hosting using Cloud Run integrations
    • Custom domains - Google Cloud Load Balancing using Cloud Run integrations
    • Cloud Run Domain Mappings

    Select Cloud Run Domain Mappings.

  5. In the Add mapping form, select Verify a new domain.

  6. In the Base domain to verify field, you need to verify the ownership of a domain before being able to use it, unless you purchased your domain from Google.

    If you want to map subdomain.example.com or subdomain1.subdomain2.example.com, you should verify ownership of example.com. For more information on verifying domain ownership, refer to Search Console help

  7. Click Continue.

  8. After domain verification is finished, click Continue verification and close.

  9. Update your DNS records at your domain registrar website using the DNS records displayed in the last step. You can display the records at any time by clicking DNS Records in the "..." action menu for a domain mapping.

  10. Click Done.

Command line

  1. You must verify domain ownership the first time you use that domain in the Google Cloud project, unless you purchased your custom domain from Google. You can determine whether the custom domain you want to use has been verified by using the command

    gcloud domains list-user-verified

    If your ownership of the domain needs to be verified, open the Search Console verification page:

    gcloud domains verify BASE-DOMAIN

    where BASE-DOMAIN is the base domain you want to verify. For example, if you want to map subdomain.example.com, you should verify the ownership of example.com.

    In Search Console, complete domain ownership verification. For more information, refer to Search Console help.

  2. Map your service to the custom domain:

    gcloud beta run domain-mappings create --service SERVICE --domain DOMAIN
    • Replace SERVICE with your service name.
    • Replace DOMAIN with your custom domain, for example, example.com or subdomain.example.com

Terraform

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

To create a Cloud Run service, add the following to your existing main.tf file:

resource "google_cloud_run_v2_service" "default" {
  name     = "cloud-run-srv"
  location = "us-central1"
  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
  }
}

Replace the value for name with your own service name.

Map your Cloud Run service to the custom domain:

data "google_project" "project" {}

resource "google_cloud_run_domain_mapping" "default" {
  name     = "verified-domain.com"
  location = google_cloud_run_v2_service.default.location
  metadata {
    namespace = data.google_project.project.project_id
  }
  spec {
    route_name = google_cloud_run_v2_service.default.name
  }
}

Replace verified-domain.com with your custom verified domain, for example, example.com or subdomain.example.com

Add your DNS records at your domain registrar

After you've mapped your service to a custom domain in Cloud Run, you need to update your DNS records at your domain registrar. As a convenience, Cloud Run generates and displays the DNS records you need to enter. You must add these records that point to the Cloud Run service at your domain registrar for the mapping to go into effect.

If you're using Cloud DNS as your DNS provider, see Adding a record.

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

    Console

    1. Go to the Cloud Run domain mappings page:
      Domain mappings page

    2. Click the 3-dot vertical ellipse icon to the right of your service, then click DNS RECORDS to display all the DNS records:

    select DNS records

    Command line

    gcloud beta run domain-mappings describe --domain [DOMAIN]

    Replace [DOMAIN] with your custom domain, for example, example.com or subdomain.example.com.

    You need all of the records returned under the heading resourceRecords.

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

  3. Locate the host records section of your domain's configuration page and then add each of the resource records that you received when you mapped your domain to your Cloud Run service.

  4. When you add each of the above DNS records to the account at the DNS provider:

    • Select the type returned in the DNS record in the previous step: A, or AAAA, or CNAME.
    • Use the name www to map to www.example.com.
    • Use the name @ to map example.com.
  5. 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.

  6. 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 managed SSL certificate to be issued.

Add verified domain owners to other users or service accounts

When a user verifies a domain, that domain is only verified to that user's account. This means that only that user can add more domain mappings that use that domain. So, to enable other users to add mappings that use that domain, you must add them as verified owners.

If you need to add verified owners of your domain to other users or service accounts, you can add permission through the Search Console page:

  1. Navigate to this address in your web browser:

    https://search.google.com/search-console/welcome

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

  3. Scroll down to the Verified owners list, click Add an owner, and 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:

    Go to Service Accounts page

Delete a Cloud Run domain mapping

You can use the Google Cloud console or the gcloud command line tool to delete a domain mapping.

Console

  1. Open the domain mappings page in the Google Cloud console:
    Domain mappings page

  2. In the Domain Mappings page, select domain mapping you want to delete and click Delete.

Command line

  1. Delete the domain mapping:

    gcloud beta run domain-mappings delete --domain DOMAIN
    • Replace DOMAIN with your custom domain, for example, example.com or subdomain.example.com

Using custom domains with authenticated services

Authenticated services are protected by IAM. Such Cloud Run services require client authentication that declares the intended recipient of a request at credential generation time (the audience).

Audience is usually the full URL of the target service, which by default for Cloud Run services is a generated URL ending in run.app. However, if you use a custom domain, you should avoid using that automatically generated run.app URL as the audience. Instead, configure the service for a custom audience so that it accepts your custom domain as a valid authentication audience.

What's next

  • To set up a custom domain for Cloud Run by using a global external Application Load Balancer with Terraform, explore this sample code.