diff options
Diffstat (limited to 'docs/guide/developer-guide.rst')
| -rw-r--r-- | docs/guide/developer-guide.rst | 57 |
1 files changed, 35 insertions, 22 deletions
diff --git a/docs/guide/developer-guide.rst b/docs/guide/developer-guide.rst index 05a8281a..30d17430 100644 --- a/docs/guide/developer-guide.rst +++ b/docs/guide/developer-guide.rst @@ -10,9 +10,11 @@ Developer Guide This document provides a quickstart for developers of the CCSDK functions for O-RAN A1 Policies. -.. image:: ../media/ONAP-A1ControllerArchitecture-NewDelhi.png +.. image:: ../media/ONAP-A1ControllerArchitecture-NewDelhiOslo.png :width: 500pt +Additional guides for developers can be found on the `ONAP wiki (Development Guides) <https://lf-onap.atlassian.net/wiki/spaces/DW/pages/16445127/Development+guide+for+O-RAN+A1+Policies+Non-RealTime+RIC+applications>`_. + Source tree +++++++++++ @@ -46,7 +48,7 @@ Dependencies ------------ This project uses various frameworks which are managed with Maven -dependency management tool (see *pom.xml* file at root level) : +dependency management tool (see *pom.xml* file at root level). For example: - Swagger annotations - `Spring Framework <https://github.com/spring-projects/spring-boot>`_ @@ -60,28 +62,34 @@ 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 application-specific configuration needed by the application, such as which near-RT RICs, or controller to use. -The second (*config/application.yaml*) contains logging and security configurations. +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 application-specific configuration needed by +the application, such as which near-RT RICs, or controller to use. +The second (*config/application.yaml*) contains configuration options for underlying service, including +configurations for logging, tracing, security, storage, etc.. -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://lf-onap.atlassian.net/wiki/spaces/DW/pages/16444961/O-RAN+A1+Policies+in+ONAP>`_ +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://lf-onap.atlassian.net/wiki/spaces/DW/pages/16444961/O-RAN+A1+Policies+in+ONAP>`_ 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 + * *server*; configuration for the Web Server (Northbound Interface) * used port for HTTP/HTTPS, this is however not the port number 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 + + * *webclient*; configuration parameters for a Web Client used by the component (Southbound Interface) * 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 for which information is logged. - * *auth-token*; optional authorization token to use for REST call. + * *auth-token*; optional authorization token to use for REST calls. * *filepath*; the local path to a file used for dynamic configuration (if used). See next chapter. * *persistent storage* of runtime information. Configuration of A1 Policy instances is stored persistently. The media for this can be either filesystem (a persistent volume) or Amazon S3 - Cloud Object Storage. @@ -89,33 +97,40 @@ 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 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 using the Configuration REST API. The configuration is re-read and refreshed at regular intervals if the file is changed (e.g. using K8s ConfigMap capabilities). +The component has configuration that can be updated in runtime. This configuration can either be loaded from a +file (accessible from the container), or using the Configuration REST API. The configuration is re-read and +refreshed at regular intervals if the file is changed (e.g. using K8s ConfigMap capabilities). The configuration includes: * Optional *Controller* configuration, e.g. an SDNC instance (with A1-Adapter) - * (If no 'Contoller' is configured, the A1 Policy Management Service will connect direct to near-RT RICs, bypassing the SDNC controller) + * (If no 'Controller' is configured, the A1 Policy Management Service will connect direct to near-RT RICs, bypassing the SDNC controller) * One entry for each near-RT-RIC (*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.). + * A optional list of O1 identifiers that near-RT-RIC is controlling. An application may 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. -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*. +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*. Configuring certificates ------------------------ -The A1 Policy Management Service uses the default security keystore and truststore that are included in the built container. The paths and -passwords for these stores are located in the static configuration file described above (*application.yaml*), with an example is provided in the source code repository *a1-policy-management/config/application.yaml* +The A1 Policy Management Service uses the default security keystore and truststore that are included +in the built container. The paths and passwords for these stores are located in the static configuration file +described above (*application.yaml*), with an example is provided in the source code +repository *a1-policy-management/config/application.yaml* -A default cert and truststore is also included in the A1 Policy Management Service, but should only be used for *mocking* and *testing* purposes. -(*ApplicationTest.java*). +A default cert and truststore is also included in the A1 Policy Management Service, but should only be used +for *mocking* and *testing* purposes. (ref. file: *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 default keystore, truststore, and application.yaml files can/should 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:` @@ -127,7 +142,7 @@ 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.5.0 + 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:latest A1 Adapter (Internal) +++++++++++++++++++++ @@ -146,5 +161,3 @@ In order to configure a HTTP Proxy for the A1-Adapter to use for southbound conn * 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). - - |