docs/installation-guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. Copyright (C) 2019 AT&T
   4
   5
   6 Installation Guide
   7 ==================
   8
   9 .. contents::
  10    :depth: 3
  11    :local:
  12
  13 Abstract
  14 --------
  15
  16 This document describes how to install the Admission Control (AC) xAPP.
  17
  18 Version history
  19
  20 +--------------------+--------------------+--------------------+--------------------+
  21 | **Date**           | **Ver.**           | **Author**         | **Comment**        |
  22 |                    |                    |                    |                    |
  23 +--------------------+--------------------+--------------------+--------------------+
  24 | 2019-11-14         |1.0.8               |Ashwin Sridharan    | Amber Release      |
  25 |                    |                    |                    |                    |
  26 +--------------------+--------------------+--------------------+--------------------+
  27
  28
  29 Introduction
  30 ------------
  31
  32 This document provides guidelines on how to install and configure the AC xAPP in various environments/operating modes.
  33 The audience of this document is assumed to have good knowledge in RAN network nd Linux system.
  34
  35
  36 Preface
  37 -------
  38 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
  39 two can be used for testing/evaluation. The last option is how an xAPP is deployed in the RAN Intelligent Controller environment.
  40 This document covers all three methods.
  41
  42
  43
  44
  45 Software Installation and Deployment
  46 ------------------------------------
  47 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,
  48 the Docker environment must be present in the system.
  49
  50
  51 Build Process
  52 ~~~~~~~~~~~~~
  53 The AC xAPP can be either tested as a Linux binary or as a docker image.
  54    1. **Docker Image**:    From the root of the repository, run   *docker --no-cache build -t <image-name> ./* .
  55       **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
  56
  57    2. **Linux binary**:
  58       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*.
  59
  60
  61 Deployment
  62 ~~~~~~~~~~
  63 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
  64 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
  65 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*.
  66
  67 1. **Invoking the AC xAPP directly as a Linux binary** :
  68
  69    - Set the environment variable *RMR_SEED_RT* to point to the complete path of a file with static routes.
  70
  71    - 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.
  72
  73
  74 2. **Invoking  xAPP docker container directly** (not in RIC Kubernetes env.):
  75
  76    - 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).
  77
  78    - 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.
  79
  80
  81 3. **Invoking docker xAPP container in RIC Kubernetes environment** :
  82    In an actual deployment, xAPPs are deployed as K8 pods via the
  83    xapp-manager in the RIC with their configuration mounted as
  84    *configmaps*. In order to be deployable by the xapp-manager, a helm
  85    chart of the xAPP must be created and uploaded to the helm
  86    repository. Generation of helm chart falls under the purview of the
  87    RIC integration team rather than the xAPP owner since the helm
  88    chart will contain several environment specific
  89    parameters. However, the xAPP owner may provide any xAPP specific
  90    configuration via a JSON configuration file and associated schema.
  91    A sample configuration json file (which **MUST** be named
  92    config-file.json) and schema are provided under init/. Parameters
  93    of the JSON are documented in README under the init/ directory.
  94
  95    As an alternative to the xapp-manager, in a test K8 environment,
  96    the AC xAPP may also be directly installed via Helm (thought it may
  97    not be controllable via the RIC dashboard).
  98
  99 Testing
 100 --------
 101
 102 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
 103
 104 *wget -nv  --directory-prefix=/usr/local/include/Catch2 https://github.com/catchorg/Catch2/releases/download/v2.9.1/catch.hpp*.
 105
 106 After that, the unit tests can be compiled and run by executing the following commands from the *test/* directory :
 107
 108 - *make all_tests*
 109 - ./run_tests.sh
 110 - If gcovr is installed (https://github.com/gcovr/gcovr) the script  will  also generates a coverage report (as ../coverage_report.html)
 111
 112 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/*
 113 directory contains mock-ups for these three components which can be build and executed from the *test/* directory as follows  :
 114
 115 1.  **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
 116
 117     - listens and responds to E2AP subscription requests.
 118     - upon receiving an E2AP subscription request, starts sending E2AP Indication messages that contain the X2AP SgNB Addition Request Message.
 119     - monitors E2AP control messages from the AC xAPP.
 120
 121     The E2 term executable can be build and executed as follows :
 122
 123     - *make mock-e2term-server* compiles the executable
 124     - 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>
 125     - *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.
 126
 127 2.  **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 :
 128
 129     - *make mock-a1-tool* builds the executable.
 130     - The executable can be run as *./mock-a1-tool -p <port number> <options>*  where port number can be any port not conflicitng  with the xAPP and E2 Term ports.
 131     - Note that the A1 mediator also uses RMR and hence the environment variable *RMR_SEED_RT* must also be set when executing *mock-a1-tool* (if static routes are being used).
 132     - Run ./mock-a1-tool -h to see various options.
 133
 134 3.  **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 VES messages from the Admission Control Xapp  and prints out relevant messages. It can be invoked as *python ./mock_ves_collector.py*.
 135
 136     - Pre-requisites for the VES collector are the *cherrypy* and *requests* Python modules. They can be installed via pip :  *pip install cherrypy requests*.
 137
 138
 139