1. xApp Configuration In-depth¶

The xApp Configuration has multiple aspects which need to be understood.

Firstly there are three JSON files that are used to define the configuration. One of the JSON files, xapp_metadata.json, is created by the developer and contains the descriptions and default values of the configuration options. The second configuration file, xapp_config.json, is generated by the xApp Helm Chart and can be used to override the default values of the configuration options defined in xapp_metadata.json at deployment time. Finally, the third configuration file, the xapp_endpoints.json, is also generated by the xApp Helm Chart on deployment and is used to store the dRAX RIC endpoints URLs and ports, which are auto discovered and used for seamless integration with the dRAX RIC.

There is also a backend Redis Database that can be used to override the configuration values set from either xapp_metadata.json or xapp_config.json at run-time. This also adds persistence, so if the xApp is restarted, any of these overriden values are still used.

The xApp Library provides a Settings class to manage and provide access to all the configuration values from within the xApp application itself.

To access the xApp configuration externally, the xApp Library exposes two xApp API endpoints: /config and /metadata. There are multiple ways of editing the configuration options during run-time. The users can use the dRAX Dashboard for a user friendly, GUI approach, or they can use the /config API endpoint to programmatically change the configuration options. Once the configuration options are changed in any way, the xApp Library Settings class will automatically save the changes to the Redis Database.

1.1 Overview of the xApp Configuration¶

In this subsection we describe the xApp Configuration in more detail. We will explain the configuration split into multiple files, and what they contain.

The xApp relies on three different configuration files:

1. The xapp_metadata.json: Required for every xApp, contains information about the xApp itself, including but not limited to the name of the xApp, a description, the date of the last modification, as well as the definitions of the configuration options of that xApp including their default values. This information is provided by the creator of the xApp and cannot be modified during run-time.
2. The xapp_config.json: This file is generated by the xApp Helm Chart on deployment. It is used to change the default values of the configuration that is defined in the xapp_metadata.json. Note, that this file is used to change the config on deployment, however, this file can be separately created and sent to the /config API endpoint to change the configuration during runtime. The dRAX Dashboard basically uses this principle to change the configuration during runtime.
3. The xapp_endpoints.json: This file is also generated by the xApp Helm Chart. The xApp Helm Chart already auto discovers the necessary endpoint of the dRAX RIC (Kafka, NATS, xApp Database, dRAX RIC API Gateway, etc.) which are necessary for proper xApp functionality and integration. However, the developer or user may choose to add additional endpoints of their choosing to make them accessible through the Settings class in the xApp itself.

When reading configuration (except for endpoints which are treated separately) the xApp first checks the xApp database for the configuration parameters, then if not present checks the configuration inside xapp_config.json, and if the configuration parameter is not present either, uses the default value from xapp_metadata.json. On the other hand, all writes during the lifetime of an xApp will be forwarded to xApp Database.

All three can be added using the builder pattern:

builder = xapp_lib.XAppBuilder("..", absolute=False)

builder.metadata("core/xapp_metadata.json")

builder.endpoints("config/xapp_endpoints.json")

builder.config("config/xapp_config.json")

xapp = builder.build()

NOTE: If for example the user during deployment does not need to change the default values defined in xapp_metadata.json, one can do so in the xApp Helm Chart by not generating the xapp_config.json. Still, the developers should leave the option for the xApp Builder to include this file if it exists. If the file does not exist, the xApp will just log that this file was not found, and us eteh default from the xapp-metadata.json.

1.2 xApp Metadata¶

The Metadata contains basic information and metadata about the xApp itself. Usually the metadata is included in the repository containing the xApp itself and is created by the developer. The list of configuration options can be expanded depending on the need, but this is only done in development. The data contained inside the xapp_metadata.json cannot be changed during runtime. To change the value of the configuration options defined here, one must use the /config API endpoint.

In the xApp Framework repository, we give an example of how the xapp_metadata.json can look like.

