RIC:1060: Change in PTL

[ric-plt/rtmgr.git] / README.md

diff --git a/README.md b/README.md
index 2cc2000..fd79b22 100644 (file)
--- 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.
 
 ## 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
 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
 
 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:
 * 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
   * (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
 
 ## 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
 
 ## 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)
 * /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
 
 ## 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
 
 ### 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 
 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
   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 and Troubleshoting

+### Testing with Kubernetes

 Routing Manager's behaviour can be tested using the mocked xApp Manager, traffic generator xApp and receiver xApp.
 
 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)
   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.
 
 #### 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:
 
 ```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
   -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
   -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")
         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
 
 ## Upcoming changes

-[] Add RESTful NBI based on swagger api definition
-

 [] Add unit tests
 
 [] Add unit tests
 

+

 ## License
 This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE)
 
 ## License
 This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE)