From: wahidw Date: Tue, 12 Nov 2019 12:59:05 +0000 (+0000) Subject: Added docs folder X-Git-Tag: 0.3.9~3 X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=d909bf02dce0e0325ee25d612cf989f3aa59b45b;p=ric-plt%2Frtmgr.git Added docs folder Change-Id: I35f9e646d1d230f6674f6e07d682d75621630cc5 Signed-off-by: wahidw --- diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..3797dc8 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,20 @@ +--- +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details +# Required +version: 2 + +formats: + - htmlzip + +build: + image: latest + +python: + version: 3.7 + install: + - requirements: docs/requirements-docs.txt + +sphinx: + configuration: docs/conf.py diff --git a/container-tag.yaml b/container-tag.yaml index 18dcc3b..14c7346 100644 --- a/container-tag.yaml +++ b/container-tag.yaml @@ -2,4 +2,4 @@ # By default this file is in the docker build directory, # but the location can configured in the JJB template. --- -tag: 0.3.7 +tag: 0.3.8 diff --git a/docs/_static/logo.png b/docs/_static/logo.png new file mode 100644 index 0000000..c3b6ce5 Binary files /dev/null and b/docs/_static/logo.png differ diff --git a/docs/api-docs.rst b/docs/api-docs.rst new file mode 100644 index 0000000..882f99a --- /dev/null +++ b/docs/api-docs.rst @@ -0,0 +1,42 @@ +.. Copyright (c) 2019 AT&T Intellectual Property. +.. Copyright (c) 2019 Nokia. +.. +.. Licensed under the Creative Commons Attribution 4.0 International +.. Public License (the "License"); you may not use this file except +.. in compliance with the License. You may obtain a copy of the License at +.. +.. https://creativecommons.org/licenses/by/4.0/ +.. +.. Unless required by applicable law or agreed to in writing, documentation +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. + + +API-Docs +======== + +This is the API-docs of ROUTING MANAGER + +.. contents:: + :depth: 3 + :local: + +.. note + +.. This section is used to describe a software API exposed from a O-RAN software component. + +.. This note must be removed after content has been added. + + +API Introduction +----------------- +.. Please add what API a component have exposed. + +API Functions +------------- +.. Please states the API functions. + diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..e59789c --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,30 @@ +#================================================================================== +# Copyright (c) 2019 AT&T Intellectual Property. +# Copyright (c) 2019 Nokia +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#================================================================================== +from docs_conf.conf import * + +branch = 'latest' + +linkcheck_ignore = [ + 'http://localhost', + 'http://127.0.0.1.*', + 'https://gerrit.o-ran-sc.org.*', + 'https://github.com.*', + 'https://docs.docker.com.*', + 'http://rtmgr*' +] +#intersphinx_mapping = {} +#intersphinx_mapping['ric-plt-rtmgr'] = ('https://o-ran-sc-doc.readthedocs.io/projects/o-ran-sc-ric-plt-rtmgr/en/%s' % branch, None ) diff --git a/docs/conf.yaml b/docs/conf.yaml new file mode 100644 index 0000000..349b100 --- /dev/null +++ b/docs/conf.yaml @@ -0,0 +1,19 @@ +--- +#================================================================================== +# Copyright (c) 2019 AT&T Intellectual Property. +# Copyright (c) 2019 Nokia +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +#================================================================================== +project_cfg: oran +project: ric-plt-rtmgr diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst new file mode 100644 index 0000000..749b236 --- /dev/null +++ b/docs/developer-guide.rst @@ -0,0 +1,98 @@ +.. +.. Copyright (c) 2019 AT&T Intellectual Property. +.. Copyright (c) 2019 Nokia. +.. +.. Licensed under the Creative Commons Attribution 4.0 International +.. Public License (the "License"); you may not use this file except +.. in compliance with the License. You may obtain a copy of the License at +.. +.. https://creativecommons.org/licenses/by/4.0/ +.. +.. Unless required by applicable law or agreed to in writing, documentation +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. + +Developer-Guide +=============== + +.. contents:: + :depth: 3 + :local: + +Overview +-------- +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. + +Architecture +------------ +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 + + +Installing Routing Manager +-------------------------- +* 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 Troubleshooting +--------------------------- +Testing with Kubernetes +----------------------- +Routing Manager's behaviour can be tested using the mocked xApp Manager, traffic generator xApp and receiver xApp. + +* 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` + +* 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. + +* 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. + +* Enter the `./test/docker/xmgr.build` folder and issue `docker build .`. Tag the recently created docker image and push it to the common registry. + +* 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. + +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. + +* 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: + + 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.html + + +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). diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 0000000..00b0fd0 Binary files /dev/null and b/docs/favicon.ico differ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..f8ac6da --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,38 @@ +.. +.. Copyright (c) 2019 AT&T Intellectual Property. +.. Copyright (c) 2019 Nokia. +.. +.. Licensed under the Creative Commons Attribution 4.0 International +.. Public License (the "License"); you may not use this file except +.. in compliance with the License. You may obtain a copy of the License at +.. +.. https://creativecommons.org/licenses/by/4.0/ +.. +.. Unless required by applicable law or agreed to in writing, documentation +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. + +.. _ric-plt-rtmgr: + +Welcome to O-RAN SC Routing Manager +=================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + installation-guide.rst + developer-guide.rst + release-notes.rst + api-docs.rst + +.. * :doc:`RIC Dashboard ` + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/installation-guide.rst b/docs/installation-guide.rst new file mode 100644 index 0000000..25ed53f --- /dev/null +++ b/docs/installation-guide.rst @@ -0,0 +1,107 @@ +.. +.. Copyright (c) 2019 AT&T Intellectual Property. +.. Copyright (c) 2019 Nokia. +.. +.. Licensed under the Creative Commons Attribution 4.0 International +.. Public License (the "License"); you may not use this file except +.. in compliance with the License. You may obtain a copy of the License at +.. +.. https://creativecommons.org/licenses/by/4.0/ +.. +.. Unless required by applicable law or agreed to in writing, documentation +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. + + + +Installation Guide +================== + +.. contents:: + :depth: 3 + :local: + +Abstract +-------- + +This document describes how to install ric-plt/rtmgr, it's dependencies and required system resources. + +Introduction +------------ +Routing Manager is a basic platform service of RIC. It is responsible for distributing routing policies among the other platform components and xApps. + +Pre-requisites +-------------- +* 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) + +Software Installation and Deployment +------------------------------------ +This section describes the installation of the ric-plt/rtmgr installation. + +Docker Image +------------ +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) + +Linux Binary +------------ +* 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): + + * 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: +assuming that you stand in project root dir + + rm -rf appmgr vendor pkg/appmgr_* pkg/models pkg/restapi + +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: + +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") + diff --git a/docs/release-notes.rst b/docs/release-notes.rst new file mode 100644 index 0000000..83bd289 --- /dev/null +++ b/docs/release-notes.rst @@ -0,0 +1,69 @@ +.. +.. Copyright (c) 2019 AT&T Intellectual Property. +.. Copyright (c) 2019 Nokia. +.. +.. Licensed under the Creative Commons Attribution 4.0 International +.. Public License (the "License"); you may not use this file except +.. in compliance with the License. You may obtain a copy of the License at +.. +.. https://creativecommons.org/licenses/by/4.0/ +.. +.. Unless required by applicable law or agreed to in writing, documentation +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. + + +Release-Notes +============= + + +This document provides the release notes for O-RAN SC Amber Release of ric-plt/rtmgr. + +.. contents:: + :depth: 3 + :local: + +Version history +--------------- + +Version 1.0.0, November 12, 2019 +-------------------------------- +* Populates the RMR routing table between the RIC platform component pairs E2Term,Subscription Manager and E2Term,E2Manager +* Queries xAppManager for the deployed xApps and populates the RMR routing table between the xApps,Subscription Manager +* Populates routes based on the subscription ID between xApps,Subscription Manager + +Components +---------- +* /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) + +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 + + +Limitations +----------- diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt new file mode 100644 index 0000000..09a0c1c --- /dev/null +++ b/docs/requirements-docs.txt @@ -0,0 +1,5 @@ +sphinx +sphinx-rtd-theme +sphinxcontrib-httpdomain +recommonmark +lfdocs-conf diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..a2250a7 --- /dev/null +++ b/tox.ini @@ -0,0 +1,32 @@ +[tox] +minversion = 2.0 +envlist = + docs, + docs-linkcheck, + +skipsdist = true + +[testenv:docs] +basepython = python3 +deps = + sphinx + sphinx-rtd-theme + sphinxcontrib-httpdomain + recommonmark + lfdocs-conf + +commands = + sphinx-build -W -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html + + echo "Generated docs available in {toxinidir}/docs/_build/html" + +whitelist_externals = echo + +[testenv:docs-linkcheck] +basepython = python3 +deps = sphinx + sphinx-rtd-theme + sphinxcontrib-httpdomain + recommonmark + lfdocs-conf +commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck