Mapping custom domains

Beta

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

You can use a custom domain for your Knative serving service.

To use a custom domain for a service, you map your service to the custom domain, then update your DNS records. You can map a service to a domain, such as example.com, or to a subdomain, such as subdomain.example.com.

If you are using HTTPS, in order for the domain mappings to work, you need to either use the managed TLS certificates feature or supply your own certificates.

You can map multiple custom domains to the same Knative serving service.

Before you begin

• You must have or purchase the domain that you want to map to your services. You can use any domain name registrar, but if you use Cloud Domains, the domain is automatically verified for Knative serving, so you won't have to go through the domain verification process.

  If you want to register a domain with Cloud Domains, see Registering a domain with Cloud Domains within the Knative serving console.

• If you are using WebSockets in Knative serving, you must first enable WebSocket support by running the following kubectl command to create an Istio EnvoyFilter object with allow_connect: true:

  cat <<EOF | kubectl apply -f -
  apiVersion: networking.istio.io/v1alpha3
  kind: EnvoyFilter
  metadata:
    name: allowconnect-cluser-local-gateway
    namespace: gke-system
  spec:
    workloadSelector:
      labels:
        app: cluster-local-gateway
    configPatches:
    - applyTo: NETWORK_FILTER
      match:
        listener:
          portNumber: 80
          filterChain:
            filter:
              name: "envoy.http_connection_manager"
      patch:
        operation: MERGE
        value:
          typed_config:
            "@type": "type.googleapis.com/envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager"
            http2_protocol_options:
              allow_connect: true
  EOF
  

Mapping a custom domain to a service

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

Console

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

   Go to Domain mappings

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

2. In the Domain Mappings page, click Add Mapping.

3. From the dropdown list in the Add Mapping form, select the service you are mapping the custom domain to:

   

4. Enter the domain name. Base path mapping is not supported. The term base path refers to the URL path name that is after the domain name. For example, users is the base path of example.com/users. Knative serving only allows you to map a domain to /, not to a specific base path. So any path routing has to be handled by using a router inside the service's container or by using Firebase Hosting.

5. Click Continue.

6. Verify ownership of your domain before you try to use it in your Google Cloud project, unless you purchased your custom domain from Cloud Domains. For example, if you want to map subdomain.example.com to a service, you need to verify ownership of the example.com domain.

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

8. Click Done.

Command line

1. Verify ownership of your domain before you try to use it in your Google Cloud project, unless you purchased your custom domain from Google Domains. 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 Webmaster Central 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 Webmaster Central, complete domain ownership verification. For more information, refer to Webmaster Central help.

2. Map your service to the custom domain:

   gcloud run domain-mappings create --service SERVICE --domain DOMAIN

   Replace:

   • SERVICE with your service name.

   • DOMAIN with your custom domain. Base path mapping is not supported. The term base path refers to the URL path name that is after the domain name. For example, users is the base path of example.com/users. Knative serving only allows you to map a domain to /, not to a specific base path. So any path routing has to be handled by using a router inside the service's container or by using Firebase Hosting.

     Optional: If DOMAIN is already mapped to another service, you can append the --force-override flag. This flag removes the mapping from the previous service and replaces it with a new mapping between the DOMAIN and SERVICE.

3. Reserve the Load Balancer IP address for the Istio ingress gateway service as a static IP:

   gcloud compute addresses create ADDRESS-NAME --addresses EXTERNAL-IP --region REGION

   Replace:

   • ADDRESS-NAME with the name you want to give your static IP.
   • EXTERNAL-IP with the IP address in the A record that you obtained with the gcloud run domain-mapping describe command.
   • REGION with the region that you are using.

Knative serving Istio ingress gateway

To get the external IP for the Istio ingress gateway:

kubectl get svc istio-ingress -n gke-system

where the resulting output looks something like this:

NAME            TYPE           CLUSTER-IP     EXTERNAL-IP  PORT(S)
istio-ingress   LoadBalancer   XX.XX.XXX.XX   pending      80:32380/TCP,443:32390/TCP,32400:32400/TCP

The EXTERNAL-IP for the Load Balancer is the IP address you must use.

OK

Add your DNS records at your domain registrar

After you've mapped your service to a custom domain in Knative serving, you need to update your DNS records at your domain registrar. As a convenience, Knative serving generates and displays the DNS records you need to enter. You must add these records that point to the Knative serving 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.

Note: Some third party CDN providers might inadvertently intercept validation requests, preventing them from reaching the Knative serving service and causing the domain mapping to fail or its certificate to fail to renew. For example, if you are using Cloudflare CDN, you should turn off the "Always use https" option in the "Edge Certificates" tab of the SSL/TLS tab.

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

   Console

   1. Go to the Knative serving domain mappings page:

      Go to Domain mappings

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

   

   Command line

   gcloud 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 Knative serving 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.

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

Note: A verified domain owner is able to override existing domain mappings from other projects after confirmation.

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

Registering a domain with Cloud Domains within the Knative serving console

Preview — Registering a domain with Cloud Domains within the Knative serving console

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To register a domain with Cloud Domains within the Knative serving console, follow these steps:

1. Go to the Knative serving domain mappings page:

   Go to Domain mappings

2. Click Register domain.

3. Complete the registration process following the instructions for Registering a domain.

4. Map your domain to Knative serving and add DNS records at your domain registrar.