commit	ead5573e8e43e7e4ae795ff6029635fa5bf2a284	[log] [tgz]
author	Grzegorz Wielgosinski <g.wielgosins@samsung.com>	Wed Mar 24 13:24:05 2021 +0100
committer	Grzegorz Wielgosinski <g.wielgosins@samsung.com>	Fri Mar 26 13:46:04 2021 +0100
tree	77f92612b5e3df1b49f7bca442e9fb7d6d8f02c5
parent	29e0ba3179409458b96089dd37452d4a11cc32d3 [diff]

tree: 77f92612b5e3df1b49f7bca442e9fb7d6d8f02c5

README.md

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

{
  "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

[
    {
        "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:

{
    "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

{
  ...
  "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

{
...
"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):

{
  "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:

mvn clean install

Run the A1 PE Simulator

Following command will run the A1 Policy Enforcement Simulator:

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

...