docs/ric/installation-xapps.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-2020 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 **xApp Onboarding using CLI tool called dms_cli**
  19
  20 xApp onboarder provides a cli tool called dms_cli to fecilitate xApp onboarding service to operators. It consumes the xApp descriptor and optionally additional schema file, and produces xApp helm charts.
  21
  22
  23 Below are the sequence of steps to onboard, install and uninstall the xApp.
  24
  25 Step 1: (OPTIONAL ) Install python3 and its dependent libraries, if not installed.
  26
  27 Step 2: Prepare the xApp descriptor and an optional schema file. xApp descriptor file is a config file that defines the behavior of the xApp. An optional schema file is a JSON schema file that validates the self-defined parameters.
  28
  29 Step 3: Before any xApp can be deployed, its Helm chart must be loaded into this private Helm repository.
  30
  31 .. code:: bash
  32
  33    #Create a local helm repository with a port other than 8080 on host
  34    docker run --rm -u 0 -it -d -p 8090:8080 -e DEBUG=1 -e STORAGE=local -e STORAGE_LOCAL_ROOTDIR=/charts -v $(pwd)/charts:/charts chartmuseum/chartmuseum:latest
  35
  36 Step 4: Set up the environment variables for CLI connection using the same port as used above.
  37
  38 .. code:: bash
  39
  40    #Set CHART_REPO_URL env variable
  41    export CHART_REPO_URL=http://0.0.0.0:8090
  42
  43 Step 5: Install dms_cli tool
  44
  45 .. code:: bash
  46
  47    #Git clone appmgr
  48    git clone "https://gerrit.o-ran-sc.org/r/ric-plt/appmgr"
  49
  50    #Change dir to xapp_onboarder
  51    cd appmgr/xapp_orchestrater/dev/xapp_onboarder
  52
  53    #If pip3 is not installed, install using the following command
  54    yum install python3-pip
  55
  56    #In case dms_cli binary is already installed, it can be uninstalled using following command
  57    pip3 uninstall xapp_onboarder
  58
  59    #Install xapp_onboarder using following command
  60    pip3 install ./
  61
  62 Step 6: (OPTIONAL ) If the host user is non-root user, after installing the packages, please assign the permissions to the below filesystems
  63
  64 .. code:: bash
  65
  66    #Assign relevant permission for non-root user
  67    sudo chmod 755 /usr/local/bin/dms_cli
  68    sudo chmod -R 755 /usr/local/lib/python3.6
  69    sudo chmod -R 755 /usr/local/lib/python3.6
  70
  71 Step 7: Onboard your xApp
  72
  73 .. code:: bash
  74
  75    # Make sure that you have the xapp descriptor config file and the schema file at your local file system
  76    dms_cli onboard CONFIG_FILE_PATH SCHEMA_FILE_PATH
  77    OR
  78    dms_cli onboard --config_file_path=CONFIG_FILE_PATH --shcema_file_path=SCHEMA_FILE_PATH
  79
  80    #Example:
  81    dms_cli onboard /files/config-file.json /files/schema.json
  82    OR
  83    dms_cli onboard --config_file_path=/files/config-file.json --shcema_file_path=/files/schema.json
  84
  85 Step 8: (OPTIONAL ) List the helm charts from help repository.
  86
  87 .. code:: bash
  88
  89    #List all the helm charts from help repository
  90    curl -X GET http://localhost:8080/api/charts | jq .
  91
  92    #List details of specific helm chart from helm repository
  93    curl -X GET http://localhost:8080/api/charts/<XAPP_CHART_NAME>/<VERSION>
  94
  95 Step 9: (OPTIONAL ) Delete a specific Chart Version from helm repository.
  96
  97 .. code:: bash
  98
  99    #Delete a specific Chart Version from helm repository
 100    curl -X DELETE http://localhost:8080/api/charts/<XAPP_CHART_NAME>/<VERSION>
 101
 102 Step 10: (OPTIONAL ) Download the xApp helm charts.
 103
 104 .. code:: bash
 105
 106    dms_cli download_helm_chart XAPP_CHART_NAME VERSION --output_path=OUTPUT_PATH
 107    OR
 108    dms_cli download_helm_chart --xapp_chart_name=XAPP_CHART_NAME --version=VERSION --output_path=OUTPUT_PATH
 109
 110    Example:
 111    dms_cli download_helm_chart ueec 1.0.0 --output_path=/files/helm_xapp
 112    OR
 113    dms_cli download_helm_chart --xapp_chart_name=ueec --version=1.0.0 --output_path=/files/helm_xapp
 114
 115 Step 11: Install the xApp.
 116
 117 .. code:: bash
 118
 119    dms_cli install XAPP_CHART_NAME VERSION NAMESPACE
 120    OR
 121    dms_cli install --xapp_chart_name=XAPP_CHART_NAME --version=VERSION --namespace=NAMESPACE
 122
 123    Example:
 124    dms_cli install ueec 1.0.0 ricxapp
 125    OR
 126    dms_cli install --xapp_chart_name=ueec --version=1.0.0 --namespace=ricxapp
 127
 128 Step 12: (OPTIONAL ) Install xApp using helm charts by providing the override values.yaml.
 129
 130 .. code:: bash
 131
 132    #Download the default values.yaml
 133    dms_cli download_values_yaml XAPP_CHART_NAME VERSION --output_path=OUTPUT_PATH
 134    OR
 135    dms_cli download_values_yaml --xapp_chart_name=XAPP_CHART_NAME --version=VERSION --output_path=OUTPUT_PATH
 136
 137    Example:
 138    dms_cli download_values_yaml traffic-steering 0.6.0 --output-path=/tmp
 139    OR
 140    dms_cli download_values_yaml --xapp_chart_name=traffic-steering --version=0.6.0 --output-path=/tmp
 141
 142    #Modify values.yaml and provide it as override file
 143    dms_cli install XAPP_CHART_NAME VERSION NAMESPACE OVERRIDEFILE
 144    OR
 145    dms_cli install --xapp_chart_name=XAPP_CHART_NAME --version=VERSION --namespace=NAMESPACE --overridefile=OVERRIDEFILE
 146
 147    Example:
 148    dms_cli install ueec 1.0.0 ricxapp /tmp/values.yaml
 149    OR
 150    dms_cli install --xapp_chart_name=ueec --version=1.0.0 --namespace=ricxapp --overridefile=/tmp/values.yaml
 151
 152 Step 13: (OPTIONAL ) Uninstall the xApp.
 153
 154 .. code:: bash
 155
 156    dms_cli uninstall XAPP_CHART_NAME NAMESPACE
 157    OR
 158    dms_cli uninstall --xapp_chart_name=XAPP_CHART_NAME --namespace=NAMESPACE
 159
 160    Example:
 161    dms_cli uninstall ueec ricxapp
 162    OR
 163    dms_cli uninstall --xapp_chart_name=ueec --namespace=ricxapp
 164
 165 Step 14: (OPTIONAL) Upgrade the xApp to a new version.
 166
 167 .. code:: bash
 168
 169    dms_cli upgrade XAPP_CHART_NAME OLD_VERSION NEW_VERSION NAMESPACE
 170    OR
 171    dms_cli upgrade --xapp_chart_name=XAPP_CHART_NAME --old_version=OLD_VERSION --new_version=NEW_VERSION --namespace=NAMESPACE
 172
 173    Example:
 174    dms_cli upgrade ueec 1.0.0 2.0.0 ricxapp
 175    OR
 176    dms_cli upgrade --xapp_chart_name=ueec --old_version=1.0.0 --new_version=2.0.0 --namespace=ricxapp
 177
 178 Step 15: (OPTIONAL) Rollback the xApp to old version.
 179
 180 .. code:: bash
 181
 182    dms_cli rollback XAPP_CHART_NAME NEW_VERSION OLD_VERSION NAMESPACE
 183    OR
 184    dms_cli rollback --xapp_chart_name=XAPP_CHART_NAME --new_version=NEW_VERSION --old_version=OLD_VERSION --namespace=NAMESPACE
 185
 186    Example:
 187    dms_cli rollback ueec 2.0.0 1.0.0 ricxapp
 188    OR
 189    dms_cli rollback --xapp_chart_name=ueec --new_version=2.0.0 --old_version=1.0.0 --namespace=ricxapp
 190
 191 Step 16: (OPTIONAL) Check the health of xApp.
 192
 193 .. code:: bash
 194
 195    dms_cli health_check XAPP_CHART_NAME NAMESPACE
 196    OR
 197    dms_cli health_check --xapp_chart_name=XAPP_CHART_NAME --namespace=NAMESPACE
 198
 199    Example:
 200    dms_cli health_check ueec ricxapp
 201    OR
 202    dms_cli health_check --xapp_chart_name=ueec --namespace=ricxapp