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.0.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/resolve.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: 203.0.113.1
  - name: my-own-personal-domain.com
    nameservers:
    - serverIP: 198.51.100.1
    - serverIP: 198.51.100.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