Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions docs/en/networking/functions/configure_node_local_dns.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,17 +16,23 @@ NodeLocal DNSCache is a cluster plugin that improves cluster DNS performance by
## Important Notes

:::warning
**Deployment Considerations:**
**Production and Deployment Considerations:**

Use NodeLocal DNSCache cautiously in production or production-like clusters. Before enabling it for business workloads, evaluate the following host port and node-level DNS availability risks. If these risks are not acceptable for your workload, continue to use CoreDNS directly instead of enabling NodeLocal DNSCache.

1. **Kube-OVN Underlay Mode**: The plugin does not support deployment in Kube-OVN Underlay mode. If deployed, it may cause DNS query failures.

2. **Kubelet Restart**: Deploying this plugin will cause the kubelet to restart.

3. **Pod Restart Required**: After the plugin is successfully deployed, it will not affect running Pods, but will only take effect on newly created Pods. When the CNI is Kube-OVN, you need to manually add the parameter "--node-local-dns-ip=(IP address of the local DNS cache server)" to the kube-ovn-controller.
3. **Host Port 8080 Usage**: The `node-cache` container uses `hostNetwork: true` and listens on `127.0.0.1:8080` for its health endpoint. This can conflict with node-level services or workloads that use `hostNetwork` or `hostPort` and bind `127.0.0.1:8080` or `0.0.0.0:8080`.

4. **Node-Level DNS Availability**: After the plugin takes effect, Pods on a node use the local NodeLocal DNSCache endpoint for DNS resolution. If the NodeLocal DNSCache Pod on that node crashes, is evicted, cannot pull its image, or is restarted during an upgrade, DNS resolution for all Pods on that node may fail. Pods do not automatically fall back to CoreDNS.

5. **Pod Restart Required**: After the plugin is successfully deployed, it will not affect running Pods, but will only take effect on newly created Pods. When the CNI is Kube-OVN, you need to manually add the parameter "--node-local-dns-ip=(IP address of the local DNS cache server)" to the kube-ovn-controller.

4. **NetworkPolicy Configuration**: If NetworkPolicy is configured in the cluster, you need to additionally allow both from and to directions for the node CIDR and nodeLocalDNSIP in the networkPolicy to ensure proper communication.
6. **NetworkPolicy Configuration**: If NetworkPolicy is configured in the cluster, you need to additionally allow both from and to directions for the node CIDR and nodeLocalDNSIP in the networkPolicy to ensure proper communication.

5. **Cluster Upgrade via Rebuilding**: If the cluster is upgraded by rebuilding nodes (re-provisioning), kubelet configuration changes will be lost. To make the NodeLocal DNS configuration persistent across upgrades, you need to add the `--cluster-dns` parameter to `kubeletExtraArgs` in the following three places of the cluster template:
7. **Cluster Upgrade via Rebuilding**: If the cluster is upgraded by rebuilding nodes (re-provisioning), kubelet configuration changes will be lost. To make the NodeLocal DNS configuration persistent across upgrades, you need to add the `--cluster-dns` parameter to `kubeletExtraArgs` in the following three places of the cluster template:
- `KubeadmControlPlane` → `initConfiguration` → `nodeRegistration` → `kubeletExtraArgs`
- `KubeadmControlPlane` → `joinConfiguration` → `nodeRegistration` → `kubeletExtraArgs`
- `KubeadmConfigTemplate` → `template` → `spec` → `joinConfiguration` → `nodeRegistration` → `kubeletExtraArgs`
Expand Down