# xApp Template
###### tags: `Construction`
# On-boarding and Deploying xApps

1. To onboard an xApp, the xApp descriptor and its schema will be submitted to the xApp onboarder.
2. xApp onboarder generates helm charts and distributes them to the local helm repo in the RIC platform instance
3. Operator triggers xApp deployment
4. (OPTIONAL)Through RIC dashboard, download an values.yaml file that contains the default xApp configuration parameters
5. (OPTIONAL) Modify the xApp configuration parameters, upload the new configuration to appmgr
6. Appmgr combines the xApp helm charts from local helm repo and the new configuration
7. Appmgr creates an xApp instance
# Writing xApps

## 1 Introduction
In order for an xApp to be deployable, it needs to have an xApp descriptor (JSON) that describes the xApp's configuration parameters and information the RIC platform needs to configure the RIC platform for the xApp. The xApp developer will also need to provide a JSON schema for the descriptor.

An xApp may do any of the following:
* Read initial configuration parameters (passed in the xApp descriptor).
* Receive updated configuration parameters.
* Send and receive messages.
* Read and write into a persistent shared data storage (key-value store).
* Receive A1-P policy guidance messages - specifically operations to create or delete a policy instance (JSON payload on an RMR message) related to a given policy type.
* Define a new A1 policy type.
* Make subscriptions via E2 interface to the RAN, receive E2 INDICATION messages from the RAN, and issue E2 POLICY and CONTROL messages to the RAN.
* Report metrics related to its own execution or observed RAN events.

## 2 xApp Specification and LocaL Testing
### 2.1 xApp development

RIC xApps to be deployable, they need to have a proper docker image generated and available in a accessible docker registry, and a valid xApp descriptor.

### 2.2 xApp Descriptor


**Name**: (REQUIRED) this is the unique identifier to address an xApp. A valid xApp descriptor must includes the xapp name attribute.

**Version**: (REQUIRED) this is the semantic version number of the xApp descriptor. It defines the version numbers of the xApp artifacts (e.g., xApp helm charts) that will be generated from the xApp descriptor. Together with the xapp name, they defines the unique identifier of an xApp artifact that can be on-boarded, distributed and deployed.

**Containers**: (REQUIRED) This section defines a list of containers that the xApp will run. For each container, a structure that defines the container name, image registry, image name, image tag, and the command that it runs is defined. **The name and images are REQUIRED**. The command and argument lists are optional


**Messaging**: (Optional) this section defines the communication ports for each containers. It may define list of RX and TX message types, and the
A1 policies for RMR communications implemented by this xApp. Each defined port will creates a K8S service port that are mapped to the container at the same port number. This section requires ports that contains the port name, port number, which container it is for. For RMR port, it also requires tx and rx message types, and A1 policy list.


**Liveness probes**: (Optional) The liveness probe section defines how liveness probe is defined in the xApp helm charts. You can provide ether a command or a http helm liveness probe definition in JSON format. This section requires initialDelaySeconds, periodSeconds, and either httpGet or exec. The following is an example for http-based liveness probes.

**Readiness probes**: (Optional) The readiness probe section defines how readiness probe is defined in the xApp helm charts. You can provide ether a command or a http helm readiness probe definition in JSON format. This section requires initialDelaySeconds, periodSeconds, and either httpGet or exec.The following is an example for http-based readiness probes.

### 2.3 Schema for the xApp Descriptor

The schema file consists of two parts: sections that are static and cannot be changed for different xApp, and xApp specific controls section. When an operator is onboarding an xApp that defines a control section, he/she will provide the controls section schema with together with the xApp descriptor. The xapp onboarder will combine the schema files into one.


### 2.4 Local Testing

To test onboard an xApp, you can utilize either the DMS CLI tool. The DMS CLI tool will return errors that can help you pinpoint problems in your xApp descriptor.

#### 2.4.1 Prerequisites
The DMS CLI tool requires a host with docker daemon and local helm repo installed.We recommend using helm version v3.5.x and above. If you are using a Ubuntu host, you can use the following commands to prepare your environment for the DMS CLI tool.

$ sudo apt-get update
$ sudo apt install docker.io

#### 2.4.2 Create a local helm repo
You can create a local helm repo by running the following command

$ 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

### 2.5 Test On-boarding using xApp-onboarder/DMS CLI Tools
Please replace the blue text with the correct values for your xApp.

