From: wrider Date: Tue, 12 Nov 2019 05:10:53 +0000 (-0500) Subject: Update doc X-Git-Tag: 3.8.0~10 X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=96a85f952452bf2efd606dcc52f86250f7da29a0;p=it%2Fdev.git Update doc Change-Id: Iaef07fc56eff9b9d0755a8ed2a58b0072ddede7e Signed-off-by: wrider --- diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst index b7cc568..4b148a1 100644 --- a/docs/developer-guide.rst +++ b/docs/developer-guide.rst @@ -10,25 +10,93 @@ Developer-Guide :depth: 3 :local: -.. note: -.. * This section is used to describe what a contributor needs to know in order to work on the componenta +Overview +--------- -.. * this should be very technical, aimed at people who want to help develop the components +The introduction of a new xApp to Near Realtime RIC consists of a number of steps: -.. * this should be how the component does what it does, not a requirements document of what the component should do +1. xApp developer implements the xApp and packaging into a docker container; +2. xApp developer creates a "descriptor" for the xApp describing how it can be configured; +3. the xApp developer generates a testing Helm chart using tools provided in this repo and test xApp in a Kubernetes/Helm environment; +4. the xApp developer submits the xApp "descriptor" along with the container image for on-boarding. -.. * this should contain what language(s) and frameworks are used, with versions +At deployment time, the descriptor and the container image of an already on-boarded xApp are applied to a standard Helm chart for the generation of the Helm chart for the xApp. Such Helm chart is pushed to the private Helm repository of the xApp Manager of the Near Realtime RIC Platform. -.. * this should contain how to obtain the code, where to look at work items (Jira tickets), how to get started developing - -.. * This note must be removed after content has been added. +The image below depicts this workflow. +.. image:: images/xapp-flow.png + :scale: 50 % + :align: center -Processes ---------- +xApp Descriptor +--------------- +An xApp's descriptor consists of two files, a config-file.json file and a schema.json file which provides the schema definition of the config-file.json file. + +An example pair of config and schema files can be found at the ric-app/admin repo, under its init directory: +https://gerrit.o-ran-sc.org/r/gitweb?p=ric-app/admin.git;a=tree;f=init;hb=HEAD + + + +Generating Helm Charts +---------------------- +The ric-xapp/bin/install script is provided for generating the xApp Helm chart. + +The scrip will insert the xApp descriptor files into the standard xApp helm chart template, package it, and upload it to a Helm repository. + +Prerequisites: +- config-file.json file from the xApp descriptor; +- schema.json file from the xApp descriptor; +- full path with tag of the docker image of the xApp; +- a recipe file that contains the full URL of the helm repo; +- username and password of the helm repo. + +Parameters: + ++------------+----------------------------------------------------+ +| option | Description | ++============+====================================================+ +|-n |name of the xApp | ++------------+----------------------------------------------------+ +|-v | version of the helm chart | ++------------+----------------------------------------------------+ +|-f | path of the recipe that contains the helm repo URL | ++------------+----------------------------------------------------+ +|-I | full docker image path | ++------------+----------------------------------------------------+ +|-d | path to the schema.json file | ++------------+----------------------------------------------------+ +|-c | path to the config-file.json file | ++------------+----------------------------------------------------+ +|-h | helm repo username | ++------------+----------------------------------------------------+ +|-p | helm repo password | ++------------+----------------------------------------------------+ + + +Below is an example of the recipe file that specifies the Helm repo parameters: +:: + + global: + # Docker registry from which RIC platform components pull the images + repository: nexus3.o-ran-sc.org:10004 + # Name of the K8S docker credential that is onboarded by 20-credential + repositoryCred: docker-reg-cred + # Docker image pull policy + imagePullPolicy: Always + # Helm repo that will be used by xApp manager + helmRepository: "https://helm-entry" + # Certificate of the helm repo + helmRepositoryCert: xapp-mgr-certs + # Name of the K8S secret that contains the credential of the helm repo + helmRepositoryCred: xapp-mgr-creds + # The name of the tiller that xApp helm client talks to + + +The resultant Helm chart is available at /tmp/{{chart-name}}-{{chart-version}}.tgz. This file can be uploaded yo Helm chart using an API call that the Helm chart repo supports. For example, the following command applies to a Chart Museum type of Helm repo: +:: + + curl -Lk -u $HELM_REPO_USERNAME:$HELM_REPO_PASSWORD "$HELM_REPO"/api/charts --data-binary "@/tmp/$CHART_NAME-$CHART_VERSION.tgz" -Actions -------- diff --git a/docs/images/xapp-flow.png b/docs/images/xapp-flow.png new file mode 100644 index 0000000..4827cf8 Binary files /dev/null and b/docs/images/xapp-flow.png differ diff --git a/docs/index.rst b/docs/index.rst index 57a9d34..0bc154d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,8 +4,8 @@ .. Copyright (C) 2019 AT&T Intellectual Property -Welcome to O-RAN SC it/dev Documentation -=========================================== +Welcome to O-RAN SC Integratoin for xApp Development Documentation +================================================================== .. toctree:: :maxdepth: 2 @@ -15,7 +15,6 @@ Welcome to O-RAN SC it/dev Documentation developer-guide.rst release-notes.rst - * :ref:`genindex` * :ref:`modindex` * :ref:`search` diff --git a/docs/overview.rst b/docs/overview.rst index 4e09fb9..4b8e427 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -7,6 +7,11 @@ Overview ====================== -This repo is used by the O-RAN SC Integration and Testing project for hosting miscellaneous development codes. +The it/dev repo is used by the O-RAN SC Integration and Testing project for hosting miscellaneous development codes. + +For Amber release this repo contains integration artifacts for developing Near Realtime RAN Intelligent Controller applications (xApps). + +Because the life cycles of Near Realtime RIC xApps are managed by Near Realtime RIC +Platform, the xApps are expect to conform with certain behavioral patterns and provide +well-described interfaces. The artifacts here help the xApp developers to generate (Near Realtime) RIC Platform deployment ready Helm charts for their xApps. -For Amber release this repo contains files for developing Near Realtime RAN Intelligent Controller applications. diff --git a/docs/release-notes.rst b/docs/release-notes.rst index 694d2d9..d14acbe 100644 --- a/docs/release-notes.rst +++ b/docs/release-notes.rst @@ -8,164 +8,20 @@ Release-Notes ============= -This document provides the release notes for of . +This document provides the release notes for O-RAN SC Amber release of it/dev. .. 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 ----------- - +Integration Development for xApps +================================== +Version 1.0.0, Nov 11, 2019 +--------------------------- +* Standard Near Realtime RIC xApp Helmm chart +* Scripts for on-board a Near Realtime RIC xApp