Configure LocalDNS in Azure Kubernetes Service

LocalDNS is a feature in Azure Kubernetes Service (AKS) designed to enhance the Domain Name System (DNS) resolution performance and resiliency for workloads running in your cluster. When you deploy a DNS proxy on each node, LocalDNS reduces DNS query latency, improves reliability during network disruptions, and provides advanced configuration options for DNS caching and forwarding. This article explains how LocalDNS works, its configuration options, and how to enable, verify, and troubleshoot LocalDNS in your AKS clusters.

To learn about what LocalDNS is, including architecture details, and key capabilities, refer to DNS Resolution in Azure Kubernetes Service (AKS).

Best practices for LocalDNS configuration

When implementing LocalDNS in your AKS clusters, consider the following best practices:

Start with a minimal configuration: Begin with a simple configuration that uses the Preferred mode before moving to Required mode. This setup allows you to validate that LocalDNS works as expected without breaking your cluster.
Implement proper caching strategies: Configure cache settings based on your workload characteristics:
- For frequently changing records, use shorter cacheDurationInSeconds values. When doing so, it's important to note that cacheDurationInSeconds acts as a cap on the DNS record TTL but doesn't increase it. The resulting TTL is the smaller of what is returned from upstream or what is set in the cache plugin.
- For stable records, use longer cache durations to reduce DNS queries.
- Enable serveStale with appropriate settings to maintain service during DNS outages.
- Caching with LocalDNS operates on a best effort basis and doesn't guarantee stale responses. The cache is divided into 256 shards and with a default maximum of 10,000 entries, allowing each shard to hold about 39 entries. When a shard is full and a new entry needs to be added, one of the existing entries is chosen at random to be evicted. There's no preference for older or expires entries. As a result, a stale record might not always be available, especially under high query volume.
Monitor DNS performance: After enabling LocalDNS, monitor your application's DNS performance using:
- Application performance metrics.
- Node metrics to detect reduced network pressure.
- Log entries when queryLogging is set to Log.
Follow least privilege principle: When configuring DNS forwarding rules, only allow access to the required DNS servers and domains.
Test before production deployment: Always test LocalDNS configuration in a nonproduction environment before rolling it out to production clusters.
Use Infrastructure as Code (IaC): Store your localdnsconfig.json file in your infrastructure repository and include it in your AKS deployment templates.
Network configuration for TCP forwarding: When using TCP for DNS forwarding to VnetDNS, ensure that your Network Security Groups (NSGs), firewalls, or Network Virtual Appliances (NVAs) don't block TCP traffic between CoreDNS/LocalDNS and VnetDNS servers.
Avoid enabling both NodeLocal DNSCache and LocalDNS: It isn't recommended to enable both the upstream Kubernetes NodeLocal DNSCache and LocalDNS in your node pool. While AKS doesn't block this configuration, all DNS traffic is routed through LocalDNS, which might lead to unexpected behavior or reduced benefits from NodeLocal DNSCache.

Prerequisites

You must have an existing AKS cluster with Kubernetes versions 1.31 or later to use LocalDNS. If you need an AKS cluster, you can create one using Azure CLI, Azure PowerShell, or the Azure portal.
This article requires version 2.80.0 or later of the Azure CLI. If you're using Azure Cloud Shell, the latest version is already installed.
Your AKS cluster can't have node autoprovisioning enabled to use LocalDNS.
LocalDNS is only supported on node pools running Azure Linux or Ubuntu 22.04 or newer.
LocalDNS only supports Virtual Machine Scale Set node pools.
The Virtual Machine (VM) SKU used for your node pool must have at least 4 vCPUs (cores) to support LocalDNS.

Manage LocalDNS on an AKS cluster

LocalDNS is configured at the node pool level in AKS, meaning you can enable or disable LocalDNS independently for each node pool in your cluster. This tailors DNS resolution behavior based on the specific requirements of different workloads or environments. To enable LocalDNS on a node pool, you need to provide a configuration file: localdnsconfig.json that defines how LocalDNS should operate for that node pool.

If you don't specify a custom configuration file, AKS automatically applies a default LocalDNS configuration.

To enable LocalDNS during node pool creation, use the following command with your custom configuration file:

az aks nodepool add --name mynodepool1 --cluster-name myAKSCluster --resource-group myResourceGroup --localdns-config ./localdnsconfig.json

To enable LocalDNS on an existing node pool, use the following command with your custom configuration file:

az aks nodepool update --name mynodepool1 --cluster-name myAKSCluster --resource-group myResourceGroup --localdns-config ./localdnsconfig.json

Important

Enabling LocalDNS on a node pool initiates a reimage operation on all nodes within that pool. This process can cause temporary disruption to running workloads and might lead to application downtime if not properly managed. You should plan for potential service interruptions and ensure that the applications are configured for high availability or have appropriate disruption budgets in place before enabling this setting.

To disable LocalDNS for a node pool, you must update your localdnsconfig.json file by setting the mode property to Disabled. This change instructs AKS to turn off the local DNS proxy on all nodes in the specified pool, reverting DNS resolution to the default cluster behavior. After updating the configuration file, apply it to the node pool using the Azure CLI to ensure the change takes effect.

