.. limitations under the License.
.. ===============LICENSE_END=========================================================
-**Loading xApp Helm Charts**
+**xApp Onboarding using CLI tool called dms_cli**
-The RIC Platform App Manager deploys RIC applications (a.k.a. xApps) using Helm charts stored in a private local Helm repo.
-The Helm local repo is deployed as a sidecar of the App Manager pod, and its APIs are exposed using an ingress controller with TLS enabled.
-You can use both HTTP and HTTPS to access it.
+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.
-Before any xApp can be deployed, its Helm chart must be loaded into this private Helm repo.
-The example below shows the command sequences that upload and delete the xApp Helm charts:
-#. Load the xApp Helm charts into the Helm repo;
-#. Verify the xApp Helm charts;
-#. Call App Manager to deploy the xApp;
-#. Call App Manager to delete the xApp;
-#. Delete the xApp helm chart from the private Helm repo.
+Below are the sequence of steps to onboard, install and uninstall the xApp.
-In the following example, the <INGRESS_CONTROLLER_IP> is the IP address that the RIC cluster ingress controller is listening to.
-If you are using a VM, it is the IP address of the main interface.
-If you are using REC clusters, it is the DANM network IP address you assigned in the recipe.
-If the commands are executed inside the host machine, you can use "localhost" as the <INGRESS_CONTROLLER_IP>.
+Step 1: (OPTIONAL ) Install python3 and its dependent libraries, if not installed.
+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.
+
+Step 3: Before any xApp can be deployed, its Helm chart must be loaded into this private Helm repository.
+
+.. code:: bash
+
+ #Create a local helm repository with a port other than 8080 on host
+ 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
+
+Step 4: Set up the environment variables for CLI connection using the same port as used above.
+
+.. code:: bash
+
+ #Set CHART_REPO_URL env variable
+ export CHART_REPO_URL=http://0.0.0.0:8090
+
+Step 5: Install dms_cli tool
+
+.. code:: bash
+
+ #Git clone appmgr
+ git clone "https://gerrit.o-ran-sc.org/r/ric-plt/appmgr"
+
+ #Change dir to xapp_onboarder
+ cd appmgr/xapp_orchestrater/dev/xapp_onboarder
+
+ #If pip3 is not installed, install using the following command
+ yum install python3-pip
+
+ #In case dms_cli binary is already installed, it can be uninstalled using following command
+ pip3 uninstall xapp_onboarder
+
+ #Install xapp_onboarder using following command
+ pip3 install ./
+
+Step 6: (OPTIONAL ) If the host user is non-root user, after installing the packages, please assign the permissions to the below filesystems
+
+.. code:: bash
+
+ #Assign relevant permission for non-root user
+ sudo chmod 755 /usr/local/bin/dms_cli
+ sudo chmod -R 755 /usr/local/lib/python3.6
+ sudo chmod -R 755 /usr/local/lib/python3.6
+
+Step 7: Onboard your xApp
+
+.. code:: bash
+
+ # Make sure that you have the xapp descriptor config file and the schema file at your local file system
+ dms_cli onboard CONFIG_FILE_PATH SCHEMA_FILE_PATH
+ OR
+ dms_cli onboard --config_file_path=CONFIG_FILE_PATH --shcema_file_path=SCHEMA_FILE_PATH
+
+ #Example:
+ dms_cli onboard /files/config-file.json /files/schema.json
+ OR
+ dms_cli onboard --config_file_path=/files/config-file.json --shcema_file_path=/files/schema.json
+
+Step 8: (OPTIONAL ) List the helm charts from help repository.
.. code:: bash
- # load admin-xapp Helm chart to the Helm repo
- curl -L --data-binary "@admin-xapp-1.0.7.tgz" http://<INGRESS_CONTROLLER_IP>:32080/helmrepo
+ #List all the helm charts from help repository
+ curl -X GET http://localhost:8080/api/charts | jq .
- # verify the xApp Helm charts
- curl -L http://<INGRESS_CONTROLLER_IP>:32080/helmrepo/index.yaml
+ #List details of specific helm chart from helm repository
+ curl -X GET http://localhost:8080/api/charts/<XAPP_CHART_NAME>/<VERSION>
- # test App Manager health check API
- curl -v http://<INGRESS_CONTROLLER_IP>:32080/appmgr/ric/v1/health/ready
- # expecting a 200 response
+Step 9: (OPTIONAL ) Delete a specific Chart Version from helm repository.
- # list deployed xApps
- curl http://<INGRESS_CONTROLLER_IP>:32080/appmgr/ric/v1/xapps
- # expecting a []
+.. code:: bash
- # deploy xApp, the xApp name has to be the same as the xApp Helm chart name
- curl -X POST http://<INGRESS_CONTROLLER_IP>/appmgr/ric/v1/xapps -d '{"name": "admin-xapp"}'
- # expecting: {"name":"admin-app","status":"deployed","version":"1.0","instances":null}
+ #Delete a specific Chart Version from helm repository
+ curl -X DELETE http://localhost:8080/api/charts/<XAPP_CHART_NAME>/<VERSION>
- # check again deployed xApp
- curl http://<INGRESS_CONTROLLER_IP>:32080/appmgr/ric/v1/xapps
- # expecting a JSON array with an entry for admin-app
+Step 10: (OPTIONAL ) Download the xApp helm charts.
- # check pods using kubectl
- kubectl get pods --all-namespaces
- # expecting the admin-xapp pod showing up
+.. code:: bash
+
+ dms_cli download_helm_chart XAPP_CHART_NAME VERSION --output_path=OUTPUT_PATH
+ OR
+ dms_cli download_helm_chart --xapp_chart_name=XAPP_CHART_NAME --version=VERSION --output_path=OUTPUT_PATH
+
+ Example:
+ dms_cli download_helm_chart ueec 1.0.0 --output_path=/files/helm_xapp
+ OR
+ dms_cli download_helm_chart --xapp_chart_name=ueec --version=1.0.0 --output_path=/files/helm_xapp
+
+Step 11: Install the xApp.
- # underlay the xapp
- curl -X DELETE http://<INGRESS_CONTROLLER_IP>:32080/appmgr/ric/v1/xapps/admin-xapp
+.. code:: bash
+
+ dms_cli install XAPP_CHART_NAME VERSION NAMESPACE
+ OR
+ dms_cli install --xapp_chart_name=XAPP_CHART_NAME --version=VERSION --namespace=NAMESPACE
+
+ Example:
+ dms_cli install ueec 1.0.0 ricxapp
+ OR
+ dms_cli install --xapp_chart_name=ueec --version=1.0.0 --namespace=ricxapp
+
+Step 12: (OPTIONAL ) Install xApp using helm charts by providing the override values.yaml.
- # check pods using kubectl
- kubectl get pods --all-namespaces
- # expecting the admin-xapp pod gone or shown as terminating
+.. code:: bash
+
+ #Download the default values.yaml
+ dms_cli download_values_yaml XAPP_CHART_NAME VERSION --output_path=OUTPUT_PATH
+ OR
+ dms_cli download_values_yaml --xapp_chart_name=XAPP_CHART_NAME --version=VERSION --output_path=OUTPUT_PATH
+
+ Example:
+ dms_cli download_values_yaml traffic-steering 0.6.0 --output-path=/tmp
+ OR
+ dms_cli download_values_yaml --xapp_chart_name=traffic-steering --version=0.6.0 --output-path=/tmp
+
+ #Modify values.yaml and provide it as override file
+ dms_cli install XAPP_CHART_NAME VERSION NAMESPACE OVERRIDEFILE
+ OR
+ dms_cli install --xapp_chart_name=XAPP_CHART_NAME --version=VERSION --namespace=NAMESPACE --overridefile=OVERRIDEFILE
+
+ Example:
+ dms_cli install ueec 1.0.0 ricxapp /tmp/values.yaml
+ OR
+ dms_cli install --xapp_chart_name=ueec --version=1.0.0 --namespace=ricxapp --overridefile=/tmp/values.yaml
+
+Step 13: (OPTIONAL ) Uninstall the xApp.
+
+.. code:: bash
- # to delete a chart
- curl -L -X DELETE -u helm:helm http://<INGRESS_CONTROLLER_IP>:32080/api/charts/admin-xapp/0.0.5
+ dms_cli uninstall XAPP_CHART_NAME NAMESPACE
+ OR
+ dms_cli uninstall --xapp_chart_name=XAPP_CHART_NAME --namespace=NAMESPACE
+
+ Example:
+ dms_cli uninstall ueec ricxapp
+ OR
+ dms_cli uninstall --xapp_chart_name=ueec --namespace=ricxapp
+
+Step 14: (OPTIONAL) Upgrade the xApp to a new version.
+
+.. code:: bash
+
+ dms_cli upgrade XAPP_CHART_NAME OLD_VERSION NEW_VERSION NAMESPACE
+ OR
+ dms_cli upgrade --xapp_chart_name=XAPP_CHART_NAME --old_version=OLD_VERSION --new_version=NEW_VERSION --namespace=NAMESPACE
+
+ Example:
+ dms_cli upgrade ueec 1.0.0 2.0.0 ricxapp
+ OR
+ dms_cli upgrade --xapp_chart_name=ueec --old_version=1.0.0 --new_version=2.0.0 --namespace=ricxapp
+
+Step 15: (OPTIONAL) Rollback the xApp to old version.
+
+.. code:: bash
+
+ dms_cli rollback XAPP_CHART_NAME NEW_VERSION OLD_VERSION NAMESPACE
+ OR
+ dms_cli rollback --xapp_chart_name=XAPP_CHART_NAME --new_version=NEW_VERSION --old_version=OLD_VERSION --namespace=NAMESPACE
+
+ Example:
+ dms_cli rollback ueec 2.0.0 1.0.0 ricxapp
+ OR
+ dms_cli rollback --xapp_chart_name=ueec --new_version=2.0.0 --old_version=1.0.0 --namespace=ricxapp
+
+Step 16: (OPTIONAL) Check the health of xApp.
+
+.. code:: bash
-For more xApp deployment and usage examples, please see the documentation for the it/test repository.
+ dms_cli health_check XAPP_CHART_NAME NAMESPACE
+ OR
+ dms_cli health_check --xapp_chart_name=XAPP_CHART_NAME --namespace=NAMESPACE
+
+ Example:
+ dms_cli health_check ueec ricxapp
+ OR
+ dms_cli health_check --xapp_chart_name=ueec --namespace=ricxapp
Code Review / it / dep.git / commitdiff