wirekube

README

WireKube

Connect Kubernetes nodes across any network — no VPN server required.

WireKube builds a WireGuard mesh between your Kubernetes nodes using CRDs for coordination. It keeps a relay path available when configured, probes direct connectivity, and preserves WireGuard payload encryption across both paths.

Documentation

When to Use WireKube

• Multi-cloud / hybrid clusters — Your Kubernetes nodes span AWS, GCP, on-prem, or home labs, and they need to communicate directly at the node level without VPC peering or dedicated VPN appliances.

• Nodes behind NAT — You have on-premises or edge nodes behind restrictive NATs that need to join a cloud-hosted cluster. WireKube detects NAT types and finds the best path automatically.

• EKS Hybrid Nodes / managed K8s with remote nodes — Managed Kubernetes services with remote worker nodes that lack direct network connectivity to the control plane VPC.

• Lightweight node-to-node encryption — You want WireGuard encryption between nodes without deploying a full-blown VPN infrastructure or modifying your CNI.

How It Works

flowchart LR
    subgraph VPC-A["Cloud VPC"]
        N1[node-1]
    end
    subgraph VPC-B["Another VPC"]
        N2[node-2]
    end
    subgraph Home["On-Prem"]
        N3[node-3]
    end
    N1 <-->|"WireGuard P2P"| N2
    N1 <-->|"WireGuard P2P"| N3
    N2 <-->|"WireGuard P2P"| N3

1. An Agent DaemonSet runs on each node, creates a WireGuard TUN (wireguard-go userspace), and discovers its public endpoint via STUN.
2. Each agent registers itself as a WireKubePeer CRD. All agents watch all peers and configure WireGuard through a custom Bind layer.
3. The custom Bind runs a bimodal warm-relay datapath: when direct is unproven or flapping, every packet is duplicated on both the direct UDP leg and the relay TCP leg. WireGuard's replay counter dedupes on the receiver, so blackouts are bounded by the 3-second trust window instead of by control-plane sync intervals.
4. When direct receive stalls, the bind fires a BimodalHint through the relay to pull the remote peer into dual-send too. This fixes asymmetric (one-way) UDP drops that would otherwise take ~30s to recover.
5. The per-peer PathMonitor FSM promotes Relay → Warm → Direct on fresh direct receive evidence and demotes back on stall. Relay is always warm; direct is an opportunistic overlay.

No coordination server, no external etcd, no control plane beyond the Kubernetes API itself.

Quick Start

brew install inerplat/tap/wirekube
wirekubectl version

wirekubectl install --kubeconfig ~/.kube/config --context my-cluster
wirekubectl status

The Homebrew formula supports macOS and Linux on ARM64 and AMD64. GitHub Release binaries with a checksum file remain available for environments that do not use Homebrew.

A Helm chart is also available for clusters managed through Helm or GitOps:

helm install wirekube ./charts/wirekube \
  --namespace wirekube-system --create-namespace \
  --set mesh.meshCIDR=100.96.0.0/11

The installer inspects the cluster and shows the exact CRDs, privileged workloads, relay infrastructure, image digest, and mesh CIDR before mutation. It applies that plan in the same run without prompting, so use --dry-run to inspect one first. An unset --relay defaults to load-balancer and an unset --mesh-cidr is selected automatically; automation should state both, for example wirekubectl install --relay load-balancer --mesh-cidr 100.96.0.0/11 --output json. LoadBalancer installs create separate TCP and UDP entry points by default; use --relay-transport wss --relay-endpoint wss://relay.example.com/relay when an existing HTTPS Gateway or Ingress must front the authenticated WebSocket relay backend.

Each agent auto-discovers its endpoint and registers as a WireKubePeer. Every peer receives a deterministic /32 overlay IP from the selected mesh CIDR:

apiVersion: wirekube.io/v1alpha1
kind: WireKubeMesh
metadata:
  name: default
spec:
  meshCIDR: "172.31.240.0/20" # example only; choose a non-overlapping private range
  autoAllowedIPs:
    includeNodeInternalIP: true  # optionally also publish each node's private IP

You can still set AllowedIPs manually for fine-grained control:

kubectl patch wirekubepeer <node-name> --type=merge \
  -p '{"spec":{"allowedIPs":["<ip>/32"]}}'

See the Quick Start guide for detailed setup instructions.

Key Features

Feature	Description
No coordination server	Kubernetes CRDs are the only control plane — no external dependencies
Deterministic mesh overlay	meshCIDR assigns each node a stable /32 from a hash of its node name — no central IP allocator
Bimodal warm-relay datapath	Direct + relay legs duplicated when the direct path is unproven; WireGuard replay window dedupes. Blackouts are bounded by a 3s trust window, not control-plane sync
Disco-style failover hints	On stale receive, a BimodalHint is relayed to the peer so asymmetric UDP blackholes recover within one trust window instead of ~30s
NAT type detection	open / cone / port-restricted-cone / symmetric — public-IP-on-NIC hosts skip traversal entirely
Automatic NAT traversal	STUN discovery + relay-first availability + direct-path promotion
Virtual Gateway	Cross-VPC routing with HA failover via WireKubeGateway CRD
CNI aware	Uses an isolated routing table; operators must keep mesh and gateway AllowedIPs from conflicting with CNI routes
Relay pool scaling	DNS-based multi-instance relay discovery with automatic failover
Prometheus metrics	Peer latency, traffic, connection state, transport mode on :9090/metrics

Architecture

Component	Runs as	Purpose
Agent	DaemonSet (hostNetwork: true)	Manages WireGuard interface, discovers endpoints, syncs peers, handles relay failover
Relay	Deployment + Service	Bridges WireGuard UDP over TCP when NAT blocks direct P2P
wirekubectl	CLI	Installation lifecycle, status inspection, diagnostics, and peer management
Admin web	Relay sidecar	Manages external peers through the Kubernetes API

For details on NAT traversal, routing design, and the relay protocol, see the Architecture documentation.

Comparison with Alternatives

	WireKube	Tailscale	Submariner	Cilium ClusterMesh
Coordination	None (K8s CRDs)	Tailscale control server	Broker cluster	Dedicated etcd
NAT traversal	STUN + TCP relay	DERP relay servers	None (gateway-based)	None
Fully open-source	Yes	Client only	Yes	Yes
CNI dependency	None (works with any CNI)	None	Requires specific CNI	Requires Cilium
Scope	K8s node-to-node mesh	All devices, any OS	K8s multi-cluster	K8s multi-cluster
External infra	Kubernetes API; relay required for paths without direct reachability	Tailscale account	Broker cluster	Shared etcd

WireKube is a good fit when you want a lightweight, Kubernetes-native node mesh without external dependencies. Tailscale is better if you need to connect non-Kubernetes devices or want a managed service. Submariner and Cilium ClusterMesh are designed for full multi-cluster service discovery, which is a broader scope than WireKube's node-level connectivity.

Documentation

Full documentation is available at inerplat.github.io/wirekube.

Building from Source

make build          # Build all binaries
make test           # Run tests
make docker-build   # Build multi-arch Docker image

Contributing

Contributions are welcome! Please see the issues for open tasks or file a new one.

License

Licensed under the Apache License 2.0 (Apache-2.0).