Configure pod DNS resolution using dnsPolicy and hostAliases - Container Compute Service

Alibaba Cloud Container Compute Service (ACS) clusters use CoreDNS for DNS resolution. This topic explains how DNS works inside a cluster and how to configure dnsPolicy to match your workload requirements.

Enable DNS resolution in your cluster

ACS clusters do not enable DNS resolution by default. To enable it, select CoreDNS when you create the cluster. CoreDNS is exposed inside the cluster as a Service named kube-dns in the kube-system namespace.

Run the following command to check the kube-dns Service:

kubectl get svc kube-dns -n kube-system

Expected output:

NAME       TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)                  AGE
kube-dns   ClusterIP   172.24.0.10   <none>        53/UDP,53/TCP,9153/TCP   27d

For more information about creating an ACS cluster with CoreDNS enabled, see Create an ACS cluster.

How DNS resolution works in ACS clusters

When a Pod starts, the kubelet configures its DNS settings using two parameters:

--cluster-dns=<dns-service-ip>: the IP address of the cluster DNS server
--cluster-domain=<default-local-domain>: the base domain name suffix

These parameters determine the content of /etc/resolv.conf inside each Pod:

nameserver xx.xx.0.10
search kube-system.svc.cluster.local svc.cluster.local cluster.local
options ndots:5

Parameter	Description
`nameserver`	IP address of the DNS server.
`search`	Domain suffixes appended to short names during DNS lookup. ACS clusters include three suffixes (`kube-system.svc.cluster.local`, `svc.cluster.local`, `cluster.local`), so a single lookup can generate up to four DNS queries.
`options`	Additional resolver options as key-value pairs. The default `ndots:5` means: if a domain name contains more dots than the `ndots` value, it is treated as a fully qualified domain name (FQDN) and resolved directly; if fewer dots, the `search` suffixes are appended first.

Choose a DNS policy

Set dnsPolicy in the Pod spec to control how the Pod resolves domain names. ACS clusters support the following policies:

Policy	DNS server used	When to use
`ClusterFirst`	CoreDNS (`kube-dns`)	Pods that need to access other Services in the cluster. This is the default.
`None`	Defined by `dnsConfig`	Pods that require fully custom DNS settings.
`Default`	Node's `/etc/resolv.conf` (Alibaba Cloud DNS)	Pods that do not access any cluster-internal Services.

Default is not the default DNS policy. If dnsPolicy is not specified, ClusterFirst is used.

Use CoreDNS to resolve cluster-internal domain names

Set dnsPolicy: ClusterFirst for Pods that communicate with other Services in the cluster. This is the default behavior for ACS workloads.

apiVersion: v1
kind: Pod
metadata:
  name: alpine
  namespace: default
spec:
  containers:
  - image: alpine
    command:
      - sleep
      - "10000"
    imagePullPolicy: Always
    name: alpine
  dnsPolicy: ClusterFirst

Customize DNS settings for a Pod

Set dnsPolicy: None and provide a dnsConfig block to fully control DNS settings for a Pod. When dnsPolicy is None, at least one nameserver must be specified in dnsConfig.

dnsConfig is optional and can be combined with any dnsPolicy, not only None. Use it with other policies to append additional nameservers or search domains on top of the existing settings.

apiVersion: v1
kind: Pod
metadata:
  name: alpine
  namespace: default
spec:
  containers:
  - image: alpine
    command:
      - sleep
      - "10000"
    imagePullPolicy: Always
    name: alpine
  dnsPolicy: None
  dnsConfig:
    nameservers: ["169.254.xx.xx"]
    searches:
    - default.svc.cluster.local
    - svc.cluster.local
    - cluster.local
    options:
    - name: ndots
      value: "2"

When the Pod starts, the above configuration produces the following /etc/resolv.conf:

nameserver 169.254.xx.xx
search default.svc.cluster.local svc.cluster.local cluster.local
options ndots:2

The following table describes the fields in dnsConfig:

Field	Description
`nameservers`	List of DNS server IP addresses for the Pod. Up to three IP addresses are allowed. When `dnsPolicy` is `None`, at least one must be specified. Duplicate addresses are removed.
`searches`	List of DNS search domains for hostname lookups. Up to six domains are allowed. These are appended to the base list derived from the DNS policy. Duplicate domains are removed.
`options`	List of resolver options, each with a `name` (required) and `value` (optional). These are merged into the options generated by the DNS policy. Duplicate items are removed.

Use node-level DNS without CoreDNS

If your Pods do not access any Services in the ACS cluster, set dnsPolicy: Default. DNS resolution is handled by Alibaba Cloud DNS using the node's /etc/resolv.conf, and CoreDNS is not involved.

apiVersion: v1
kind: Pod
metadata:
  name: alpine
  namespace: default
spec:
  containers:
  - image: alpine
    command:
      - sleep
      - "10000"
    imagePullPolicy: Always
    name: alpine
  dnsPolicy: Default

Map static hostnames to IP addresses

To add static hostname-to-IP mappings for a specific Pod, add the hostAliases field to the Pod spec. The kubelet manages the Pod's /etc/hosts file and writes these entries at startup.

Warning

Do not manually edit /etc/hosts inside a running container. The kubelet overwrites the file when a container restarts, so manual changes are lost.

To apply static mappings to all Pods in the cluster instead of a single Pod, enable the CoreDNS hosts plug-in. See Configure CoreDNS extensions.

The following example maps foo.local, bar.local, and foo.remote to static IP addresses:

apiVersion: v1
kind: Pod
metadata:
  name: hostaliases-pod
spec:
  hostAliases:
  - ip: "127.0.**.**"
    hostnames:
    - "foo.local"
    - "bar.local"
  - ip: "10.1.**.**"
    hostnames:
    - "foo.remote"
  containers:
  - name: cat-hosts
    image: busybox:1.28
    command:
    - cat
    args:
    - "/etc/hosts"

After the Pod starts, /etc/hosts contains:

# Kubernetes-managed hosts file.
127.0.**.**	localhost
10.200.**.**	hostaliases-pod

# Entries added by HostAliases.
127.0.**.**	foo.local	bar.local
10.1.**.**	foo.remote	bar.remote

What's next

Configure CoreDNS extensions