fix(chart): discovery-based defaults for subnets; required endpoint and VIP

README.md

@@ -59,16 +59,35 @@ cd newcluster
 talm init -p cozystack -N myawesomecluster
 ```
 
-Boot Talos Linux node, let's say it has address `1.2.3.4`
+Edit `values.yaml` to set your cluster's control-plane endpoint. This
+is the URL every node's kubelet and kube-proxy will dial. The chart
+leaves it empty on purpose so a missed override fails loudly instead
+of silently embedding a placeholder. For cozystack VIP setups set
+`endpoint` and `floatingIP` together (same IP, single shared VIP);
+for single-node clusters use that node's routable IP and leave
+`floatingIP` blank; for multi-node with an external load balancer
+use the LB URL and leave `floatingIP` blank. Subnet-selector fields
+(`kubelet.validSubnets`, `etcd.advertisedSubnets`) are derived
+automatically from the node's default-gateway-bearing link, so no
+override is needed unless you have a multi-homed node that requires
+a specific subnet pinned.
+
+Boot Talos Linux node, let's say it has address `192.0.2.4`. Then:
+
+```yaml
+# values.yaml (single-node example matching the 192.0.2.4 node below)
+endpoint: "https://192.0.2.4:6443"
+floatingIP: ""
+```
 
 Gather node information:
 ```bash
-talm -n 1.2.3.4 -e 1.2.3.4 template -t templates/controlplane.yaml -i > nodes/node1.yaml
+talm -n 192.0.2.4 -e 192.0.2.4 template -t templates/controlplane.yaml -i > nodes/node1.yaml
 ```
 
 Edit `nodes/node1.yaml` file:
 ```yaml
-# talm: nodes=["1.2.3.4"], endpoints=["1.2.3.4"], templates=["templates/controlplane.yaml"]
+# talm: nodes=["192.0.2.4"], endpoints=["192.0.2.4"], templates=["templates/controlplane.yaml"]
 machine:
     network:
         # -- Discovered interfaces:
@@ -89,10 +108,10 @@ machine:
         interfaces:
             - interface: enx9c6b0047066c
               addresses:
-                - 1.2.3.4/26
+                - 192.0.2.4/26
               routes:
                 - network: 0.0.0.0/0
-                  gateway: 1.2.3.1
+                  gateway: 192.0.2.1
         nameservers:
             - 8.8.8.8
             - 8.8.4.4
@@ -113,7 +132,7 @@ machine:
 cluster:
     clusterName: talm
     controlPlane:
