IPV6 APIVIP Handling

RELEASE_NOTES.md

@@ -4,6 +4,8 @@
 
 ## General
 
+* Added support for IPv6 addresses in the Kubernetes 'apiVIP' field
+
 ## API
 
 ### Image Definition Changes

docs/building-images.md

@@ -261,7 +261,7 @@ kubernetes:
 * `network` - Required for multi-node clusters, optional for single-node clusters; Defines the network configuration 
 for bootstrapping a cluster.
   * `apiVIP` - Required for multi-node clusters, optional for single-node clusters; Specifies the IP address which
-  will serve as the cluster LoadBalancer, backed by MetalLB.
+  will serve as the cluster LoadBalancer, backed by MetalLB. Supports IPv4 and IPv6 addresses.
   * `apiHost` - Optional; Specifies the domain address for accessing the cluster.
 * `nodes` - Required for multi-node clusters; Defines a list of all nodes that form the cluster.
   * `hostname` - Required; Indicates the fully qualified domain name (FQDN) to identify the particular node on which

pkg/combustion/kubernetes.go

@@ -3,6 +3,7 @@ package combustion
 import (
 	_ "embed"
 	"fmt"
+	"net/netip"
 	"os"
 	"path/filepath"
 	"strings"
@@ -316,11 +317,18 @@ func (c *Combustion) downloadRKE2Artefacts(ctx *image.Context, cluster *kubernet
 }
 
 func kubernetesVIPManifest(k *image.Kubernetes) (string, error) {
+	ip, err := netip.ParseAddr(k.Network.APIVIP)
+	if err != nil {
+		return "", fmt.Errorf("parsing kubernetes apiVIP address: %w", err)
+	}
+
 	manifest := struct {
 		APIAddress string
+		IsIPV4     bool
 		RKE2       bool
 	}{
 		APIAddress: k.Network.APIVIP,
+		IsIPV4:     ip.Is4(),
 		RKE2:       strings.Contains(k.Version, image.KubernetesDistroRKE2),
 	}
 

pkg/combustion/kubernetes_test.go

@@ -821,3 +821,46 @@ func TestConfigureKubernetes_SuccessfulRKE2ServerWithManifests(t *testing.T) {
 	assert.Contains(t, contents, "name: my-nginx")
 	assert.Contains(t, contents, "image: nginx:1.14.2")
 }
+
+func TestKubernetesVIPManifestValidIPV4(t *testing.T) {
+	k8s := &image.Kubernetes{
+		Version: "v1.30.3+rke2r1",
+		Network: image.Network{
+			APIVIP: "192.168.1.1",
+		},
+	}
+
+	manifest, err := kubernetesVIPManifest(k8s)
+	require.NoError(t, err)
+
+	assert.Contains(t, manifest, "- 192.168.1.1/32")
+	assert.Contains(t, manifest, "- name: rke2-api")
+}
+
+func TestKubernetesVIPManifestValidIPV6(t *testing.T) {
+	k8s := &image.Kubernetes{
+		Version: "v1.30.3+k3s1",
+		Network: image.Network{
+			APIVIP: "fd12:3456:789a::21",
+		},
+	}
+
+	manifest, err := kubernetesVIPManifest(k8s)
+	require.NoError(t, err)
+
+	assert.Contains(t, manifest, "- fd12:3456:789a::21/128")
+	assert.Contains(t, manifest, "- name: k8s-api")
+	assert.NotContains(t, manifest, "rke2")
+}
+
+func TestKubernetesVIPManifestInvalidIP(t *testing.T) {
+	k8s := &image.Kubernetes{
+		Version: "v1.30.3+k3s1",
+		Network: image.Network{
+			APIVIP: "1111",
+		},
+	}
+
+	_, err := kubernetesVIPManifest(k8s)
+	require.ErrorContains(t, err, "parsing kubernetes apiVIP address: ParseAddr(\"1111\"): unable to parse IP")
+}

pkg/combustion/templates/k8s-vip.yaml.tpl

@@ -6,7 +6,11 @@ metadata:
   namespace: metallb-system
 spec:
   addresses:
-  - {{ .APIAddress }}/32
+  {{- if .IsIPV4 }}
+    - {{ .APIAddress }}/32
+  {{- else }}
+    - {{ .APIAddress }}/128
+  {{- end }}
   avoidBuggyIPs: true
   serviceAllocation:
     namespaces:

pkg/combustion/templates/rke2-multi-node-installer.sh.tpl

@@ -91,7 +91,7 @@ systemctl enable kubernetes-resources-install.service
 {{- end }}
 fi
 
-{{- if .apiHost }}
+{{- if and .apiVIP .apiHost }}
 echo "{{ .apiVIP }} {{ .apiHost }}" >> /etc/hosts
 {{- end }}
 

pkg/image/validation/kubernetes.go

@@ -3,6 +3,7 @@ package validation
 import (
 	"errors"
 	"fmt"
+	"net/netip"
 	"net/url"
 	"os"
 	"path/filepath"
@@ -32,6 +33,7 @@ func validateKubernetes(ctx *image.Context) []FailedValidation {
 		return failures
 	}
 
+	failures = append(failures, validateNetwork(&def.Kubernetes)...)
 	failures = append(failures, validateNodes(&def.Kubernetes)...)
 	failures = append(failures, validateManifestURLs(&def.Kubernetes)...)
 	failures = append(failures, validateHelm(&def.Kubernetes, combustion.HelmValuesPath(ctx), combustion.HelmCertsPath(ctx))...)
@@ -52,12 +54,6 @@ func validateNodes(k8s *image.Kubernetes) []FailedValidation {
 		return failures
 	}
 
-	if k8s.Network.APIVIP == "" {
-		failures = append(failures, FailedValidation{
-			UserMessage: "The 'apiVIP' field is required in the 'network' section when defining entries under 'nodes'.",
-		})
-	}
-
 	var nodeTypes []string
 	var nodeNames []string
 	var initialisers []*image.Node
@@ -117,6 +113,47 @@ func validateNodes(k8s *image.Kubernetes) []FailedValidation {
 	return failures
 }
 
+func validateNetwork(k8s *image.Kubernetes) []FailedValidation {
+	var failures []FailedValidation
+
+	if k8s.Network.APIVIP == "" {
+		if len(k8s.Nodes) > 1 {
+			failures = append(failures, FailedValidation{
+				UserMessage: "The 'apiVIP' field is required in the 'network' section for multi node clusters.",
+			})
+		}
+
+		return failures
+	}
+
+	parsedIP, err := netip.ParseAddr(k8s.Network.APIVIP)
+	if err != nil {
+		failures = append(failures, FailedValidation{
+			UserMessage: fmt.Sprintf("Invalid address value %q for field 'apiVIP'.", k8s.Network.APIVIP),
+			Error:       err,
+		})
+
+		return failures
+	}
+
+	if !parsedIP.Is4() && !parsedIP.Is6() {
+		failures = append(failures, FailedValidation{
+			UserMessage: "Only IPv4 and IPv6 addresses are valid values for field 'apiVIP'.",
+		})
+
+		return failures
+	}
+
+	if !parsedIP.IsGlobalUnicast() {
+		msg := fmt.Sprintf("Invalid non-unicast cluster API address (%s) for field 'apiVIP'.", k8s.Network.APIVIP)
+		failures = append(failures, FailedValidation{
+			UserMessage: msg,
+		})
+	}
+
+	return failures
+}
+
 func validateManifestURLs(k8s *image.Kubernetes) []FailedValidation {
 	var failures []FailedValidation
 

pkg/image/validation/kubernetes_test.go

@@ -15,7 +15,7 @@ import (
 
 var validNetwork = image.Network{
 	APIHost: "host.com",
-	APIVIP:  "127.0.0.1",
+	APIVIP:  "192.168.1.1",
 }
 
 func TestValidateKubernetes(t *testing.T) {
@@ -78,7 +78,10 @@ func TestValidateKubernetes(t *testing.T) {
 		`failures all sections`: {
 			K8s: image.Kubernetes{
 				Version: "v1.30.3",
-				Network: validNetwork,
+				Network: image.Network{
+					APIHost: "host.com",
+					APIVIP:  "127.0.0.1",
+				},
 				Nodes: []image.Node{
 					{
 						Type:        image.KubernetesNodeTypeServer,
@@ -116,6 +119,7 @@ func TestValidateKubernetes(t *testing.T) {
 				"Helm chart 'name' field must be defined.",
 				"Helm repository 'name' field for \"apache-repo\" must match the 'repositoryName' field in at least one defined Helm chart.",
 				"Helm chart 'repositoryName' \"another-apache-repo\" for Helm chart \"\" does not match the name of any defined repository.",
+				"Invalid non-unicast cluster API address (127.0.0.1) for field 'apiVIP'.",
 			},
 		},
 	}
@@ -185,24 +189,6 @@ func TestValidateNodes(t *testing.T) {
 				Nodes: []image.Node{},
 			},
 		},
-		`with nodes - no network config`: {
-			K8s: image.Kubernetes{
-				Network: image.Network{},
-				Nodes: []image.Node{
-					{
-						Hostname: "host1",
-						Type:     image.KubernetesNodeTypeServer,
-					},
-					{
-						Hostname: "host2",
-						Type:     image.KubernetesNodeTypeAgent,
-					},
-				},
-			},
-			ExpectedFailedMessages: []string{
-				"The 'apiVIP' field is required in the 'network' section when defining entries under 'nodes'.",
-			},
-		},
 		`no hostname`: {
 			K8s: image.Kubernetes{
 				Network: validNetwork,
@@ -1079,3 +1065,108 @@ func TestValidateAdditionalArtifacts(t *testing.T) {
 		})
 	}
 }
+
+func TestValidateNetwork(t *testing.T) {
+	tests := map[string]struct {
+		K8s                    image.Kubernetes
+		ExpectedFailedMessages []string
+	}{
+		`no network defined, no nodes defined`: {
+			K8s: image.Kubernetes{
+				Network: image.Network{},
+			},
+		},
+		`no network defined, nodes defined`: {
+			K8s: image.Kubernetes{
+				Network: image.Network{},
+				Nodes: []image.Node{
+					{
+						Hostname:    "node1",
+						Type:        "server",
+						Initialiser: false,
+					},
+					{
+						Hostname:    "node2",
+						Type:        "server",
+						Initialiser: false,
+					},
+				},
+			},
+			ExpectedFailedMessages: []string{
+				"The 'apiVIP' field is required in the 'network' section for multi node clusters.",
+			},
+		},
+		`valid ipv4`: {
+			K8s: image.Kubernetes{
+				Network: image.Network{
+					APIVIP: "192.168.1.1",
+				},
+			},
+		},
+		`valid ipv6`: {
+			K8s: image.Kubernetes{
+				Network: image.Network{
+					APIVIP: "fd12:3456:789a::21",
+				},
+			},
+		},
+		`invalid ipv4`: {
+			K8s: image.Kubernetes{
+				Network: image.Network{
+					APIVIP: "500.168.1.1",
+				},
+			},
+			ExpectedFailedMessages: []string{
+				"Invalid address value \"500.168.1.1\" for field 'apiVIP'.",
+			},
+		},
+		`non-unicast ipv4`: {
+			K8s: image.Kubernetes{
+				Network: image.Network{
+					APIVIP: "127.0.0.1",
+				},
+			},
+			ExpectedFailedMessages: []string{
+				"Invalid non-unicast cluster API address (127.0.0.1) for field 'apiVIP'.",
+			},
+		},
+		`invalid ipv6`: {
+			K8s: image.Kubernetes{
+				Network: image.Network{
+					APIVIP: "xxxx:3456:789a::21",
+				},
+			},
+			ExpectedFailedMessages: []string{
+				"Invalid address value \"xxxx:3456:789a::21\" for field 'apiVIP'.",
+			},
+		},
+		`non-unicast ipv6`: {
+			K8s: image.Kubernetes{
+				Network: image.Network{
+					APIVIP: "ff02::1",
+				},
+			},
+			ExpectedFailedMessages: []string{
+				"Invalid non-unicast cluster API address (ff02::1) for field 'apiVIP'.",
+			},
+		},
+	}
+
+	for name, test := range tests {
+		t.Run(name, func(t *testing.T) {
+			k := test.K8s
+			failures := validateNetwork(&k)
+			assert.Len(t, failures, len(test.ExpectedFailedMessages))
+
+			var foundMessages []string
+			for _, foundValidation := range failures {
+				foundMessages = append(foundMessages, foundValidation.UserMessage)
+			}
+
+			for _, expectedMessage := range test.ExpectedFailedMessages {
+				assert.Contains(t, foundMessages, expectedMessage)
+			}
+
+		})
+	}
+}