fix(talos): pin kubelet node IP for NetBird

docs/decisions/0003-talos-native-remote-access.md

@@ -15,6 +15,8 @@ Use NetBird Cloud for coordination and relay, with the NetBird client running as
 
 Run NetBird below Kubernetes. Do not deploy it as a DaemonSet, subnet-router pod, or separate LAN VM. Keep the Talos API on TCP 50000 and the Kubernetes API on TCP 6443 reachable only from the administrator workstation group.
 
+Because the NetBird interface makes Talos multihomed, restrict kubelet node-IP selection to the physical LAN. This prevents the overlay address from replacing the Kubernetes node `InternalIP` while preserving direct Talos API access through NetBird.
+
 Upgrade Talos from v1.11.5 to v1.12.11 before enabling NetBird because v1.11.5 has no NetBird extension artifact. Keep Kubernetes on v1.34.1 during this operating-system change.
 
 ## Consequences

talos/machineconfigs/nitro-5.machine.patch.yaml

@@ -10,6 +10,9 @@ machine:
     image: factory.talos.dev/metal-installer/6da7b4e2db4c4bdf73bf98fcdcb689b2abb21567c57082a8413742b96851ee33:v1.12.11
     wipe: false
   kubelet:
+    nodeIP:
+      validSubnets:
+        - 192.168.1.0/24
     extraMounts:
       - destination: /var/mnt/longhorn
         type: bind

talos/machineconfigs/optiplex-7040.machine.patch.yaml

@@ -9,6 +9,9 @@ machine:
     image: factory.talos.dev/metal-installer/f141fc2a08d5a459a80d871faa48d7dc92bc354e4faf6cdbafe1cc0fac717991:v1.12.11
     wipe: false
   kubelet:
+    nodeIP:
+      validSubnets:
+        - 192.168.1.0/24
     extraMounts:
       - destination: /var/mnt/longhorn
         type: bind

talos/netbird/README.md

@@ -11,6 +11,8 @@ NetBird runs as a Talos extension service on each physical node. It is independe
 
 NetBird is not present in the Talos v1.11.5 extension catalog. Do not attempt to use the v1.12 extension with the current operating system and do not substitute a Kubernetes pod for recovery access.
 
+NetBird makes each enrolled node multihomed. Kubelet must be restricted to `192.168.1.0/24` before the extension starts, otherwise it can publish the NetBird address as the node `InternalIP` and break control-plane, Cilium, and CSI traffic. Keep NetBird in its default kernel mode.
+
 ## NetBird account preparation
 
 Complete these control-plane steps before changing a Talos node:
@@ -45,8 +47,23 @@ Use a `talosctl` client matching the running Talos v1.11.5 cluster to initiate t
 
 For each node, build a private temporary full configuration from the live main document, every required auxiliary document, and `../patches/netbird.extensionserviceconfig.example.yaml`. Confirm the intended node twice before continuing.
 
+First inspect the live machine configuration. If the constraint is missing, apply this patch once to pin kubelet to the physical LAN, then verify that Kubernetes still reports the node's LAN address:
+
 ```bash
 NETBIRD_NODE=192.168.1.10
+KUBERNETES_NODE=talos-opt-7040
+
+talosctl --nodes "$NETBIRD_NODE" patch machineconfig \
+  --patch @talos/patches/netbird.node-ip.patch.yaml \
+  --mode=no-reboot
+
+kubectl get node "$KUBERNETES_NODE" \
+  --output jsonpath='{.status.addresses[?(@.type=="InternalIP")].address}{"\n"}'
+```
+
+Do not continue unless the result is the node's `192.168.1.x` address. The committed worker machine patches carry the same constraint for future rendered configurations.
+
+```bash
 NETBIRD_CONFIG_PATH="$(mktemp)"
 NETBIRD_DRY_RUN_PATH="$(mktemp)"
 trap 'shred -u "$NETBIRD_CONFIG_PATH" "$NETBIRD_DRY_RUN_PATH"' EXIT
@@ -96,7 +113,7 @@ talosctl --nodes "$NETBIRD_NODE" apply-config \
 
 shred -u "$NETBIRD_CONFIG_PATH" "$NETBIRD_DRY_RUN_PATH"
 trap - EXIT
-unset NETBIRD_CONFIG_PATH NETBIRD_DRY_RUN_PATH NETBIRD_EXTRA_DOCUMENTS NETBIRD_NODE NETBIRD_SOURCE_PATH
+unset KUBERNETES_NODE NETBIRD_CONFIG_PATH NETBIRD_DRY_RUN_PATH NETBIRD_EXTRA_DOCUMENTS NETBIRD_NODE NETBIRD_SOURCE_PATH
 ```
 
 Perform the dry run while the placeholder is still present so no real key appears in the diff. Keep the output private because unchanged context can contain existing machine-configuration secrets. It must add only one `ExtensionServiceConfig` document named `netbird`. On the OptiPlex, the diff must not delete or alter `VolumeConfig/EPHEMERAL` or `UserVolumeConfig/longhorn`. Applying the NetBird document alone removes those auxiliary documents and is prohibited.
@@ -118,6 +135,7 @@ talosctl upgrade --nodes 192.168.1.10 \
 Do not continue until:
 
 - the node is Ready and reports Talos v1.12.11;
+- Kubernetes still reports `192.168.1.10` as the node `InternalIP`, and `kubectl logs` or `kubectl exec` can reach a pod on it;
 - `talosctl get extensions` lists `netbird`, `intel-ucode`, `iscsi-tools`, and `util-linux-tools`;
 - `talosctl service ext-netbird` is healthy and its logs contain no enrollment loop;
 - `u-longhorn` is mounted at `/var/mnt/longhorn`;

talos/patches/README.md

@@ -3,3 +3,5 @@
 Reusable Talos configuration patches, applied on top of the base machine configs so common settings are defined once and shared across nodes rather than copied into each machineconfig.
 
 `netbird.extensionserviceconfig.example.yaml` is a secret-free enrollment template. Append it to the complete live configuration for exactly one node, including that node's auxiliary volume documents, dry-run the full document set, then insert a one-off setup key and apply it. Never commit or paste a live setup key.
+
+`netbird.node-ip.patch.yaml` pins kubelet node traffic to the physical LAN so the NetBird interface cannot replace the Kubernetes `InternalIP`.

talos/patches/netbird.node-ip.patch.yaml

@@ -0,0 +1,6 @@
+# Keep Kubernetes node traffic on the physical LAN after NetBird adds wt0.
+machine:
+  kubelet:
+    nodeIP:
+      validSubnets:
+        - 192.168.1.0/24