Using a test domain

Learn how to use wildcard DNS records to configure a domain for your cluster. You must configure a domain to enable your services to accept requests and allow you access for testing purposes.

By default, your Knative serving clusters use the example.com base domain and do not allow requests to your services. For example, sending requests to http://{service}.{namespace}.example.com fails.

To enable the services in your cluster to accept requests, you must configure your domain to use either of the following:

DNS wildcard records should be used for testing only due to the issues around the reliability of requests. Learn more about wildcard DNS records.

Before you begin

Make sure you have installed and configured Google Cloud CLI and kubectl.

Choosing between a wildcard DNS service and a custom domain

When you are developing and testing, you can change the default domain to use a wildcard DNS test site. Examples include:

If you already have a domain you want to use for testing purposes, or if you don't mind purchasing a domain for testing purposes, you can set the default domain to use your own domain. A custom domain offers better reliability for testing.

Getting the external IP address

Before proceeding, you must obtain the external IP address of the load balancer service created for the Istio ingress controller.

Console

To get the load balancer's external IP address from the Google Cloud console:

  1. Go to the GKE page in the Google Cloud console:
    Go to the GKE page

  2. Click Services and ingress.

  3. Identify the service that is your cluster's Istio ingress controller. The service's Type will be External load balancer. The following table shows the service's name based on your cluster's version:

    Cluster version ISTIO-GATEWAY
    1.15.3-gke.19 and greater
    1.14.3-gke.12 and greater
    1.13.10-gke.8 and greater    		 istio-ingress
    All other versions istio-ingressgateway

  4. Once you've found your cluster's Istio ingress controller, copy its Endpoint. This will be the IP address without the port number. For example, you might see 00.000.000.000:11 listed as an endpoint, but you only need to copy 00.000.000.000.

Command line

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.

If you're using a wildcard service, you'll need the external IP address when you edit the cluster configuration. If you're using your own custom domain, you'll need the external IP address to create or update a record at your domain registrar.

Configuring your cluster's domain

Knative serving uses the config-domain ConfigMap to define the base domain for all services deployed to the cluster. The command to edit this configuration will vary depending on whether you use a wildcard DNS service or a custom domain that you own. You can repeat these steps with different values if you want to update the default cluster domain in the future.

Testing with a DNS wildcard service

xip.io is used to demonstrate how to configure your domain to use a DNS wildcard service, but you can replace it with whatever service you choose.

Console

To change the default base domain from example.com to one of the DNS wildcard services (xip.io for example) in the Google Cloud console:

  1. Go to the Knative serving Domain mappings page in the Google Cloud console:

    Go to Domain mappings

  2. Select Add mapping > Add cluster default domain

  3. Select the checkbox next to "Apply this domain mapping to all Knative serving services deployed to this cluster."

  4. Select your cluster from the drop-down menu.

  5. In the Domain field, enter [EXTERNAL-IP].xip.io. Replace:

    • [EXTERNAL-IP] with the Load Balancer external IP address.

    • xip.io with the wildcard DNS site you are using.

Command line

To change the default base domain from example.com to one of the DNS wildcard sites (xip.io for example), use the command:

kubectl patch configmap config-domain --namespace knative-serving --patch \
  '{"data": {"example.com": null, "[EXTERNAL-IP].xip.io": ""}}'

Replace

  • [EXTERNAL-IP] with the Load Balancer external IP address.
  • xip.io with the wildcard DNS site you are using.

Your service is now available at {service-name}.{namespace}.{[EXTERNAL-IP].xip.io}.

Testing with a custom domain

If you want to use a custom domain of your own for testing, the following steps will help you get set up.

First, update the cluster's ConfigMap to point to your domain:

Console

  1. Go to the Knative serving Domain mappings page in the Google Cloud console:

    Go to Domain mappings

  2. Select Add mapping > Add cluster default domain

  3. Select the checkbox next to "Apply this domain mapping to all Knative serving services deployed to this cluster."

  4. Select your cluster from the drop-down menu.

  5. In the Domain field, enter your domain name. For example, example.com.

Command line

Specify your custom domain using the command:

kubectl patch configmap config-domain --namespace knative-serving --patch \
'{"data": {"example.com": null, "[DOMAIN]": ""}}'

Replace [DOMAIN] with your own domain, for example, mydomain.com The command above removes example.com from the ConfigMap and adds mydomain.com as the default base domain. You can repeat this command if you want to change this again to some other domain.

The remaining steps must be performed on your domain registrar's website:

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

  2. Locate the host records section of your domain's configuration page and then add the resource records you need.

    1. To add a DNS record to the account at the DNS provider:

      • Select the record type A.

      • Supply the wildcard *, as shown in the following example:

        dns wildcard

    2. 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 several hours, depending on the registrar, and on the Time-To-Live (TTL) of any previous DNS records for your domain.

After updating your DNS records and pointing them to your cluster, your service is available at {service-name}.{namespace}.{your-domain}.