Fix ipv6 handling and update the docs with behavior

Author: komer3

cloud/linode/loadbalancers.go

@@ -1418,8 +1418,10 @@ func getNodeBackendIP(service *v1.Service, node *v1.Node, subnetID int, useIPv6B
 	}
 
 	if publicIPv6, exists := node.Annotations[annotations.AnnLinodeNodePublicIPv6]; exists {
-		if parsed := net.ParseIP(publicIPv6); parsed != nil && parsed.To4() == nil {
-			return publicIPv6, nil
+		if prefix, err := netip.ParsePrefix(publicIPv6); err == nil {
+			if addr := prefix.Addr(); addr.Is6() {
+				return addr.String(), nil
+			}
 		}
 	}
 

cloud/linode/loadbalancers_test.go

@@ -4116,7 +4116,7 @@ func Test_getNodeBackendIP(t *testing.T) {
 				ObjectMeta: metav1.ObjectMeta{
 					Name: "node-1",
 					Annotations: map[string]string{
-						annotations.AnnLinodeNodePublicIPv6: "2600:3c06::1",
+						annotations.AnnLinodeNodePublicIPv6: "2600:3c06::1/128",
 					},
 				},
 				Status: v1.NodeStatus{
@@ -4136,7 +4136,7 @@ func Test_getNodeBackendIP(t *testing.T) {
 					Name: "node-1",
 					Annotations: map[string]string{
 						annotations.AnnLinodeNodePrivateIP: "192.168.10.10",
-						annotations.AnnLinodeNodePublicIPv6: "2600:3c06::1",
+						annotations.AnnLinodeNodePublicIPv6: "2600:3c06::1/128",
 					},
 				},
 				Status: v1.NodeStatus{
@@ -4150,6 +4150,44 @@ func Test_getNodeBackendIP(t *testing.T) {
 			useIPv6Backends: true,
 			expectedIP:      "2600:3c06::1",
 		},
+		{
+			name: "errors when public IPv6 annotation is missing prefix length",
+			node: &v1.Node{
+				ObjectMeta: metav1.ObjectMeta{
+					Name: "node-1",
+					Annotations: map[string]string{
+						annotations.AnnLinodeNodePublicIPv6: "2600:3c06::2",
+					},
+				},
+				Status: v1.NodeStatus{
+					Addresses: []v1.NodeAddress{
+						{Type: v1.NodeExternalIP, Address: "172.232.0.2"},
+						{Type: v1.NodeExternalIP, Address: "fd00::11"},
+					},
+				},
+			},
+			useIPv6Backends: true,
+			expectErr:       true,
+		},
+		{
+			name: "errors when public IPv6 annotation is not a valid IPv6 value",
+			node: &v1.Node{
+				ObjectMeta: metav1.ObjectMeta{
+					Name: "node-1",
+					Annotations: map[string]string{
+						annotations.AnnLinodeNodePublicIPv6: "not-an-ip",
+					},
+				},
+				Status: v1.NodeStatus{
+					Addresses: []v1.NodeAddress{
+						{Type: v1.NodeExternalIP, Address: "172.232.0.2"},
+						{Type: v1.NodeExternalIP, Address: "2600:3c06::1"},
+					},
+				},
+			},
+			useIPv6Backends: true,
+			expectErr:       true,
+		},
 		{
 			name: "errors when IPv6 backends are requested and node lacks public IPv6 annotation",
 			node: &v1.Node{
@@ -4334,7 +4372,7 @@ func Test_buildLoadBalancerRequestPreservesVPCConfigForIPv6Backends(t *testing.T
 					ObjectMeta: metav1.ObjectMeta{
 						Name: "node-1",
 						Annotations: map[string]string{
-							annotations.AnnLinodeNodePublicIPv6: "2600:3c06:e727:1::1",
+							annotations.AnnLinodeNodePublicIPv6: "2600:3c06:e727:1::1/128",
 						},
 					},
 					Status: v1.NodeStatus{

deploy/chart/values.yaml

@@ -108,10 +108,11 @@ tolerations:
 # This can also be controlled per-service using the "service.beta.kubernetes.io/linode-loadbalancer-enable-ipv6-ingress" annotation
 # enableIPv6ForLoadBalancers: true
 
-# Enable IPv6 backend addresses for NodeBalancer services (including VPC-backed NodeBalancers).
+# Enable public IPv6 backend addresses for NodeBalancer services.
+# VPC IPv6 backend addresses are not currently supported.
 # When enabled globally, both newly created and existing eligible services may be reconciled to use IPv6 backends.
 # Per-service behavior can be overridden with the "service.beta.kubernetes.io/linode-loadbalancer-enable-ipv6-backends" annotation; set it to "false" to keep a service on IPv4 backends only.
-# All selected backend nodes must have the required IPv6 address (public or VPC, depending on the NodeBalancer configuration).
+# If your cluster uses VPC-backed NodeBalancers, the nodes must still expose public IPv6 endpoints so CCM can read the node.k8s.linode.com/public-ipv6 annotation and program IPv6 backends.
 # enableIPv6ForNodeBalancerBackends: false
 
 # disableNodeBalancerVPCBackends is used to disable the use of VPC backends for NodeBalancers.

docs/configuration/annotations.md

@@ -40,7 +40,7 @@ The keys and the values in [annotations must be strings](https://kubernetes.io/d
 | `firewall-acl` | string | | The Firewall rules to be applied to the NodeBalancer. See [Firewall Configuration](#firewall-configuration) |
 | `nodebalancer-type` | string | | The type of NodeBalancer to create (options: common, premium, premium_40gb). See [NodeBalancer Types](#nodebalancer-type). Note: NodeBalancer types should always be specified in lowercase. |
 | `enable-ipv6-ingress` | bool | `false` | When `true`, both IPv4 and IPv6 addresses will be included in the LoadBalancerStatus ingress |
-| `enable-ipv6-backends` | bool | `false` | When `true`, NodeBalancer services use IPv6 backend nodes. If VPC-backed NodeBalancers are enabled, CCM preserves the NodeBalancer VPC configuration. This requires a dual-stack cluster and a dual-stack Service configuration. Reconciliation fails if a selected backend node does not have the required IPv6 address. |
+| `enable-ipv6-backends` | bool | `false` | When `true`, NodeBalancer services use node public IPv6 addresses as backend targets. VPC IPv6 backend addresses are not supported. |
 | `backend-ipv4-range` | string | | The IPv4 range from VPC subnet to be applied to the NodeBalancer backend. See [Nodebalancer VPC Configuration](#nodebalancer-vpc-configuration) |
 | `backend-vpc-name` | string | | VPC which is connected to the NodeBalancer backend. See [Nodebalancer VPC Configuration](#nodebalancer-vpc-configuration) |
 | `backend-subnet-name` | string | | Subnet within VPC which is connected to the NodeBalancer backend. See [Nodebalancer VPC Configuration](#nodebalancer-vpc-configuration) |

docs/configuration/environment.md

@@ -53,7 +53,7 @@ The CCM supports the following flags:
 | `--nodebalancer-backend-ipv4-subnet-name` | String | `""` | ipv4 subnet name to use for NodeBalancer backends |
 | `--disable-nodebalancer-vpc-backends` | Boolean | `false` | don't use VPC specific ip-addresses for nodebalancer backend ips when running in VPC (set to `true` for backward compatibility if needed) |
 | `--enable-ipv6-for-loadbalancers` | Boolean | `false` | Set both IPv4 and IPv6 addresses for all LoadBalancer services (when disabled, only IPv4 is used). This can also be configured per-service using the `service.beta.kubernetes.io/linode-loadbalancer-enable-ipv6-ingress` annotation. |
-| `--enable-ipv6-for-nodebalancer-backends` | Boolean | `false` | Use IPv6 addresses for NodeBalancer service backends. If VPC-backed NodeBalancers are enabled, CCM preserves the NodeBalancer VPC configuration. Enabling this flag can migrate existing eligible NodeBalancer services from IPv4 to IPv6 backends during reconcile. This requires a dual-stack cluster and dual-stack Service configuration. If enabled, every selected backend node must have the required IPv6 address or reconciliation will fail. This can also be configured per-service using the `service.beta.kubernetes.io/linode-loadbalancer-enable-ipv6-backends` annotation. |
+| `--enable-ipv6-for-nodebalancer-backends` | Boolean | `false` | Use node public IPv6 addresses for NodeBalancer service backends. VPC IPv6 backend addresses are not supported. Can also be configured per-service using the `service.beta.kubernetes.io/linode-loadbalancer-enable-ipv6-backends` annotation. |
 | `--node-cidr-mask-size-ipv4` | Int | `24` | ipv4 cidr mask size for pod cidrs allocated to nodes |
 | `--node-cidr-mask-size-ipv6` | Int | `64` | ipv6 cidr mask size for pod cidrs allocated to nodes |
 | `--nodebalancer-prefix` | String | `ccm` | Name prefix for NoadBalancers. |

docs/configuration/loadbalancer.md

@@ -71,13 +71,16 @@ metadata:
 ```
 
 When IPv6 backends are enabled:
+- NodeBalancer backend targets use the node public IPv6 annotation `node.k8s.linode.com/public-ipv6`
+- IPv6 NodeBalancer backends are currently supported only through node public IPv6 addresses, not VPC IPv6 backend addresses
 - both VPC-backed and non-VPC-backed NodeBalancer services are affected
 - when VPC-backed NodeBalancers are enabled, CCM preserves the NodeBalancer VPC configuration instead of dropping it
 - enabling the global `--enable-ipv6-for-nodebalancer-backends` flag can migrate existing eligible NodeBalancer services from IPv4 to IPv6 backends during reconcile
 - to keep an existing Service on IPv4 while the global flag is enabled, set `service.beta.kubernetes.io/linode-loadbalancer-enable-ipv6-backends: "false"` on that Service
-- every selected backend node must have an IPv6 address in the currently selected backend path
+- every selected backend node must have a public IPv6 address available
+- if your cluster uses VPC backends, the nodes still need public IPv6 endpoints so CCM can program IPv6 NodeBalancer backends
 - the workload cluster and Service must be configured for dual-stack networking
-- reconciliation fails and CCM logs an error if a selected backend node does not have the required IPv6 address
+- reconciliation fails and CCM logs an error if a selected backend node does not have the required public IPv6 address
 
 Recommended Service configuration for IPv6 backends:
 
@@ -101,7 +104,7 @@ spec:
     app: my-app
 ```
 
-If your cluster does not provide IPv6-capable NodePort routing, the NodeBalancer may still be created with IPv6 backend addresses, but the backends will not become healthy.
+If your cluster does not provide IPv6-capable NodePort routing, the NodeBalancer may still be created with IPv6 backend addresses, but the backends will not become healthy. Likewise, if your cluster is using VPC backends but the nodes do not also have public IPv6 endpoints, IPv6 backend reconciliation will fail because CCM does not currently program VPC IPv6 backend addresses.
 
 ### Basic Configuration