Welcome to O-RAN SC Routing Manager¶

Installation Guide¶

Introduction ¶

Routing Manager is a basic platform service of RIC. It is responsible for distributing routing policies to other platform components and xApps.

Installation of routing manager in a k8s environment¶

This deployment guide is for testing routing manager in actual k8s environment.

Pre-requisites ¶

Kubernetes v.1.16.0 or above

helm v2.12.3 or above

Appmgr pods should be deployed and in running state

Clone the ric-plt/dep git repository ¶

git clone "https://gerrit.o-ran-sc.org/r/ric-plt/ric-dep"

Modify the deployment recipe ¶

Locate for ‘rtmgr’ in the recipe file and edit the tag and repo.

rtmgr:
  image:
    registry: "nexus3.o-ran-sc.org:10004/o-ran-sc"
    name: ric-plt-rtmgr
    tag: 0.5.3

Copy the ric-common helm charts for it/dep, configure the helm repo and start local helm server

git clone "https://gerrit.o-ran-sc.org/r/it/dep"
HELM_HOME=$(helm home)
COMMON_CHART_VERSION=$(cat dep/ric-common/Common-Template/helm/ric-common/Chart.yaml | grep version | awk '{print $2}')
helm package -d /tmp dep/ric-common/Common-Template/helm/ric-common
cp /tmp/ric-common-$COMMON_CHART_VERSION.tgz $HELM_HOME/repository/local/
helm repo index $HELM_HOME/repository/local/
helm serve >& /dev/null &
helm repo remove local
helm repo add local http://127.0.0.1:8879/charts

At this stage, routing manager can be deployed.

cd ric-dep/bin
./install -f ../RECIPE_EXAMPLE/PLATFORM/example_recipe.yaml -c rtmgr

Checking the Deployment Status ¶

Now check the deployment status after a short wait. Results similar to the output shown below indicate a complete and successful deployment. Check the STATUS column from both kubectl outputs to ensure that all are either “Completed” or “Running”, and that none are “Error” or “ImagePullBackOff”.

#helm list | grep rtmgr
r3-rtmgr                1               Wed Mar 25 08:34:22 2020        DEPLOYED        rtmgr-3.0.0             1.0          ricplt

# kubectl get pods -n ricplt | grep rtmgr
deployment-ricplt-rtmgr-6446b96b65-8mxzn           1/1     Running   0          46s

Checking Container Health ¶

Check the health of the routing manager platform component by querying it with the following command.

#kubectl get pods -n ricplt -o wide | grep rtmgr
deployment-ricplt-rtmgr-6446b96b65-8mxzn           1/1     Running   0          16m   10.244.0.17    master-node   <none>           <none>


