# Aether OnRamp

Aether OnRamp is an automated deployment system that provides a low-overhead way to bring up a Kubernetes cluster and deploy a 5G version of SD-Core (Software-Defined Core) on that cluster. It uses Ansible playbooks and Make-based workflows to orchestrate the installation and configuration of all components needed for a complete 5G mobile network, including the ability to connect to either emulated RAN (Radio Access Network) simulators or physical gNBs (5G base stations). The project also supports 4G configurations with physical eNBs.

The system is built around a modular architecture where each subsystem (Kubernetes, 5G Core, RAN simulators, monitoring platform) is packaged as a separate Ansible role in the `deps` directory. All configurations are centralized in a `vars/main.yml` file that overrides per-component settings, and deployment targets are specified in an Ansible inventory file (`hosts.ini`). This design allows operators to deploy various network configurations - from simple single-server Quick Start deployments to complex multi-node setups with multiple UPFs (User Plane Functions), SD-RAN integration, and different RAN implementations (gNBsim, UERANSIM, OAI, srsRAN).

## Installation and Setup

### Quick Start Single-Server Deployment

Complete deployment of 5G core with emulated RAN on a single server:

```bash
# Clone repository with all submodules
git clone --recursive https://github.com/opennetworkinglab/aether-onramp.git
cd aether-onramp

# Verify Ansible connectivity to target hosts
make aether-pingall

# Install Kubernetes cluster
make aether-k8s-install

# Deploy 5G SD-Core
make aether-5gc-install

# Install and run gNBsim emulator
make aether-gnbsim-install
make aether-gnbsim-run

# View test results
docker exec -it gnbsim-1 cat summary.log

# Install Aether Management Platform (monitoring dashboards)
make aether-amp-install

# Access dashboards at:
# http://<server_ip>:31194  (Runtime Control)
# http://<server_ip>:30950  (Monitoring)

# Teardown
make aether-uninstall
```

### Configuration File Setup

Edit `vars/main.yml` before installation:

```yaml
# vars/main.yml - Key configuration parameters
k8s:
  rke2:
    version: v1.24.17+rke2r1
    config:
      token: purdue-k8s-rke2
      port: 9345

core:
  standalone: true              # false = under ROC control
  data_iface: ens18            # Network interface for data plane
  ran_subnet: "172.20.0.0/16"
  helm:
    chart_ref: aether/sd-core
    chart_version: 3.1.3
  upf:
    access_subnet: "192.168.252.1/24"
    core_subnet: "192.168.250.1/24"
    mode: af_packet             # or dpdk for high performance
    default_upf:
      ip:
        access: "192.168.252.3"
        core: "192.168.250.3"
      ue_ip_pool: "192.168.100.0/24"
  amf:
    ip: "10.76.28.113"         # AMF IP address

gnbsim:
  docker:
    container:
      image: omecproject/5gc-gnbsim:rel-1.7.0
      prefix: gnbsim
      count: 1
  router:
    data_iface: ens18
    macvlan:
      subnet_prefix: "172.20"
```

### Ansible Inventory Configuration

Define target servers in `hosts.ini`:

```ini
# hosts.ini - Single node configuration
[all]
node1 ansible_host=10.76.28.113 ansible_user=aether ansible_password=aether ansible_sudo_pass=aether

[master_nodes]
node1

[worker_nodes]
# Additional worker nodes for multi-server deployments

[gnbsim_nodes]
node1

# Multi-node example (commented out)
# [all]
# node1 ansible_host=10.76.28.113 ansible_user=aether ansible_password=aether ansible_sudo_pass=aether
# node2 ansible_host=10.76.28.115 ansible_user=aether ansible_password=aether ansible_sudo_pass=aether
#
# [master_nodes]
# node1
#
# [worker_nodes]
# node2
#
# [gnbsim_nodes]
# node2
```

## Component Management

### Kubernetes Cluster Operations

Install and manage the underlying Kubernetes infrastructure:

```bash
# Install RKE2 Kubernetes cluster
make aether-k8s-install

# Verify cluster status
kubectl get nodes
kubectl get pods --all-namespaces

# Uninstall Kubernetes cluster
make aether-k8s-uninstall
```

### 5G Core Network Management

Deploy and manage the SD-Core 5G network functions:

