fix: make Tailscale network intent plan-known

Author: mysticaltech

.claude/skills/kh-assistant/SKILL.md

@@ -281,7 +281,7 @@ Core rules:
 - Invert positive/negative booleans carefully.
 - Remove `network_id = 0`; omitted/null means the primary Network in v3.
 - Remove control-plane `network_id`; control planes stay on the primary Network.
-- For secure Tailnet access or private multinetwork scale, prefer `node_transport_mode = "tailscale"`. For v2-to-v3 upgrades, introduce large multinetwork scale in a separate audited plan after the base upgrade. Tailscale mode keeps Kubernetes node IPs on Hetzner private addresses and can advertise node-private `/32` routes with Tailscale subnet-route SNAT disabled.
+- For secure Tailnet access or private multinetwork scale, prefer `node_transport_mode = "tailscale"`. For v2-to-v3 upgrades, introduce large multinetwork scale in a separate audited plan after the base upgrade. Tailscale mode keeps Kubernetes node IPs on Hetzner private addresses and can advertise node-private `/32` routes with Tailscale subnet-route SNAT disabled. Active agent/autoscaler nodepools in Tailscale mode must set `network_scope = "primary"` or `network_scope = "external"` so invalid same-root external Network configs fail at plan time.
 - Do not suggest Calico with Tailscale node transport yet. Flannel is first supported; Cilium is still explicitly experimental in this transport mode.
 - For Cloudflare, recommend only the external Access/Tunnel pattern for kube API, SSH, Rancher, Grafana, or ingress. Do not suggest Cloudflare Mesh/WARP as kube-hetzner node transport and do not invent Cloudflare provider inputs.
 - Run `terraform fmt -recursive`, `terraform init -upgrade`, `terraform validate`, and `terraform plan -out=v3-upgrade.tfplan`.
