Skip to content

1. Build your own x/rApp Development Environment

In certain use cases, the developer will need a more flexible approach than the xApp Dev environment. For example:

  • Edit the xApp Helm Chart
  • Add another Docker image to the xApp
  • Add certain files or packages to the xApp Core

In such cases, deploying the xApp Dev Environment will not be sufficient, as you don’t have such options. However, in this case you can create your own xApp Core Docker image, including any additional files you need to it, as well as edit the default xApp Helm Chart to create one specific to your xApp, including any additional Docker images. You can then enable the Developer Mode on your own xApp to have the same options as in the xApp Dev Environment.

In the following subsection, we assume that you are on the dRAX host machine, since it contains all the necessary tools pre-installed. If you are not working on the dRAX Host Machine, please check section (Alternative) Not using the dRAX Host Machine for details

NOTE: Since upgrading to the latest version of Kubernetes, we are now using ContainerD as the container runtime for Kubernetes. This means that you can still build your docker images using the docker tools, but you will have to then inject them into the ContainerD runtime.

1.1 Download the xApp Framework Source Code

To get the latest version of the xApp Framework source code, follow these steps:

1.2 1. Access the GitHub Repository

Go to the GitHub repository where the source code is hosted. You will find the .zip file containing the source code in the Releases section.

https://github.com/accelleran-ext/xapp-framework-package/releases

1.3 2. Download the Source Code

In the Releases section, locate the latest version of the .zip file for the xApp Framework. Download the .zip file to your local machine.

1.4 3. Extract the Code

Once downloaded, extract the contents of the .zip file using a command like this (adjust the filename as needed):

unzip xapp-framework-package-version.zip

NOTE: You will need to contact Accelleran and provide a GitHub username so that we can grant you access to this repository.

1.5 Edit and build your xApp Core Docker image

This repository contains the xApp Library, as well as an example on how to build your own xApp located in the example folder. To build your own xApp Core Docker image, we provide the default Dockerfile. There are two Dockerfiles:

  • Dockerfile - Used to generate the production version of the xApp
  • Dockerfile.dev - Used to generate the Development Environment version of your xApp

You can, therefore, edit the Dockerfile.dev according to you own needs and initiate a build by issuing the following command:

cd xapp-framework-package/example

sudo docker build -t my-xapp:0.1.0 --build-arg username=<GITHUB_USERNAME> --build-arg token=<GITHUB_TOKEN> -f Dockerfile.dev .

Here:

  • my-xapp: This is the name of your xApp Docker image, which we will need to also provide to the Helm Chart
  • 0.1.0: This is the version of the Docker image. We follow the semver versioning, so we also advise you to do the same
  • <GITHUB_USERNAME>: Replace this with the GitHub username that has access to the xApp Framework GitHub repository
  • <GITHUB_TOKEN>: This is the security token of your GitHub account

1.6 Inject Docker image into dRAX

Once your Docker image is built, it needs to be injected into the dRAX system, specifically it needs to be added to the ContainerD registry.

1.6.1 Save Docker image to file

