--- /dev/null
+.black {
+ color: black;
+}
+
+.gray {
+ color: gray;
+}
+
+.grey {
+ color: gray;
+}
+
+.silver {
+ color: silver;
+}
+
+.white {
+ color: white;
+}
+
+.maroon {
+ color: maroon;
+}
+
+.red {
+ color: red;
+}
+
+.magenta {
+ color: magenta;
+}
+
+.fuchsia {
+ color: fuchsia;
+}
+
+.pink {
+ color: pink;
+}
+
+.orange {
+ color: orange;
+}
+
+.yellow {
+ color: yellow;
+}
+
+.lime {
+ color: lime;
+}
+
+.green {
+ color: green;
+}
+
+.olive {
+ color: olive;
+}
+
+.teal {
+ color: teal;
+}
+
+.cyan {
+ color: cyan;
+}
+
+.aqua {
+ color: aqua;
+}
+
+.blue {
+ color: blue;
+}
+
+.navy {
+ color: navy;
+}
+
+.purple {
+ color: purple;
+}
+
+.under {
+ text-decoration: underline;
+}
+
+.over {
+ text-decoration: overline;
+}
+
+.blink {
+ text-decoration: blink;
+}
+
+.line {
+ text-decoration: line-through;
+}
+
+.strike {
+ text-decoration: line-through;
+}
+
+.it {
+ font-style: italic;
+}
+
+.ob {
+ font-style: oblique;
+}
+
+.small {
+ font-size: small;
+}
+
+.large {
+ font-size: large;
+}
+
+.smallpar {
+ font-size: small;
+}
+
+
+/* Style pour les badges en bas de la page. */
+
+div.supportBadges {
+ margin: 1em;
+ text-align: right;
+}
+
+div.supportBadges ul {
+ padding: 0;
+ display: inline;
+}
+
+div.supportBadges li {
+ display: inline;
+}
+
+div.supportBadges a {
+ margin-right: 1px;
+ opacity: 0.6;
+}
+
+div.supportBadges a:hover {
+ opacity: 1;
+}
+
+
+/* Details elements in the sidebar */
+
+a.reference {
+ border-bottom: none;
+ text-decoration: none;
+}
+
+ul.details {
+ font-size: 80%;
+}
+
+ul.details li p {
+ font-size: 85%;
+}
+
+ul.externallinks {
+ font-size: 85%;
+}
+
+
+/* Pour le drapeau de langue */
+
+img.languageswitch {
+ width: 50px;
+ height: 32px;
+ margin-left: 5px;
+ vertical-align: bottom;
+}
+
+div.sphinxsidebar {
+ overflow: hidden !important;
+ font-size: 120%;
+ word-wrap: break-word;
+ width: 300px;
+ max-width: 300px;
+}
+
+div.sphinxsidebar h3 {
+ font-size: 125%;
+}
+
+div.sphinxsidebar h4 {
+ font-size: 110%;
+}
+
+div.sphinxsidebar a {
+ font-size: 85%;
+}
+
+
+/* Image style for scrollUp jQuery plugin */
+
+#scrollUpLeft {
+ bottom: 50px;
+ left: 260px;
+ height: 38px;
+ width: 38px;
+ background: url('//perso.crans.org/besson/_images/.top.svg');
+ background: url('../_images/.top.svg');
+}
+
+@media screen and (max-width: 875px) {
+ #scrollUpLeft {
+ right: 50px;
+ left: auto;
+ }
+}
+
+
+/* responsive for font-size. */
+
+@media (max-width: 875px) {
+ body {
+ font-size: 105%;
+ /* Increase font size for responsive theme */
+ }
+}
+
+@media (max-width: 1480px) and (min-width: 876px) {
+ body {
+ font-size: 110%;
+ /* Increase font size for not-so-big screens */
+ }
+}
+
+@media (min-width: 1481px) {
+ body {
+ font-size: 115%;
+ /* Increase even more font size for big screens */
+ }
+}
+
+
+/* Social Icons in the sidebar (available: twitter, facebook, linkedin, google+, bitbucket, github) */
+
+.social-icons {
+ display: inline-block;
+ margin: 0;
+ text-align: center;
+}
+
+.social-icons a {
+ background: none no-repeat scroll center top #444444;
+ border: 1px solid #F6F6F6;
+ border-radius: 50% 50% 50% 50%;
+ display: inline-block;
+ height: 35px;
+ width: 35px;
+ margin: 0;
+ text-indent: -9000px;
+ transition: all 0.2s ease 0s;
+ text-align: center;
+ border-bottom: none;
+}
+
+.social-icons li {
+ display: inline-block;
+ list-style-type: none;
+ border-bottom: none;
+}
+.social-icons li a {
+ border-bottom: none;
+}
+
+.social-icons a:hover {
+ background-color: #666666;
+ transition: all 0.2s ease 0s;
+ text-decoration: none;
+}
+
+.social-icons a.facebook {
+ background-image: url('../_images/.facebook.png');
+ background-image: url('//perso.crans.org/besson/_images/.facebook.png');
+ display: block;
+ margin-left: auto;
+ margin-right: auto;
+ background-size: 35px 35px;
+}
+
+.social-icons a.bitbucket {
+ background-image: url('../_images/.bitbucket.png');
+ background-image: url('//perso.crans.org/besson/_images/.bitbucket.png');
+ display: block;
+ margin-left: auto;
+ margin-right: auto;
+ background-size: 35px 35px;
+}
+
+.social-icons li a.github {
+ background-image: url('../_images/.github.png');
+ background-image: url('//perso.crans.org/besson/_images/.github.png');
+ display: block;
+ margin-left: auto;
+ margin-right: auto;
+ background-size: 35px 35px;
+}
+
+.social-icons li a.wikipedia {
+ background-image: url('../_images/.wikipedia.png');
+ background-image: url('//perso.crans.org/besson/_images/.wikipedia.png');
+ display: block;
+ margin-left: auto;
+ margin-right: auto;
+ background-size: 35px 35px;
+}
'https://gerrit.o-ran-sc.org.*'
]
+rst_prolog = """
+.. include:: <s5defs.txt>
+.. default-role::
+
+"""
+
+html_css_files = ['css/s4defs-roles.css']
+
+extensions = ['sphinxcontrib.contentui']
+++ /dev/null
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-..
-.. Copyright (C) 2019 AT&T Intellectual Property
-
-Developer-Guide
-===============
-
-.. contents::
- :depth: 3
- :local:
-
-Overview
----------
-
-The introduction of a new xApp to Near Realtime RIC consists of a number of steps:
-
-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.
-
-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.
-
-The image below depicts this workflow.
-
-.. image:: images/xapp-flow.png
- :scale: 50 %
- :align: center
-
-
-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"
-
-
-
Welcome to O-RAN SC Integratoin for xApp Development Documentation
==================================================================
+The it/dev repo is used by the O-RAN SC Integration and Testing project for hosting miscellaneous development codes.
+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.
+
+
+The following is a list of projects hosted by this repo.
+
.. toctree::
- :maxdepth: 2
- :caption: Contents:
+ :maxdepth: 1
- overview.rst
- developer-guide.rst
- release-notes.rst
+ xapp_onboarder/index.rst
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+++ /dev/null
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. SPDX-License-Identifier: CC-BY-4.0
-..
-.. Copyright (C) 2019 AT&T Intellectual Property
-
-
-Overview
-======================
-
-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.
-
+++ /dev/null
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-..
-.. Copyright (C) 2019 AT&T Intellectual Property
-
-
-Release-Notes
-=============
-
-
-This document provides the release notes for O-RAN SC Amber release of it/dev.
-
-.. contents::
- :depth: 3
- :local:
-
-
-
-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
-
-
--- /dev/null
+{
+ "xapp_name": "mcxapp",
+ "version": "1.0.2",
+ "containers": [
+ {
+ "name": "mcxapp",
+ "image": {
+ "registry": "nexus3.o-ran-sc.org:10002",
+ "name": "o-ran-sc/ric-app-mc",
+ "tag": "1.0.2"
+ },
+ "command": "/playpen/bin/container_start.sh"
+ }
+ ],
+ "livenessProbe": {
+ "exec": {
+ "command": ["/usr/local/bin/health_ck"]
+ },
+ "initialDelaySeconds": 5,
+ "periodSeconds": 15
+ },
+ "readinessProbe": {
+ "httpGet": {
+ "path": "ric/v1/health/alive",
+ "port": 8080
+ },
+ "initialDelaySeconds": 5,
+ "periodSeconds": 15
+ },
+ "messaging": {
+ "ports": [
+ {
+ "name": "http",
+ "container": "mcxapp",
+ "port": 8080,
+ "description": "http service"
+ },
+ {
+ "name": "rmr-data",
+ "container": "mcxapp",
+ "port": 4560,
+ "txMessages":
+ [
+ "RIC_SUB_REQ",
+ "RIC_SUB_DEL_REQ"
+ ],
+ "rxMessages":
+ [
+ "RIC_SUB_RESP",
+ "RIC_SUB_FAILURE",
+ "RIC_SUB_DEL_RESP",
+ "RIC_INDICATION"
+ ],
+ "policies": [1,2],
+ "description": "rmr data port for mcxapp"
+ },
+ {
+ "name": "rmr-route",
+ "container": "mcxapp",
+ "port": 4561,
+ "description": "rmr route port for mcxapp"
+ }
+ ]
+ },
+ "controls": {
+ "active": true,
+ "interfaceId": {
+ "globalENBId": {
+ "plmnId": 123456,
+ "eNBId": 5678
+ }
+ },
+ "ves_collector_address": "xapp-sandbox2.research.att.com:8888",
+ "measurement_interval": 10000,
+ "simulator_mode": "true",
+ "debug_mode": "true",
+ "local": {
+ "host": ":8080"
+ },
+ "logger": {
+ "level": 3
+ }
+ },
+ "metrics": [
+ {
+ "objectName": "UEEventStreamingCounters",
+ "objectInstance": "SgNBAdditionRequest",
+ "name": "SgNBAdditionRequest",
+ "type": "counter",
+ "description": "The total number of SG addition request events processed"
+ },
+ {
+ "objectName": "UEEventStreamingCounters",
+ "objectInstance": "SgNBAdditionRequestAcknowledge",
+ "name": "SgNBAdditionRequestAcknowledge",
+ "type": "counter",
+ "description": "The total number of SG addition request acknowledge events processed"
+ }
+ ]
+}
\ No newline at end of file
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+..
+.. Copyright (C) 2019 AT&T Intellectual Property
+
+
+xApp descriptor
+===============
+
+
+Introduction
+------------
+
+The xApp descriptor is provided by the xApp developer. xApp descriptor includes all the basic and essential information for the RIC platform to manage the life cycle of the xApp. Information and configuration included in the xApp descriptor will be used to generate the xApp helm charts and define the data flows to the north and south bound traffics. xApp developer can also include self-defined internal parameters that will be consumed by the xApp in the xApp descriptor.
+
+The xApp descriptor comes with a config-file.json file that defines the behavior of the xApp, and optionally a schema.json JSON schema file that validates the self-defined parameters.
+
+Config File Structure
+---------------------
+The xApp descriptor config-file.json file follows a JSON structure. The following are the key sections that defines an xApp.
+
+
+* **xapp_name:** :red:`(REQUIRED)` this is the unique identifier to address an xApp. A valid xApp descriptor must includes the xapp_name attribute. The following is an example.
+
+ .. code-block::
+
+ "xapp_name": "example_xapp"
+
+* **version:** :red:`(REQUIRED)` this is the semantic version number of the xApp descriptor. It defines the version numbers of the xApp artifacts (e.g., xApp helm charts) that will be generated from the xApp descriptor. Together with the xapp\_name, they defines the unique identifier of an xApp artifact that can be on-boarded, distributed and deployed. The following is an example.
+
+ .. code-block::
+
+ "version": "1.0.0"
+
+* **containers:** :red:`(REQUIRED)` this section defines a list of containers that the xApp will run. For each container, a structure that defines the container name, image registry, image name, image tag, and the command that it runs is defined. :red:`The name and images are REQUIRED.` The command field is optional. The following is an example that defines two containers.
+
+ .. code-block::
+
+ "containers": [
+ {
+ "name": "example_container_1",
+ "image": {
+ "registry": "example_image_registry_1",
+ "name": "example_image_name_1",
+ "tag": "example_image_tag_1"
+ },
+ "command": "example_command_1"
+ },
+ {
+ "name": "example_container_2",
+ "image": {
+ "registry": "example_image_registry_2",
+ "name": "example_image_name_2",
+ "tag": "example_image_tag_2"
+ }
+ }
+ ]
+
+
+* **controls:** :green:`(OPTIONAL)` The control section holds the internal configuration of the xApp. Therefore, this section is xApp specific. This section can include arbitrary number of xApp defined parameters. The xApp consumes the parameters by reading the xApp descriptor file that will be injected into the container as a JSON file. An environment variable XAPP_DESCRIPTOR_PATH will point to the directory where the JSON file is mounted inside the container. :red:`If the controls section is not empty, the xApp developer must provide the additional schema file for this controls section.` Please refer to Schema for xApp Descriptor for creating such schema file. The following is an example for the controls section.
+
+ .. code-block::
+
+ "controls": {
+ "active": True,
+ "requestorId": 66,
+ "ranFunctionId": 1,
+ "ricActionId": 0,
+ "interfaceId": {
+ "globalENBId": {
+ "plmnId": "310150",
+ "eNBId": 202251
+ }
+ }
+ }
+
+
+* **metrics:** :green:`(OPTIONAL)` The metrics section of the xApp descriptor holds information about metrics provided by the xApp. :red:`Each metrics item requires the objectName, objectInstance, name, type and description of each counter.` The metrics section is required by VESPA manager (RIC platform component) and the actual metrics data are exposed to external servers via Prometheus VESPA interface. The following is an example.
+
+ .. code-block::
+
+ "metrics": [
+ {
+ "objectName": "UEEventStreamingCounters",
+ "objectInstance": "SgNBAdditionRequest",
+ "name": "SgNBAdditionRequest",
+ "type": "counter",
+ "description": "The total number of SG addition request events processed"
+ },
+ {
+ "objectName": "UEEventStreamingCounters",
+ "objectInstance": "SgNBAdditionRequestAcknowledge",
+ "name": "SgNBAdditionRequestAcknowledge",
+ "type": "counter",
+ "description": "The total number of SG addition request acknowledge events processed"
+ }
+ ]
+
+* **messaging:** :green:`(OPTIONAL)` This section defines the communication ports for each containers. It may define list of RX and TX message types, and the A1 policies for RMR communications implemented by this xApp. Each defined port will creates a K8S service port that are mapped to the container at the same port number. :red:`This section requires ports that contains the port name, port number, which container it is for. For RMR port, it also requires tx and rx message types, and A1 policy list.`
+
+ .. note:: **Stop gap solution for bronze release:** The messaging section replaces the previously RMR section in the xApp descriptor. It requires appmgr to modify its codes to parse the new messaging section. Before the new version of appmgr is released, as a stop gap solution, we will also include a compatible RMR section with the same information in the xApp descriptor. Please refer to the stop-gap-MCxApp descriptor for example.
+
+
+ .. warning:: **Choosing port numbers:** In the bronze release appmgr is not consuming the port name defined in the messaging section yet. Please chose to use the default 4560 port for rmr-data and 4561 for rmr-route.
+
+ .. warning:: **Port naming convention:** Kubernetes requires the port name to be DNS compatible. Therefore, please choose a port name that contains only alphabetical characters (A-Z), numeric characters (0-9), the minus sign (-), and the period (.). Period characters are allowed only when they are used to delimit the components of domain style names.
+
+ The following is an example
+
+ .. code-block::
+
+ "messaging": {
+ "ports": [
+ {
+ "name": "http",
+ "container": "mcxapp",
+ "port": 8080,
+ "description": "http service"
+ },
+ {
+ "name": "rmr-data",
+ "container": "mcxapp",
+ "port": 4560,
+ "txMessages":
+ [
+ "RIC_SUB_REQ",
+ "RIC_SUB_DEL_REQ"
+ ],
+ "rxMessages":
+ [
+ "RIC_SUB_RESP",
+ "RIC_SUB_FAILURE",
+ "RIC_SUB_DEL_RESP",
+ "RIC_INDICATION"
+ ],
+ "policies": [1,2],
+ "description": "rmr data port for mcxapp"
+ },
+ {
+ "name": "rmr-route",
+ "container": "mcxapp",
+ "port": 4561,
+ "description": "rmr route port for mcxapp"
+ }
+ ]
+ },
+
+* **liveness probes:** :green:`(OPTIONAL)` The liveness probe section defines how liveness probe is defined in the xApp helm charts. You can provide ether a command or a http helm liveness probe definition in JSON format. :red:`This section requires initialDelaySeconds, periodSeconds, and either httpGet or exec.`
+ The following is an example for http-based liveness probes.
+
+ .. code-block::
+
+ "livenessProbe": {
+ "exec": {
+ "command": ["/usr/local/bin/rmr_probe"]
+ },
+ "initialDelaySeconds": "5",
+ "periodSeconds": "15"
+ },
+
+
+ The following is an example for rmr-based liveness probes.
+
+ .. code-block::
+
+ "livenessProbe": {
+ "exec": {
+ "command": ["/usr/local/bin/rmr_probe"]
+ },
+ "initialDelaySeconds": "5",
+ "periodSeconds": "15"
+ },
+
+* **readiness probes:** :green:`(OPTIONAL)` The readiness probe section defines how readiness probe is defined in the xApp helm charts. You can provide ether a command or a http helm readiness probe definition in JSON format. :red:`This section requires initialDelaySeconds, periodSeconds, and either httpGet or exec.`
+ The following is an example for http-based readiness probes.
+
+ .. code-block::
+
+ "readinessProbe": {
+ "httpGet": {
+ "path": "ric/v1/health/alive",
+ "port": "8080"
+ },
+ "initialDelaySeconds": "5",
+ "periodSeconds": "15"
+ },
+
+ The following is an example for rmr-based readiness probes.
+
+ .. code-block::
+
+ "readinessProbe": {
+ "exec": {
+ "command": ["/usr/local/bin/rmr_probe"]
+ },
+ "initialDelaySeconds": "5",
+ "periodSeconds": "15"
+ },
+
+
--- /dev/null
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "$id": "http://o-ran-sc.org/xapp_root.json",
+ "type": "object",
+ "title": "The xApp Root Schema",
+ "required": [
+ "xapp_name",
+ "version",
+ "containers"
+ ],
+ "properties": {
+ "xapp_name": {
+ "$id": "#/properties/xapp_name",
+ "type": "string",
+ "title": "The xApp Name",
+ "default": "xapp",
+ "examples": [
+ "example_xapp"
+ ]
+ },
+ "version": {
+ "$id": "#/properties/version",
+ "type": "string",
+ "title": "The xApp version",
+ "default": "1.0.0",
+ "examples": [
+ "1.0.0"
+ ],
+ "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$"
+ },
+ "containers": {
+ "$id": "#/properties/containers",
+ "type": "array",
+ "title": "The Container Schema",
+ "items": {
+ "$id": "#/properties/containers/items",
+ "type": "object",
+ "title": "The Container Items Schema",
+ "required": [
+ "name",
+ "image"
+ ],
+ "properties": {
+ "name": {
+ "$id": "#/properties/containers/items/properties/name",
+ "type": "string",
+ "title": "The xApp Container Name",
+ "default": "xapp",
+ "examples": [
+ "xapp"
+ ]
+ },
+ "image": {
+ "$id": "#/properties/containers/items/properties/image",
+ "type": "object",
+ "title": "The Container Image",
+ "required": [
+ "registry",
+ "name",
+ "tag"
+ ],
+ "properties": {
+ "registry": {
+ "$id": "#/properties/containers/items/properties/image/properties/registry",
+ "type": "string",
+ "title": "The xApp Image Registry",
+ "default": "nexus3.o-ran-sc.org:10002",
+ "examples": [
+ "nexus3.o-ran-sc.org:10002"
+ ],
+ "pattern": "^[A-Za-z0-9\\.-]{1,}\\.[A-Za-z]{1,}(?:\\:\\d+)?$"
+ },
+ "name": {
+ "$id": "#/properties/containers/items/properties/image/properties/name",
+ "type": "string",
+ "title": "The xApp Image Name",
+ "default": "xapp",
+ "examples": [
+ "xapp"
+ ]
+ },
+ "tag": {
+ "$id": "#/properties/containers/items/properties/image/properties/tag",
+ "type": "string",
+ "title": "The xApp Image Tag",
+ "default": "latest",
+ "examples": [
+ "latest"
+ ]
+ }
+ }
+ },
+ "command": {
+ "$id": "#/properties/containers/items/properties/command",
+ "type": "string",
+ "title": "Command To Run The xApp Container",
+ "default": "command",
+ "examples": [
+ "command"
+ ]
+ }
+ }
+ }
+ },
+ "livenessProbe": {
+ "$id": "#/properties/livenessprobe",
+ "type": "object",
+ "title": "The Liveness Probe Definition",
+ "properties": {
+ "exec": {
+ "$id": "#/properties/livenessprobe/exec",
+ "type": "object",
+ "title": "Script of Liveness Probe",
+ "properties": {
+ "command": {
+ "$id": "#/properties/livenessprobe/exec/command",
+ "type": "array",
+ "items": [
+ {
+ "$id": "#/properties/livenessprobe/exec/command/item",
+ "type": "string",
+ "title": "The Command Item",
+ "default": "/bin/sh",
+ "examples": [
+ "/bin/sh"
+ ]
+ }
+ ]
+ }
+ },
+ "required": [
+ "command"
+ ]
+ },
+ "httpGet": {
+ "$id": "#/properties/livenessprobe/httpget",
+ "type": "object",
+ "title": "Http of Liveness Probe",
+ "properties": {
+ "path": {
+ "$id": "#/properties/livenessprobe/httpget/path",
+ "type": "string",
+ "title": "The Path of Http Liveness Probe",
+ "default": "/health",
+ "examples": [
+ "/health"
+ ]
+ },
+ "port": {
+ "$id": "#/properties/livenessprobe/httpget/port",
+ "type": "integer",
+ "title": "The Port of Http Liveness Probe",
+ "default": 80,
+ "examples": [
+ 80
+ ]
+ }
+ },
+ "required": [
+ "path",
+ "port"
+ ]
+ },
+ "initialDelaySeconds": {
+ "$id": "#/properties/livenessprobe/initialdelayseconds",
+ "type": "integer",
+ "title": "Initial Delay of Liveness Probe",
+ "default": 5,
+ "examples": [
+ 5
+ ]
+ },
+ "periodSeconds": {
+ "$id": "#/properties/livenessprobe/periodseconds",
+ "type": "integer",
+ "title": "Period of Liveness Probe",
+ "default": 15,
+ "examples": [
+ 15
+ ]
+ }
+ },
+ "oneOf": [
+ {
+ "$id": "#/properties/livenessprobe/oneof/exec",
+ "required": ["exec", "initialDelaySeconds", "periodSeconds"]
+ },
+ {
+ "$id": "#/properties/livenessprobe/oneof/httpget",
+ "required": ["httpGet", "initialDelaySeconds", "periodSeconds"]
+ }
+ ]
+ },
+ "readinessProbe": {
+ "$id": "#/properties/readinessprobe",
+ "type": "object",
+ "title": "The Readiness Probe Definition",
+ "properties": {
+ "exec": {
+ "$id": "#/properties/readinessprobe/exec",
+ "type": "object",
+ "title": "Script of Readiness Probe",
+ "properties": {
+ "command": {
+ "$id": "#/properties/readinessprobe/exec/command",
+ "type": "array",
+ "items": [
+ {
+ "type": "string"
+ }
+ ]
+ }
+ },
+ "required": [
+ "command"
+ ]
+ },
+ "httpGet": {
+ "$id": "#/properties/readinessprobe/httpget",
+ "type": "object",
+ "title": "Http of Readiness Probe",
+ "properties": {
+ "path": {
+ "$id": "#/properties/readinessprobe/httpget/path",
+ "type": "string",
+ "title": "The Path of Http Readiness Probe",
+ "default": "/health",
+ "examples": [
+ "/health"
+ ]
+ },
+ "port": {
+ "$id": "#/properties/readinessprobe/httpget/port",
+ "type": "integer",
+ "title": "The Port of Http Readiness Probe",
+ "default": 80,
+ "examples": [
+ 80
+ ]
+ }
+ },
+ "required": [
+ "path",
+ "port"
+ ]
+ },
+ "initialDelaySeconds": {
+ "$id": "#/properties/readinessprobe/initialdelayseconds",
+ "type": "integer",
+ "title": "Initial Delay of Readiness Probe",
+ "default": 5,
+ "examples": [
+ 5
+ ]
+ },
+ "periodSeconds": {
+ "$id": "#/properties/readinessprobe/periodseconds",
+ "type": "integer",
+ "title": "Period of Readiness Probe",
+ "default": 15,
+ "examples": [
+ 15
+ ]
+ }
+ },
+ "oneOf": [
+ {
+ "$id": "#/properties/readinessprobe/oneof/exec",
+ "required": ["exec", "initialDelaySeconds", "periodSeconds"]
+ },
+ {
+ "$id": "#/properties/readinessprobe/oneof/httpget",
+ "required": ["httpGet", "initialDelaySeconds", "periodSeconds"]
+ }
+ ]
+ },
+ "messaging": {
+ "type": "object",
+ "$id": "#/properties/messaging",
+ "title": "The Messaging Schema",
+ "properties": {
+ "ports": {
+ "$id": "#/properties/messaging/ports",
+ "type": "array",
+ "title": "The Ports for Messaging",
+ "items":{
+ "$id": "#/properties/messaging/ports/items",
+ "type": "object",
+ "title": "The Item of Port",
+ "required": ["name", "container", "port"],
+ "dependencies": {
+ "txMessages": ["rxMessages", "policies"],
+ "rxMessages": ["txMessages", "policies"],
+ "policies": ["rxMessages", "txMessages"]
+ },
+ "properties": {
+ "name": {
+ "$id": "#/properties/messaging/ports/items/name",
+ "type": "string",
+ "title": "The Name of the Port",
+ "default": "App",
+ "examples": [
+ "App"
+ ]
+ },
+ "container": {
+ "$id": "#/properties/messaging/ports/items/container",
+ "type": "string",
+ "title": "The Container of the Port",
+ "default": "xapp",
+ "examples": [
+ "xapp"
+ ]
+ },
+ "port": {
+ "$id": "#/properties/messaging/ports/items/port",
+ "type": "integer",
+ "title": "The Port Number",
+ "default": 8080,
+ "examples": [
+ 8080
+ ]
+ },
+ "description": {
+ "$id": "#/properties/messaging/ports/items/description",
+ "type": "string",
+ "title": "The description for the port",
+ "default": "port description",
+ "examples": [
+ "port description"
+ ]
+ },
+ "txMessages": {
+ "$id": "#/properties/messaging/ports/items/txmessages",
+ "type": "array",
+ "title": "The txMessage Types",
+ "items":{
+ "$id": "#/properties/messaging/ports/items//txmessages/item",
+ "type": "string",
+ "title": "The txMessage Types Item",
+ "default": "RIC_SUB",
+ "examples": [
+ "RIC_SUB"
+ ]
+ }
+ },
+ "rxMessages": {
+ "$id": "#/properties/messaging/ports/items/rxmessages",
+ "type": "array",
+ "title": "The rxMessage Types",
+ "items":{
+ "$id": "#/properties/messaging/ports/items/rxmessages/item",
+ "type": "string",
+ "title": "The rxMessage Types Item",
+ "default": "RIC_SUB",
+ "examples": [
+ "RIC_SUB"
+ ]
+ }
+ },
+ "policies": {
+ "$id": "#/properties/messaging/ports/items/policies",
+ "type": "array",
+ "title": "The Policies Types",
+ "items":{
+ "$id": "#/properties/messaging/ports/items/policies/item",
+ "type": "integer",
+ "title": "The Policy Types Item",
+ "default": 1,
+ "examples": [
+ 1
+ ]
+ }
+ }
+ }
+ }
+ }
+ },
+ "required": [
+ "ports"
+ ]
+
+ },
+ "metrics": {
+ "type": "array",
+ "$id": "#/properties/metrics",
+ "title": "The Metrics Schema",
+ "items": {
+ "$id": "#/properties/metrics/items",
+ "type": "object",
+ "title": "The Metrics Items Schema",
+ "required": [
+ "objectName",
+ "objectInstance",
+ "name",
+ "type",
+ "description"
+ ],
+ "properties": {
+ "objectName": {
+ "$id": "#/properties/metrics/items/objectname",
+ "type": "string",
+ "title": "The Object Name"
+ },
+ "objectInstance": {
+ "$id": "#/properties/metrics/items/objectinstance",
+ "type": "string",
+ "title": "The Object Instance"
+ },
+ "name": {
+ "$id": "#/properties/metrics/items/name",
+ "type": "string",
+ "title": "The Object Name"
+ },
+ "type": {
+ "$id": "#/properties/metrics/items/type",
+ "type": "string",
+ "title": "The Object Type"
+ },
+ "description": {
+ "$id": "#/properties/metrics/items/description",
+ "type": "string",
+ "title": "The Object Description"
+ }
+ }
+ }
+ },
+ "controls": {
+ "required": [
+ "__empty_control_section__"
+ ]
+ }
+
+ }
+}
\ No newline at end of file
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+..
+.. Copyright (C) 2019 AT&T Intellectual Property
+
+
+Step-by-step xApp Descriptor Design Example
+===========================================
+
+Step 1: Gather Information
+--------------------------
+Collect the information about the following items
+
+* xApp name
+* Version of the xApp descriptor
+* Details of the xApp containers
+* (Optional) xApp-specific configuration parameters
+* (Optional) Metrics produced
+* (Optional) Ports for messaging
+* (Optional) Liveness and readiness probes methods
+
+Step 2: Download config-file.json skeleton
+------------------------------------------
+Download the config-file.json file :download:`here <config-file.json>`
+
+Step 3: Change xapp_name and version
+------------------------------------
+In the config-file.json file, change the values for "xapp_name" and "version"
+
+.. note:: If xapp-onboarder is configured with ALLOW_REDEPLOY=False, you cannot reuse the same version number between onboarding.
+
+Step 4: Fill in the container information
+-----------------------------------------
+The container section in the config-file.json is a list of container properties structure. For each container, give it a unique name. Specify the docker image registry, docker image name, and docker iamge tag. Optionally. Please make sure that the docker registry is accessible from the RIC platform instance to which the xApp will be deployed. If you want to specify the contianer entry point, you can specify the command used to start the container.
+
+
+
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+..
+.. Copyright (C) 2019 AT&T Intellectual Property
+
+
+xApp Descriptor JSON Schema
+===========================
+
+Introduction
+------------
+
+JSON schema is used to describe the attributes and values in the xApp descriptor config-file.json file. The xApp onboarding process verifies the types and values of the xApp parameters in the descriptor. If mismatches are found, xApp onboarding will return failure. The schema file consists of two parts: sections that are static and cannot be changed for different xApp, and xApp specific controls section. When an operator is onboarding an xApp that defines a control section, he/she will provide the controls section schema with together with the xApp descriptor.
+
+The xapp_onboarder will combine the schema files into one.
+
+Control Section Schema
+----------------------
+.. note:: No control section schema is needed if your xApp doesn't need a controll section in the config-file.json.
+
+You can submit arbitrary schema for the controls section. However, if the xApp descriptor contains a controls section, you have to provide the correct schema that describes it. If the xApp does not require a control section, you can ignore the control section schema. It is highly recommended to use draft-07 schema. The following is a skeleton schema that you can use
+
+.. code-block::
+
+ {
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "$id": "#/controls",
+ "type": "object",
+ "title": "Controls Section Schema",
+ "required": [
+ "REQUIRED_ITEM_1",
+ "REQUIRED_ITEM_2"
+ ],
+ "properties": {
+ "REQUIRED_ITEM_1": {REQUIRED_ITEM_1_SUB_SCHEMA},
+ "REQUIRED_ITEM_2": {REQUIRED_ITEM_2_SUB_SCHEMA}
+ }
+ }
+
+
+Embedded JOSN Schema
+--------------------
+The following JSON schema is provided by the xApp-onboarder. It defines the JSON file structure of the config-file.json file except the control section.
+Expand the following link to read more details.
+
+.. toggle-header::
+ :header: **embedded JSON schema**
+
+ .. literalinclude:: embedded-schema.json
+ :language: JSON
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+..
+.. Copyright (C) 2019 AT&T Intellectual Property
+
+
+xApp Descriptor Guide
+=====================
+
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Index:
+
+ guide/descriptor.rst
+ guide/schema.rst
+ guide/example.rst
+
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+..
+.. Copyright (C) 2019 AT&T Intellectual Property
+
+
+xApp Onboarder
+==============
+
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+
+ overview.rst
+ guide_index.rst
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+..
+.. Copyright (C) 2019 AT&T Intellectual Property
+
+Project Overview
+================
+
+Introduction
+------------
+
+xApp onboarder provides the xapp onboarding service to operators. It consumes the xApp descriptor and optionally additional schema file, and produces xApp helm charts.
+xApp onboarder also provides CLI tools for local testing and debuging.
+
+
+.. image:: images/onboard.png
+ :scale: 50 %
+ :align: center
+
+
+
+Change logs
+-----------
++------------+--------------+-------------------------------------------------------------------------------------------------+
+| Version | Date | Description |
++============+==============+=================================================================================================+
+|1.0.0 | Mar 23 2020 | First release |
++------------+--------------+-------------------------------------------------------------------------------------------------+
+|1.0.1 | May 13 2020 | **Bug fix:** add a work-around for backward compatibility. Now xapp onboarder writes the xApp |
+| | | descriptor and schema json files into xApp helm charts. |
++------------+--------------+-------------------------------------------------------------------------------------------------+
+
+Configurations
+--------------
+
+xApp onboarder uses the following environment parameters to configurate its instance.
+
++----------------------+----------------------+-------------------------------------------------------------------------------------------------+
+| Enviroment Variable | Default Value | Description |
++======================+======================+=================================================================================================+
+| CHART_WORKSPACE_PATH | /tmp/xapp_onboarder | Temporary directory for xApp helm chart generation |
++----------------------+----------------------+-------------------------------------------------------------------------------------------------+
+| CHART_REPO_URL | \http://0.0.0.0:8080 | URL for local helm repo that stores the onboarded xApp helm chart |
++----------------------+----------------------+-------------------------------------------------------------------------------------------------+
+| HTTP_TIME_OUT | 10 | Timeout value for outgoing REST API calls |
++----------------------+----------------------+-------------------------------------------------------------------------------------------------+
+| HELM_VERSION | 2.12.3 | Version of the helm client |
++----------------------+----------------------+-------------------------------------------------------------------------------------------------+
+| HTTP_RETRY | 3 | Number of http retries for outgoing REST API calls |
++----------------------+----------------------+-------------------------------------------------------------------------------------------------+
+| ALLOW_REDEPLOY | True | Whether to allow reusing version number when onboard xApps |
++----------------------+----------------------+-------------------------------------------------------------------------------------------------+
+| CHART_WORKSPACE_SIZE | 500 MB | Size limit of the CHART_WORKSPACE_PATH temporary directory |
++----------------------+----------------------+-------------------------------------------------------------------------------------------------+
+| FLASK_PORT | 8888 | Port the xApp onboarder will listen to |
++----------------------+----------------------+-------------------------------------------------------------------------------------------------+
+| FLASK_DEBUG | True | Enable HTTP server debug messages |
++----------------------+----------------------+-------------------------------------------------------------------------------------------------+
deps =
sphinx
sphinx-rtd-theme
+ sphinxcontrib-contentui
sphinxcontrib-httpdomain
recommonmark
lfdocs-conf
basepython = python3
deps = sphinx
sphinx-rtd-theme
+ sphinxcontrib-contentui
sphinxcontrib-httpdomain
recommonmark
lfdocs-conf
Code Review / it / dev.git / commitdiff
