README.md

   1 #==================================================================================
   2 #        Copyright (c) 2018-2019 AT&T Intellectual Property.
   3 #
   4 #   Licensed under the Apache License, Version 2.0 (the "License");
   5 #   you may not use this file except in compliance with the License.
   6 #   You may obtain a copy of the License at
   7 #
   8 #       http://www.apache.org/licenses/LICENSE-2.0
   9 #
  10 #   Unless required by applicable law or agreed to in writing, software
  11 #   distributed under the License is distributed on an "AS IS" BASIS,
  12 #   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 #   See the License for the specific language governing permissions and
  14 #   limitations under the License.
  15 #==================================================================================
  16
  17 This repository contains source code for a prototype open-source admission control xAPP.
  18 The admission control xAPP subscribes and listens for SgNB Addition Request X2AP messages. Upon
  19 receiving one, it makes a decision on whether to accept or reject the request based on a simple
  20 sliding window. If the decision is to accept the request, it sends an SgNB Addition Acknowledge, else
  21 it sends an SgNB Addition Reject message.
  22
  23 1. Building docker image of the Admission Control xAPP
  24 ------------------------------------------------------
  25   Simply run : docker build -t <image-name> ./
  26   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
  27
  28
  29 2. Compiling and invoking the AC xAPP directly
  30 -----------------------------------------------
  31 The Admission Control xAPP may be compiled and invoked directly. Required components for compilation are documeted in the Dockerfile (and also in README under src/).  A sample script src/run_xapp.sh is provided to show how to invoke the admission control xAPP with various options.
  32
  33 3. Invoking  xAPP docker container directly (ie not in RIC Kubernetes env.)
  34 ------------------------------------------------------------------
  35 The xAPP docker run time can be configured with a json configuration file (example provided under init/config-file.json). Once such a file is availabel (say under directory /home/user/test-config), the docker image can be invoked as
  36 docker run --net host -it --rm -v "/home/user/test-config:/opt/ric/config" --name "AC-xAPP" <image>
  37 See REAMDE.md under the init directory for more details.
  38
  39
  40 4. Invoking docker xAPP container in RIC Kubernetes environment
  41 --------------------------------------------------------------
  42 xAPPs are deployed via the xapp manager in the RIC. In  order to be deployable, a helm chart of the xAPP is created and uploaded to the helm
  43 repository. Typically the helm chart must be created by the RIC team rather than the xAPP owner since the helm chart will contain several environment
  44 specific parameters. However, the xAPP owner may provide any xAPP specific configuration via a JSON configuration file and associated schema.
  45 A sample configuration json file (which MUST be named config-file.json) and schema are provided under init/. Parameters of the JSON
  46 are documented in README under the init/ directory.
  47
  48 5. Testing Admission Control xAPP
  49 ---------------------------------
  50 The Admission Control xAPP can be tested using mockups available under the test directory.
  51 1.  mock-e2term-server  can be used to send X2 SgNB Addition Requests at a specified rate and monitor responses from the xAPP
  52 2.  mock_ves_collectory.py is a simply cherrypy web-server which can be used to receive metrics from the AC xAPP
  53 3.  mock_a1_mediator can be used to test sending policies to the AC xAPP.
  54
  55 The README.md under the test directory contains instructions on how to build and use these mock up tools.
  56
  57
  58 6. Layout
  59 ---------
  60    a. src/ contains code for the admission control xAPP. See README.md under src for more information, as well as how to run the compiled executable directly (without docker container).
  61
  62    b. test/ contains unit tests as well as mock up tools for integration testing
  63
  64    c. schemas/ contains the various JSON schemas, sample responses/inputs  used by the Admission Control (AC) xAPP for setting/getting policies as wellreporting metrics.
  65
  66    d. init/  contains a sample JSON configuration file and python script for starting xAPP in a container (only the JSON config should be modified as per environment)
  67
  68    e. asn1c_defs : Contains all the getter/setting  asn1c generated code for manipulating/decoding/encoding ASN1 E2AP/E2SM/X2AP packages