|
| 1 | +# What is [free5GC](https://www.free5gc.org/) |
| 2 | + |
| 3 | +Free5GC is an open-source implementation of a 5G Core Network (5GC). |
| 4 | +This example demonstrates how free5GC can be deployed as a Cloud-Native Network Function (CNF) using Helm and tested via the CNTi test suite. |
| 5 | + |
| 6 | +The goal of this example is to provide a working reference deployment that is compatible with Kubernetes environments, including **kind clusters**. |
| 7 | + |
| 8 | +--- |
| 9 | + |
| 10 | +# Architecture Overview |
| 11 | + |
| 12 | +Free5GC implements a Service-Based Architecture (SBA) for 5G core networks, where individual network functions communicate over HTTP-based APIs. |
| 13 | + |
| 14 | +The main components deployed in this example include: |
| 15 | + |
| 16 | +- **NRF (Network Repository Function)** – service discovery |
| 17 | +- **AMF (Access and Mobility Management Function)** – handles device registration and mobility |
| 18 | +- **SMF (Session Management Function)** – manages sessions and IP allocation |
| 19 | +- **UPF (User Plane Function)** – handles user data traffic forwarding |
| 20 | +- **AUSF, UDM, UDR, PCF, NSSF** – supporting control-plane services |
| 21 | + |
| 22 | +The **UPF component** has additional requirements compared to other network functions: |
| 23 | +- It relies on low-level networking capabilities (packet forwarding, GTP tunneling) |
| 24 | +- It requires kernel-level features such as IP forwarding |
| 25 | + |
| 26 | +For this reason, when running in a Kubernetes environment (especially **kind**), specific `sysctl` settings must be enabled to allow proper packet routing and forwarding. |
| 27 | + |
| 28 | +Without these settings, the UPF will fail to initialize or will not properly handle traffic. |
| 29 | + |
| 30 | +# Prerequisites |
| 31 | + |
| 32 | +- Kubernetes cluster (tested with **kind**) |
| 33 | +- kubectl configured to access the cluster |
| 34 | +- Helm installed |
| 35 | +- CNTi test suite available locally |
| 36 | + |
| 37 | +## UPF kernel requirements |
| 38 | + |
| 39 | +- The UPF component requires the `gtp5g` kernel module. |
| 40 | +- If the module is not available, the UPF may fail with: |
| 41 | + `operation not supported` when creating GTP interfaces. |
| 42 | + |
| 43 | +To load the module: |
| 44 | + |
| 45 | +```bash |
| 46 | +git clone https://github.com/free5gc/gtp5g.git |
| 47 | +cd gtp5g |
| 48 | +make |
| 49 | +sudo make install |
| 50 | +sudo modprobe gtp5g |
| 51 | +``` |
| 52 | + |
| 53 | +## kind cluster configuration (required for UPF) |
| 54 | + |
| 55 | +When deploying on a kind cluster, the UPF component requires specific sysctl settings. |
| 56 | + |
| 57 | +Save the following configuration as `kind-free5gc-config.yaml`: |
| 58 | + |
| 59 | +```yaml |
| 60 | +kind: Cluster |
| 61 | +apiVersion: kind.x-k8s.io/v1alpha4 |
| 62 | +nodes: |
| 63 | +- role: control-plane |
| 64 | + kubeadmConfigPatches: |
| 65 | + - | |
| 66 | + kind: KubeletConfiguration |
| 67 | + allowedUnsafeSysctls: |
| 68 | + - "net.ipv4.ip_forward" |
| 69 | + - "net.ipv4.conf.all.forwarding" |
| 70 | +- role: worker |
| 71 | + kubeadmConfigPatches: |
| 72 | + - | |
| 73 | + kind: KubeletConfiguration |
| 74 | + allowedUnsafeSysctls: |
| 75 | + - "net.ipv4.ip_forward" |
| 76 | + - "net.ipv4.conf.all.forwarding" |
| 77 | +- role: worker |
| 78 | + kubeadmConfigPatches: |
| 79 | + - | |
| 80 | + kind: KubeletConfiguration |
| 81 | + allowedUnsafeSysctls: |
| 82 | + - "net.ipv4.ip_forward" |
| 83 | + - "net.ipv4.conf.all.forwarding" |
| 84 | +
|
| 85 | +``` |
| 86 | +Create the kind cluster using the configuration file: |
| 87 | +
|
| 88 | +
|
| 89 | +```bash |
| 90 | +kind create cluster --config kind-free5gc-config.yaml |
| 91 | +``` |
| 92 | + |
| 93 | +## Initialize submodules |
| 94 | + |
| 95 | +This example uses the free5GC Helm chart as a Git submodule. |
| 96 | + |
| 97 | +After cloning the repository, initialize the submodule: |
| 98 | + |
| 99 | +```bash |
| 100 | +git submodule update --init --recursive |
| 101 | +``` |
| 102 | + |
| 103 | +## Prepare CNTi test suite |
| 104 | + |
| 105 | +Initialize the test suite: |
| 106 | + |
| 107 | +```bash |
| 108 | +cnf-testsuite setup |
| 109 | +``` |
| 110 | + |
| 111 | +# Installation |
| 112 | + |
| 113 | +Deploy free5GC using the CNTi test suite: |
| 114 | + |
| 115 | +```bash |
| 116 | +cnf-testsuite cnf_install cnf-config=example-cnfs/free5gc/cnf-testsuite.yml |
| 117 | +``` |
| 118 | + |
| 119 | +The CNF is deployed into the `free5gc` namespace. |
| 120 | + |
| 121 | +The free5GC Helm chart is located at: |
| 122 | + |
| 123 | +`example-cnfs/free5gc/charts/free5gc-helm/charts/free5gc` |
| 124 | + |
| 125 | +The chart is deployed automatically through the provided `cnf-testsuite.yml`. |
| 126 | + |
| 127 | +# Running CNF Tests |
| 128 | + |
| 129 | +To run CNF certification tests: |
| 130 | + |
| 131 | +```bash |
| 132 | +cnf-testsuite cert |
| 133 | +``` |
| 134 | + |
| 135 | +## Verify Deployment |
| 136 | + |
| 137 | +To check that all components are running: |
| 138 | + |
| 139 | +```bash |
| 140 | +kubectl get pods -n free5gc |
| 141 | +``` |
| 142 | + |
| 143 | +# Uninstallation |
| 144 | + |
| 145 | +To uninstall free5GC: |
| 146 | + |
| 147 | +```bash |
| 148 | +cnf-testsuite cnf_uninstall cnf-config=example-cnfs/free5gc/cnf-testsuite.yml |
| 149 | +``` |
| 150 | + |
| 151 | +In some cases, persistent resources (e.g. PersistentVolumeClaims) may remain and need to be removed manually: |
| 152 | + |
| 153 | +```bash |
| 154 | +kubectl delete pvc --all -n free5gc |
| 155 | +``` |
| 156 | + |
| 157 | +# Notes and Adjustments |
| 158 | + |
| 159 | +The free5GC Helm chart is included as an upstream Git submodule and is not modified directly. |
| 160 | + |
| 161 | +To ensure compatibility with a kind-based Kubernetes environment, MongoDB configuration is overridden via the <br /> `cnf-testsuite.yml` file using Helm values. |
| 162 | + |
| 163 | +The following adjustments are applied at deployment time: |
| 164 | + |
| 165 | +- Disabled persistence (`mongodb.persistence.enabled=false`) |
| 166 | +- Removed the `extraDeploy` section to avoid creation of a static PersistentVolume |
| 167 | + |
| 168 | +These changes were necessary because the original chart assumes a specific storage backend (microk8s), which is not available in kind clusters. |
| 169 | +Without these modifications, MongoDB would remain in a `Pending` state due to incompatible storage configuration. |
| 170 | + |
| 171 | +# Known Limitations |
| 172 | + |
| 173 | +This example is intended as a **reference CNF deployment** for testing purposes and has several limitations: |
| 174 | + |
| 175 | +- **Privileged networking requirements** |
| 176 | + - The UPF requires kernel-level networking features such as IP forwarding (`net.ipv4.ip_forward`, `net.ipv4.conf.all.forwarding`) |
| 177 | + - Without enabling these unsafe sysctls (e.g. via `allowedUnsafeSysctls` in kind), UPF pods fail to start with `SysctlForbidden` errors. |
| 178 | + |
| 179 | +- **CNTi certification test results** |
| 180 | + - The following tests are observed to fail: |
| 181 | + |
| 182 | + - `non_root_containers` |
| 183 | + - Fails for UPF components (`iupf1`, `psaupf1`, `psaupf2`) |
| 184 | + - Reason: the UPF requires low-level networking capabilities and is designed to run with root privileges, which violates the non-root container requirement |
| 185 | + |
| 186 | + - `node_drain` |
| 187 | + - Unstable (intermittent failures) |
| 188 | + - Reason: MongoDB uses single-replica RWO storage, which can cause multi-attach errors during node migration |
| 189 | + |
| 190 | +- **Non-production configuration** |
| 191 | + - Persistence for MongoDB is disabled for compatibility with kind |
| 192 | + - The deployment is not optimized for high availability or data durability |
| 193 | + |
| 194 | +- **Environment-specific behavior** |
| 195 | + - The setup is tested primarily on **kind clusters** |
| 196 | + - Other environments (e.g., managed Kubernetes services) may require additional adjustments |
| 197 | + |
| 198 | +This example focuses on **deployability and testability**, not production readiness. |
0 commit comments