KELT

Kubernetes-Edge Lightweight Testbed
A reproducible, cloud-native 5G core and cloud-edge testbed that runs on a single workstation.

Status

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, CAMARA location and positioning*.
• Experimental (present, not fully validated): 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 shown at their target tier; end-to-end validation is in progress.

Full matrix and reproducibility scope: docs/status.md.

How It Works

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.

5G System Architecture (3GPP Release 17)

The testbed implements the reference point interfaces: N1 (UE–AMF), N2 (gNB–AMF), N3 (gNB–UPF), N4 (SMF–UPF), and N6 (UPF–DN). Each interface runs on a dedicated VXLAN-isolated overlay.

Testbed Implementation

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")]
    end

    subgraph master["Master Node"]
        direction TB
        K3s["K3s Server"]
        Dash["Dashboard"]
    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

Loading

Getting Started

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 shell alias automatically.

git clone https://github.com/Jacobbista/kelt.git
cd kelt
./testbed-config           # first run launches the onboarding wizard

The wizard verifies host requirements (vagrant, VirtualBox, vboxusers group, CPU virtualization), installs gum, sets up the testbed shell alias, and initializes the deployment profile. Once complete, the alias works from any directory:

testbed up                 # bring the cluster up
testbed                    # open the interactive menu
testbed autostart on       # bring the cluster up automatically on boot
testbed help               # full reference

Verify after deployment:

vagrant ssh master
sudo k3s kubectl get nodes
sudo k3s kubectl get pods -n 5g

Full guides:

• End-user and agent operations: QUICKSTART.md
• Detailed walkthrough: docs/getting-started.md
• Tool reference: docs/tools/testbed-config.md

Stack

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)

5G Interfaces

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)

Testing

cd tests
make test    # run all enabled suites

For individual suites and how to write new ones, see the Testing Guide.

Documentation

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

Companion Repositories

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/.

License

Copyright 2024–2026 Jacopo Bennati. Licensed under the Apache License 2.0.

Third-party component licenses are listed in NOTICE.

Acknowledgements

Inspired by ComNetsEmu, the SDN/NFV network emulator from the Granelli Lab (Prof. Fabrizio Granelli, University of Trento), where this project started as a course project. KELT takes a different route: it runs real workloads on Kubernetes connected by real OVS/VXLAN overlays, rather than ComNetsEmu's Mininet and Docker emulation.

Built with K3s, KubeEdge, Open5GS, UERANSIM, and Multus CNI.