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
10 .. http://creativecommons.org/licenses/by/4.0
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=========================================================
18 **xApp Onboarding using CLI tool called dms_cli**
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.
23 Below are the sequence of steps to onboard, install and uninstall the xApp.
25 Step 1: (OPTIONAL ) Install python3 and its dependent libraries, if not installed.
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.
29 Step 3: Before any xApp can be deployed, its Helm chart must be loaded into this private Helm repository.
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
36 Step 4: Set up the environment variables for CLI connection using the same port as used above.
40 #Set CHART_REPO_URL env variable
41 export CHART_REPO_URL=http://0.0.0.0:8090
43 Step 5: Install dms_cli tool
48 git clone "https://gerrit.o-ran-sc.org/r/ric-plt/appmgr"
50 #Change dir to xapp_onboarder
51 cd appmgr/xapp_orchestrater/dev/xapp_onboarder
53 #If pip3 is not installed, install using the following command
54 yum install python3-pip
56 #In case dms_cli binary is already installed, it can be uninstalled using following command
57 pip3 uninstall xapp_onboarder
59 #Install xapp_onboarder using following command
62 Step 6: (OPTIONAL ) If the host user is non-root user, after installing the packages, please assign the permissions to the below filesystems
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
71 Step 7: Onboard your xApp
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
78 dms_cli onboard --config_file_path=CONFIG_FILE_PATH --shcema_file_path=SCHEMA_FILE_PATH
81 dms_cli onboard /files/config-file.json /files/schema.json
83 dms_cli onboard --config_file_path=/files/config-file.json --shcema_file_path=/files/schema.json
85 Step 8: (OPTIONAL ) List the helm charts from help repository.
89 #List all the helm charts from help repository
90 curl -X GET http://localhost:8080/api/charts | jq .
92 #List details of specific helm chart from helm repository
93 curl -X GET http://localhost:8080/api/charts/<XAPP_CHART_NAME>/<VERSION>
95 Step 9: (OPTIONAL ) Delete a specific Chart Version from helm repository.
99 #Delete a specific Chart Version from helm repository
100 curl -X DELETE http://localhost:8080/api/charts/<XAPP_CHART_NAME>/<VERSION>
102 Step 10: (OPTIONAL ) Download the xApp helm charts.
106 dms_cli download_helm_chart XAPP_CHART_NAME VERSION --output_path=OUTPUT_PATH
108 dms_cli download_helm_chart --xapp_chart_name=XAPP_CHART_NAME --version=VERSION --output_path=OUTPUT_PATH
111 dms_cli download_helm_chart ueec 1.0.0 --output_path=/files/helm_xapp
113 dms_cli download_helm_chart --xapp_chart_name=ueec --version=1.0.0 --output_path=/files/helm_xapp
115 Step 11: Install the xApp.
119 dms_cli install XAPP_CHART_NAME VERSION NAMESPACE
121 dms_cli install --xapp_chart_name=XAPP_CHART_NAME --version=VERSION --namespace=NAMESPACE
124 dms_cli install ueec 1.0.0 ricxapp
126 dms_cli install --xapp_chart_name=ueec --version=1.0.0 --namespace=ricxapp
128 Step 12: (OPTIONAL ) Install xApp using helm charts by providing the override values.yaml.
132 #Download the default values.yaml
133 dms_cli download_values_yaml XAPP_CHART_NAME VERSION --output_path=OUTPUT_PATH
135 dms_cli download_values_yaml --xapp_chart_name=XAPP_CHART_NAME --version=VERSION --output_path=OUTPUT_PATH
138 dms_cli download_values_yaml traffic-steering 0.6.0 --output-path=/tmp
140 dms_cli download_values_yaml --xapp_chart_name=traffic-steering --version=0.6.0 --output-path=/tmp
142 #Modify values.yaml and provide it as override file
143 dms_cli install XAPP_CHART_NAME VERSION NAMESPACE OVERRIDEFILE
145 dms_cli install --xapp_chart_name=XAPP_CHART_NAME --version=VERSION --namespace=NAMESPACE --overridefile=OVERRIDEFILE
148 dms_cli install ueec 1.0.0 ricxapp /tmp/values.yaml
150 dms_cli install --xapp_chart_name=ueec --version=1.0.0 --namespace=ricxapp --overridefile=/tmp/values.yaml
152 Step 13: (OPTIONAL ) Uninstall the xApp.
156 dms_cli uninstall XAPP_CHART_NAME NAMESPACE
158 dms_cli uninstall --xapp_chart_name=XAPP_CHART_NAME --namespace=NAMESPACE
161 dms_cli uninstall ueec ricxapp
163 dms_cli uninstall --xapp_chart_name=ueec --namespace=ricxapp
165 Step 14: (OPTIONAL) Upgrade the xApp to a new version.
169 dms_cli upgrade XAPP_CHART_NAME OLD_VERSION NEW_VERSION NAMESPACE
171 dms_cli upgrade --xapp_chart_name=XAPP_CHART_NAME --old_version=OLD_VERSION --new_version=NEW_VERSION --namespace=NAMESPACE
174 dms_cli upgrade ueec 1.0.0 2.0.0 ricxapp
176 dms_cli upgrade --xapp_chart_name=ueec --old_version=1.0.0 --new_version=2.0.0 --namespace=ricxapp
178 Step 15: (OPTIONAL) Rollback the xApp to old version.
182 dms_cli rollback XAPP_CHART_NAME NEW_VERSION OLD_VERSION NAMESPACE
184 dms_cli rollback --xapp_chart_name=XAPP_CHART_NAME --new_version=NEW_VERSION --old_version=OLD_VERSION --namespace=NAMESPACE
187 dms_cli rollback ueec 2.0.0 1.0.0 ricxapp
189 dms_cli rollback --xapp_chart_name=ueec --new_version=2.0.0 --old_version=1.0.0 --namespace=ricxapp
191 Step 16: (OPTIONAL) Check the health of xApp.
195 dms_cli health_check XAPP_CHART_NAME NAMESPACE
197 dms_cli health_check --xapp_chart_name=XAPP_CHART_NAME --namespace=NAMESPACE
200 dms_cli health_check ueec ricxapp
202 dms_cli health_check --xapp_chart_name=ueec --namespace=ricxapp