near-rt-ric-simulator/README.md

   1 # O-RAN-SC Near-RealTime RIC Simulator
   2
   3 The O-RAN SC Near-RealTime RIC simulates the A1 as an generic REST API which can receive and send northbound messages. The simulator validates the payload and applies policy.
   4
   5 The simulator supports multiple A1 interface versions (version of the open API yaml file\):
   6 | Yaml file version     | Version id|
   7 | --------------------- | ------------------- |
   8 | OSC 2.1.0,            |      OSC\_2.1.0     |
   9 | A1 Standard 1.1.3,    |      STD\_1.1.3     |
  10 | 1.1.x-alpha.2 ,       |      1.1.x-alpha.2  |
  11
  12 All versions are supported by the same container, see section 'Configuring the simulator' below for details about how to the start the simulator with the intended version id.
  13
  14 The overall folder structure is \(relative to the location of this README file\):
  15 | Dir              | Description |
  16 | ---------------- | ----------- |
  17 |.                 |Dockerfile and README |
  18 |api               |The open api yaml for each supported version |
  19 |src               |Python source code for each supported version |
  20 |test              |Basic test |
  21
  22
  23 The simulator handles the requests that are defined in the A1 open API yaml file. All these requests are implemented in the a1.py file in the source folder. In addition, a number of administrative functions are also supported and implemented by the main.py in the source folder.
  24
  25 The section below outlines the supported open api REST operations as well as the adminstrative REST operations.
  26
  27
  28 # Supported operations in simulator OSC 2.1.0
  29
  30 URIs for A1:
  31 | Function              | Path and parameters |
  32 | --------------------- | ------------------- |
  33 |  GET, do a healthcheck |  http://localhost:8085/a1-p/healthcheck |
  34 |  GET, get all policy type ids | http://localhost:8085/a1-p/policytypes |
  35 |  DELETE, delete a policy type | http://localhost:8085/a1-p/policytypes/{policy\_type\_id} |
  36 |  GET, get a policy type | http://localhost:8085/a1-p/policytypes/{policy\_type\_id} |
  37 |  PUT, create/update a policy type | http://localhost:8085/a1-p/policytypes/{policy\_type\_id} |
  38 |  GET, get all policy ids for a type | http://localhost:8085/a1-p/policytypes/{policy\_type\_id}/policies |
  39 |  DELETE, delete a policy | http://localhost:8085/a1-p/policytypes/{policy\_type\_id}/policies/{policy\_instance\_id} |
  40 |  GET, get a policy | http://localhost:8085/a1-p/policytypes/{policy\_type\_id}/policies/{policy\_instance\_id} |
  41 |  PUT, create/update a policy | http://localhost:8085/a1-p/policytypes/{policy\_type\_id}/policies/{policy\_instance\_id} |
  42 |  GET, get policy status | http://localhost:8085/a1-p/policytypes/{policy\_type\_id}/policies/{policy\_instance\_id}/status |
  43
  44 Swagger UI at: http://localhost:8085/ui/
  45
  46 URIs for admin operations:
  47 | Function              | Path and parameters |
  48 | --------------------- | ------------------- |
  49 |  GET, a basic healthcheck | http://localhost:8085/ |
  50 |  GET, a list of all supported interfaces | http://localhost:8085/container\_interfaces |
  51 |  POST, delete all policy instances | http://localhost:8085/deleteinstances |
  52 |  POST, full reset | http://localhost:8085/deleteall |
  53 |  PUT, create/update a policy type | http://localhost:8085/policytype?id=&lt;policytypeid&gt; |
  54 |  DELETE, delete a policy type | http://localhost:8085/policytype?id=&lt;policytypeid&gt; |
  55 |  GET, list of policy type id | http://localhost:8085/policytypes |
  56 |  POST, force a specific response code for an A1 operation | http://localhost:8085/forceresponse?code=&lt;http-code&gt; |
  57 |  POST, force delayed response of all A1 operations | http://localhost:8085/forcedelay?delay=&lt;seconds&gt; |
  58 |  PUT, set status and optional reason, delete and timestamp | http://localhost:8085/status?status=&lt;status&gt;&amp;reason=&lt;reason&gt;[&amp;deleted=&lt;boolean&gt;][&amp;created\_at=&lt;timestamp&gt;]  |
  59 |  GET a counter  <br> (counter-name: 'num\_instances', 'num\_types' or 'interface') | http://localhost:8085/counter/&lt;counter-name&gt; |
  60
  61
  62 # Supported operations in simulator A1 Standard 1.1.3
  63
  64 URIs for A1:
  65 | Function              | Path and parameters |
  66 | --------------------- | ------------------- |
  67 |  GET all policy identities | http://localhost:8085/A1-P/v1/policies |
  68 |  PUT a policy instance(create or update it) | http://localhost:8085/A1-P/v1/policies/{policyId} |
  69 |  GET a policy | http://localhost:8085/A1-P/v1/policies/{policyId} |
  70 |  DELETE a policy instance | http://localhost:8085/A1-P/v1/policies/{policyId} |
  71 |  GET a policy status | http://localhost:8085/A1-P/v1/policies/{policyid} |
  72 Swagger UI at: http://localhost:8085/A1-P/v1/ui/
  73
  74 URIs for admin operations:
  75 | Function              | Path and parameters |
  76 | --------------------- | ------------------- |
  77 |  GET, a basic healthcheck | http://localhost:8085/ |
  78 |  GET, a list of all supported interfaces | http://localhost:8085/container\_interfaces |
  79 |  POST, delete all policy instances | http://localhost:8085/deleteinstances |
  80 |  POST, full reset | http://localhost:8085/deleteall |
  81 |  POST, force a specific response code for an A1 operation | http://localhost:8085/forceresponse?code=&lt;http-code&gt; |
  82 |  POST, force delayed response of all A1 operations | http://localhost:8085/forcedelay?delay=&lt;seconds&gt; |
  83 |  PUT, set status and optional reason | http://localhost:8085/status?status=&lt;status&gt;[&amp;reason=&lt;reason&gt;] |
  84 |  POST, send status for policy | http://localhost:8085/sendstatus?policyid=&lt;policyid&gt; |
  85 |  GET a counter <br> (counter-name: 'num\_instances', 'num\_types'(always 0) or 'interface') | http://localhost:8085/counter/&lt;counter-name&gt; |
  86
  87
  88
  89 # Supported operations in simulator 1.1.x-alpha.2
  90
  91  The available requests and the addresses are currently:
  92 | Function              | Path and parameters |
  93 | --------------------- | ------------------- |
  94 |  GET all policy identities (respectively for a policy type if query parameter used) | http://localhost:8085/A1-P/v1/policies?policyTypeId={policyTypeId} |
  95 |  PUT a policy instance(create or update it) | http://localhost:8085/A1-P/v1/policies/{policyId}?policyTypeId={policyTypeId} |
  96 |  GET a policy | http://localhost:8085/A1-P/v1/policies/{policyId} |
  97 |  DELETE a policy instance | http://localhost:8085/A1-P/v1/policies/{policyId} |
  98 |  GET a policy status | http://localhost:8085/A1-P/v1/policystatus |
  99 |  GET all policy types | http://localhost:8085/A1-P/v1/policytypes |
 100 |  GET the schemas for a policy type | http://localhost:8085/A1-P/v1/policytypes/{policyTypeId} |
 101
 102 Nota Bene: It could happen that this page is not updated as soon as the yaml file is. The yaml file can be found under /near-rt-ric-simulator/a1-openapi.yaml.
 103
 104 Additionally, there are requests that are defined in main.py as an administrative API. The goal is to handle information that couldn't be handled using the A1 interface. The available requests and the addresses are currently:
 105 | Function              | Path and parameters |
 106 | --------------------- | ------------------- |
 107 |  GET, a basic healthcheck | http://localhost:8085/ |
 108 |  PUT a policy type | http://localhost:8085/policytypes/{policyTypeId} |
 109 |  DELETE a policy type | http://localhost:8085/policytypes/{policyTypeId} |
 110 |  DELETE all policy instances | http://localhost:8085/deleteinstances |
 111 |  DELETE all policy types | http://localhost:8085/deletetypes |
 112 |  PUT a status to a policy instance with an enforceStatus parameter only | http://localhost:8085/{policyId}/{enforceStatus} |
 113 |  PUT a status to a policy instance with both enforceStatus and enforceReason | http://localhost:8085/{policyId}/{enforceStatus}/{enforceReason} |
 114 |  GET a counter  <br> (counter-name: 'num\_instances', 'num\_types' or 'interface') | http://localhost:8085/counter/{counter-name} |
 115
 116 The backend server publishes live API documentation at the URL `http://localhost:8085/A1-P/v1/ui/`
 117
 118 # Configuring the simulator
 119 A env variable, A1\_VERSION need to be passed to the container at start to select the desired interface version. The variable shall be set to one of the version-ids shown in the table in the first section. For example A1\_VERSIION=STD\_1.1.3.
 120 In docker run the full command could look like this 'docker run -it -p 8085:8085 -e A1\_VERSION=STD\_1.1.3 a1test' where the variable is set with the '-e' flag.
 121
 122 # Updating the openapi specs
 123 The openapi specifications are stored in the 'api/&lt;version&gt;/'. If adding/replacing with a new file, make sure to copy the 'operationId' parameter for each operation to the new file.
 124
 125 # Start and test of the simulator
 126 First, download the sim/a1-interface repo on gerrit:
 127 git clone "https://gerrit.o-ran-sc.org/oransc/sim/a1-interface"
 128
 129 Goto the main directory, 'a1-interface/near-rt-ric-simulator'.
 130 There is a folder 'test/&lt;version&gt;/' for each supported simulator version. This folder contains a script to build and start the simulator (as a container in interactive mode), a script for basic testing as well as json files for the test script.
 131
 132 Go to the test folder of the selected version, 'test/&lt;version&gt;/.
 133
 134 Build and start the simulator container using: ./build\_and\_start.sh
 135 This will build and start the container in interactive mode. The built container only resides in the local docker repository.
 136 Note, the default port is 8085 which can be easily changed in the the script above as well as in the test script.
 137
 138 In a second terminal, go to the same folder and run the basic test script, basic\_test.sh or commands.sh depending on version.
 139 This script runs a number of tests towards the simulator to make sure it works properply.
 140
 141 Only for version 1.1.x-alpha.2
 142 Let the simulator run in one terminal; in another terminal, one can run the command ./commands.sh. It contains the main requests, and will eventually leave the user with a policy type STD\_QoSNudging\_0.2.0 and a policy instance pi1 with an enforceStatus set to NOT\_ENFORCED and an enforce Reason set to 300.
 143 All the response codes should be 20X, otherwise something went wrong.
 144
 145 ## License
 146
 147 Copyright (C) 2019 Nordix Foundation.
 148 Licensed under the Apache License, Version 2.0 (the "License")
 149 you may not use this file except in compliance with the License.
 150 You may obtain a copy of the License at
 151
 152       http://www.apache.org/licenses/LICENSE-2.0
 153
 154 Unless required by applicable law or agreed to in writing, software
 155 distributed under the License is distributed on an "AS IS" BASIS,
 156 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 157 See the License for the specific language governing permissions and
 158 limitations under the License.
 159
 160 For more information about license please see the [LICENSE](LICENSE.txt) file for details.