I release step 2 of 2
[ric-plt/rtmgr.git] / 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