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
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.
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:
23 Version bumping the framework
24 -----------------------------
26 This project follows semver. When changes are made, the versions are in:
28 #. ``docs/release-notes.rst``
34 These items in this repo must be kept in sync with the RMR version:
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
42 Registration/Deregistartion of Xapp
43 -----------------------------------
45 For registration and deregistration of Xapp following items need to be defined:
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.
54 Director examples has many examples for creating the xapp having features like:
55 * REST subscription interface
58 * REST healthy and ready response handler
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
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).
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.
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``
80 In case of using restserversimu.py for testing configure your host ip address, for example 192.168.1.122 port 8090:
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``
85 Then start the restserversimu:
88 python3 examples/restserversimu.py -port 9000 -address 192.168.1.122
90 and then the xapp_test:
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
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
102 Subscription REST interface
103 ---------------------------
105 api/xapp_rest_api.yaml defines interface and it has been used to generate the swagger api calls.
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
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:
113 find ./out/swagger_client -type f -exec sed -i -e 's/swagger_client/ricxappframe\.swagger_client/g' {} \;
115 Then copy the generated ./out/swagger_client directory to ./ricxappframe/subsclient directory:
117 cp -r ./out/swagger_client/* ./ricxappframe/subsclient
122 Running the unit tests requires the python packages ``tox`` and ``pytest``.
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.
127 Upon completion, view the test coverage like this:
132 open htmlcov/index.html
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.
140 docker build --no-cache -f Dockerfile-Unit-Test .