Configure DNS for a cluster

This document shows how to configure Domain Name System (DNS) provider options for Google Distributed Cloud. The DNS configuration for a cluster is held in a ClusterDNS custom resource named default . This resource is cluster-wide, which means that it isn't namespaced. The ClusterDNS custom resource applies to all cluster types.

Create the ClusterDNS resource

Create a manifest for a ClusterDNS resource named default . Fill in the spec to configure the resource settings that you want. For example:

  apiVersion 
 : 
  
 networking.gke.io/v1alpha1 
 kind 
 : 
  
 ClusterDNS 
 metadata 
 : 
  
 name 
 : 
  
 default 
 spec 
 : 
  
 upstreamNameservers 
 : 
  
 - 
  
 serverIP 
 : 
  
 8.8.8.8 
  
 - 
  
 serverIP 
 : 
  
 8.8.4.4 
  
 domains 
 : 
  
 - 
  
 name 
 : 
  
 altostrat.com 
  
 nameservers 
 : 
  
 - 
  
 serverIP 
 : 
  
 198.51.100.1 
  
 - 
  
 name 
 : 
  
 my-own-personal-domain.com 
  
 nameservers 
 : 
  
 - 
  
 serverIP 
 : 
  
 203.0.113.1 
  
 - 
  
 serverIP 
 : 
  
 203.0.113.2 
  
 serverPort 
 : 
  
 54 
  
 googleAccess 
 : 
  
 default 
 

To save the manifest to a file named my-dns.yaml and apply the resource to the cluster, run the following command:

 kubectl  
--kubeconfig  
 KUBECONFIG 
  
apply  
-f  
my-dns.yaml 

Replace KUBECONFIG with the path to the cluster kubeconfig file.

View the ClusterDNS resource

To view the ClusterDNS resource, run the following command:

 kubectl  
--kubeconfig  
 KUBECONFIG 
  
get  
clusterdns  
default  
--output  
yaml 

Replace KUBECONFIG with the path to the cluster kubeconfig file.

The ClusterDNS spec

The following sections describe the parts of the ClusterDNS custom resource definition you use to configure DNS for your clusters. You can update the ClusterDNS resource for a cluster at any time.

spec.upstreamNameservers

Use the spec.upstreamNameservers field to specify your default upstream name servers with an array of objects. Each object has a server IP address and optionally a server port. The default value for the server port is 53. Requests for non-cluster domains are forwarded to this set of servers by default.

Here's an example upstreamNameservers configuration:

  spec 
 : 
  
 upstreamNameservers 
 : 
  
 - 
  
 serverIP 
 : 
  
 8.8.8.8 
  
 - 
  
 serverIP 
 : 
  
 1.2.3.4 
  
 serverPort 
 : 
  
 54 
 

If you don't specify any values for upstreamNameservers , then the DNS provider uses the /etc/resolv.conf file on the node to find the list of upstream name servers.

spec.domains

Use the spec.domains field to configure different upstream name servers for particular domains. These domain-specific name server settings override the configuration in upstreamNameservers .

You can also turn on query logging for a domain. You can turn on query logging for any specified domain or the cluster domain, cluster.local .

Here's an example spec.domains configuration:

spec:
  domains:
  - name: altostrat.com
    nameservers:
    - serverIP: 198.51.100.1
  - name: my-own-personal-domain.com
    nameservers:
    - serverIP: 203.0.113.1
    - serverIP: 203.0.113.2
      serverPort: 50000
  - name: cluster.local
    queryLogging: true

spec.googleAccess

The spec.googleAccess field is a string that specifies how to treat Google domains. googleAccess values specify the following behavior:

• default : no special treatment for Google domains. Removing the googleAccess field has the same effect.

• private : resolves Google domains to private-access IP addresses only.

• restricted : resolves Google domains to restricted-access IP addresses only.

The following setting example resolves Google domains to private-access IP addresses only:

  spec 
 : 
  
 googleAccess 
 : 
  
 private 
 

For more information, see Configure Private Google Access for on-premises hosts .

spec.orderPolicy

The spec.orderPolicy field is a string. Use this field to specify the ordering policy by which upstream servers are selected.

• The default value is random .
• Supported types are random , round_robin , and sequential .
• This ordering policy applies to defined domains as well.

For more information about policy and what each configuration does, See the coredns documentation.

Here's an example spec.orderPolicy configuration:

spec:
  orderPolicy: sequential