-        endpoint: https://192.168.0.1:6443
+        endpoint: https://192.0.2.4:6443
 ```
 
 > **Note:** The output format depends on the Talos version configured in `Chart.yaml` (`templateOptions.talosVersion`) or via the `--talos-version` CLI flag.

charts/cozystack/templates/_helpers.tpl

@@ -18,7 +18,27 @@ machine:
   kubelet:
     nodeIP:
       validSubnets:
+        {{- if .Values.advertisedSubnets }}
         {{- toYaml .Values.advertisedSubnets | nindent 8 }}
+        {{- else }}
+        {{- /* Fall back to the subnet of the node's default-gateway-bearing
+               link. cidrNetwork masks host bits so the emitted YAML is the
+               canonical network form (192.168.201.0/24) rather than the
+               host form (192.168.201.10/24). Dedupe after masking because
+               a link with a secondary address in the same subnet would
+               otherwise produce duplicate list entries. */ -}}
+        {{- $addrs := fromJsonArray (include "talm.discovered.default_addresses_by_gateway" .) }}
+        {{- if not $addrs }}
+        {{- fail "values.yaml: `advertisedSubnets` was left empty and talm could not derive a default from discovery. No default-gateway-bearing link was found on the node. This field is a cluster-wide subnet selector fed to kubelet and etcd; `talm template` is invoked once per node and cannot merge per-node values into one cluster value. Either set advertisedSubnets explicitly in values.yaml, or ensure the node has a default route before running `talm template`." }}
+        {{- end }}
+        {{- $subnets := list }}
+        {{- range $addrs }}
+        {{- $subnets = append $subnets (. | cidrNetwork) }}
+        {{- end }}
+        {{- range uniq $subnets }}
+        - {{ . }}
+        {{- end }}
+        {{- end }}
     extraConfig:
       cpuManagerPolicy: static
       maxPods: 512
@@ -85,7 +105,7 @@ cluster:
       {{- toYaml .Values.serviceSubnets | nindent 6 }}
   clusterName: "{{ .Chart.Name }}"
   controlPlane:
-    endpoint: "{{ .Values.endpoint }}"
+    endpoint: {{ required "values.yaml: `endpoint` must be set to the cluster control-plane URL (e.g. https://<vip>:6443). This field is cluster-wide: every node's kubelet and kube-proxy dials it, so it cannot be auto-derived from the current node's IP -- `talm template` runs once per node and has no way to reconcile per-node IPs into a single shared endpoint. For multi-node setups use a VIP (cozystack floatingIP) or an external load balancer; for single-node clusters the node's routable IP works." .Values.endpoint | quote }}
   {{- if eq .MachineType "controlplane" }}
   allowSchedulingOnControlPlanes: true
   controllerManager:
@@ -119,7 +139,23 @@ cluster:
     enabled: false
   etcd:
     advertisedSubnets:
+      {{- if .Values.advertisedSubnets }}
       {{- toYaml .Values.advertisedSubnets | nindent 6 }}
+      {{- else }}
+      {{- /* Fall back to the subnet of the node's default-gateway-bearing
+             link; cidrNetwork masks host bits to emit canonical network
+             form. Dedupe handled the same way as validSubnets above.
+             Empty discovery already errored via validSubnets' required()
+             guard, so we reach this block only when at least one address
+             was resolved. */ -}}
+      {{- $subnets := list }}
+      {{- range fromJsonArray (include "talm.discovered.default_addresses_by_gateway" .) }}
+      {{- $subnets = append $subnets (. | cidrNetwork) }}
+      {{- end }}
+      {{- range uniq $subnets }}
+      - {{ . }}
+      {{- end }}
+      {{- end }}
   {{- end }}
 {{- end }}
 

charts/cozystack/values.yaml

@@ -1,13 +1,53 @@
-endpoint: "https://192.168.100.10:6443"
+# REQUIRED. Cluster control-plane endpoint. Left empty intentionally
+# so the chart's `required` check fires loudly on a fresh install.
+# A placeholder default would silently embed a broken endpoint in
+# every rendered machine config. No auto-discovery is possible: this
+# is a cluster-wide value that every node's kubelet and kube-proxy
+# dials, not a per-node one.
+#
+# For cozystack VIP setups, set `endpoint` AND `floatingIP` below to
+# the SAME IP. floatingIP drives the per-node VIP (Layer2VIPConfig)
+# that endpoint points at; leaving them mismatched produces a cluster
+# that talks to an IP no node actually claims.
+#
+# For single-node clusters without a VIP, set `endpoint` to that
+# node's routable IP and leave `floatingIP` blank.
+#
+# For multi-node with an external load balancer, set `endpoint` to
+# the LB URL and leave `floatingIP` blank.
+#
+# Example: endpoint: "https://192.168.0.1:6443"
+endpoint: ""
+
 clusterDomain: cozy.local
-floatingIP: 192.168.100.10
+# Layer-2 VIP for cozystack multi-node setups. When set, the chart
+# emits a Layer2VIPConfig document pinning this IP as a floating
+# address on the node's primary link. MUST equal the host portion
+# of `endpoint` above, otherwise the cluster dials an IP that no
+# node actually claims. Blank by default so the shipped value never
+# silently embeds a wrong VIP -- fill in only if you want a VIP.
+# Single-node clusters and external-LB topologies leave it blank.
+# Example: floatingIP: 192.168.0.1
+floatingIP: ""
 image: "ghcr.io/cozystack/cozystack/talos:v1.12.6"
 podSubnets:
 - 10.244.0.0/16
 serviceSubnets:
 - 10.96.0.0/16
-advertisedSubnets:
-- 192.168.100.0/24
+
+# Optional override for machine.kubelet.nodeIP.validSubnets and
+# cluster.etcd.advertisedSubnets. When left empty the chart derives
+# the value from the node's default-gateway-bearing link at render
+# time (via talm.discovered.default_addresses_by_gateway), so the
+# generated machine config matches the node's actual network without
+# any values.yaml edit. Set this only when you want to pin a specific
+# subnet — typically for multi-homed nodes where the default-gateway
+# link is not the subnet you want kubelet/etcd to use.
+# Example:
+#   advertisedSubnets:
+#     - "10.0.0.0/8"
+advertisedSubnets: []
+
 oidcIssuerUrl: ""
 certSANs: []
 nr_hugepages: 0

charts/generic/templates/_helpers.tpl

@@ -13,7 +13,27 @@ machine:
   kubelet:
     nodeIP:
       validSubnets:
+        {{- if .Values.advertisedSubnets }}
         {{- toYaml .Values.advertisedSubnets | nindent 8 }}
+        {{- else }}
+        {{- /* Fall back to the subnet of the node's default-gateway-bearing
+               link. cidrNetwork masks host bits so the emitted YAML is the
+               canonical network form (192.168.201.0/24) rather than the
+               host form (192.168.201.10/24). Dedupe after masking because
+               a link with a secondary address in the same subnet would
+               otherwise produce duplicate list entries. */ -}}
+        {{- $addrs := fromJsonArray (include "talm.discovered.default_addresses_by_gateway" .) }}
+        {{- if not $addrs }}
+        {{- fail "values.yaml: `advertisedSubnets` was left empty and talm could not derive a default from discovery. No default-gateway-bearing link was found on the node. This field is a cluster-wide subnet selector fed to kubelet and etcd; `talm template` is invoked once per node and cannot merge per-node values into one cluster value. Either set advertisedSubnets explicitly in values.yaml, or ensure the node has a default route before running `talm template`." }}
+        {{- end }}
+        {{- $subnets := list }}
+        {{- range $addrs }}
+        {{- $subnets = append $subnets (. | cidrNetwork) }}
+        {{- end }}
+        {{- range uniq $subnets }}
+        - {{ . }}
+        {{- end }}
+        {{- end }}
   {{- with .Values.certSANs }}
   certSANs:
   {{- toYaml . | nindent 2 }}
@@ -33,7 +53,7 @@ cluster:
       {{- toYaml .Values.serviceSubnets | nindent 6 }}
   clusterName: "{{ .Chart.Name }}"
   controlPlane:
-    endpoint: "{{ .Values.endpoint }}"
+    endpoint: {{ required "values.yaml: `endpoint` must be set to the cluster control-plane URL (e.g. https://<vip>:6443). This field is cluster-wide: every node's kubelet and kube-proxy dials it, so it cannot be auto-derived from the current node's IP -- `talm template` runs once per node and has no way to reconcile per-node IPs into a single shared endpoint. For multi-node setups use a VIP or an external load balancer; for single-node clusters the node's routable IP works." .Values.endpoint | quote }}
   {{- if eq .MachineType "controlplane" }}
   apiServer:
     {{- with .Values.certSANs }}
@@ -42,7 +62,23 @@ cluster:
     {{- end }}
   etcd:
     advertisedSubnets:
+      {{- if .Values.advertisedSubnets }}
       {{- toYaml .Values.advertisedSubnets | nindent 6 }}
+      {{- else }}
+      {{- /* Fall back to the subnet of the node's default-gateway-bearing
+             link; cidrNetwork masks host bits to emit canonical network
+             form. Dedupe handled the same way as validSubnets above.
+             Empty discovery already errored via validSubnets' required()
+             guard, so we reach this block only when at least one address
+             was resolved. */ -}}
+      {{- $subnets := list }}
+      {{- range fromJsonArray (include "talm.discovered.default_addresses_by_gateway" .) }}
+      {{- $subnets = append $subnets (. | cidrNetwork) }}
+      {{- end }}
+      {{- range uniq $subnets }}
+      - {{ . }}
+      {{- end }}
+      {{- end }}
   {{- end }}
 {{- end }}
 

charts/generic/values.yaml

@@ -1,8 +1,29 @@
-endpoint: "https://192.168.100.10:6443"
+# REQUIRED. Cluster control-plane endpoint. Left empty intentionally
+# so the chart's `required` check fires loudly on a fresh install.
+# A placeholder default would silently embed a broken endpoint in
+# every rendered machine config. No auto-discovery is possible: this
+# is a cluster-wide value that every node's kubelet and kube-proxy
+# dials, not a per-node one. For single-node clusters set it to that
+# node's routable IP; for multi-node set it to a VIP or external LB.
+# Example: endpoint: "https://192.168.0.1:6443"
+endpoint: ""
+
 podSubnets:
 - 10.244.0.0/16
 serviceSubnets:
 - 10.96.0.0/16
-advertisedSubnets:
-- 192.168.100.0/24
+
+# Optional override for machine.kubelet.nodeIP.validSubnets and
+# cluster.etcd.advertisedSubnets. When left empty the chart derives
+# the value from the node's default-gateway-bearing link at render
+# time (via talm.discovered.default_addresses_by_gateway), so the
+# generated machine config matches the node's actual network without
+# any values.yaml edit. Set this only when you want to pin a specific
+# subnet — typically for multi-homed nodes where the default-gateway
+# link is not the subnet you want kubelet/etcd to use.
+# Example:
+#   advertisedSubnets:
+#     - "10.0.0.0/8"
+advertisedSubnets: []
+
 certSANs: []

pkg/engine/helm/engine.go

@@ -19,6 +19,7 @@ package engine
 import (
 	"fmt"
 	"log"
+	"net/netip"
 	"path"
 	"path/filepath"
 	"regexp"
@@ -218,6 +219,19 @@ func (e Engine) initFunMap(t *template.Template) {
 		}
 	}
 
+	// cidrNetwork canonicalizes a CIDR string to its network form
+	// ("192.168.201.10/24" -> "192.168.201.0/24"), matching what
+	// operators see in Talos docs and upstream examples. Sprig ships
+	// no equivalent; net/netip's ParsePrefix + Masked handles both
+	// IPv4 and IPv6 without any host-bit arithmetic in the template.
+	funcMap["cidrNetwork"] = func(cidr string) (string, error) {
+		p, err := netip.ParsePrefix(cidr)
+		if err != nil {
+			return "", fmt.Errorf("cidrNetwork: %w", err)
+		}
+		return p.Masked().String(), nil
+	}
+
 	t.Funcs(funcMap)
 }
 

pkg/engine/helm/engine_test.go

@@ -1218,3 +1218,56 @@ func TestTalosVersionConcurrentRender(t *testing.T) {
 	}
 	wg.Wait()
 }
+
+// TestCidrNetworkTemplateFunc exercises the cidrNetwork template
+// function directly (bypassing chart rendering) so a future refactor
+// that breaks parsing or masking — for either IPv4 or IPv6 inputs —
+// is caught without needing to boot the whole helm engine.
+func TestCidrNetworkTemplateFunc(t *testing.T) {
+	renderExpr := func(expr string) (string, error) {
+		chrt := &chart.Chart{
+			Metadata:  &chart.Metadata{Name: "cidrtest"},
+			Templates: []*chart.File{{Name: "templates/out.yaml", Data: []byte(expr)}},
+			Values:    map[string]any{},
+		}
+		var eng Engine
+		out, err := eng.Render(chrt, chartutil.Values{"Values": map[string]any{}})
+		if err != nil {
+			return "", err
+		}
+		return out["cidrtest/templates/out.yaml"], nil
+	}
+
+	tests := []struct {
+		name    string
+		input   string
+		want    string
+		wantErr bool
+	}{
+		{"ipv4 host form", "192.168.201.10/24", "192.168.201.0/24", false},
+		{"ipv4 already canonical", "10.0.0.0/8", "10.0.0.0/8", false},
+		{"ipv4 narrow prefix", "192.168.201.10/31", "192.168.201.10/31", false},
+		{"ipv6 host form", "2001:db8::1/64", "2001:db8::/64", false},
+		{"ipv6 already canonical", "fd00::/8", "fd00::/8", false},
+		{"malformed missing prefix", "192.168.201.10", "", true},
+		{"malformed garbage", "not-a-cidr", "", true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := renderExpr(fmt.Sprintf(`{{ cidrNetwork %q }}`, tt.input))
+			if tt.wantErr {
+				if err == nil {
+					t.Errorf("expected error for input %q, got output %q", tt.input, got)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error for %q: %v", tt.input, err)
+			}
+			if got != tt.want {
+				t.Errorf("cidrNetwork(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}