Configure DNS for a cluster

This document shows how to configure DNS for an admin cluster or user cluster.

The DNS configuration for a cluster is held in a ClusterDNS custom resource named default . This is a cluster-wide resource; that is, it is not namespaced.

View the ClusterDNS resource

To view the ClusterDNS resource:

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

Replace CLUSTER_KUBECONFIG with the path of the cluster kubeconfig file.

The DNS configuration is in the spec section. If the spec section is empty or missing, then the cluster uses a default Kubernetes CoreDNS configuration.

Change the DNS configuration

Create a manifest for a ClusterDNS resource named default . Fill in the spec as desired. 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: private

Save the manifest to a file named my-dns.yaml and apply the resource to the cluster:

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

The ClusterDNS spec

spec.upstreamNameservers

An array of objects, each of which has a server IP address and optionally a server port. The default value for the server port is 53.

The default upstream name servers. Requests for non-cluster domains are forwarded to this set of servers by default. For example:

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

If you do not 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

Configuration for specific domains. This allows overriding of the configuration in upstreamNameservers .

You can use this section to configure different upstream name servers for particular domains, separately from the default upstream name servers.

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

For example:

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

String. If you want Google domains to resolve to private-access IP addresses, set this to "private" . If you want Google domains to resolve to restricted-access IP addresses, set this to restricted . If you want no special treatment for Google domains, set this to default or remove it. For more information, see Configuring Private Google Access for on-premises hosts .

For example:

spec:
  googleAccess: private

spec.orderPolicy

String. If you want to specify the ordering policy by which upstream servers are selected. Default is "random" . Supported types are "random" , "round_robin" and "sequential" . Note that this ordering policy will apply to defined domains as well. See the coredns docs for more info about policy and what each configuration does.

For example:

spec:
  orderPolicy: sequential