From ae0397136d9fbb2dd6d392f30b8dab1c32706388 Mon Sep 17 00:00:00 2001 From: Larry Peterson Date: Wed, 30 Oct 2024 14:42:32 -0700 Subject: [PATCH 1/3] sync with onramp refactor Signed-off-by: Larry Peterson --- conf.py | 4 +-- onramp/blueprints.rst | 20 ++++++----- onramp/gnb.rst | 32 ++++++++++------- onramp/network.rst | 26 +++++++++----- onramp/overview.rst | 10 +++--- onramp/start.rst | 7 ++-- testing/integration_tests.rst | 68 ++++++++++------------------------- 7 files changed, 79 insertions(+), 88 deletions(-) diff --git a/conf.py b/conf.py index 9d642c9..e193e03 100644 --- a/conf.py +++ b/conf.py @@ -281,8 +281,8 @@ def get_version(): intersphinx_mapping = { 'ansible': ('https://docs.ansible.com/ansible/latest', None), 'sphinx': ('https://www.sphinx-doc.org/en/master', None), - 'sdcore': ('https://docs.sd-core.opennetworking.org/main', None), - 'sdran': ('https://docs.sd-ran.org/master', None), + 'sdcore': ('https://docs.sd-core.aetherproject.org/main', None), + 'sdran': ('https://docs.sd-ran.aetherproject.org/master', None), 'sysapproach5g': ('https://5g.systemsapproach.org/', None), 'sysapproachnet': ('https://book.systemsapproach.org/', None), 'sysapproachsdn': ('https://sdn.systemsapproach.org/', None), diff --git a/onramp/blueprints.rst b/onramp/blueprints.rst index 9f9a9d4..cbce9ff 100644 --- a/onramp/blueprints.rst +++ b/onramp/blueprints.rst @@ -307,11 +307,14 @@ The UERANSIM blueprint includes the following: [master_nodes] node1 + [worker_nodes] + #node2 + [ueransim_nodes] node2 -* New make targets, ``aether-ueransim-install``, - ``aether-ueransim-run``, and ``aether-ueransim-uninstall``, to be +* New make targets, ``ueransim-install``, + ``ueransim-run``, and ``ueransim-uninstall``, to be executed after the standard SD-Core installation. * A new submodule ``deps/ueransim`` (corresponding to repo @@ -320,7 +323,8 @@ The UERANSIM blueprint includes the following: for the emulator. * The Jenkins pipeline ``ueransim.groovy`` validates the UERANSIM - blueprint. + blueprint. It also illustrates how to run Linux commands that + exercise the user plane from the emulated UE. To use UERANSIM, first copy the vars file to ``main.yml``: @@ -335,15 +339,15 @@ followed by UERANSIM: .. code-block:: - $ make aether-k8s-install - $ make aether-5gc-install - $ make aether-ueransim-install - $ make aether-ueransim-run + $ make k8s-install + $ make 5gc-install + $ make ueransim-install + $ make ueransim-run The last step actually starts UERANSIM, configured according to the specification given in files ``custom-gnb.yaml`` and ``custom-ue.yaml`` located in ``deps/ueransim/config``. Make target -``aether-ueransim-run`` can be run multiple times, where doing so +``ueransim-run`` can be run multiple times, where doing so reflects any recent edits to the config files. More information about UERANSIM can be found on `GitHub `__, including how to set up the diff --git a/onramp/gnb.rst b/onramp/gnb.rst index 9ee05c7..9e557b4 100644 --- a/onramp/gnb.rst +++ b/onramp/gnb.rst @@ -71,18 +71,26 @@ using. .. code-block:: - core: - standalone: true - data_iface: ens18 - values_file: "deps/5gc/roles/core/templates/radio-5g-values.yaml" - ran_subnet: "" - helm: - chart_ref: aether/sd-core - chart_version: 0.12.6 - upf: - ip_prefix: "192.168.252.0/24" - amf: - ip: "10.76.28.113" + core: + standalone: true # set to false to place under control of ROC + data_iface: ens18 + values_file: "deps/5gc/roles/core/templates/radio-5g-values.yaml" + ran_subnet: "" # set to empty string to get subnet from 'data_iface' + helm: + local_charts: false # set chart_ref to local path name if true + chart_ref: aether/sd-core + chart_version: 1.1.0 + upf: + ip_prefix: "192.168.252.0/24" + iface: "access" + mode: af_packet # Options: af_packet or dpdk + default_upf: + ip: + access: "192.168.252.3/24" + core: "192.168.250.3/24" + ue_ip_pool: "172.250.0.0/16" + amf: + ip: "10.76.28.113" Prepare UEs diff --git a/onramp/network.rst b/onramp/network.rst index fd4569c..c48d494 100644 --- a/onramp/network.rst +++ b/onramp/network.rst @@ -210,23 +210,31 @@ section are defined in the ``core`` and ``gnbsim`` sections of the ``vars/main.yml`` file. Note that an empty value for ``core.ran_subnet`` implies the physical L2 network is used to connect RAN elements to the core, as is typically the case when connecting -physical gNBs. - +physical gNBs. Many of the other variables are explained in subsequent +sections, but for a summary, see the :doc:`Quick Reference `. .. code-block:: core: - standalone: true + standalone: true # set to false to place under control of ROC data_iface: ens18 - values_file: "config/sdcore-5g-values.yaml" - ran_subnet: "172.20.0.0/16" + values_file: "deps/5gc/roles/core/templates/sdcore-5g-values.yaml" + ran_subnet: "172.20.0.0/16" # set to empty string to get subnet from 'data_iface' helm: - chart_ref: aether/sd-core - chart_version: 0.12.6 + local_charts: false # set chart_ref to local path name if true + chart_ref: aether/sd-core + chart_version: 1.1.0 upf: - ip_prefix: "192.168.252.0/24" + ip_prefix: "192.168.252.0/24" + iface: "access" + mode: af_packet # Options: af_packet or dpdk + default_upf: + ip: + access: "192.168.252.3/24" + core: "192.168.250.3/24" + ue_ip_pool: "172.250.0.0/16" amf: - ip: "10.76.28.113" + ip: "10.76.28.113" gnbsim: ... diff --git a/onramp/overview.rst b/onramp/overview.rst index ed1d974..1f64e5a 100644 --- a/onramp/overview.rst +++ b/onramp/overview.rst @@ -54,7 +54,9 @@ and Kubernetes (rather than depending entirely on OnRamp's playbooks). That final :doc:`Other Blueprints ` section then gives a synopsis of several additional OnRamp blueprints. Each -blueprint enables a particular combination of Ansible features, -demonstrating how those features are enabled, configured, and -deployed. This section presumes familiarity with all of OnRamp's -capabilities introduced in the earlier sections. +blueprint enables a particular combination of Aether features, +demonstrating how those features are configured, and deployed. This +section presumes familiarity with all of OnRamp's capabilities +introduced in the earlier sections. For a summary review of all +available blueprints, see the :doc:`Quick Reference ` +guide. diff --git a/onramp/start.rst b/onramp/start.rst index 31aa2da..9b57eb9 100644 --- a/onramp/start.rst +++ b/onramp/start.rst @@ -4,10 +4,11 @@ Quick Start This section describes a low-overhead way to get started with OnRamp. It brings up a one-node Kubernetes cluster, deploys a 5G version of SD-Core on that cluster, and runs an emulated 5G workload against the -5G Core. It assumes a low-end server that meets the following +5G Core. It assumes a modest server that meets the following requirements: -* Haswell CPU (or newer), with at least 4 CPU cores and 16GB RAM. +* Haswell CPU (or newer), with at least 4 CPU cores (ideally 8) and + 16GB RAM (ideally 32GB). * Clean install of Ubuntu 20.04 or 22.04, with 5.15 (or later) kernel. For example, something like an Intel NUC is likely more than enough to get @@ -18,7 +19,7 @@ in a VirtualBox VM), because the goal is to eventually scale a deployment and/or run Aether 24/7, OnRamp has been developed and tested on physical servers and server-based VMs. The latter includes Proxmox (see the example configuration shown in :numref:`Figure %s -`); AWS (specify a ``t2.xlarge`` instance); and CloudLab +`); AWS (specify an ``M7iFlex2xlarge`` instance); and CloudLab (specify either a ``small-lan`` or ``single-pc-ubuntu`` instance). .. _fig-proxmox: diff --git a/testing/integration_tests.rst b/testing/integration_tests.rst index af4d35e..5935ce8 100644 --- a/testing/integration_tests.rst +++ b/testing/integration_tests.rst @@ -5,53 +5,21 @@ Integration Tests =================== -A set of integration tests run daily to validate various -configurations of Aether, corresponding to the set of supported -:doc:`OnRamp Blueprints `. The tests are managed -by Jenkins, and can be monitored using the following -`Dashboard `__. -The following summarizes the current set of tests. - -Basic Functionality ----------------------- - -These tests validate the base components, configured with (``AMP``) or -without the Aether Management Plane; running on either a single server -(``QuickStart``) or two servers (``2server``); configured with the -officially released Helm Charts (``default-charts``) or the most -recently published charts (``latest-charts``); and deployed on Ubuntu -``20.04`` or ``22.04``. - -* ``AetherOnRamp_QuickStart_20.04_default-charts`` -* ``AetherOnRamp_QuickStart_22.04_default-charts`` -* ``AetherOnRamp_QuickStart_20.04_latest-charts`` -* ``AetherOnRamp_QuickStart_22.04_latest-charts`` -* ``AetherOnRamp_QuickStart_20.04_AMP`` -* ``AetherOnRamp_QuickStart_22.04_AMP`` -* ``AetherOnRamp_2servers_20.04_default-charts`` -* ``AetherOnRamp_2servers_22.04_default-charts`` - -Advanced Functionality ----------------------------- - -These tests validate blueprints that incorporate additional -functionality, including being configured with alternative RANs -(``Physical-ENB``, ``Physical-GNB``, ``SD-RAN``, ``UERANSIM``) and -with multiple UPF pods (``Multi-UPF``). - -* ``AetherOnRamp_2servers_20.04_UERANSIM`` -* ``AetherOnRamp_QuickStart_20.04_UERANSIM`` -* ``AetherOnRamp_2servers_Multi-UPF`` -* ``AetherOnRamp_QuickStart_Multi-UPF`` -* ``AetherOnRamp_QuickStart_SD-RAN`` -* ``AetherOnRamp_Physical-ENB`` -* ``AetherOnRamp_Physical-GNB`` - -Testing In-Depth -------------------------- - -Although still a work-in-progress, we also plan for additional -in-depth tests, including automated testing of the :doc:`Aether API -`. - -* ``AetherOnRamp_QuickStart_API-Test`` +A set of integration tests validate various configurations of Aether. +The tests are managed by Jenkins, and can be monitored using the +following `Dashboard `__. + +Source code for the integration tests can be found on `GitHub +`__, where each +file in the repo corresponds to a Groovy script that implements a Jenkins pipeline +for one of the :doc:`Aether Blueprints `. + +The pipelines are executed daily, with each pipeline parameterized to +run in multiple jobs. The ``${AgentLabel}`` parameter selects the +Ubuntu release being tested (currently ``20.04`` and ``22.04``), +with all jobs running in AWS VMs (currently resourced as ``M7iFlex2xlarge``). +Pipelines that exercise two-server tests (e.g., ``ueransim.groovy``, ``upf.groovy``, +and ``gnbsim.groovy`` run in VMs that have the +`AWS CLI `__ installed; the CLI is is used to create +the second VM. All VMs have Ansible installed, as documented in the +:doc:`OnRamp Guide `. From d97ab793d15aefce7211312770de3639606cd857 Mon Sep 17 00:00:00 2001 From: Larry Peterson Date: Wed, 30 Oct 2024 14:47:43 -0700 Subject: [PATCH 2/3] jenkins & docs repos Signed-off-by: Larry Peterson --- onramp/directory.rst | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/onramp/directory.rst b/onramp/directory.rst index cca7de2..eee0655 100644 --- a/onramp/directory.rst +++ b/onramp/directory.rst @@ -124,12 +124,18 @@ self-contained if you are interested in deploying just that subsystem, but this guide approaches the deployment challenge from an integrated, end-to-end perspective. -Because OnRamp uses Ansible as its primary deployment tool, a general -understanding of Ansible is helpful (see the suggested reference). -However, this guide walks you, step-by-step, through the process of -deploying and operating Aether, so previous experience with Ansible is -not a requirement. Note that Ansible has evolved to be both a -"Community Toolset" anyone can use to manage a software deployment, +There are two other Aether-related repos of note; they are **not** +managed as submodules of ``aether-onramp``: + + | Aether Documentation: https://github.com/opennetworkinglab/aether-docs + | Jenkins Pipelines: https://github.com/opennetworkinglab/aether-jenkins + +Finally, because OnRamp uses Ansible as its primary deployment tool, a +general understanding of Ansible is helpful (see the suggested +reference). However, this guide walks you, step-by-step, through the +process of deploying and operating Aether, so previous experience with +Ansible is not a requirement. Note that Ansible has evolved to be both +a "Community Toolset" anyone can use to manage a software deployment, and an "Automation Platform" offered as a service by RedHat. OnRamp uses the toolset, but not the platform/service. From 383e124243d93931de097f24360aa74e5cb4e1b0 Mon Sep 17 00:00:00 2001 From: Larry Peterson Date: Wed, 30 Oct 2024 14:52:26 -0700 Subject: [PATCH 3/3] fixed typo Signed-off-by: Larry Peterson --- onramp/ref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/onramp/ref.rst b/onramp/ref.rst index 70fc984..6cae6c0 100644 --- a/onramp/ref.rst +++ b/onramp/ref.rst @@ -47,7 +47,7 @@ repo. The groovy files can be found in the `aether-jenkins - `main-upf.yml` - `upf.groovy` - Instantiate multiple UPFs and bind them to distinct Slices. - * - `SD-RAN (RIC) `__ + * - `SD-RAN (RIC) `__ - `main-sdran.yml` - `sdran.groovy` - SD-RAN (with RANSIM traffic) connected to 5G Core.