docs/developer-guides.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. ===============LICENSE_START=======================================================
   4 .. Copyright (C) 2019 AT&T Intellectual Property
   5 .. ===================================================================================
   6 .. This documentation file is distributed under the Creative Commons Attribution
   7 .. 4.0 International License (the "License"); you may not use this file except in
   8 .. compliance with the License.  You may obtain a copy of the License at
   9 ..
  10 .. http://creativecommons.org/licenses/by/4.0
  11 ..
  12 .. This file is distributed on an "AS IS" BASIS,
  13 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 .. See the License for the specific language governing permissions and
  15 .. limitations under the License.
  16 .. ===============LICENSE_END=========================================================
  17
  18 .. contents::
  19    :depth: 3
  20    :local:
  21
  22 Developer-Guides
  23 ================
  24
  25 Overview
  26 ------------------
  27
  28 The Amber release of the it/dep repo provides deployment artifacts for the O-RAN SC
  29 Near Realtime RIC.  The components in the deployment are spread onto two Kubernetes
  30 clusters, one for running the Near Realtime RIC, the other for running auxilary
  31 functions such as the dashboards.  These two clusters are referred to as the RIC and
  32 AUX clusters respectively.
  33
  34 This document describe the deployment artifacts, how theye are organized, and how to
  35 contribute for modifications, additions, and other enhancements to these artifacts.
  36
  37 Deployment Organization
  38 ------------------------
  39 To organize the deployments of the compoents, the various O-RAN SC Near Realtime RIC
  40 and auxilary components are organized into three groups: infrastructure, platform,
  41 and auxilary, or ric-infra, ric-platform, and ric-aux respectively.
  42
  43 The **ric-infra** group is expected to be deployed in each Kubernetes cluster.  It
  44 consists of components such as Kong ingress controller, Helm chart repo, Tiller for
  45 xApp deployment, as well as various credentials.  This group is deployed in both the
  46 RIC and AUX clusters.
  47
  48 The **ric-platform** group is deployed in the RIC cluster.  It consists of all Near
  49 Realtime RIC Platform components, including:
  50
  51 - DBaaS
  52 - E2 Termination
  53 - E2 Manager
  54 - A1 Mediator
  55 - Routing Manager
  56 - Subscription Manager
  57 - xApp manager
  58 - VESPA Manager
  59 - Jaeger Adapter
  60 - Resource Status Manager
  61
  62 The **ric-aux** group is deployed in the AUX cluster.  It consists of components that
  63 facilitate the operation of Near Realtime RIC and receiving inputs from the Near Realtime
  64 RIC.  In Amber release, this group includes the following:
  65
  66 - ONAP VES Collector
  67 - ONAP DMaaP Message Router
  68 - RIC Dashboard
  69
  70 In addition, this group also include ONAP AAF and ONAP Portal.
  71
  72
  73
  74 Directory Structure
  75 -------------------
  76
  77 The directories of the it/dep repo is organized as the following.
  78
  79 ::
  80
  81   |-- LICENSES.txt
  82   |-- README.md
  83   |-- RECIPE_EXAMPLE
  84   |-- bin
  85   |-- ci
  86   |-- docs
  87   |-- etc
  88   |-- ric-aux
  89   |   |-- 80-Auxiliary-Functions
  90   |   |-- 85-Ext-Services
  91   |   `-- README.md
  92   |-- ric-common
  93   |   |-- Common-Template
  94   |   |-- Docker-Credential
  95   |   |-- Helm-Credential
  96   |   `-- Initcontainer
  97   |-- ric-infra
  98   |   |-- 00-Kubernetes
  99   |   |-- 15-Chartmuseum
 100   |   |-- 20-Monitoring
 101   |   |-- 30-Kong
 102   |   |-- 40-Credential
 103   |   |-- 45-Tiller
 104   |   `-- README.md
 105   |-- ric-platform
 106   |   |-- 50-RIC-Platform
 107   |   |-- 55-Ext-Services
 108   |   `-- README.md
 109   `-- tox.ini
 110
 111 The deployment artifacts of these deployment groups are placed under the ric-infra,
 112 ric-platform, and ric-aux directories.  These directories are structured similarly
 113 where underneath each group is a list of numbered sub-groups.  The numbering is
 114 based on the order that how different sub-groups would be deployed within the same
 115 Kubernetes cluster.  For example, the 50-RIC-Platform subgroup should be deployed
 116 before the 55-Ext-Services subgroup.  And all subgroups in the ric-infra group
 117 should be deployed before the sub-groups in the ric-platform group, as indicated
 118 by they sub-group numbers being lower than those of the ric-platform group.
 119
 120 Within each numbered subgroup, there is a **helm** directory and a **bin** directory.
 121 The bin directory generally contains the install and uninstall script for deploying
 122 all the Helm charts of the subgroup.  The helm directory contains the helm charts
 123 for all the components within the subgroup.
 124
 125 At the top level, these is also a bin directory, where group level deployment and
 126 undeployment scripts are located.  For example, the **deploy-ric-platform** script
 127 iterates all the subgroups under the ric-platform group, and calls the install script
 128 of each subgroup to deploy the components in each subgroup.
 129
 130 Recipes
 131 --------
 132 **Recipe** is an important concept for Near Realtime RIC deployment.  Each
 133 deployment group has its own recipe.  Recipe provides a customized specification
 134 for the components of a deployment group for a specific dpeloyment site.  The
 135 RECIPE_EXAMPLE directory contains the example recipes for the three deployment
 136 groups.
 137
 138
 139
 140 Helm Chart Structure
 141 --------------------
 142
 143
 144 Common Chart
 145 ^^^^^^^^^^^^
 146
 147 Indiviudal Deployment Tasks
 148 ---------------------------
 149
 150
 151 Deploying a 1-node Kubernetes Cluster
 152 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 153
 154 Deploying Near Realtime RIC
 155 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 156
 157 Deploying Near Realtime RIC xApp
 158 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 159
 160
 161
 162 Processes
 163 ---------
 164 Contribution to then it/dep repository is open to all community members by following
 165 the standard Git/Gerrit contribution and Gerrit review flows.
 166
 167 Code change submitted to the it/dep repo of the gerrit.o-ran-sc.org is first reviewed by both an automated verification Jenkins job and human reviewers.
 168
 169
 170 Actions
 171 -------
 172
 173