RIC Dashboard¶
RIC Dashboard Overview¶
The O-RAN SC RIC Dashboard provides administrative and operator functions for a radio access network (RAN) controller. The web app is built as a single-page app using an Angular (version 8) front end and a Java (version 11) Spring-Boot (version 2.1) back end.
Project Resources¶
The source code is available from the Linux Foundation Gerrit server:
The build (CI) jobs are in the Linux Foundation Jenkins server:
Issues are tracked in the Linux Foundation Jira server:
Project information is available in the Linux Foundation Wiki:
A1 Mediator¶
The Dashboard interfaces with the A1 Mediator. This platform component is accessed via HTTP/REST requests using a client that is generated from an API specification published by the A1 Mediator team.
The A1 Mediator supports fetching and storing configuration of applications, which is referred to as getting or setting a policy. The Dashboard UI provides screens to view and modify configuration data for such applications. As of this writing, the only application that is managed via the A1 Mediator interface is the Admission Control (“AC”) application.
Application Manager¶
The Dashboard interfaces with the Application Manager. This platform component is accessed via HTTP/REST requests using a client that is generated from an API specification published by the Application Manager team.
The Application Manager supports deploying, undeploying and configuring applications in the RIC. The Dashboard UI provides screens for these functions.
Automatic Neighbor Relation Application¶
The Dashboard interfaces with the Automatic Neighbor Relation (ANR) application. This RIC application is accessed via HTTP/REST requests using a client that is generated from an API specification published by the ANR team.
This RIC application discovers and manages the Neighbor Cell Relation Table (NCRT). The Dashboard UI provides screens to view and modify NCRT data.
E2 Manager¶
The Dashboard interfaces with the E2 Manager. This platform component is accessed via HTTP/REST requests using a client that is generated from an API specification published by the E2 Manager team.
The E2 Manager platform component supports connecting and disconnecting RAN elements. The Dashboard UI provides controls for operators to create “ENDC” and “X2” connections, and to disconnect RAN elements.
RIC Dashboard Configuration and Deployment¶
This documents the configuration and deployment of the O-RAN SC RIC Dashboard web application, which is often deployed together with the ONAP Portal.
Configuration¶
The application requires the following configuration files:
application.properties
key.properties
portal.properties
In the usual Kubernetes deployment, all file contents are provided by a configuration map.
Application Properties¶
The file application.properties
must be provided when the
application is launched, either in the current working directory or in
a config
subdirectory (latter is preferred). The Helm chart that
deploys the application should mount this file appropriately.
Many properties have default values cached within the application, in
file src/main/resources/application.properties
. Properties with
default values do NOT need to be repeated in a deployment-specific
configuration. Properties without default values MUST be specified in
a deployment-specific configuration.
The properties are listed below in alphabetical order.
a1med.url.prefix
A1 Mediator URL prefix. No useful default. Usually a service name
like http://ricplt-entry/a1mediator
a1med.url.suffix
A1 Mediator URL suffix. Default is the empty string.
anrxapp.url.prefix
ANR Application URL prefix. No useful default. Usually a service name
like http://ricxapp-entry/anr
anrxapp.url.suffix
ANR Application URL suffix. Default is the empty string.
appmgr.url.prefix
Application Manager URL prefix. No useful default. Usually a service
name like http://ricplt-entry/appmgr
appmgr.url.suffix
Application Manager URL suffix. Default is /ric/v1
.
caasingress.aux.url.prefix
CAAS-Ingress application URL prefix for the RIC Auxiliary cluster. No useful default.
caasingress.aux.url.suffix
CAAS-Ingress application URL suffix for the RIC Auxiliary cluster. Default is api
.
caasingress.insecure
Flag whether to disable SSL/TLS certificate and hostname verification. If true, the dashboard can communicate with a CAAS-Ingress endpoint that uses self-signed certificates.
caasingress.plt.url.prefix
CAAS-Ingress application URL prefix for the RIC Platform cluster. No useful default.
caasingress.plt.url.suffix
CAAS-Ingress application URL suffix for the RIC-PLT cluster. Default is api
.
e2mgr.url.prefix
E2 Manager URL prefix. No useful default. Usually a service name like
http://ricplt-entry/e2mgr
e2mgr.url.suffix
E2 Manager URL prefix. Default is /v1
.
mock.config.delay
Sleep period for mock methods in milliseconds. This mimics slow
endpoints. Default is 0
.
portalapi.appname
Application name expected at ONAP portal. Default is RIC Dashboard
portalapi.decryptor
Java class that decrypts ciphertext from Portal. Default is
org.oransc.ric.portal.dashboard.portalapi.PortalSdkDecryptorAes
.
portalapi.password
REST password expected at ONAP portal. No default value.
portalapi.security
Boolean flag whether the Dashboard limits access to users (browsers) that present security tokens set by the ONAP Portal. If false, no access control is performed, which is only appropriate for isolated lab testing.
portalapi.usercookie
Name of request cookie with user ID. Default is UserId
.
portalapi.username
REST user name expected at ONAP portal. No default value.
server.port
Port where the Tomcat server listens for requests. Default is 8080
.
metrics.url.ac
Url to the kibana source which visualizes AC App metrics. No default value and needs to be replaced with actual value during deployment time.
userfile
Path of file that stores user details. Default is users.json
.
Key Properties¶
The file key.properties
must be provided on the Java classpath for
the Spring-Boot application, as required by the EPSDK-FW library. The
Helm chart for the application should mount this file appropriately.
A sample file is in directory src/test/resources
.
The file must contain the following entries, listed here in alphabetical order.
cipher.enc.key
Encryption key used by the EPSDK-FW library. No default value.
Portal Properties¶
The file portal.properties
must be provided on the Java classpath
for the application, as required by the EPSDK-FW library. The Helm
chart for the application should mount this file appropriately. A
sample file is in directory src/test/resources
.
The file must contain the following entries, listed here in alphabetical order.
ecomp_redirect_url
Portal URL that is reachable by a user’s browser. This is a value
like
https://portal.api.simpledemo.onap.org:30225/ONAPPORTAL/login.htm
ecomp_rest_url
Portal REST URL that is reachable by the Dashboard back-end.
This is a value like http://portal-app.onap:8989/ONAPPORTAL/auxapi
portal.api.impl.class
Java class name. No default value. Value must be
org.oransc.ric.portal.dashboard.portalapi.PortalRestCentralServiceImpl
role_access_centralized
Selector for role access. No default value. Value must be remote
.
ueb_app_key
Unique key assigned by ONAP Portal to the RIC Dashboard application. No default value.
Deployment¶
A production server requires the configuration files listed above.
All files should be placed in a config
directory. That name is
important; Spring automatically searches that directory for the
application.properties
file. Further, that directory can easily be
placed on the Java classpath so the additional files can be found at
runtime.
On-Board Dashboard to ONAP Portal¶
When on-boarding the Dashboard to the ONAP Portal the administrator must supply the following information about the deployed instance:
- Dashboard URL that is reachable by a user’s browser. The domain of
this host name must match the Portal URL that is similarly reachable
by a user’s browser for cookie-based authentication to function as
expected. This should be a value like
http://dashboard.simpledemo.onap.org:8080
- Dashboard REST URL that is reachable by the Portal back-end server.
This can be a host name or an IP address, because it does not use
cookie-based authentication. This must be a URL with suffix “/api/v3”
for example
http://192.168.1.1:8080/api/v3
.
The Dashboard server only listens on a single port, so the examples above both use the same port number. Different port numbers might be required if an ingress controller or other proxy server is used.
After the on-boarding process is complete, the administrator must enter values from the Portal for the following properties explained above:
portalapi.password
portalapi.username
ueb_app_key
Launch Server¶
After creating, populating and mounting Kubernetes config maps
appropriately, launch the server with this command-line invocation to
include the config
directory on the Java classpath:
java -cp config:target/ric-dash-be-1.2.0-SNAPSHOT.jar \
-Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \
org.springframework.boot.loader.PropertiesLauncher
Alternately, to use the configuration in the “application-abc.properties” file, modify the command to have “spring.config.name=name” like this:
java -cp config:target/ric-dash-be-1.2.0-SNAPSHOT.jar \
-Dspring.config.name=application-abc \
-Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \
org.springframework.boot.loader.PropertiesLauncher
RIC Dashboard Developer Guide¶
This document provides a quickstart for developers of the O-RAN SC RIC Dashboard web application.
Prerequisites¶
- Java development kit (JDK), version 11 or later
- Maven dependency-management tool, version 3.4 or later
Other required tools including the Node Package Manager (npm) are fetched dynamically.
Clone and Update Submodules¶
After cloning the repository, initialize and update all git submodules like this:
git submodule init
git submodule update
Check the submodule status at any time like this:
git submodule status
Angular Front-End Application¶
The Angular 8 application files are in subdirectory webapp-frontend
.
Build the front-end application via mvn package
. For development and debugging,
build the application, then launch an ng development server using this command:
./ng serve --proxy-config proxy.conf.json
The app will automatically reload in the browser if you change any of the source files. The ng server listens for requests at this URL:
Spring-Boot Back-End Application¶
A development (not production) server uses local configuration and serves mock data that simulates the behavior of remote endpoints. The back-end server listens for requests at this URL:
The directory src/test/resources
contains usable versions of the required property
files. These steps are required to launch:
- Install all project jar files locally
- Set an environment variable via JVM argument:
-Dorg.oransc.ric.portal.dashboard=mock
- Run the JUnit test case
DashboardServerTest
which is not exactly a “test” because it never finishes.
These steps can be done with these commands:
mvn -Ddocker.skip=true -DskipTests=true install
mvn -Dorg.oransc.ric.portal.dashboard=mock -Dtest=DashboardTestServer test
Development user authentication¶
The development server requires basic HTTP user authentication for all requests. Like
the production server, it requires HTTP headers with authentication for Portal API
requests. The username and password are stored in constants in this Java class in
the src/test/java
folder:
org.oransc.ric.portal.dashboard.config.WebSecurityMockConfiguration
Like the production server, the development server also performs role-based authentication on requests. The user name-role name associations are also defined in the class shown above.
Production user authentication¶
The server uses the ONAP Portal’s “EPSDK-FW” library to support a single-sign-on (SSO) feature, which requires users to authenticate at the ONAP Portal UI. The RIC Dashboard can be on-boarded as an application on the ONAP Portal using its application on-boarding UI.
The server authenticates requests using cookies that are set by the ONAP Portal:
EPService
UserId
The EPService value is not checked. The UserId value is decrypted using a secret key shared with the ONAP Portal to yield a user ID. That ID must match a user’s loginId defined in the user manager.
The regular server checks requests for the following granted
authorities (role names), as defined in the java class DashboardConstants
.
A standard user can invoke all “GET” methods but not make changes.
A system administrator can invoke all methods (“GET”, “POST”, “PUT”,
“DELETE”) to make arbitrary changes:
Standard_User
System_Administrator
Use the following structure in a JSON file to publish a user for the user manager:
[
{
"orgId":null,
"managerId":null,
"firstName":"Demo",
"middleInitial":null,
"lastName":"User",
"phone":null,
"email":null,
"hrid":null,
"orgUserId":null,
"orgCode":null,
"orgManagerUserId":null,
"jobTitle":null,
"loginId":"demo",
"active":true,
"roles":[
{
"id":null,
"name":"Standard_User",
"roleFunctions":null
}
]
}
]
RIC Dashboard Release Notes¶
Version 1.3.0, 26 Nov 2019¶
- This is the Amber release version
- Revise e2-mgr-client to use API spec in new submodule ric-plt/e2mgr; removed cached copy
- Silence many Sonar complaints
- Revise license statements in documentation files
- Revise stats screen to drop mock load, pendulum, reporting items
- Remove ANR xApp
Version 1.2.4, 24 Oct 2019¶
- This version is used for the AT&T/Nokia co-create PIZ trials Nov 2019.
- Revise a1-med-client to use API spec in new submodule ric-plt/a1; removed cached copy
- Revise app manager client to use API spec in new submodule ric-plt/appmgr; removed cached copy
- Add Platform page showing Kubernetes pods in aux and platform obtained from CAAS-Ingress
- Update Angular libraries to recent stable versions
- Revise user controller to answer data sent by portal, drop the mock implementation
- Set global style for page titles
- Align page titles to top left,decrease font size
- Update EPSDK-FW to version 2.6
- Make constructor robust to missing caasingress.insecure property
- Repair bug that omitted slashes in CAAS-Ingress URL builder
- Improve the dark mode
- Show container ready count with total count
Version 1.2.3, 4 Oct 2019¶
- Serve unauthenticated user a login-at-portal page without using redirect
- Upgrade to Spring-Boot 2.1.9.RELEASE
Version 1.2.2, 27 Sep 2019¶
- Support Portal security using EPSDK-FW cookie and user management
Version 1.2.1, 20 Sep 2019¶
- Repair E2 URLs in front end like endc-setup/endcSetup
- Extend ANR mock feature to persist edits for demos
- Block whitespace in E2 IP input field validation
- Relax validation in E2 RAN name field validation
- Make RAN connection table robust to missing fields
- Install curl when building Docker image
Version 1.2.0, 11 Sep 2019¶
- Split URL properties into prefix/suffix parts
- Add jacoco plugin to back-end for code coverage
- Compile with Java version 11, use base openjdk:11-jre-slim
- Clean code of issues reported by Sonar
- Drop mock RAN names feature that supported R1 testing
- Extend mock endpoints to simulate delay seen in tests
- Move mock configuration classes into test area
- Update App manager client to spec version 0.1.7
- Add controller for page refresh of Angular routes
- Extend E2 mock configuration for demo purposes
- Add pattern for matching AC/admin application name
- Add custom (plain but not white-label) error page
- Synch A1 method paths in front-end and back-end
- Add xapp dynamic configuration feature
- Disable x-frame-options response header
- Repair app manager undeploy-app back/front methods
- Display AC xAPP metrics data via Kibana source (metrics.url.ac) on dashboard
- Pass AC policy parameter without parsing as JSON
- Use snake_case (not camelCase) names in AC policy front end
- Update A1 mediator client to spec version 0.10.3
- Extend AC control screen to read policy from A1
- Create loading-dialog component and service
- Showing the loading-dialog while making API call
- Add notification and error handling for xapp configuration
- Update E2 manager client to spec version 2.0.5 of 2019-09-11
- Display MC xAPP metrics data via Kibana source (metrics.url.mc) on dashboard
Version 1.0.5, 5 July 2019¶
- Upgrade to Angular version 8
- Upgrade to Spring-Boot 2.1.6.RELEASE
- Align AC xApp policy page title
- Update E2 manager client to spec version 20190703
- Add configuration-driven mock of E2 getNodebIdList
- Revise front-end components to use prefix ‘rd’
- Improve error handling in BE and FE code
- Revise the notification service to display multiple notifications
- Add JUnit test cases for controller methods
Version 1.0.4, 27 June 2019¶
- Add AC xApp neighbor control screen
- Add ANR xApp neighbor cell relation table
- Drop the pendulum xApp control screen
- Add column sorting on xApp catalog, xApp control, ANR
- Add disconnect-all button to RAN connection screen
- Extend E2 service with disconnect-all method
- Update ANR xApp client to spec version 0.0.8
- Update E2 manager client to spec version 20190620
- Adjust CSS and HTML for main container positioning
- Revise config property keys to use URL (not basepath)
- Left menu overlap main content fix
- Extend back-end controllers to return error details
- Add feature resilient to malformed instance data
- Extend Xapp Controller with config endpoints
- Add build number to dashboard version string
- Move mock admin screen user data to backend
- Update App manager client to spec version 0.1.5
- Move RAN connection feature to control screen
- Rework admin table
- Update the notification service
- Move RAN connection feature to control screen
- Repair deploy-app feature and use icon instead of text button
Version 1.0.3, 28 May 2019¶
- Add AC xApp controller to backend
- Add AC xApp interface to frontend
- Add RAN type radio selector to connection setup
- Update ANR xApp client to spec version 0.0.7
- Update E2 manager client to spec version 20190515
- Update xApp manager client to spec version 0.1.4
- Add get-version methods to all controllers
- Add simple page footer with copyright and version
- Add AC and ANR xApp services
- Rename signal service to E2 Manager service
- Use XappMgrService to replace ControlService and CatalogService
- Apply mat-table to control and catalog
- RAN Connection screen upgrade to mat-table
Version 1.0.2, 13 May 2019¶
- Update A1 mediator client to version 0.4.0
- Add E2 response message with timestamp and status code
- Fetch xAPP instance status information from xAPP Manager and display in dashboard
- Allow the user to initiate an E2 (X2) connection between RIC and gNB/eNB
- User input validations on connections between RIC and eNB/gNB in the dashboard
- Add ANR xApp backend with mock implementation
- Add undeploy xApp function
- Add shared confirm dialog
- Add shared notification
Version 1.0.1, 6 May 2019¶
- Add draft A1 Mediator API definition
- Use E2 Manager API definition dated 2 May 2019, with tag modifications
- Adjust group IDs and packages for name O-RAN-SC; drop ORAN-OSC
- Add ANR API spec and client code generator
- Update xApp Manager API spec to version 0.1.2
Version 1.0.0, 30 Apr 2019¶
- Initial version