-# Routing Manager\r
-\r
-## Table of contents\r
-* [Introduction](#introduction)\r
-* [Release notes](#release-notes)\r
-* [Prerequisites](#prerequisites)\r
-* [Project folders structure](#project-folders-structure)\r
-* [Installation guide](#installation-guide)\r
- * [Compiling code](#compiling-code)\r
- * [Building docker container](#building-docker-container)\r
- * [Installing Routing Manager](#installing-routing-manager)\r
- * [Testing and Troubleshoting](#testing-and-troubleshoting)\r
-* [Upcoming changes](#upcoming-changes)\r
-* [License](#license)\r
-\r
-## Introduction\r
-__Routing Manager__ is a basic platform serive of RIC. It is responsible for distributing routing policies among the other platform components and xApps.\r
-\r
-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.\r
-The architecture consists of the following five well defined functions:\r
-* NorthBound Interface (__NBI__): Maintains the communication channels towards RIC manager components \r
-* Routing Policy Engine (__RPE__): Provides the logic to calculate routing policies\r
-* Shared Data Layer (__SDL__): Provides access to different kind persistent data stores\r
-* SouthBound Interface (__SBI__): Maintains the communication channels towards RIC tenants and control components\r
-* Controll Logic (__RTMGR__): Controls the operatin of above functions\r
-\r
-Current implementation provides support for the followings:\r
-* NBI:\r
- * __httpGet__: simple HTTP GET interface. Expects an URL where it gets the xApps' list in JSON format\r
- * (WIP) __httRESTful__: provides REST API endpoints towards RIC manager components \r
-* RPE:\r
- * __rmr__: creates routing policies formatted for RIC RMR\r
-* SDL:\r
- * __file__: stores xApp data in container's local filesystem (or in a mountpoint)\r
- * (backlog) __sdl__: Shared Data Library to Redis database\r
-* SBI:\r
- * __nngpub__: distributes RPE created policies via NNG Pub channel\r
- * (WIP) __nngpipe__: distributes RPE created policies via NNG Pipeline channel\r
-\r
-## Release notes\r
-Check the separated `RELNOTES` file.\r
-\r
-## Prerequisites\r
-* Healthy kubernetes cluster\r
-* Access to the common docker registry\r
-\r
-## Project folder structure\r
-* /api: contains swagger source files\r
-* /build: contains build tools (scripts, Dockerfiles, etc.)\r
-* /manifest: contains deployment files (kubernetes manifests, helm chart)\r
-* /cmd: contains go project's main file\r
-* /pkg: contains go project's internal packages\r
-* /test: contains CI/CD testing files (scripts, mocks, manifests)\r
-\r
-## Installation guide\r
-\r
-### Compiling code\r
-Enter the project root and execute `./build.sh` script.\r
-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`\r
-**NOTE:** The script puts a copy of the binary into the `./bin` folder for further use cases\r
-\r
-### Installing Routing Manager\r
-#### Preparing environment\r
-Re-Tag the `rtmgr` container according to the project release and push it to a registry accessible from all minions of the kubernetes cluster.\r
-Edit the container image section of `rtmgr-dep.yaml` file according to the `rtmgr` image tag\r
-\r
-#### Deploying Routing Manager \r
-Issue the `kubectl create -f {manifest.yaml}` command in the following order\r
- 1. `manifests/namespaces.yaml`: creates the `example` namespace for routing-manager resources\r
- 2. `manifests/rtmgr/rtmgr-dep.yaml`: instantiates the `rtmgr` deployment in the `example` namespace\r
- 3. `manifests/rtmgr/rtmgr-svc.yaml`: creates the `rtmgr` service in `example` namespace\r
-\r
-### Testing and Troubleshoting\r
-Routing Manager's behaviour can be tested using the mocked xApp Manager, traffic generator xApp and receiver xApp.\r
-\r
- 1. Checkout and compile both xApp receiver and xApp Tx generator of RIC admission control project\r
- 2. Copy the `adm-ctrl-xapp` binary to `./test/docker/xapp.build` folder. Enter the folder and issue `docker build .`. Tag the recently created docker image and push it to the common registry.\r
- 3. Copy the `test-tx` binary to `./test/docker/xapp-tx.build` folder. Enter the folder and issue `docker build .`. Tag the recently created docker image and push it to the common registry.\r
- 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.\r
- 5. Modify the 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.\r
- 6. [Compile](#compiling-code) and [Install routing manager](#installing-routing-manager)\r
-\r
-#### Command line arguments\r
-Routing manager binary can be called with `-h` flag when it displays the available command line arguments and it's default value.\r
-\r
-Example:\r
-\r
-```bash\r
-root@a3684ff4cdb0:/# ./rtmgr -h\r
-Usage of ./rtmgr:\r
- -loglevel string\r
- INFO | WARN | ERROR | DEBUG (default "INFO")\r
- -nbi-httpget string\r
- xApp Manager URL (default "http://localhost:3000/xapps")\r
- -rpe string\r
- Policy Engine Module name (default "rmr")\r
- -sbi-nngsub string\r
- NNG Subsciption Socket URI (default "tcp://0.0.0.0:4560")\r
- -sdl-file string\r
- Local file store location (default "/db/rt.json")\r
-```\r
-\r
-For troubleshooting purpose the default logging level can be increased to `DEBUG`.\r
-\r
-## Upcoming changes\r
-[] Add RESTful NBI based on swagger api definition\r
-\r
-[] Support RMR Pipeline\r
-\r
-[] Add unit tests\r
-\r
-## License\r
-This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE)\r
-\r
+# Routing Manager
+
+## Table of contents
+* [Introduction](#introduction)
+* [Release notes](#release-notes)
+* [Prerequisites](#prerequisites)
+* [Project folders structure](#project-folders-structure)
+* [Installation guide](#installation-guide)
+ * [Compiling code](#compiling-code)
+ * [Building docker container](#building-docker-container)
+ * [Installing Routing Manager](#installing-routing-manager)
+ * [Testing and Troubleshoting](#testing-and-troubleshoting)
+* [Upcoming changes](#upcoming-changes)
+* [License](#license)
+
+## 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 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 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
+ * __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
+
+## Release notes
+Check the separated `RELNOTES` file.
+
+## Prerequisites
+* 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 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
+#### 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:** 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
+Tag the `rtmgr` container according to the project release and push it to a registry accessible from all minions of the Kubernetes cluster.
+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:
+ 1. `manifests/namespace.yaml`: creates the `example` namespace for routing-manager resources
+ 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: `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.
+
+Example:
+
+```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 | 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
+ Southbound interface module to be used. Valid values are: 'nngpush | nngpub' (default "nngpush")
+ -sbi-if string
+ IPv4 address of interface where Southbound socket to be opened (default "0.0.0.0")
+ -sdl 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`. (by hand launch it's set to INFO, kubernetes manifest has DEBUG set by default).
+
+## Upcoming changes
+[] 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