X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=README.md;h=fd79b2285590859e292662ddbfb8f71423527ec3;hb=HEAD;hp=41a767d7c41d1a73b57f4ef4a6e902783536c8aa;hpb=871fa393844ce1b61b8d5218d27687d9fc05803a;p=ric-plt%2Frtmgr.git diff --git a/README.md b/README.md index 41a767d..fd79b22 100644 --- a/README.md +++ b/README.md @@ -1,114 +1,168 @@ -# 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 serive 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 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 -* Controll Logic (__RTMGR__): Controls the operatin 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 -* 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 - * (WIP) __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 - -## Project folder structure -* /api: contains swagger source files -* /build: contains build tools (scripts, Dockerfiles, etc.) -* /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) - -## 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` -**NOTE:** The script puts a copy of the binary into the `./bin` folder for further use cases - -### Installing Routing Manager -#### Preparing environment -Re-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/namespaces.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 - -### Testing and Troubleshoting -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 - 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. - 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. - 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 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) - -#### 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 -root@a3684ff4cdb0:/# ./rtmgr -h -Usage of ./rtmgr: - -loglevel string - INFO | WARN | ERROR | DEBUG (default "INFO") - -nbi-httpget string - xApp Manager URL (default "http://localhost:3000/xapps") - -rpe string - Policy Engine Module name (default "rmr") - -sbi-nngsub string - NNG Subsciption Socket URI (default "tcp://0.0.0.0:4560") - -sdl-file string - Local file store location (default "/db/rt.json") -``` - -For troubleshooting purpose the default logging level can be increased to `DEBUG`. - -## Upcoming changes -[] Add RESTful NBI based on swagger api definition - -[] Support RMR Pipeline - -[] Add unit tests - -## License -This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE) - +# 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) +