.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
+.. SPDX-License-Identifier: CC-BY-4.0
+.. Copyright (C) 2020 AT&T Intellectual Property
Developer Guide
===============
-.. contents::
- :depth: 3
- :local:
+This document explains how to maintain the RIC Xapp framework.
+Information for users of this framework (i.e., Xapp developers) is in the User Guide.
+
+Tech Stack
+----------
+
+The framework requires Python version 3.8 or later, and depends on
+these packages provided by the O-RAN-SC project and third parties:
+
+* msgpack
+* mdclogpy
+* ricsdl
+* protobuf
+
Version bumping the framework
-----------------------------
This project follows semver. When changes are made, the versions are in:
-1) ``docs/release-notes.rst``
-
-2) ``setup.py``
+#. ``docs/release-notes.rst``
+#. ``setup.py``
Version bumping RMR
-------------------
-These items in this repo must be kept in sync:
-* Dockerfile-Unit-Test
-* examples/Dockerfile-Ping
-* examples/Dockerfile-Pong
-* ``rmr-version.yaml`` controls what rmr gets installed for unit testing in Jenkins
+These items in this repo must be kept in sync with the RMR version:
+
+#. Dockerfile-Unit-Test
+#. examples/Dockerfile-Ping
+#. examples/Dockerfile-Pong
+#. ``rmr-version.yaml`` controls what version of RMR is installed for
+ unit testing in Jenkins CI
+
+Registration/Deregistartion of Xapp
+-----------------------------------
+
+For registration and deregistration of Xapp following items need to be defined:
+
+#. CONFIG_FILE_PATH variable as a environment variable in Dockerfile if running
+ Xapp as a docker container or in configmap in case of Xapp as a pod.
+#. Copy the xappConfig.json into the docker image in Dockerfile.
+
+Example Xapp
+------------
+
+Director examples has many examples for creating the xapp having features like:
+* REST subscription interface
+* symptomdata handler
+* rmr send/receive
+* REST healthy and ready response handler
+* REST config handler
+
+List of xapps:
+* ping_xapp.py and ping_xapp.py using RMR to send and receive
+* xapp_symptomdata.py for subscribing the symptomdata event
+* xapp_test.py for both symptomdata, RMR recveice, k8s healthy service and REST subscription
+
+xapp_test.py
+------------
+
+Test xapp can be run by creating the docker container or as standalone process. For testing restserversimu.py
+has been made to emulate the REST subscription request responses and responding the symptomdata dynamic registration
+reponse. When running the xapp_test you need to create the RMR static routing file so that the rmr initialization
+will return (otherwise it will wait for rtmgr connection).
+
+Test xapp has as well the config file in descriptor/config-file.json where your can adjust the local runtime
+environment for subscriptions and symptomdata lwsd service ip address.
+
+Subsciprion interface url has the submgr service endpoint : ``http://service-ricplt-submgr-http.ricplt:8088/``
+Symptomdata registration url set to lwsd service url : ``http://service-ricplt-lwsd-http.ricplt:8080/ric/v1/lwsd``
+
+In case of using restserversimu.py for testing configure your host ip address, for example 192.168.1.122 port 8090:
+Subsciprion interface url has the submgr service endpoint : ``http://192.168.1.122:9000/``
+Symptomdata registration url set to lwsd service url : ``http://192.168.1.122:9000/ric/v1/lwsd``
+
+Then start the restserversimu:
+
+export PYTHONPATH=./
+python3 examples/restserversimu.py -port 9000 -address 192.168.1.122
+
+and then the xapp_test:
+
+export PYTHONPATH=./
+export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
+export RMR_SEED_RT=examples/descriptor/xapp-test.rt
+export RMR_SRC_ID="192.168.1.122"
+python3 examples/xapp_test.py -config examples/descriptor/config-file.json -port 8888 -xapp xapp-test -service xapp-test
+
+If you like to implement the kubernetes healthy service responder, you can follow the example how to use the
+xapp_rest.py defined rest hander. Basically you can initiate the REST service listener and add the handlers (examples in
+xapp_tets.py).
+
+Subscription REST interface
+---------------------------
+
+api/xapp_rest_api.yaml defines interface and it has been used to generate the swagger api calls.
+
+Generating the swagger client model:
+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
+
+swagger-codegen-cli generated code result needs to be adjusted to have the ricxappframe prefix.
+Replace the module name to have the ricxappframe prefix:
+
+find ./out/swagger_client -type f -exec sed -i -e 's/swagger_client/ricxappframe\.swagger_client/g' {} \;
+
+Then copy the generated ./out/swagger_client directory to ./ricxappframe/subsclient directory:
+
+cp -r ./out/swagger_client/* ./ricxappframe/subsclient
Unit Testing
------------
-You can run the unit tests in Docker to avoid installing RMR locally:
+Running the unit tests requires the python packages ``tox`` and ``pytest``.
+
+The RMR library is also required during unit tests. If running directly from tox
+(outside a Docker container), install RMR according to its instructions.
+
+Upon completion, view the test coverage like this:
+
+::
+
+ tox
+ open htmlcov/index.html
+
+Alternatively, if you cannot install RMR locally, you can run the unit
+tests in Docker. This is somewhat less nice because you don't get the
+pretty HTML report on coverage.
::
- docker build -f Dockerfile-Unit-Test .
+ docker build --no-cache -f Dockerfile-Unit-Test .
Code Review / ric-plt / xapp-frame-py.git / blobdiff