K3S integrates with Netbird and TailScale for dynamic IP updates, balancing simplicity and control with tradeoffs in network overhead and security.

Context

K3S nodes in dynamic environments (edge, cloud, or hybrid) often face flapping IPs due to DHCP, scaling, or network churn. Manual IP updates break automation and risk service outages. Tools like Netbird and TailScale automate peer discovery and overlay networking, but introduce complexity.

Actionable Workflow

1. Install K3S: Use the official installer with --disable=traefik if replacing with a mesh-compatible ingress.
2. Deploy Netbird or TailScale:
   • Netbird: Deploy via Helm:

     helm repo add netbird https://netbird.io/helm-charts  
     helm install netbird netbird/netbird --create-namespace -n netbird  
     

   • TailScale: Use the daemonset manifest from docs.
3. Configure Auto-Registration:
   • Annotate K3S nodes with netbird.io/agent: "true" or use TailScale’s --node=auto flag.
   • Validate peers:

     kubectl exec -it netbird-0 -- /usr/local/bin/netbird peers  
     

4. Update K3S Configuration:
   • Set clusterCIDR in /etc/rancher/k3s/k3s.yaml to match the overlay network range.
   • Restart K3S: systemctl restart k3s.
5. Test Connectivity:
   • Deploy a test pod and verify it can reach services via overlay IPs:

     kubectl run test --image=alpine --rm -i /bin/sh  
     / # ping <overlay-ip>  
     

Policy Example

Netbird Network Policy (restrict access to registered nodes only):

apiVersion: networking.k8s.io/v1  
kind: NetworkPolicy  
metadata:  
  name: allow-netbird-peers  
spec:  
  podSelector: {}  
  ingress:  
  - from:  
    - ipBlock:  
        cidr: 10.0.0.0/24  # Netbird overlay CIDR  

Tooling

• Netbird: Open-source, WireGuard-based, lightweight. Best for small teams needing simplicity.
• TailScale: Commercial support, richer features (e.g., Tailscale SSH, MagicDNS). Better for enterprises.
• Alternatives: Cilium (for native Kubernetes networking), Calico (policy-heavy).

Tradeoffs

• Netbird: Limited enterprise support; overlay traffic may increase latency.
• TailScale: Dependency on Tailscale’s infrastructure; costs scale with nodes.
• Both: Introduce failure points (e.g., agent crashes, key rotation delays).

Troubleshooting

• Nodes Not Registering:
  • Check firewall rules: Allow UDP 41641 (Netbird) or 41641/TCP+UDP (TailScale).
  • Verify DNS resolves the control plane: nslookup <control-plane-host>.
• Connectivity Failures:
  • Inspect agent logs:

    kubectl logs -n netbird netbird-0  
    

  • Check overlay interface: ip a show tun0 (Netbird) or ip a show tailscale0.
• IP Conflicts:
  • Ensure clusterCIDR in K3S config matches the overlay network range.
  • Use kubectl get nodes -o wide to validate node IPs.

Prevention

• Monitor agent health with Prometheus alerts on netbird_agent_status or tailscale_node_status.
• Automate key rotation using tools like Vault or the cloud provider’s secrets manager.
• Test failover by simulating agent restarts or network partitions in staging.

This approach balances automation with operational control, but requires ongoing monitoring to mitigate tradeoffs.

Source thread: Does anyone use K3S with Netbird or TailScale for updating IPs?