# Kedge

Dual-mode Kubernetes CNI plugin and node-level DaemonSet for attested connectivity between clusters and managed infrastructure. Part of the [Guildhouse](https://github.com/guildhouse-co/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

```bash
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.