recommend OnRamp
Change-Id: I97c96445fd6e3ed2529dd3b5f02282fa2ac5c080
diff --git a/developer/aiab.rst b/developer/aiab.rst
index 34b577b..1ae7d67 100644
--- a/developer/aiab.rst
+++ b/developer/aiab.rst
@@ -1,748 +1,40 @@
.. vim: syntax=rst
-Aether-in-a-Box for Developers
-==============================
+Development Environment
+=========================
-Aether-in-a-Box (AiaB) provides an easy way to deploy Aether's SD-CORE and ROC
-components, and then run basic tests to validate the installation.
-This guide describes the steps to set up AiaB.
+There are different ways to build a development environment for
+Aether. Historically, Aether-in-a-Box (AiaB) has provided an easy way
+to deploy and test Aether. AiaB is still available (as documented in
+`Version 2.1 of this Guide
+<https://docs.aetherproject.org/aether-2.1/developer/aiab.html>`__),
+but it is no long supported.
-AiaB can be set up with a 4G or 5G SD-CORE. In either case, SD-CORE configuration
-can be done with or without the ROC. The ROC
-provides an interactive GUI for examining and changing the configuration, and is used to
-manage the production Aether; it can be deployed to test the integration between
-ROC and SD-CORE. If the ROC is not deployed, a simple tool called SimApp
-is used to configure the required state in SD-CORE for testing core functionality.
+`Aether OnRamp
+<https://docs.aetherproject.org/master/onramp/overview.html>`__, which
+builds on AiaB, is now the recommended way to deploy and test
+Aether. It works across a range of scenarios, from a single VM running
+an emulated RAN to a multi-node cluster supporting a physical
+RAN. OnRamp's `Quick Start blueprint
+<https://docs.aetherproject.org/master/onramp/start.html>`__ is
+the closest in functionality to AiaB.
-Helm charts are the primary method of installing the SD-CORE and ROC resources.
-AiaB offers a great deal of flexibility regarding which Helm chart versions to install:
+.. note:: If you are already using AiaB for your development, it
+ should continue to work for the foreseeable future. One reason to
+ consider migrating to OnRamp is that it establishes a well-defined
+ procedure for contributing new configurations (OnRamp calls them
+ `blueprints <https://docs.aetherproject.org/master/onramp/blueprints.html>`__)
+ back to the community. This includes daily integration tests to ensure
+ that various combinations of features continue to function correctly.
-* Local definitions of charts (for testing Helm chart changes)
-* Latest published charts (for deploying a development version of Aether)
-* Specified versions of charts (for deploying a specific Aether release)
+Finally, many developers prefer to work directly with Helm and
+Kubernetes, bypassing the scripts/playbooks that AiaB and OnRamp
+provide. This approach is especially efficient when you are working on
+a single component and not concerned with cross-component integration.
+The following section on ROC Development adopts this approach. For
+details about contributing to SD-Core and SD-RAN, we refer you to
+their respective guides:
-AiaB can be run on a bare metal machine or VM. System prerequisites:
+* :doc:`SD-Core Documentation <sdcore:index>`
-* AiaB 4G: Ubuntu 18.04 clean install (18.04 is a requirement of OAISIM which is used to test 4G Aether)
-* AiaB 5G: Ubuntu 18.04, 20.04, 22.04 [#]_
-* Kernel 4.15 or later
-* Haswell CPU or newer
-* At least 4 CPUs and 12GB RAM
-* Ability to run "sudo" without a password. Due to this requirement, AiaB is most suited
- to disposable environments like a VM or a `CloudLab <https://cloudlab.us>`_ machine.
-* No firewall running on the AiaB host. For example, `sudo ufw status` should show `inactive`,
- and `sudo iptables -L` and `sudo nft list` should show a blank configuration.
-
-.. [#] AiaB requires to increase the maximum number of available watches and the maximum number of
- inotify instances in Ubuntu 22.04. Otherwise, there will be a "time out" error due to "Too many
- files open". Some users have also reported to see this issue when using Ubuntu 20.04. :ref:`AiaB
- fails too many files open <developer/troubleshooting:AiaB fails during deployment of SD-Core network>`
- provides more details on how to address this issue.
-
-.. note::
- * Running both 4G and 5G SD-CORE simultaneously in AiaB is currently not supported.
- * AiaB changes the host server by adding systemd-networkd configuration files to the
- host's network configuration. Systemd-networkd is the default networking configuration
- tool for Ubuntu, but if your server or VM uses a different method it may not be fully
- compatible with AiaB.
-
-Ubuntu Environment
-------------------
-
-AiaB has been tested in the following environments:
-
-* Bare metal (on `CloudLab <https://cloudlab.us>`_ Wisconsin cluster, `small-lan` profile running `UBUNTU 18.04` OS image)
-* AWS VM (official Ubuntu 18.04 image on `t2.xlarge` instance)
-* VirtualBox VM running `bento/ubuntu-18.04` `Vagrant <https://www.vagrantup.com>`_ box on Intel Mac
-* VM created using `Multipass <https://multipass.run>`_ on Intel Mac
-
-The `Multipass <https://multipass.run>`_ tool by Canonical provides an easy way to create a compatible
-environment for playing with AiaB on Linux, Mac, or Windows. After installing Multipass on your development
-machine, you can bring up a VM as follows::
-
- multipass launch 18.04 --cpus 4 --disk 50G --mem 12G --name aiab
- multipass shell aiab
- sudo apt update
- sudo apt install -y make
-
-Proxy Settings (Conditional)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-AiaB can also be installed behind a proxy. To do so you will need to set the
-standard Linux environment variables `http_proxy`, `https_proxy`, `no_proxy`,
-`HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` appropriately, and i) prepend
-`PROXY_ENABLED=true` to the `make` commands in this document or
-ii) export `PROXY_ENABLED=true` as follows::
-
- make {arg} PROXY_ENABLED=true
-
-or::
-
- export PROXY_ENABLED=true
-
-The latter option can be included in the `.bashrc` file to make it permanent.
-
-Installing the 4G AIAB
-----------------------
-
-Clone 4G AIAB (aether-in-a-box)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To initialize the AiaB environment, first clone the following repository in your home directory::
-
- cd ~
- git clone "https://gerrit.opencord.org/aether-in-a-box"
- cd ~/aether-in-a-box
-
-.. note::
- * Most users install AiaB using *published Helm charts* (e.g., `CHARTS=latest`, `CHARTS=release-2.0`)
- * If you wish to modify helm charts and want to test AIAB with modified helm charts then check the
- section - :ref:`local-helm-4g`
-
-
-Installing the 4G ROC
-^^^^^^^^^^^^^^^^^^^^^
-
-Note that you must install the ROC *before* installing SD-CORE.
-If you are not using the ROC to configure SD-CORE, you can skip this step.
-
-In order to install the ROC using the latest published charts, add *CHARTS=latest*
-to the command, e.g.,::
-
- CHARTS=latest make roc-4g-models
-
-To install the Aether 2.0 release, add *CHARTS=release-2.0*::
-
- CHARTS=release-2.0 make roc-4g-models
-
-
-The ROC has successfully initialized when you see output like this::
-
- echo "ONOS CLI pod: pod/onos-cli-5b947f8f6-4r5nm"
- ONOS CLI pod: pod/onos-cli-5b947f8f6-4r5nm
- until kubectl -n aether-roc exec pod/onos-cli-5b947f8f6-4r5nm -- \
- curl -s -f -L -X PATCH "http://aether-roc-api:8181/aether-roc-api" \
- --header 'Content-Type: application/json' \
- --data-raw "$(cat /root/aether-in-a-box//roc-5g-models.json)"; do sleep 5; done
- command terminated with exit code 22
- command terminated with exit code 22
- command terminated with exit code 22
- "9513ea10-883d-11ec-84bf-721e388172cd"
-
-Don't worry if you see a few lines of *command terminated with exit code 22*; that command is trying to
-load the ROC models, and the message appears if the ROC isn't ready yet. However if you see that message
-more than 10 times then something is probably wrong with the ROC or its models.
-
-
-Installing the 4G SD-CORE
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you have already installed the 5G SD-CORE, you must skip this step. Only one version of
-the SD-CORE can be installed at a time.
-
-
-To install the SD-CORE using the latest published charts, add *CHARTS=latest*
-to the command, e.g.,::
-
- CHARTS=latest make test #override value file - `~/aether-in-a-box/sd-core-4g-values.yaml`
-
-To install the Aether 2.0 release, add *CHARTS=release-2.0*::
-
- CHARTS=release-2.0 make test #override value file - `~/aether-in-a-box/release-2.0/sd-core-4g-values.yaml`
-
-4G SD-CORE deploys the following core components to provide mobile connectivity:
-
-* SPGW (Serving/PDN Gateway): Combined Serving Gateway and Packet Data Network (PDN) Gateway
-* UPF (User Plane Function): The interconnect between the mobile infrastructure and the Data Network (DN).
-* PCRF (Policy and Charging Rules Function): Data flow detection, policy enforcement, and flow-based charging.
-* MME (Mobility Management Entity): Manages UE access network and mobility, and establishing the bearer path for UE.
-* HSS (Home Subscriber Server): The main subscriber database.
-* Config4g (Config Pod)
-
-.. figure:: images/4g-call-flow.png
- :align: center
- :width: 80 %
-
- *Communication between 4G SD-CORE Components*
-
-The eNB (evolved Node B) is the Radio Access Network (RAN) of the 4G architecture and allows
-the UEs to connect to the Mobile network.
-It passes UE's attach request to MME via S1AP interface to be identified and authenticated through HSS.
-MME sends the session request to SPGW to create the GTP tunnel and request the default bearer. SPGW sends back the UPF
-address to establish the connectivity (GTP tunnel) to the DN through the user plane.
-
-When the AiaB is up, you can explicitly specify the *oip1* interface within the command to send
-data over the 4G datapath. Examples::
-
- curl --interface oip1 http://ipv4.download.thinkbroadband.com/5MB.zip --output /dev/null
- ping -I oip1 google.com
- iperf3 -c la.speedtest.clouvider.net -p 5204 -B 172.250.255.254
-
-AiaB deploys a router pod in the "default" namespace with four interfaces: *ran-gw* for the radio network,
-*access-gw* for access network, *core-gw* for core network, and *eth0* for the external network.
-When a UE starts sending traffics to the data network through the user plane (access network),
-the uplink (UE to internet) data packets traverse the following path across the pods::
-
- (oip1) enb-0 (enb) ==GTP==> (ran-gw) router (access-gw) ==GTP==> (access) upf-0 (core)
- ----> (core-gw) router (NAT,eth0)
-
-And the downlink (internet to UE) packets follow as::
-
- (NAT,eth0) router (core-gw) ----> (core) upf-0 (access) ==GTP==> (access-gw) router (ran-gw)
- ==GTP==> (enb) enb-0 (oip1)
-
-.. note::
- In the above notations, network interfaces within each pod are shown in parenthesis.
- The IP packets sent/received between the UE and external host via the user plane are GTP-encapsulated
- and tunneled between the eNB and UPF.
-
-Exploring 4G AIAB
-^^^^^^^^^^^^^^^^^
-
-The *kubectl* tool is the best way to get familiar with the pods and other Kubernetes objects installed by AiaB.
-The SD-CORE services, UPF, and simulated edge devices run in the *omec* namespace, while the ROC is running
-in the *aether-roc* namespace.
-
-The ROC GUI is available on port 31194 on the host running AiaB.
-
-Cleanup 4G AIAB
-^^^^^^^^^^^^^^^
-
-The first time you build AiaB, it takes a while because it sets up the Kubernetes cluster.
-Subsequent builds will be much faster if you follow these steps to clean up the Helm charts without
-destroying the Kubernetes cluster.
-
-* Clean up the 4G SD-CORE: *make reset-test*
-* Reset the 4G UE / eNB in order to re-run the 4G test: *make reset-ue*
-* Clean up the ROC: *make roc-clean*
-
-It's normal for the above commands to take a minute or two to complete.
-
-As an example, suppose that you want to test the 4G SD-CORE with the ROC, and then the 5G SD-CORE
-with the ROC. You could run these commands::
-
- CHARTS=latest make roc-4g-models # Install ROC with 4G configuration
- CHARTS=latest make test # Install 4G SD-CORE and run ping test
- make reset-test
- make roc-clean
- CHARTS=latest make roc-5g-models # Install ROC with 5G configuration
- CHARTS=latest make 5g-test # Install 5G SD-CORE and run gNB Sim test
- make reset-5g-test
- make roc-clean
-
-To completely remove AiaB by tearing down the Kubernetes cluster, run *make clean*.
-
-.. _developer-4g-loop:
-
-Using Custom 4G Container Images
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Suppose you wish to test a new build of a 4G SD-CORE services. You can deploy custom images
-by editing::
-
- Override file - `~/aether-in-a-box/sd-core-4g-values.yaml` if you are using latest or local Helm charts
- Override file - `~/aether-in-a-box/release-2.0/sd-core-4g-values.yaml` if you are using release-2.0 charts
-
-
- #update following content in override values to update image tags
- omec-control-plane:
- images:
- repository: "" # default docker hub
- tags:
- mme: omecproject/nucleus:master-a8002eb
- pullPolicy: IfNotPresent
-
-To upgrade a running 4G SD-CORE with the new image, or to deploy the 4G SD-CORE with the image. Use appropriate
-make commands. Following commands assumes that you are using local helm charts ::
-
- make reset-test; make test #if you are not using local charts then CHARTS option
-
-**Note**: You can use locally built image (Clone + Compile Code) or you can refer to omecproject
-dockerhub project to see available image tags.
-
-.. _local-helm-4g:
-
-Using Local Helm Charts 4G
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-**Note**: Most users will install AiaB using *published Helm charts* (e.g., `CHARTS=latest`,
-`CHARTS=release-2.0`). However, if you need to change the Helm
-charts themselves, clone these additional repositories to work with the *local Helm charts*::
-
- mkdir -p ~/cord
- cd ~/cord
- git clone "https://gerrit.opencord.org/sdcore-helm-charts"
- git clone "https://gerrit.opencord.org/roc-helm-charts"
- git clone "https://gerrit.opencord.org/sdfabric-helm-charts"
- cd ~/aether-in-a-box
-
-Modify the helm charts as per your need. Also execute `helm dep update .` in the changed helm
-chart repo. Example below to add testOpt option in mme.::
-
- node0:~/cord/sdcore-helm-charts$ git diff
- diff --git a/omec-control-plane/Chart.yaml b/omec-control-plane/Chart.yaml
- index 79c3738..48ae901 100644
- --- a/omec-control-plane/Chart.yaml
- +++ b/omec-control-plane/Chart.yaml
- @@ -9,4 +9,4 @@ description: OMEC control plane services
- name: omec-control-plane
- icon: https://guide.opencord.org/logos/cord.svg
-
- -version: 0.11.1
- +version: 0.11.2
- diff --git a/omec-control-plane/values.yaml b/omec-control-plane/values.yaml
- index 33ac6ce..a6b994a 100644
- --- a/omec-control-plane/values.yaml
- +++ b/omec-control-plane/values.yaml
- @@ -395,6 +395,7 @@ config:
- - id: frequency
- type: integer
- mme:
- + testOpt: true
- deploy: true
- podAnnotations:
- fluentbit.io/parser: mme
- diff --git a/sdcore-helm-charts/Chart.yaml b/sdcore-helm-charts/Chart.yaml
- index 44a5558..151eb07 100644
- --- a/sdcore-helm-charts/Chart.yaml
- +++ b/sdcore-helm-charts/Chart.yaml
- @@ -8,7 +8,7 @@ name: sd-core
- description: SD-Core control plane services
- icon: https://guide.opencord.org/logos/cord.svg
- type: application
- -version: 0.11.8
- +version: 0.11.9
- home: https://opennetworking.org/sd-core/
- maintainers:
- - name: SD-Core Support
- @@ -16,9 +16,9 @@ maintainers:
-
- dependencies:
- - name: omec-control-plane
- - version: 0.11.1
- - repository: https://charts.aetherproject.org
- - #repository: "file://../omec-control-plane"
- + version: 0.11.2
- + #repository: https://charts.aetherproject.org
- + repository: "file://../omec-control-plane" #refer local helm chart
- condition: omec-control-plane.enable4G
-
- - name: omec-sub-provision
- node0:~/cord/sdcore-helm-charts$
-
- node0:~$ cd cord/sdcore-helm-charts/omec-control-plane/
- node0:~/cord/sdcore-helm-charts/omec-control-plane$ helm dependency update .
-
-
-To install the ROC from the local charts::
-
- make roc-4g-models
-
-To install the 4G SD-CORE from the local charts::
-
- make test
-
-.. note::
- * Helm chart changes can not be done when CHARTS option is used. If you need to change helm chart then you should use local helm charts
-
-Troubleshooting 4G Issues
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-**NOTE: Running both 4G and 5G SD-CORE simultaneously in AiaB is currently not supported.**
-
-If you suspect a problem, first verify that all pods are in Running state::
-
- kubectl -n omec get pods
- kubectl -n aether-roc get pods
-
-4G Test Fails
-*************
-
-Occasionally *make test* (for 4G) fails for unknown reasons; this is true regardless of which Helm charts are used.
-If this happens, first try recreating the simulated UE / eNB and re-running the test as follows::
-
- make reset-ue
- make test
-
-If that does not work, try cleaning up AiaB as described above and re-building it.
-
-If *make test* fails consistently, check whether the configuration has been pushed to the SD-CORE::
-
- kubectl -n omec logs config4g-0 | grep "Successfully"
-
-You should see that a device group and slice has been pushed::
-
- [INFO][WebUI][CONFIG] Successfully posted message for device group 4g-oaisim-user to main config thread
- [INFO][WebUI][CONFIG] Successfully posted message for slice default to main config thread
-
-Then tail the *config4g-0* log and make sure that the configuration has been successfully pushed to all
-SD-CORE components.
-
-
-.. note::
- Please refer to the Troubleshooting section for more details.
-
-Installing the 5G AIAB
-----------------------
-
-Clone 5G AIAB (aether-in-a-box)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To initialize the AiaB environment, first clone the following repository in your home directory::
-
- cd ~
- git clone "https://gerrit.opencord.org/aether-in-a-box"
- cd ~/aether-in-a-box
-
-.. note::
- * Most users install AiaB using *published Helm charts* (e.g., `CHARTS=latest`, `CHARTS=release-2.0`)
- * If you wish to modify helm charts and want to test AIAB with modified helm charts then check the
- section :ref:`local-helm-5g`
-
-
-Installing the ROC for 5G
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Note that you must install the ROC *before* installing SD-CORE.
-If you are not using the ROC to configure SD-CORE, you can skip this step.
-
-To install the ROC using the latest published charts, add *CHARTS=latest*
-to the command, e.g.,::
-
- CHARTS=latest make roc-5g-models #override value file - `~/aether-in-a-box/sd-core-5g-values.yaml`
-
-To install the Aether 2.0 release, add *CHARTS=release-2.0*::
-
- CHARTS=release-2.0 make roc-5g-models #override value file - `~/aether-in-a-box/release-2.0/sd-core-5g-values.yaml`
-
-The ROC has successfully initialized when you see output like this::
-
- echo "ONOS CLI pod: pod/onos-cli-5b947f8f6-4r5nm"
- ONOS CLI pod: pod/onos-cli-5b947f8f6-4r5nm
- until kubectl -n aether-roc exec pod/onos-cli-5b947f8f6-4r5nm -- \
- curl -s -f -L -X PATCH "http://aether-roc-api:8181/aether-roc-api" \
- --header 'Content-Type: application/json' \
- --data-raw "$(cat /root/aether-in-a-box//roc-5g-models.json)"; do sleep 5; done
- command terminated with exit code 22
- command terminated with exit code 22
- command terminated with exit code 22
- "9513ea10-883d-11ec-84bf-721e388172cd"
-
-Don't worry if you see a few lines of *command terminated with exit code 22*; that command is trying to
-load the ROC models, and the message appears if the ROC isn't ready yet. However if you see that message
-more than 10 times then something is probably wrong with the ROC or its models.
-
-
-Installing the 5G SD-CORE
-^^^^^^^^^^^^^^^^^^^^^^^^^
-If you have already installed the 4G SD-CORE, you must skip this step. Only one version of
-the SD-CORE can be installed at a time.
-
-To deploy the 5G SD-CORE and run a test with gNBSim that performs Registration + UE-initiated
-PDU Session Establishment + sends User Data packets.
-
-In order to install the SD-CORE using the latest published charts, add *CHARTS=latest*
-to the command, e.g.,::
-
- CHARTS=latest make 5g-test
-
-To install the Aether 2.0 release, add *CHARTS=release-2.0*::
-
- CHARTS=release-2.0 make 5g-test
-
-To change the behavior of the test run by gNBSim, change the contents of *gnb.conf*
-in *sd-core-5g-values.yaml*. Consult the
-`gNBSim documentation <https://docs.sd-core.opennetworking.org/master/developer/gnbsim.html>`_ for more information.
-
-Deploying Additional UPF(s)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-There may be cases where the user wants/needs to deploy additional UPS(s) and
-to facilitate this a "target" was added to the Makefile::
-
- CHARTS=latest make 5g-upf
-
-The above command has to be executed after the SD Core network has been
-deployed as follows::
-
- ENABLE_GNBSIM=false DATA_IFACE=<iface> CHARTS=latest make 5g-core
-
-where ``<iface>`` is the network interface connecting the AiaB server
-to the local L2/L3 network. If not, you will receive a message saying::
-
- Deploy '5g-core' before adding additional UPF(s)
- make: *** [Makefile:359: 5g-upf] Error 1
-
-Every time the above command is executed, a new UPF is deployed in a new
-namespace, where the namespace has the following format: "upf-#", where
-"#" is an increasing value that starts with "1". In other words, the first
-time the "5g-upf" target is executed, a new UPF is deployed and its namespace
-is "upf-1", the next time it gets executed, another UPF is deployed and its
-name space is "upf-2", and so on.
-
-The "5g-upf" target also takes care of the networking configuration for the
-UPF. That is, it will assign IP addresses for the UPF's Core and Access
-interfaces in an ascending way, where the first additional UPF will get
-"IP_ID = 4", second additional UPF will get "IP_ID = 5", and so on::
-
- access:
- iface: ${DATA_IFACE}
- ip: 192.168.252.${IP_ID}/24
- core:
- iface: ${DATA_IFACE}
- ip: 192.168.250.${IP_ID}/24
-
-In addition to this, it will also insert a route in the "router", where
-"IP_UE_ID = 249" for the 1st additional UPF, and "IP_UE_ID" will keep
-decreasing by 1 for every additional UPF::
-
- kubectl -n default exec -ti router -- ip route add 172.$(IP_UE_ID).0.0/16 via 192.168.250.$(IP_ID)
-
-There is also the option to remove ALL additional UPF(s) by executing the "make
-upf-clean" command. It will also delete the "upf-#" namespaces and remove
-the routing entries from the router. When the 5G core is removed through "make
-reset-5g-test", it will also remove ALL additional UPF(s).
-
-.. note::
-
- The "CHARTS=latest make 5g-upf" command ONLY deploys additional UPFs
- with their own connectivity. It does NOT create slices.
-
-
-Exploring 5G AIAB
-^^^^^^^^^^^^^^^^^
-
-The *kubectl* tool is the best way to get familiar with the pods and other Kubernetes objects installed by AiaB.
-The SD-CORE services, UPF, and simulated edge devices run in the *omec* namespace, while the ROC is running
-in the *aether-roc* namespace.
-
-The ROC GUI is available on port 31194 on the host running AiaB.
-
-
-Cleanup 5G AIAB
-^^^^^^^^^^^^^^^
-
-The first time you build AiaB, it takes a while because it sets up the Kubernetes cluster.
-Subsequent builds will be much faster if you follow these steps to clean up the Helm charts without
-destroying the Kubernetes cluster.
-
-* Clean up the 5G SD-CORE: *make reset-5g-test*
-* Clean up the ROC: *make roc-clean*
-
-It's normal for the above commands to take a minute or two to complete.
-
-As an example, suppose that you want to test the 4G SD-CORE with the ROC, and then the 5G SD-CORE
-with the ROC. You could run these commands::
-
- CHARTS=latest make roc-4g-models # Install ROC with 4G configuration
- CHARTS=latest make test # Install 4G SD-CORE and run ping test
- make reset-test
- make roc-clean
- CHARTS=latest make roc-5g-models # Install ROC with 5G configuration
- CHARTS=latest make 5g-test # Install 5G SD-CORE and run gNB Sim test
- make reset-5g-test
- make roc-clean
-
-To completely remove AiaB by tearing down the Kubernetes cluster, run *make clean*.
-
-.. _developer-5g-loop:
-
-Using Custom 5G Container Images
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Suppose you wish to test a new build of a 5G SD-CORE services. You can deploy custom images
-by editing::
-
-
- Override file - `~/aether-in-a-box/sd-core-5g-values.yaml` if you are using latest or local Helm charts
- Override file - `~/aether-in-a-box/release-2.0/sd-core-5g-values.yaml` if you are using release-2.0 charts
-
- #update following content in override values to update image tags
- 5g-control-plane:
- images:
- tags:
- webui: registry.aetherproject.org/omecproject/5gc-webui:onf-release3.0.5-roc-935305f
- pullPolicy: IfNotPresent
-
-To upgrade a running 5G SD-CORE with the new image, or to deploy the 5G SD-CORE with the image. Use appropriate
-make commands. Following commands assumes that you are using local helm charts ::
-
- make reset-5g-test; make 5g-test #if you are not using local charts then use CHARTS option
-
-**Note**: You can use locally built image (Clone + Compile Code) or you can refer to omecproject
-dockerhub project to see available image tags.
-
-.. _local-helm-5g:
-
-Using Local Helm Charts 5G
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-**Note**: Most users will install AiaB using *published Helm charts* (e.g., `CHARTS=latest`,
-`CHARTS=release-2.0`). However, if you need to change the Helm
-charts themselves, clone these additional repositories to work with the *local Helm charts*::
-
- mkdir -p ~/cord
- cd ~/cord
- git clone "https://gerrit.opencord.org/sdcore-helm-charts"
- git clone "https://gerrit.opencord.org/roc-helm-charts"
- git clone "https://gerrit.opencord.org/sdfabric-helm-charts"
- cd ~/aether-in-a-box
-
-Modify the helm charts as per your need. Also execute `helm dep update .` in the changed helm
-chart repo. Example below to add testOpt option in amf.::
-
- node0:~/cord/sdcore-helm-charts$ git diff
- diff --git a/5g-control-plane/Chart.yaml b/5g-control-plane/Chart.yaml
- index 421e7e5..3cea334 100644
- --- a/5g-control-plane/Chart.yaml
- +++ b/5g-control-plane/Chart.yaml
- @@ -10,7 +10,7 @@ description: SD-Core 5G control plane services
- name: 5g-control-plane
- icon: https://guide.opencord.org/logos/cord.svg
-
- -version: 0.7.10
- +version: 0.7.11
-
- dependencies:
- - name: mongodb
- diff --git a/5g-control-plane/values.yaml b/5g-control-plane/values.yaml
- index 8ddcf66..c15d77d 100644
- --- a/5g-control-plane/values.yaml
- +++ b/5g-control-plane/values.yaml
- @@ -417,6 +417,7 @@ config:
- ngapIpList:
- - "0.0.0.0"
- amf:
- + testOpt: true
- deploy: true
- podAnnotations:
- field.cattle.io/workloadMetrics: '[{"path":"/metrics","port":9089,"schema":"HTTP"}]'
- diff --git a/sdcore-helm-charts/Chart.yaml b/sdcore-helm-charts/Chart.yaml
- index 44a5558..8f52f77 100644
- --- a/sdcore-helm-charts/Chart.yaml
- +++ b/sdcore-helm-charts/Chart.yaml
- @@ -8,7 +8,7 @@ name: sd-core
- description: SD-Core control plane services
- icon: https://guide.opencord.org/logos/cord.svg
- type: application
- -version: 0.11.8
- +version: 0.11.9
- home: https://opennetworking.org/sd-core/
- maintainers:
- - name: SD-Core Support
- @@ -28,9 +28,9 @@ dependencies:
- condition: omec-sub-provision.enable
-
- - name: 5g-control-plane
- - version: 0.7.8
- - repository: https://charts.aetherproject.org
- - #repository: "file://../5g-control-plane"
- + version: 0.7.11
- + #repository: https://charts.aetherproject.org
- + repository: "file://../5g-control-plane" #enable this line to refer locally changed helm charts
- condition: 5g-control-plane.enable5G
-
- - name: bess-upf
- node0:~/cord/sdcore-helm-charts$
-
- node0:~$ cd cord/sdcore-helm-charts/5g-control-plane/
- node0:~/cord/sdcore-helm-charts/5g-control-plane$ helm dependency update .
-
-To install the ROC from the local charts::
-
- make roc-5g-models
-
-To install the 5G SD-CORE from the local charts::
-
- make 5g-test
-
-.. note::
- * Helm chart changes can not be done when CHARTS option is used. If you need to change helm chart then you should use local helm charts
-
-
-Troubleshooting 5G Issues
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-**NOTE: Running both 4G and 5G SD-CORE simultaneously in AiaB is currently not supported.**
-
-If you suspect a problem, first verify that all pods are in Running state::
-
- kubectl -n omec get pods
- kubectl -n aether-roc get pods
-
-5G Test Fails
-*************
-
-If the 5G test fails (*make 5g-test*) then you will see output like this::
-
- 2022-04-21T17:59:12Z [INFO][GNBSIM][Summary] Profile Name: profile2 , Profile Type: pdusessest
- 2022-04-21T17:59:12Z [INFO][GNBSIM][Summary] Ue's Passed: 2 , Ue's Failed: 3
- 2022-04-21T17:59:12Z [INFO][GNBSIM][Summary] Profile Errors:
- 2022-04-21T17:59:12Z [ERRO][GNBSIM][Summary] imsi:imsi-208930100007492, procedure:REGISTRATION-PROCEDURE, error:triggering event:REGESTRATION-REQUEST-EVENT, expected event:AUTHENTICATION-REQUEST-EVENT, received event:REGESTRATION-REJECT-EVENT
- 2022-04-21T17:59:12Z [ERRO][GNBSIM][Summary] imsi:imsi-208930100007493, procedure:REGISTRATION-PROCEDURE, error:triggering event:REGESTRATION-REQUEST-EVENT, expected event:AUTHENTICATION-REQUEST-EVENT, received event:REGESTRATION-REJECT-EVENT
- 2022-04-21T17:59:12Z [ERRO][GNBSIM][Summary] imsi:imsi-208930100007494, procedure:REGISTRATION-PROCEDURE, error:triggering event:REGESTRATION-REQUEST-EVENT, expected event:AUTHENTICATION-REQUEST-EVENT, received event:REGESTRATION-REJECT-EVENT
- 2022-04-21T17:59:12Z [INFO][GNBSIM][Summary] Simulation Result: FAIL
-
-In this case check whether the *webui* pod has restarted... this can happen if it times out waiting
-for the database to come up::
-
- $ kubectl -n omec get pod -l app=webui
- NAME READY STATUS RESTARTS AGE
- webui-6b9c957565-zjqls 1/1 Running 1 (6m55s ago) 7m56s
-
-If the output shows any restarts, then restart the *simapp* pod to cause it to re-push its subscriber state::
-
- $ kubectl -n omec delete pod -l app=simapp
- pod "simapp-6c49b87c96-hpf82" deleted
-
-Re-run the 5G test, it should now pass.
-
-.. note::
- Please refer to the Troubleshooting section for more details.
-
-Packet Capture
---------------
-
-`Ksniff <https://github.com/eldadru/ksniff>`_ is a Kubernetes-integrated packet sniffer shipped as a kubectl plugin.
-Ksniff uses tcpdump and Wireshark (Wireshark 3.x) to capture traffic on a specific pod within the cluster.
-After installing Ksniff using Krew and Wireshark, by running the following command
-you can see the communications between the components. Ksniff uses kubectl to upload
-the tcpdump binary into the target container (e.g. mme, amf, upf, ...), and redirects the output to Wireshark::
-
- kubectl sniff -n omec mme-0
-
-**Note**: To collect packets using Wireshark, the (virtual) machine where Ksniff/Wireshark is running needs
-to have a Desktop environment installed for Wireshark to run. Also, note that the desktop machine running
-Ksniff/Wireshark doesn't need to be the same machine as the one running AiaB.
-
-You can see the packets sent/received between the core components from the moment an
-UE initiates the attach procedure through eNB until
-the dedicated bearer (uplink and downlink) has been established (see figure below).
-After the bearer has been established, traffic sent from UE's interface (*oip1*) will go through the eNB and UPF.
-
-.. figure:: images/wireshark-4g.png
- :width: 80 %
- :align: center
-
- *Wireshark output of ksniff on mme pod*
-
-Using Ksniff on the router pod you can see all the packets exchanged between the UE and external hosts
-(e.g. ping an external host from the UE interface)::
-
- kubectl sniff -n default router
-
-.. figure:: images/4g-ue-ping.png
- :width: 80 %
- :align: center
-
- *Data Flow from UE to an external host through the User Plane (filtered on UE's IP address)*
-
-Looking at the packet's details, the first and second packets are from *enb* to *router*
-and then to *upf* in a GTP tunnel. And the third packet is sent from *router* to the external network via NAT.
-The rest are the reply packets from the external host to the UE.
-
-By default, Ksniff runs *tcpdump* on all interfaces (i.e. *-i any*). To retrieve more details
-of packets (e.g. ethernet header information) on a specific interface,
-you can explicitly specify the interface along with options (e.g. *-e*). e.g.::
-
- kubectl sniff -n default router -i access-gw -f "-e"
+* :doc:`SD-RAN Documentation <sdran:index>`
diff --git a/developer/contributing.rst b/developer/contributing.rst
index 02feb69..1820996 100644
--- a/developer/contributing.rst
+++ b/developer/contributing.rst
@@ -157,39 +157,6 @@
comments section, the TST meetings are a good place to raise your concerns and
have a discussion.
-Current Core Contributors
-"""""""""""""""""""""""""
-
-Aether-Roc-Api:
-
-* ``Pushp Raj``
-
-Chronos Exporter:
-
-* ``Pushp Raj``
-
-Subscriber Proxy:
-
-* ``Amit Wankhede``
-* ``Pushp Raj``
-
-Prom-Label-Proxy:
-
-* ``Amit Wankhede``
-
-All of the codebase:
-
-* ``Shad Ansari``
-* ``Scott Baker``
-* ``Andy Bavier``
-* ``Hung-Wei Chiu``
-* ``Sean Condon``
-* ``Kevin Marquardsen``
-* ``Hyunsun Moon``
-* ``Don Newton``
-* ``Matteo Scandolo``
-* ``Zack Williams``
-
Community Guidelines
--------------------
diff --git a/amp/monitoring.rst b/developer/monitoring.rst
similarity index 71%
rename from amp/monitoring.rst
rename to developer/monitoring.rst
index 800936d..8aa6eb6 100644
--- a/amp/monitoring.rst
+++ b/developer/monitoring.rst
@@ -8,13 +8,14 @@
Aether leverages `Prometheus <https://prometheus.io/docs/introduction/overview/>`_ to collect
and store platform and service metrics, `Grafana <https://grafana.com/docs/grafana/latest/getting-started/>`_
to visualize metrics over time, and `Alertmanager <https://prometheus.io/docs/alerting/latest/alertmanager/>`_ to
-notify Aether OPs staff of events requiring attention. This monitoring stack is running on each Aether cluster.
+notify Aether operators of events requiring attention. This monitoring stack is running on each Aether cluster.
This section describes how an Aether component can "opt in" to the Aether monitoring stack so that its metrics can be
collected and graphed, and can trigger alerts.
Exporting Service Metrics to Prometheus
---------------------------------------
+
An Aether component implements a `Prometheus exporter <https://prometheus.io/docs/instrumenting/writing_exporters/>`_
to expose its metrics to Prometheus. An exporter provides the current values of a components's
metrics via HTTP using a simple text format. Prometheus scrapes the exporter's HTTP endpoint and stores the metrics
@@ -31,36 +32,49 @@
Working with Grafana Dashboards
--------------------------------
-Once the local cluster's Prometheus is collecting a component's metrics, they can be visualized using Grafana
-dashboards. The Grafana instance running on the AMP cluster is able to send queries to the Prometheus
-servers running on all Aether clusters. This means that component metrics can be visualized on the AMP Grafana
-regardless of where the component is actually running.
-In order to create a new Grafana dashboard or modify an existing one, first login to the AMP Grafana using an account
-with admin privileges. To add a new dashboard, click the **+** at left. To make a copy of an existing dashboard for
-editing, click the **Dashboard Settings** icon (gear icon) at upper right of the existing dashboard, and then
-click the **Save as…** button at left.
+Once the local cluster's Prometheus is collecting a component's
+metrics, they can be visualized using Grafana dashboards. The Grafana
+instance running on the AMP cluster is able to send queries to the
+Prometheus servers running on all Aether clusters. This means that
+component metrics can be visualized on the AMP Grafana regardless of
+where the component is actually running.
-Next, add panels to the dashboard. Since Grafana can access Prometheus on all the clusters in the environment,
-each cluster is available as a data source. For example, when adding a panel showing metrics collected on the
-ace-menlo cluster, choose ace-menlo as the data source.
+In order to create a new Grafana dashboard or modify an existing one,
+first login to the AMP Grafana using an account with admin privileges.
+To add a new dashboard, click the **+** at left. To make a copy of an
+existing dashboard for editing, click the **Dashboard Settings** icon
+(gear icon) at upper right of the existing dashboard, and then click
+the **Save as…** button at left.
-Clicking on the floppy disk icon at top will save the dashboard *temporarily* (the dashboard is not
-saved to persistent storage and is deleted as soon as Grafana is restarted). To save the dashboard *permanently*,
-click the **Share Dashboard** icon next to the title and save its JSON to a file. Then add the file to the
-aether-app-configs repository so that it will be deployed by Fleet:
+Next, add panels to the dashboard. Since Grafana can access
+Prometheus on all the clusters in the environment, each cluster is
+available as a data source. For example, when adding a panel showing
+metrics collected on the ace-menlo cluster, choose ace-menlo as the
+data source.
-* Change to directory ``aether-app-configs/infrastructure/rancher-monitoring/overlays/<amp-cluster>/``
+Clicking on the floppy disk icon at top will save the dashboard
+*temporarily* (the dashboard is not saved to persistent storage and is
+deleted as soon as Grafana is restarted). To save the dashboard
+*permanently*, click the **Share Dashboard** icon next to the title
+and save its JSON to a file. Then add the file to the
+AMP submodule of OnRamp so that it will be deployed by Ansible:
+
+* Change to directory ``aeher-onramp/deps/amp/roles/monitor-load/templates/``
* Copy the dashboard JSON file to the ``dashboards/`` sub-directory
* Edit ``kustomization.yaml`` and add the new dashboard JSON under ``configmapGenerator``
-* Commit the changes and submit patchset to gerrit
-
-Once the patchset is merged, the AMP Grafana will automatically detect and deploy the new dashboard.
Adding Service-specific Alerts
------------------------------
+
An alert can be triggered in Prometheus when a component metric crosses a threshold. The Alertmanager
-then routes the alert to one or more receivers (e.g., an email address or Slack channel).
+then routes the alert to one or more receivers (e.g., an email address
+or Slack channel).
+
+.. note:: This section on alerts is specific to an operational
+ instantiation of Aether that is no supported. A port of this
+ capability to Aether OnRamp (so it is available to anyone
+ that wants to operate Aether) is pending.
To add an alert for a component, create a
`PrometheusRule <https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/user-guides/alerting.md>`_
diff --git a/developer/roc.rst b/developer/roc.rst
index 9b7f96a..281d828 100644
--- a/developer/roc.rst
+++ b/developer/roc.rst
@@ -5,21 +5,14 @@
ROC Development
===============
-Background / Development Environment
-------------------------------------
+This document assumes familiarity with Kubernetes and Helm, and that a
+Kubernetes/Helm development environment has already been deployed in
+the developer’s work environment (for example, using a mechanism like
+KinD or kubeadm).
-This document assumes familiarity with Kubernetes and Helm, and that a Kubernetes/Helm development
-environment has already been deployed in the developer’s work environment.
-
-This development environment can use any of a number of potential mechanisms -- including KinD, kubeadm, etc.
-
-The Aether-in-a-Box script is one potential way to setup a development environment, but not the only way.
-As an alternative to the developer’s local machine, a remote environment can be set up, for example on
-cloud infrastructure such as Cloudlab.
-
-.. note:: When ROC is deployed it is unsecured by default, with no Authentication or Authorization.
+.. note:: By default, ROC is deployed without security enabled, with no Authentication or Authorization.
To secure ROC so that the Authentication and Authorization can be tested, follow the Securing ROC
- guide below :ref:`securing_roc`
+ section below :ref:`securing_roc`.
Installing Prerequisites
------------------------
@@ -42,7 +35,7 @@
ONOS_OPERATOR_VERSION=0.5.6
helm install -n kube-system onos-operator onosproject/onos-operator --version $ONOS_OPERATOR_VERSION
-.. note:: The ROC is sensitive to the versions of Atomix and onos-operator installed. The values
+.. note:: ROC is sensitive to the versions of Atomix and onos-operator installed. The values
shown above are correct for the 2.1.36- versions of the *aether-roc-umbrella*.
.. list-table:: ROC support component version matrix
@@ -104,12 +97,13 @@
- 1.1.2
- 0.5.6
-.. note::
- Changing between atomix and operators in a cluster may cause problems if there are changes in the definition of
- the CRDs that they include. To fully ensure a clean installation the CRDs should be deleted manually AFTER deleting
- the old version of atomix or Onos Operator.
+.. note:: Changing between atomix and operators in a cluster may cause problems
+ if there are changes in the definition of the CRDs that they
+ include. To fully ensure a clean installation the CRDs should be
+ deleted manually AFTER deleting the old version of atomix or ONOS
+ Operator.
- Use `kubectl get crds | grep atomix` and `kubectl get crds | grep onos` to see the CRDs present.
+Use `kubectl get crds | grep atomix` and `kubectl get crds | grep onos` to see the CRDs present.
Verify that these services were installed properly.
You should see pods for *atomix-controller(s)*
@@ -137,11 +131,13 @@
.. _posting-the-mega-patch:
-Posting the mega-patch
+Posting the Mega-Patch
----------------------
-The ROC usually comes up in a blank state -- there are no Enterprises, UEs, or other artifacts present in it.
-The mega-patch is an example patch that populates the ROC with some sample enterprises, UEs, slices, etc.
+The ROC usually comes up in a blank state; there are no Enterprises,
+UEs, or other artifacts present in it. The Mega-Patch is an example
+patch that populates the ROC with some sample enterprises, UEs,
+slices, etc.
Execute the following::
@@ -158,61 +154,63 @@
# execute the mega-patch (it will post via CURL to localhost:8181)
bash ~/path/to/aether-roc-api/examples/MEGA_Patch_20.curl
-.. note:: To configure Aether-In-a-Box - no port-forward is necessary - use the URL *http://<hostname>:31194/aether-roc-api/*
+.. note:: No port-forwarding is necessary to configure Aether
+ OnRamp. Use URL *http://<hostname>:31194/aether-roc-api/*.
-You may wish to customize the mega patch.
-
-For example, by default the patch configures the ``sdcore-adapter`` to push to
-``sdcore-test-dummy``.
-
-You could configure it to push to a live aether-in-a-box core by doing something like this::
+You may wish to customize the mega patch. For example, by default the
+patch configures the ``sdcore-adapter`` to push to
+``sdcore-test-dummy``. You could instead configure it to push to a
+live instantiation of Aether by doing something like this::
sed -i 's^http://aether-roc-umbrella-sdcore-test-dummy/v1/config/5g^http://webui.omec.svc.cluster.local:9089/config^g' MEGA_Patch_21.curl
#apply the patch
./MEGA_Patch_20.curl
-(Note that if your Aether-in-a-Box was installed on a different machine that port-forwarding may be necessary)
+Note that if Aether is installed on a different machine, then port-forwarding may be necessary.
+Expected CURL output from a successful Mega-Patch post will be a UUID.
-Expected CURL output from a successful mega-patch post will be a UUID.
-
-You can also verify that the mega-patch was successful by going into the
+You can also verify that the Mega-Patch was successful by going into the
``aether-roc-gui`` in a browser (see the section on useful port-forwards
-below). The GUI may open to a dashboard that is unpopulated -- you can use the
+below). The GUI may open to a dashboard that is unpopulated. You can use the
dropdown menu (upper-right hand corner of the screen) to select an object such
as Slice and you will see a list of slices.
|ROCGUI|
-Adding new Enterprises
+Adding New Enterprises
----------------------
-Enterprises are stored in `onos-topo` outside of `onos-config` are are usually only created by system administrators
-during the onboarding of new customers (tenants) on Aether.
+Enterprises are stored in `onos-topo` outside of `onos-config` are are
+usually only created by system administrators during the onboarding of
+new customers (tenants) on Aether.
-There is currently no way of adding new Enterprises through the ROC GUI or the ROC API - it can be
-done in the 2 ways in the following sections.
+There is currently no way of adding new Enterprises through the ROC
+GUI or the ROC API. It can be done in the two ways described in the
+following sections.
-Enterprises are specified as Entities using CRDs, and the `onos-operator` ensures that these are created
-as `entitites` inside `onos-topo`.
+Enterprises are specified as Entities using CRDs, and the
+`onos-operator` ensures that these are created as `entitites` inside
+`onos-topo`.
To check that the current list of enterprises (as CRDs), the following command may be used::
kubectl -n aether get entities
-and to check that the `onos-operator` does indeed take effect, the ROC API endpoint `/targets` can be used to list the
-`enterprises`.
+and to check that the `onos-operator` does indeed take effect, the ROC
+API endpoint `/targets` can be used to list the `enterprises`.
Another option is to use the `onos-cli` pod to query `onos-topo` directly::
kubectl -n aether exec deployment/onos-cli -- onos topo get entities -v
-Adding new Enterprises through Helm Chart
+Adding New Enterprises Through Helm Chart
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-To have an entity added at **start up of the cluster** it can be added through the Helm Chart in the `values.yaml`
-under `enterprises`. e.g.::
+To have an entity added at **start up of the cluster** it can be added
+through the Helm Chart in the `values.yaml` under
+`enterprises`. e.g.::
enterprises:
- id: starbucks
@@ -222,11 +220,12 @@
This will load the `enterprise` as an Entity CRD through the `onos-operator`.
-Adding new Enterprises through `onos-topo`
+Adding New Enterprises Through `onos-topo`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-New `enterprises` can be added to a live running system through the `onos-topo` command line (bypassing
-the `onos-operator`). For example::
+New `enterprises` can be added to a live running system through the
+`onos-topo` command line (bypassing the `onos-operator`). For
+example::
kubectl -n aether exec deployment/onos-cli -- \
onos topo create entity new-enterprise \
@@ -236,22 +235,26 @@
-a onos.topo.MastershipState='{}' \
-k enterprise
-Uninstalling the ``aether-roc-umbrella`` Helm chart
+Uninstalling the ``aether-roc-umbrella`` Helm Chart
---------------------------------------------------
-To tear things back down, usually as part of a developer loop prior to redeploying again, do the following::
+To tear things back down, usually as part of a developer loop prior to
+redeploying again, do the following::
helm -n aether del aether-roc-umbrella
-Useful port forwards
+Useful Port Forwards
--------------------
-Port forwarding is often necessary to allow access to ports inside of Kubernetes pods that use ClusterIP addressing.
-Note that you typically need to leave a port-forward running (you can put it in the background).
-Also, If you redeploy the ROC and/or if a pod crashes then you might have to restart a port-forward.
+Port forwarding is often necessary to allow access to ports inside of
+Kubernetes pods that use ClusterIP addressing. Note that you
+typically need to leave a port-forward running (you can put it in the
+background). Also, If you redeploy the ROC and/or if a pod crashes
+then you might have to restart a port-forward.
-.. note:: With Aether-In-a-Box no port-forward is necessary - the GUI can be accessed
- at ``http://<hostname>:31194`` and the API at ``http://<hostname>:31194/aether-roc-api/``
+.. note:: No port-forward is necessary with OnRamp. The GUI
+ can be accessed at ``http://<hostname>:31194`` and the API at
+ ``http://<hostname>:31194/aether-roc-api/``.
The following port-forwards may be useful::
@@ -267,13 +270,14 @@
kubectl -n aether port-forward service/aether-roc-umbrella-grafana --address 0.0.0.0 8187:80
-.. note:: Internally the ``aether-roc-gui`` operates a Reverse Proxy on the ``aether-roc-api``. This
- means that if you have done a ``port-forward`` to ``aether-roc-gui`` say on port ``8183`` there's no
- need to do another on the ``aether-roc-api`` instead you can access the API on
- ``http://localhost:8183/aether-roc-api``
+.. note:: Internally, the ``aether-roc-gui`` operates a Reverse Proxy
+ on the ``aether-roc-api``. This means that if you have done a
+ ``port-forward`` to ``aether-roc-gui``, say on port ``8183``,
+ there's no need to do another on the ``aether-roc-api``. Instead,
+ you can access the API on ``http://localhost:8183/aether-roc-api``.
-Deploying using custom images
------------------------------
+Deploying Custom Images
+--------------------------
Custom images may be used by editing the values-override.yaml file.
For example, to deploy a custom ``sdcore-adapter``::
@@ -285,22 +289,23 @@
tag: my-tag
pullPolicy: Always
-The above example assumes you have published a docker images at ``my-private-repo/sdcore-adapter:my-tag``.
-My particular workflow is to deploy a local-docker registry and push my images to that.
-Please do not publish ONF images to a public repository unless the image is intended to be public.
-Several ONF repositories are private, and therefore their docker artifacts should also be private.
+The above example assumes you have published a docker images at
+``my-private-repo/sdcore-adapter:my-tag``. One possible workflow is
+to deploy a local-docker registry and push images to that.
-There are alternatives to using a private docker repository.
-For example, if you are using kubeadm, then you may be able to simply tag the image locally.
-If you’re using KinD, then you can push a local image to into the kind cluster::
+There are alternatives to using a private docker repository. For
+example, if you are using kubeadm, then you may be able to simply tag
+the image locally. If you’re using KinD, then you can push a local
+image to into the kind cluster::
kind load docker-image sdcore-adapter:my-tag
-Developing using a custom onos-config
+Developing with a Custom onos-config
-------------------------------------
-The onos-config helm chart is responsible for loading model plugins at runtime. You can override which
-plugins it loads, and optionally override the image for onos-config as well. For example::
+The onos-config Helm Chart is responsible for loading model plugins at
+runtime. You can override which plugins it loads, and optionally
+override the image for onos-config as well. For example::
onos-config:
image:
@@ -316,14 +321,16 @@
endpoint: localhost
port: 5153
-In the above example, the onos-config image will be pulled from `mydockeraccount`, and it will install
-two plugins for v2 and v4 models, from that same docker account.
+In the above example, the onos-config image will be pulled from
+`mydockeraccount`, and it will install two plugins for v2 and v4
+models, from that same docker account.
-Inspecting logs
+Inspecting Logs
---------------
-Most of the relevant Kubernetes pods are in the aether namespace.
-The names may change from deployment to deployment, so start by getting a list of pods::
+Most of the relevant Kubernetes pods are in the aether namespace. The
+names may change from deployment to deployment, so start by getting a
+list of pods::
kubectl -n aether get pods
@@ -339,46 +346,30 @@
Running your own Keycloak Server
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. note:: Unfortunately there is no longer a central keycloak server for development as there was
- at `keycloak-dev.onlab.us`, so you must run your own own Keycloak server inside of Kubernetes.
+.. note:: There is no longer a central keycloak server
+ for development as there was at `keycloak-dev.onlab.us`, so you
+ must run your own own Keycloak server inside of Kubernetes.
See `Keycloak README.md <https://gerrit.opencord.org/plugins/gitiles/roc-helm-charts/+/refs/heads/master/keycloak/>`_ for details.
-It has the following users by default.
+When running it should be available at
+*http://localhost:8080/realms/master/.well-known/openid-configuration*.
-+------------------+----------+-----------------+-----------------+-----------+------+------------+-----------------+
-| User | login | AetherROCAdmin | EnterpriseAdmin | starbucks | acme | defaultent | aiab-enterprise |
-+==================+==========+=================+=================+===========+======+============+=================+
-| Alice Admin | alicea | ✓ | | | | | |
-+------------------+----------+-----------------+-----------------+-----------+------+------------+-----------------+
-| Bob Cratchit | bobc | | | | | | |
-+------------------+----------+-----------------+-----------------+-----------+------+------------+-----------------+
-| Charlie Brown | charlieb | | | | | | |
-+------------------+----------+-----------------+-----------------+-----------+------+------------+-----------------+
-| Daisy Duke | daisyd | | ✓ | ✓ | | | ✓ |
-+------------------+----------+-----------------+-----------------+-----------+------+------------+-----------------+
-| Elmer Fudd | elmerf | | | ✓ | | | ✓ |
-+------------------+----------+-----------------+-----------------+-----------+------+------------+-----------------+
-| Fred Flintstone | fredf | | ✓ | | ✓ | ✓ | |
-+------------------+----------+-----------------+-----------------+-----------+------+------------+-----------------+
-| Gandalf The Grey | gandalfg | | | | ✓ | ✓ | |
-+------------------+----------+-----------------+-----------------+-----------+------+------------+-----------------+
+.. note:: You can access the Keycloak management page from
+ *http://localhost:8080/admin* but you must login as
+ `admin`. Because of the SSO feature of Keycloak this will affect
+ your Aether ROC GUI login too. To login as two separate users at
+ the same time, use a private browser window for one.
+.. note:: Services inside the cluster (e.g. onos-config) should set
+ the issuer to *https://keycloak/realms/master* on port 80, while
+ the aether-roc-gui should use `http://localhost:8080/realms/master`.
-When running it should be available at *http://localhost:8080/realms/master/.well-known/openid-configuration*.
+Enabling Security
+^^^^^^^^^^^^^^^^^^^^^
-.. note:: You can access the Keycloak management page from *http://localhost:8080/admin* but you must
- login as `admin`. Because of the SSO feature of Keycloak this will affect your Aether ROC GUI login too.
- To login as 2 separate users at the same time, use a private browser window for one.
-
-.. note:: Services inside the cluster (e.g. onos-config) should set the issuer to *https://keycloak/realms/master*
- on port 80, while the aether-roc-gui should use `http://localhost:8080/realms/master`
-
-Enabling security in the cluster
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When deploying ROC with the ``aether-roc-umbrella`` chart, secure mode can be enabled by
-specifying an OpenID Connect (OIDC) issuer like::
+When deploying ROC with the ``aether-roc-umbrella`` chart, secure mode
+can be enabled by specifying an OpenID Connect (OIDC) issuer; for example::
helm -n aether install aether-roc-umbrella aether/aether-roc-umbrella \
--set onos-config.openidc.issuer=http://keycloak/realms/master \
@@ -389,48 +380,48 @@
--set prom-label-proxy-acc.config.openidc.issuer=http://keycloak/realms/master \
--set prom-label-proxy-amp.config.openidc.issuer=http://keycloak/realms/master
-The choice of OIDC issuer in this case is the **local** Keycloak server at *http://keycloak* inside the `aether` namespace.
-
-
-As any OIDC server can work with ROC you can alternately use ``dex-ldap-umbrella``
-(`deprecated <https://github.com/onosproject/onos-helm-charts/tree/master/dex-ldap-umbrella>`_).
+The choice of OIDC issuer in this case is the **local** Keycloak
+server at *http://keycloak* inside the `aether` namespace.
Production Environment
^^^^^^^^^^^^^^^^^^^^^^
-In a production environment, the public Aether Keycloak (with its LDAP server populated with real Aether users and groups) should be used.
-See `public keycloak <https://keycloak.opennetworking.org/auth/realms/master/.well-known/openid-configuration>`_ for more details.
+
+In a production environment, the public Aether Keycloak (with its LDAP
+server populated with real Aether users and groups) should be used.
+See `public keycloak
+<https://keycloak.opennetworking.org/auth/realms/master/.well-known/openid-configuration>`_
+for more details.
.. note:: Your RBAC access to ROC will be limited by the groups you belong to in its LDAP store.
Role Based Access Control
^^^^^^^^^^^^^^^^^^^^^^^^^
-When secured, access to the configuration in ROC is limited by the **groups** that a user belongs to.
+When secured, access to the configuration in ROC is limited by the
+**groups** that a user belongs to.
* **AetherROCAdmin** - users in this group have full read **and** write access to all configuration.
* *<enterprise>* - users in a group the lowercase name of an enterprise, will have **read** access to that enterprise.
* **EnterpriseAdmin** - users in this group will have read **and** write access the enterprise they belong to.
- For example in *keycloak-389-umbrella* the user *Daisy Duke* belongs to *starbucks* **and**
- *EnterpriseAdmin* and so has read **and** write access to items linked with *starbucks* enterprise.
-
- By comparison the user *Elmer Fudd* belongs only to *starbucks* group and so has only **read** access to items
- linked with the *starbucks* enterprise.
Requests to a Secure System
^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When configuration is retrieved or updated through *aether-config*, a Bearer Token in the
-form of a JSON Web Token (JWT) issued by the selected OIDC Issuer server must accompany
-the request as an Authorization Header.
+When configuration is retrieved or updated through *aether-config*, a
+Bearer Token in the form of a JSON Web Token (JWT) issued by the
+selected OIDC Issuer server must accompany the request as an
+Authorization Header.
-This applies to both the REST interface of ``aether-roc-api`` **and** the *gnmi* interface of
-``aether-config``.
+This applies to both the REST interface of ``aether-roc-api`` **and**
+the *gnmi* interface of ``aether-config``.
-In the Aether ROC, a Bearer Token can be generated by logging in and selecting API Key from the
-menu. This pops up a window with a copy button, where the key can be copied.
+In the Aether ROC, a Bearer Token can be generated by logging in and
+selecting API Key from the menu. This pops up a window with a copy
+button, where the key can be copied.
-Alternatively with Keycloak a Token may be requested programmatically through the Keycloak API::
+Alternatively with Keycloak a Token may be requested programmatically
+through the Keycloak API::
curl --location --request POST 'http://localhost:8080/realms/master/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
@@ -515,7 +506,7 @@
ROC Data Model Conventions and Requirements
-------------------------------------------
-The MEGA-Patch described above will bring up a fully compliant sample data model.
+The Mega-Patch described above will bring up a fully compliant sample data model.
However, it may be useful to bring up your own data model, customized to a different
site of sites. This subsection documents conventions and requirements for the Aether
modeling within the ROC.
@@ -525,32 +516,6 @@
* A default enterprise with the id `defaultent`.
* A default site with the id `defaultent-defaultsite`.
This site should be within the `defaultent` enterprise.
- This site is used by ``subscriber-proxy`` to place detected SIM Cards that cannot
- be matched to an existing site.
-
-Some exercises to get familiar
-------------------------------
-
-1. Deploy the ROC and POST the mega-patch, go into the ``aether-roc-gui`` and click
- through the Slice, DeviceGroup, and other objects to see that they were
- created as expected.
-
-2. Examine the log of the ``sdcore-adapter-v2`` container. It should be
- attempting to push the mega-patch’s changes. If you don’t have a core
- available, it may be failing the push, but you should see the attempts.
-
-3. Change an object in the GUI. Watch the ``sdcore-adapter-v2`` log file and
- see that the adapter attempts to push the change.
-
-4. Try POSTing a change via the API. Observe the ``sdcore-adapter-v2`` log
- file and see that the adapter attempts to push the change.
-
-5. Deploy a 5G Aether-in-a-Box (See :doc:`Setting Up Aether-in-a-Box
- <aiab>`), modify the mega-patch to specify the URL for the Aether-in-a-Box
- ``webui`` container, POST the mega-patch, and observe that the changes were
- correctly pushed via the ``sdcore-adapter-v2`` into the ``sd-core``’s
- ``webui`` container (``webui`` container log will show configuration as it
- is received)
.. |ROCGUI| image:: images/rocgui.png
:width: 945
diff --git a/developer/troubleshooting.rst b/developer/troubleshooting.rst
deleted file mode 100644
index d07b439..0000000
--- a/developer/troubleshooting.rst
+++ /dev/null
@@ -1,324 +0,0 @@
-.. vim: syntax=rst
-
-.. _aiab_troubleshooting:
-
-Troubleshooting Aether-in-a-Box
-===============================
-
-FAQs
-----
-
-RKE2 vs. Kubespray Install
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The AiaB installer will bring up Kubernetes on the server where it is run. By default it
-uses `RKE2 <https://docs.rke2.io>`_ as the Kubernetes platform. However, older versions of AiaB
-used `Kubespray <https://kubernetes.io/docs/setup/production-environment/tools/kubespray/>`_
-and that is still an option. To switch to Kubespray as the Kubernetes platform, edit the
-Makefile and replace *rke2* with *kubespray* on this line::
-
- node0:~/aether-in-a-box$ git diff Makefile
- diff --git a/Makefile b/Makefile
- index 5f2c186..608c221 100644
- --- a/Makefile
- +++ b/Makefile
- @@ -35,7 +35,7 @@ ENABLE_GNBSIM ?= true
- ENABLE_SUBSCRIBER_PROXY ?= false
- GNBSIM_COLORS ?= true
-
- -K8S_INSTALL ?= rke2
- +K8S_INSTALL ?= kubespray
- CTR_CMD := sudo /var/lib/rancher/rke2/bin/ctr --address /run/k3s/containerd/containerd.sock --namespace k8s.io
-
- PROXY_ENABLED ?= false
- node0:~/aether-in-a-box$
-
-
-You may wish to use Kubespray instead of RKE2 if you want to use locally-built images with AiaB
-(e.g., if you are developing SD-CORE services). The reason is that RKE2 uses containerd instead of
-Docker and so cannot access images in the local Docker registry.
-
-How to use Local Image
-^^^^^^^^^^^^^^^^^^^^^^
-
-Note that RKE2 (the default Kubernetes installer) is based on containerd rather than Docker.
-Containerd has its own local image registry that is separate from the local Docker Registry. With RKE2,
-if you have used `docker build` to build a local image, it is only in the Docker registry and so is not
-available to run in AiaB without some additional steps. An easy workaround
-is to use `docker push` to push the image to a remote repository (e.g., Docker Hub) and then modify your
-Helm values file to pull in that remote image. Another option is to save the local Docker image
-into a file and push the file to the containerd registry like this::
-
- docker save -o /tmp/lte-uesoftmodem.tar omecproject/lte-uesoftmodem:1.1.0
- sudo /var/lib/rancher/rke2/bin/ctr --address /run/k3s/containerd/containerd.sock --namespace k8s.io \
- images import /tmp/lte-uesoftmodem.tar
-
-The above commands save the local Docker image `omecproject/lte-uesoftmodem:1.1.0` in a tarball, and then upload
-the tarball into the containerd registry where it is available for use by RKE2. Of course you should replace
-`omecproject/lte-uesoftmodem:1.1.0` with the name of your image.
-
-If you know that you are going to be using AiaB to test locally-built images, probably the easiest thing to do is to
-use the Kubespray installer. If you have already installed using RKE2 and you want to switch to Kubespray, first
-run `make clean` before following the steps in the :ref:`rke2-vs-kubespray-install` section above.
-
-Restarting the AiaB Server
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-AiaB should come up in a mostly working state if the AiaB server is rebooted. If any pods are
-stuck in an Error or CrashLoopBackoff state they can be restarted using ``kubectl delete pod``.
-It might also be necessary to power cycle the Sercomm eNodeB in order to get it to reconnect to
-the SD-CORE.
-
-
-Enabling externalIP at MME
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-You can enable externalIP service in the MME by providing following config in the override file::
-
- node0:~/aether-in-a-box$ git diff sd-core-4g-values.yaml
- diff --git a/sd-core-4g-values.yaml b/sd-core-4g-values.yaml
- index 0939739..f240f89 100644
- --- a/sd-core-4g-values.yaml
- +++ b/sd-core-4g-values.yaml
- @@ -24,6 +24,11 @@ omec-control-plane:
- bootstrap:
- users: []
- staticusers: []
- + mme:
- + s1ap:
- + serviceType: ClusterIP
- + externalIP: 10.1.1.1
- +
- spgwc:
- pfcp: true
- cfgFiles:
- node0:~/aether-in-a-box$
-
-Enabling externalIP at AMF
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-You can enable externalIP service in the AMF by providing following config in the override file::
-
- node0:~/aether-in-a-box$ git diff sd-core-5g-values.yaml
- diff --git a/sd-core-5g-values.yaml b/sd-core-5g-values.yaml
- index e513e1f..fc1c684 100644
- --- a/sd-core-5g-values.yaml
- +++ b/sd-core-5g-values.yaml
- @@ -34,6 +34,9 @@
-
- amf:
- cfgFiles:
- + ngapp:
- + serviceType: ClusterIP
- + externalIp: "10.1.1.2"
- + port: 38412
- amfcfg.conf:
- configuration:
- enableDBStore: false
- @@ -176,6 +179,7 @@ omec-user-plane:
- cpiface:
- dnn: "internet"
- hostname: "upf"
-
- 5g-ran-sim:
- enable: ${ENABLE_GNBSIM}
-
- node0:~/aether-in-a-box$
-
-Troubleshooting
----------------
-
-**NOTE: Running both 4G and 5G SD-CORE simultaneously in AiaB is currently not supported.**
-
-Proxy Issues
-^^^^^^^^^^^^
-
-When working with AiaB behind a proxy, it may be possible to experience certain issues
-due to security policies. That is, the proxy may block a domain (e.g., opencord.org)
-and you may see messages like these ones when trying to clone or get a copy of aether-in-a-box::
-
- ubuntu18:~$ git clone https://gerrit.opencord.org/aether-in-a-box
- Cloning into 'aether-in-a-box'...
- fatal: unable to access 'https://gerrit.opencord.org/aether-in-a-box/': server certificate verification failed. CAfile: /etc/ssl/certs/ca-certificates.crt CRLfile: none
-
-or::
-
- ubuntu18:~$ wget https://gerrit.opencord.org/plugins/gitiles/aether-in-a-box/+archive/refs/heads/master.tar.gz
- --2022-06-01 13:13:42-- https://gerrit.opencord.org/plugins/gitiles/aether-in-a-box/+archive/refs/heads/master.tar.gz
- Resolving proxy.company-xyz.com (proxy.company-xyz.com)... w.x.y.z
- Connecting to proxy.company-xyz.com (proxy.company-xyz.com)|w.x.y.z|:#... connected.
- ERROR: cannot verify gerrit.opencord.org's certificate, issued by 'emailAddress=proxy-team@company-xyz.com,... ,C=US':
- Self-signed certificate encountered.
-
-To address this issue, you need to talk to your company's proxy admins and request to
-unblock (re-classify) the opencord.org domain
-
-
-"make" fails immediately
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-AiaB connects macvlan networks to ``DATA_IFACE`` so that the UPF can communicate on the network.
-To do this it assumes that the *systemd-networkd* service is installed and running, ``DATA_IFACE``
-is under its control, and the systemd-networkd configuration file for ``DATA_IFACE`` ends with
-``<DATA_IFACE>.network``, where ``<DATA_IFACE>`` stands for the actual interface name. It
-tries to find this configuration file by looking in the standard paths. If it fails you'll see
-a message like::
-
- FATAL: Could not find systemd-networkd config for interface foobar, exiting now!
- make: *** [Makefile:112: /users/acb/aether-in-a-box//build/milestones/interface-check] Error 1
-
-In this case, you can specify a ``DATA_IFACE_PATH=<path to the config file>`` argument to ``make``
-so that AiaB can find the systemd-networkd configuration file for ``DATA_IFACE``. It's also possible
-that your system does not use systemd-networkd to configure network interfaces (more likely if you
-are running in a VM), in which case AiaB is currently not able to install in your setup. You
-can check that systemd-networkd is installed and running as follows::
-
- $ systemctl status systemd-networkd.service
- ● systemd-networkd.service - Network Service
- Loaded: loaded (/lib/systemd/system/systemd-networkd.service; disabled; vendor preset: enabled)
- Active: active (running) since Tue 2022-07-12 13:42:18 CDT; 2h 26min ago
- TriggeredBy: ● systemd-networkd.socket
- Docs: man:systemd-networkd.service(8)
- Main PID: 13777 (systemd-network)
- Status: "Processing requests..."
- Tasks: 1 (limit: 193212)
- Memory: 6.4M
- CGroup: /system.slice/systemd-networkd.service
- └─13777 /lib/systemd/systemd-networkd
-
-
-.. _AiaB_fails_too_many_files_open:
-
-AiaB fails during deployment of SD-Core network
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When running AiaB in Ubuntu 22.04, AiaB installation fails during the deployment of the SD-Core with
-an error message as shown below::
-
- ...
- ...
- Update Complete. ⎈Happy Helming!⎈
- NODE_IP=10.80.51.4 DATA_IFACE=data RAN_SUBNET=192.168.251.0/24 ENABLE_GNBSIM=true envsubst < /home/ubuntu/aether-in-a-box//sd-core-5g-values.yaml | \
- helm upgrade --create-namespace --install --wait \
- --namespace omec \
- --values - \
- sd-core \
- aether/sd-core
- Release "sd-core" does not exist. Installing it now.
- coalesce.go:175: warning: skipped value for kafka.config: Not a table.
- Error: timed out waiting for the condition
- make: *** [Makefile:336: /home/ubuntu/aether-in-a-box//build/milestones/5g-core] Error 1
-
-To get more details about the issue, you can execute the following command to see what pod(s) have issues::
-
- $ kubectl -n omec get pods
- NAME READY STATUS RESTARTS AGE
- amf-6dd746b9cd-2mk2j 0/1 CrashLoopBackOff 13 (24s ago) 42m
- ausf-6dbb7655c7-4pkmp 1/1 Running 0 42m
- gnbsim-0 1/1 Running 0 42m
- metricfunc-7864fb8b7c-srf2l 1/1 Running 3 (41m ago) 42m
- mongodb-0 1/1 Running 0 42m
- mongodb-1 1/1 Running 0 41m
- mongodb-arbiter-0 1/1 Running 0 42m
- nrf-57c79d9f65-fs9qj 1/1 Running 0 42m
- nssf-5b85b8978d-q8dz5 1/1 Running 0 42m
- pcf-758d7cfb48-wjfxf 1/1 Running 0 42m
- sd-core-kafka-0 1/1 Running 0 42m
- sd-core-zookeeper-0 1/1 Running 0 42m
- simapp-6cccd6f787-sd52q 0/1 Error 13 (5m14s ago) 42m
- smf-ff667d5b8-sw5vf 1/1 Running 0 42m
- udm-768b9987b4-cqvbg 1/1 Running 0 42m
- udr-8566897d45-n8cbz 1/1 Running 0 42m
- upf-0 5/5 Running 0 42m
- webui-5894ffd49d-bdwf4 1/1 Running 0 42m
-
-As shown above, there are problems with the AMF and SIMAPP pods and to see the specifics of the
-problem, the user can see the logs as shown below::
-
- $ kubectl -n omec logs amf-6dd746b9cd-2mk2j
- ...
- ...
- } (resolver returned new addresses)
- 2023/01/24 17:24:56 INFO: [core] [Channel #1] Channel switches to new LB policy "pick_first"
- 2023/01/24 17:24:56 INFO: [core] [Channel #1 SubChannel #2] Subchannel created
- 2023/01/24 17:24:56 too many open files
-
-As the message shows, the problem is due to "too many open files". To resolve this issue, the user
-can increase the maximum number of available watches and the maximum number of inotify instances
-(e.g., 10x). To do so, first, see the current maximum numbers::
-
- $ sysctl fs.inotify.max_user_instances
- fs.inotify.max_user_instances = 128
- $ sysctl fs.inotify.max_user_watches
- fs.inotify.max_user_watches = 1048576
-
-Then, increase these values by executing::
-
- sudo sysctl fs.inotify.max_user_instances=1280
- sudo sysctl fs.inotify.max_user_watches=10485760
-
-The above setting gets reset to their original values when the machine is rebooted. You can make
-this change permanent by creating an override file::
-
- sudo nano /etc/sysctl.d/90-override.conf
- fs.inotify.max_user_instances=1280
- fs.inotify.max_user_watches=10485760
- sudo sysctl --system
-
-The last command is to load the changes without having to reboot the machine
-
-Data plane is not working
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The first step is to read `Understanding AiaB networking`_understanding_aiab_networking, which
-gives a high level picture
-of the AiaB data plane and how the pieces fit together. In order to debug the problem you will
-need to figure out where data plane packets from the eNodeB are dropped. One way to do this is to
-run ``tcpdump`` on (1) DATA_IFACE to ensure that the data plane packets are arriving, (2) the
-``access`` interface to see that they make it to the UPF, and (3) the ``core`` to check that they
-are forwarded upstream.
-
-If the upstream packets don't make it to DATA_IFACE, you probably need to add the static route
-on the eNodeB so packets to the UPF have a next hop of DATA_IFACE. You can see these upstream
-packets by running::
-
- tcpdump -i <data-iface> -n udp port 2152
-
-If they don't make it to ``access`` you should check that the kernel routing table is forwarding
-a packet with destination 192.158.252.3 to the ``access`` interface. You can see them by running::
-
- tcpdump -i access -n udp port 2152
-
-In case packets are not forwarded from ``DATA_IFACE`` to ``acccess`` interface, the following command
-can be used to forward the traffic which is destined to 192.168.252.3::
-
- iptables -A FORWARD -d 192.168.252.3 -i <data-iface> -o access -j ACCEPT
-
-If they don't make it to ``core`` then they are being dropped by the UPF for some reason. This
-may be a configuration issue with the state loaded in the ROC / SD-CORE -- the UPF is being told
-to discard these packets. You should check that the device's IMSI is part of a slice and that
-the slice's policy settings allow traffic to that destination. You can view them via the following::
-
- tcpdump -i core -n net 172.250.0.0/16
-
-That command will capture all packets to/from the UE subnet.
-
-If you cannot figure out the issue, see `Getting Help`_.
-
-.. _rke2-vs-kubespray-install:
-
-Getting Help
-------------
-
-Please introduce yourself and post your questions to the `#aether-dev` channel on the ONF Community Slack.
-Details about how to join this channel can be found on the `ONF Wiki <https://wiki.opennetworking.org/display/COM/Aether>`_.
-In your introduction please state your institution and position, and describe why you are interested in Aether
-and what is your end goal.
-
-If you need help debugging your setup, please give as much detail as possible about
-your environment: the OS version you have installed, are you running on bare metal or in a VM,
-how much CPU and memory does your server have, are you installing behind a proxy, and so on. Also list the steps
-you have performed so far, and post any error messages you have received. These details will aid the community
-to understand where you are and how to help you make progress.
-
-
diff --git a/index.rst b/index.rst
index a420481..619486c 100644
--- a/index.rst
+++ b/index.rst
@@ -26,14 +26,13 @@
.. toctree::
:maxdepth: 3
- :caption: Aether-in-a-Box
+ :caption: Developing for Aether
:hidden:
:glob:
developer/aiab
- developer/troubleshooting
developer/roc
- amp/monitoring
+ developer/monitoring
developer/contributing.rst
diff --git a/intro.rst b/intro.rst
index 72055f1..2c8edc2 100644
--- a/intro.rst
+++ b/intro.rst
@@ -18,15 +18,17 @@
Getting Started with Aether
---------------------------
-There are two ways to get started with Aether:
+:doc:`Aether OnRamp </onramp/overview>` is now the recommended way to
+get started with Aether. It defines a step-by-step procedure for
+deploying and operating Aether on your own hardware, including support
+for `5G small cell
+<https://opennetworking.org/products/moso-canopy-5g-indoor-small-cell/>`__
+radios.
-* Deploy and operate Aether on your own servers (including `5G small cell
- <https://opennetworking.org/products/moso-canopy-5g-indoor-small-cell/>`__)
- with :doc:`Aether OnRamp </onramp/overview>`.
+Other Aether guides available on this site include:
-* Setup an Aether software development environment on your laptop with :doc:`Aether-in-a-Box </developer/aiab>`.
-
-Other Aether guides included on this site include:
+* :doc:`Developing for Aether </developer/aiab>`: Learn how to
+ contribute back to Aether.
* :doc:`Runtime Operations </operations/gui>`: Learn how
to operate Aether's 5G connectivity service.