Configure Pod DNS Policy and Fix Domain Resolution in ACK - ACK

Prerequisites

Before you begin, ensure that you have:

An ACK managed cluster or ACK Serverless cluster. For details, see Create an ACK managed cluster and ACK Serverless quick start
Connected kubectl to your cluster using the kubeconfig file

How CoreDNS works in ACK

ACK deploys CoreDNS workloads in every cluster. A Service named kube-dns exposes these workloads so that pods can send DNS queries to it. By default, two coredns pods serve as the backend.

Run the following commands to inspect the DNS components in your cluster:

# Check the kube-dns Service
kubectl get svc kube-dns -n kube-system

# Check the coredns Deployment
kubectl get deployment coredns -n kube-system

For a detailed explanation of how DNS resolution works in ACK clusters, see DNS overview.

Set a DNS policy for a pod

The dnsPolicy field controls how a pod resolves domain names. ACK supports four policies:

Policy	Behavior
`ClusterFirst`	The pod uses CoreDNS. `/etc/resolv.conf` inside the pod is populated with the `kube-dns` Service address. This is the default policy.
`None`	The pod ignores the cluster's DNS settings. Specify custom DNS settings using `dnsConfig`; without it, the pod cannot resolve any domain names.
`Default`	The pod inherits DNS settings from the node it runs on. In ACK, nodes are Elastic Compute Service (ECS) instances, so the pod uses the node's `/etc/resolv.conf`, which points to Alibaba Cloud DNS. CoreDNS is bypassed.
`ClusterFirstWithHostNet`	For pods running in hostNetwork mode. Without this policy, a hostNetwork pod defaults to `Default` and cannot reach cluster Services.

Default is not the default policy. If you omit dnsPolicy, the pod uses ClusterFirst.

Use CoreDNS to resolve domain names

Use ClusterFirst when pods need to reach other Services in the cluster. This is the most common case and the default behavior.

Set dnsPolicy: ClusterFirst in the pod spec:

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

Apply the manifest and verify DNS resolution:

kubectl apply -f pod.yaml

# Verify that the pod resolves cluster Services correctly
kubectl exec alpine -- nslookup kubernetes.default

Customize DNS settings for a pod

Use dnsPolicy: None when you need full control over the DNS server and search domains for a specific pod.

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"

The dnsConfig field accepts the following properties:

nameservers: A list of DNS server IP addresses for the pod. You can specify up to three addresses. At least one is required when dnsPolicy is None; otherwise, this field is optional. The addresses are merged with any nameservers generated by the DNS policy, and duplicates are removed.
searches: A list of DNS search domains for hostname lookup. Optional. The domains are merged with base search names generated from the DNS policy, and duplicates are removed. You can specify up to six domains. If the DNS server is unreachable, only the first search domain is tried.
options: A list of objects, each with a required name and an optional value. The entries are merged with options generated from the DNS policy, and duplicates are removed. For details, see DNS resolution and caching policies.

Apply the manifest and verify:

kubectl apply -f pod.yaml

# Check the DNS configuration inside the pod
kubectl exec alpine -- cat /etc/resolv.conf

For the full specification, see DNS for Services and Pods.

Use the node's DNS settings

Use dnsPolicy: Default when pods do not need to access cluster Services and you want DNS resolution handled by Alibaba Cloud DNS instead of CoreDNS.

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

Apply the manifest and verify:

kubectl apply -f pod.yaml

# Confirm the pod inherits the node's resolv.conf
kubectl exec alpine -- cat /etc/resolv.conf

Enable hostNetwork pods to reach cluster Services

When a pod runs with hostNetwork: true, it uses the host network stack directly. The default DNS policy for such pods is Default, which means they cannot reach cluster Services by name. Set dnsPolicy: ClusterFirstWithHostNet to restore cluster DNS resolution for these pods.

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

Apply the manifest and verify:

kubectl apply -f pod.yaml

# Verify that the pod resolves cluster Services correctly
kubectl exec alpine -- nslookup kubernetes.default

Map domain names to specific IP addresses

Two methods are available:

All pods (global): Enable the CoreDNS hosts plugin to apply the mapping cluster-wide. For details, see Configure extended features based on CoreDNS.
Individual pod: Use the hostAliases field to add entries to that pod's /etc/hosts.

Add host aliases to a pod

The hostAliases field in the pod spec adds entries to /etc/hosts after Kubernetes initializes the file.

Warning

Do not edit /etc/hosts directly inside a container. The kubelet manages this file and overwrites any manual changes when the pod starts or restarts.

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 Kubernetes initializes the pod, /etc/hosts contains the Kubernetes-managed entries followed by the aliases you specified:

# Kubernetes-managed hosts file.
127.0.**.**	localhost
::1	localhost ip6-localhost ip6-loopback
fe00::0	ip6-localnet
fe00::0	ip6-mcastprefix
fe00::1	ip6-allnodes
fe00::2	ip6-allrouters
10.200.**.**	hostaliases-pod

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

Apply the manifest and verify that the aliases resolve correctly:

kubectl apply -f hostaliases-pod.yaml

# Check that the aliases appear in /etc/hosts
kubectl exec hostaliases-pod -- cat /etc/hosts

# Verify resolution
kubectl exec hostaliases-pod -- nslookup foo.local

What's next

Best practices for DNS services — recommendations for optimizing DNS performance and reliability in ACK clusters.
DNS resolution and caching policies — detailed reference for CoreDNS resolution and caching configuration.