X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;ds=sidebyside;f=README.md;h=fd79b2285590859e292662ddbfb8f71423527ec3;hb=HEAD;hp=2cc200054882790cb6e5eff913c777ce73672fbd;hpb=16d84d6f7d3489e65e0a83ba9c0d5d62c3914c7f;p=ric-plt%2Frtmgr.git

diff --git a/README.md b/README.md
index 2cc2000..fd79b22 100644
--- a/README.md
+++ b/README.md
@@ -16,18 +16,22 @@
 ## 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:
@@ -35,30 +39,55 @@ Current implementation provides support for the followings:
   * (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
@@ -66,20 +95,37 @@ Tag the `rtmgr` container according to the project release and push it to a regi
 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.
@@ -88,12 +134,16 @@ 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' (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
@@ -104,15 +154,15 @@ Usage of ./rtmgr:
         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)