Welcome to O-RAN SC Admission Control xAPP Documentation¶
Admission Control xAPP Overview¶
The Admission Control (AC) xAPP repository contains open-source code for a prototype xAPP that can execute the full control loop to regulate the number of 5G connection requests at a gNodeB.
The AC xAPP subscribes and listens for SgNB Addition Request X2AP messages. Upon receiving one, it makes a decision on whether to accept or reject the request based on a simple sliding window. If the decision is to accept the request, it sends an SgNB Addition Acknowledge, else it sends an SgNB Addition Reject message.
The AC xAPP repository contains code to handle the E2 subscription process, encode/decode E2AP Indication/Control messages, X2AP SgNB Addition Request/Response and supports the A1-interface which can be used to send policies to configure the admission control behaviour.
Release Notes¶
This document provides the release notes for the Amber Release of the Admission Control xAPP.
Version history¶
Date | Ver. | Author | Comment |
2019-11-04 | 1.0.0 | Ashwin Sridharan | First draft |
Summary¶
The Amber release of the AC xAPP supports full closed loop control as well as report mode operation for admission control of SgNB Addition requests, reporting of metrics over VES, and configuration of single instance policies via the A1-Interface.
Release Data¶
Project | RAN Intelligent Controller |
Repo/commit-ID | ric-app/admin |
Release designation | Amber |
Release date | 2019-11-14 |
Purpose of the delivery | open-source xAPP for admission control. |
Components¶
- src/ contains the main source code. Under that directory :
- xapp_utils.hpp, xapp_utils.cc is generic multi-threaded framework for receiving and sending RMR events.
- E2AP-c/subscription/ contains generic classes to send/process ASN1 subscription requests, responses, deletes and failures as well as thread-safe subscription handler for managing the subscription process.
- E2AP-c/ contains generic classes for generating/processing ASN1 E2AP Indication and Control messages.
- E2SM/ contains generic classes for handling generating/processing ASN1 E2SM service model (e.g event trigger etc).
- curl/ contains a simple libcurl based class for POSTing JSON messages.
- json/ contains a generic class for simple JSON key retrieval and modification (based on rapidjson)
- protector-plugin/ contains code specific to the admission control algorithm and interfaces for setting/getting policy.
- test/ contains unit tests showing how to use various components as well as mock-ups for integration testing.
- schemas/ contains the JSON schemas for A1 policy, VES metrics as well as sample payloads.
Limitations¶
- While the xAPP framework used in the AC xAPP supports multi-threading, the admission plugin currently only supports a single thread.
- The admission plugin supports only a single class of service in current release.
- The subscription request parameters (RAN Function ID etc) cannot be changed.
Installation Guide¶
Abstract¶
This document describes how to install the Admission Control (AC) xAPP.
Version history
Date | Ver. | Author | Comment |
2019-11-14 | 1.0.8 | Ashwin Sridharan | Amber Release |
Introduction¶
This document provides guidelines on how to install and configure the AC xAPP in various environments/operating modes. The audience of this document is assumed to have good knowledge in RAN network nd Linux system.
Preface¶
The AC xAPP can be run directly as a Linux binary, as a docker image, or in a pod in a Kubernetes environment. The first two can be used for testing/evaluation. The last option is how an xAPP is deployed in the RAN Intelligent Controller environment. This document covers all three methods.
Software Installation and Deployment¶
The build process assumes a Linux environment with a gcc (>= 4.0) compatible compiler and has been tested on Ubuntu and Fedora. For building docker images, the Docker environment must be present in the system.
Build Process¶
- The AC xAPP can be either tested as a Linux binary or as a docker image.
- Docker Image: From the root of the repository, run docker –no-cache build -t <image-name> ./ . IMPORTANT : docker user must have credentials to access to the LF O-RAN docker repository : nexus3.o-ran-sc.org:10004, which can be done with docker login prior to running the build
- Linux binary: The AC xAPP may be compiled and invoked directly. Pre-requisite software packages that must be installed prior to compiling are documented in the Dockerfile (and also in README under src/) in the repository. From within the src directory, run make adm-ctrl-xapp.
Deployment¶
For simple unit tests, integration tests etc., the Linux binary or docker image may be used directly. When tested E2E in a RIC, the AC xAPP must be deployed as a K8 pod using the xAPP manager (or helm for simple tests). In all scenarios, an important pre-requisite for deployment is the availability of routes (see RMR documentation) to the xAPP indicating where to send E2AP subscription requests and control messages. In production, this set of routes will be provided by the Route Manager. For local testing, static routes can be provided to the RMR library by setting the environment variable RMR_SEED_RT to point to the complete path of a file with routes. An example RMR route file is provided under test/uta_rtg.rt.
Invoking the AC xAPP directly as a Linux binary :
- Set the environment variable RMR_SEED_RT to point to the complete path of a file with static routes.
- Use the provided sample script src/run_xapp.sh to invoke the AC xAPP. The script lists the various options which may be changed depending on environment.
Invoking xAPP docker container directly (not in RIC Kubernetes env.):
- The xAPP docker run time must be configured with a json configuration file appropriate to the test environment which injects various environment variables including the RMR routes (an example is provided under init/config-file.json).
- Once such a file is available (say under directory /home/user/test-config), the docker image can be invoked as docker run –net host -it –rm -v “/home/user/test-config:/opt/ric/config” –name “AC-xAPP” <image>. See README.md under the init directory for more details.
Invoking docker xAPP container in RIC Kubernetes environment : In an actual deployment, xAPPs are deployed as K8 pods via the xapp-manager in the RIC with their configuration mounted as configmaps. In order to be deployable by the xapp-manager, a helm chart of the xAPP must be created and uploaded to the helm repository. Generation of helm chart falls under the purview of the RIC integration team rather than the xAPP owner since the helm chart will contain several environment specific parameters. However, the xAPP owner may provide any xAPP specific configuration via a JSON configuration file and associated schema. A sample configuration json file (which MUST be named config-file.json) and schema are provided under init/. Parameters of the JSON are documented in README under the init/ directory.
As an alternative to the xapp-manager, in a test K8 environment, the AC xAPP may also be directly installed via Helm (thought it may not be controllable via the RIC dashboard).
Testing¶
Unit tests for various modules of the AC xAPP are under the test/ repository. Currently, the unit tests must be compiled and executed in a Linux environment. All software packages required for compiling the AC xAPP must be installed (as listed in the Dockerfile). In addition a pre-requisite for the unit tests is installation of the Catch2 C++ header file since the unit tests use this framework. This can be easily done by running
wget -nv –directory-prefix=/usr/local/include/Catch2 https://github.com/catchorg/Catch2/releases/download/v2.9.1/catch.hpp.
After that, the unit tests can be compiled and run by executing the following commands from the test/ directory :
- make all_tests
- ./run_tests.sh
- If gcovr is installed (https://github.com/gcovr/gcovr) the script will also generates a coverage report (as ../coverage_report.html)
In order to run integration tests, the AC-xAPP requires three components : an E2 Termination point to send and receive RAN messages, an A1 mediator to send policy updates and a VES collector to receive metrics. The test/ directory contains mock-ups for these three components which can be build and executed from the test/ directory as follows :
E2 Termination : The E2 termination is responsible for forwarding messages to and fro between the RAN and RIC. A mock-up of the E2 termination is provided in test/ that
- listens and responds to E2AP subscription requests.
- upon receiving an E2AP subscription request, starts sending E2AP Indication messages that contain the X2AP SgNB Addition Request Message.
- monitors E2AP control messages from the AC xAPP.
The E2 term executable can be build and executed as follows :
- make mock-e2term-server compiles the executable
- To invoke it first ensure the RMR_SEED_RT environment variable is set to point to complete path of a route file. Then run * ./mock-e2term-server -p <E2 term port number> -r <rate to send E2AP indication messages>
- NOTE : The E2 term port number must be set to the port number listed in the route table that can receive E2AP subscription requests, E2AP indications. Default port that is used is 38000.
A1 Mediator : The A1 mediator is responsible for sending policies to the xAPPs over RMR to configure their behaviour. A mock-up of the A1 mediator can be built and executed as follows :
- make mock-a1-server builds the executable.
- The executable can be run as ./mock-a1-server -p <port number> where port number can be any port not conflicting with the xAPP and E2 Term.
- Note that the A1 mediator also uses RMR and hence the environment variable RMR_SEED_RT must also be set when executing mock-a1-server (if static routes are being used).
- On start up, the mock-a1-mediator will send a stream of valid/invalid JSON messages containing policies to test the xAPP.
VES Collector : This component is responsible for receiving metrics from xAPPs as JSON payloads. A simple mock-up is available under test/ which is basically a cherrypy web-server that receives JSON and prints out relevant messages. It can be invoked as python ./mock_ves_collector.py.
- Pre-requisites for the VES collector are the cherrypy and requests Python modules. They can be installed via pip : pip install cherrypy requests.
User Guide¶
This is the user guide of AC xAPP, describing its various features and how to configure them .
Description¶
The AC xAPP provides rate control of SgNB Addition Requests via a standard sliding window control algorithm which is configurable at run-time. Please see Installation Guide for instructions on compiling and executing the AC xAPP. This document explains the various configurable parameters of the AC xAPP executable, policies and metrics.
Upon start up, the AC xAPP will spin up a thread on which to listen for RMR events, another thread to post metrics and then start sending subscription requests for the SgNB Addition Request on the main thread. When an E2AP indication message with the X2AP SgNB Addition Request message is received, the AC xAPP will run the sliding window algorithm, decide a response (see below for specifics) and return the response. The next section shows how to configure various facets of the AC xAPP that cover subscription, policy for configuration, metric reporting and behaviour of the core algorithm itself.
Run Time options¶
The AC xAPP takes the following parameters (either on the command line) or as environment variables on invocation (see src/run_xapp.sh for an example of providing arguments on command line and init/config-file.json for environment variables) :
List of comma separated gNodeBs to send subscription requests to. Can be specified with :
- Use -g or –gNodeB on command line.
- Set the “GNODEB” environment variable
The A1 policy schema file which specifies the schema and parameters of acceptable policy. The AC xAPP sliding window algorithm can be configured with the following 5 parameters via the policy (see schemas/sample.json for an example). The AC xAPP policy schema file is outlined in schemas/adm-ctrl-xapp-policy-schema.json. The policy parameters are :
“enforce”: A boolean flag on whether to enforce policy or not.
“window_length” : Length of the sliding window in minutes.
“trigger_threshold: Threshold of events in sliding window above which to start blocking.
“blocking_rate”: A percentage between [0-100] of connections to block if above trigger_threshold.
For example, a window length of 1, trigger threshold of 5000 and blocking rate of 50 would mean that if in a window of 1 minute (60 seconds), there are more than 5000 events, then start blocking half of the incoming connections. Note that the window is always updated prior to blocking. In the above example, if arrival rate exceeds 84 events/sec ) over a period exceeding 1 minute ((84 * 60 = 5040 > 5000), then blocking will be triggered.
The A1 policy file location can be specified to the AC xAPP with - -a on command line. - “A1_SCHEMA_FILE” environment variable.
The VES schema to which all reported metrics must comply. The VES schema file can be specified with
- -v on command line.
- “VES_SCHEMA_FILE” environment variable.
Set of sample JSON payloads for policy and metrics that the AC xAPP uses as templates to generate payloads. Values in the template payload are modified/retrieved rather than construct the entire payload from scratch. The JSON file containing the payloads can be specified with :
- -s on command line.
- “SAMPLE_FILE” environment variable.
URL of the VES collector to which to send metrics. Can be specified with :
- -u on command line.
- “VES_COLLECTOR_URL” environment variable.
Reporting interval for metrics in seconds (i.e., how often to post metrics to VES). Can be specified with :
- -i on command line.
- “VES_MEASUREMENT_INTERVAL” environment variable.
Log level. Can be specified with :
- –verbose* flag on command line which will set the log level to most verbose (DEBUG).
- “LOG_LEVEL” environment variable. This allows finer grained control. Options are MDCLOG_ERR, MDCLOG_INFO, MDCLOG_DEBUG.
The operating mode of the AC xAPP. The AC xAPP can be run in three modes which can be specified with :
- -c option on command line.
- “OPERATING_MODE” environment variable.
The three operating modes supported are :
- “E2AP_PROC_ONLY” . In this mode, the AC xAPP simply decodes and records the E2AP message.
- “REPORT” . In this mode, the AC xAPP decodes the E2AP and the underlying X2AP message. If the message is an SgNB Addition Request Message, it executes the admission control algorithm and records the result. It does not however send a response back to RAN. This is useful when testing passively without interfering with RAN operation.
- “CONTROL”. In this mode, the AC xAPP executes the full control loop where it also sends back an SgNB Addition Response or Reject message.