From: Bin Yang Date: Mon, 20 Dec 2021 03:14:13 +0000 (+0800) Subject: Add docs for pti o2 service X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=0daf5c4f160ec3fde4eb849fbd59ff75eff8e76c;p=pti%2Fo2.git Add docs for pti o2 service Issue-ID: INF-247 Signed-off-by: Bin Yang Change-Id: I5b51753c9a12a1848bfbf02c7be262d913b58dac (cherry picked from commit 82ae293db69b560751856f925ccf0a7f58a184d9) --- diff --git a/.gitignore b/.gitignore index 91ffe40..669448b 100644 --- a/.gitignore +++ b/.gitignore @@ -5,4 +5,6 @@ __pycache__ *.pyc .tox *.log -temp \ No newline at end of file +.vscode +temp +docs/_build/ 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..922e22f --- /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 0000000..54e9a90 --- /dev/null +++ b/docs/conf.yaml @@ -0,0 +1,3 @@ +--- +project_cfg: oran +project: pti-o2 diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst new file mode 100644 index 0000000..1af3489 --- /dev/null +++ b/docs/developer-guide.rst @@ -0,0 +1,69 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2019 Wind River Systems, Inc. + +Developer-Guide +=============== + +.. contents:: + :depth: 3 + :local: + + +This project implements a reference implementation for O-RAN O2 IMS and DMS to expose INF platfrom to SMO with O2 interface. + +To contribute on this project, you are supposed to be familiar with INF platfrom as well as O-RAN O2 interface specifications: + +- `O-RAN SC INF platfrom`_ +- `O-RAN O2 interface`_ + +.. _`O-RAN SC INF platfrom`: https://docs.o-ran-sc.org/en/latest/projects.html#infrastructure-inf +.. _`O-RAN O2 interface`: https://oranalliance.atlassian.net/wiki/spaces/COWG/overview + + + +1. Prerequisite for build environment +------------------------------------- + +* A ubuntu 18.04 host is sufficient to build o2 projects + +:: + + # clone code from gerrit repo + $ git clone "https://gerrit.o-ran-sc.org/r/pti/o2" && (cd "o2" && mkdir -p .git/hooks && curl -Lo `git rev-parse --git-dir`/hooks/commit-msg https://gerrit.o-ran-sc.org/r/tools/hooks/commit-msg; chmod +x `git rev-parse --git-dir`/hooks/commit-msg) + # run unit tests + $ sudo apt-get install tox + $ tox -e flake8 + $ tox -e code + + +1. local test with docker-compose +--------------------------------- + +* To test with docker-compose, a docker engine is supposed to be installed as well + +:: + + $ docker-compose build + $ docker-compose up -d + $ docker-compose run --rm --no-deps --entrypoint=pytest api /tests/unit /tests/integration + + +3, Test with INF platform +------------------------- + +* To test with INF platform, you should install INF platform first, by default you will be able to use the 'admin' user + +:: + + $ source ./admin_openrc.sh + $ export |grep OS_AUTH_URL + $ export |grep OS_USERNAME + $ export |grep OS_PASSWORD + $ docker-compose run --rm --no-deps --entrypoint=pytest api /tests/integration-ocloud --log-level=DEBUG --log-file=/tests/debug.log + +4, Tear down docker containers + +:: + + $ docker-compose down --remove-orphans 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..e9f0d9a --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,19 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2021 Wind River Systems, Inc. +.. rtp documentation master + +Welcome to RTP O2 ducomentation +=============================== + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + overview.rst + developer-guide.rst + release-notes.rst + installation-guide.rst + +* :ref:`search` diff --git a/docs/installation-guide.rst b/docs/installation-guide.rst new file mode 100644 index 0000000..0297aa1 --- /dev/null +++ b/docs/installation-guide.rst @@ -0,0 +1,182 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2021 Wind River Systems, Inc. + + +Installation Guide +================== + +.. contents:: + :depth: 3 + :local: + +Abstract +-------- + +This document describes how to install O-RAN O2 service over O-RAN INF platform. + +The audience of this document is assumed to have basic knowledge in kubernetes cli, helm chart cli. + + +Preface +------- + +Before starting the installation and deployment of O-RAN O2 service, you should have already deployed O-RAN INF platform, and you need to download the helm charts or build from source as described in developer-guide. + + +ORAN O2 Service in E Release +============================ + +1. Provision remote cli for kubernetes over INF platform +-------------------------------------------------------- + + +1.1 Setup Service Account over O-RAN INF platform +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following instruction must be done over INF platform controller host (controller-0) + +- Please see the O-RAN INF documentation to find out how to ssh to controller host of INF platform. + +:: + + USER="admin-user" + NAMESPACE="kube-system" + + cat < admin-login.yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: ${USER} + namespace: kube-system + --- + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRoleBinding + metadata: + name: ${USER} + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin + subjects: + - kind: ServiceAccount + name: ${USER} + namespace: kube-system + EOF + + kubectl apply -f admin-login.yaml + TOKEN_DATA=$(kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep ${USER} | awk '{print $1}') | grep "token:" | awk '{print $2}') + echo $TOKEN_DATA + + +1.2 Setup remote cli over another linux host (ubuntu as example) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following instruction should be done outside of INF platform controller host + +:: + + sudo apt-get install -y apt-transport-https + echo "deb http://mirrors.ustc.edu.cn/kubernetes/apt kubernetes-xenial main" | \ + sudo tee -a /etc/apt/sources.list.d/kubernetes.list + sudo apt-get update + sudo apt-get install -y kubectl + + source <(kubectl completion bash) # setup autocomplete in bash into the current shell, bash-completion package should be installed first. + echo "source <(kubectl completion bash)" >> ~/.bashrc # add autocomplete permanently to your bash shell. + + https://get.helm.sh/helm-v3.5.3-linux-amd64.tar.gz + tar xvf helm-v3.5.3-linux-amd64.tar.gz + sudo cp linux-amd64/helm /usr/local/bin + + source <(helm completion bash) + echo "source <(helm completion bash)" >> ~/.bashrc + + OAM_IP= + NAMESPACE=orano2 + TOKEN_DATA= + + USER="admin-user" + + kubectl config set-cluster inf-cluster --server=https://${OAM_IP}:6443 --insecure-skip-tls-verify + kubectl config set-credentials ${USER} --token=$TOKEN_DATA + kubectl config set-context ${USER}@inf-cluster --cluster=inf-cluster --user ${USER} --namespace=${NAMESPACE} + kubectl config use-context ${USER}@inf-cluster + + kubectl get pods -A + + +2. Deploy O2 service +-------------------- + +2.1 Retrieve Helm chart for deploying of O2 service +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + git clone -b e-release "https://gerrit.o-ran-sc.org/r/pti/o2" + + + +2.2 Prepare override yaml +~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + export NAMESPACE=orano2 + kubectl create ns ${NAMESPACE} + + cd /home/sysadmin/ + source /etc/platform/openrc + cat <o2service-override.yaml + o2ims: + imagePullSecrets: admin-orano2-registry-secret + image: + repository: registry.local:9001/admin/o2imsdms + tag: 0.1.4 + pullPolicy: IfNotPresent + logginglevel: "DEBUG" + + ocloud: + OS_AUTH_URL: "${OS_AUTH_URL}" + OS_USERNAME: "${OS_USERNAME}" + OS_PASSWORD: "${OS_PASSWORD}" + EOF + + +2.3 Deploy by helm cli +~~~~~~~~~~~~~~~~~~~~~~ + +:: + + helm install o2service o2/charts/ -f o2service-override.yaml + helm list |grep o2service + kubectl -n ${NAMESPACE} get pods |grep o2service + kubectl -n ${NAMESPACE} get services |grep o2service + + +2.4 Verify O2 service +~~~~~~~~~~~~~~~~~~~~~ + +:: + + curl -k http(s)://:30205 + curl -k http(s)://:30205/o2ims_infrastructureInventory/v1 + + +3 Register O-Cloud to SMO + +- assumed you have setup SMO O2 endpoint for registration +- O2 service will post the O-Cloud registration data to that SMO O2 endpoint + +:: + + curl -k -X POST http(s)://:30205/provision/smo-endpoint/v1 -d '{"smo-o2-endpoint": ""}' + + +References +---------- + +- `O-RAN-SC INF`_ + +.. _`O-RAN-SC INF`: https://docs.o-ran-sc.org/en/latest/projects.html#infrastructure-inf diff --git a/docs/overview.rst b/docs/overview.rst new file mode 100644 index 0000000..036e77c --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,46 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2021 Wind River Systems, Inc. + +INF O2 Service Overview +======================= + +This project implements a reference O2 IMS and DMS service to expose O2 interface to SMO. + +In the E release, the following API of O2 interface is enabled: + +1. O-Cloud registration and inventory query + + - O2 service discovers INF platform as O-Cloud, register the O-Cloud to SMO with provisioned SMO O2 endpoint. + + - Provision SMO O2 endpoint + + - Register INF as O-Cloud to SMO via SMO O2 endpoint + + - O2 service discovers following resources of INF platform to answer queries from SMO + + - O-Cloud information + + - Resource Pool of the O-Cloud + + - Resources of the Resource Pool, including pserver, cpu, memory, port, interface + + - kubernetes API endpoint as Deployment Management Service + + +2. Deployment Management Service + + - O2 service expose DMS on behalf of kubernetes API endpoint hosted by INF platform, which support NfDeployment described by Helm charts + + - Management of NfDeploymentDescriptor + + - Management of NfDeployment + + +3. Subscription and Notification + + - O2 service exposes Subscription API to enable SMO subscribes to Notification of changes of resources + + - Management of Subscriptions + + - Notification delivery via Rest API provided by specific Subscriptions diff --git a/docs/release-notes.rst b/docs/release-notes.rst new file mode 100644 index 0000000..0988143 --- /dev/null +++ b/docs/release-notes.rst @@ -0,0 +1,39 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2019 Wind River Systems, Inc. + + +Release-notes +============= + + +This document provides the release notes for 5.0.0 of RTP O2 service. + +.. contents:: + :depth: 3 + :local: + + +Version history +--------------- + ++--------------------+--------------------+--------------------+--------------------+ +| **Date** | **Ver.** | **Author** | **Comment** | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| 2021-12-15 | 1.0.0 | Bin Yang | E Release | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ + +Version 1.0.0, 2021-12-15 +------------------------- +- Initial version (E release) +- Add O2 IMS for INF platform + - Enable O-Cloud registration to SMO + - Enable O2 infrastructure inventory service API + - Enable O2 Subscription service API + - Enable O2 Notification service +- ADD O2 DMS for INF platform + - A PoC which enables NfDeployment described with helm charts + - Add Lifecycle Management API for NfDeploymentDescriptor + - Add Lifecycle Management API for NfDeployment 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 index 39016e9..d316240 100644 --- a/tox.ini +++ b/tox.ini @@ -1,8 +1,12 @@ # content of: tox.ini , put in same dir as setup.py [tox] -envlist=flake8,code +envlist= + flake8, + code, + docs, + docs-linkcheck, -minversion = 1.6 +minversion = 2.0 skipsdist = True [testenv] @@ -33,3 +37,29 @@ commands = [testenv:nosetests] commands = pytest tests/unit + + +[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