llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 1 | Quick Start |
| 2 | ----------------------- |
| 3 | |
Larry Peterson | b0c0da3 | 2023-08-23 13:07:10 -0700 | [diff] [blame] | 4 | This section describes a low-overhead way to get started with OnRamp. |
| 5 | It brings up a one-node Kubernetes cluster, deploys a 5G version of |
| 6 | SD-Core on that cluster, and runs an emulated 5G workload against the |
| 7 | 5G Core. It assumes a low-end server that meets the following |
| 8 | requirements: |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 9 | |
Larry Peterson | 134bc72 | 2023-08-25 13:47:48 -0700 | [diff] [blame] | 10 | * Haswell CPU (or newer), with at least 4 CPUs and 16GB RAM. |
Larry Peterson | b0c0da3 | 2023-08-23 13:07:10 -0700 | [diff] [blame] | 11 | * Clean install of Ubuntu 20.04 or 22.04, with 5.15 (or later) kernel. |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 12 | |
| 13 | For example, something like an Intel NUC is more than enough to get |
| 14 | started. |
| 15 | |
Larry Peterson | b0c0da3 | 2023-08-23 13:07:10 -0700 | [diff] [blame] | 16 | While it's possible to use OnRamp to deploy Aether on a laptop (e.g., |
| 17 | in a VirtualBox VM), because the goal is to eventually scale a |
| 18 | deployment and/or run Aether 24/7, OnRamp has been developed and |
| 19 | tested on physical servers and server-based VMs. The latter includes |
Larry Peterson | 134bc72 | 2023-08-25 13:47:48 -0700 | [diff] [blame] | 20 | Proxmox (see the example configuration shown in :numref:`Figure %s |
Larry Peterson | b0c0da3 | 2023-08-23 13:07:10 -0700 | [diff] [blame] | 21 | <fig-proxmox>`); AWS (specify a ``t2.xlarge`` instance); and CloudLab |
Larry Peterson | 134bc72 | 2023-08-25 13:47:48 -0700 | [diff] [blame] | 22 | (specify either a ``small-lan`` or ``single-pc-ubuntu`` instance). |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 23 | |
Larry Peterson | b0c0da3 | 2023-08-23 13:07:10 -0700 | [diff] [blame] | 24 | .. _fig-proxmox: |
| 25 | .. figure:: figures/proxmox.png |
| 26 | :width: 500px |
| 27 | :align: center |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 28 | |
Larry Peterson | b0c0da3 | 2023-08-23 13:07:10 -0700 | [diff] [blame] | 29 | Example configuration of Proxmox VM. |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 30 | |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 31 | |
| 32 | Prep Environment |
| 33 | ~~~~~~~~~~~~~~~~~~~~~ |
| 34 | |
Larry Peterson | def1b67 | 2023-08-07 14:06:24 -0700 | [diff] [blame] | 35 | To install Aether OnRamp, you must be able able to run ``sudo`` without |
| 36 | a password, and there should be no firewall running on the server. You can |
| 37 | verify this is the case by executing the following, which should |
| 38 | report ``Status: inactive``: |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 39 | |
| 40 | .. code-block:: |
| 41 | |
| 42 | $ sudo ufw status |
Larry Peterson | def1b67 | 2023-08-07 14:06:24 -0700 | [diff] [blame] | 43 | Status: inactive |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 44 | |
Larry Peterson | 5d6b3b3 | 2023-09-05 15:11:55 -0700 | [diff] [blame] | 45 | Your server should use *systemd-networkd* to configure the network, |
| 46 | which you can verify by typing: |
Larry Peterson | a30a75e | 2023-09-01 15:44:37 -0700 | [diff] [blame] | 47 | |
| 48 | .. code-block:: |
| 49 | |
| 50 | $ systemctl status systemd-networkd.service |
| 51 | |
Larry Peterson | 5d6b3b3 | 2023-09-05 15:11:55 -0700 | [diff] [blame] | 52 | Note that Aether assumes Ubuntu Server (as opposed to Ubuntu Desktop), |
| 53 | the main implication being that it uses *systemd-networkd* rather than |
| 54 | *Network Manager* to manage network settings. It is possible to work |
| 55 | around this requirement, but be aware that doing so may impact the |
| 56 | Ansible playbook for installing SD-Core. |
| 57 | |
Larry Peterson | def1b67 | 2023-08-07 14:06:24 -0700 | [diff] [blame] | 58 | OnRamp depends on Ansible, which you can install on your server as |
| 59 | follows: |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 60 | |
| 61 | .. code-block:: |
| 62 | |
| 63 | $ sudo apt install pipx |
| 64 | $ sudo apt install python3.8-venv |
| 65 | $ pipx install --include-deps ansible |
| 66 | $ pipx ensurepath |
| 67 | $ sudo apt-get install sshpass |
| 68 | |
Larry Peterson | 4d344dd | 2023-08-17 14:46:22 -0700 | [diff] [blame] | 69 | Once installed, displaying the Ansible version number should result in |
| 70 | output similar to the following: |
| 71 | |
| 72 | .. code-block:: |
| 73 | |
| 74 | $ ansible --version |
| 75 | ansible [core 2.11.12] |
| 76 | config file = None |
| 77 | configured module search path = ['/home/foo/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules'] |
| 78 | ansible python module location = /home/foo/.local/lib/python3.6/site-packages/ansible |
| 79 | ansible collection location = /home/foo/.ansible/collections:/usr/share/ansible/collections |
| 80 | executable location = /home/foo/.local/bin/ansible |
| 81 | python version = 3.6.9 (default, Mar 10 2023, 16:46:00) [GCC 8.4.0] |
| 82 | jinja version = 3.0.3 |
| 83 | libyaml = True |
| 84 | |
Larry Peterson | aa89b8e | 2023-08-17 15:28:59 -0700 | [diff] [blame] | 85 | Note that a fresh install of Ubuntu may be missing other packages that |
| 86 | you need (e.g., ``git``, ``curl``, ``make``), but you will be prompted |
| 87 | to install them as you step through the Quick Start sequence. |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 88 | |
| 89 | Download Aether OnRamp |
| 90 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 91 | |
| 92 | Once ready, clone the Aether OnRamp repo on this target deployment |
| 93 | server: |
| 94 | |
| 95 | .. code-block:: |
| 96 | |
| 97 | $ git clone --recursive https://github.com/opennetworkinglab/aether-onramp.git |
| 98 | $ cd aether-onramp |
| 99 | |
| 100 | Taking a quick look at your ``aether-onramp`` directory, there are |
| 101 | four things to note: |
| 102 | |
| 103 | 1. The ``deps`` directory contains the Ansible deployment |
| 104 | specifications for all the Aether subsystems. Each of these |
| 105 | subdirectories (e.g., ``deps/5gc``) is self-contained, meaning you |
| 106 | can execute the Make targets in each individual directory. Doing so |
| 107 | causes Ansible to run the corresponding playbook. For example, the |
| 108 | installation playbook for the 5G Core can be found in |
| 109 | ``deps/5gc/roles/core/tasks/install.yml``. |
| 110 | |
| 111 | 2. The Makefile in the main OnRamp directory imports (``#include``) |
| 112 | the per-subsystem Makefiles, meaning all the individual steps |
| 113 | required to install Aether can be managed from this main directory. |
| 114 | The Makefile includes comments listing the key Make targets defined |
| 115 | by the included Makefiles. *Importantly, the rest of this guide |
| 116 | assumes you are working in the main OnRamp directory, and not in |
| 117 | the individual subsystems.* |
| 118 | |
| 119 | 3. File ``vars/main.yml`` defines all the Ansible variables you will |
| 120 | potentially need to modify to specify your deployment scenario. |
| 121 | This file is the union of all the per-component ``var/main.yml`` |
| 122 | files you find in the corresponding ``deps`` directory. This |
| 123 | top-level variable file overrides the per-component var files, so |
| 124 | you will not need to modify the latter. Note that the ``vars`` |
| 125 | directory contains several variants of ``main.yml``, each tailored |
| 126 | for a different deployment scenario. The default ``main.yml`` |
| 127 | (which is the same as ``main-quickstart.yml``) supports the Quick |
| 128 | Start deployment described in this section; we'll substitute the |
| 129 | other variants in later sections. |
| 130 | |
| 131 | 4. File ``hosts.ini`` (host inventory) is Ansible's way of specifying |
| 132 | the set of servers (physical or virtual) that Ansible targets with |
Larry Peterson | 4d344dd | 2023-08-17 14:46:22 -0700 | [diff] [blame] | 133 | various installation playbooks. The default version of ``hosts.ini`` |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 134 | included with OnRamp is simplified to run everything on a single |
| 135 | server (the one you've cloned the repo onto), with additional lines |
| 136 | you may eventually need for a multi-node cluster commented out. |
| 137 | |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 138 | Set Target Parameters |
| 139 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 140 | |
| 141 | The Quick Start deployment described in this section requires that you |
Larry Peterson | 0fa9b36 | 2023-08-09 15:15:13 -0700 | [diff] [blame] | 142 | modify two sets of parameters to reflect the specifics of your target |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 143 | deployment. |
| 144 | |
Larry Peterson | 4d344dd | 2023-08-17 14:46:22 -0700 | [diff] [blame] | 145 | The first set is in file ``hosts.ini``, where you will need to give the IP |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 146 | address and login credentials for the server you are working on. At |
| 147 | this stage, we assume the server you downloaded OnRamp onto is the |
| 148 | same server you will be installing Aether on. |
| 149 | |
| 150 | .. code-block:: |
| 151 | |
Larry Peterson | 925ac6b | 2023-08-23 13:38:35 -0700 | [diff] [blame] | 152 | node1 ansible_host=10.76.28.113 ansible_user=aether ansible_password=aether ansible_sudo_pass=aether |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 153 | |
Larry Peterson | 925ac6b | 2023-08-23 13:38:35 -0700 | [diff] [blame] | 154 | In this example, address ``10.76.28.113`` and the three occurrences |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 155 | of the string ``aether`` need to be replaced with the appropriate |
| 156 | values. Note that if you set up your server to use SSH keys instead |
| 157 | of passwords, then ``ansible_password=aether`` needs to be replaced |
| 158 | with ``ansible_ssh_private_key_file=~/.ssh/id_rsa`` (or wherever |
| 159 | your private key can be found). |
| 160 | |
Larry Peterson | 0fa9b36 | 2023-08-09 15:15:13 -0700 | [diff] [blame] | 161 | The second set of parameters is in ``vars/main.yml``, where the **two** lines |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 162 | currently reading |
| 163 | |
| 164 | .. code-block:: |
| 165 | |
| 166 | data_iface: ens18 |
| 167 | |
| 168 | need to be edited to replace ``ens18`` with the device interface for |
Larry Peterson | 0fa9b36 | 2023-08-09 15:15:13 -0700 | [diff] [blame] | 169 | you server, and the line specifying the IP address of the Core's AMF |
| 170 | needs to be edited to reflect your server's IP address: |
| 171 | |
| 172 | .. code-block:: |
| 173 | |
| 174 | amf: |
Larry Peterson | 925ac6b | 2023-08-23 13:38:35 -0700 | [diff] [blame] | 175 | ip: "10.76.28.113" |
Larry Peterson | 0fa9b36 | 2023-08-09 15:15:13 -0700 | [diff] [blame] | 176 | |
| 177 | You can learn your server's IP address and interface using the Linux ``ip`` |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 178 | command: |
| 179 | |
| 180 | .. code-block:: |
| 181 | |
| 182 | $ ip a |
| 183 | 1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 |
| 184 | link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 |
| 185 | inet 127.0.0.1/8 scope host lo |
| 186 | valid_lft forever preferred_lft forever |
| 187 | inet6 ::1/128 scope host |
| 188 | valid_lft forever preferred_lft forever |
| 189 | 2: ens18: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000 |
| 190 | link/ether 2c:f0:5d:f2:d8:21 brd ff:ff:ff:ff:ff:ff |
| 191 | inet 10.76.28.113/24 metric 100 brd 10.76.28.255 scope global ens3 |
| 192 | valid_lft forever preferred_lft forever |
| 193 | inet6 fe80::2ef0:5dff:fef2:d821/64 scope link |
| 194 | valid_lft forever preferred_lft forever |
| 195 | |
| 196 | In this example, the reported interface is ``ens18`` and the IP |
| 197 | address is ``10.76.28.113`` on subnet ``10.76.28.0/24``. We will use |
| 198 | these three values as a running example throughout the guide, as a |
| 199 | placeholder for your local details. |
| 200 | |
Larry Peterson | 505d4b3 | 2023-08-21 14:39:45 -0700 | [diff] [blame] | 201 | .. admonition:: Troubleshooting Hint |
| 202 | |
| 203 | Due to a limitation in gNBsim (the RAN emulator introduced later in |
| 204 | this section), it is necessary for your server to be configured with |
| 205 | IPv6 enabled (as the ``inet6`` line in the example output indicates |
| 206 | is the case for interface ``ens18``). If IPv6 is not enabled, the |
| 207 | emulated RAN will not successfully connect to the AMF. |
| 208 | |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 209 | Note that ``vars/main.yml`` and ``hosts.ini`` are the only two files |
| 210 | you need to modify for now, but there are additional config files that |
| 211 | you may want to modify as we move beyond the Quick Start deployment. |
| 212 | We'll identify those files throughout this section, for informational |
| 213 | purposes, and revisit them in later sections. |
| 214 | |
| 215 | Many of the tasks specified in the various Ansible playbooks result in |
| 216 | calls to Kubernetes, either directly via ``kubectl``, or indirectly |
| 217 | via ``helm``. This means that after executing the sequence of |
| 218 | Makefile targets described in the rest of this guide, you'll want to |
| 219 | run some combination of the following commands to verify that the |
| 220 | right things happened: |
| 221 | |
| 222 | .. code-block:: |
| 223 | |
| 224 | $ kubectl get pods --all-namespaces |
| 225 | $ helm repo list |
| 226 | $ helm list --namespace kube-system |
| 227 | |
| 228 | The first reports the set of Kubernetes namespaces currently running; |
| 229 | the second shows the known set of repos you are pulling charts from; |
| 230 | and the third shows the version numbers of the charts currently |
| 231 | deployed in the ``kube-system`` namespace. |
| 232 | |
| 233 | If you are not familiar with ``kubectl`` (the CLI for Kubernetes), we |
| 234 | recommend that you start with `Kubernetes Tutorial |
| 235 | <https://kubernetes.io/docs/tutorials/kubernetes-basics/>`__. And |
| 236 | although not required, you may also want to install |
| 237 | `k9s <https://k9scli.io/>`__\ , a terminal-based UI that provides a |
| 238 | convenient alternative to ``kubectl`` for interacting with Kubernetes. |
| 239 | |
| 240 | Note that we have not yet installed Kubernetes or Helm, so these |
| 241 | commands are not yet available. At this point, the only verification |
| 242 | step you can take is to type the following: |
| 243 | |
| 244 | .. code-block:: |
| 245 | |
| 246 | $ make aether-pingall |
| 247 | |
| 248 | The output should show that Ansible is able to securely connect to all |
| 249 | the nodes in your deployment, which is currently just the one that |
| 250 | Ansible knows as ``node1``. |
| 251 | |
| 252 | Install Kubernetes |
| 253 | ~~~~~~~~~~~~~~~~~~~ |
| 254 | |
| 255 | The next step is to bring up an RKE2.0 Kubernetes cluster on your |
| 256 | target server. Do this by typing: |
| 257 | |
| 258 | .. code-block:: |
| 259 | |
| 260 | $ make aether-k8s-install |
| 261 | |
Larry Peterson | 4d344dd | 2023-08-17 14:46:22 -0700 | [diff] [blame] | 262 | Note that the Ansible playbooks triggered by this (and other) make |
| 263 | targets will output red results from time-to-time (indicating an |
| 264 | exception or failure), but as long as Ansible keeps progressing |
| 265 | through the playbook, such output can be safely ignored. |
| 266 | |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 267 | Once the playbook completes, executing ``kubectl`` will show the |
| 268 | ``kube-system`` namespace running, with output looking something like |
| 269 | the following: |
| 270 | |
| 271 | .. code-block:: |
| 272 | |
| 273 | $ kubectl get pods --all-namespaces |
| 274 | NAMESPACE NAME READY STATUS RESTARTS AGE |
| 275 | kube-system cloud-controller-manager-node1 1/1 Running 0 2m4s |
| 276 | kube-system etcd-node1 1/1 Running 0 104s |
| 277 | kube-system helm-install-rke2-canal-8s67r 0/1 Completed 0 113s |
| 278 | kube-system helm-install-rke2-coredns-bk5rh 0/1 Completed 0 113s |
| 279 | kube-system helm-install-rke2-ingress-nginx-lsjz2 0/1 Completed 0 113s |
| 280 | kube-system helm-install-rke2-metrics-server-t8kxf 0/1 Completed 0 113s |
| 281 | kube-system helm-install-rke2-multus-tbbhc 0/1 Completed 0 113s |
| 282 | kube-system kube-apiserver-node1 1/1 Running 0 97s |
| 283 | kube-system kube-controller-manager-node1 1/1 Running 0 2m7s |
| 284 | kube-system kube-multus-ds-96cnl 1/1 Running 0 95s |
| 285 | kube-system kube-proxy-node1 1/1 Running 0 2m1s |
| 286 | kube-system kube-scheduler-node1 1/1 Running 0 2m7s |
| 287 | kube-system rke2-canal-h79qq 2/2 Running 0 95s |
| 288 | kube-system rke2-coredns-rke2-coredns-869b5d56d4-tffjh 1/1 Running 0 95s |
| 289 | kube-system rke2-coredns-rke2-coredns-autoscaler-5b947fbb77-pj5vk 1/1 Running 0 95s |
| 290 | kube-system rke2-ingress-nginx-controller-s68rx 1/1 Running 0 48s |
| 291 | kube-system rke2-metrics-server-6564db4569-snnv4 1/1 Running 0 56s |
| 292 | |
| 293 | If you are interested in seeing the details about how Kubernetes is |
| 294 | customized for Aether, look at |
| 295 | ``deps/k8s/roles/rke2/templates/master-config.yaml``. Of particular |
| 296 | note, we have instructed Kubernetes to allow service for ports ranging |
| 297 | from ``2000`` to ``36767`` and we are using the ``multus`` and |
| 298 | ``canal`` CNI plugins. |
| 299 | |
| 300 | Install SD-Core |
| 301 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 302 | |
| 303 | We are now ready to bring up the 5G version of the SD-Core. To do |
| 304 | that, type: |
| 305 | |
| 306 | .. code-block:: |
| 307 | |
| 308 | $ make aether-5gc-install |
| 309 | |
| 310 | ``kubectl`` will now show the ``omec`` namespace running (in addition |
| 311 | to ``kube-system``), with output similar to the following: |
| 312 | |
| 313 | .. code-block:: |
| 314 | |
| 315 | $ kubectl get pods -n omec |
| 316 | NAME READY STATUS RESTARTS AGE |
| 317 | amf-5887bbf6c5-pc9g2 1/1 Running 0 6m13s |
| 318 | ausf-6dbb7655c7-42z7m 1/1 Running 0 6m13s |
| 319 | kafka-0 1/1 Running 0 6m13s |
| 320 | metricfunc-b9f8c667b-r2x9g 1/1 Running 0 6m13s |
| 321 | mongodb-0 1/1 Running 0 6m13s |
| 322 | mongodb-1 1/1 Running 0 4m12s |
| 323 | mongodb-arbiter-0 1/1 Running 0 6m13s |
| 324 | nrf-54bf88c78c-kcm7t 1/1 Running 0 6m13s |
| 325 | nssf-5b85b8978d-d29jm 1/1 Running 0 6m13s |
| 326 | pcf-758d7cfb48-dwz9x 1/1 Running 0 6m13s |
| 327 | sd-core-zookeeper-0 1/1 Running 0 6m13s |
| 328 | simapp-6cccd6f787-jnxc7 1/1 Running 0 6m13s |
| 329 | smf-7f89c6d849-wzqvx 1/1 Running 0 6m13s |
| 330 | udm-768b9987b4-9qz4p 1/1 Running 0 6m13s |
| 331 | udr-8566897d45-kv6zd 1/1 Running 0 6m13s |
| 332 | upf-0 5/5 Running 0 6m13s |
| 333 | webui-5894ffd49d-gg2jh 1/1 Running 0 6m13s |
| 334 | |
Larry Peterson | 4d344dd | 2023-08-17 14:46:22 -0700 | [diff] [blame] | 335 | If you see problematic pods that are not getting into the ``Running`` |
Larry Peterson | 14b9b95 | 2023-09-21 10:03:44 -0700 | [diff] [blame] | 336 | state, a reset usually corrects the problem. Type: |
Larry Peterson | 4d344dd | 2023-08-17 14:46:22 -0700 | [diff] [blame] | 337 | |
| 338 | .. code-block:: |
| 339 | |
| 340 | make aether-resetcore |
| 341 | |
| 342 | Once running, you will recognize pods that correspond to many of the |
Larry Peterson | def1b67 | 2023-08-07 14:06:24 -0700 | [diff] [blame] | 343 | microservices discussed is `Chapter 5 |
| 344 | <https://5g.systemsapproach.org/core.html>`__. For example, |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 345 | ``amf-5887bbf6c5-pc9g2`` implements the AMF. Note that for historical |
| 346 | reasons, the Aether Core is called ``omec`` instead of ``sd-core``. |
| 347 | |
Larry Peterson | 5d6b3b3 | 2023-09-05 15:11:55 -0700 | [diff] [blame] | 348 | .. admonition:: Troubleshooting Hint |
| 349 | |
| 350 | If you see failures of the ``find ens18's netplan network |
| 351 | directory`` task in the ``router`` role, it indicates that |
| 352 | *systemd-networkd* is not configured as expected. Check the |
| 353 | ``Troubleshooting`` bookmark on the ``#aether-onramp`` Slack channel |
| 354 | for possible workarounds. |
| 355 | |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 356 | If you are interested in seeing the details about how SD-Core is |
| 357 | configured, look at |
| 358 | ``deps/5gc/roles/core/templates/radio-5g-values.yaml``. This is an |
Larry Peterson | 505d4b3 | 2023-08-21 14:39:45 -0700 | [diff] [blame] | 359 | example of a *values override* file that Helm passes along to |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 360 | Kubernetes when launching the service. Most of the default settings |
| 361 | will remain unchanged, with the main exception being the |
| 362 | ``subscribers`` block of the ``omec-sub-provision`` section. This |
| 363 | block will eventually need to be edited to reflect the SIM cards you |
| 364 | actually deploy. We return to this topic in the section describing how |
| 365 | to bring up a physical gNB. |
| 366 | |
| 367 | |
| 368 | Run Emulated RAN Test |
| 369 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 370 | |
| 371 | We can now test SD-Core with emulated traffic by typing: |
| 372 | |
| 373 | .. code-block:: |
| 374 | |
| 375 | $ make aether-gnbsim-install |
| 376 | $ make aether-gnbsim-run |
| 377 | |
| 378 | Note that you can re-execute the ``aether-gnbsim-run`` target multiple |
| 379 | times, where the results of each run are saved in a file within the |
| 380 | Docker container running the test. You can access that file by typing: |
| 381 | |
| 382 | .. code-block:: |
| 383 | |
| 384 | $ docker exec -it gnbsim-1 cat summary.log |
| 385 | |
Larry Peterson | 0fa9b36 | 2023-08-09 15:15:13 -0700 | [diff] [blame] | 386 | If successful, the output should look like the following: |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 387 | |
| 388 | .. code-block:: |
| 389 | |
Larry Peterson | 0fa9b36 | 2023-08-09 15:15:13 -0700 | [diff] [blame] | 390 | 2023-08-09T19:57:09Z [INFO][GNBSIM][Summary] Profile Name: profile2 , Profile Type: pdusessest |
Larry Peterson | af9ea36 | 2023-08-11 16:40:19 -0700 | [diff] [blame] | 391 | 2023-08-09T19:57:09Z [INFO][GNBSIM][Summary] UEs Passed: 5 , UEs Failed: 0 |
Larry Peterson | 0fa9b36 | 2023-08-09 15:15:13 -0700 | [diff] [blame] | 392 | 2023-08-09T19:57:09Z [INFO][GNBSIM][Summary] Profile Status: PASS |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 393 | |
| 394 | This particular test, which runs the cryptically named ``pdusessest`` |
Larry Peterson | af9ea36 | 2023-08-11 16:40:19 -0700 | [diff] [blame] | 395 | profile, emulates five UEs, each of which: (1) registers with the |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 396 | Core, (2) initiates a user plane session, and (3) sends a minimal data |
Larry Peterson | 0fa9b36 | 2023-08-09 15:15:13 -0700 | [diff] [blame] | 397 | packet over that session. In addition to displaying the summary |
| 398 | results, you can also open a shell in the ``gnbsim-1`` container, |
| 399 | where you can view the full trace of every run of the emulation, each |
| 400 | of which has been saved in a timestamped file: |
| 401 | |
| 402 | .. code-block:: |
| 403 | |
| 404 | $ docker exec -it gnbsim-1 bash |
| 405 | bash-5.1# ls |
| 406 | gnbsim gnbsim1-20230809T125702.config summary.log |
| 407 | gnbsim.log gnbsim1-20230809T125702.log |
| 408 | bash-5.1# more gnbsim1-20230809T125702.log |
| 409 | 2023-08-09T19:57:05Z [INFO][GNBSIM][App] App Name: GNBSIM |
| 410 | 2023-08-09T19:57:05Z [INFO][GNBSIM][App] Setting log level to: info |
| 411 | 2023-08-09T19:57:05Z [INFO][GNBSIM][GNodeB][gnb1] GNodeB IP: GNodeB Port: 9487 |
| 412 | 2023-08-09T19:57:05Z [INFO][GNBSIM][GNodeB][UserPlaneTransport] User Plane transport listening on: 172.20.0.2:2152 |
| 413 | 2023-08-09T19:57:05Z [INFO][GNBSIM][GNodeB] Current range selector value: 63 |
| 414 | 2023-08-09T19:57:05Z [INFO][GNBSIM][GNodeB] Current ID range start: 1056964608 end: 1073741823 |
| 415 | 2023-08-09T19:57:05Z [INFO][GNBSIM][GNodeB][ControlPlaneTransport] Connected to AMF, AMF IP: 10.76.28.113 AMF Port: 38412 |
| 416 | ... |
| 417 | |
Larry Peterson | 505d4b3 | 2023-08-21 14:39:45 -0700 | [diff] [blame] | 418 | .. admonition:: Troubleshooting Hint |
| 419 | |
| 420 | If ``summary.log`` is empty, it means the emulation did not run due |
| 421 | to a configuration error. To debug the problem, open a bash shell on |
| 422 | the gNBsim container (as shown in the preceding example), and look |
| 423 | at ``gnbsim.log``. Output that includes ``failed to connect amf`` |
| 424 | and ``err: address family not supported by protocol`` indicates that |
| 425 | your server does not have IPv6 enabled. |
| 426 | |
Larry Peterson | 134bc72 | 2023-08-25 13:47:48 -0700 | [diff] [blame] | 427 | .. admonition:: Troubleshooting Hint |
| 428 | |
| 429 | If ``summary.log`` reports ``UEs Passed: 0 , UEs Failed: 5`` then it |
Larry Peterson | 14b9b95 | 2023-09-21 10:03:44 -0700 | [diff] [blame] | 430 | may be the case that SD-Core did not come up cleanly. Type |
Larry Peterson | 134bc72 | 2023-08-25 13:47:48 -0700 | [diff] [blame] | 431 | ``make aether-resetcore``, and after verifying all pods are running |
| 432 | with ``kubectl``, run gNBsim again. |
| 433 | |
Larry Peterson | 14b9b95 | 2023-09-21 10:03:44 -0700 | [diff] [blame] | 434 | Another possibility is that you have multiple SD-Cores running in |
| 435 | the same broadcast domain. This causes ARP to behave in unexpected |
| 436 | ways, which interferes with OnRamp's ability to establish a route |
| 437 | to the UPF pod. |
| 438 | |
Larry Peterson | 0fa9b36 | 2023-08-09 15:15:13 -0700 | [diff] [blame] | 439 | If you are interested in the config file that controls the test, |
| 440 | including the option of enabling other profiles, take a look at |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 441 | ``deps/gnbsim/config/gnbsim-default.yaml``. We return to the issue of |
Larry Peterson | af9ea36 | 2023-08-11 16:40:19 -0700 | [diff] [blame] | 442 | customizing gNBsim in a later section, but for now there are some |
| 443 | simple modifications you can try. For example, the following code |
| 444 | block defines a set of parameters for ``pdusessest`` (also known as |
| 445 | ``profile2``): |
| 446 | |
| 447 | .. code-block:: |
| 448 | |
| 449 | - profileType: pdusessest # UE Initiated Session |
| 450 | profileName: profile2 |
| 451 | enable: true |
| 452 | gnbName: gnb1 |
| 453 | execInParallel: false |
| 454 | startImsi: 208930100007487 |
| 455 | ueCount: 5 |
| 456 | defaultAs: "192.168.250.1" |
| 457 | perUserTimeout: 100 |
| 458 | plmnId: |
| 459 | mcc: 208 |
| 460 | mnc: 93 |
| 461 | dataPktCount: 5 |
| 462 | opc: "981d464c7c52eb6e5036234984ad0bcf" |
| 463 | key: "5122250214c33e723a5dd523fc145fc0" |
| 464 | sequenceNumber: "16f3b3f70fc2" |
| 465 | |
| 466 | You can edit ``ueCount`` to change the number of UEs included in the |
| 467 | emulation (currently limited to 100) and you can set |
| 468 | ``execInParallel`` to ``true`` to emulate those UEs connecting to the |
Larry Peterson | 80235b9 | 2023-09-22 11:43:16 -0700 | [diff] [blame^] | 469 | Core in parallel (rather than serially). You can also change variable |
| 470 | ``defaultAs: "192.168.250.1"`` to specify the target of ICMP Echo |
| 471 | Request packets sent by the emulated UEs. Selecting the IP address of |
| 472 | a real-world server (e.g., ``8.8.8.8``) is a good test of end-to-end |
| 473 | connectivity. Finally, you can change the amount of information gNBsim |
| 474 | outputs by modifying ``logLevel`` in the ``logger`` block at the end |
| 475 | of the file. For any changes you make, just rerun ``make |
| 476 | aether-gnbsim-run`` to see the effects; you do not need to reinstall |
| 477 | gNBsim. |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 478 | |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 479 | Clean Up |
| 480 | ~~~~~~~~~~~~~~~~~ |
| 481 | |
| 482 | We recommend continuing on to the next section before wrapping up, but |
| 483 | when you are ready to tear down your Quick Start deployment of Aether, |
| 484 | simply execute the following commands: |
| 485 | |
| 486 | .. code-block:: |
| 487 | |
| 488 | $ make aether-gnbsim-uninstall |
| 489 | $ make aether-5gc-uninstall |
| 490 | $ make aether-k8s-uninstall |
| 491 | |
| 492 | Note that while we stepped through the system one component at a time, |
| 493 | OnRamp includes compound Make targets. For example, you can uninstall |
| 494 | everything covered in this section by typing: |
| 495 | |
| 496 | .. code-block:: |
| 497 | |
| 498 | $ make aether-uninstall |
| 499 | |
| 500 | Look at the ``Makefile`` to see the available set of Make targets. |