docs/developer-guide.rst

   1 ..
   2 ..  Copyright (c) 2019 AT&T Intellectual Property.
   3 ..  Copyright (c) 2019 Nokia.
   4 ..
   5 ..  Licensed under the Creative Commons Attribution 4.0 International
   6 ..  Public License (the "License"); you may not use this file except
   7 ..  in compliance with the License. You may obtain a copy of the License at
   8 ..
   9 ..    https://creativecommons.org/licenses/by/4.0/
  10 ..
  11 ..  Unless required by applicable law or agreed to in writing, documentation
  12 ..  distributed under the License is distributed on an "AS IS" BASIS,
  13 ..  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 ..
  15 ..  See the License for the specific language governing permissions and
  16 ..  limitations under the License.
  17 ..
  18
  19 Developer-Guide
  20 ===============
  21
  22 .. contents::
  23    :depth: 3
  24    :local:
  25
  26 Overview
  27 --------
  28 Routing Manager is a basic platform service of RIC. It is responsible for distributing routing policies among the other platform components and xApps.
  29
  30 The routing manager has two ways to get the xapp details from xapp manager - httpGetter or httpRESTful.
  31 In case of httpGetter, the implemented logic periodically queries the xApp Manager component for xApps' list.
  32 Where in httpRESTful, starts a http server and creates a webhook subscription in xapp manager to update about changes in xapps and waits changed data to arrive on the REST http server.
  33 Either ways, the xapp data received is stored and then processed to create routing policies and distributes them to all xApps.
  34
  35 Architecture
  36 ------------
  37 The architecture consists of the following five well defined functions:
  38
  39 * NorthBound Interface (__NBI__): Maintains the communication channels towards RIC manager components
  40 * Routing Policy Engine (__RPE__): Provides the logic to calculate routing policies
  41 * Shared Data Layer (__SDL__): Provides access to different kind persistent data stores
  42 * SouthBound Interface (__SBI__): Maintains the communication channels towards RIC tenants and control components
  43 * Control Logic (__RTMGR__): Controls the operation of above functions
  44
  45
  46 Installing Routing Manager
  47 --------------------------
  48 * Tag the `rtmgr` container according to the project release and push it to a registry accessible from all minions of the Kubernetes cluster.
  49 * Edit the container image section of `rtmgr-dep.yaml` file according to the `rtmgr` image tag.
  50
  51 Deploying Routing Manager
  52 -------------------------
  53 * Issue the `kubectl create -f {manifest.yaml}` command in the following order:
  54    1. `manifests/namespace.yaml`: creates the `example` namespace for routing-manager resources
  55    2. `manifests/rtmgr/rtmgr-cfg.yaml`: creates default routes config file for routing-manager
  56    3. `manifests/rtmgr/rtmgr-dep.yaml`: instantiates the `rtmgr` deployment in the `example` namespace
  57    4. `manifests/rtmgr/rtmgr-svc.yaml`: creates the `rtmgr` service in `example` namespace
  58
  59 NOTE: The above manifest files will deploy routing manager with NBI as httpRESTful which would not succeed unless there is an xapp manager running at the defined xm-url. The solution is either to deploy a real XAPP manager before deploying routing-manager or start the mock xmgr as mentioned in [Testing](#testing-and-troubleshoting).
  60
  61 Testing and Troubleshooting
  62 ---------------------------
  63 Testing with Kubernetes
  64 -----------------------
  65 Routing Manager's behaviour can be tested using the mocked xApp Manager, traffic generator xApp and receiver xApp.
  66
  67 * Checkout and compile both xApp receiver and xApp Tx generator of RIC admission control project:
  68   `https://gerrit.o-ran-sc.org/r/admin/repos/ric-app/admin`
  69
  70 * Copy the `adm-ctrl-xapp` binary to `./test/docker/xapp.build` folder furthermore copy all RMR related dinamycally linked library under `./test/docker/xapp.build/usr` folder. Issue `docker build ./test/docker/xapp.build` command. Tag the recently created docker image and push it to the common registry.
  71
  72 * Copy the `test-tx` binary to `./test/docker/xapp-tx.build` folder furthermore copy all RMR related dinamycally linked library under `./test/docker/xapp.build/usr` folder. Issue `docker build ./test/docker/xapp-tx.build` command.  Tag the recently created docker image and push it to the common registry.
  73
  74 * Enter the `./test/docker/xmgr.build` folder and issue `docker build .`.  Tag the recently created docker image and push it to the common registry.
  75
  76 * Modify the docker image version in each kuberbetes manifest files under `./test/kubernetes/` folder accordingly then issue the `kubectl create -f {manifest.yaml}` on each file.
  77
  78 Once the routing manager is started, it retrievs the initial xapp list from `xmgr` via HTTPGet additonaly it starts to listen on http://rtmgr:8888/v1/handles/xapp-handle endpoint and ready to receive xapp list updates.
  79
  80 * Edit the provided `test/data/xapp.json` file accordingly and issue the following curl command to update `rtmgr's` xapp list.
  81
  82   `curl --header "Content-Type: application/json" --request POST --data '@./test/data/xapps.json' http://10.244.2.104:8888/v1/handles/xapp-handle`
  83
  84 Executing unit tests
  85 --------------------
  86 For running unit tests, execute the following command:
  87    `go test ./pkg/nbi` (or any package - feel free to add your own parameters)
  88
  89 If you wish to execute the full UT set with coverage:
  90
  91    mkdir -p unit-test
  92
  93    go test ./pkg/sbi ./pkg/rpe ./pkg/nbi ./pkg/sdl -cover -race -coverprofile=$PWD/unit-test/c.out
  94
  95    go tool cover -html=$PWD/unit-test/c.out -o $PWD/unit-test/coverage.html
  96
  97
  98 For troubleshooting purpose the default logging level can be increased to `DEBUG`. (by hand launch it's set to INFO, kubernetes manifest has DEBUG set by default).