-###################################################################################
-# ============LICENSE_START=======================================================
-#
-# ================================================================================
-# Copyright (C) 2020 Hcl Technologies Limited.
-# ================================================================================
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-# ============LICENSE_END=========================================================
-###################################################################################
+.. ============LICENSE_START=======================================================
+..
+.. ================================================================================
+.. Copyright (C) 2020 Hcl Technologies Limited.
+.. ================================================================================
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+.. ============LICENSE_END=========================================================
Important
-^^^^^^^^^^
+^^^^^^^^^
The redis-cluster currently is NOT part of RIC platform & hence is completely optional.
This piece of document has been created as part of delivery item for below jira ticket
https://jira.o-ran-sc.org/browse/RIC-109
supporting desired pod anti-affinity for high availability as per the ticket.
Overview
-^^^^^^^^^^
+^^^^^^^^
This document describes the environment/conditions used to test the feasibility of Redis
cluster set-up as detailed in the above ticket. Redis Cluster is a distributed implementation
of Redis with high performance goals. More details at https://redis.io/topics/cluster-spec
Environment Set-Up
-^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^
The set up was tested with kubernetes v1.19 cluster with
#. Pod topology spread constraint enabled
Reference: https://kubernetes.io/docs/concepts/workloads/pods/pod-topology-spread-constraints
#. Three worker nodes in the kubernet cluster
Execution
-^^^^^^^^^^
+^^^^^^^^^
Once environment is set-up, a redis-cluster can be set up using the helm-chart (also provided with
this commit). Once cluster is running, any master/slave of the redis instance pods can be deleted which
will be compensated automatically by new instances
.. code:: bash
- git clone "https://gerrit.o-ran-sc.org/r/ric-plt/ric-dep"
+ git clone "https://gerrit.o-ran-sc.org/r/ric-plt/ric-dep"
Modify the deployment recipe
----------------------------
-Edit the recipe files ./RECIPE_EXAMPLE/example_recipe.yaml.
+Edit the recipe files ./RECIPE_EXAMPLE/example_recipe_latest_stable.yaml (which is
+a softlink that points to the latest release version). "example_recipe_latest_unstable.yaml
+points to the latest example file that is under current development.
.. code:: bash
ricip: ""
auxip: ""
+- Deployment scripts support both helm v2 and v3. The deployment script will determine the helm version installed in cluster during the deployment.
- To specify which version of the RIC platform components will be deployed, update the RIC platform component container tags in their corresponding section.
- You can specify which docker registry will be used for each component. If the docker registry requires login credential, you can add the credential in the following section. Please note that the installation suite has already included credentials for O-RAN Linux Foundation docker registries. Please do not create duplicate entries.
.. code:: bash
cd ric-dep/bin
- ./install -f ../RECIPE_EXAMPLE/PLATFORM/example_recipe.yaml
+ ./install -f ../RECIPE_EXAMPLE/PLATFORM/example_recipe_latest_stable.yaml
Checking the Deployment Status
After a reboot of the VM, and a suitable delay for initialization,
all the containers should be running again as shown above.
+
+RIC Applications
+----------------
+
+.. include:: installation-xapps.rst
+
+OPTIONALLY use Redis Cluster (instead of Redis standalone)
+----------------------------------------------------------
+
+.. include:: installation-rediscluster.rst
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. ===============LICENSE_START=======================================================
+.. Copyright (C) 2019-2020 AT&T Intellectual Property
+.. ===================================================================================
+.. This documentation file is distributed under the Creative Commons Attribution
+.. 4.0 International License (the "License"); you may not use this file except in
+.. compliance with the License. You may obtain a copy of the License at
+..
+.. http://creativecommons.org/licenses/by/4.0
+..
+.. This file is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+.. ===============LICENSE_END=========================================================
+
+**xApp Onboarding using CLI tool called dms_cli**
+
+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.
+
+
+Below are the sequence of steps to onboard, install and uninstall the xApp.
+
+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
+
+ #List all the helm charts from help repository
+ curl -X GET http://localhost:8080/api/charts | jq .
+
+ #List details of specific helm chart from helm repository
+ curl -X GET http://localhost:8080/api/charts/<XAPP_CHART_NAME>/<VERSION>
+
+Step 9: (OPTIONAL ) Delete a specific Chart Version from helm repository.
+
+.. code:: bash
+
+ #Delete a specific Chart Version from helm repository
+ curl -X DELETE http://localhost:8080/api/charts/<XAPP_CHART_NAME>/<VERSION>
+
+Step 10: (OPTIONAL ) Download the xApp helm charts.
+
+.. 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.
+
+.. 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.
+
+.. 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
+
+ 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
+
+ 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 / ric-plt / ric-dep.git / commitdiff