@@ -452,17 +452,18 @@ tailscale_node_transport = {
     mode = "auth_key"
   }
   routing = {
-    # Single-network clusters may set false; external network_id nodepools need true.
+    # Single-network clusters may set false; network_scope = "external" nodepools need true.
     advertise_node_private_routes = false
   }
 }
 ```
 
 Rules to mention:
-- Tailnet ACLs must auto-approve advertised Hetzner node-private `/32` routes when external `network_id` nodepools are used.
+- Tailscale mode requires explicit `network_scope = "primary"` or `"external"` on every active agent/autoscaler nodepool. Use `"primary"` when `network_id` is omitted/null; use `"external"` with external `network_id`, including same-root `hcloud_network.*.id`.
+- Tailnet ACLs must auto-approve advertised Hetzner node-private `/32` routes when external `network_scope` nodepools are used.
 - The module disables Tailscale subnet-route SNAT for node/CNI traffic.
 - Flannel VXLAN is first supported; Cilium needs the experimental flag; Calico is rejected.
-- Managed Hetzner private LBs are fine for single-primary-network clusters; external `network_id` nodepools need public LB targets or non-Hetzner/private alternatives.
+- Managed Hetzner private LBs are fine for single-primary-network clusters; external `network_scope` nodepools need public LB targets or non-Hetzner/private alternatives.
 - The module NAT router only gives egress to the primary Hetzner Network; external-network Tailscale nodepools need public egress or an external bootstrap path.
 - Large examples live in `examples/tailscale-node-transport/large-scale-200.tf.example` and `examples/tailscale-node-transport/massive-10000-nodes.tf.example`.
 - The 200-node static example is `3 control planes + 97 primary agents + 100 agents on one external Network`; both Networks are exactly at Hetzner's 100-attachment limit and placement groups auto-shard to 21 groups.

.claude/skills/migrate-v2-to-v3/SKILL.md

@@ -168,9 +168,13 @@ terraform show -json v3-upgrade.tfplan \
 - Tailscale mode keeps Kubernetes node IPs on Hetzner private addresses and
   can advertise node-private `/32` routes with Tailscale subnet-route SNAT
   disabled. Single-network clusters may disable route advertisement; external
-  `network_id` nodepools require route advertisement and Tailnet auto-approval.
+  `network_scope = "external"` nodepools require route advertisement and Tailnet
+  auto-approval.
 - External agent/autoscaler Network IDs must be positive Hetzner Network IDs.
-  Omit/null means the primary Network.
+  Omit/null means the primary Network. In Tailscale mode, active
+  agent/autoscaler nodepools must also set `network_scope = "primary"` or
+  `network_scope = "external"` so same-root external Network IDs validate
+  during `terraform plan`.
 - Do not add new optional v3 features such as `cilium_gateway_api_enabled`,
   `embedded_registry_mirror`, new Tailscale multinetwork shards, or external
   Cloudflare Access/Tunnel routing during the same first in-place v2-to-v3

.claude/skills/prepare-release/SKILL.md

@@ -237,6 +237,8 @@ For v3, additionally verify the Tailscale node-transport surfaces stay aligned:
 private multinetwork path, Flannel is first supported, Cilium is experimental,
 Calico is rejected, subnet-route SNAT is disabled when advertising routes,
 single-network examples may disable node-private route advertisement, and
+active Tailscale agent/autoscaler nodepools set `network_scope` explicitly so
+same-root external Network IDs are validated during `terraform plan`,
 external-overlay docs still describe only user-owned operator
 access/post-bootstrap features.
 

CHANGELOG.md

@@ -46,7 +46,7 @@ This is the v3 major-release line. Before upgrading from any `v2.x` release:
 - **Cilium v3 Dual-Stack Defaults** - Cilium now renders IPv4/IPv6 Helm values from the configured cluster CIDRs and keeps kube-proxy replacement tied to `enable_kube_proxy = false` (#2170, #2178).
 - **Cilium Gateway API Support** - Added `cilium_gateway_api_enabled` to install standard Gateway API CRDs for the selected Cilium line, enable Cilium `gatewayAPI.enabled`, and wire cert-manager Gateway API support. Added `examples/cilium-gateway-api`.
 - **Cilium Multinetwork Public Overlay Preview** - Added gated `multinetwork_mode = "cilium_public_overlay"` plumbing for Cilium-only clusters spanning multiple Hetzner Networks, including public IPv4/IPv6/dual-stack transport selection, WireGuard/tunnel defaults, public load-balancer targeting, control-plane fanout removal, and one Cluster Autoscaler Deployment per effective `network_id`. This path now requires `enable_experimental_cilium_public_overlay = true` and is not production-supported until the live datapath E2E passes.
-- **Tailscale Node Transport** - Added opt-in `node_transport_mode = "tailscale"` for secure single-network clusters and supported private multinetwork scale-out. The module can bootstrap Tailscale, use MagicDNS for Terraform/kubeconfig access, optionally advertise each node's Hetzner private `/32` route with subnet-route SNAT disabled, keep Kubernetes node IPs on Hetzner private addresses, validate Tailnet/firewall/CNI/load-balancer constraints at plan time, and render autoscaler nodes with per-Network Tailscale bootstrap. Flannel is the first supported CNI; Cilium remains gated as experimental for this transport until live datapath coverage promotes it.
+- **Tailscale Node Transport** - Added opt-in `node_transport_mode = "tailscale"` for secure single-network clusters and supported private multinetwork scale-out. The module can bootstrap Tailscale, use MagicDNS for Terraform/kubeconfig access, optionally advertise each node's Hetzner private `/32` route with subnet-route SNAT disabled, keep Kubernetes node IPs on Hetzner private addresses, validate Tailnet/firewall/CNI/load-balancer constraints at plan time with explicit nodepool `network_scope`, and render autoscaler nodes with per-Network Tailscale bootstrap. Flannel is the first supported CNI; Cilium remains gated as experimental for this transport until live datapath coverage promotes it.
 - **Embedded Registry Mirror** - Added `embedded_registry_mirror` for trusted large clusters, enabling k3s/RKE2's embedded Spegel mirror while preserving user `registries_config` entries.
 - **Placement Group Auto-Sharding** - Count-based nodepools without an explicit `placement_group` now shard implicit Hetzner spread placement groups every 10 servers; explicit placement groups still fail validation above Hetzner's 10-server limit.
 - **Large-Scale Tailscale Examples** - Added +100-node and 10,000-total-node Tailscale node-transport reference examples that account for Hetzner Network attachment limits, placement-group limits, autoscaler shards, and the public-IP/Tailnet exposure model.
@@ -66,7 +66,8 @@ This is the v3 major-release line. Before upgrading from any `v2.x` release:
 - **Terraform 1.15 Validation Compatibility** - Moved cross-variable and local-dependent module contract checks from input-variable validation blocks into a hard `terraform_data.validation_contract` precondition surface, preserving plan-time failures while allowing Terraform 1.15.0 to initialize and validate the module.
 - **Tailscale Volume Provisioning Ordering** - Agent Longhorn and attached-volume configuration now waits for Tailscale agent bootstrap before using Tailnet MagicDNS SSH targets.
 - **Tailscale Auth-Key Ergonomics** - `auth_key` mode no longer advertises kube-hetzner tags by default, so simple pre-auth keys work without Tailnet `tagOwners`; tagged nodes remain an explicit opt-in and OAuth mode now validates that tag-scoped auth is configured.
-- **Tailscale Single-Network Ergonomics** - Tailscale mode now cleanly supports ordinary single-network clusters: node-private route advertisement can be disabled when no external `network_id` nodepools are used, private control-plane Load Balancers are allowed, and private managed ingress Load Balancers are rejected only for external-network scale-out.
+- **Tailscale Single-Network Ergonomics** - Tailscale mode now cleanly supports ordinary single-network clusters: node-private route advertisement can be disabled when no `network_scope = "external"` nodepools are used, private control-plane Load Balancers are allowed, and private managed ingress Load Balancers are rejected only for external-network scale-out.
+- **Tailscale Same-Root Network Validation** - Tailscale static agent and autoscaler nodepools now use explicit `network_scope = "primary" | "external"` intent, so invalid same-root external Network configurations fail during `terraform plan` even when `network_id` is not known until apply.
 - **Placement Group Disable/Limit Semantics** - `enable_placement_groups = false` now stops creating unused placement-group resources, and plan-time validation enforces Hetzner's 50-placement-group project limit before large static topologies hit provider errors.
 - **Same-Root Tailscale External Networks** - In Tailscale transport mode, nodepool `network_id` values can come from Hetzner Network resources created in the same Terraform root because control planes no longer need apply-time fanout attachments to every external agent Network.
 - **Cloud-Init Health-Checker Race** - Host and autoscaler cloud-init now masks Leap Micro/MicroOS `health-checker.service` before `cloud-final` to prevent a systemd ordering-cycle race that can skip first-boot Kubernetes bootstrap on autoscaled nodes.

MIGRATION.md

@@ -328,13 +328,17 @@ Current behavior:
   `network_id` is omitted or null. Set a positive Hetzner Network ID only for an
   external network, and use either Tailscale node transport or the Cilium public
   overlay preview for autoscaler external networks.
+- In `node_transport_mode = "tailscale"`, active agent and autoscaler nodepools
+  must also set `network_scope = "primary"` or `network_scope = "external"`.
+  This makes the topology plan-known when `network_id` comes from a same-root
+  `hcloud_network` resource.
 - In default mode, control planes may attach to external agent networks for
   compatibility with the existing private-network behavior.
 - In `node_transport_mode = "tailscale"`, control-plane fanout is disabled,
   Kubernetes keeps Hetzner private node IPs, and Tailscale can advertise each
   node's Hetzner private `/32` route with subnet-route SNAT disabled. Route
   advertisement can be disabled for single-primary-network clusters; it must
-  stay enabled for external `network_id` nodepools.
+  stay enabled for `network_scope = "external"` nodepools.
 - In `multinetwork_mode = "cilium_public_overlay"`, control-plane fanout is
   disabled and Cilium uses public IPv4/IPv6 transport with WireGuard encryption
   for pod-to-pod reachability across Hetzner Network islands.
@@ -349,7 +353,7 @@ Current behavior:
 
 Do not turn an existing v2 cluster into a large multinetwork cluster as part of
 the same first v3 apply. Upgrade cleanly first, then introduce Tailscale
-transport or new external `network_id` nodepools in a separate audited plan, or
+transport or new `network_scope = "external"` nodepools in a separate audited plan, or
 use blue/green.
 
 ## Post-upgrade verification checklist

README.md

@@ -132,7 +132,7 @@ Only apply after reviewing all planned resource actions.
 | Private-only | `nat_router` plus private control-plane LB on the primary Network. |
 | Secure operator/API access | `node_transport_mode = "tailscale"` with public API/SSH firewall sources closed. |
 | Cloudflare-protected operator/app access | Keep Tailscale or Hetzner private transport underneath; put user-managed Cloudflare Access/Tunnel in front of kube API, SSH, Rancher, or ingress endpoints. |
-| More than 100 Cloud nodes | Tailscale node transport plus external `network_id` shards, one Hetzner Network per 100-node budget. |
+| More than 100 Cloud nodes | Tailscale node transport plus `network_scope = "external"` shards, one Hetzner Network per 100-node budget. |
 | Very large reference | Autoscaler-first Tailscale multinetwork; see the 200-node and 10k-node examples. |
 | Cilium Gateway API | Cilium, `enable_kube_proxy = false`, `cilium_gateway_api_enabled = true`. |
 | Heavy image-pull pressure | `embedded_registry_mirror.enabled = true` on trusted clusters. |
@@ -1154,10 +1154,21 @@ tailscale_node_transport = {
 # Tailscale mode deliberately rejects public world-open API/SSH defaults.
 firewall_kube_api_source = null
 firewall_ssh_source      = null
+
+# Every active Tailscale agent/autoscaler nodepool sets network_scope explicitly.
+# Use "primary" when network_id is omitted/null.
+# agent_nodepools = [{
+#   name = "agent", server_type = "cx23", location = "nbg1",
+#   labels = [], taints = [], count = 2, network_scope = "primary"
+# }]
 ```
 
