Kubernetes-Edge Lightweight Testbed
A 5G core and cloud-edge testbed that runs on one machine, built from scratch with Vagrant and Ansible.
A research testbed under active development. Components are tiered by maturity:
- Supported (validated, reproducible): core 5G deployment, VXLAN overlays, dashboard, IAM, node and NF metrics, physical RAN.
- Experimental (present, not fully validated): CAMARA location and positioning, UERANSIM, KubeEdge edge node, UPF-MEC, log and alerting stack.
- Planned (no working code yet): edge provisioning from the dashboard, MEC scheduling, O-RAN RIC, NWDAF.
CAMARA location and positioning are built and deploy, and Supported is where they are headed, but the end-to-end validation is not done yet.
Full matrix and reproducibility scope: docs/status.md.
The cluster is up to three nodes (K3s master, worker, and an optional KubeEdge edge), brought up and configured by a separate Ansible provisioning VM. The worker runs the Open5GS core network functions (AMF, SMF, UPF, NRF, and others) alongside KubeEdge CloudCore. The edge node hosts EdgeCore with UERANSIM gNB and UEs, or a physical femtocell. OVS+VXLAN tunnels carry the 5G control and user-plane traffic between them with per-interface isolation.
The figure above is the 3GPP service-based architecture, for reference. The network functions themselves come from Open5GS. What KELT adds is the deployment: the functions run as pods, and the interfaces between them (N1, N2, N3, N4, N6) each get their own VXLAN overlay instead of sharing one flat network.
graph LR
subgraph ran["Edge Node · or Physical RAN"]
direction TB
UE["UE
(simulated or physical)"]
gNB["gNB
(UERANSIM or femtocell)"]
end
subgraph worker["Worker Node"]
direction TB
subgraph core["Open5GS Core"]
direction TB
AMF
SMF
UPF
NRF
PCF
end
CC["KubeEdge CloudCore"]
DB[("MongoDB")]
DashFE["Dashboard frontend (pod)"]
end
subgraph master["Master Node"]
direction TB
K3s["K3s Server"]
end
subgraph prov["Provisioning VM (ansible)"]
direction TB
Dash["Dashboard backend"]
end
UE <-->|N1| AMF
gNB <-->|"N2 · 10.202.0.0/24"| AMF
gNB <-->|"N3 · 10.203.0.0/24"| UPF
SMF <-->|"N4 · 10.204.0.0/24"| UPF
UPF -->|N6| DN[("Data Network")]
master -.->|K3s| worker
Host OS: Ubuntu 24.04.4 LTS (desktop and server). Other Linux distributions are untested.
Prerequisites: Vagrant ≥ 2.3.0, VirtualBox ≥ 6.1.0, 16 GB RAM. The first-run wizard checks these and offers to install gum and the kelt command.
git clone https://github.com/Jacobbista/kelt.git
cd kelt
./testbed-config # first run launches the onboarding wizardThe wizard verifies host requirements (vagrant, VirtualBox, vboxusers
group, CPU virtualization), installs gum, puts kelt on your PATH, and
initializes the deployment profile. After that it works from any directory:
kelt up # bring the cluster up
kelt # open the interactive menu
kelt autostart on # bring the cluster up automatically on boot
kelt help # full referenceVerify after deployment:
vagrant ssh master
sudo k3s kubectl get nodes
sudo k3s kubectl get pods -n 5gFull guides:
- End-user and agent operations: QUICKSTART.md
- Detailed walkthrough: docs/getting-started.md
- Tool reference: docs/tools/testbed-config.md
VMs run Ubuntu 22.04 (Jammy).
| Layer | Technology | Version |
|---|---|---|
| Container orchestration | K3s | v1.30.6+k3s1 |
| Edge computing | KubeEdge | 1.21.0 |
| 5G core | Open5GS | 2.7.7 (patched; per-NF images built in 5g-nf-platform) |
| RAN simulation | UERANSIM | 3.2.7 (jacobbista/comnetsemu-ueransim) |
| Overlay networking | OVS + VXLAN | OVS CNI 0.34.3 |
| Multi-homed pods | Multus CNI | 4.1.0 |
| IPAM | Whereabouts | 0.7.0 |
| Operations | Dashboard (FastAPI + React) |
| Interface | Subnet | Protocol | Path |
|---|---|---|---|
| N1 | 10.201.0.0/24 | NAS / SCTP | UE ↔ AMF |
| N2 | 10.202.0.0/24 | NGAP / SCTP | gNB ↔ AMF |
| N3 | 10.203.0.0/24 | GTP-U / UDP | gNB ↔ UPF |
| N4 | 10.204.0.0/24 | PFCP / UDP | SMF ↔ UPF |
| N6c | 10.207.0.0/24 | IP / NAT | UPF-Cloud ↔ internet |
| N6m | 10.208.0.0/24 | IP routing | UPF-Cloud ↔ MEC data network |
| N6e | 10.206.0.0/24 | IP routing | UPF-Edge ↔ MEC (disabled) |
cd tests
make test # run all enabled suitesFor individual suites and how to write new ones, see the Testing Guide.
Full documentation lives in docs/.
Architecture
- System Overview: node roles, component placement, deployment flow
- Virtualization Layers: 5-layer stack from host to 5G NFs
- Network Topology: OVS, VXLAN, Multus from first principles
- 5G Interfaces: N1–N6 subnets, IPs, ports, verification
Deployment
- Deployment Phases: what each of the 12 phases does
- Server / NUC Setup: headless server deployment
- Physical RAN Integration: connect a real femtocell
Operations
- Troubleshooting: start here when something is wrong
- Handbook: operator cheat-sheet (IPs, ports, commands)
- Runbooks: step-by-step diagnostics for NGAP, PFCP, GTP-U, OVS, Multus
Dashboard
- Overview: architecture, access URLs, security model
- API Reference: REST and WebSocket endpoints
KELT pulls container images built and versioned in separate repositories:
- 5g-nf-platform: per-NF Open5GS images (AMF, SMF, UPF, and the rest) with research patches, built and published via CI. Pinned by tag in
ansible/group_vars/all.yml. - 5g-northbound: CAMARA gateway and positioning engine / demo images for the optional northbound addons.
The 5g-probe UE measurement tool ships in this repository under 5g-probe/.
Copyright 2024–2026 Jacopo Bennati. Licensed under the Apache License 2.0.
Third-party component licenses are listed in NOTICE.
This project started as a course project in the Granelli Lab (Prof. Fabrizio Granelli, University of Trento), and took its starting point from ComNetsEmu, the lab's SDN/NFV emulator. It went in a different direction: ComNetsEmu builds its topologies with Mininet and Docker, while KELT schedules containers on Kubernetes and carries the 5G interfaces over OVS/VXLAN overlays.
Built with K3s, KubeEdge, Open5GS, UERANSIM, and Multus CNI.