# Subscription Manager
-## Table of contents
-* [Introduction](#introduction)
-* [Release notes](#release-notes)
-* [Prerequisites](#prerequisites)
-* [Project folders structure](#project-folders-structure)
-* [Installation guide](#installation-guide)
- * [Compiling code](#compiling-code)
- * [Building docker container](#building-docker-container)
- * [Installing Subscription Manager](#installing-routing-manager)
- * [Testing and Troubleshoting](#testing-and-troubleshoting)
-* [Upcoming changes](#upcoming-changes)
-* [License](#license)
-
-## Introduction
-__Subscription Manager__ is a basic platform service of RIC. It is responsible to serve, coordinate and manage xApps' subscriptions.
-
-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.
-
-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.
-
-Current implementation provides the following functionalities:
-* Handles RIC_SUB_REQ and RIC_SUB_RESP type RMR messages
-* Utilizes E2AP encoder/decoder generated by ASN1-C
-* Generates New subscription ID and forwards subscription request to E2 termination
-* Keeps maintaining the status of subscriptions
-* Receives Subscription response and sends it back to the subscriber
-* Uses SUBMGR_SEED_SN environment variable to initialize subscription ID counter
-
-## Release notes
-Check the separated `RELNOTES` file.
-
-## Prerequisites
-* Healthy kubernetes cluster
-* Access to the common docker registry
+## Subscription Manager User guide
-## Project folder structure
-* /manifest: contains deployment files (Kubernetes manifests)
-* /cmd: contains go project's main file
-* /pkg: contains go project's packages
-* /config: contains default configuration file for the service
-* /test: contains CI/CD testing files (scripts, stubs, mocks, manifests)
+ Subscription manager User guide is available here: https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-submgr/en/latest/user-guide.html
+ The document source is under the submgr/doc directory. Web document is generated automatically from that after the change has been merged
+ in the ORAN Gerrit repo.
-## Installation guide
+## ORAN E2 interface specifications
-### Compiling code
-Enter the project root and execute `docker build -t submgr:tag .`.
-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.
+ WG3: The Near-Real-Time RIC and E2 Interface Workgroup
+ https://www.o-ran.org/specifications
-**NOTE:** If you are behind proxy, see this guide: https://docs.docker.com/network/proxy/#configure-the-docker-client
+## Compiling Subscription Manager code
-### Installing Subscription Manager
-#### Preparing environment
-Tag the `submgr` container according to the project release and push it to a registry accessible from all minions of the Kubernetes cluster.
-Edit the container image section of `submgr-dep.yaml` file and set the `submgr` image tag accordingly.
+### Just to compile Docker image give this command
-#### Deploying Subscription Manager
-Issue the `kubectl create -f {manifest.yaml}` command in the following order
- 1. `manifests/namespace.yaml`: creates the `example` namespace for routing-manager resources
- 2. `manifests/submgr/submgr-dep.yaml`: instantiates the `submgr` deployment in the `example` namespace
- 3. `manifests/submgr/submgr-svc.yaml`: creates the `submgr` service in `example` namespace
+ docker build -t submgr:tag .
-### Testing and Troubleshoting
-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.
+ The command will build the docker image with name 'submgr:tag'. It will run also all the unit tests before image is created.
+ Unit tests may fail randomly. There are some cases which may fail due to incorrect timing. in test case. If error happens just
+ issue the same command to recompile. Tag value can be anything or it can be omitted.
- 1. [Compile](#compiling-code) and [Installing subscription manager](#installing-subscription-manager)
- 2 Enter `./test/dbaas` folder and issue `kubectl apply -f ./manifests`
- 3. Enter `./test/e2t/` folder and run `build.sh`. After docker image successfully built, issue `kubectl apply -f ./manifests`
- 4. Enter `./test/rco/` folder and run `build.sh`. After docker image successfully built, issue `kubectl apply -f ./manifests`
- 5. Configure RMR routes accordingly
+### Compiling code to run unit tests give this command
-Sunny Day testing scenario:
- 1. RCO (stub) sends valid Subscription Requests (12010) to SUBMGR.
- 2. SUBMGR receives RCO's subscription request and generates and puts a new ID in the given request and forwards it to E2T (stub)
- 3. E2T (stub) receives the Subscription Request message and sends a valid Subscription Response (12011) to SUBMGR
- 4. SUBMGR accepts the Subscirption Response and forwards it to RCO (stub)
+ docker build -t submgr . > build.txt
-Rainy Day testing scenarios:
+ The command will build the docker image with name 'submgr:latest'. It will run also all the unit tests before image is created.
+ Compilation and test cases logs are stores in build.txt. Unit tests may fail randomly. There are some cases which may fail due
+ to incorrect timing in test case. If error happens just issue the same command to recompile.
-* Wrong/Malformed Request
- 1. RCO (stub) sends non-subsciption type (10000) message to SUBMGR.
- 2. SUBMGR discards the non-subscription related tye message and emmits an error log entry on it's standard output
- 3. RCO (stub) sends Subscription Request type (12010) messages to SUBMGR but with malformed payload
- 4. SUBMGR accepts the Suubscription Requets but fails to decode so emmits an error log entry on it's standard output
+## Subscription Manager ORAN Helm chart
-* Wrong/Malformed Response
- 1. E2T (stub) sends Subsciption Response type (12011) message to SUBMGR but with wrong Subscription Sequence Number
- 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
- 3. E2T (stub) sends Subscription Response type (12011) messages but with malformed payload to SUBMGR
- 4. SUBMGR accepts the Subscription Response but fails to decode so emmits an error log entry on it's standard output
+ Subscription Manager ORAN Helm chart is stored here: https://gerrit.o-ran-sc.org/r/admin/repos/ric-plt/ric-dep.
-NOTES:
-* 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.
-* 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.
+## How to generate E2AP ASN.1 C-codes
+ E2AP ASN.1 C-codes has been generated using fork of ASN1C tool. The tool is stored here: https://github.com/nokia/asn1c.
-## Configuration and Troubleshooting
-Basic configuration file provided in `./config/` folder. Consult xapp-frame project documentation for custom configuration settings.
-`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
+ Latest version of the tool should be used. Follow Build and Install instructions for the tool on the page.
-## Upcoming changes
-[] Unit tests
+ Generated ASN1 C-codes are stored in submgr/3rdparty/E2AP-v01.00.00 directory. Directory is name based in the specification version.
-[] Full RTMGR integration
+ Note that any E2AP specifications are not allowed to store in ORAN Gerrit repo! Only generated C-code from the specification can
+ be stored there.
-[] Jaeger tracing support
+ Example: Update current E2AP-v01.00.00 version to E2AP-v01.00.01 version.
+
+ Create following directory structure:
+ E2AP-v01.00.01
+ |
+ - spec
+ |
+ - e2ap-v01.00.01.asn
+
+ e2ap-v01.00.01.asn file contains the E2AP v01.00.01 specification's data structures in ASN1 format.
-[] Generate ASN1-C code in build time
+ To generate the ASN.1 C-codes give following command in E2AP-v01.00.01 dir:
+ asn1c -pdu=auto -fincludes-quoted -fcompound-names -fno-include-deps -gen-PER -no-gen-OER -no-gen-example spec/e2ap-v01.00.01.asn
-[] Full RTMGR integration
+ Copy E2AP-v01.00.01 directory with the generated C-codes under submgr/3rdparty directory.
-[] Jaeger tracing support
+ Remove spec directory under E2AP-v01.00.01 directory.
-[] Rainy Day scenarios
+ Remove old submgr/3rdparty/E2AP-v01.00.00 directory.
## License
-This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE)
+
+ This project is licensed under the Apache License, Version 2.0 - see the LICENSES.txt
Code Review / ric-plt / submgr.git / commitdiff