README.md

   1 # O-RAN-SC Non-RT RIC A1 Policy Management Service
   2
   3 The O-RAN-SC A1 Policy Management Service provides a REST API for the management of policies within the O-RAN architecture. This README provides details on the features, configuration, and running instructions for the A1 Policy Management Service.
   4 For detailed API documentation and further information, refer to the NONRTRIC documentation at [NONRTRIC Wiki](https://wiki.o-ran-sc.org/display/RICNR).
   5 For additional detailed documentation, also refer to the NONRTRIC documentation at [A1 Policy Management Service Documentation site](https://docs.o-ran-sc.org/projects/o-ran-sc-nonrtric-plt-a1policymanagementservice).
   6
   7 The A1 Policy Management Service is homed in ONAP. For additional documentation see [ONAP CCSDK documentation](https://docs.onap.org/projects/onap-ccsdk-oran).
   8 and [wiki](https://wiki.onap.org/display/DW/O-RAN+A1+Policies+in+ONAP).
   9
  10 ## Features
  11
  12
  13 The A1 Policy Management Service is a microservice which maintains a transient repository of:
  14
  15 - All A1 policies instances in the network. Each policy is targeted to a near-RT-RIC instance and is owned by a 'service' (e.g., rApps or the NONRTRIC Dashboard).
  16 - All near-RT-RICs in the network.
  17 - All Policy types supported by each near-RT-RIC.
  18
  19 The service provides :
  20
  21 - Unified REST API for managing A1 Policies in all near-RT-RICs.
  22 - Compliant with O-RAN R1 specification for A1-Policy Management (R1-AP v5.0, with additional features & fixes)
  23 - Synchronized view of A1 Policy instances for each rAPP
  24 - Synchronized view of A1 Policy instances in each near-RT-RIC
  25 - Synchronized view of A1 Policy types supported by each near-RT-RIC
  26 - Lookup service to find the near-RT-RIC to control resources in the RAN as defined in  O1 (e.g. which near-RT-RIC should be accessed to control a certain CU or DU, which in turn controls a certain cell).
  27 - Monitors all near-RT-RICs and maintains data consistency, e.g. recovery from near-RT-RIC restarts
  28 - Support for different Southbound APIs  to the near-RT-RICs (different versions of the A1-P and other similar APIs).
  29 - HTTPS can be configured to use a supplied certificate/private key and to validate peers towards a list of trusted CAs/certs.
  30 - HTTP proxy support for tunneling HTTP/HTTPS connections.
  31 - Fine-grained access-control - with new optional callouts to an external auth function
  32 - Fine-grained monitoring metrics, logging & call tracing can be configured
  33
  34 ## Configuration
  35
  36 The A1 Policy Management Service uses default keystore and truststore files included in the container. The paths and passwords for these stores are specified in a YAML configuration file located at:
  37
  38
  39
  40 ### Default Truststore Certificates
  41
  42 The default truststore includes the following trusted certificates:
  43 - **A1 Simulator Certificate**: [a1simulator cert](https://gerrit.o-ran-sc.org/r/gitweb?p=sim/a1-interface.git;a=tree;f=near-rt-ric-simulator/certificate)
  44 - **A1 Policy Management Service's Own Certificate**: Used for mocking and unit-testing purposes (ApplicationTest.java).
  45
  46 ### Overriding Default Configuration
  47
  48 You can override the default keystore, truststore, and application.yaml files by mounting new files using the `volumes` field in Docker Compose or the `docker run` command.
  49
  50 Assuming the new keystore, truststore, and application.yaml files are located in the same directory as your Docker Compose file, the `volumes` field should include these entries:
  51
  52 ```yaml
  53 volumes:
  54   - ./new_keystore.jks:/opt/app/policy-agent/etc/cert/keystore.jks:ro
  55   - ./new_truststore.jks:/opt/app/policy-agent/etc/cert/truststore.jks:ro
  56   - ./new_application.yaml:/opt/app/policy-agent/config/application.yaml:ro
  57 ```
  58
  59 The target paths in the container should remain unchanged.
  60
  61 Example Docker Run Command
  62 To run the Policy Agent container and mount the new configuration files, use the following docker run command:
  63
  64 ```sh
  65 docker run -p 8081:8081 -p 8433:8433 --name=policy-agent-container --network=nonrtric-docker-net \
  66   --volume "$PWD/new_keystore.jks:/opt/app/policy-agent/etc/cert/keystore.jks" \
  67   --volume "$PWD/new_truststore.jks:/opt/app/policy-agent/etc/cert/truststore.jks" \
  68   --volume "$PWD/new_application.yaml:/opt/app/policy-agent/config/application.yaml" \
  69   nexus3.o-ran-sc.org:10002/o-ran-sc/nonrtric-plt-a1policymanagementservice:2.8.0
  70 ```
  71
  72 ### Running Policy Agent Locally
  73 To run the Policy Agent locally in a simulated test mode, follow these steps:
  74
  75 1. In the folder /opt/app/policy-agent/config/, create a soft link to your test configuration file:
  76
  77 ```sh
  78 ln -s <path to test_application_configuration.json> application_configuration.json
  79 ```
  80
  81 2. Start the Policy Agent with the following Maven command:
  82
  83 ```sh
  84 mvn -Dtest=MockPolicyAgent test
  85 ```
  86
  87 This will start the agent in a simulated mode, where it mimics the behavior of RICs. The REST API will be available on port 8081.
  88
  89 ### API Documentation
  90 The backend server publishes live API documentation, which can be accessed at:
  91
  92 ```bash
  93 http://your-host-name-here:8081/swagger-ui.html
  94 ```
  95
  96 ## License
  97
  98 Copyright (C) 2019-2023 Nordix Foundation. All rights reserved.
  99 Copyright (C) 2024: OpenInfra Foundation Europe. All rights reserved.
 100 Licensed under the Apache License, Version 2.0 (the "License");
 101 you may not use this file except in compliance with the License.
 102 You may obtain a copy of the License at
 103
 104      http://www.apache.org/licenses/LICENSE-2.0
 105
 106 Unless required by applicable law or agreed to in writing, software
 107 distributed under the License is distributed on an "AS IS" BASIS,
 108 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 109 See the License for the specific language governing permissions and
 110 limitations under the License.