Add dnsServiceIP override for cluster DNS settings

Support `clusterNetwork.dnsServiceIP` in API versions and conversions, validate the value, and
use it for kubelet/OSM when NodeLocalDNS is disabled. Fall back to the default 10th
service-subnet IP when unset.

Signed-off-by: Artiom Diomin <artiom@kubermatic.com>

Author: kron4eg

addons/operating-system-manager/deployment-controller.yaml

@@ -46,9 +46,7 @@ spec:
             - -log-format=json # json or console
             - -health-probe-address=0.0.0.0:8085
             - -metrics-address=0.0.0.0:8080
-            {{ if .Config.Features.NodeLocalDNS.Deploy -}}
-            - -cluster-dns={{ .Resources.NodeLocalDNSVirtualIP }}
-            {{ end -}}
+            - -cluster-dns={{ .ClusterDNSIP }}
             - -namespace=kube-system
             - -container-runtime={{ .Config.ContainerRuntime }}
             - -pause-image={{ .InternalImages.Get "PauseImage" }}

docs/api_reference/v1beta2.en.md

@@ -1,6 +1,6 @@
 +++
 title = "v1beta2 API Reference"
-date = 2026-04-03T12:52:19+02:00
+date = 2026-04-09T11:02:18+03:00
 weight = 11
 +++
 ## v1beta2
@@ -236,6 +236,7 @@ ClusterNetworkConfig describes the cluster network
 | ipFamily | IPFamily allows specifying IP family of a cluster. Valid values are IPv4 \| IPv6 \| IPv4+IPv6 \| IPv6+IPv4. | IPFamily | false |
 | nodeCIDRMaskSizeIPv4 | NodeCIDRMaskSizeIPv4 is the mask size used to address the nodes within provided IPv4 Pods CIDR. It has to be larger than the provided IPv4 Pods CIDR. Defaults to 24. | *int | false |
 | nodeCIDRMaskSizeIPv6 | NodeCIDRMaskSizeIPv6 is the mask size used to address the nodes within provided IPv6 Pods CIDR. It has to be larger than the provided IPv6 Pods CIDR. Defaults to 64. | *int | false |
