From: maximesson Date: Thu, 31 Oct 2019 12:26:13 +0000 (+0100) Subject: Documentation Non-RT RIC X-Git-Tag: 1.7.3~17^2 X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=e6b4d27d99570c34271d3176c6969bc5bc46a039;p=nonrtric.git Documentation Non-RT RIC Change-Id: Ic873bca6ac86556f3e0f057358c88bc24a693151 Issue-ID: NONRTRIC-47 Signed-off-by: maximesson --- diff --git a/.gitignore b/.gitignore index 9f11b755..c1089daf 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,4 @@ +# Documentation .idea/ +.tox +docs/_build/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..b45b11d2 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,16 @@ +--- +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/docs/.project b/docs/.project new file mode 100644 index 00000000..e248a4fa --- /dev/null +++ b/docs/.project @@ -0,0 +1,11 @@ + + + docs + + + + + + + + diff --git a/docs/_static/logo.png b/docs/_static/logo.png new file mode 100644 index 00000000..c3b6ce56 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 00000000..a2964601 --- /dev/null +++ b/docs/api-docs.rst @@ -0,0 +1,51 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + + + +API-Docs +======== + +This is the API-docs of Non-RT RIC. + +.. contents:: + :depth: 3 + :local: + +API Introduction +----------------- + +The Non-RT RIC dashboard is an interface that allows human users to create, edit and delete policy instances, for each existing policy type. The policy types are owned by the Near-RT RIC, Non-RT RIC can just query them, so it's not possible to act on them. + + +API Functions +------------- + +To run the dashboard locally, you can follow these steps: + +- Fetch the latest code from `gerrit`_ + +.. _gerrit: https://gerrit.nordix.org/c/oransc/nonrtric/+/2747/ + +- Before compiling, run the following commands:: + + git submodule init + + git submodule update + +- Start the backend (you might have to build it first):: + + mvn clean install + + mvn -Dorg.oransc.ric.portal.dashboard=mock -Dtest=DashboardTestServer -DfailIfNoTests=false test + + +- Now you can open URL: `localhost:8080`_ in a browser. + +.. _localhost:8080: localhost:8080 + +From the main page, click on the "Policy Control" card. From here, it is possible to create or list instances for each existing policy type. + +When the instances are listed, it is possible to edit or delete each instance from the expanded view. + +.. image:: ./images/non-RT_RIC_dashboard.png \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..922e22fb --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,6 @@ +from docs_conf.conf import * +linkcheck_ignore = [ + 'http://localhost.*', + 'http://127.0.0.1.*', + 'https://gerrit.o-ran-sc.org.*' +] diff --git a/docs/conf.yaml b/docs/conf.yaml new file mode 100644 index 00000000..7235ba1d --- /dev/null +++ b/docs/conf.yaml @@ -0,0 +1,3 @@ +--- +project_cfg: oran +project: nonrtric diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst index 94044d04..36ac802d 100644 --- a/docs/developer-guide.rst +++ b/docs/developer-guide.rst @@ -20,8 +20,9 @@ A1 Mediation: 1. SDNC Controller 2. Near-RT RIC Simulator +********************************** SDNC A1 Controller Developer Guide -================================== +********************************** This document provides a quickstart for developers of the O-RAN SC A1 Controller SDNC Application @@ -41,6 +42,7 @@ This will build the project and create artifcats in maven repo Go to oam/installation directory and run this command :: mvn clean install -P docker + This will create the docker images required for sdnc After this step check for the docker images created by the maven build with this command :: @@ -55,10 +57,11 @@ This will create the docker containers with the sdnc image, you can check the st The SDNC url to access the Northbound API, http://localhost:8282/apidoc/explorer/index.html -Credentails: admin/Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U +Credentials: admin/Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U +************************************* Near-RT RIC Simulator Developer Guide -===================================== +************************************* Prerequisites ------------- @@ -79,3 +82,11 @@ The backend server listens for requests at this URL: The backend server publishes live API documentation at the URL http://localhost:8080/swagger-ui.html + +*************** +End-to-end call +*************** + +In order to make a complete end-to-end call, follow the instructions given in this `guide`_. + +.. _guide: https://wiki.o-ran-sc.org/pages/viewpage.action?pageId=12157166 \ No newline at end of file diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 00000000..00b0fd0e Binary files /dev/null and b/docs/favicon.ico differ diff --git a/docs/images/architecture.png b/docs/images/architecture.png new file mode 100644 index 00000000..ed118383 Binary files /dev/null and b/docs/images/architecture.png differ diff --git a/docs/images/non-RT_RIC_dashboard.png b/docs/images/non-RT_RIC_dashboard.png new file mode 100644 index 00000000..b69ba4da Binary files /dev/null and b/docs/images/non-RT_RIC_dashboard.png differ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..3f421d33 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,23 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 + + +Non-RT RIC +========== + +.. Add or remove sections below as appropriate for the platform component. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + ./api-docs.rst + ./developer-guide.rst + ./installation-guide.rst + ./overview.rst + ./release-notes.rst + + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` \ No newline at end of file diff --git a/docs/installation-guide.rst b/docs/installation-guide.rst new file mode 100644 index 00000000..f78a5eec --- /dev/null +++ b/docs/installation-guide.rst @@ -0,0 +1,109 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + + + +Installation Guide +================== + +.. contents:: + :depth: 3 + :local: + +Abstract +-------- + +This document describes how to install the Non-RT RIC dashboard, its dependencies and required system resources. + + +Version history + ++--------------------+--------------------+--------------------+--------------------+ +| **Date** | **Ver.** | **Author** | **Comment** | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| 20XX-XX-XX | 0.1.0 | | First draft | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| | 0.1.1 | | | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| | 1.0 | | | +| | | | | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ + + +Introduction +------------ + +.. + +.: + +This document describes the supported software and hardware configurations for the reference component as well as providing guidelines on how to install and configure such reference system. + +The audience of this document is assumed to have good knowledge in RAN network and Linux system. + + +Preface +------- +.. + +: + +Before starting the installation of , some planning must precede. + +.. note:any preperation you need before setting up sotfware and hardware + + +Hardware Requirements +--------------------- +.. + +: + +Following minimum hardware requirements must be met for installation of : + ++--------------------+----------------------------------------------------+ +| **HW Aspect** | **Requirement** | +| | | ++--------------------+----------------------------------------------------+ +| **# of servers** | | ++--------------------+----------------------------------------------------+ +| **CPU** | | +| | | ++--------------------+----------------------------------------------------+ +| **RAM** | | +| | | ++--------------------+----------------------------------------------------+ +| **Disk** | | +| | | ++--------------------+----------------------------------------------------+ +| **NICs** | | +| | | +| | | +| | | +| | | +| | | ++--------------------+----------------------------------------------------+ + + + +Software Installation and Deployment +------------------------------------ +.. + +: + +This section describes the installation of the installation on the reference hardware. + + + +References +---------- +.. + + + + diff --git a/docs/overview.rst b/docs/overview.rst new file mode 100644 index 00000000..8c2e8161 --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,72 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 + + +..please write your project overview +..please delete this content after editing + + +Non-RT RIC Overview +=================== + +Find detailed description of what Non-RT RIC is on this `page`_. + +.. _page: https://wiki.o-ran-sc.org/display/RICNR/ + +A-release architecture +---------------------- + +The architecture is as shown on the following picture: + +.. image:: ./images/architecture.png + :scale: 50 % + +The A1 controller is located in SDNC, an ONAP component. It communicates with ORAN via the A1 interface with the Near-RT RIC simulator. + +On the other end, it is accessible via a dashboard, that allows to interact with policies. The dashboard itself is split into the backend and the frontend, and can be deployed following the instructions on the `human interfaces page`_. + +.. _human interfaces page: ./human-interfaces.html + +Requirements for the Non-RT RIC project +--------------------------------------- + +There are functional requirements emitted by O-RAN WG2 for the Non-RT RIC, which are the following: + +1. Non-RT RIC shall support data retrieval and analysis; the data may include performance, configuration or other data related to the application (recommended data shown in required data section for different use cases). +2. Non-RT RIC shall support relevant AI/ML model training based on the data in 1. for non-real-time optimization of configuration parameters in RAN or Near-RT RIC, as applicable for the use case. +3. Non-RT RIC shall support relevant AI/ML model training based on the data in 1. for generating/optimizing policies and intents to guide the behavior of applications in Near-RT RIC or RAN, as applicable for the use case. +4. Non-RT RIC shall support training of relevant AI/ML models based on the data in 1. to be deployed/updated in Near-RT RIC as required by the applications. +5. Non-RT RIC shall support performance monitoring and evaluation. +6. Non-RT RIC shall support a fallback mechanism to prevent drastic degradation/fluctuation of performance, e.g. to restore to the previous policy or configuration. + +The non-functional requirements are the following ones: + +1. Non-RT RIC shall not update the same policy or configuration parameter for a given near-RT RIC or RAN function more often than once per second. +2. Non-RT RIC shall be able to update policies in several near-RT RICs. + +Moreover, there are functional requirements regarding the A1 interface: + +1. A1 interface shall support communication of policies/intents from Non-RT RIC to Near-RT RIC. +2. A1 interface shall support AI/ML model deployment and update from Non-RT RIC to Near-RT RIC. +3. A1 interface shall support communication of enrichment information from Non-RT RIC to Near-RT RIC. +4. A1 interface shall support feedback from Near-RT RIC for monitoring AI/ML model performance. +5. A1 interface shall support the policy/intents feedback from Near-RT RIC to Non-RT RIC. + +A1 policy procedure +------------------- + +As for A-release, the methods are as follows: + ++---------------------+--------------------------+--------------------------+ +| A1 policy procedure | Single policy method | Multiple policies method | ++---------------------+--------------------------+--------------------------+ +| Create policy | PUT | | ++---------------------+--------------------------+--------------------------+ +| Query policy | GET | GET (sequence of \*) | ++---------------------+--------------------------+--------------------------+ +| Update policy | PUT | | ++---------------------+--------------------------+--------------------------+ +| Delete policy | DELETE | | ++---------------------+--------------------------+--------------------------+ +| Notify policy | POST | POST | ++---------------------+--------------------------+--------------------------+ \ No newline at end of file diff --git a/docs/release-notes.rst b/docs/release-notes.rst new file mode 100644 index 00000000..0359af41 --- /dev/null +++ b/docs/release-notes.rst @@ -0,0 +1,169 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + + +Release-Notes +============= + + +This document provides the release notes for of . + +.. contents:: + :depth: 3 + :local: + + +Version history +--------------- + ++--------------------+--------------------+--------------------+--------------------+ +| **Date** | **Ver.** | **Author** | **Comment** | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| 20XX-XX-XX | 0.1.0 | | First draft | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| | 0.1.1 | | | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| | 1.0 | | | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ + + +Summary +------- + + + + + + +Release Data +------------ + + +: + ++--------------------------------------+--------------------------------------+ +| **Project** | E.g. project | +| | | ++--------------------------------------+--------------------------------------+ +| **Repo/commit-ID** | E.g. genesis/adf634a0d4..... | +| | | ++--------------------------------------+--------------------------------------+ +| **Release designation** | E.g. Arno RC2 | +| | | ++--------------------------------------+--------------------------------------+ +| **Release date** | E.g. 2015-04-16 | +| | | ++--------------------------------------+--------------------------------------+ +| **Purpose of the delivery** | | +| | | ++--------------------------------------+--------------------------------------+ + + + + +Feature Additions +^^^^^^^^^^^^^^^^^ + + +: + +**JIRA BACK-LOG:** + ++--------------------------------------+--------------------------------------+ +| **JIRA REFERENCE** | **SLOGAN** | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ + +Bug Corrections +^^^^^^^^^^^^^^^ + +**JIRA TICKETS:** + ++--------------------------------------+--------------------------------------+ +| **JIRA REFERENCE** | **SLOGAN** | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ + +Deliverables +^^^^^^^^^^^^ + +Software Deliverables ++++++++++++++++++++++ + + + + + +Documentation Deliverables +++++++++++++++++++++++++++ + + + + + + +Known Limitations, Issues and Workarounds +----------------------------------------- + +System Limitations +^^^^^^^^^^^^^^^^^^ + + + + +Known Issues +^^^^^^^^^^^^ + + +: + +**JIRA TICKETS:** + ++--------------------------------------+--------------------------------------+ +| **JIRA REFERENCE** | **SLOGAN** | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ + +Workarounds +^^^^^^^^^^^ + + + + + + +References +---------- + + + + + diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt new file mode 100644 index 00000000..09a0c1cb --- /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 00000000..c86cfdf3 --- /dev/null +++ b/tox.ini @@ -0,0 +1,30 @@ +# documentation only +[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