ccsdk/oran
Architecture
Introduction
The CCSDK ORAN components add support for handling “A1 Policies” as defined for the O-RAN A1 interface.
The O-RAN A1 interface is defined by the O-RAN Alliance
Architecture for ONAP Istanbul release
This picture provides a overview of ONAP’s A1 Controller architecture, integration with other ONAP components and API resource/operation provided.
Developer Guide
Technical information about the O-RAN components (dependencies, configuration, running & testing) can be found in Developer Guide.
Developer Guide
This document provides a quickstart for developers of the CCSDK functions for O-RAN A1 Policies.
Source tree
This provides CCSDK with “A1 Policy Management Service” and “A1 Adapter” functions. Each resource is implemented independently in a package corresponding to its name.
A1 Policy Management Service
The ONAP CCSDK A1 Policy Management Service is a Java 11 web application built using the Spring Framework. Using Spring Boot dependencies, it runs as a standalone application.
A1 Policy Management Service provides a REST API for management of policies. It provides support for:
Supervision of clients (R-APPs) to eliminate stray policies in case of failure
Consistency monitoring of the SMO view of policies and the actual situation in the RICs
Consistency monitoring of RIC capabilities (policy types)
Policy configuration. This includes:
One REST API towards all RICs in the network
Query functions that can find all policies in a RIC, all policies owned by a service (R-APP), all policies of a type etc.
Maps O1 resources (ManagedElement) as defined in O1 to the controlling RIC.
The Policy Management Service can be accessed over the REST API, and with an equivalent interface using DMaaP. See A1 Policy Management Service API for more information about the API.
The configured A1 policies are stored persistently to survive a service restart.
Dependencies
This project uses various frameworks which are managed with Maven dependency management tool (see pom.xml file at root level) :
Swagger annotations
Springfox Automated JSON API documentation for APIs built with Spring
Immutable to generate simple, safe and consistent value objects
JSON in Java to parse JSON documents into Java objects
Apache Commons Net for network utilities and protocol implementations
DCAE SDK to get configuration from CBS
Lombok to generate code, such as getters and setters
Awaitility to test asynchronous functionality
To get a complete list of all dependencies, use command “mvn dependency:tree”.
Configuration
There are two configuration files for A1 Policy Management Service, config/application_configuration.json and config/application.yaml The first (config/application_configuration.json) contains configuration needed by the application, such as which near-RT-RICs, controller, or DMaaP topic to use. The second (config/application.yaml) contains logging and security configurations.
For more information about these configuration files can be found as comments in the sample files provided with the source code, or on the ONAP wiki
Static configuration - Settings that cannot be changed at runtime (application.yaml)
The file ./config/application.yaml is read by the application at startup. It provides the following configurable features:
server; configuration for the WEB server
used port for HTTP/HTTPS, this is however not the port numbers visible outside the container
SSL parameters for setting up using of key store and trust store databases.
webclient; configuration parameters for a web client used by the component
SSL parameters for setting up using of key store and trust store databases.
Usage of HTTP(S) Proxy; if configured, the proxy will be used for southbound access to the NearRT-RICs
logging; setting of of which information that is logged.
filepath; the local path to a file used for dynamic configuration (if used). See next chapter.
For details about the parameters in this file, see documentation in the file.
Dynamic configuration - Settings that can be changed at runtime (application_configuration.json or REST or Consul or ConfigMap)
The component has configuration that can be updated in runtime. This configuration can either be loaded from a file (accessible from the container), or from a CBS/Consul database (Cloudify), or using the Configuration REST API. The configuration is re-read and refreshed at regular intervals.
The configuration includes:
Optional Controller configuration, e.g. an SDNC instance (with A1-Adapter)
One entry for each near-RT-RIC, which includes:
The base URL of the near-RT-RIC
A optional list of O1 identifiers that near-RT-RIC is controlling. An application can query this service which near-RT-RIC should be addressed for which component (e.g. cells, sectors, locations, etc.) .
An optional reference to the controller to use, or excluded if the near-RT-RIC should be accessed directly from the A1 Policy Management Service.
Optional configuration for using of DMaaP. There can be one stream for requests to the component and an other stream for responses.
Controller configuration, which includes information on how to access the a1-adapter
One entry for each NearRT-RIC, which includes:
The base URL of the NearRT RIC
A list of O1 identifiers that the NearRT RIC is controlling. An application can query this service which NearRT RIC should be addressed for controlling (for instance) a given Cell.
An optional reference to the controller to use, or excluded if the NearRT-RIC can be accessed directly from this component.
Optional configuration for using of DMAAP. There can be one stream for requests to the component and an other stream for responses.
For details about the syntax of the file, there is an example in source code repository /config/application_configuration.json. This file is also included in the docker container /opt/app/policy-agent/data/application_configuration.json_example. Using CBS/Consul database for dynamic configuration —————————————————
Access to CBS is setup by means of environment variables. There is currently no support for setting these at on-boarding.
The following variables are required by the CBS:
CONSUL_HOST
CONSUL_PORT
CONFIG_BINDING_SERVICE
SERVICE_NAME
The CBS/Consul overrides the configuration file. So when CBS/Consul is used, the configuration file is ignored.
Configuration of security certs
The A1 Policy Management Service uses the default keystore and truststore that are built into the container. The paths and passwords for these stores are located in a yaml file, with an example is provided in the source code repository a1-policy-management/config/application.yaml
There is also Policy Management Service’s own cert in the default truststore for mocking purposes and unit-testing (ApplicationTest.java).
The default keystore, truststore, and application.yaml files can be overridden by mounting new files using the the docker “volumes” command for docker-compose or docker run command. Assuming that the keystore, truststore, and application.yaml files are located in the same directory as docker-compose, the volumes field should have these entries:
`volumes:`
`- ./new_keystore.jks:/opt/app/policy-agent/etc/cert/keystore.jks:ro`
`- ./new_truststore.jks:/opt/app/policy-agent/etc/cert/truststore.jks:ro`
`- ./new_application.yaml:/opt/app/policy-agent/config/application.yaml:ro`
The target paths in the container should not be modified.
Example docker run command for mounting new files (assuming they are located in the current directory):
docker run -p 8081:8081 -p 8433:8433 --name=policy-agent-container --network=nonrtric-docker-net --volume "$PWD/new_keystore.jks:/opt/app/policy-agent/etc/cert/keystore.jks" --volume "$PWD/new_truststore.jks:/opt/app/policy-agent/etc/cert/truststore.jks" --volume "$PWD/new_application.yaml:/opt/app/policy-agent/config/application.yaml" onap/ccsdk-oran-a1policymanagementservice:1.2.6-SNAPSHOT
A1 Adapter (Internal)
The O-RAN A1 Adapter provides an internal RESTCONF API that is used by the A1 Policy Management System when accessing the A1 Interface. This API is useful for test and verification but should not used otherwise.
See A1 ADAPTER API for details of this internal API.
Configuration of HTTP Proxy
In order to configure a HTTP Proxy for southbound connections:
Modify file: odlsli/src/main/properties/a1-adapter-api-dg.properties. This file is found in CCSDK/distribution for SDNC.
In a running container this file is found at /opt/onap/ccsdk/data/properties/a1-adapter-api-dg.properties
Variable a1Mediator.proxy.url must contain the full Proxy URL
After this configuration has been changed the A1 adapter needs to be either rebuilt, or restarted if the configuration is changed inside a container, or re-read by the container if externally accessible (e.g. K8s ConfigMap).
Offered APIs
Introduction
The north bound REST API of the A1 Policy Management Service provides convenient methods to handle policies.
Overall architecture for O-RAN A1 Policy functions
This picture provides a overview of ONAP’s A1 Controller architecture, integration with other ONAP components and API resource/operation provided.
API Version
APIs are described with a state version with “v” following the API Name,
e.g.: v2/policy.
The schema associated with a REST API must have its version number aligned
with that of the REST API.
API Table
API name |
|
|
|---|---|---|
A1 Policy Management Service API (NBI) |
||
A1 ADAPTER API (Internal) |
A1 Policy Management Service API
The A1 Policy Management Service API is described in more detail in A1 Policy Management Service API (html)
A1 ADAPTER API
The O-RAN A1 Adapter provides an internal RESTCONF API that is used by the A1 Policy Management System when accessing the A1 Interface. This API is useful for test and verification but should not be used otherwise.
The A1 Adapter API is described in more detail in A1 ADAPTER API (html)
Consumed APIs
Policy Management Service application is interacting with two ONAP APIs and the A1-P API.
CBS API
If Consul is used for configuring the A1 Policy Management Service the ONAP DCAE Config Binding Service is used.
DMaaP API
The A1 Policy Management Service API can also be accessed using ONAP DMaaP. To support this the DMaaP Message Router API is used.
O-RAN A1 interface for A1 Policies (A1-P)
Southbound, the ONAP A1 Policy functions communicate with near-RT-RIC RAN functions using the A1 interface, as defined by the O-RAN Alliance The A1 Interface - Application Protocol Specification (A1-AP) describe this interface. The specification can be viewed from the O-RAN Alliance website.
The Istanbul ONAP A1 Policy functions implement the A1 Policy parts (A1-P) of A1-AP versions v1.1, v2.0 and v3.0
An opensource implementation of a near-RT-RIC is available from O-RAN Software Community. It supports a pre-spec version of the A1-AP. The ONAP A1 Policy functions described here also supports this A1 version (A1-OSC).
Human Interfaces
The NON-RT RIC Control Panel in O-RAN-SC can be used to interact with the Policy Management Service. See NON-RT RIC Control Panel repo from the O-RAN-SC NONRTRIC Project.
Any “Rest Client” application may be used (Postman, …) to interact with the Policy Management Service application via the A1 Policy Management Service API
Release-Notes
This document provides the release notes for the release of the different parts of the ORAN project.
Version history Policy Management Service
Date |
Ver. |
Author |
Comment |
2020-09-10 |
1.0.0 |
Dan Timoney |
M4 version, Guilin Release |
2020-11-02 |
1.0.1 |
Dan Timoney |
RC1 version, Guilin Release |
2021-01-08 |
1.0.2 |
Dan Timoney |
Guilin Maintenance Release |
2020-11-30 |
1.1.0 |
Dan Timoney |
First version, Honolulu Release |
2021-02-23 |
1.1.1 |
Dan Timoney |
M3 version, Honolulu Release |
2021-03-25 |
1.1.2 |
Dan Timoney |
RC0 version, Honolulu Release |
2021-04-05 |
1.1.3 |
Dan Timoney |
RC1 version, Honolulu Release |
2021-04-19 |
1.1.4 |
Dan Timoney |
RC2 version, Honolulu Release |
2021-05-10 |
1.1.5 |
Dan Timoney |
Final version, Honolulu Release |
2021-09-02 |
1.2.0 |
Dan Timoney |
M3 version, Istanbul Release |
2021-09-16 |
1.2.1 |
Dan Timoney |
M4 version, Istanbul Release |
Version history A1 Adapter
Date |
Ver. |
Author |
Comment |
2019-09-10 |
1.0.0 |
Dan Timoney |
M4 version, Guilin Release |
2020-11-02 |
1.0.1 |
Dan Timoney |
RC1 version, Guilin Release |
2021-01-08 |
1.0.2 |
Dan Timoney |
Guilin Maintenance Release |
2020-11-30 |
1.1.0 |
Dan Timoney |
First version, Honolulu Release |
2021-02-23 |
1.1.1 |
Dan Timoney |
M3 version, Honolulu Release |
2021-03-25 |
1.1.2 |
Dan Timoney |
RC0 version, Honolulu Release |
2021-04-05 |
1.1.3 |
Dan Timoney |
RC1 version, Honolulu Release |
2021-04-19 |
1.1.4 |
Dan Timoney |
RC2 version, Honolulu Release |
2021-05-10 |
1.1.5 |
Dan Timoney |
Final version, Honolulu Release |
2021-09-02 |
1.2.0 |
Dan Timoney |
M3 version, Istanbul Release |
2021-09-16 |
1.2.1 |
Dan Timoney |
M4 version, Istanbul Release |
Release Data
Guilin, M4
Project |
CCSDK ORAN |
Repo/commit-ID |
ccsdk-oran/28d357836d89914e241c0fcd20239aff7498568e |
Release designation |
Guilin |
Release date |
2020-09-10 |
Purpose of the delivery |
Introducing ORAN, M4 version |
Guilin, RC1
Project |
CCSDK ORAN |
Repo/commit-ID |
ccsdk-oran/50a0abeaa63fa8103ae0e663ed2fcf6272b2637b |
Release designation |
Guilin |
Release date |
2020-11-02 |
Purpose of the delivery |
Introducing ORAN, RC1 version |
Guilin, Maintenance
Project |
CCSDK ORAN |
Repo/commit-ID |
ccsdk-oran/a36efc8971cb3eafa37e71de819060c0390e4aa4 |
Release designation |
Guilin Maintenance |
Release date |
2021-01-08 |
Purpose of the delivery |
Introducing ORAN, Maintenance version |
Honolulu, First version
Project |
CCSDK ORAN |
Repo/commit-ID |
ccsdk-oran/7f767b4455af5ea65bb69ce40a8ac998ddbca04f |
Release designation |
Honolulu |
Release date |
2020-11-30 |
Purpose of the delivery |
Improvements in ORAN, First version |
Honolulu, M3
Project |
CCSDK ORAN |
Repo/commit-ID |
ccsdk-oran/53c4d37cfdfc65a47431d27deb2764d277f62720 |
Release designation |
Honolulu |
Release date |
2021-02-23 |
Purpose of the delivery |
Improvements in ORAN, M3 version |
Honolulu, RC0
Project |
CCSDK ORAN |
Repo/commit-ID |
ccsdk-oran/e9e8fda7dc7facf288d1652152ceb358977c1006 |
Release designation |
Honolulu |
Release date |
2021-03-25 |
Purpose of the delivery |
Improvements in ORAN, RC0 version |
Honolulu, RC1
Project |
CCSDK ORAN |
Repo/commit-ID |
ccsdk-oran/a17d643fcee3240c98bf3e101c1eac5a2b53119a |
Release designation |
Honolulu |
Release date |
2021-04-05 |
Purpose of the delivery |
Improvements in ORAN, RC1 version |
Honolulu, RC2
Project |
CCSDK ORAN |
Repo/commit-ID |
ccsdk-oran/b4f33c2d6fef60df2e48d81e2f7cdbf6a66cb30d |
Release designation |
Honolulu |
Release date |
2021-04-19 |
Purpose of the delivery |
Improvements in ORAN, RC2 version |
Honolulu, Final version
Project |
CCSDK ORAN |
Repo/commit-ID |
ccsdk-oran/9f99c19662c8190ad821144f3f4406c60d48025c |
Release designation |
Honolulu |
Release date |
2021-05-10 |
Purpose of the delivery |
Improvements in ORAN, Final version |
Istanbul, M3
Project |
CCSDK ORAN |
Repo/commit-ID |
ccsdk-oran/8a70f00cc986df657ddd3ab92f449f9e1690cf62 |
Release designation |
Istanbul |
Release date |
2021-09-02 |
Purpose of the delivery |
Improvements in ORAN, M3 version |
Istanbul, M4
Project |
CCSDK ORAN |
Repo/commit-ID |
ccsdk-oran/9241d1d555884ba2d28eab9ed692f50a660ba2a5 |
Release designation |
Istanbul |
Release date |
2021-09-16 |
Purpose of the delivery |
Improvements in ORAN, M4 version |