A Deep Dive into Kubernetes dnsPolicy

Table of Contents

1. Introduction
#

In Kubernetes, dnsPolicy is a critical field within a Pod’s spec that precisely defines how DNS resolution should be handled inside the Pod. When an application within your Pod attempts to resolve a domain name (whether it’s a cluster-internal service like my-service or an external domain like google.com), dnsPolicy determines which resolution process the system should follow.

2. The Four DNS Policies
#

Kubernetes provides four distinct DNS policies to accommodate different application scenarios.

Policy (`dnsPolicy`)	Core Behavior	Primary Use Cases
`ClusterFirst`	(Default Policy) Cluster Priority: DNS requests are first sent to the cluster’s internal DNS service (e.g., CoreDNS). If the domain is a cluster service, it’s resolved directly; otherwise, the request is forwarded to the node’s upstream DNS server.	The vast majority of standard applications. This is the most common and recommended configuration because it seamlessly supports both internal and external domain resolution.
`Default`	Inherit from Node: The Pod completely ignores the cluster’s DNS service and directly inherits the `/etc/resolv.conf` file configuration from its host node.	1. When a Pod does not need to access other services within the cluster. 2. To resolve specific compatibility issues with the cluster’s DNS.
`None`	No Policy / Fully Custom: Kubernetes applies no DNS configuration to the Pod. You must provide a complete DNS setup manually using the `dnsConfig` field.	When you need to use a completely separate, custom DNS resolution scheme, suitable for advanced network configurations.
`ClusterFirstWithHostNet`	`hostNetwork` version of ClusterFirst: Specifically designed for Pods with `hostNetwork: true`. Its behavior is similar to `ClusterFirst`, but its configuration is adapted for the host’s network.	When a Pod needs to use the host’s network directly but still needs to resolve services within the cluster.

3. How to Configure
#

Both dnsPolicy and dnsConfig are configured in the spec section of a Pod’s YAML file.

Example 1: Using `ClusterFirst` (Default)
#

If you don’t explicitly set dnsPolicy, it will automatically default to ClusterFirst.

1apiVersion: v1
2kind: Pod
3metadata:
4  name: my-pod-default
5spec:
6  containers:
7  - name: my-app
8    image: my-image
9  # dnsPolicy: ClusterFirst  <-- This line can be omitted as it's the default

Example 2: Using the `Default` Policy
#

This Pod will use its host node’s DNS configuration to resolve all domain names.

 1apiVersion: v1
 2kind: Pod
 3metadata:
 4  name: my-pod-node-dns
 5spec:
 6  containers:
 7  - name: my-app
 8    image: my-image
 9  # Set the DNS policy here
10  dnsPolicy: Default

Example 3: Using `None` with `dnsConfig` for Full Customization
#

In this example, we completely bypass Kubernetes DNS and configure Google’s DNS servers directly for the Pod.

 1apiVersion: v1
 2kind: Pod
 3metadata:
 4  name: my-pod-custom-dns
 5spec:
 6  containers:
 7  - name: my-app
 8    image: my-image
 9
10  # 1. Set the policy to "None" to enable full customization
11  dnsPolicy: "None"
12
13  # 2. Manually provide the complete DNS configuration
14  dnsConfig:
15    # Specify the IP addresses of the DNS servers
16    nameservers:
17      - 8.8.8.8
18      - 8.8.4.4
19    # Specify DNS search domains (for resolving short domain names)
20    searches:
21      - my-namespace.svc.cluster.local
22      - svc.cluster.local
23      - cluster.local
24    # DNS resolver options
25    options:
26      - name: ndots
27        value: "5"

4. Deep Dive into the `dnsConfig` Field
#

The dnsConfig field allows for more granular control over DNS and can be used in conjunction with dnsPolicy.

nameservers: A list of IP addresses to be used as DNS servers for the Pod. A maximum of 3 can be specified.
searches: A list of DNS search domains. When resolving a short domain name that doesn’t contain a dot (.) (e.g., my-service), the system will search under these domains in order. For example, it will attempt to resolve my-service.my-namespace.svc.cluster.local, then my-service.svc.cluster.local, and so on.
options: A list of objects for setting DNS resolver options.
- name: The name of the option (e.g., ndots, timeout).
- value: The value for the option.

Note: The behavior of dnsConfig differs depending on the dnsPolicy:

If dnsPolicy is ClusterFirst, the nameservers provided in dnsConfig are added after the cluster’s CoreDNS as fallbacks. The searches and options are merged with the default values.
If dnsPolicy is None, dnsConfig must provide all necessary information, as it will be the Pod’s sole DNS configuration.

5. Summary
#

For everyday use: Stick with the default ClusterFirst policy; it satisfies 99% of use cases.
For special requirements: Use Default when you need to bypass the cluster DNS.
For advanced customization: Use None in combination with dnsConfig when you need to integrate with a completely different DNS system.

1. Introduction#

2. The Four DNS Policies#

3. How to Configure#

Example 1: Using ClusterFirst (Default)#

Example 2: Using the Default Policy#

Example 3: Using None with dnsConfig for Full Customization#

4. Deep Dive into the dnsConfig Field#

5. Summary#