{
    "name": "xApp Name",
    "configName": "",
    "description": "xApp Description...",
    "last_modified": "06/07/2020 23:32:00",
    "config_options": [
        {
            "name": "LOG_LEVEL",
            "description": "Log stuff",
            "default": 10,
            "jsonSchemaOptions": {
                "type": "number"
            },
            "uiSchemaOptions": {}
        },
        {
            "name": "example_slider",
            "description": "Test string configuration option",
            "default": 10,
            "jsonSchemaOptions": {
                "type": "number",
                "minimum": 0,
                "maximum": 50
            },
            "uiSchemaOptions": {
                "ui:widget": "range"
            }
        },
        {
            "name": "someUrl",
            "description": "Test URL configuration option",
            "default": "url://some.url",
            "jsonSchemaOptions": {
                "type": "string"
            },
            "uiSchemaOptions": {}
        },
        {
            "name": "boolean",
            "description": "Test boolean configuration option",
            "default": true,
            "jsonSchemaOptions": {
                "type": "boolean"
            },
            "uiSchemaOptions": {
                "ui:widget": "select"
            }
        }

    ]
}

As can be seen, we define 4 configuration options: LOG_LEVEL, example_slider, someUrl, boolean. Each of them has a name, description, default value, and visualization options for the dRAX Dashboard. The visualization options are described in the How to create configuration option widgets on the dRAX Dashboard section.

1.3 xApp Runtime Configuration¶

The configuration options as seen before are defined in the xapp_metadata.json and loaded into the Settings class of the xApp. Changing the value of these configuration options can be done in multiple ways:

• During deployment time by defining the xapp_config.json through the xApp Helm Chart
• During runtime via the dRAX Dashboard
• During runtime using the /config xApp API endpoint

1.3.1 Setting xApp Configuration during runtime¶

If the user needs to change the xApp Configuration options default values on deployment, one can edit the xApp Helm Chart to generate the xapp_config.json file. In particular, the user can supply a values.yaml file containing the following:

### Define the xapp_config.json
xappConfig:
  LOG_LEVEL: 20
  example_slider: 50
  someUrl: "nats://{{ .Values.global.kubeIp }}:31000"
  boolean: false

The configuration options in this example (LOG_LEVEL, example_slider, someUrl, boolean) need to be defined in the xapp-metadata.json. When comparing with the previous subsection, the xapp_metadata.json example, we see that the LOG_LEVEL by default has the value of 10. However, if we use the above-mentioned values file for the xApp Helm Chart, the LOG_LEVEL will change to 20 during deployment time.

1.3.2 Changing xApp Configuration during runtime - dRAX Dashboard¶

The xApp Configuration can then further be changed during runtime. One way to achieve this is using the dRAX Dashboard. The dRAX Dashboard uses the xApps /metadata and /config API endpoints to retrieve information on the xApp. Then it can also use the /config API endpoint to change the runtime configuration of the xApp.

Simply navigate to the xApp Management -> Overview page of the dRAX Dashboard. Click the icon under the Detail column of your xApp. Expand the Configuration Parameters section to see all the configuration options of your xApp like shown on Figure: xApp example configuration options. Now change any value and click the Submit button. In the background, the dRAX Dashboard generates the equivalent of the xapp_config.json, and sends it to the xApp /config API endpoint. This triggers the xApp Library Settings class to apply the configuration change, but also to store this configuration change into the xApp Database for persistence.

Figure: xApp example configuration options

1.3.3 Changing xApp Configuration during runtime - xApp API¶

The configuration of an xApp can also be changed using the xApp /config API endpoint. To do so, we need to create the xapp_config.json. This JSON is then forwarded to the xApp /config API, which will trigger the Settings class in the xApp Library to adjust the xApp Configuration and save teh changes to the xApp Database for persistence. For example, if we want to change the LOG_LEVEL configuration option from our example, we can simply create the following xapp_config.json:

{
 'LOG_LEVEL': 20,
}

By creating such a JSON and sending it to the xApp /config API, the configuration options can be edited during runtime. The xApp API can be reached via the dRAX RIC API Gateway. Each xApp has their API endpoints exposed through the dRAX RIC API Gateway. You can use the:

