near-rt-ric-simulator/README.md

   1 # O-RAN-SC A1 Simulator
   2
   3 The O-RAN SC A1 simulator simulates the A1 as a generic REST API that 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
   7 | YAML file version     | Version ID|
   8 | --------------------- | ------------------- |
   9 | OSC 2.1.0,            |      OSC_2.1.0     |
  10 | A1 Standard 1.1.3,    |      STD_1.1.3     |
  11 | A1 Standard 2.0.0,    |      STD_2.0.0     |
  12
  13 All versions are supported by the same container. See the section 'Configuring the simulator' below for details about how to start the simulator with the intended version ID.
  14
  15 The overall folder structure is (relative to the location of this README file):
  16
  17 | Dir              | Description |
  18 | ---------------- | ----------- |
  19 |.                 |Dockerfile and README |
  20 |api               |The open API YAML for each supported version |
  21 |src               |Python source code for each supported version |
  22 |test              |Basic test using script|
  23 |tests             |Basic test using pytest unit test|
  24 |certificate       |A self-signed certificate and a key|
  25
  26 The simulator handles the requests 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.
  27
  28 The section below outlines the supported open API REST operations as well as the administrative REST operations. For the documentation of the common parts in the admin API, see [Common Functions](https://docs.o-ran-sc.org/projects/o-ran-sc-sim-a1-interface/en/latest/simulator-api.html#common-functions).
  29
  30 # Ports and certificates
  31
  32 The simulator normally opens port 8085 for HTTP. If a certificate and a key are provided, the simulator will open port 8185 for HTTPS instead. Port 8185 is only opened if a valid certificate and key are found.
  33 The certificate and key should be placed in the same directory and the directory should be mounted to `/usr/src/app/cert` in the container.
  34
  35 | Port     | Protocol |
  36 | -------- | ----- |
  37 | 8085     | HTTP  |
  38 | 8185     | HTTPS |
  39
  40 The directory `certificate` contains a self-signed certificate. Use the script `generate_cert_and_key.sh` to generate a new certificate and key. The password of the certificate must be set to 'test'.
  41 The same URLs are available on both the HTTP port 8085 and the HTTPS port 8185. If using curl and HTTPS, the flag `-k` should be given to make curl ignore checking the certificate.
  42
  43 # Supported operations in simulator OSC 2.1.0
  44
  45 For the complete YAML specification, see [openapi.yaml](../near-rt-ric-simulator/api/OSC_2.1.0/openapi.yaml).
  46
  47 ## URIs for A1:
  48
  49 | Function              | Path and parameters |
  50 | --------------------- | ------------------- |
  51 |  GET, do a healthcheck |  http://localhost:8085/a1-p/healthcheck |
  52 |  GET, get all policy type IDs | http://localhost:8085/a1-p/policytypes |
  53 |  DELETE, delete a policy type | http://localhost:8085/a1-p/policytypes/{policy_type_id} |
  54 |  GET, get a policy type | http://localhost:8085/a1-p/policytypes/{policy_type_id} |
  55 |  PUT, create/update a policy type | http://localhost:8085/a1-p/policytypes/{policy_type_id} |
  56 |  GET, get all policy IDs for a type | http://localhost:8085/a1-p/policytypes/{policy_type_id}/policies |
  57 |  DELETE, delete a policy | http://localhost:8085/a1-p/policytypes/{policy_type_id}/policies/{policy_instance_id} |
  58 |  GET, get a policy | http://localhost:8085/a1-p/policytypes/{policy_type_id}/policies/{policy_instance_id} |
  59 |  PUT, create/update a policy | http://localhost:8085/a1-p/policytypes/{policy_type_id}/policies/{policy_instance_id} |
  60 |  GET, get policy status | http://localhost:8085/a1-p/policytypes/{policy_type_id}/policies/{policy_instance_id}/status |
  61 |  PUT, deliver data produced by data producer | http://localhost:8085/data-delivery json payload = {"job":"101",    "payload":"another payload"}|
  62
  63 Swagger UI at: http://localhost:8085/ui/
  64
  65 For the documentation of the admin API, see [OSC_2.1.0](https://docs.o-ran-sc.org/projects/o-ran-sc-sim-a1-interface/en/latest/simulator-api.html#osc-2-1-0).
  66
  67 ## URIs for admin operations:
  68
  69 | Function              | Path and parameters |
  70 | --------------------- | ------------------- |
  71 |  GET, a basic healthcheck | http://localhost:8085/ |
  72 |  GET, a list of all supported interfaces | http://localhost:8085/container_interfaces |
  73 |  POST, delete all policy instances | http://localhost:8085/deleteinstances |
  74 |  POST, full reset | http://localhost:8085/deleteall |
  75 |  PUT, create/update a policy type | http://localhost:8085/policytype?id=&lt;policytypeid&gt; |
  76 |  DELETE, delete a policy type | http://localhost:8085/policytype?id=&lt;policytypeid&gt; |
  77 |  GET, list of policy type ID | http://localhost:8085/policytypes |
  78 |  POST, force a specific response code for an A1 operation | http://localhost:8085/forceresponse?code=&lt;http-code&gt; |
  79 |  POST, force delayed response of all A1 operations | http://localhost:8085/forcedelay?delay=&lt;seconds&gt; |
  80 |  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;]  |
  81 |  GET a counter  <br> (counter-name: 'num_instances', 'num_types', 'interface' or 'remote_hosts') | http://localhost:8085/counter/&lt;counter-name&gt; |
  82 |  Turn on HTTP header and payload logging | http://localhost:8085/payload_logging/on |
  83 |  Turn off HTTP header and payload logging | http://localhost:8085/payload_logging/off |
  84
  85 # Supported operations in simulator A1 Standard 1.1.3
  86
  87 For the complete YAML specification, see [STD_A1.yaml](../near-rt-ric-simulator/api/STD_1.1.3/STD_A1.yaml).
  88
  89 URIs for A1:
  90
  91 | Function              | Path and parameters |
  92 | --------------------- | ------------------- |
  93 |  GET all policy identities | http://localhost:8085/A1-P/v1/policies |
  94 |  PUT a policy instance(create or update it) | http://localhost:8085/A1-P/v1/policies/{policyId} |
  95 |  GET a policy | http://localhost:8085/A1-P/v1/policies/{policyId} |
  96 |  DELETE a policy instance | http://localhost:8085/A1-P/v1/policies/{policyId} |
  97 |  GET a policy status | http://localhost:8085/A1-P/v1/policies/{policyid}/status |
  98
  99 Swagger UI at: http://localhost:8085/A1-P/v1/ui/
 100
 101 For the documentation of the admin API, see [A1 Standard 1.1.3](https://docs.o-ran-sc.org/projects/o-ran-sc-sim-a1-interface/en/latest/simulator-api.html#a1-standard-1-1-3).
 102
 103 ## URIs for admin operations:
 104
 105 | Function              | Path and parameters |
 106 | --------------------- | ------------------- |
 107 |  GET, a basic healthcheck | http://localhost:8085/ |
 108 |  GET, a list of all supported interfaces | http://localhost:8085/container_interfaces |
 109 |  POST, delete all policy instances | http://localhost:8085/deleteinstances |
 110 |  POST, full reset | http://localhost:8085/deleteall |
 111 |  POST, force a specific response code for an A1 operation | http://localhost:8085/forceresponse?code=&lt;http-code&gt; |
 112 |  POST, force delayed response of all A1 operations | http://localhost:8085/forcedelay?delay=&lt;seconds&gt; |
 113 |  PUT, set status and optional reason | http://localhost:8085/status?status=&lt;status&gt;[&amp;reason=&lt;reason&gt;] |
 114 |  POST, send status for policy | http://localhost:8085/sendstatus?policyid=&lt;policyid&gt; |
 115 |  GET a counter <br> (counter-name: 'num_instances', 'num_types'(always 0), 'interface' or 'remote_hosts') | http://localhost:8085/counter/&lt;counter-name&gt; |
 116 |  Turn on HTTP header and payload logging | http://localhost:8085/payload_logging/on |
 117 |  Turn off HTTP header and payload logging | http://localhost:8085/payload_logging/off |
 118
 119 # Supported operations in simulator A1 Standard 2.0.0
 120
 121 For the complete YAML specification, see [STD_A1.yaml](../near-rt-ric-simulator/api/STD_2.0.0/STD_A1.yaml).
 122
 123 ## URIs for A1:
 124
 125 | Function              | Path and parameters |
 126 | --------------------- | ------------------- |
 127 |  GET all policy identities | http://localhost:8085/A1-P/v2/policies |
 128 |  PUT a policy instance(create or update it) | http://localhost:8085/A1-P/v2/policies/{policyId} |
 129 |  GET a policy | http://localhost:8085/A1-P/v2/policies/{policyId} |
 130 |  DELETE a policy instance | http://localhost:8085/A1-P/v2/policies/{policyId} |
 131 |  GET a policy status | http://localhost:8085/A1-P/v2/policies/{policyid}/status |
 132
 133 Swagger UI at: http://localhost:8085/A1-P/v2/ui/
 134
 135 For the documentation of the admin API, see [A1 Standard 2.0.0](https://docs.o-ran-sc.org/projects/o-ran-sc-sim-a1-interface/en/latest/simulator-api.html#a1-standard-2-0-0).
 136
 137 ## URIs for admin operations:
 138
 139 | Function              | Path and parameters |
 140 | --------------------- | ------------------- |
 141 |  GET, a basic healthcheck | http://localhost:8085/ |
 142 |  GET, a list of all supported interfaces | http://localhost:8085/container_interfaces |
 143 |  POST, delete all policy instances | http://localhost:8085/deleteinstances |
 144 |  POST, full reset | http://localhost:8085/deleteall |
 145 |  POST, force a specific response code for an A1 operation | http://localhost:8085/forceresponse?code=&lt;http-code&gt; |
 146 |  POST, force delayed response of all A1 operations | http://localhost:8085/forcedelay?delay=&lt;seconds&gt; |
 147 |  PUT, set status and optional reason | http://localhost:8085/status?status=&lt;status&gt;[&amp;reason=&lt;reason&gt;] |
 148 |  POST, send status for policy | http://localhost:8085/sendstatus?policyid=&lt;policyid&gt; |
 149 |  GET a counter <br> (counter-name: 'num_instances', 'num_types'(always 0), 'interface' or 'remote_hosts') | http://localhost:8085/counter/&lt;counter-name&gt; |
 150 |  Turn on HTTP header and payload logging | http://localhost:8085/payload_logging/on |
 151 |  Turn off HTTP header and payload logging | http://localhost:8085/payload_logging/off |
 152
 153 # Configuring the simulator
 154
 155 The simulator needs some mandatory environment variables to be set.
 156
 157 | Env variable | Description | Example |
 158 | ------------ | ----------- |---------|
 159 |A1_VERSION| *MANDATORY*: 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.| A1_VERSION=STD_1.1.3|
 160 |REMOTE_HOSTS_LOGGING| *OPTIONAL*: can be set (any value is ok) and the the counter remote_hosts will log the host names of all remote hosts that has accessed the A1 URIs. If host names cannot be resolved, the ip address of the remote host is logged instead. This logging is default off so must be configured to be enabled. If not configured, the counter remote_hosts will return a fixed text indicating that host name logging is not enabled. Use this feature with caution, remote host lookup may take time in certain environments.| REMOTE_HOSTS_LOGGING=1|
 161 |DUPLICATE_CHECK| *OPTIONAL*: can be set to '1' to turn on duplicate check of policy json. A duplicate policy is when the policy json is exactly same as for a different policy id of the same type.  This function is default set off if the variable is not set at all or set to '0'.|DUPLICATE_CHECK=0|
 162
 163 The simulator can also run using the **https** protocol. The enable https, a valid certificate and key need to provided. There is self-signed certificate available in the certificate dir and that dir shall be mounted to the container to make it available
 164
 165 By default, this image has default certificates under /usr/src/app/cert
 166 file "cert.crt" is the certificate file
 167 file "key.crt" is the key file
 168 file "generate_cert_and_key.sh" is a shell script to generate certificate and key
 169 file "pass" stores the password when you run the shell script
 170
 171 Start the a1-interface container without specifing external certificates:
 172
 173 ```shell
 174 docker run --rm -it -p 8085:8085 -p 8185:8185 -e A1_VERSION=STD_1.1.3 -e REMOTE_HOSTS_LOGGING=1 -e DUPLICATE_CHECK=0 a1test
 175 ```
 176
 177 It will listen to https 8185 port(using default certificates) by default.
 178 Http can be enabled on port 8085 using an environment variable "ALLOW_HTTP".
 179 If this environment variable is left out or set to false, the nginx server will send
 180 "444 Connection Closed Without Response" when making a call using http.
 181 Example command to enable http:
 182
 183 ```shell
 184 docker run -it -p 8085:8085 -p 8185:8185 -e A1_VERSION=OSC_2.1.0 -e ALLOW_HTTP=true -e DUPLICATE_CHECK=0 a1test
 185 ```
 186
 187 This certificates/key can be overriden by mounting a volume when using "docker run" or "docker-compose"
 188 In 'docker run', use field:
 189 --volume "$PWD/certificate:/usr/src/app/cert" a1test
 190
 191 In 'docker-compose.yml', use field:
 192 ```yaml
 193 volumes:
 194       - ./certificate:/usr/src/app/cert:ro
 195 ```
 196 In docker run the full command could look like this:
 197 ```shell
 198 docker run -it -p 8085:8085 -p 8185:8185 -e A1_VERSION=STD_1.1.3 -e ALLOW_HTTP=true -e REMOTE_HOSTS_LOGGING=1 -e DUPLICATE_CHECK=0 --volume /PATH_TO_CERT_DIR/certificate:/usr/src/app/cert a1test
 199 ```
 200 http port 8085 and https port 8185
 201
 202 The variable for A1 version is set with the '-e' flag.
 203
 204 With logging of remote host enabled `-e REMOTE_HOSTS_LOGGING=1`
 205
 206 With policy json duplicate check set to off (0)
 207
 208 With certificate dir mounted  `--volume /PATH_TO_CERT_DIR/certificate:/usr/src/app/cert`
 209
 210 To access the Healthcheck endpoint, you can use curl:
 211
 212 ```bash
 213 curl http://localhost:8085/a1-p/healthcheck
 214 ```
 215 To access the Swagger UI, open the following URL in your web browser:
 216
 217 - http://localhost:8085/ui/
 218 - http://localhost:8085/A1-P/v1/ui/
 219 - http://localhost:8085/A1-P/v2/ui/
 220
 221 # Updating the openapi specs
 222 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.
 223
 224 # Start and test of the simulator
 225 See also [Basic test and code coverage](#basic-test-and-code-coverage).
 226
 227 First, download the sim/a1-interface repo on gerrit:
 228 git clone "https://gerrit.o-ran-sc.org/oransc/sim/a1-interface"
 229
 230 Go to the main directory, 'a1-interface/near-rt-ric-simulator'.
 231 There is a folder 'test/version/' 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.
 232
 233 Go to the test folder of the selected version, 'test/version/'.
 234
 235 Note that test can be performed both using the nonsecure http port and the secure https port.
 236
 237 Build and start the simulator containers: STD_1.1.3 and OSC_2.1.0, using:
 238 ```shell
 239 ./build_and_start.sh duplicate-check|ignore-duplicate
 240 ```
 241 Build and start the simulator container version STD_2.0.0, using two alternatives: ext-srv or kafka-srv. However, both can not be used at the same time to start A1 sim.
 242
 243 In order to start with ext-srv:
 244 ```shell
 245 ./build_and_start.sh duplicate-check|ignore-duplicate ext-srv|ext-srv-secure|ignore-ext-srv
 246 ```
 247
 248 In order to start with kafka-srv:
 249 ```shell
 250 ./build_and_start.sh duplicate-check|ignore-duplicate kafka-srv|kafka-srv-secure publish-resp|ignore-publish
 251 ```
 252 STD_2.0.0 version is now including an external server that is a Python server building RESTful API. The external server supports HTTP/HTTPS protocols.
 253 The description of the start parameters are explained below:
 254 ext-srv: Runs external server that supports HTTP protocol only.
 255 ext-srv-secure: Runs external server that supports HTTPS protocol as well.
 256 ignore-ext-srv: Ignores external server to run.
 257
 258 STD_2.0.0 version also includes an kafka message dispatcher that is a Python server building RESTful APIs. The kafka server supports HTTP/HTTPS protocols.
 259 The description of the start parameters are explained below:
 260 kafka-srv: Runs kafka server that supports HTTP protocol only.
 261 kafka-srv-secure: Runs kafka server that supports HTTPS protocol as well.
 262 publish-resp: The flag controls the dispatcher module to decide auto responding to each requests for test purposes only.
 263 ignore-publish: If the A1 sim is being started using ignore flag, then the dispatcher module will look for a respone message published by south-bound module.
 264
 265 This will build and start the container in interactive mode. The built container only resides in the local docker repository.
 266 Note, the default port is 8085 for http and 8185 for https. When running the simulator as a container, the defualt ports can be re-mapped to any port on the localhost.
 267
 268 In a second terminal, go to the same folder and run the basic test script, basic_test.sh nonsecure|secure or commands.sh nonsecure|secure duplicate-check|ignore-duplicate for STD_1.1.3 and OSC_2.1.0 versions.
 269
 270 For the STD_2.0.0 version, in a second terminal, go to the same folder and run the basic test script for external server activated case:
 271 ```shell
 272 ./basic_test.sh nonsecure|secure duplicate-check|ignore-duplicate ext-srv|ext-srv-secure|ignore-ext-srv
 273 ```
 274 The description of the test script parameters are explained below:
 275 nonsecure|secure: Runs test cases with either support of HTTP/HTTPS protocol.
 276 duplicate-check|ignore-duplicate: Runs test cases with either support of duplicate/ignore-duplicate flag for the policies.
 277 ext-srv|ext-srv-secure|ignore-ext-srv: If the simulator started with ext-srv or ext-srv-secure parameter, then one of these options can be used. Otherwise, ignore-ext-srv parameter should be used.
 278
 279 For the STD_2.0.0 version, in a second terminal, go to the same folder and run the basic test script for kafka dispatcher server activated case:
 280 ```shell
 281 ./basic_test.sh nonsecure|secure duplicate-check|ignore-duplicate ext-srv|ext-srv-secure|ignore-ext-srv
 282 ```
 283 The description of the test script parameters are explained below:
 284 nonsecure|secure: Runs test cases with either support of HTTP/HTTPS protocol.
 285 duplicate-check|ignore-duplicate: Runs test cases with either support of duplicate/ignore-duplicate flag in accordance with the one which used while starting A1 sim.
 286 ext-srv|ext-srv-secure|ignore-ext-srv: If the simulator started with kafka-srv or kafka-srv-secure parameter, then ignore-ext-srv option should be used.
 287
 288 Note that the arg for duplicate check must match in both scripts.
 289 This script runs a number of tests towards the simulator to make sure it works properply.
 290
 291 # Basic test and code coverage
 292
 293 Basic test, or unit test, using a python script is also supported. This test basically the same thing as the bash script mentioned in the section above. Follow the instruction of how to clone the repo described in that section.
 294 Only http is tested as the internal flask server is only using http (https is part of the webserver inteface).
 295
 296 Navigate to 'near-rt-ric-simulator/tests'. Choose the version to test and use that file for test.
 297
 298 Use `python3 -m pytest <filename>` to run unit test only with no coverage check. Before running that command, the dependencies which are pytest and connexion should be installed in your virtual environment. If the latest connexion version arises DeprecationWarning, you may try to install connexion with version 2.6.0.
 299
 300 Or use `coverage run  -m pytest <filename>` to run unit test and produce coverage data.
 301
 302 List coverage data by `coverage report -m --include=../../*` - the include flag makes the list to only contain coverage data from the simulator python file.
 303
 304 To use the 'coverage' cmd, coverage need to be installed use `pip install coverage`
 305
 306 ## License
 307
 308 Copyright (C) 2023 Nordix Foundation.
 309 Licensed under the Apache License, Version 2.0 (the "License")
 310 you may not use this file except in compliance with the License.
 311 You may obtain a copy of the License at
 312
 313       http://www.apache.org/licenses/LICENSE-2.0
 314
 315 Unless required by applicable law or agreed to in writing, software
 316 distributed under the License is distributed on an "AS IS" BASIS,
 317 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 318 See the License for the specific language governing permissions and
 319 limitations under the License.
 320
 321 For more information about license please see the [LICENSE](LICENSE.txt) file for details.
 322
 323 ---