aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authork.kedron <k.kedron@partner.samsung.com>2021-03-17 09:28:59 +0100
committerKrystian Kedron <k.kedron@partner.samsung.com>2021-03-23 13:37:08 +0000
commit5ea372baed3b743dbf3ddeffb8fe1a0acdf376d6 (patch)
treeaf5b8f01a32a71cd5c0361141e11d9236ee1093e /README.md
parent431dd5721e7c37170c254836f4566e48a0cc1837 (diff)
Provide initial a1-pe-sim docs
Swagger tool integration README.md Configuration files example content Issue-ID: INT-1887 Signed-off-by: Krystian Kedron <k.kedron@partner.samsung.com> Change-Id: Idbdec7b3091dc78428ec5740283f82d1e2b9c19b
Diffstat (limited to 'README.md')
-rw-r--r--README.md381
1 files changed, 381 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8b5ebcf
--- /dev/null
+++ b/README.md
@@ -0,0 +1,381 @@
+# A1 Policy Enforcement Simulator (A1 PE Simulator)
+
+Simulator that supports the A1-P OSC\_2.1.0 interface also provides internal API to managed the RAN elements (Cells, Ues) and allows to customize and send VES Events.
+
+## How to use the A1 PE Simulator?
+
+### RAN
+
+A1 PE Simulator needs two main files to define the topology(cells) and user equipments that should be managed (and those cells/ues are used in A1 Policy Enforcement loop).
+
+- doc/resource/cell.json
+
+```json
+{
+ "cellList": [
+ {
+ "Cell": {
+ "networkId": "RAN001",
+ "nodeId": "Cell1",
+ "physicalCellId": 0,
+ "pnfName": "ncserver1",
+ "sectorNumber": 0,
+ "latitude": "50.11",
+ "longitude": "19.98"
+ },
+ "neighbor": [
+ {
+ "nodeId": "Cell3",
+ "blacklisted": "false"
+ },
+ {
+ "nodeId": "Cell4",
+ "blacklisted": "false"
+ },
+ {
+ "nodeId": "Cell2",
+ "blacklisted": "false"
+ }
+ ]
+ }
+}
+```
+
+- doc/resource/ue.json
+
+```json
+[
+ {
+ "id": "emergency_samsung_s10_01",
+ "latitude": "50.09",
+ "longitude": "19.94",
+ "cellId": "Cell1"
+ },
+ {
+ "id": "emergency_police_01",
+ "latitude": "50.035",
+ "longitude": "19.97",
+ "cellId": "Cell3"
+ }
+]
+```
+
+Those files location is defined in the *src/main/resources/application.properties*.
+
+Important: The vnf.config, cells.json, ue.json files should be in the */var/a1pesim/* (default folder location, can be changed).
+So copy the content of **doc/resources/** to this location on the host, where simulator will be running.
+
+How to change those default location, see:
+
+- **Run A1 PE Simulator with a new configuration**
+
+How to refresh the content of those files in runtime, see:
+
+- **Refresh the configuration files in runtime**
+
+### VES
+
+A1 PE Simulator provides REST endpoints that can be used to trigger sending VES events to e.q DMaaP topic via VES-COLLECTOR (DCAE MS).
+
+The file **vnf.config** provides the connectivity configuration like also the sourceId, sourceName values that will be added to the commonEventHeader:
+
+```
+vesHost=vesconsumer
+vesPort=30417
+vesUser=sample1
+vesPassword=sample1
+vnfId=de305d54-75b4-431b-adb2-eb6b9e546014
+vnfName=ibcx0001vm002ssc001
+```
+
+- vesHost defines the hostname of the VES consumer
+- vesPort defines the port on which consumer expects events
+- vesUser and vesPassword are used to create the BasicAuth header in the request
+- vnfId, vnfName map to the VES event -> commonEventHeader content:
+
+```json
+{
+ "event":{
+ "commonEventHeader": {
+ "sourceId": "de305d54-75b4-431b-adb2-eb6b9e546014",
+ "sourceName": "ibcx0001vm002ssc001",
+ ...
+ },
+ ...
+}
+```
+
+Cells can seed two types of VES events **normal** and **failure**.
+In both cases the VES events values are mostly the same.
+Is only one distinction, the *measurementFields.additionalMeasurements.latency/throughput* values are generated by using different algorithms.
+
+- for normal VES Events
+
+```json
+{
+ ...
+ "measurementFields" : {
+ "additionalMeasurements" : [
+ {
+ "name": "latency",
+ "hashMap": {
+ "value": "[[10-150]]"
+ }
+ },
+ {
+ "name": "throughput",
+ "hashMap": {
+ "value": "[[10-100]]"
+ }
+ }
+ ],
+ ...
+ }
+}
+```
+
+**10-150** means that the generated values will oscillate between 10 and 150
+
+- for failure VES Events
+
+```json
+{
+...
+"measurementFields" : {
+ "additionalMeasurements" : [
+ {
+ "name": "latency",
+ "hashMap": {
+ "value": "[[200->500]]"
+ }
+ },
+ {
+ "name": "throughput",
+ "hashMap": {
+ "value": "[[10->1]]"
+ }
+ }
+ ],
+ ...
+ }
+}
+```
+
+**200->500** means that the value will be generated from 200 to 500 (by using the exponential function)
+
+### A1-P Mediator API
+
+The A1 Mediator listens on the northbound interface of the RIC for policy guidance.
+The caller (e.g., non RT RIC, SMO, etc.) creates policy types and policy instances through A1, and subsequently A1 exchanges messages with xApps via RMR.
+
+#### Policy Type
+
+Example schema (use in Policy Enforcement PoC):
+
+```json
+{
+ "name": "samsung_policy_type",
+ "description": "samsung policy type; standard model of a policy with unconstrained scope id combinations",
+ "policy_type_id": 1000,
+ "create_schema": {
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "title": "Samsung_demo",
+ "description": "Samsung demo policy type",
+ "type": "object",
+ "properties": {
+ "scope": {
+ "type": "object",
+ "properties": {
+ "ueId": {
+ "type": "string"
+ },
+ "groupId": {
+ "type": "string"
+ }
+ },
+ "additionalProperties": false,
+ "required": [
+ "ueId"
+ ]
+ },
+ "resources": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "cellIdList": {
+ "type": "array",
+ "minItems": 1,
+ "uniqueItems": true,
+ "items": {
+ "type": "string"
+ }
+ },
+ "preference": {
+ "type": "string",
+ "enum": [
+ "SHALL",
+ "PREFER",
+ "AVOID",
+ "FORBID"
+ ]
+ }
+ },
+ "additionalProperties": false,
+ "required": [
+ "cellIdList",
+ "preference"
+ ]
+ }
+ }
+ },
+ "additionalProperties": false,
+ "required": [
+ "scope",
+ "resources"
+ ]
+ }
+}
+```
+
+To create the policy type, the proper request, can be sent:
+
+```
+curl -X PUT -v -H "accept: application/json" -H "Content-Type: application/json" --data-binary @/tmp/policy_type.json localhost:9998/v1/a1-p/policytypes/1000
+```
+
+where:
+
+- @/tmp/policy_type.json file with policy schema
+- localhost:9998/v1/a1-p/policytypes/${policy_type_id} - policy type ID use to create the policy instance
+
+#### Create/Delete Policy Instance
+
+Create new/Update example policy instance request:
+
+```
+curl --location --request PUT 'http://localhost:9998/a1-p/policytypes/1000/policies/1' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+ "scope" : {
+ "ueId" : "emergency_samsung_s10_01"
+ },
+ "resources" : [
+ {
+ "cellIdList" : [ "Cell1" ],
+ "preference" : "AVOID"
+ }
+ ]
+}'
+```
+
+where:
+
+- localhost:9998/a1-p/policytypes/${policy_type_id}/policies/${policy_instance_id} - id of the policy instance to create
+
+Delete the policy instance request:
+
+```
+curl --location --request DELETE 'http://localhost:9998/a1-p/policytypes/1000/policies/1'
+```
+
+### Run A1 PE Simulator with a new configuration
+
+A1 PE Simulator uses the properties to define the:
+
+- File location for vnf.config, cells.json, ue.json
+- VES consumer supported protocol and endpoint (e.q for VES-Collector)
+- Cell range
+- VES sending default interval
+- Version of the A1 PE Simulator API
+
+To see the default see (src/main/resources/application.properties)
+
+To override those values one of the options can be used:
+
+#### 1. By defining the OS env variables
+
+- VNF_CONFIG_FILE=
+- TOPOLOGY_CELL_CONFIG_FILE=
+- TOPOLOGY_UE_CONFIG_FILE=
+- VES_COLLECTOR_PROTOCOL=
+- VES_COLLECTOR_ENDPOINT=
+- VES_DEFAULTINTERVAL=
+- RESTAPI_VERSION=
+
+#### 2. By adding the process arguments
+
+Add the -D flag the running command:
+
+- "-Dvnf.config.file="
+- "-Dtopology.cell.config.file="
+- "-Dtopology.ue_config.file="
+- "-Dves.collector.protocol="
+- "-Dves.collector.endpoint="
+- "-Dves.defaultinterval="
+- "-Drestapi.version="
+
+When running with -Dspring.profiles.active=dev default values for **vnf.config.file**, **topology.cell.config.file** and **topology.ue.config.file** are setup to use the example files from *src/test/resources/*
+
+### Refresh the configuration files in runtime
+
+When the content of cells.json, use.json will be changed, the user should send a request to notify the server about this change and A1 PE Simulator will reload those files:
+
+```
+curl --location --request GET 'http://localhost:9998/v1/ran/refresh'
+```
+
+Also, A1 PE Simulator automatically refreshes the topology/ues information from those file in defined time interval:
+
+**refresher.fixed.rate.ms=60000**
+
+# API
+
+The API is documented by the Swagger tool.
+
+## Swagger
+
+The generated swagger html file can be found in *doc/swagger/html* directory.
+JSON file that can be e.q import to Swagger GUI can be found in *doc/swagger*.
+Those files are regenerate each maven build. So to generate this file please see **Build the A1 PE Simulator** chapter.
+
+# Developer Guide
+
+## Build the A1 PE Simulator
+
+Following mvn command (in the project directory) will build A1 Policy Enforcement Simulator:
+
+```bash
+mvn clean install
+```
+
+## Run the A1 PE Simulator
+
+Following command will run the A1 Policy Enforcement Simulator:
+
+```bash
+java -jar a1-pe-simulator-1.0-SNAPSHOT.jar org.onap.a1pesimulator.A1PolicyEnforcementSimulatorApplication
+```
+
+The application should start on 9998 port.
+
+## Logging
+
+The logs file will be created in the ${user.home}/log path.
+To define the **user.home** value, use the process arguments e.g "-Duser.home=/path_to_dir".
+
+After the A1 PE Simulator starts successfully the */path_to_dir.log* should start to contain the logs:
+
+```
+.
+└── a1-pe-simulator
+ ├── application
+ │ ├── debug-2021-03-15.0.log
+ │ ├── error-2021-03-15.0.log
+ │ └── metrics-2021-03-15.0.log
+ └── debug-2021-03-15.0.log
+```
+
+# Dockerized the A1 PE Simulator
+
+...