/xappconfiguration/config/{xAppName}

API endpoint to reach the configuration of each xApp. You can get the xApp configuration from this endpoint and edit it. Details on the dRAX RIC API Gateway endpoints for the xApps can be seen on Swagger which can be reached at:

http://<kubernets_ip>:31315/api/v1/docs

Just substitute <kubernetes_ip> with the advertised address of your Kubernetes cluster.

1.4 xApp Endpoints¶

The xApp Endpoints are a list of urls explaining to the xApp where to find databases and event brokers. The xapp_endpoints.json, which is loaded by the xApp Builder, is filled with information how to reach all the necessary dRAX RIC hooks. Since this is generated by the xApp Helm Chart, these URLs and ports can also be auto discovered, which is what the xApp Helm Chart does. This way, the developer does not have to worry about how to properly connect to all the dRAX RIC hooks. Some of the default endpoints this file contains are:

The developer is however free to add additional xApp endpoints, so they can be accessible through the endpoints object in the Settings class. This can be done in the xApp Helm Chart. Edit the xApp Chart values.yaml file, and locate the xappEndPoints key:

...
### Define the xapp_endpoints.json
xappEnpoints:
  REDIS_URL: "redis://{{ .Release.Name }}-xapp-redis.{{ .Release.Namespace }}:6379"
  KAFKA_URL: "kafka://{{ .Values.global.kubeIp }}:31090"
  API_URL: "http://{{ .Values.global.kubeIp }}:31315"
  NATS_URL: "nats://{{ .Values.global.kubeIp }}:31000"
...

Here, the developer can add additional endpoints.

1.5 xApp Settings Class¶

Most configuration can be accessed through the Settings class, which abstracts away the peculiarities when dealing with configuration. The Settings class is in charge of setting the configuration options locally through the xApp configuration files. Furthermore, it is in charge of changing those configuration options once a change happens via the xApp API. Finally, it also stores the configuration in the xApp Database for persistence.

The Settings class can be obtained from the within the xApp via the method:

xapp.settings()

The following methods are then available from the Settings class:

### Loads a config file in the format of the xapp_config.json to override values in xapp_metadata.json
load(filename: str)   

### Wipes values stored in the Redis Database
wipe()

### Sets the Ready Flag - this can be used by the application to specify whether it is ready to run
set_ready(ready: bool)

### Gets the Ready Flag - this can be used by the application to retrieve whether it is ready to run
get_ready() -> bool

### Sets a specific configuration value (in the Redis Database) where key is the configuration option
set_config(key: str, value: str)

### Gets a configuration option (using the precedence checking order)
get_config(key: str) -> str

### Sets a whole config in the Redis Database supplied in JSON format of key value pairs
set_whole_config(config: str)

### Gets the whole config from the Redis Database in JSON format of key value pairs
get_whole_config() -> str

1.6 How to create configuration option widgets on the dRAX Dashboard¶

The dashboard front-end makes use of the react-jsonschema-form library to visualize the xApp configuration form. Changing the "jsonSchemaOptions" and "uiSchemaOptions" objects within the xApp configuration xapp_metadata.json, will change the way the form appears on the browser. e.g.

  {
    "name": "example_slider",
    "description": "Test string configuration option",
    "default": 10,
    "jsonSchemaOptions": {
      "type": "number",
      "minimum": 0,
      "maximum": 50
    },
    "uiSchemaOptions": {
      "ui:widget": "range"
    }
  },

Will create a configuration option named “example_slider”, with a default value of 10. Then the jsonSchemaOptions define that this is a number, with a range of (0-50). The uiSchemaOptions defines this as a “range” widget, which is a slider. Therefore, the dRAX Dashboard will use this data to display a slider.

For more information and how to modify these options check :

https://react-jsonschema-form.readthedocs.io/en/latest/usage/widgets/

The visualization library used can be found here:

https://github.com/rjsf-team/react-jsonschema-form