-Multinetwork scale-out adds external `network_id` values and requires approved
-node-private routes:
+Multinetwork scale-out adds `network_scope = "external"` nodepools with
+external `network_id` values and requires approved node-private routes. Set
+`network_scope` explicitly in Tailscale mode so
+Terraform can validate primary-vs-external Network intent during `plan`, even
+when a `network_id` comes from an `hcloud_network` resource created in the same
+root.
 
 ```tf
 node_transport_mode = "tailscale"
@@ -1194,6 +1205,7 @@ agent_nodepools = [
     taints      = []
     count       = 50
     # network_id omitted/null means the primary kube-hetzner network.
+    network_scope = "primary"
   },
   {
     name        = "agent-small-b"
@@ -1202,7 +1214,8 @@ agent_nodepools = [
     labels      = []
     taints      = []
     count       = 50
-    network_id  = 11959154 # existing external private network id
+    network_id    = 11959154 # existing external private network id
+    network_scope = "external"
   },
 ]
 
@@ -1213,14 +1226,16 @@ autoscaler_nodepools = [
     location    = "nbg1"
     min_nodes   = 0
     max_nodes   = 50
+    network_scope = "primary"
   },
   {
     name        = "autoscaled-b"
     server_type = "cx23"
     location    = "nbg1"
     min_nodes   = 0
     max_nodes   = 50
-    network_id  = 11959154
+    network_id    = 11959154
+    network_scope = "external"
   },
 ]
 ```
