Merge pull request #30 from opennetworkinglab/maintenance

Maintenance

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),

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
 <https://github.com/aligungr/UERANSIM>`__, including how to set up the

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.
 

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

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 </onramp/ref>`.
 
 .. 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:
         ...

onramp/overview.rst

@@ -54,7 +54,9 @@ and Kubernetes (rather than depending entirely on OnRamp's playbooks).
 
 That final :doc:`Other Blueprints </onramp/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 </onramp/ref>`
+guide.

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) <https://docs.aetherproject.org/master/onramp/blueprints.html#sd-ran>`__
+   * - `SD-RAN (RIC) <https://docs.aetherproject.org/master/onramp/blueprints.html#sd-ran-ric>`__
      - `main-sdran.yml`
      - `sdran.groovy`
      - SD-RAN (with RANSIM traffic) connected to 5G Core.

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
-<fig-proxmox>`); AWS (specify a ``t2.xlarge`` instance); and CloudLab
+<fig-proxmox>`); AWS (specify an ``M7iFlex2xlarge`` instance); and CloudLab
 (specify either a ``small-lan`` or ``single-pc-ubuntu`` instance).
 
 .. _fig-proxmox:

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 </onramp/blueprints>`. The tests are managed
-by Jenkins, and can be monitored using the following
-`Dashboard <https://jenkins.aetherproject.org/view/Aether%20OnRamp/>`__.
-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
-</testing/aether-roc-tests>`.
-
-* ``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 <https://jenkins.aetherproject.org/>`__.
+
+Source code for the integration tests can be found on `GitHub
+<https://github.com/opennetworkinglab/aether-jenkins>`__, where each
+file in the repo corresponds to a Groovy script that implements a Jenkins pipeline
+for one of the :doc:`Aether Blueprints </onramp/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 <https://aws.amazon.com/cli/>`__ installed; the CLI is is used to create
+the second VM. All VMs have Ansible installed, as documented in the
+:doc:`OnRamp Guide </onramp/start>`.