.. SPDX-License-Identifier: CC-BY-4.0
-.. Copyright 2020 Nordix Foundation
+.. Copyright 2021 Nordix Foundation
.. _architecture:
************
-The CCSDK ORAN components provides handling of the O-RAN A1 interface.
+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 <https://www.o-ran.org>`_
-*********************************************
-Global NBI architecture for Frankfurt release
-*********************************************
-Following illustration provides a global view about Non-Real-Time-RIC architecture,
+************************************
+Architecture for ONAP Honolulu release
+************************************
+
+This picture provides a overview of ONAP's A1 Controller architecture,
integration with other ONAP components and API resource/operation provided.
.. image:: ../media/ONAP-A1ControllerArchitecture.png
Developer Guide
***************
-Technical information about the ORAN components (dependencies, configuration, running & testing) could be found in :ref:`developer_guide`.
+Technical information about the O-RAN components (dependencies, configuration, running & testing) can be found in :ref:`developer_guide`.
.. SPDX-License-Identifier: CC-BY-4.0
-.. Copyright 2020 Nordix Foundation
+.. Copyright 2021 Nordix Foundation
Consumed APIs
=============
CBS API
*******
-The CBS API is used to get the dynamic configuration of the service, such as available Near-RT RICs.
-
-::
-
- CBS_GET_ALL
+If *Consul* is used for configuring the A1 Policy Management Service the `ONAP DCAE Config Binding Service <https://docs.onap.org/projects/onap-dcaegen2/en/honolulu/sections/apis/configbinding.html>`_ is used.
*********
DMAAP API
*********
-The DMaaP API is used to provide the possibility to interact with the Policy Management Service through DMaaP Message
-Router.
+The A1 Policy Management Service API can also be accessed using *ONAP DMaaP*. To support this the `DMaaP Message Router API <https://docs.onap.org/projects/onap-dmaap-messagerouter-messageservice/en/honolulu/offeredapis/api.html>`_ is used.
-::
+*****************************************
+O-RAN A1 interface for A1 Policies (A1-P)
+*****************************************
- DMAAP_GET_EVENTS
+Southbound, the ONAP A1 Policy functions communicate with *near-RT-RIC* RAN functions using the **A1** interface, as defined by the `O-RAN Alliance <https://www.o-ran.org>`_
+The *A1 Interface - Application Protocol Specification (A1-AP)* describe this interface. The specification can be viewed from the `O-RAN Alliance <https://www.o-ran.org>`_ website.
-********
-A1-P API
-********
+The **Honolulu** ONAP A1 Policy functions implement the *A1 Policy* parts (*A1-P*) of A1-AP versions *v1.1* and *v2.0*
+
+An opensource implementation of a `near-RT-RIC <https://wiki.o-ran-sc.org/pages/viewpage.action?pageId=1179659>`_ is available from `O-RAN Software Community <https://o-ran-sc.org>`_. It supports a pre-spec version of the A1-AP. The ONAP A1 Policy functions described here also supports this A1 version (A1-OSC).
-The A1-P API is used to communicate with the Near-RT RICs (north bound). All endpoints of the OSC A1 REST API and the
-standard A1 REST API version 1.1 are used.
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
-.. Copyright (C) 2020 Nordix Foundation.
+.. Copyright (C) 2021 Nordix Foundation.
.. _developer_guide:
Developer Guide
===============
-This document provides a quickstart for developers of the CCSDK ORAN parts.
+This document provides a quickstart for developers of the CCSDK functions for O-RAN A1 Policies.
Source tree
+++++++++++
-This application provides CCSDK Policy Management Service and A1 Adapter as main functional resources.
+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 CCSDK Policy Management Service (PMS) is a Java 11 web application built over Spring Framework.
+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.
-PMS provides a REST API for management of policices. It provides support for:
+A1 Policy Management Service provides a revised 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
+ * 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. See :ref:`pms_api` for how to use the API.
+The Policy Management Service can be accessed over the REST API, and with an equivalent interface using DMaaP. See :ref:`pms_api` for more information about the API.
Dependencies
------------
Configuration
-------------
-There are two configuration files for PMS, *config/application_configuration.json* and *config/application.yaml*.
+There are two configuration files for A1 Policy Management Service, *config/application_configuration.json* and *config/application.yaml*
The first one contains configuration of data needed by the application, such as which Near-RT RICs
that are available. The second 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 <https://wiki.onap.org/display/DW/O-RAN+A1+Policies+in+ONAP+Honolulu>`_
+
+Static configuration (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 Proxy; if configured, the proxy will be used for accessing 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 (REST)
+----------------------------------
+A REST Api to dynamically reconfigure the Service (If Consul is not used). See :ref:`pms_api` for more information.
+
+
+Dynamic configuration (CBS/Consul)
+----------------------------------
+
+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). The configuration is re-read and refreshed at regular intervals.
+
+The configuration includes:
+
+ * 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
+---------------------------------------------------
+
+The access of 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
+
+
+
Configuration of certs
----------------------
The target paths in the container should not be modified.
+It is also possible to configure a HTTP(S) Proxy for southbound connections. This can be set in the application.yaml configuration file.
+
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=PMS-container --network=oran-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.1.2-SNAPSHOT
-
+
A1 Adapter (Internal)
+++++++++++++++++++++
-The O-RAN A1 Adapter provides an internal REST CONF API for management of A1 policices, useful for test and verification.
+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.
-The A1 Adapter can be accessed over the REST CONF API. See :ref:`a1_adapter_api` for how to use the API.
+See :ref:`a1_adapter_api` for details of this internal API.
.. SPDX-License-Identifier: CC-BY-4.0
-.. Copyright 2020 Nordix Foundation
+.. Copyright 2021 Nordix Foundation
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 <https://gerrit.o-ran-sc.org/r/admin/repos/portal/nonrtric-controlpanel>`_.
+See `NON-RT RIC Control Panel repo <https://gerrit.o-ran-sc.org/r/admin/repos/portal/nonrtric-controlpanel>`_ from the `O-RAN-SC NONRTRIC Project <https://wiki.o-ran-sc.org/display/RICNR>`_.
-Any "Rest Client" application may be used (Postman, ...) to interact with the Policy Management Service application.
+Any "Rest Client" application may be used (Postman, ...) to interact with the Policy Management Service application via the :ref:`A1 Policy Management Service API<offered_apis>`_
.. This work is licensed under a Creative Commons Attribution 4.0
International License.
.. http://creativecommons.org/licenses/by/4.0
-.. Copyright 2020 Nordix Foundation
+.. Copyright 2021 Nordix Foundation
.. _offered_apis:
============
Introduction
-************
+------------
-The north bound REST API of the Policy Management Service provides convenient methods to handle policies.
+The north bound REST API of the A1 Policy Management Service provides convenient methods to handle policies.
-Overview
-************************
+Overall architecture for O-RAN A1 Policy functions
+--------------------------------------------------
-Following illustration provides a global view about **ORAN** architecture,
+This picture provides a overview of ONAP's A1 Controller architecture,
integration with other ONAP components and API resource/operation provided.
.. image:: ../media/ONAP-A1ControllerArchitecture.png
:width: 500pt
-
-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.
-
-The version number has major, minor and revision numbers. E.g. v1.0.0
-The version number (without the revision number) is held in the URI.
-
-The major version number is incremented for an incompatible change.
-The minor version number is incremented for a compatible change.
-For minor modifications of the API, version numbering must not be updated,
-
-For major modifications of the API, not backward compatible and forcing client
-implementations to be changed, the major version number must be updated.
-
-
API Table
-*********
+---------
.. |swagger-icon| image:: ../media/swagger.png
:width: 40px
:header: "API name", "|swagger-icon|", "|yaml-icon|"
:widths: 10,5, 5
- "PMS API", ":download:`link <./swagger/pms-api.json>`", ":download:`link <./swagger/pms-api.yaml>`"
+ "A1 Policy Management Service API (NBI)", ":download:`link <./swagger/pms-api.json>`", ":download:`link <./swagger/pms-api.yaml>`"
"A1 ADAPTER API (Internal)", ":download:`link <./swagger/a1-adapter-api.json>`", ":download:`link <./swagger/a1-adapter-api.yaml>`"
-
.. _pms_api:
-PMS API
-.......
-`PMS API <./pms-api.html>`_
+A1 Policy Management Service API
+................................
+
+The A1 Policy Management Service API is described in more detail in `A1 Policy Management Service API (html) <./pms-api.html>`_
+
.. _a1_adapter_api:
A1 ADAPTER API
..............
-`A1 ADAPTER API (Internal) <./a1-adapter-api.html>`_
+
+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) <./a1-adapter-api.html>`_
Version history Policy Management Service
=========================================
-+------------+----------+-------------+----------------+
-| **Date** | **Ver.** | **Author** | **Comment** |
-| | | | |
-+------------+----------+-------------+----------------+
-| 2020-09-10 | 1.0.0 | Dan Timoney | First version |
-| | | | Guilin Release |
-+------------+----------+-------------+----------------+
-
-
-Summary
--------
-First version.
++------------+----------+-------------+-------------------+
+| **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 |
++------------+----------+-------------+-------------------+
Version history A1 Adapter
==========================
-+------------+----------+-------------+----------------+
-| **Date** | **Ver.** | **Author** | **Comment** |
-| | | | |
-+------------+----------+-------------+----------------+
-| 2019-09-10 | 1.0.0 | Dan Timoney | First version |
-| | | | Guilin Release |
-+------------+----------+-------------+----------------+
++------------+----------+-------------+-------------------+
+| **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 |
++------------+----------+-------------+-------------------+
Release Data
============
-Guilin
-------
+Guilin, M4
+----------
+-----------------------------+-----------------------------------------------------+
| **Project** | CCSDK ORAN |
| | |
+-----------------------------+-----------------------------------------------------+
-| **Repo/commit-ID** | ccsdk-oran/ec3829493c0b71c5e5908a430edd1e493504178e |
+| **Repo/commit-ID** | ccsdk-oran/28d357836d89914e241c0fcd20239aff7498568e |
| | |
+-----------------------------+-----------------------------------------------------+
| **Release designation** | Guilin |
| **Release date** | 2020-09-10 |
| | |
+-----------------------------+-----------------------------------------------------+
-| **Purpose of the delivery** | Introducing ORAN |
+| **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 |
+| | |
++-----------------------------+-----------------------------------------------------+
\ No newline at end of file
Code Review / ccsdk / oran.git / commitdiff