az aks nodepool update --name mynodepool1 --cluster-name myAKSCluster --resource-group myResourceGroup --localdns-config ./localdnsconfig.json

Once LocalDNS is enabled, you can verify its operation by running DNS queries from pods in the specified node pool and inspecting the SERVER field in the responses to confirm LocalDNS addresses are returned (169.254.10.10 or 169.254.10.11).

Before running the validation steps, ensure the following conditions are met:

You have kubectl installed and configured to access your AKS cluster.
Your user account has sufficient permissions to create and exec into pods.
The node pool where you want to validate LocalDNS is in a Ready state.
The BusyBox image (busybox:1.28) is accessible from your cluster nodes.

Here's an example of how to verify:

Create a debug pod in the node pool where LocalDNS is enabled:
```
kubectl run dnstest --image=busybox:1.28 -- sleep 3600
```
Once the pod is running, execute the following command to check DNS resolution:
```
kubectl exec -it dnstest -- nslookup kubernetes.default
```
Check the output. If localDNS is working correctly, you should see a response with the server address of 169.254.10.10 or 169.254.10.11:
```
Server:    169.254.10.10
Address 1: 169.254.10.10

Name:      kubernetes.default
Address 1: 10.0.0.1 kubernetes.default.svc.cluster.local
```

LocalDNS uses a JSON-based configuration file localdnsconfig.json to define DNS resolution behavior for each node pool. This file allows you to specify operational modes, server blocks for different DNS domains, and plugin settings such as caching, forwarding, and logging.

Default LocalDNS configuration

The default LocalDNS configuration provides a balanced setup that optimizes both internal and external DNS resolution for most AKS workloads. You can use this configuration as a starting point and customize it to better suit your cluster's specific DNS requirements.

When customizing LocalDNS, use the following configuration format as your template. You can add additional server blocks, however adding unsupported or additional top-level properties causes validation failures.

{
  "mode": "Required",
  "vnetDNSOverrides": {
    ".": {
      "queryLogging": "Error",
      "protocol": "PreferUDP",
      "forwardDestination": "VnetDNS",
      "forwardPolicy": "Sequential",
      "maxConcurrent": 1000,
      "cacheDurationInSeconds": 3600,
      "serveStaleDurationInSeconds": 3600,
      "serveStale": "Immediate"
    },
    "cluster.local": {
      "queryLogging": "Error",
      "protocol": "ForceTCP",
      "forwardDestination": "ClusterCoreDNS",
      "forwardPolicy": "Sequential",
      "maxConcurrent": 1000,
      "cacheDurationInSeconds": 3600,
      "serveStaleDurationInSeconds": 3600,
      "serveStale": "Immediate"
    }
  },
  "kubeDNSOverrides": {
    ".": {
      "queryLogging": "Error",
      "protocol": "PreferUDP",
      "forwardDestination": "ClusterCoreDNS",
      "forwardPolicy": "Sequential",
      "maxConcurrent": 1000,
      "cacheDurationInSeconds": 3600,
      "serveStaleDurationInSeconds": 3600,
      "serveStale": "Immediate"
    },
    "cluster.local": {
      "queryLogging": "Error",
      "protocol": "ForceTCP",
      "forwardDestination": "ClusterCoreDNS",
      "forwardPolicy": "Sequential",
      "maxConcurrent": 1000,
      "cacheDurationInSeconds": 3600,
      "serveStaleDurationInSeconds": 3600,
      "serveStale": "Immediate"
    }
  }
}

Configure the `mode` for LocalDNS

LocalDNS can be enabled in three possible modes that define the extent of enforcement of LocalDNS for the workload:

Required: In this mode, LocalDNS is enforced on the node pool if all prerequisites are satisfied. If the requirements aren't met, the deployment fails.
Disabled: Disables the local DNS feature, meaning DNS queries aren't resolved locally within the AKS cluster.
Preferred: In this mode, AKS manages LocalDNS enablement based on the Kubernetes version of the node pool. The configuration is always validated and included, but LocalDNS isn't enabled unless the correct Kubernetes version is used.

The following table summarizes LocalDNS behavior for each mode and Kubernetes version:

Kubernetes Version	Preferred	Required	Disabled
Less than 1.31	Not supported	Not supported	Not supported
Greater than 1.31	Config validated, not installed	Installed and enforced	Config validated, not installed

Server blocks and supported plugins for LocalDNS

The default configuration applies to queries from pods using dnsPolicy:default (under vnetDNSOverrides) and pods using dnsPolicy:ClusterFirst (under kubeDNSOverrides). Within each, there are two default server blocks defined: . and cluster.local.

. represents all external DNS queries from pods that are trying to resolve public or non cluster domains (for example, microsoft.com).
cluster.local represents all internal Kubernetes service discovery queries from pods that are trying to resolve kubernetes service names or internal cluster resources. These queries are routed through CoreDNS for resolution within the cluster.

Supported plugins

