docs/developer-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) 2020 AT&T Intellectual Property
   4
   5 Developer Guide
   6 ===============
   7
   8 This document explains how to maintain the RIC Xapp framework.
   9 Information for users of this framework (i.e., Xapp developers) is in the User Guide.
  10
  11 Tech Stack
  12 ----------
  13
  14 The framework requires Python version 3.8 or later, and depends on
  15 these packages provided by the O-RAN-SC project and third parties:
  16
  17 * msgpack
  18 * mdclogpy
  19 * ricsdl
  20 * protobuf
  21
  22
  23 Version bumping the framework
  24 -----------------------------
  25
  26 This project follows semver. When changes are made, the versions are in:
  27
  28 #. ``docs/release-notes.rst``
  29 #. ``setup.py``
  30
  31 Version bumping RMR
  32 -------------------
  33
  34 These items in this repo must be kept in sync with the RMR version:
  35
  36 #. Dockerfile-Unit-Test
  37 #. examples/Dockerfile-Ping
  38 #. examples/Dockerfile-Pong
  39 #. ``rmr-version.yaml`` controls what version of RMR is installed for
  40    unit testing in Jenkins CI
  41
  42 Registration/Deregistartion of Xapp
  43 -----------------------------------
  44
  45 For registration and deregistration of Xapp following items need to be defined:
  46
  47 #. CONFIG_FILE_PATH variable as a environment variable in Dockerfile if running
  48    Xapp as a docker container or in configmap in case of Xapp as a pod.
  49 #. Copy the xappConfig.json into the docker image in Dockerfile.
  50
  51 Example Xapp
  52 ------------
  53
  54 Director examples has many examples for creating the xapp having features like:
  55 * REST subscription interface
  56 * symptomdata handler
  57 * rmr send/receive
  58 * REST healthy and ready response handler
  59 * REST config handler
  60
  61 List of xapps:
  62 * ping_xapp.py and ping_xapp.py using RMR to send and receive
  63 * xapp_symptomdata.py for subscribing the symptomdata event
  64 * xapp_test.py for both symptomdata, RMR recveice, k8s healthy service and REST subscription
  65
  66 xapp_test.py
  67 ------------
  68
  69 Test xapp can be run by creating the docker container or as standalone process. For testing restserversimu.py
  70 has been made to emulate the REST subscription request responses and responding the symptomdata dynamic registration
  71 reponse. When running the xapp_test you need to create the RMR static routing file so that the rmr initialization
  72 will return (otherwise it will wait for rtmgr connection).
  73
  74 Test xapp has as well the config file in descriptor/config-file.json where your can adjust the local runtime
  75 environment for subscriptions and symptomdata lwsd service ip address.
  76
  77 Subsciprion interface url has the submgr service endpoint : ``http://service-ricplt-submgr-http.ricplt:8088/``
  78 Symptomdata registration url set to lwsd service url : ``http://service-ricplt-lwsd-http.ricplt:8080/ric/v1/lwsd``
  79
  80 In case of using restserversimu.py for testing configure your host ip address, for example 192.168.1.122 port 8090:
  81
  82 Subsciprion interface url has the submgr service endpoint : ``http://192.168.1.122:9000/``
  83 Symptomdata registration url set to lwsd service url : ``http://192.168.1.122:9000/ric/v1/lwsd``
  84
  85 Then start the restserversimu:
  86
  87 export PYTHONPATH=./
  88 python3 examples/restserversimu.py -port 9000 -address 192.168.1.122
  89
  90 and then the xapp_test:
  91
  92 export PYTHONPATH=./
  93 export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
  94 export RMR_SEED_RT=examples/descriptor/xapp-test.rt
  95 export RMR_SRC_ID="192.168.1.122"
  96 python3 examples/xapp_test.py -config examples/descriptor/config-file.json -port 8888 -xapp xapp-test -service xapp-test
  97
  98 If you like to implement the kubernetes healthy service responder, you can follow the example how to use the
  99 xapp_rest.py defined rest hander. Basically you can initiate the REST service listener and add the handlers (examples in
 100 xapp_tets.py).
 101
 102 Subscription REST interface
 103 ---------------------------
 104
 105 api/xapp_rest_api.yaml defines interface and it has been used to generate the swagger api calls.
 106
 107 Generating the swagger client model:
 108 docker run --rm -v ${PWD}:/local -u $(id -u ${USER}):$(id -g ${USER}) swaggerapi/swagger-codegen-cli generate -i /local/api/xapp_rest_api.yaml -l python -o /local/out
 109
 110 swagger-codegen-cli generated code result needs to be adjusted to have the ricxappframe prefix.
 111 Replace the module name to have the ricxappframe prefix:
 112
 113 find ./out/swagger_client -type f -exec sed -i -e 's/swagger_client/ricxappframe\.swagger_client/g' {} \;
 114
 115 Then copy the generated ./out/swagger_client directory to ./ricxappframe/subsclient directory:
 116
 117 cp -r ./out/swagger_client/* ./ricxappframe/subsclient
 118
 119 Unit Testing
 120 ------------
 121
 122 Running the unit tests requires the python packages ``tox`` and ``pytest``.
 123
 124 The RMR library is also required during unit tests. If running directly from tox
 125 (outside a Docker container), install RMR according to its instructions.
 126
 127 Upon completion, view the test coverage like this:
 128
 129 ::
 130
 131    tox
 132    open htmlcov/index.html
 133
 134 Alternatively, if you cannot install RMR locally, you can run the unit
 135 tests in Docker. This is somewhat less nice because you don't get the
 136 pretty HTML report on coverage.
 137
 138 ::
 139
 140    docker build  --no-cache -f Dockerfile-Unit-Test .