To do this, we first need to save the image to a file using the Docker save command (more info on this command can be found on the following link. Here we can use the following command to save the Docker image to a tar file (assuming that the name of the docker image was my-xapp as used in the example in the previous section):

sudo docker save my-xapp > my-xapp.tar

1.6.2 Load Docker image into ContainerD

Now that you have your xApp Core Docker image in a file, you can inject it into ContainerD using the following command:

sudo ctr -n=k8s.io image import my-xapp.tar

1.7 Prepare the xApp Helm Chart

Once the Docker image is built, we need to prepare the xApp Helm Chart. The default xApp helm Chart is available in the example folder of the xApp Framework Git repository. Therefore, go to the following folder:

cd example/helm_chart/xapp

We need to edit the values.yaml file to point the xApp Helm Chart to use our previously built xApp Core Docker image. In our case the <app-name> is my-xapp, <xapp-version> is 0.1.0. Therefore, edit the values.yaml accordingly:

...

image:
 repository: <xapp-name>
 tag: "<xapp-version>"

...

You are of course free to now edit the xApp Helm Chart in any way you see fit, for example adding another Docker image to it, which we explain in the section How to add another microservice helm chart to the xApp.

You can now package your xApp Helm Chart which will generate a .tgz file:

helm package example/helm_chart/xapp

1.8 Deploy your xApp in Developer Mode

You can now deploy your xApp in Developer Mode, which will grant you the same options as the xApp Dev Environment. Your xApp will be deployed as a sandbox environment, which you can access, further develop and debug, start or stop the xApp, etc.

From this point on, you can use any of the development workflows as described in the Development Workflows section.

You can deploy the xApp on dRAX in a couple of ways.

1.8.1 Deploy xApp using the helm install command

To deploy the xApp using the helm install command, you can run the following command on the dRAX host machine:

helm install <xapp-name> /path/to/xAppHelmChart.tgz --set developerMode.enabled=true --set-string global.kubeIp=<drax-host-ip>

NOTE 1: You can give the deployment any generic name you want by changing the <xapp-name>. When deploying from the command line, using helm install, we also have to supply the dRAX Host IP as the global.kubeIp parameter in helm.

NOTE 2: You can also point to the path of the xApp helm Chart folder if it is on the dRAX Host Machine.

1.8.2 Deploy xApp using the dRAX API

You can deploy the xApp using the dRAX API. Specifically using the deployment/xapp API endpoint.

You will need to set the Developer Mode using a Helm Chart values file. Each Helm Chart, including the xApp Helm Chart, has its default values.yaml file (which you can see in example/helm_chart/xapp). You can either copy that file and edit it, or create a reduced version of the file by specifying just the fild that change (in this case the developer mode). Therefore, your values.yaml file can look like:

developerMode:
  enabled: true
  devPassword: "password1!"

Let's assume you save this into a my-xapp-values.yaml file. You can now deploy the xApp using the following API (here is an example curl command):

curl -X 'POST' \
'http://<drax-host-machine>:31315/api/deployment/xapp' \
-H 'accept: */*' \
-H 'Content-Type: multipart/form-data' \
-F 'file=@my-xapp.tgz;type=application/x-compressed-tar' \
-F 'values=@my-xapp-values.yaml;type=application/x-yaml' \
-F 'xAppForm={"xAppName":"my-xapp","organization":"Accelleran","team":"dRAX","version":"0.1.0","owner":"dRAX","method":"Upload Helm Chart","namespace":"default"}'

Here, as you can see you need to fill in the xApp Form part, by providing your xAppName, organisation, team, version, owner. Leave the method and namespace as is.

1.8.3 Deploy xApp using the dRAX Dashboard

You can also deploy your xApp using the dRAX Dashboard in a more visual, GUI way.

You also need to prepare your my-xapp-values.yaml file in the same way as done in section Deploy xApp using the dRAX API.

Navigate to the dRAX Dashboard on port 31315 on the dRAX Host Machine. Next, click the xApp Deployment button on the left side menu.

Select the Upload Helm Chart from the Deployment method drop down menu.

Next fill in the x/rApp Metadata: - xApp Name - Choose a name for your x/rApp - Organisation - Input the name of your organisation - Team - Input the name of your team - Version - Input the version of the x/rApp - Owner - Input the name of the Owner/Deployer - Namespace - We use the default namespace in Kubernetes, and this should only be changed in advanced cases and if you know what you are doing!

Next click the Choose a file button to select and upload your x/rApp Helm Chart .tgz file.

You can click the Choose a file (Optional Values file) to select and upload the my-xapp-values.yaml file for the x/rApp Helm Chart.

Finally, click the Submit button to deploy the x/rApp.

1.9 (Optional) Mount a host folder inside your xApp

The xApp Helm Chart also has an optional feature, which is to mount a folder from the dRAX host machine inside the xApp Core container. This can be useful:

  • The files located in that mounted folder will be shared between the host and xApp Core
  • When the xApp is deleted, the files in the mounted folder will still be present on the host machine
  • Provides an easy way to share files from the host to inside the xApp Core

To enable such a folder, edit the helm install command used during the deployment of the xApp as follows:

helm install <xapp-name> /path/to/xAppHelmChartFolder --set developerMode.enabled=true --set developerMode.hostPath=/path/to/shared/folder/on/host  --set-string global.kubeIp=<drax-host-ip>

NOTE: The developerMode.hostPath uses the absolute path to a folder on the host machine. This folder will be mounted by default to the following folder inside the xApp Core container:

/home/xapp/xapp_core/dev.

You can, for example, mount the whole example folder from the xApp Framework git repository, making the python files automatically saved on the host machine. This way even if you delete the xApp, your code will be preserved. Also, if you deploy another xApp, you can mount the same folder into it, getting your code into the second xApp automatically.

1.10 (Alternative) Not using the dRAX Host Machine

1.10.1 xApp Core Docker Image

In case you are not on the dRAX Host Machine, you will have to install the following dependencies: - docker (more details can be found on Docker's official page)

Once this is done, you can proceed with downloading the xApp Framework source code, edit and build your image locally and save the Docker image in a file.

You then need to copy the my-xapp.tar (or however you called it) file over to the dRAX Host Machine.

Once the file is on the dRAX Host Machine, you then need to load the file into ContainerD on the dRAX Host Machine. This means that this parts needs to be done on the dRAX Host Machine.

1.10.2 xApp Helm Chart

As for the xApp Helm Chart, you can also prepare the Helm chart on a different machine, however you need to copy it over to the dRAX Host Machine if you want to deploy the xApp using the helm install command.

You can however also deploy your xApps programmatically using the dRAX API or via the dRAX Dashboard in a visual way. In these cases you do not have to copy over the xApp Helm Chart.