# Install xapp-onboarder DMS CLI
$ git clone "https://gerrit.o-ran-sc.org/r/ric-plt/appmgr" dev/xapp_onboarder
$ pip3 install ./

# Set up the environment variables for DMS CLI connection
$ export CHART_REPO_URL="http://0.0.0.0:8090"

# It should return True if your DMS CLI tool is properly connected to the RIC instance cli health
# Onboard your xApp. Please refer to xApp descriptor for preparing for the xApp descriptor
# Make sure that you have the xapp descriptor
# config file and the schema file at your local file system cli onboard CONFIG_FILE_PATH SHCEMA_FILE_PATH

If onboarding fails, the DMS CLI tool will return you messages that indicate where the errors are in the descriptor.

### 2.6 xApp deployment and undeployment
To deploy an xApp named ”EXAMPLE-XAPP”, you need a fully functioning near real-time RIC platform. Please refer to the other guide about how to create one.
To deploy xApp using the DMS CLI , run the following commands.

# Run DMS CLI to install xapp
$ dms_cli install --xapp_chart_name=XAPP_CHART_NAME --version=VERSION -- namespace=NAMESPACE
# Run DMS CLI to uninstall xapp
$ dms_cli uninstall --xapp_chart_name=XAPP_CHART_NAME --namespace=NAMESPACE

## 3 Functions
The RIC platform provides a set of functions that the xApps can use to accomplish their tasks.

### 3.1 Registering/De-registering Xapp
The xapp after deployment needs to be registered to the RIC platform by sharing its config to the platform.
Otherwise RMR and other functionalities described later will not be available for the xapp. This could be accomplished using REST API's described below.

1. Registration to xapp manager

Xapp indicates RIC platform i.e xapp manager to register itself.

The "configPath", is the http URL. If this parameter is not set the default will be set to "/ric/v1/config". This parameter indicates the xapp manager that when it queries for the xapp config, it needs to add this URL in its request.

2. Get Config query from xapp to xapp manager

Xapp needs to implement this REST interface when xapp manager queries for it. If during registration if the configuration is already sent, xapp manager would not request again for the configuration.
This request will be sent by xapp-manager.

### 3.2 Messaging - RMR
RMR is a message router library which an application can use to send messages to other RMR based applications. The destination of each message is governed by the message type and subscription ID, or just the message type. RMR is re- sponsible for establishing and managing each connection freeing the application from any network connectivity management.The library is available in repo

#### 3.2.1 Using RMR from C++
RMR functionality is inherent to the Xapp Core System of C++ xApp frame- work. The section provides snippets of key RMR functions to be used.

#### 3.2.2 Using RMR from go
RIC xApps can communicate with other each and with other RIC platform com- ponents via RMR, which is a very thin but robust library that allow applications to send and receives RMR messages. RMR message consists of message header and payload. The message header defines the type of the message to be sent, a subscription ID that identifies a subscription of routing entry, a MEID, which the global RAN name and a application specific transaction ID. The message payload carries the actual user data.

Below is a sample code that attempts to send RMR message:

### 3.3 Shared data layer - SDL
assert send summary [”message state”] == 0 Receive snippet:
Shared data layer provides xApps the capability to share data directly via database. SDL APIs provide simple yet flexible way to store and retrieve data while hiding all the unnecessary details such as type and location of database, all management operations of database layer such as high availability, scaling, load-balancing.
SDL uses following 4 environment variables to connect to Redis instance:
DBAAS SERVICE HOST, DBAAS SERVICE PORT, DBAAS SERVICE SENTINEL PORT and DBAAS MASTER NAME

### 3.4 Using R-NIB
RIC applications can obtain the list of GNBs connected/discovered, and as well as their connection status stored in RNIB.
#### 3.4.1 Using R-NIB from go
Following example shows how the GO applications can access RNIB and extract GNB related information.

## 4 Frameworks

The RIC platform currently provides frameworks that make it easier to construct xApps in go and C++.

### 4.1 Go framework

#### 4.1.1 Getting Started – A simple example xApp
The following is a sample xApp that receives RMR messages, stores message payload to SDL and echo the message back to the sender:


* RESTful (new resources can be injected dynamically)
* RMR (with message filtering based on application rules)
* Database backend services (with configurable namespaces, etc)
* Watching and populating config-map changes in K8S environment
* Logging (via MDCLOG + tracing support in the future)
* ASN.1 decoding and encoding

Include Kubernetes, Docker, RMR, SDL, E2 Node, E2 Termination, database and xApp Framework