README.md

   1 # Routing Manager
   2
   3 ## Table of contents
   4 * [Introduction](#introduction)
   5 * [Release notes](#release-notes)
   6 * [Prerequisites](#prerequisites)
   7 * [Project folders structure](#project-folders-structure)
   8 * [Installation guide](#installation-guide)
   9   * [Compiling code](#compiling-code)
  10   * [Building docker container](#building-docker-container)
  11   * [Installing Routing Manager](#installing-routing-manager)
  12   * [Testing and Troubleshoting](#testing-and-troubleshoting)
  13 * [Upcoming changes](#upcoming-changes)
  14 * [License](#license)
  15
  16 ## Introduction
  17 __Routing Manager__ is a basic platform service of RIC. It is responsible for distributing routing policies among the other platform components and xApps.
  18
  19 The routing manager has two ways to get the xapp details from xapp manager - httpGetter or httpRESTful.
  20 In case of httpGetter, the implemented logic periodically queries the xApp Manager component for xApps' list.
  21 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.
  22 Either ways, the xapp data received is stored and then processed to create routing policies and distributes them to all xApps.
  23
  24 The architecture consists of the following five well defined functions:
  25 * NorthBound Interface (__NBI__): Maintains the communication channels towards RIC manager components
  26 * Routing Policy Engine (__RPE__): Provides the logic to calculate routing policies
  27 * Shared Data Layer (__SDL__): Provides access to different kind persistent data stores
  28 * SouthBound Interface (__SBI__): Maintains the communication channels towards RIC tenants and control components
  29 * Control Logic (__RTMGR__): Controls the operation of above functions
  30
  31 Current implementation provides support for the followings:
  32 * NBI:
  33   * __httpGet__: simple HTTP GET interface. Expects an URL where it gets the xApps' list in JSON format
  34   * __httRESTful__: provides REST API endpoints towards RIC manager components. Expects REST port and url where the HTTP service will be started to listen on.
  35 * RPE:
  36   * __rmr__: creates routing policies formatted for RIC RMR
  37 * SDL:
  38   * __file__: stores xApp data in container's local filesystem (or in a mountpoint)
  39   * (backlog) __sdl__: Shared Data Library to Redis database
  40 * SBI:
  41   * __nngpub__: distributes RPE created policies via NNG Pub channel
  42   * __nngpipe__: distributes RPE created policies via NNG Pipeline channel
  43
  44 ## Release notes
  45 Check the separated `RELNOTES` file.
  46
  47 ## Prerequisites
  48 * Healthy kubernetes cluster (for Kubernetes testing)
  49 * Access to the common docker registry (alternatively, you can set up your own private registry for testing: https://docs.docker.com/registry/deploying/)
  50 * In case of non-Docker build: golang 11.1 at least, go-swagger (https://github.com/go-swagger/go-swagger, v0.19.0), glide (https://github.com/Masterminds/glide), XApp Manager spec file (available in ORAN: https://gerrit.o-ran-sc.org/r/admin/repos/ric-plt/appmgr under api folder)
  51
  52 ## Project folder structure
  53 * /api: contains Swagger spec files
  54 * /manifest: contains deployment files (Kubernetes manifests, Helm chart)
  55 * /cmd: contains go project's main file
  56 * /pkg: contains go project's internal packages
  57 * /test: contains CI/CD testing files (scripts, mocks, manifests)
  58 * Dockerfile: contains main docker file
  59 * container-tag.yaml: contains CI specific container tag information
  60 * run_rtmgr.sh: shell script to run rtmgr (requires environment variables to be set)
  61
  62 ## Installation guide
  63
  64 ### Compiling code
  65 #### Docker compile
  66 The Dockerfile located in the project root folder does the following three things:
  67 - As a first step, it creates a build container, fetches XApp Manager's spec file, generates rest api code from swagger spec and builds rtmgr.
  68 - As a second step, it executes UTs on rtmgr source code.
  69 - As a third step, it creates the final container from rtmgr binary (Ubuntu based).
  70 For a docker build execute `docker build --tag=rtmgr-build:test .` in the project root directory (feel free to replace the name:tag with your own)
  71
  72 #### Compiling without docker
  73 Compiling without Docker involves some manual steps before compiling directly with "go build".
  74 The XApp manager's spec file must be fetched, then api generated with swagger. (these steps are included in the Dockerfile).
  75 After the code is generated, glide can install the dependencies of rtmgr.
  76 Make sure you set your GOPATH variable correctly (example: $HOME/go/src/routing-manager)
  77 Code generation and building example (from project root folder):
  78 ```bash
  79 git clone "https://gerrit.o-ran-sc.org/r/ric-plt/appmgr" && cp appmgr/api/appmgr_rest_api.yaml api/
  80 swagger generate server -f api/routing_manager.yaml -t pkg/ --exclude-main -r LICENSE
  81 swagger generate client -f api/appmgr_rest_api.yaml -t pkg/ -m appmgr_model -c appmgr_client -r LICENSE
  82 glide install --strip-vendor
  83 go build cmd/rtmgr.go
  84 ```
  85
  86 **NOTE:** before doing a docker build it is advised to remove any generated files and vendor packages:
  87 ```bash
  88 # assuming that you stand in project root dir
  89 rm -rf appmgr vendor pkg/appmgr_* pkg/models pkg/restapi
  90 ```
  91
  92 ### Installing Routing Manager
  93 #### Preparing environment
  94 Tag the `rtmgr` container according to the project release and push it to a registry accessible from all minions of the Kubernetes cluster.
  95 Edit the container image section of `rtmgr-dep.yaml` file according to the `rtmgr` image tag.
  96
  97 #### Deploying Routing Manager
  98 Issue the `kubectl create -f {manifest.yaml}` command in the following order:
  99   1. `manifests/namespace.yaml`: creates the `example` namespace for routing-manager resources
 100   2. `manifests/rtmgr/rtmgr-cfg.yaml`: creates default routes config file for routing-manager
 101   3. `manifests/rtmgr/rtmgr-dep.yaml`: instantiates the `rtmgr` deployment in the `example` namespace
 102   4. `manifests/rtmgr/rtmgr-svc.yaml`: creates the `rtmgr` service in `example` namespace
 103
 104 **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).
 105
 106 ### Testing and Troubleshoting
 107 ### Testing with Kubernetes
 108 Routing Manager's behaviour can be tested using the mocked xApp Manager, traffic generator xApp and receiver xApp.
 109
 110   1. Checkout and compile both xApp receiver and xApp Tx generator of RIC admission control project: `https://gerrit.o-ran-sc.org/r/admin/repos/ric-app/admin`
 111   2. 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.
 112   3. 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.
 113   4. Enter the `./test/docker/xmgr.build` folder and issue `docker build .`.  Tag the recently created docker image and push it to the common registry.
 114   5. 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.
 115   6. [Compile](#compiling-code) and [Install routing manager](#installing-routing-manager)
 116   7. 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.
 117   8. Edit the provided `test/data/xapp.json` file accordingly and issue the following curl command to update `rtmgr's` xapp list.
 118      ``` curl --header "Content-Type: application/json" --request POST --data '@./test/data/xapps.json' http://10.244.2.104:8888/v1/handles/xapp-handle ```
 119
 120 ### Executing unit tests
 121 For running unit tests, execute the following command:
 122   `go test ./pkg/nbi` (or any package - feel free to add your own parameters)
 123 If you wish to execute the full UT set with coverage:
 124 ```bash
 125   mkdir -p unit-test
 126   go test ./pkg/sbi ./pkg/rpe ./pkg/nbi ./pkg/sdl -cover -race -coverprofile=$PWD/unit-test/c.out
 127   go tool cover -html=$PWD/unit-test/c.out -o $PWD/unit-test/coverage.htm
 128 ```
 129
 130 #### Command line arguments
 131 Routing manager binary can be called with `-h` flag when it displays the available command line arguments and it's default value.
 132
 133 Example:
 134
 135 ```bash
 136 Usage of ./rtmgr:
 137   -configfile string
 138         Routing manager's configuration file path (default "/etc/rtmgrcfg.json")
 139   -filename string
 140         Absolute path of file where the route information to be stored (default "/db/rt.json")
 141   -loglevel string
 142         INFO | WARN | ERROR | DEBUG (default "INFO")
 143   -nbi string
 144         Northbound interface module to be used. Valid values are: 'httpGetter | httpRESTful' (default "httpGetter")
 145   -nbi-if string
 146         Base HTTP URL where routing manager will be listening on (default "http://localhost:8888")
 147   -rpe string
 148         Route Policy Engine to be used. Valid values are: 'rmrpush | rmrpub' (default "rmrpush")
 149   -sbi string
 150         Southbound interface module to be used. Valid values are: 'nngpush | nngpub' (default "nngpush")
 151   -sbi-if string
 152         IPv4 address of interface where Southbound socket to be opened (default "0.0.0.0")
 153   -sdl string
 154         Datastore enginge to be used. Valid values are: 'file' (default "file")
 155   -xm-url string
 156         HTTP URL where xApp Manager exposes the entire xApp List (default "http://localhost:3000/xapps")
 157
 158 ```
 159
 160 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).
 161
 162 ## Upcoming changes
 163 [] Add unit tests
 164
 165
 166 ## License
 167 This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE)
 168