@@ -1245,7 +1260,9 @@ The important constraints are enforced during `terraform plan`:
 - Control planes always stay on the primary kube-hetzner network and no longer
   accept `network_id`.
 - Static agents and autoscaler nodepools may use `network_id` to spread across
-  existing Hetzner private Networks.
+  existing Hetzner private Networks. In Tailscale mode, every active static
+  agent node, agent nodepool, and autoscaler nodepool must set
+  `network_scope = "primary"` or `network_scope = "external"`.
 - Control planes are not auto-attached to every external agent Network, avoiding
   Hetzner's 3-Networks-per-server limit.
 - The module can advertise each node's Hetzner private `/32` route through
@@ -1254,8 +1271,8 @@ The important constraints are enforced during `terraform plan`:
   source IP.
 - Single-network clusters may set
   `tailscale_node_transport.routing.advertise_node_private_routes = false` to
-  avoid Tailnet route approvals. External `network_id` nodepools require the
-  default `true`.
+  avoid Tailnet route approvals. Any nodepool with `network_scope = "external"`
+  requires the default `true`.
 - For multinetwork clusters, Tailnet ACLs must auto-approve node-private routes
   for the users, groups, or node tags you use, or the cluster will wait for
   manual route approval. Tags are optional in `auth_key` mode, but they are the