Adding TailScale to an existing k3s cluster simplifies secure networking but requires careful node configuration and firewall adjustments.

Workflow: TailScale Integration with k3s

1. Install k3s
   Use the official install script with any required flags (e.g., --server for the master node):

   curl -sfL https://get.k3s.io | sh -  
   

2. Install TailScale Operator
   Deploy via krew (Kubernetes CLI tool for plugins):

   krew install tailscale  
   

   Or manually apply the TailScale manifest:

   kubectl apply -f https://raw.githubusercontent.com/tailscale/tailscale-k8s/main/deploy/tailscale.yaml  
   

3. Authenticate and Join Nodes
   On each node (including the k3s server):

   sudo tailscale up --auth-key=<AUTH_KEY>  
   

   Replace <AUTH_KEY> with your TailScale authentication key from the web UI.

4. Verify Cluster Connectivity
   Check node IPs in the TailScale subnet:

   tailscale status  
   

   Ensure all nodes show as “ready” in kubectl get nodes.

Policy Example: Restrict Access to Subnet

Use TailScale’s subnet routing to limit access to specific services:

# Allow only 10.0.0.0/24 subnet to access the cluster  
tailscale set --subnet=10.0.0.0/24  

For granular control, apply network policies in Kubernetes alongside TailScale’s ACLs.

Tooling

• k3s: Lightweight Kubernetes distribution (ideal for edge or small clusters).
• TailScale CLI: For node authentication and subnet configuration.
• krew: For installing TailScale operator and other Kubernetes tools.
• Monitoring: Use Prometheus/Grafana to track network latency and packet loss post-integration.

Tradeoffs

• Pros:
  • Simplifies cross-cluster and hybrid-cloud connectivity.
  • Automatic encryption and NAT traversal reduce firewall headaches.
• Cons:
  • Adds dependency on TailScale’s DERP relays (potential latency).
  • Not ideal for high-throughput workloads (e.g., video processing).
  • Costs scale with node count for paid tiers.

Troubleshooting

Common Issues:

• Nodes Not Joining:
  • Check firewall rules blocking UDP port 4160.
  • Verify tailscale service is running: systemctl status tailscale.
• DNS Resolution Failures:
  • Ensure coresdns is configured to use TailScale’s DNS:

    tailscale set --dns=auto  
    

• Intermittent Connectivity:
  • Inspect logs for DERP relay timeouts:

    journalctl -u tailscale -n 100 --since "5 minutes ago"  
    

Validation:

• Ping between nodes using their TailScale IPs:

  ping <TAILSCALE_IP>  
  

• Test service reachability via Kubernetes services.

Prevention

• Firewall Rules: Allow UDP 4160 and ICMP for DERP relay reliability.
• Node Labels: Tag nodes with tailscale.io/subnet for policy enforcement.
• Backup Auth Keys: Rotate keys periodically and avoid reusing them across environments.

TailScale streamlines secure networking for k3s but isn’t a silver bullet. Use it where simplicity and encryption outweigh strict performance or control requirements.

Source thread: Who has added TailScale (NetBird?) VPN to their setup? Is it easier to add it after, setting up k3s?