```bash
# Install 5G core (AMF, SMF, UPF, etc.)
make aether-5gc-install

# Reset core configuration without reinstalling
make aether-5gc-reset

# Add additional User Plane Functions
make aether-add-upfs

# Remove additional UPFs
make aether-remove-upfs

# Uninstall 5G core
make aether-5gc-uninstall

# Check core status
kubectl get pods -n omec
kubectl logs -n omec <pod-name>
```

### 4G Core Network Deployment

Deploy 4G/LTE core for eNB compatibility:

```bash
# Install 4G core with shared router
make aether-4gc-install

# Reset 4G core
make aether-4gc-reset

# Uninstall 4G core
make aether-4gc-uninstall
```

## RAN Simulators and Emulators

### gNBsim - Primary 5G RAN Emulator

Deploy and run the default 5G RAN simulator:

```bash
# Install gNBsim containers
make aether-gnbsim-install

# Run simulation tests
make aether-gnbsim-run

# View test results showing UE connections
docker exec -it gnbsim-1 cat summary.log

# Expected output format:
# Profile Name: profile1
# Profile Type: register
# UEs Passed: 5
# UEs Failed: 0

# Run multiple test iterations
make aether-gnbsim-run
make aether-gnbsim-run
make aether-gnbsim-run

# Uninstall gNBsim
make aether-gnbsim-uninstall
```

### UERANSIM - Alternative RAN Simulator

Deploy UERANSIM for alternative RAN simulation:

```bash
# Install UERANSIM
make aether-ueransim-install

# Start UERANSIM simulation
make aether-ueransim-run

# Stop UERANSIM
make aether-ueransim-stop

# Uninstall UERANSIM
make aether-ueransim-uninstall
```

### OAI (OpenAirInterface) 5G RAN

Deploy OAI-based 5G RAN with real or simulated UE:

```bash
# Install OAI gNB
make aether-oai-gnb-install

# Start OAI UE simulator
make aether-oai-uesim-start

# Stop OAI UE simulator
make aether-oai-uesim-stop

# Uninstall OAI gNB
make aether-oai-gnb-uninstall
```

### srsRAN 5G Implementation

Deploy srsRAN-based 5G network:

```bash
# Install srsRAN gNB
make aether-srsran-gnb-install

# Start srsRAN UE simulator
make aether-srsran-uesim-start

# Stop srsRAN UE simulator
make aether-srsran-uesim-stop

# Uninstall srsRAN gNB
make aether-srsran-gnb-uninstall
```

## Monitoring and Management Platform

### AMP (Aether Management Platform) Deployment

Install comprehensive monitoring and runtime control dashboards:

```bash
# Install AMP (includes ROC and monitoring)
make aether-amp-install

# Access Runtime Control dashboard
# http://<server_ip>:31194

# Access Monitoring dashboard (Grafana)
# http://<server_ip>:30950

# Generate traffic for monitoring
make aether-gnbsim-run

# Uninstall AMP
make aether-amp-uninstall
```

### SD-RAN Integration

Deploy Software-Defined RAN control plane:

```bash
# Install SD-RAN with RANSIM
make aether-sdran-install

# Install OSC-RIC (O-RAN Software Community RIC)
make aether-oscric-ric-install

# Uninstall SD-RAN
make aether-sdran-uninstall

# Uninstall OSC-RIC
make aether-oscric-ric-uninstall
```

## Advanced Configurations

### N3IWF Non-3GPP Access

Deploy N3IWF for non-3GPP access (WiFi integration):

```bash
# Install N3IWF component
make aether-n3iwf-install

# Uninstall N3IWF
make aether-n3iwf-uninstall
```

### Multi-UPF Deployment

Configure multiple User Plane Functions with slice support by using `vars/main-upf.yml`:

```bash
# Copy multi-UPF configuration
cp vars/main-upf.yml vars/main.yml

# Edit vars/main.yml to set:
# core.standalone: false  (enable AMP control)

# Install infrastructure
make aether-k8s-install
make aether-5gc-install

# Add additional UPFs
make aether-add-upfs

# Install AMP to program slices
make aether-amp-install
```

### DPDK/SR-IOV High Performance Mode

Enable high-performance packet processing using `vars/main-sriov.yml`:

```bash
# Copy SR-IOV configuration blueprint
cp vars/main-sriov.yml vars/main.yml

# Edit vars/main.yml:
# core.upf.mode: dpdk

# Deploy with DPDK-enabled UPF
make aether-k8s-install
make aether-5gc-install
```

