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; that is, it is not 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 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
      - serverIP: 203.0.113.1
      - serverIP: 203.0.113.2
        serverPort: 54
  googleAccess: default

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

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:

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

Specify your default upstream name servers with 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. Requests for non-cluster domains are forwarded to this array of server addresses by default.

Here's an example upstreamNameservers configuration:

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. Use this section 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 enable query logging 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

Enumeration (private, restricted, or default). 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 Configuring Private Google Access for on-premises hosts.