fix(routes): reject IPv6 routes early (#1280)

Detect IPv6 destination CIDRs up front and return a clear error
without issuing an API call. Also document that the route
controller manages IPv4 routes exclusively.

Fixes #659

Author: lukasmetzner

docs/explanation/private-networks.md

@@ -27,6 +27,8 @@ It is enabled by default, if a networking is enabled and a Private Network ID or
 
 To utilize this feature you need to use a CNI, which supports using the native routing capability of the infrastructure. As an example, Cilium can be set to use the [`routing-mode: native`](https://docs.cilium.io/en/stable/network/concepts/routing/#native-routing).
 
+Private Networks only support IPv4, so the route controller manages IPv4 routes exclusively. In a dual-stack cluster it will not create routes for IPv6 pod CIDRs; IPv6 connectivity must be handled separately (e.g. natively by your CNI).
+
 ### IP Range Considerations
 
 When using the route controller you need to make some considerations on the IP ranges for the cluster and service CIDR. By default, Kubernetes will allocate a `/24` subnet for each node. Depending on the amount of nodes you plan to add to the cluster you need to choose your cluster CIDR accordingly.

hcloud/routes.go

@@ -129,6 +129,22 @@ func (r *routes) CreateRoute(ctx context.Context, _ string, _ string, route *clo
 	metrics.OperationCalled.WithLabelValues(op).Inc()
 	ctx = cache.SetSubsystem(ctx, "routes")
 
+	// Parse and return early if we detect IPv6 routes.
+	// Private Networks don't support IPv6, so we can save an API
+	// request by validating beforehand.
+	ip, ipNet, err := net.ParseCIDR(route.DestinationCIDR)
+	if err != nil {
+		return fmt.Errorf("%s: %w", op, err)
+	}
+	if ip.To4() == nil {
+		return fmt.Errorf(
+			"%s: can't create route %q via node %q: private networks do not support IPv6",
+			op,
+			ipNet.String(),
+			route.TargetNode,
+		)
+	}
+
 	node, gateway, err := r.resolveRouteTarget(ctx, string(route.TargetNode))
 	if err != nil {
 		return fmt.Errorf("%s: error resolving route target: %w", op, err)
@@ -140,15 +156,10 @@ func (r *routes) CreateRoute(ctx context.Context, _ string, _ string, route *clo
 		return fmt.Errorf("%s: IP %s not part of routes target addresses", op, gateway.String())
 	}
 
-	_, cidr, err := net.ParseCIDR(route.DestinationCIDR)
-	if err != nil {
-		return fmt.Errorf("%s: %w", op, err)
-	}
-
-	r.warnCIDRMismatch(cidr, node)
+	r.warnCIDRMismatch(ipNet, node)
 
-	if err := r.upsertRoute(ctx, gateway, cidr, string(route.TargetNode)); err != nil {
-		return fmt.Errorf("error upserting route %q via %q: %w", cidr.String(), gateway.String(), err)
+	if err := r.upsertRoute(ctx, gateway, ipNet, string(route.TargetNode)); err != nil {
+		return fmt.Errorf("error upserting route %q via %q: %w", ipNet.String(), gateway.String(), err)
 	}
 
 	return nil

hcloud/routes_test.go

@@ -253,6 +253,31 @@ func TestRoutes_CreateRoute_RobotProviderID(t *testing.T) {
 	assert.ErrorContains(t, err, "not a cloud server")
 }
 
+// TestRoutes_CreateRoute_IPv6 asserts that an IPv6 destination CIDR is rejected early with a
+// clear error.
+func TestRoutes_CreateRoute_IPv6(t *testing.T) {
+	env := newTestEnv()
+	defer env.Teardown()
+
+	env.Mux.HandleFunc("/networks/1", func(w http.ResponseWriter, _ *http.Request) {
+		json.NewEncoder(w).Encode(schema.NetworkGetResponse{
+			Network: schema.Network{ID: 1, Name: "network-1", IPRange: "10.0.0.0/8"},
+		})
+	})
+
+	routes, err := newRoutes(env.Client, 1, DefaultClusterCIDR, env.Recorder, nodeLister(t), env.ServerCache)
+	require.NoError(t, err)
+
+	err = routes.CreateRoute(context.TODO(), "my-cluster", "route", &cloudprovider.Route{
+		TargetNode:      "node15",
+		DestinationCIDR: "2001:cafe:42::/64",
+	})
+	require.Error(t, err)
+	assert.ErrorContains(t, err, "private networks do not support IPv6")
+	// The target node must be named in the error, not left blank (route.Name is unset here).
+	assert.ErrorContains(t, err, "node15")
+}
+
 // TestRoutes_CreateRoute_NodeNameDrift proves the routes controller still works when the
 // k8s node name differs from the hcloud server name — the core fix in this PR. The server is
 // resolved by its immutable ProviderID rather than by k8s node name.