curl -v http://10.244.0.17:8080/ric/v1/health/alive
*   Trying 10.244.0.17...
* TCP_NODELAY set
* Connected to 10.244.0.17 (10.244.0.17) port 8080 (#0)
> GET /ric/v1/health/alive HTTP/1.1
> Host: 10.244.0.17:8080
> User-Agent: curl/7.58.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Wed, 25 Mar 2020 03:19:05 GMT
< Content-Length: 0
<
* Connection #0 to host 10.244.0.17 left intact

Undeploying Routing Manager ¶

#helm delete --purge r3-rtmgr

Installation of routing manager in a standalone linux machine¶

This deployment guide will be useful for development purposes

Pre-requisites¶

Ubuntu machine

golang 1.12.1 minimum

Compiling Routing Manager¶

Clone the ric-plt/dep git repository.

git clone "https://gerrit.o-ran-sc.org/r/ric-plt/rtmgr"

Execute this shell script which will give you the rtmgr as executable

cd rtmgr/example
./rtmgr_exe.sh

Run rtmgr by passing the config file as parameter. Note that the rtmgr may abort after sometime as it needs appmgr to be running. This can be tweaked by modifying the actual code. As this would be needed only for actual Development, the sam eis not being mentioned here.

./rtmgr -f rtmgr-config.yaml

Developer-Guide¶

Overview ¶

Routing Manager is a basic platform service of RIC. It is responsible for distributing routing policies among the other platform components and xApps.

Architecture ¶

The architecture consists of the following five well defined functions:

NorthBound Interface (__NBI__): Maintains the communication channels towards RIC manager components
Routing Policy Engine (__RPE__): Provides the logic to calculate routing policies
Shared Data Layer (__SDL__): Provides access to different kind persistent data stores
SouthBound Interface (__SBI__): Maintains the communication channels towards RIC tenants and control components
Control Logic (__RTMGR__): Controls the operation of above functions

Configuration Settings for Routing Manager ¶

The configuration related parameters for routing manager are provided in the following files -

ConfigMap: ric-dep/helm/rtmgr/config.yaml:¶

This file has the major configurations. The description for each of them is given below -

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.
XMURL : The URL used by RM to query Appmgr to provide the Xapp list during start-up
EMURL : The URL used by RM to query E2Mgr to provide the E2Termination list during start-up
RTFILE: File based data store that RM uses to store the route table information and other internal details.
CFGFILE: Stores the path of config file in RTE. Mandatorily needed to start RM.
RPE/SBI/SBIURL/NBI/NBIURL/SDL : Derived from the RM helm chart and needed for respective module initialization.
logger : To change the log level setting
local : Http server that listens on the specified port. This port used for dumping RTFILE contains.
rmr : RMR messaging related attributes needed by xapp-framework.
- protPort: RMR Listening Port
- maxSize: Maximum Transmission Buffer size
- threadType: Always set to 1 so that RM doesn’t wait for static Route table initialization.
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.
- messagetype: Message types as defined in mtypes.go(rmr.h) in xapp-framework(RMR)
- senderendpoint: Message originating address in the form IP:PORT
- subscriptionid: Subscription ID to be filled, mostlt “-1” for all static routes
- endpoint: Message reception address in the form IP:PORT
- meid: meid entry is required to be populated by “%meid”

Env File: ric-dep/helm/rtmgr/env.yaml:¶

This file contains attributes based that are required by RMR.

Installing RIC Platform - Routing Manager gets deployed automatically ¶

Follow the procedure found in

https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-ric-dep/en/latest/

This will be the best way to test the bugs and integrate new features.

Testing and Troubleshooting ¶

Routing Manager is in Continous Reboot loop.

1a. Check if the appmgr POD is running by running the command. This command should show it as “Running” 1b. If appmgr is running as expected, check the logs of appmgr,if helm is properly initialised.

1a .#kubectl get pods -n ricplt | grep appmgr
deployment-ricplt-appmgr-77bcbb8886-p4zvq          2/2     Running   0          2d3h

2a .# kubectl logs  deployment-ricplt-appmgr-77bcbb8886-p4zvq -n ricplt container-ricplt-appmgr | grep "Helm init done successfully"
{"ts":1585551084410,"crit":"INFO","id":"appmgr","mdc":{"time":"2020-03-30T06:51:24Z","xm":"0.4.1"},"msg":"Helm init done successfully!"}

Check the Routes generated by Routing Manager and its internal map.

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.

curl -X GET "http://<KONGPROXY_IP>:3800/ric/v1/getdebuginfo" -H  "accept: application/json" | json_pp

# curl -X GET "http://10.101.18.182:3800/ric/v1/getdebuginfo" -H  "accept: application/json" | json_pp
% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                               Dload  Upload   Total   Spent    Left  Speed
100  3765    0  3765    0     0  71037      0 --:--:-- --:--:-- --:--:-- 71037
{
 "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}",
"RouteTable" : [
   "newrt|start\n",
   "mse|12010,service-ricplt-submgr-rmr.ricplt:4560|-1|%meid\n",
   "mse|12020,service-ricplt-submgr-rmr.ricplt:4560|-1|%meid\n",
   "mse|12011|-1|service-ricplt-submgr-rmr.ricplt:4560\n",
   "mse|12021|-1|service-ricplt-submgr-rmr.ricplt:4560\n",
   "mse|12012|-1|service-ricplt-submgr-rmr.ricplt:4560\n",
   "mse|12022|-1|service-ricplt-submgr-rmr.ricplt:4560\n",
   "mse|10060,service-ricplt-e2mgr-rmr.ricplt:3801|-1|%meid\n",
   "mse|10070,service-ricplt-e2mgr-rmr.ricplt:3801|-1|%meid\n",
   "mse|10071,service-ricplt-e2mgr-rmr.ricplt:3801|-1|%meid\n",
   "mse|10360,service-ricplt-e2mgr-rmr.ricplt:3801|-1|%meid\n",
   "mse|10081,service-ricplt-e2mgr-rmr.ricplt:3801|-1|%meid\n",
   "mse|10082,service-ricplt-e2mgr-rmr.ricplt:3801|-1|%meid\n",
   "mse|10371,service-ricplt-e2mgr-rmr.ricplt:3801|-1|%meid\n",
   "mse|10372,service-ricplt-e2mgr-rmr.ricplt:3801|-1|%meid\n",
   "mse|1100|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
   "mse|10061|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
   "mse|10062|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
   "mse|10070|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
   "mse|10071|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
   "mse|10361|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
   "mse|10362|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
   "mse|10370|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
   "mse|1080|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
   "mse|10030|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
   "mse|10080|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
   "mse|10020|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
   "mse|1102|-1|service-ricplt-e2mgr-rmr.ricplt:3801\n",
   "mse|1200,service-ricplt-e2mgr-rmr.ricplt:3801|-1|\n",
   "mse|1210,service-ricplt-e2mgr-rmr.ricplt:3801|-1|\n",
   "mse|1220,service-ricplt-e2mgr-rmr.ricplt:3801|-1|\n",
   "mse|20012|-1|service-ricplt-a1mediator-rmr.ricplt:4562\n",
   "mse|20011|-1|service-ricplt-a1mediator-rmr.ricplt:4562\n",
   "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",
   "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",
   "newrt|end\n",
   "meid_map|start\nmeid_map|end|0\n"
]
}

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

#To enable debug logs, ensure this variable is as shown below in  ric-dep/helm/rtmgr/templates/config.yaml
        "logger":
              "level": 4
#Re-start rtmgr and check for the logs,
        kubectl logs <podname> -n ricplt

Executing unit tests ¶

For running unit tests, execute the following command:: go test ./pkg/nbi (or any package - feel free to add your own parameters)

If you wish to execute the full UT set with coverage:

mkdir -p unit-test
go test ./pkg/sbi ./pkg/rpe ./pkg/nbi ./pkg/sdl -cover -race -coverprofile=$PWD/unit-test/c.out
go tool cover -html=$PWD/unit-test/c.out -o $PWD/unit-test/coverage.html

Release-Notes¶

This document provides the release notes for O-RAN SC Amber Release of ric-plt/rtmgr.

Version history ¶

Version 1.0.0, November 12, 2019 ¶

Populates the RMR routing table between the RIC platform component pairs E2Term,Subscription Manager and E2Term,E2Manager
Queries xAppManager for the deployed xApps and populates the RMR routing table between the xApps,Subscription Manager
Populates routes based on the subscription ID between xApps,Subscription Manager

Components ¶

/api: contains Swagger spec files
/manifest: contains deployment files (Kubernetes manifests, Helm chart)
/cmd: contains go project’s main file
/pkg: contains go project’s internal packages
/test: contains CI/CD testing files (scripts, mocks, manifests)
Dockerfile: contains main docker file
container-tag.yaml: contains CI specific container tag information
run_rtmgr.sh: shell script to run rtmgr (requires environment variables to be set)

Current implementation provides support for the followings:

NBI: * __httpGet__: simple HTTP GET interface. Expects an URL where it gets the xApps’ list in JSON format * __httRESTful__: provides REST API endpoints towards RIC manager components. Expects REST port and url where the HTTP service will be started to listen on.
RPE: * __rmr__: creates routing policies formatted for RIC RMR
SDL: * __file__: stores xApp data in container’s local filesystem (or in a mountpoint) * (backlog) __sdl__: Shared Data Library to Redis database
SBI: * __nngpub__: distributes RPE created policies via NNG Pub channel * __nngpipe__: distributes RPE created policies via NNG Pipeline channel

Limitations ¶

API-Docs¶

This is the API-docs of ROUTING MANAGER

API Introduction ¶

Routing Manager interacts with the following RIC platform components.

* Appmgr:

  1. POST API to request the xapp list available
   http://<rtmgr_http_service_IP>/ric/v1/xapps
  2. POST API to send the xapps that either get deployed or undeployed
   http://<rtmgr_http_service_IP>/ric/v1/handles/xapp-handle

* Submgr:

  1. POST API to provide the subscription details
   http://<rtmgr_http_service_IP>/ric/v1/handles/xapp-subscription-handle

  2. DELETE API to delete the subscription details
   http://<rtmgr_http_service_IP>/ric/v1/handles/xapp-subscription-handle

  3. PUT API to update the subscriptionID for given xApp.
   http://<rtmgr_http_service_IP>/ric/v1/handles/xapp-subscription-handle/{subscription_id}

* E2Mgr:

  1. POST API to Add E2Termination Instance
   http://<rtmgr_http_service_IP>/ric/v1/handles/e2t

  2. DELETE API to Delete E2Termination Instance
   http://<rtmgr_http_service_IP>/ric/v1/handles/e2t

  3. POST API to Associate RAN names to a given E2Termination
   http://<rtmgr_http_service_IP>/ric/v1/handles/associate-ran-to-e2t

  4. DELETE API to Dissociate RAN names to a given E2Termination
   http://<rtmgr_http_service_IP>/ric/v1/handles/dissociate-ran

* Health Check:

  1. GET API's to retrieve the Aliveness and Readyness checks
   http://<rtmgr_pod_IP>:8080/ric/v1/health/alive
   http://<rtmgr_pod_IP>:8080/ric/v1/health/ready

API Functions ¶

Routing Manager request the xapp list and E2Term list available during startup.

AppMgr send complete xapps list whenever a xapp is deployed/undeployed

Subscription Manager adds/deletes subscription ID

Update the subscription ID for given xApp.(Subscription Merge Add)

Update the subscription ID for given xApp.(Subscription Merge Delete)

E2Mgr sends request to Add/Delete E2Termination Instance

E2Mgr sends request to Associate/Dissociate RAN names to a given E2Termination Instance