## Custom Playbook Execution

### Direct Ansible Playbook Invocation

Run Ansible playbooks with custom variables:

```bash
# Ping all configured hosts
ansible-playbook -i hosts.ini pingall.yml --extra-vars "@vars/main.yml"

# Run main Aether provisioning playbook
ansible-playbook -i hosts.ini aether.yml --extra-vars "@vars/main.yml"

# Use alternative configuration
ansible-playbook -i hosts.ini aether.yml --extra-vars "@vars/main-gnbsim.yml"

# Debug playbook with verbose output
ansible-playbook -i hosts.ini debug.yml -vvv
```

### Configuration Blueprints

Switch between predefined deployment scenarios:

```bash
# Quick Start (default) - single server with gNBsim
cp vars/main-quickstart.yml vars/main.yml

# Distributed gNBsim - separate servers for RAN simulator
cp vars/main-gnbsim.yml vars/main.yml

# Physical gNB - connect to real 5G base station
cp vars/main-gNB.yml vars/main.yml

# Physical eNB - connect to 4G base station
cp vars/main-eNB.yml vars/main.yml

# Multiple UPFs with network slicing
cp vars/main-upf.yml vars/main.yml

# SD-RAN with RANSIM
cp vars/main-sdran.yml vars/main.yml

# UERANSIM instead of gNBsim
cp vars/main-ueransim.yml vars/main.yml

# OAI 5G RAN
cp vars/main-oai.yml vars/main.yml

# srsRAN 5G
cp vars/main-srsran.yml vars/main.yml

# N3IWF non-3GPP access
cp vars/main-n3iwf.yml vars/main.yml

# SR-IOV/DPDK optimizations
cp vars/main-sriov.yml vars/main.yml

# After copying, edit local parameters (IPs, interfaces)
nano vars/main.yml
```

## Verification and Troubleshooting

### System Health Checks

Verify deployment status and connectivity:

```bash
# Check Ansible connectivity
make aether-pingall

# Verify Kubernetes cluster
kubectl cluster-info
kubectl get nodes -o wide
kubectl get pods -n kube-system

# Check 5G core pods
kubectl get pods -n omec
kubectl get services -n omec

# View pod logs
kubectl logs -n omec <pod-name> --tail=100 -f

# Check container status
docker ps | grep gnbsim
docker logs gnbsim-1

# Inspect gNBsim test results
docker exec -it gnbsim-1 cat summary.log
docker exec -it gnbsim-1 cat gnbsim.log

# Network connectivity from gNB perspective
# (if using physical gNB with web GUI)
# Use built-in PING and TRACEROUTE diagnostic tools

# Verify IP forwarding on Aether server
sudo sysctl net.ipv4.ip_forward
sudo iptables -L -v -n | grep FORWARD

# Enable IP forwarding if needed
sudo iptables -P FORWARD ACCEPT
```

### Common Configuration Checks

Validate environment-specific settings:

```bash
# Check data interface exists
ip addr show ens18

# Verify AMF IP is reachable
ping 10.76.28.113

# Check routes for UPF subnets
ip route | grep 192.168

# Verify macvlan network for gNBsim
docker network ls | grep gnbnet
docker network inspect gnbnet

# Test DNS resolution
nslookup google.com

# Check available CPU features (MongoDB requires AVX)
grep avx /proc/cpuinfo
```

Aether OnRamp serves as a comprehensive deployment automation platform for private 5G and 4G mobile networks. Its primary use case is enabling network operators, researchers, and enterprises to rapidly deploy and test mobile network infrastructures without deep expertise in Kubernetes or 5G protocols. The modular design supports various deployment scenarios from lab testing with emulated components to production environments with physical radio equipment, making it suitable for proof-of-concept demonstrations, network function testing, and educational purposes.

The integration patterns follow a declarative infrastructure-as-code approach where all configuration is centralized in YAML files and deployment is orchestrated through Make targets that invoke Ansible playbooks. This design allows users to version control their network configurations, reproduce deployments across different environments, and easily switch between configuration blueprints. The system integrates with upstream Helm charts from the Aether project for core network functions, uses standard Kubernetes networking for service connectivity, and supports multiple RAN implementations through pluggable simulator modules. Advanced scenarios like network slicing, multi-site deployments, and SD-RAN integration are achieved by combining different configuration blueprints and enabling specific subsystem deployments through the unified Make interface.