getAllSubscriptions API (RM -> SM) during restart of routing manager handled
[ric-plt/rtmgr.git] / 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).