Kedge

Dual-mode Kubernetes CNI plugin and node-level DaemonSet for attested connectivity between clusters and managed infrastructure. Part of the Guildhouse ecosystem.

Modes

• Overlay: Tunnels over networks Kedge doesn't control (WireGuard/VXLAN). For cloud anchors, remote sites, MSP-managed customer environments.
• Underlay: Programs the actual physical network fabric via vendor SDK dispatch through Bascule. For sites where you own the iron.

Both modes coexist at the same site. The capability token in a Shellstream handshake determines whether a session gets tunnel access (overlay) or infrastructure mutation authority (underlay).

Components

Component	Language	Description
CNI Plugin	Go	Multus secondary network attachment (net1), route programming
DaemonSet	Go	WireGuard mesh, Shellstream termination, QM notarization, VLAN management
YANG Compiler	Python	Device-agnostic policy → vendor-specific config (FortiOS, VyOS, UniFi)

Build

make build          # Build both binaries
make test           # Run Go tests
make lint           # golangci-lint
make proto-gen      # Generate gRPC client code from protos
make yang-validate  # Validate YANG models with pyang
make python-test    # Run YANG compiler tests

Project Structure

cmd/                 # Binary entry points (kedge-cni, kedge-daemon)
internal/            # Go internal packages
  cni/               # CNI plugin logic
  mesh/              # WireGuard tunnel lifecycle (overlay)
  vlan/              # VLAN interface management (underlay)
  shellstream/       # Handshake termination, SAT validation
  quartermaster/     # QM gRPC client, artifact types
  underlay/          # YANG watch, compilation trigger
  health/            # Prometheus metrics
  headscale/         # Peer discovery
  topology/          # Shared topology state
  config/            # Configuration types
yang/                # YANG models, site configs, Python compiler
k8s/                 # Kubernetes manifests
ansible/             # Bootstrap provisioning roles
terraform/           # Cloud anchor, mesh topology IaC
monitoring/          # Prometheus, Grafana dashboards

Current Status

Phase 1 (active): Two-cluster connectivity (homelab k3s + cloud anchor k3s). Overlay: WireGuard mesh, Shellstream handshake, SessionTransitArtifact. Underlay: VLAN bridges, YANG model, FortiOS + VyOS compiler targets, NetworkMutationArtifact.