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