near-rt-ric-simulator/test/KAFKA_DISPATCHER/README.md

   1 # O-RAN-SC Kafka Dispatcher Module extension for A1 Simulator
   2
   3 The O-RAN SC dispatcher module is an extension for A1 simulator. It creates a web server building RESTful APIs. It is capable of recieving Rest calls from the northbound simulator version and respond back to it.
   4
   5 The kafka dispatcher module supports GET, PUT and DELETE operations (version of the open API yaml file\):
   6
   7 | Yaml file version          |     Version id      |
   8 | -------------------------- |-------------------- |
   9 | KAFKA_DISPATCHER_api.yaml  |      0.0.1          |
  10
  11 The overall folder structure is \(relative to the location of this README file\):
  12
  13 | Dir              | Description |
  14 | ---------------- | ----------- |
  15 |.                 |Dockerfile, tox.ini and README |
  16 |api               |The open api yaml |
  17 |src               |Python source code |
  18 |certificate       |A self-signed certificate and a key |
  19 |docs              |Auto generated API descriptions in HTML format |
  20
  21 The dispatcher module handles the requests that are defined in the open API yaml file. All these requests are implemented in the dispatcher.py file in the src folder. In addition, a number of administrative functions are also supported and implemented by the main.py in the source folder.
  22
  23 The section below outlines the supported open api rest-based operations as well as the adminstrative operations.
  24
  25 # Ports and certificates
  26
  27 The dispatcher module normally opens the port 7075 for http. If a certificate and a key are provided the kafka dispatcher module will open port 7175 for https instead. The port 7175 is only opened if a valid certificate and key is found.
  28 The certificate and key shall be placed in the same directory and the directory shall be mounted to /usr/src/app/cert in the container.
  29
  30 | Port     | Protocol |
  31 | -------- | ----- |
  32 | 7075     | http  |
  33 | 7175     | https |
  34
  35 The directory certificate contains a self-signed cert. Use the script generate_cert_and_key.sh to generate a new certificate and key. The password of the certificate must be set 'test'.
  36 The same urls are availables on both the http port 7075 and the https port 7175. If using curl and https, the flag -k shall be given to make curl ignore checking the certificate.
  37
  38 # Supported operations in Kafka Dispatcher Module 0.0.1
  39
  40
  41 For the complete yaml specification, see [openapi.yaml](../api/KAFKA_DISPATCHER_api.yaml)
  42
  43 URIs for server:
  44
  45 | Function              | Path and parameters |
  46 | --------------------- | ------------------- |
  47 |  GET, Get the kafka request and response topic map corresponding to policy type | localhost:7075/policytypetotopicmapping/ANR |
  48 |  GET, Dispatch policy status query opertion as kafka message to kafka cluster | localhost:7075/policytypes/ANR/kafkadispatcher/alpha/status |
  49 |  PUT, Dispatch create and update operation as kafka message to kafka cluster | localhost:7075/policytypes/ANR/kafkadispatcher/alpha |
  50 |  DELETE, Dispatch policy delete opertion as kafka message to kafka cluster | localhost:7075/policytypes/ptype1/kafkadispatcher/alpha |
  51
  52 URIs for admin operations:
  53
  54 | Function              | Path and parameters |
  55 | --------------------- | ------------------- |
  56 |  GET, Get status of dispatcher module | http://localhost:7075/ |
  57 |  POST, Force a specific response code for all dispatcher module operations | localhost:7075/dispatcheradmin/forceresponse?code=500 |
  58 |  POST, Reset force response code | localhost:7075/dispatcheradmin/forceresponse |
  59 |  POST, Force delayed response of all dispatcher module operations | localhost:7075/dispatcheradmin/forcedelay?delay=5 |
  60 |  POST, Reset force delayed response | localhost:7075/dispatcheradmin/forcedelay |
  61
  62
  63 ## License
  64
  65 Copyright (C) 2022 Nordix Foundation.
  66 Licensed under the Apache License, Version 2.0 (the "License")
  67 you may not use this file except in compliance with the License.
  68 You may obtain a copy of the License at
  69
  70       http://www.apache.org/licenses/LICENSE-2.0
  71
  72 Unless required by applicable law or agreed to in writing, software
  73 distributed under the License is distributed on an "AS IS" BASIS,
  74 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  75 See the License for the specific language governing permissions and
  76 limitations under the License.
  77
  78 For more information about license please see the [LICENSE](LICENSE.txt) file for details.