README.md

   1 # Subscription Manager
   2
   3 ## Table of contents
   4 * [Introduction](#introduction)
   5 * [Release notes](#release-notes)
   6 * [Prerequisites](#prerequisites)
   7 * [Project folders structure](#project-folders-structure)
   8 * [Installation guide](#installation-guide)
   9   * [Compiling code](#compiling-code)
  10   * [Building docker container](#building-docker-container)
  11   * [Installing Subscription Manager](#installing-routing-manager)
  12   * [Testing and Troubleshoting](#testing-and-troubleshoting)
  13 * [Upcoming changes](#upcoming-changes)
  14 * [License](#license)
  15
  16 ## Introduction
  17 __Subscription Manager__ is a basic platform service of RIC. It is responsible to serve, coordinate and manage xApps' subscriptions.
  18
  19 Submgr acts as an anchor point for subscription related internal messaging, i.e. every xApp sends its subscription related messages to Submgr. Submgr invokes Routing Manager (Rtmgr) to create or tear down the subscription related routes, and the appropriate E2 Termination to signal the subscription related event also towards the RAN.
  20
  21 The solution base on the [xapp-frame](https://gerrit.o-ran-sc.org/r/admin/repos/ric-plt/xapp-frame) project which provides the common HttpREST, RMR and SDL interfaces.
  22
  23 Current implementation provides the following functionalities:
  24 * Handles RIC_SUB_REQ and RIC_SUB_RESP type RMR messages
  25 * Utilizes E2AP encoder/decoder generated by ASN1-C
  26 * Generates New subscription ID and forwards subscription request to E2 termination
  27 * Keeps maintaining the status of subscriptions
  28 * Receives Subscription response and sends it back to the subscriber
  29 * Uses SUBMGR_SEED_SN environment variable to initialize subscription ID counter
  30
  31 ## Release notes
  32 Check the separated `RELNOTES` file.
  33
  34 ## Prerequisites
  35 * Healthy kubernetes cluster
  36 * Access to the common docker registry
  37
  38 ## Project folder structure
  39 * /manifest: contains deployment files (Kubernetes manifests)
  40 * /cmd: contains go project's main file
  41 * /pkg: contains go project's packages
  42 * /config: contains default configuration file for the service
  43 * /test: contains CI/CD testing files (scripts, stubs, mocks, manifests)
  44
  45 ## Installation guide
  46
  47 ### Compiling code
  48 Enter the project root and execute `docker build -t submgr:tag .`.
  49 The Dockerfile has two main phases. First is the code compilation, where it creates an intermediate container for downloading all dependencies then compiles the code. In the second phase it builds the production ready container.
  50
  51 **NOTE:** If you are behind proxy, see this guide: https://docs.docker.com/network/proxy/#configure-the-docker-client
  52
  53 ### Installing Subscription Manager
  54 #### Preparing environment
  55 Tag the `submgr` container according to the project release and push it to a registry accessible from all minions of the Kubernetes cluster.
  56 Edit the container image section of `submgr-dep.yaml` file and set the `submgr` image tag accordingly.
  57
  58 #### Deploying Subscription Manager
  59 Issue the `kubectl create -f {manifest.yaml}` command in the following order
  60   1. `manifests/namespace.yaml`: creates the `example` namespace for routing-manager resources
  61   2. `manifests/submgr/submgr-dep.yaml`: instantiates the `submgr` deployment in the `example` namespace
  62   3. `manifests/submgr/submgr-svc.yaml`: creates the `submgr` service in `example` namespace
  63
  64 ### Testing and Troubleshoting
  65 Subscription Manager's behaviour can be tested using the provided stub xApp (called RCO) and the stub E2 Termination (called E2T) on the following way.
  66
  67   1. [Compile](#compiling-code) and [Installing subscription manager](#installing-subscription-manager)
  68   2  Enter `./test/dbaas` folder and issue `kubectl apply -f ./manifests`
  69   3. Enter `./test/e2t/` folder and run `build.sh`. After docker image successfully built, issue `kubectl apply -f ./manifests`
  70   4. Enter `./test/rco/` folder and run `build.sh`. After docker image successfully built, issue `kubectl apply -f ./manifests`
  71   5. Configure RMR routes accordingly
  72
  73 Sunny Day testing scenario:
  74   1. RCO (stub) sends valid Subscription Requests (12010) to SUBMGR.
  75   2. SUBMGR receives RCO's subscription request and generates and puts a new ID in the given request and forwards it to E2T (stub)
  76   3. E2T (stub) receives the Subscription Request message and sends a valid Subscription Response (12011) to SUBMGR
  77   4. SUBMGR accepts the Subscirption Response and forwards it to RCO (stub)
  78
  79 Rainy Day testing scenarios:
  80
  81 * Wrong/Malformed Request
  82   1. RCO (stub) sends non-subsciption type (10000) message to SUBMGR.
  83   2. SUBMGR discards the non-subscription related tye message and emmits an error log entry on it's standard output
  84   3. RCO (stub) sends Subscription Request type (12010) messages to SUBMGR but with malformed payload
  85   4. SUBMGR accepts the Suubscription Requets but fails to decode so emmits an error log entry on it's standard output
  86
  87 * Wrong/Malformed Response
  88   1. E2T (stub) sends Subsciption Response type (12011) message to SUBMGR but with wrong Subscription Sequence Number
  89   2. SUBMGR accepts the Suubscription Response but it emmits an error log entry on it's standard output since the given Sequence Number is invalid
  90   3. E2T (stub) sends Subscription Response type (12011) messages but with malformed payload to SUBMGR
  91   4. SUBMGR accepts the Subscription Response but fails to decode so emmits an error log entry on it's standard output
  92
  93 NOTES:
  94 * Both stub component use pre coded E2 message as a skeleton to set or get the `ricRequestSequenceNumber` in it and pass it between the components. The message presented as a hex dump which is inprinted in the code. Use the `RCO_RAWDATA` and `E2T_RAWDATA` environment variables in the pod manifest to override the default skeleton messages.
  95 * RCO (stub) sends Subscription Requests with ID=12345 by default. Use the `RCO_SEED_SN` environment variable in the pod manifest to override this number.
  96
  97
  98 ## Configuration and Troubleshooting
  99 Basic configuration file provided in `./config/` folder. Consult xapp-frame project documentation for custom configuration settings.
 100 `SUBMGR_SEED_SN` environment variable is defined in the pod manifest and used to control the initial value of the Subscription Sequence Number. If this environment variable is undefied, SUBMGR choses a random number from the range of 0-65535
 101
 102 ## Upcoming changes
 103 [] Unit tests
 104
 105 [] Full RTMGR integration
 106
 107 [] Jaeger tracing support
 108
 109
 110 [] Generate ASN1-C code in build time
 111
 112 [] Full RTMGR integration
 113
 114 [] Jaeger tracing support
 115
 116 [] Rainy Day scenarios
 117
 118 ## License
 119 This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE)