From: wahidw Date: Mon, 24 Feb 2020 06:11:47 +0000 (+0000) Subject: Adding documentation to repo X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=7b43586eb054bfdebde4d140959cb8cabea13665;p=ric-plt%2Fric-dep.git Adding documentation to repo Change-Id: I79b18e9c8cc335389fc12b13b07e457650220486 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/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/conf.py b/docs/conf.py new file mode 100644 index 0000000..828b292 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,24 @@ +################################################################################ +# Copyright (c) 2019 AT&T Intellectual Property. # +# # +# 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 * +linkcheck_ignore = [ + 'http://localhost.*', + 'http://127.0.0.1.*', + 'https://gerrit.o-ran-sc.org.*' + 'https://gerrit.o-ran-sc.org/r/ric-plt/ric-dep' + 'https://o-ran-sc-doc.readthedocs.io/projects/o-ran-sc-ric-plt-dep/en/latest/index.html' + 'https://docs.o-ran-sc.org/projects/o-ran-sc-it-dep/en/latest/*' + ] diff --git a/docs/conf.yaml b/docs/conf.yaml new file mode 100644 index 0000000..432cc07 --- /dev/null +++ b/docs/conf.yaml @@ -0,0 +1,6 @@ +--- +project_cfg: oran +project: oran + +# Change this to ReleaseBranchName to modify the header +default-version: latest 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..8494c9f --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,30 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. ===============LICENSE_START======================================================= +.. Copyright (C) 2019 AT&T Intellectual Property +.. =================================================================================== +.. This documentation file is distributed under the Creative Commons Attribution +.. 4.0 International License (the "License"); you may not use this file except in +.. compliance with the License. You may obtain a copy of the License at +.. +.. http://creativecommons.org/licenses/by/4.0 +.. +.. This file 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. +.. ===============LICENSE_END========================================================= + + +.. Integration and Testing Documentation + +Integration and Testing of RIC Platform +======================================= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + overview + release-notes + installation-guides diff --git a/docs/installation-guides.rst b/docs/installation-guides.rst new file mode 100644 index 0000000..55330ed --- /dev/null +++ b/docs/installation-guides.rst @@ -0,0 +1,61 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. ===============LICENSE_START======================================================= +.. Copyright (C) 2019-2020 AT&T Intellectual Property +.. =================================================================================== +.. This documentation file is distributed under the Creative Commons Attribution +.. 4.0 International License (the "License"); you may not use this file except in +.. compliance with the License. You may obtain a copy of the License at +.. +.. http://creativecommons.org/licenses/by/4.0 +.. +.. This file 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. +.. ===============LICENSE_END========================================================= + +=================== +Installation Guides +=================== + +This document describes how to install the RIC components deployed by scripts and Helm charts +under the ric-plt/dep repository, including the dependencies and required system resources. + +.. contents:: + :depth: 3 + :local: + +Version history +=============== + ++--------------------+--------------------+--------------------+--------------------+ +| **Date** | **Ver.** | **Author** | **Comment** | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| 2020-02-29 | 0.1.0 |Abdulwahid W | | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ + + +Overview +======== + +This section explains the installation of Near Realtime RAN Intelligent Controller Platform only. + +Prerequisites +============= + +Refer to the following links to set up the pre-requisites + +VM installation - https://docs.o-ran-sc.org/projects/o-ran-sc-it-dep/en/latest/installation-guides.html#virtualbox-vms-as-installation-hosts + +k8s installation - https://docs.o-ran-sc.org/projects/o-ran-sc-it-dep/en/latest/installation-guides.html#one-node-kubernetes-cluster + + +Installing Near Realtime RIC in RIC Cluster +=========================================== + +After the Kubernetes cluster is installed, the next step is to install the (Near Realtime) RIC Platform. + +.. include:: ./installation-ric.rst diff --git a/docs/installation-ric.rst b/docs/installation-ric.rst new file mode 100644 index 0000000..7b5c177 --- /dev/null +++ b/docs/installation-ric.rst @@ -0,0 +1,203 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. ===============LICENSE_START======================================================= +.. Copyright (C) 2019-2020 AT&T Intellectual Property +.. =================================================================================== +.. This documentation file is distributed under the Creative Commons Attribution +.. 4.0 International License (the "License"); you may not use this file except in +.. compliance with the License. You may obtain a copy of the License at +.. +.. http://creativecommons.org/licenses/by/4.0 +.. +.. This file 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. +.. ===============LICENSE_END========================================================= + + +Getting and Preparing Deployment Scripts +---------------------------------------- + +Clone the ric-plt/dep git repository that has deployment scripts and support files on the target VM. + +:: + + % git clone "https://gerrit.o-ran-sc.org/r/ric-plt/ric-dep" + + +.. code:: bash + + git clone "https://gerrit.o-ran-sc.org/r/ric-plt/ric-dep" + +Modify the deployment recipe +---------------------------- + +Edit the recipe files ./RECIPE_EXAMPLE/example_recipe.yaml. + +.. code:: bash + + extsvcplt: + ricip: "" + auxip: "" + +- To specify which version of the RIC platform components will be deployed, update the RIC platform component container tags in their corresponding section. +- You can specify which docker registry will be used for each component. If the docker registry requires login credential, you can add the credential in the following section. Please note that the installation suite has already included credentials for O-RAN Linux Foundation docker registries. Please do not create duplicate entries. + +.. code:: bash + + docker-credential: + enabled: true + credential: + SOME_KEY_NAME: + registry: "" + credential: + user: "" + password: "" + email: "" + +For more advanced recipe configuration options, please refer to the recipe configuration guideline. + + +Deploying the Infrastructure and Platform Groups +------------------------------------------------ + +Copy the ric-common helm charts for it/dep, configure the helm repo and start local helm server + +.. code:: bash + + git clone "https://gerrit.o-ran-sc.org/r/it/dep" + HELM_HOME=$(helm home) + COMMON_CHART_VERSION=$(cat dep/ric-common/Common-Template/helm/ric-common/Chart.yaml | grep version | awk '{print $2}') + helm package -d /tmp dep/ric-common/Common-Template/helm/ric-common + cp /tmp/ric-common-$COMMON_CHART_VERSION.tgz $HELM_HOME/repository/local/ + helm repo index $HELM_HOME/repository/local/ + helm serve >& /dev/null & + helm repo remove local + helm repo add local http://127.0.0.1:8879/charts + + +After the recipes are edited and helm started, the Near Realtime RIC platform is ready to be deployed. + +.. code:: bash + + cd ric-dep/bin + ./install -f ../RECIPE_EXAMPLE/PLATFORM/example_recipe.yaml + + +Checking the Deployment Status +------------------------------ + +Now check the deployment status after a short wait. Results similar to the +output shown below indicate a complete and successful deployment. Check the +STATUS column from both kubectl outputs to ensure that all are either +"Completed" or "Running", and that none are "Error" or "ImagePullBackOff". + +.. code:: + + # helm list + NAME REVISION UPDATED STATUS CHART APP VERSION NAMESPACE + r3-a1mediator 1 Thu Jan 23 14:29:12 2020 DEPLOYED a1mediator-3.0.0 1.0 ricplt + r3-appmgr 1 Thu Jan 23 14:28:14 2020 DEPLOYED appmgr-3.0.0 1.0 ricplt + r3-dbaas1 1 Thu Jan 23 14:28:40 2020 DEPLOYED dbaas1-3.0.0 1.0 ricplt + r3-e2mgr 1 Thu Jan 23 14:28:52 2020 DEPLOYED e2mgr-3.0.0 1.0 ricplt + r3-e2term 1 Thu Jan 23 14:29:04 2020 DEPLOYED e2term-3.0.0 1.0 ricplt + r3-infrastructure 1 Thu Jan 23 14:28:02 2020 DEPLOYED infrastructure-3.0.0 1.0 ricplt + r3-jaegeradapter 1 Thu Jan 23 14:29:47 2020 DEPLOYED jaegeradapter-3.0.0 1.0 ricplt + r3-rsm 1 Thu Jan 23 14:29:39 2020 DEPLOYED rsm-3.0.0 1.0 ricplt + r3-rtmgr 1 Thu Jan 23 14:28:27 2020 DEPLOYED rtmgr-3.0.0 1.0 ricplt + r3-submgr 1 Thu Jan 23 14:29:23 2020 DEPLOYED submgr-3.0.0 1.0 ricplt + r3-vespamgr 1 Thu Jan 23 14:29:31 2020 DEPLOYED vespamgr-3.0.0 1.0 ricplt + + # kubectl get pods -n ricplt + NAME READY STATUS RESTARTS AGE + deployment-ricplt-a1mediator-69f6d68fb4-7trcl 1/1 Running 0 159m + deployment-ricplt-appmgr-845d85c989-qxd98 2/2 Running 0 160m + deployment-ricplt-dbaas-7c44fb4697-flplq 1/1 Running 0 159m + deployment-ricplt-e2mgr-569fb7588b-wrxrd 1/1 Running 0 159m + deployment-ricplt-e2term-alpha-db949d978-rnd2r 1/1 Running 0 159m + deployment-ricplt-jaegeradapter-585b4f8d69-tmx7c 1/1 Running 0 158m + deployment-ricplt-rsm-755f7c5c85-j7fgf 1/1 Running 0 158m + deployment-ricplt-rtmgr-c7cdb5b58-2tk4z 1/1 Running 0 160m + deployment-ricplt-submgr-5b4864dcd7-zwknw 1/1 Running 0 159m + deployment-ricplt-vespamgr-864f95c9c9-5wth4 1/1 Running 0 158m + r3-infrastructure-kong-68f5fd46dd-lpwvd 2/2 Running 3 160m + + # kubectl get pods -n ricinfra + NAME READY STATUS RESTARTS AGE + deployment-tiller-ricxapp-d4f98ff65-9q6nb 1/1 Running 0 163m + tiller-secret-generator-plpbf 0/1 Completed 0 163m + +Checking Container Health +------------------------- + +Check the health of the application manager platform component by querying it +via the ingress controller using the following command. + +.. code:: bash + + % curl -v http://localhost:32080/appmgr/ric/v1/health/ready + +The output should look as follows. + +.. code:: + + * Trying 10.0.2.100... + * TCP_NODELAY set + * Connected to 10.0.2.100 (10.0.2.100) port 32080 (#0) + > GET /appmgr/ric/v1/health/ready HTTP/1.1 + > Host: 10.0.2.100:32080 + > User-Agent: curl/7.58.0 + > Accept: */* + > + < HTTP/1.1 200 OK + < Content-Type: application/json + < Content-Length: 0 + < Connection: keep-alive + < Date: Wed, 22 Jan 2020 20:55:39 GMT + < X-Kong-Upstream-Latency: 0 + < X-Kong-Proxy-Latency: 2 + < Via: kong/1.3.1 + < + * Connection #0 to host 10.0.2.100 left intact + + +Undeploying the Infrastructure and Platform Groups +-------------------------------------------------- + +To undeploy all the containers, perform the following steps in a root shell +within the it-dep repository. + +.. code:: bash + + # cd bin + # ./uninstall + +Results similar to below indicate a complete and successful cleanup. + +.. code:: + + # ./undeploy-ric-platform + Undeploying RIC platform components [appmgr rtmgr dbaas1 e2mgr e2term a1mediator submgr vespamgr rsm jaegeradapter infrastructure] + release "r3-appmgr" deleted + release "r3-rtmgr" deleted + release "r3-dbaas1" deleted + release "r3-e2mgr" deleted + release "r3-e2term" deleted + release "r3-a1mediator" deleted + release "r3-submgr" deleted + release "r3-vespamgr" deleted + release "r3-rsm" deleted + release "r3-jaegeradapter" deleted + release "r3-infrastructure" deleted + configmap "ricplt-recipe" deleted + namespace "ricxapp" deleted + namespace "ricinfra" deleted + namespace "ricplt" deleted + + +Restarting the VM +----------------- + +After a reboot of the VM, and a suitable delay for initialization, +all the containers should be running again as shown above. diff --git a/docs/overview.rst b/docs/overview.rst new file mode 100644 index 0000000..ab75d57 --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,25 @@ +. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. ===============LICENSE_START======================================================= +.. Copyright (C) 2019 AT&T Intellectual Property +.. =================================================================================== +.. This documentation file is distributed under the Creative Commons Attribution +.. 4.0 International License (the "License"); you may not use this file except in +.. compliance with the License. You may obtain a copy of the License at +.. +.. http://creativecommons.org/licenses/by/4.0 +.. +.. This file 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. +.. ===============LICENSE_END========================================================= + +Overview +======== + +The ric-plt/dep repositoy hosts deployment and integration artifacts such as scripts, Helm charts, and other files used for deploying RIC Platform Software. + +For release this repo contains: + +- Deployment scripts and Helm charts for Near Realtime RAN Intelligent Controller Platform. diff --git a/docs/release-notes.rst b/docs/release-notes.rst new file mode 100644 index 0000000..1c01f64 --- /dev/null +++ b/docs/release-notes.rst @@ -0,0 +1,165 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. ===============LICENSE_START======================================================= +.. Copyright (C) 2019 AT&T Intellectual Property +.. =================================================================================== +.. This documentation file is distributed under the Creative Commons Attribution +.. 4.0 International License (the "License"); you may not use this file except in +.. compliance with the License. You may obtain a copy of the License at +.. +.. http://creativecommons.org/licenses/by/4.0 +.. +.. This file 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. +.. ===============LICENSE_END========================================================= + + +This document provides the release notes for of . + +.. contents:: + :depth: 3 + :local: + + +Release Notes +============= + +Version history +--------------- + ++--------------------+--------------------+--------------------+--------------------+ +| **Date** | **Ver.** | **Author** | **Comment** | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| 2020-02-20 | 0.1.0 | Abdul Wahid W | First draft | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ + + +Summary +------- + +The ric-plt/dep repositoy hosts deployment and integration artifacts such as scripts, Helm charts, and other files used for deploying RIC Platform Software. + +For release this repo contains: + +- Deployment scripts and Helm charts for Near Realtime RAN Intelligent Controller Platform. + + +Release Data +------------ + ++--------------------------------------+--------------------------------------+ +| **Project** | Integration and Testing | +| | | ++--------------------------------------+--------------------------------------+ +| **Repo/commit-ID** | ric-plt/dep | +| | | ++--------------------------------------+--------------------------------------+ +| **Release designation** | Bronze | +| | | ++--------------------------------------+--------------------------------------+ +| **Release date** | 2020-02-29 | +| | | ++--------------------------------------+--------------------------------------+ +| **Purpose of the delivery** | First release | +| | | ++--------------------------------------+--------------------------------------+ + + + + +Feature additions +------------------- + +**JIRA BACK-LOG:** + ++--------------------------------------+--------------------------------------+ +| **JIRA REFERENCE** | **SLOGAN** | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ + +Bug corrections +---------------- + +**JIRA TICKETS:** + ++--------------------------------------+--------------------------------------+ +| **JIRA REFERENCE** | **SLOGAN** | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ + +Deliverables +------------- + + + +Software deliverables +--------------------- + + + +Documentation deliverables +--------------------------- + +Documentation for installing, using, and developing for Integration and Testing project can be found at: + +:: + +% https://o-ran-sc-doc.readthedocs.io/projects/o-ran-sc-ric-plt-dep/en/latest/index.html + +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 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..db50ddf --- /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