docs/developer-guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 ..
   4 .. Copyright (C) 2019 AT&T Intellectual Property
   5
   6 Developer-Guide
   7 ===============
   8
   9 .. contents::
  10    :depth: 3
  11    :local:
  12
  13 Overview
  14 ---------
  15
  16 The introduction of a new xApp to Near Realtime RIC consists of a number of steps:
  17
  18 1. xApp developer implements the xApp and packaging into a docker container;
  19 2. xApp developer creates a "descriptor" for the xApp describing how it can be configured;
  20 3. the xApp developer generates a testing Helm chart using tools provided in this repo and test xApp in a Kubernetes/Helm environment;
  21 4. the xApp developer submits the xApp "descriptor" along with the container image for on-boarding.
  22
  23 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.
  24
  25 The image below depicts this workflow.
  26
  27 .. image:: images/xapp-flow.png
  28    :scale: 50 %
  29    :align: center
  30
  31
  32 xApp Descriptor
  33 ---------------
  34 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.
  35
  36 An example pair of config and schema files can be found at the ric-app/admin repo, under its init directory:
  37 https://gerrit.o-ran-sc.org/r/gitweb?p=ric-app/admin.git;a=tree;f=init;hb=HEAD
  38
  39
  40
  41 Generating Helm Charts
  42 ----------------------
  43 The ric-xapp/bin/install script is provided for generating the xApp Helm chart.
  44
  45 The scrip will insert the xApp descriptor files into the standard xApp helm chart template, package it, and upload it to a Helm repository.
  46
  47 Prerequisites:
  48 - config-file.json file from the xApp descriptor;
  49 - schema.json file from the xApp descriptor;
  50 - full path with tag of the docker image of the xApp;
  51 - a recipe file that contains the full URL of the helm repo;
  52 - username and password of the helm repo.
  53
  54 Parameters:
  55
  56 +------------+----------------------------------------------------+
  57 | option     | Description                                        |
  58 +============+====================================================+
  59 |-n          |name of the xApp                                    |
  60 +------------+----------------------------------------------------+
  61 |-v          | version of the helm chart                          |
  62 +------------+----------------------------------------------------+
  63 |-f          | path of the recipe that contains the helm repo URL |
  64 +------------+----------------------------------------------------+
  65 |-I          | full docker image path                             |
  66 +------------+----------------------------------------------------+
  67 |-d          | path to the schema.json file                       |
  68 +------------+----------------------------------------------------+
  69 |-c          | path to the config-file.json file                  |
  70 +------------+----------------------------------------------------+
  71 |-h          | helm repo username                                 |
  72 +------------+----------------------------------------------------+
  73 |-p          | helm repo password                                 |
  74 +------------+----------------------------------------------------+
  75
  76
  77 Below is an example of the recipe file that specifies the Helm repo parameters:
  78 ::
  79
  80   global:
  81     # Docker registry from which RIC platform components pull the images
  82     repository: nexus3.o-ran-sc.org:10004
  83     # Name of the K8S docker credential that is onboarded by 20-credential
  84     repositoryCred: docker-reg-cred
  85     # Docker image pull policy
  86     imagePullPolicy: Always
  87     # Helm repo that will be used by xApp manager
  88     helmRepository: "https://helm-entry"
  89     # Certificate of the helm repo
  90     helmRepositoryCert: xapp-mgr-certs
  91     # Name of the K8S secret that contains the credential of the helm repo
  92     helmRepositoryCred: xapp-mgr-creds
  93     # The name of the tiller that xApp helm client talks to
  94
  95
  96 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:
  97 ::
  98
  99   curl -Lk -u $HELM_REPO_USERNAME:$HELM_REPO_PASSWORD "$HELM_REPO"/api/charts --data-binary "@/tmp/$CHART_NAME-$CHART_VERSION.tgz"
 100
 101
 102