Upgraded to RMR 4.7.4 and some improvements
[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 Architecture
31 ------------
32 The architecture consists of the following five well defined functions:
33
34 * NorthBound Interface (__NBI__): Maintains the communication channels towards RIC manager components
35 * Routing Policy Engine (__RPE__): Provides the logic to calculate routing policies
36 * Shared Data Layer (__SDL__): Provides access to different kind persistent data stores
37 * SouthBound Interface (__SBI__): Maintains the communication channels towards RIC tenants and control components
38 * Control Logic (__RTMGR__): Controls the operation of above functions
39
40 Configuration Settings for Routing Manager
41 ------------------------------------------
42 The configuration related parameters for routing manager are provided in the following files -
43
44 ConfigMap: ric-dep/helm/rtmgr/config.yaml:
45 ------------------------------------------
46 This file has the major configurations. The description for each of them is given below -
47
48 * PlatformComponents : Represents the platform components that needs route table to be distributed. They usually contain the hard coded name(used internally by Routing Manager), the FQDN name and the port.
49
50 * XMURL : The URL used by RM to query Appmgr to provide the Xapp list during start-up
51
52 * EMURL : The URL used by RM to query E2Mgr to provide the E2Termination list during start-up
53
54 * RTFILE: File based data store that RM uses to store the route table information and other internal details.
55
56 * CFGFILE: Stores the path of config file in RTE. Mandatorily needed to start RM.
57
58 * RPE/SBI/SBIURL/NBI/NBIURL/SDL : Derived from the RM helm chart and needed for respective module initialization.
59
60 * logger : To change the log level setting
61
62 * local : Http server that listens on the specified port. This port used for dumping RTFILE contains.
63
64 * rmr : RMR messaging related attributes needed by xapp-framework.
65
66   * protPort: RMR Listening Port
67   * maxSize: Maximum Transmission Buffer size
68   * threadType: Always set to 1 so that RM doesn't wait for static Route table initialization.
69
70 * PlatformRoutes: Static platform routes between the Platform Components. Based on these rules the routes wll get populated. The syntax is based on the RMR route table syntax.
71
72   * messagetype: Message types as defined in mtypes.go(rmr.h) in xapp-framework(RMR)
73   * senderendpoint: Message originating address in the form IP:PORT
74   * subscriptionid: Subscription ID to be filled, mostlt "-1" for all static routes
75   * endpoint: Message reception address in the form IP:PORT
76   * meid: meid entry is required to be populated by "%meid"
77   
78   
79 Env File: ric-dep/helm/rtmgr/env.yaml:
80 ---------------------------------------
81 This file contains attributes based that are required by RMR.
82
83
84 Installing RIC Platform - Routing Manager gets deployed automatically
85 ---------------------------------------------------------------------
86 Follow the procedure found in 
87
88 https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-ric-dep/en/latest/
89
90 This will be the best way to test the bugs and integrate new features. 
91
92 Testing and Troubleshooting
93 ---------------------------
94
95 1. Routing Manager is in Continous Reboot loop.
96   
97    1a. Check if the appmgr POD is running by running the command. This command should show it as "Running"
98    1b. If appmgr is running as expected, check the logs of appmgr,if helm is properly initialised.
99
100 .. code:: bash
101
102    1a .#kubectl get pods -n ricplt | grep appmgr
103    deployment-ricplt-appmgr-77bcbb8886-p4zvq          2/2     Running   0          2d3h
104
105    2a .# kubectl logs  deployment-ricplt-appmgr-77bcbb8886-p4zvq -n ricplt container-ricplt-appmgr | grep "Helm init done successfully"
106    {"ts":1585551084410,"crit":"INFO","id":"appmgr","mdc":{"time":"2020-03-30T06:51:24Z","xm":"0.4.1"},"msg":"Helm init done successfully!"}
107
108    
109 2. Check the Routes generated by Routing Manager and its internal map.
110
111    If this REST API is command fired, it should return the list of routes generated for platform components and the file contents. This should match with the user expectations while debugging.
112
113 .. code:: bash
114
115    curl -X GET "http://<KONGPROXY_IP>:3800/ric/v1/getdebuginfo" -H  "accept: application/json" | json_pp
116
117    # curl -X GET "http://10.101.18.182:3800/ric/v1/getdebuginfo" -H  "accept: application/json" | json_pp
118    % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
119                                   Dload  Upload   Total   Spent    Left  Speed
120    100  3765    0  3765    0     0  71037      0 --:--:-- --:--:-- --:--:-- 71037
121    {
122     "RouteConfigs" : "{\n\"XApps\": null,\n\"E2Ts\": {\n\"10.102.131.163:38000\": {\n\"name\": \"E2TERMINST\",\n\"fqdn\": \"10.102.131.163:38000\",\n\"ranlist\": []\n},\n\"10.103.165.47:38000\": {\n\"name\": \"E2TERMINST\",\n\"fqdn\": \"10.103.165.47:38000\",\n\"ranlist\": []\n},\n\"10.104.160.127:38000\": {\n\"name\": \"E2TERMINST\",\n\"fqdn\": \"10.104.160.127:38000\",\n\"ranlist\": []\n},\n\"10.104.30.46:38000\": {\n\"name\": \"E2TERMINST\",\n\"fqdn\": \"10.104.30.46:38000\",\n\"ranlist\": []\n},\n\"10.108.90.168:38000\": {\n\"name\": \"E2TERMINST\",\n\"fqdn\": \"10.108.90.168:38000\",\n\"ranlist\": []\n},\n\"10.110.3.220:38000\": {\n\"name\": \"E2TERMINST\",\n\"fqdn\": \"10.110.3.220:38000\",\n\"ranlist\": []\n},\n\"10.97.122.250:38000\": {\n\"name\": \"E2TERMINST\",\n\"fqdn\": \"10.97.122.250:38000\",\n\"ranlist\": []\n},\n\"10.98.173.62:38000\": {\n\"name\": \"E2TERMINST\",\n\"fqdn\": \"10.98.173.62:38000\",\n\"ranlist\": []\n}\n},\n\"MeidMap\": [],\n\"Pcs\": [\n{\n\"name\": \"E2TERM\",\n\"fqdn\": \"service-ricplt-e2term-rmr.ricplt\",\n\"port\": 38000\n},\n{\n\"name\": \"SUBMAN\",\n\"fqdn\": \"service-ricplt-submgr-rmr.ricplt\",\n\"port\": 4560\n},\n{\n\"name\": \"E2MAN\",\n\"fqdn\": \"service-ricplt-e2mgr-rmr.ricplt\",\n\"port\": 3801\n},\n{\n\"name\": \"RSM\",\n\"fqdn\": \"service-ricplt-rsm-rmr.ricplt\",\n\"port\": 4801\n},\n{\n\"name\": \"A1MEDIATOR\",\n\"fqdn\": \"service-ricplt-a1mediator-rmr.ricplt\",\n\"port\": 4562\n}\n]\n}",
123    "RouteTable" : [
124       "newrt|start\n",
125       "mse|12010,service-ricplt-submgr-rmr.ricplt:4560|-1|%meid\n",
126       "mse|12020,service-ricplt-submgr-rmr.ricplt:4560|-1|%meid\n",
127       "mse|12011|-1|service-ricplt-submgr-rmr.ricplt:4560\n",
128       "mse|12021|-1|service-ricplt-submgr-rmr.ricplt:4560\n",
129       "mse|12012|-1|service-ricplt-submgr-rmr.ricplt:4560\n",
130       "mse|12022|-1|service-ricplt-submgr-rmr.ricplt:4560\n",
131       "mse|10060,service-ricplt-e2mgr-rmr.ricplt:3801|-1|%meid\n",
132       "mse|10070,service-ricplt-e2mgr-rmr.ricplt:3801|-1|%meid\n",
133       "mse|10071,service-ricplt-e2mgr-rmr.ricplt:3801|-1|%meid\n",
134       "mse|10360,service-ricplt-e2mgr-rmr.ricplt:3801|-1|%meid\n",
135       "mse|10081,service-ricplt-e2mgr-rmr.ricplt:3801|-1|%meid\n",
136       "mse|10082,service-ricplt-e2mgr-rmr.ricplt:3801|-1|%meid\n",
137       "mse|10371,service-ricplt-e2mgr-rmr.ricplt:3801|-1|%meid\n",
138       "mse|10372,service-ricplt-e2mgr-rmr.ricplt:3801|-1|%meid\n",
139       "mse|1100|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
140       "mse|10061|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
141       "mse|10062|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
142       "mse|10070|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
143       "mse|10071|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
144       "mse|10361|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
145       "mse|10362|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
146       "mse|10370|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
147       "mse|1080|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
148       "mse|10030|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
149       "mse|10080|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
150       "mse|10020|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
151       "mse|1102|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
152       "mse|1200,service-ricplt-e2mgr-rmr.ricplt:3801|-1|\n",
153       "mse|1210,service-ricplt-e2mgr-rmr.ricplt:3801|-1|\n",
154       "mse|1220,service-ricplt-e2mgr-rmr.ricplt:3801|-1|\n",
155       "mse|20012|-1|service-ricplt-a1mediator-rmr.ricplt:4562\n",
156       "mse|20011|-1|service-ricplt-a1mediator-rmr.ricplt:4562\n",
157       "mse|1090,service-ricplt-e2mgr-rmr.ricplt:3801|-1|10.104.160.127:38000;10.108.90.168:38000;10.102.131.163:38000;10.97.122.250:38000;10.98.173.62:38000;10.103.165.47:38000;10.110.3.220:38000;10.104.30.46:38000\n",
158       "mse|1101,service-ricplt-e2mgr-rmr.ricplt:3801|-1|10.104.160.127:38000;10.108.90.168:38000;10.102.131.163:38000;10.97.122.250:38000;10.98.173.62:38000;10.103.165.47:38000;10.110.3.220:38000;10.104.30.46:38000\n",
159       "newrt|end\n",
160       "meid_map|start\nmeid_map|end|0\n"
161    ]
162    }
163
164 3. Further debugging can be done by checking the logs of routing manager. Debug flag if enabled in config map will allow more logs to be printed on the console
165
166 .. code:: bash
167
168    #To enable debug logs, ensure this variable is as shown below in  ric-dep/helm/rtmgr/templates/config.yaml
169            "logger":
170                  "level": 4
171    #Re-start rtmgr and check for the logs,
172            kubectl logs <podname> -n ricplt
173
174 Executing unit tests
175 --------------------
176 For running unit tests, execute the following command:
177    `go test ./pkg/nbi` (or any package - feel free to add your own parameters)
178
179 If you wish to execute the full UT set with coverage:
180
181 .. code:: bash
182
183    mkdir -p unit-test
184    go test ./pkg/sbi ./pkg/rpe ./pkg/nbi ./pkg/sdl -cover -race -coverprofile=$PWD/unit-test/c.out
185    go tool cover -html=$PWD/unit-test/c.out -o $PWD/unit-test/coverage.html
186