diff options
| -rwxr-xr-x | docs/architecture/architecture.rst | 16 | ||||
| -rwxr-xr-x | docs/consumedapis/consumedapis.rst | 26 | ||||
| -rw-r--r-- | docs/guide/developer-guide.rst | 83 | ||||
| -rw-r--r-- | docs/humaninterfaces/humaninterfaces.rst | 6 | ||||
| -rw-r--r-- | docs/media/ONAP-A1ControllerArchitecture.png | bin | 80069 -> 79142 bytes | |||
| -rw-r--r-- | docs/offeredapis/offeredapis.rst | 50 | ||||
| -rw-r--r-- | docs/releasenotes/release-notes.rst | 141 |
7 files changed, 230 insertions, 92 deletions
diff --git a/docs/architecture/architecture.rst b/docs/architecture/architecture.rst index bfe827bd..a0d71539 100755 --- a/docs/architecture/architecture.rst +++ b/docs/architecture/architecture.rst @@ -1,5 +1,5 @@ .. SPDX-License-Identifier: CC-BY-4.0 -.. Copyright 2020 Nordix Foundation +.. Copyright 2021 Nordix Foundation .. _architecture: @@ -11,14 +11,16 @@ Introduction ************ -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 @@ -29,5 +31,5 @@ integration with other ONAP components and API resource/operation provided. 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`. diff --git a/docs/consumedapis/consumedapis.rst b/docs/consumedapis/consumedapis.rst index 8357e43d..06b47dd1 100755 --- a/docs/consumedapis/consumedapis.rst +++ b/docs/consumedapis/consumedapis.rst @@ -1,5 +1,5 @@ .. SPDX-License-Identifier: CC-BY-4.0 -.. Copyright 2020 Nordix Foundation +.. Copyright 2021 Nordix Foundation Consumed APIs ============= @@ -11,26 +11,22 @@ Policy Management Service application is interacting with two ONAP APIs and the 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. diff --git a/docs/guide/developer-guide.rst b/docs/guide/developer-guide.rst index fb8c97ec..ea3a635b 100644 --- a/docs/guide/developer-guide.rst +++ b/docs/guide/developer-guide.rst @@ -1,38 +1,38 @@ .. 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 ------------ @@ -53,10 +53,69 @@ dependency management tool (see *pom.xml* file at root level) : 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 ---------------------- @@ -83,13 +142,15 @@ the volumes field should have these entries: :: 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. diff --git a/docs/humaninterfaces/humaninterfaces.rst b/docs/humaninterfaces/humaninterfaces.rst index ab7d421f..c0ede9c5 100644 --- a/docs/humaninterfaces/humaninterfaces.rst +++ b/docs/humaninterfaces/humaninterfaces.rst @@ -1,11 +1,11 @@ .. 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>`_ diff --git a/docs/media/ONAP-A1ControllerArchitecture.png b/docs/media/ONAP-A1ControllerArchitecture.png Binary files differindex 59516628..ded44fbc 100644 --- a/docs/media/ONAP-A1ControllerArchitecture.png +++ b/docs/media/ONAP-A1ControllerArchitecture.png diff --git a/docs/offeredapis/offeredapis.rst b/docs/offeredapis/offeredapis.rst index a43c0460..99f59e9b 100644 --- a/docs/offeredapis/offeredapis.rst +++ b/docs/offeredapis/offeredapis.rst @@ -1,7 +1,7 @@ .. 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: @@ -10,42 +10,22 @@ 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 @@ -58,19 +38,23 @@ API Table :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>`_ diff --git a/docs/releasenotes/release-notes.rst b/docs/releasenotes/release-notes.rst index 1bee897e..b6a5b618 100644 --- a/docs/releasenotes/release-notes.rst +++ b/docs/releasenotes/release-notes.rst @@ -18,40 +18,59 @@ of the ORAN project. 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 | @@ -60,6 +79,82 @@ 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 |
