## Introduction
__Routing Manager__ is a basic platform service of RIC. It is responsible for distributing routing policies among the other platform components and xApps.
-The implemented logic periodically queries the xApp Manager component for xApps' list. Stores the data then processes it to create routing policies and distributes them to all xApps.
+The routing manager has two ways to get the xapp details from xapp manager - httpGetter or httpRESTful.
+In case of httpGetter, the implemented logic periodically queries the xApp Manager component for xApps' list.
+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.
+Either ways, the xapp data received is stored and then processed to create routing policies and distributes them to all xApps.
+
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 operatin of above functions
+* Control Logic (__RTMGR__): Controls the operation of above functions
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
- * (WIP) __httRESTful__: provides REST API endpoints towards RIC manager components
+ * __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:
* (backlog) __sdl__: Shared Data Library to Redis database
* SBI:
* __nngpub__: distributes RPE created policies via NNG Pub channel
- * (WIP) __nngpipe__: distributes RPE created policies via NNG Pipeline channel
+ * __nngpipe__: distributes RPE created policies via NNG Pipeline channel
## Release notes
Check the separated `RELNOTES` file.
## Prerequisites
-* Healthy kubernetes cluster
-* Access to the common docker registry
+* Healthy kubernetes cluster (for Kubernetes testing)
+* Access to the common docker registry (alternatively, you can set up your own private registry for testing: https://docs.docker.com/registry/deploying/)
+* 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)
## Project folder structure
-* /api: contains Swagger source files
-* /build: contains build tools (scripts, Dockerfiles, etc.)
+* /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)
## Installation guide
### Compiling code
-Enter the project root and execute `./build.sh` script.
-The build script has two main phases. First is the code compilation, where it creates a temporary container for downloading all dependencies then compiles the code. In the second phase it builds the production ready container and taggs it to `rtmgr:builder`
+#### Docker compile
+The Dockerfile located in the project root folder does the following three things:
+- 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.
+- As a second step, it executes UTs on rtmgr source code.
+- As a third step, it creates the final container from rtmgr binary (Ubuntu based).
+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)
+
+#### Compiling without docker
+Compiling without Docker involves some manual steps before compiling directly with "go build".
+The XApp manager's spec file must be fetched, then api generated with swagger. (these steps are included in the Dockerfile).
+After the code is generated, glide can install the dependencies of rtmgr.
+Make sure you set your GOPATH variable correctly (example: $HOME/go/src/routing-manager)
+Code generation and building example (from project root folder):
+```bash
+git clone "https://gerrit.o-ran-sc.org/r/ric-plt/appmgr" && cp appmgr/api/appmgr_rest_api.yaml api/
+swagger generate server -f api/routing_manager.yaml -t pkg/ --exclude-main -r LICENSE
+swagger generate client -f api/appmgr_rest_api.yaml -t pkg/ -m appmgr_model -c appmgr_client -r LICENSE
+glide install --strip-vendor
+go build cmd/rtmgr.go
+```
-**NOTE:** The script puts a copy of the binary into the `./bin` folder for further use cases
+**NOTE:** before doing a docker build it is advised to remove any generated files and vendor packages:
+```bash
+# assuming that you stand in project root dir
+rm -rf appmgr vendor pkg/appmgr_* pkg/models pkg/restapi
+```
### Installing Routing Manager
#### Preparing environment
Edit the container image section of `rtmgr-dep.yaml` file according to the `rtmgr` image tag.
#### Deploying Routing Manager
-Issue the `kubectl create -f {manifest.yaml}` command in the following order
+Issue the `kubectl create -f {manifest.yaml}` command in the following order:
1. `manifests/namespace.yaml`: creates the `example` namespace for routing-manager resources
- 2. `manifests/rtmgr/rtmgr-dep.yaml`: instantiates the `rtmgr` deployment in the `example` namespace
- 3. `manifests/rtmgr/rtmgr-svc.yaml`: creates the `rtmgr` service in `example` namespace
+ 2. `manifests/rtmgr/rtmgr-cfg.yaml`: creates default routes config file for routing-manager
+ 3. `manifests/rtmgr/rtmgr-dep.yaml`: instantiates the `rtmgr` deployment in the `example` namespace
+ 4. `manifests/rtmgr/rtmgr-svc.yaml`: creates the `rtmgr` service in `example` namespace
+
+**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).
### Testing and Troubleshoting
+### Testing with Kubernetes
Routing Manager's behaviour can be tested using the mocked xApp Manager, traffic generator xApp and receiver xApp.
- 1. Checkout and compile both xApp receiver and xApp Tx generator of RIC admission control project
+ 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`
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.
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.
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.
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.
6. [Compile](#compiling-code) and [Install routing manager](#installing-routing-manager)
+ 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.
+ 8. Edit the provided `test/data/xapp.json` file accordingly and issue the following curl command to update `rtmgr's` xapp list.
+ ``` curl --header "Content-Type: application/json" --request POST --data '@./test/data/xapps.json' http://10.244.2.104:8888/v1/handles/xapp-handle ```
+
+### 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:
+```bash
+ 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.htm
+```
#### Command line arguments
Routing manager binary can be called with `-h` flag when it displays the available command line arguments and it's default value.
```bash
Usage of ./rtmgr:
+ -configfile string
+ Routing manager's configuration file path (default "/etc/rtmgrcfg.json")
-filename string
Absolute path of file where the route information to be stored (default "/db/rt.json")
-loglevel string
INFO | WARN | ERROR | DEBUG (default "INFO")
-nbi string
- Northbound interface module to be used. Valid values are: 'httpGetter' (default "httpGetter")
+ Northbound interface module to be used. Valid values are: 'httpGetter | httpRESTful' (default "httpGetter")
+ -nbi-if string
+ Base HTTP URL where routing manager will be listening on (default "http://localhost:8888")
-rpe string
Route Policy Engine to be used. Valid values are: 'rmrpush | rmrpub' (default "rmrpush")
-sbi string
Datastore enginge to be used. Valid values are: 'file' (default "file")
-xm-url string
HTTP URL where xApp Manager exposes the entire xApp List (default "http://localhost:3000/xapps")
+
```
-For troubleshooting purpose the default logging level can be increased to `DEBUG`.
+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).
## Upcoming changes
-[] Add RESTful NBI based on swagger api definition
-
[] Add unit tests
+
## License
This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE)
Code Review / ric-plt / rtmgr.git / blobdiff