+| dnsServiceIP | DNSServiceIP is an optional override for the cluster DNS service IP. If not set, it defaults to the 10th IP of the serviceSubnet (e.g. 10.96.0.10 for 10.96.0.0/12). When nodeLocalDNS is enabled, OSM always uses the NodeLocalDNS virtual IP regardless of this field. | string | false |
 
 [Back to Group](#v1beta2)
 

docs/api_reference/v1beta3.en.md

@@ -1,6 +1,6 @@
 +++
 title = "v1beta3 API Reference"
-date = 2026-04-03T12:52:19+02:00
+date = 2026-04-09T11:02:18+03:00
 weight = 11
 +++
 ## v1beta3
@@ -249,6 +249,7 @@ ClusterNetworkConfig describes the cluster network
 | ipFamily | IPFamily allows specifying IP family of a cluster. Valid values are IPv4 \| IPv6 \| IPv4+IPv6 \| IPv6+IPv4. | IPFamily | false |
 | nodeCIDRMaskSizeIPv4 | NodeCIDRMaskSizeIPv4 is the mask size used to address the nodes within provided IPv4 Pods CIDR. It has to be larger than the provided IPv4 Pods CIDR. Defaults to 24. | *int | false |
 | nodeCIDRMaskSizeIPv6 | NodeCIDRMaskSizeIPv6 is the mask size used to address the nodes within provided IPv6 Pods CIDR. It has to be larger than the provided IPv6 Pods CIDR. Defaults to 64. | *int | false |
+| dnsServiceIP | DNSServiceIP is an optional override for the cluster DNS service IP. If not set, it defaults to the 10th IP of the serviceSubnet (e.g. 10.96.0.10 for 10.96.0.0/12). When nodeLocalDNS is enabled, OSM always uses the NodeLocalDNS virtual IP regardless of this field. | string | false |
 
 [Back to Group](#v1beta3)
 

pkg/addons/applier.go

@@ -90,6 +90,7 @@ type templateData struct {
 	InternalImages                           *internalImages
 	Resources                                map[string]string
 	Params                                   map[string]string
+	ClusterDNSIP                             string
 }
 
 type registryCredentialsContainer struct {
@@ -185,6 +186,14 @@ func newAddonsApplier(s *state.State) (*applier, error) {
 		}
 	}
 
+	clusterDNSIP := resources.NodeLocalDNSVirtualIP
+	if !s.Cluster.Features.NodeLocalDNS.Deploy {
+		clusterDNSIP, err = s.Cluster.ClusterNetwork.EffectiveDNSServiceIP()
+		if err != nil {
+			return nil, fail.Runtime(err, "computing cluster DNS service IP")
+		}
+	}
+
 	data := templateData{
 		Config: s.Cluster,
 		Certificates: map[string]string{
@@ -211,8 +220,9 @@ func newAddonsApplier(s *state.State) (*applier, error) {
 			pauseImage: s.PauseImage,
 			resolver:   s.Images.Get,
 		},
-		Resources: resources.All(),
-		Params:    map[string]string{},
+		Resources:    resources.All(),
+		Params:       map[string]string{},
+		ClusterDNSIP: clusterDNSIP,
 	}
 
 	if !s.LiveCluster.IsProvisioned() {

pkg/apis/kubeone/helpers.go

@@ -18,8 +18,10 @@ package kubeone
 
 import (
 	"bytes"
+	"encoding/binary"
 	"fmt"
 	"math/rand"
+	"net"
 	"net/url"
 	"path/filepath"
 	"sort"
@@ -547,3 +549,31 @@ func (v VersionConfig) KubernetesMajorMinorVersion() string {
 
 	return fmt.Sprintf("v%d.%d", kubeSemVer.Major(), kubeSemVer.Minor())
 }
+
+// EffectiveDNSServiceIP returns the cluster DNS service IP to use for kubelet and OSM.
+// If DNSServiceIP is explicitly set, it is returned as-is.
+// Otherwise the 10th IP in the ServiceSubnet is computed (e.g. 10.96.0.10 for 10.96.0.0/12),
+// matching the CoreDNS service IP assigned by kubeadm.
+func (c ClusterNetworkConfig) EffectiveDNSServiceIP() (string, error) {
+	if c.DNSServiceIP != "" {
+		return c.DNSServiceIP, nil
+	}
+
+	return nthIPInSubnet(c.ServiceSubnet, 10)
+}
+
+// nthIPInSubnet returns the n-th IP address within the given CIDR subnet.
+func nthIPInSubnet(cidr string, n uint32) (string, error) {
+	_, network, err := net.ParseCIDR(cidr)
+	if err != nil {
+		return "", fmt.Errorf("parsing subnet %q: %w", cidr, err)
+	}
+
+	ip := network.IP.To4()
+	addr := binary.BigEndian.Uint32(ip)
+	addr += n
+	result := make(net.IP, 4)
+	binary.BigEndian.PutUint32(result, addr)
+
+	return result.String(), nil
+}

pkg/apis/kubeone/types.go

@@ -611,6 +611,11 @@ type ClusterNetworkConfig struct {
 
 	// NodeCIDRMaskSizeIPv6 is the mask size used to address the nodes within provided IPv6 Pods CIDR. It has to be larger than the provided IPv6 Pods CIDR. Defaults to 64.
 	NodeCIDRMaskSizeIPv6 *int `json:"nodeCIDRMaskSizeIPv6,omitempty"`
+
+	// DNSServiceIP is an optional override for the cluster DNS service IP.
+	// If not set, it defaults to the 10th IP of the serviceSubnet (e.g. 10.96.0.10 for 10.96.0.0/12).
+	// When nodeLocalDNS is enabled, OSM always uses the NodeLocalDNS virtual IP regardless of this field.
+	DNSServiceIP string `json:"dnsServiceIP,omitempty"`
 }
 
 // IPFamily allows specifying IP family of a cluster.

pkg/apis/kubeone/v1beta2/types.go

@@ -616,6 +616,11 @@ type ClusterNetworkConfig struct {
 
 	// NodeCIDRMaskSizeIPv6 is the mask size used to address the nodes within provided IPv6 Pods CIDR. It has to be larger than the provided IPv6 Pods CIDR. Defaults to 64.
 	NodeCIDRMaskSizeIPv6 *int `json:"nodeCIDRMaskSizeIPv6,omitempty"`
+
+	// DNSServiceIP is an optional override for the cluster DNS service IP.
+	// If not set, it defaults to the 10th IP of the serviceSubnet (e.g. 10.96.0.10 for 10.96.0.0/12).
+	// When nodeLocalDNS is enabled, OSM always uses the NodeLocalDNS virtual IP regardless of this field.
+	DNSServiceIP string `json:"dnsServiceIP,omitempty"`
 }
 
 // IPFamily allows specifying IP family of a cluster.

pkg/apis/kubeone/v1beta2/zz_generated.conversion.go

@@ -608,6 +608,11 @@ type ClusterNetworkConfig struct {
 
 	// NodeCIDRMaskSizeIPv6 is the mask size used to address the nodes within provided IPv6 Pods CIDR. It has to be larger than the provided IPv6 Pods CIDR. Defaults to 64.
 	NodeCIDRMaskSizeIPv6 *int `json:"nodeCIDRMaskSizeIPv6,omitempty"`
+
+	// DNSServiceIP is an optional override for the cluster DNS service IP.
+	// If not set, it defaults to the 10th IP of the serviceSubnet (e.g. 10.96.0.10 for 10.96.0.0/12).
+	// When nodeLocalDNS is enabled, OSM always uses the NodeLocalDNS virtual IP regardless of this field.
+	DNSServiceIP string `json:"dnsServiceIP,omitempty"`
 }
 
 // IPFamily allows specifying IP family of a cluster.