Plugin	Description	Default	Allowed Inputs
`queryLogging`	Define the logging level for DNS queries.	`Error`	`Error` `Log`
`protocol`	Sets the protocol used for DNS queries (UDP/TCP preference).	`ForceTCP` for cluster.local, else `PreferUDP`	`PreferUDP` `ForceTCP`
`forwardDestination`	Specifies the DNS server to forward queries to.	`ClusterCoreDNS` for cluster.local and kubeDNS traffic, else `VnetDNS`	`VnetDNS` `ClusterCoreDNS`
`forwardPolicy`	Determines the policy to use when selecting the upstream DNS server.	`Sequential`	`Random` `RoundRobin` `Sequential`
`maxConcurrent`	Maximum number of concurrent DNS queries handled by LocalDNS.	`1000`	Integer
`cacheDurationInSeconds`	Maximum TTL (Time To Live) in seconds for which DNS responses are cached.	`3600`	Integer
`serveStaleDurationInSeconds`	Duration (in seconds) to serve stale DNS responses if upstream is unavailable.	`3600`	Integer
`serveStale`	Policy for serving stale DNS responses during upstream failures.	`Immediate`	`Verify` `Immediate` `Disabled`

Configuration validation rules

When creating your LocalDNS configuration, be aware of these validation rules to avoid deployment failures:

Root zone (.) restrictions: Under vnetDNSOverrides, the forwardDestination for the root zone can't be ClusterCoreDNS.
Cluster.local zone restrictions: Under both vnetDNSOverrides and kubeDNSOverrides, the forwardDestination for cluster.local can't be VnetDNS.
Protocol and serveStale compatibility: When protocol is set to ForceTCP, serveStale can't be set to Verify. Use Immediate instead.

Note

These validation rules are enforced during configuration deployment. Violating them causes the LocalDNS configuration to fail validation.

Create a custom server block in LocalDNS

CoreDNS matches queries to a specific server block based on an exact match for domain being queried and not on partial matches. If you have the need for custom server blocks, you can add them to your LocalDNS configuration by creating a file called localdnsconfig.json with the added configurations.

For example, if you have specific DNS needs when accessing microsoft.com, you could use the following server block:

"microsoft.com": {
  "queryLogging": "Error",
  "protocol": "ForceTCP",
  "forwardDestination": "ClusterCoreDNS",
  "forwardPolicy": "Sequential",
  "maxConcurrent": 1000,
  "cacheDurationInSeconds": 3600,
  "serveStaleDurationInSeconds": 3600,
  "serveStale": "Immediate"
}

Monitor LocalDNS

LocalDNS exposes Prometheus metrics that you can use for monitoring and alerting. These metrics are exposed on port 9253 of the Node IP and can be scraped from there.

The following example YAML shows a scrape configuration you can use with the Azure Managed Prometheus add on as a DaemonSet:

kind: ConfigMap
apiVersion: v1
metadata:
  name: ama-metrics-prometheus-config-node
  namespace: kube-system
data:
  prometheus-config: |-
    global:
      scrape_interval: 1m
    scrape_configs:
    - job_name: localdns-metrics
      scrape_interval: 1m
      scheme: http
      metrics_path: /metrics
      relabel_configs:
      - source_labels: [__metrics_path__]
        regex: (.*)
        target_label: metrics_path
      - source_labels: [__address__]
        replacement: '$NODE_NAME'
        target_label: instance
      static_configs:
      - targets: ['$NODE_IP:9253']

Troubleshoot LocalDNS

DNS queries to specific domains are failing

If DNS queries to specific domains are failing after enabling LocalDNS:

Check if you have domain-specific overrides in your localdnsconfig.json that might be misconfigured.
Temporarily try removing domain-specific overrides and using only the default . configuration.
Check if the issue occurs with both User Datagram Protocol (UDP) and Transmission Control Protocol (TCP) by adjusting the protocol setting.

Update VNet DNS servers for LocalDNS

When you update custom DNS servers directly in the VNet configuration (using the Azure portal or CLI), these changes aren't automatically applied to your AKS cluster nodes. This happens because updating DNS settings at the VNet level only informs the Network Resource Provider (NRP), but doesn't notify the AKS Resource Provider. As a result, AKS nodes continue to use the previous DNS server settings until further action is taken.

To ensure AKS nodes pick up the new VNet DNS server settings:

Update the VNet DNS configuration using the Azure portal or APIs as needed.

Reimage the node pool through the AKS Resource Provider to apply and persist the DNS changes:

az aks nodepool upgrade --resource-group myResourceGroup --cluster-name myAKSCluster --name mynodepool --node-image-only

This process ensures the AKS Resource Provider is aware of the DNS changes and applies them to all nodes in the node pool.

Next steps

For information on LocalDNS in AKS, see LocalDNS in Azure Kubernetes Service (conceptual).

For comprehensive troubleshooting guidance on DNS issues when using LocalDNS, see Troubleshoot LocalDNS issues in AKS.

For details on how to customize CoreDNS in AKS, refer to the CoreDNS customization guide.

For information on the CoreDNS project, see the CoreDNS upstream project page.

To learn more about core network concepts, see Network concepts for applications in AKS.

Last updated on 2026-01-23