#Configure NodeLocal DNSCache

#Overview

NodeLocal DNSCache is a cluster plugin that improves cluster DNS performance by running a DNS caching proxy on cluster nodes. This plugin reduces DNS query latency and improves cluster stability by caching DNS responses locally on each node, minimizing the load on the central DNS service.

#Key Features

• Local DNS Caching: Caches DNS responses locally on each node to reduce query latency
• Improved Performance: Significantly reduces DNS lookup times for applications

#Important Notes

#Installation

#Install via Marketplace

1. Navigate to Administrator > Marketplace > Cluster Plugins.

2. Search for "Alauda Build of NodeLocal DNSCache" in the plugin list.

3. Click Install to open the installation configuration page.

4. Configure the required parameters:

   Parameter	Description	Example Value
   IP	The IP address of the node local DNS cache server. For IPv4, it is recommended to use an address within the 169.254.0.0/16 range, preferably 169.254.20.10. For IPv6, it is recommended to use an address within the fd00::/8 range, preferably fd00::10.	169.254.20.10

5. Review the deployment notes and ensure your environment meets the requirements.

6. Click Install to complete the installation.

7. Wait for the plugin status to change to "Ready".

#How It Works

#Architecture

Pod → NodeLocal DNSCache → [Cache Hit] → Pod
           ↓
    [Cache Miss] → CoreDNS → Response → Cache & Pod

#Configuration

#Default Health Check Port

The node-cache Pod runs with hostNetwork: true and exposes its health check endpoint on the node loopback 127.0.0.1:8080. The current plugin package does not provide an installation parameter to change this health check port.

Because node-cache uses the node network namespace, the 127.0.0.1:8080 it occupies is the node's loopback, not a pod's. Conflict only happens with workloads that share the node network namespace or run directly on the node host:

• A hostNetwork: true Pod that binds 127.0.0.1:8080 or 0.0.0.0:8080.
• A process running directly on the node host that binds 127.0.0.1:8080 or 0.0.0.0:8080.

Regular Pods (each in its own network namespace) are not affected, even if they listen on 8080.

Before installing the plugin, check whether 127.0.0.1:8080 is already used on each node:

ss -ltnp | grep '127.0.0.1:8080'

If the port is already used by a hostNetwork Pod or a node-host process, choose one of the following approaches:

• Move the conflicting workload to another port before installing NodeLocal DNSCache.
• Run the workload as a regular Pod (not hostNetwork), or bind it to a specific node IP other than 127.0.0.1 or 0.0.0.0.
• If the port must be changed for NodeLocal DNSCache, contact Alauda support to confirm whether your target version provides a supported configuration method.

Avoid manually editing the generated ConfigMap or DaemonSet as a long-term solution. Manual changes can be overwritten when the plugin is upgraded, reinstalled, or reconciled by the platform.

#DNS Availability Risk

After NodeLocal DNSCache takes effect, newly created Pods use the node-local DNS address as their DNS server. If the node-cache Pod on a node is unavailable, for example during a crash, eviction, image pull failure, or plugin upgrade, Pods on that node can fail to resolve DNS names.

To reduce the operational risk:

• Monitor the NodeLocal DNSCache DaemonSet and alert when any node-cache Pod is not Ready.

• Plan a maintenance window for plugin upgrades because DNS resolution on a node can be affected while the node-local DNS Pod is unavailable.

• Emergency recovery: If DNS resolution on a node fails because the node-cache Pod is unavailable, restore kubelet cluster-dns to the CoreDNS ClusterIP and recreate the affected Pods so that their /etc/resolv.conf is regenerated. The CoreDNS ClusterIP is the ClusterIP of the DNS Service in the kube-system namespace. To find it:

  kubectl get svc -n kube-system

  Look for the DNS Service (commonly named kube-dns or coredns) and use its ClusterIP.

#Optional: Configure Multiple DNS Servers

Kubelet supports multiple cluster-dns addresses. You can configure the CoreDNS ClusterIP as a secondary DNS server so that new Pods receive both DNS servers in /etc/resolv.conf.

Example:

cluster-dns: "169.254.20.10,10.96.0.10"

In this example, 169.254.20.10 is the NodeLocal DNSCache IP address and 10.96.0.10 is the CoreDNS ClusterIP. Replace both values with the addresses used by your cluster. To find the CoreDNS ClusterIP, run kubectl get svc -n kube-system and use the ClusterIP of the DNS Service (commonly named kube-dns or coredns).

This configuration can reduce the impact of a node-local DNS failure, but it is not a no-impact failover mechanism:

• The failover behavior depends on the resolver implementation in the workload image. For example, the glibc resolver typically tries the next nameserver only after the current one times out, so DNS resolution can become slower during a failure. musl libc, which is used by Alpine Linux, can query multiple nameservers in parallel and may fail over faster.
• Resolver options such as timeout and attempts also affect the failure delay.
• If NetworkPolicy is enabled, allow Pods to access both the NodeLocal DNSCache IP address and the CoreDNS ClusterIP on TCP and UDP port 53.
• When the CNI is Kube-OVN, the --node-local-dns-ip parameter on kube-ovn-controller does not conflict with a multi-address cluster-dns on kubelet. --node-local-dns-ip lets Kube-OVN deliver traffic to the node-local DNS IP, while the secondary CoreDNS ClusterIP still reaches CoreDNS through the normal Service path.

Validation in an IPv4 cluster showed the following behavior when the node-local DNS process on the workload node was stopped:

• A Pod with only the NodeLocal DNSCache IP address in /etc/resolv.conf failed to resolve DNS names.
• A Pod with both the NodeLocal DNSCache IP address and the CoreDNS ClusterIP in /etc/resolv.conf could resolve DNS names through CoreDNS.
• With the default glibc resolver behavior, failover to CoreDNS can take several seconds because the resolver waits for the first nameserver to time out.
• With musl libc, such as in Alpine Linux images, DNS queries can be sent to multiple nameservers in parallel, so failover can be faster.

If your cluster is upgraded by rebuilding nodes, add the multi-address cluster-dns value to each kubeletExtraArgs location described in the Important Notes section.

#Network Policy Configuration

Important: If your cluster has NetworkPolicy enabled, you must configure proper rules to allow DNS traffic to the NodeLocal DNSCache. Without these rules, pods may not be able to resolve DNS queries.

When using NetworkPolicy, ensure the following DNS traffic is allowed:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-dns-cache
spec:
  podSelector: {}
  policyTypes:
    - Ingress
    - Egress
  ingress:
    - from:
        - ipBlock:
            cidr: 169.254.20.10/32 # NodeLocal DNS IP address
      ports:
        - protocol: UDP
          port: 53
        - protocol: TCP
          port: 53
  egress:
    - to:
        - ipBlock:
            cidr: 169.254.20.10/32 # NodeLocal DNS IP address
      ports:
        - protocol: UDP
          port: 53
        - protocol: TCP
          port: 53