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 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.
  20 The architecture consists of the following five well defined functions:
  21 * NorthBound Interface (__NBI__): Maintains the communication channels towards RIC manager components
  22 * Routing Policy Engine (__RPE__): Provides the logic to calculate routing policies
  23 * Shared Data Layer (__SDL__): Provides access to different kind persistent data stores
  24 * SouthBound Interface (__SBI__): Maintains the communication channels towards RIC tenants and control components
  25 * Control Logic (__RTMGR__): Controls the operatin of above functions
  26
  27 Current implementation provides support for the followings:
  28 * NBI:
  29   * __httpGet__: simple HTTP GET interface. Expects an URL where it gets the xApps' list in JSON format
  30   * (WIP) __httRESTful__: provides REST API endpoints towards RIC manager components
  31 * RPE:
  32   * __rmr__: creates routing policies formatted for RIC RMR
  33 * SDL:
  34   * __file__: stores xApp data in container's local filesystem (or in a mountpoint)
  35   * (backlog) __sdl__: Shared Data Library to Redis database
  36 * SBI:
  37   * __nngpub__: distributes RPE created policies via NNG Pub channel
  38   * (WIP) __nngpipe__: distributes RPE created policies via NNG Pipeline channel
  39
  40 ## Release notes
  41 Check the separated `RELNOTES` file.
  42
  43 ## Prerequisites
  44 * Healthy kubernetes cluster
  45 * Access to the common docker registry
  46
  47 ## Project folder structure
  48 * /api: contains Swagger source files
  49 * /build: contains build tools (scripts, Dockerfiles, etc.)
  50 * /manifest: contains deployment files (Kubernetes manifests, Helm chart)
  51 * /cmd: contains go project's main file
  52 * /pkg: contains go project's internal packages
  53 * /test: contains CI/CD testing files (scripts, mocks, manifests)
  54
  55 ## Installation guide
  56
  57 ### Compiling code
  58 Enter the project root and execute `./build.sh` script.
  59 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`
  60
  61 **NOTE:** The script puts a copy of the binary into the `./bin` folder for further use cases
  62
  63 ### Installing Routing Manager
  64 #### Preparing environment
  65 Tag the `rtmgr` container according to the project release and push it to a registry accessible from all minions of the Kubernetes cluster.
  66 Edit the container image section of `rtmgr-dep.yaml` file according to the `rtmgr` image tag.
  67
  68 #### Deploying Routing Manager
  69 Issue the `kubectl create -f {manifest.yaml}` command in the following order
  70   1. `manifests/namespace.yaml`: creates the `example` namespace for routing-manager resources
  71   2. `manifests/rtmgr/rtmgr-dep.yaml`: instantiates the `rtmgr` deployment in the `example` namespace
  72   3. `manifests/rtmgr/rtmgr-svc.yaml`: creates the `rtmgr` service in `example` namespace
  73
  74 ### Testing and Troubleshoting
  75 Routing Manager's behaviour can be tested using the mocked xApp Manager, traffic generator xApp and receiver xApp.
  76
  77   1. Checkout and compile both xApp receiver and xApp Tx generator of RIC admission control project
  78   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.
  79   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.
  80   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.
  81   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.
  82   6. [Compile](#compiling-code) and [Install routing manager](#installing-routing-manager)
  83
  84 #### Command line arguments
  85 Routing manager binary can be called with `-h` flag when it displays the available command line arguments and it's default value.
  86
  87 Example:
  88
  89 ```bash
  90 Usage of ./rtmgr:
  91   -filename string
  92         Absolute path of file where the route information to be stored (default "/db/rt.json")
  93   -loglevel string
  94         INFO | WARN | ERROR | DEBUG (default "INFO")
  95   -nbi string
  96         Northbound interface module to be used. Valid values are: 'httpGetter' (default "httpGetter")
  97   -rpe string
  98         Route Policy Engine to be used. Valid values are: 'rmrpush | rmrpub' (default "rmrpush")
  99   -sbi string
 100         Southbound interface module to be used. Valid values are: 'nngpush | nngpub' (default "nngpush")
 101   -sbi-if string
 102         IPv4 address of interface where Southbound socket to be opened (default "0.0.0.0")
 103   -sdl string
 104         Datastore enginge to be used. Valid values are: 'file' (default "file")
 105   -xm-url string
 106         HTTP URL where xApp Manager exposes the entire xApp List (default "http://localhost:3000/xapps")
 107 ```
 108
 109 For troubleshooting purpose the default logging level can be increased to `DEBUG`.
 110
 111 ## Upcoming changes
 112 [] Add RESTful NBI based on swagger api definition
 113
 114 [] Add unit tests
 115
 116 ## License
 117 This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE)
 118