From 4e36ac4d6f927db9afb35769d34eaccf69ed5e49 Mon Sep 17 00:00:00 2001 From: Woojoong Kim Date: Mon, 18 Nov 2024 21:38:23 -0800 Subject: [PATCH] fix subdoc --- .github/workflows/publish.yml | 3 + .gitignore | 44 +++---- Makefile | 14 ++- conf.py | 2 +- hw_install_index.rst | 16 +-- index.rst | 36 +++--- onos-a1t/README.md | 29 +++++ onos-a1t/onos-a1t | 1 + onos-api/CODE_OF_CONDUCT.md | 8 ++ onos-api/README.md | 49 ++++++++ onos-api/onos-api | 1 + onos-cli/CODE_OF_CONDUCT.md | 8 ++ onos-cli/README.md | 20 ++++ onos-cli/onos-cli | 1 + onos-config/CODE_OF_CONDUCT.md | 9 ++ onos-config/README.md | 19 +++ onos-config/onos-config | 1 + onos-e2-sm/CODE_OF_CONDUCT.md | 9 ++ onos-e2-sm/README.md | 89 ++++++++++++++ onos-e2-sm/onos-e2-sm | 1 + onos-e2t/CODE_OF_CONDUCT.md | 8 ++ onos-e2t/README.md | 17 +++ onos-e2t/onos-e2t | 1 + onos-exporter/README.md | 107 +++++++++++++++++ onos-exporter/onos-exporter | 1 + onos-kpimon/CODE_OF_CONDUCT.md | 9 ++ onos-kpimon/README.md | 37 ++++++ onos-kpimon/onos-kpimon | 1 + onos-mho/CODE_OF_CONDUCT.md | 9 ++ onos-mho/README.md | 58 +++++++++ onos-mho/onos-mho | 1 + onos-mlb/CODE_OF_CONDUCT.md | 9 ++ onos-mlb/README.md | 79 ++++++++++++ onos-mlb/onos-mlb | 1 + onos-operator/README.md | 123 +++++++++++++++++++ onos-operator/onos-operator | 1 + onos-pci/CODE_OF_CONDUCT.md | 9 ++ onos-pci/README.md | 25 ++++ onos-pci/onos-pci | 1 + onos-proxy/README.md | 47 ++++++++ onos-proxy/onos-proxy | 1 + onos-ric-python-apps/CODE_OF_CONDUCT.md | 9 ++ onos-ric-python-apps/README.md | 15 +++ onos-ric-python-apps/onos-ric-python-apps | 1 + onos-ric-sdk-go/README.md | 37 ++++++ onos-ric-sdk-go/onos-ric-sdk-go | 1 + onos-ric-sdk-py/README.md | 28 +++++ onos-ric-sdk-py/onos-ric-sdk-py | 1 + onos-rsm/CODE_OF_CONDUCT.md | 9 ++ onos-rsm/README.md | 82 +++++++++++++ onos-rsm/onos-rsm | 1 + onos-topo/CODE_OF_CONDUCT.md | 8 ++ onos-topo/README.md | 140 ++++++++++++++++++++++ onos-topo/onos-topo | 1 + onos-uenib/README.md | 60 ++++++++++ onos-uenib/onos-uenib | 1 + ran-simulator/CODE_OF_CONDUCT.md | 9 ++ ran-simulator/README.md | 45 +++++++ ran-simulator/ran-simulator | 1 + sdran-in-a-box/CODE_OF_CONDUCT.md | 9 ++ sdran-in-a-box/README.md | 83 +++++++++++++ sdran-in-a-box/sdran-in-a-box | 1 + 62 files changed, 1396 insertions(+), 51 deletions(-) create mode 100644 onos-a1t/README.md create mode 160000 onos-a1t/onos-a1t create mode 100644 onos-api/CODE_OF_CONDUCT.md create mode 100644 onos-api/README.md create mode 160000 onos-api/onos-api create mode 100644 onos-cli/CODE_OF_CONDUCT.md create mode 100644 onos-cli/README.md create mode 160000 onos-cli/onos-cli create mode 100644 onos-config/CODE_OF_CONDUCT.md create mode 100644 onos-config/README.md create mode 160000 onos-config/onos-config create mode 100644 onos-e2-sm/CODE_OF_CONDUCT.md create mode 100644 onos-e2-sm/README.md create mode 160000 onos-e2-sm/onos-e2-sm create mode 100644 onos-e2t/CODE_OF_CONDUCT.md create mode 100644 onos-e2t/README.md create mode 160000 onos-e2t/onos-e2t create mode 100644 onos-exporter/README.md create mode 160000 onos-exporter/onos-exporter create mode 100644 onos-kpimon/CODE_OF_CONDUCT.md create mode 100644 onos-kpimon/README.md create mode 160000 onos-kpimon/onos-kpimon create mode 100644 onos-mho/CODE_OF_CONDUCT.md create mode 100644 onos-mho/README.md create mode 160000 onos-mho/onos-mho create mode 100644 onos-mlb/CODE_OF_CONDUCT.md create mode 100644 onos-mlb/README.md create mode 160000 onos-mlb/onos-mlb create mode 100644 onos-operator/README.md create mode 160000 onos-operator/onos-operator create mode 100644 onos-pci/CODE_OF_CONDUCT.md create mode 100644 onos-pci/README.md create mode 160000 onos-pci/onos-pci create mode 100644 onos-proxy/README.md create mode 160000 onos-proxy/onos-proxy create mode 100644 onos-ric-python-apps/CODE_OF_CONDUCT.md create mode 100644 onos-ric-python-apps/README.md create mode 160000 onos-ric-python-apps/onos-ric-python-apps create mode 100644 onos-ric-sdk-go/README.md create mode 160000 onos-ric-sdk-go/onos-ric-sdk-go create mode 100644 onos-ric-sdk-py/README.md create mode 160000 onos-ric-sdk-py/onos-ric-sdk-py create mode 100644 onos-rsm/CODE_OF_CONDUCT.md create mode 100644 onos-rsm/README.md create mode 160000 onos-rsm/onos-rsm create mode 100644 onos-topo/CODE_OF_CONDUCT.md create mode 100644 onos-topo/README.md create mode 160000 onos-topo/onos-topo create mode 100644 onos-uenib/README.md create mode 160000 onos-uenib/onos-uenib create mode 100644 ran-simulator/CODE_OF_CONDUCT.md create mode 100644 ran-simulator/README.md create mode 160000 ran-simulator/ran-simulator create mode 100644 sdran-in-a-box/CODE_OF_CONDUCT.md create mode 100644 sdran-in-a-box/README.md create mode 160000 sdran-in-a-box/sdran-in-a-box diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index fe7e90c..5f4cbed 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -133,6 +133,9 @@ jobs: with: python-version: 3.11 + - name: Build docs + run: make html + - name: Build docs run: make multiversion diff --git a/.gitignore b/.gitignore index abf8a8d..b50b482 100644 --- a/.gitignore +++ b/.gitignore @@ -8,27 +8,27 @@ repos .DS_Store # subrepos -sdran-in-a-box -onos-operator -onos-e2t -onos-a1t -onos-e2-sm -onos-api -onos-ric-sdk-go -onos-kpimon -onos-pci -onos-config -onos-topo -onos-uenib -onos-cli -onos-exporter -onos-mlb -onos-mho -onos-rsm -onos-proxy -ran-simulator -openairinterface5g -onos-ric-python-apps -onos-ric-sdk-py +#sdran-in-a-box +#onos-operator +#onos-e2t +#onos-a1t +#onos-e2-sm +#onos-api +#onos-ric-sdk-go +#onos-kpimon +#onos-pci +#onos-config +#onos-topo +#onos-uenib +#onos-cli +#onos-exporter +#onos-mlb +#onos-mho +#onos-rsm +#onos-proxy +#ran-simulator +#openairinterface5g +#onos-ric-python-apps +#onos-ric-sdk-py .idea diff --git a/Makefile b/Makefile index ebb3914..e87393f 100644 --- a/Makefile +++ b/Makefile @@ -65,6 +65,7 @@ clean-all: clean # checkout the repos inside repos/ dir repos: mkdir repos + mkdir -p subdocs # build directory paths in repos/* to perform 'git clone ' into CHECKOUT_REPOS = $(foreach repo,$(OTHER_REPO_DOCS),repos/$(repo)) @@ -90,7 +91,9 @@ $(OTHER_REPO_DOCS): | $(CHECKOUT_REPOS) cd "repos/$@" && git fetch && git checkout $$GIT_REF ;\ fi GIT_SUBDIR=`grep '^$@ ' git_refs | awk '{print $$2}'` ;\ - cp -r repos/$(@)$$GIT_SUBDIR $@ ;\ + mkdir -p $(@) ;\ + cp repos/$(@)$$GIT_SUBDIR*.md $@/ ;\ + cp -r repos/$(@)$$GIT_SUBDIRdocs $@/ ;\ # generate a list of git checksums suitable for updating git_refs freeze: repos @@ -108,8 +111,15 @@ prep: | $(OTHER_REPO_DOCS) # build multiple versions multiversion: $(VENV_NAME) Makefile | prep $(OTHER_REPO_DOCS) source $`_. :hidden: :caption: Components - repos/onos-api/README - repos/onos-ric-sdk-go/README - repos/onos-operator/README - repos/onos-e2t/README - repos/onos-a1t/README - repos/onos-e2-sm/README - repos/onos-kpimon/README - repos/onos-pci/README - repos/onos-config/README - repos/onos-topo/README - repos/onos-uenib/README - repos/onos-proxy/README - repos/onos-cli/README - repos/onos-exporter/README - repos/onos-mlb/README - repos/onos-mho/README - repos/onos-rsm/README - repos/ran-simulator/README + subdocs/onos-api/README + subdocs/onos-ric-sdk-go/README + subdocs/onos-operator/README + subdocs/onos-e2t/README + subdocs/onos-a1t/README + subdocs/onos-e2-sm/README + subdocs/onos-kpimon/README + subdocs/onos-pci/README + subdocs/onos-config/README + subdocs/onos-topo/README + subdocs/onos-uenib/README + subdocs/onos-proxy/README + subdocs/onos-cli/README + subdocs/onos-exporter/README + subdocs/onos-mlb/README + subdocs/onos-mho/README + subdocs/onos-rsm/README + subdocs/ran-simulator/README oai_cu_cp .. toctree:: diff --git a/onos-a1t/README.md b/onos-a1t/README.md new file mode 100644 index 0000000..ad73806 --- /dev/null +++ b/onos-a1t/README.md @@ -0,0 +1,29 @@ + + +# onos-a1t +A1 AP Termination module for ONOS SD-RAN (µONOS Architecture) + +## Overview +The `onos-a1t` is the A1 termination node in the near-RT RIC for A1 interface to communicate the near-RT RIC with the non-RT RIC. +It is the proxy that forwards incoming A1 messages from the non-RT RIC to appropriate xApps or outgoing A1 messages from xApps to the non-RT RIC. +As per the O-RAN Working Group 2 specification, `onos-a1t` should support A1 messages for (i) the policy management, (ii) the enrichment information, and (iii) the machine learning model management. +As of today, since the O-RAN A1 specification only defines the policy management data model, `onos-a1t` only supports the policy management service. + +Regarding O-RAN specifications, `onos-a1t` supports A1 Application Protocol v03.01 and A1 Type Definitions v02.00. + +## Interaction +The `onos-a1t` interacts with at least three nodes: (i) `onos-topo`, (ii) `A1-enabled xApps` and (iii) `non-RT RIC`. +To begin with, `onos-a1t` keeps listening the `onos-topo` to check if there is new `A1-enabled xApps` deployed and if there are `A1-enabled xApps` already running. +Basically, the A1-enabled `xApps` initially stores its A1 interface information, such as supported A1 services (i.e., the policy management, the enrichment information, and the machine learning model management) and A1 interface endpoint (i.e., IP address and port number). +Listening `onos-topo`, `onos-a1t` scrapes the A1 interface information and store it into the `onos-a1t` local store. +With the A1 interface information, `onos-a1t` starts creating the gRPC session with appropriate xApps to communicate with each other. +A gRPC server is the `A1-enabled xApp`, whereas `onos-a1t` acts as the gRPC client (Note that this design is able to support the high availability and reliability by using the replicas for the near future). +In order to communicate with the non-RT RIC, `onos-a1t` has both an HTTP server and an HTTP client. +And of course, the non-RT RIC has to have both the HTTP server and the HTTP client for the bi-directional communication over HTTP. +The HTTP server in `onos-a1t` receives the JSON formatted A1 interface message from the non-RT RIC. +The HTTP client in `onos-a1t` is the client that sends the JSON formatted outgoing A1 interface messages to the non-RT RIC. +The HTTP client and server implementations are auto generated from the OpenAPI definitions provided by the A1 Application Protocol specifications. \ No newline at end of file diff --git a/onos-a1t/onos-a1t b/onos-a1t/onos-a1t new file mode 160000 index 0000000..0975630 --- /dev/null +++ b/onos-a1t/onos-a1t @@ -0,0 +1 @@ +Subproject commit 0975630c8bd0a6e6bb1ec9d346b58c240af643dc diff --git a/onos-api/CODE_OF_CONDUCT.md b/onos-api/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..7f4a722 --- /dev/null +++ b/onos-api/CODE_OF_CONDUCT.md @@ -0,0 +1,8 @@ + + +We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf). + +If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [conduct@opennetworking.org](conduct@opennetworking.org). diff --git a/onos-api/README.md b/onos-api/README.md new file mode 100644 index 0000000..40b325b --- /dev/null +++ b/onos-api/README.md @@ -0,0 +1,49 @@ + + +# onos-api +gRPC API definitions for the µONOS platform + +## Overview +This repository houses not only the `.proto` files, but also a number of automatically generated artifacts, e.g. `.pb.go`, `.py` files and similarly for other languages that may be added in the future. + +The source tree structure is paritioned into `proto`, which contains the canonical protobuf definitions and a top-level directory for each of the supported languages. The structure within each of the language-specific directories reflects the idoms and conventions appropriate to each language. + +## Proto +The top-level package for the protobuf definitions is `onos` and the next level subpackage is the name of the particular platform subsystem, such as `config`, `topo`, etc. This directory tree should contain exclusively the `.proto` files and not be tainted by any other artifacts, especially any language-specific ones. + +The proto files are compiled and processed via `build/bin/compile-protos.sh` script, which is invoked by the `Makefile`. All protofiles here should follow the established guidelines and must pass the protobuf lint checker enforcing these conventions. + +## Golang +The `go` source tree holds the automatically-generated `.pb.go` artifacts and also any manually authored `.go` source files written in support of the Golang bindings. To minimize the churn and to exercise tighter control over versioning, the generated files are also versioned and maintained in the SCM repo. + +The root package of the module is `github.com/onosproject/onos-api/go/onos`, with subpackages being named after each of the platform subsystems, mirroring the structure of the `proto` packages. Golang projects that wish to import µONOS API packages should include the following in the requirements section of their `go.mod` file: + +```go +require ( + ... + github.com/onosproject/onos-api/go v0.6.1 + ... +) + +``` + +Additionally, Go bindings are generated with mocks for testing with [gomock]. Mocks of Protobuf interfaces can be constructed via the same package as the interfaces they mock: + +```go +import topoapi "github.com/onosproject/onos-api/go/onos/topo" +... +mockClient := topoapi.NewMockTopoClient(ctrl) +``` + +## Python + +The `python` source tree holds gRPC bindings are generated for [Python]. Pyhton bindings are generated with the [python-betterproto] protoc plugin and support Python3's `asyncio` framework. + +[gomock]: https://github.com/golang/mock +[Go]: https://golang.org/ +[Protobuf]: https://developers.google.com/protocol-buffers +[Python]: https://www.python.org +[python-betterproto]: https://github.com/danielgtaylor/python-betterproto diff --git a/onos-api/onos-api b/onos-api/onos-api new file mode 160000 index 0000000..fbdd323 --- /dev/null +++ b/onos-api/onos-api @@ -0,0 +1 @@ +Subproject commit fbdd3234086ac94193a145c4b46d410ecf4247b0 diff --git a/onos-cli/CODE_OF_CONDUCT.md b/onos-cli/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..b709e6c --- /dev/null +++ b/onos-cli/CODE_OF_CONDUCT.md @@ -0,0 +1,8 @@ + + +We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf). + +If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [conduct@opennetworking.org](conduct@opennetworking.org). diff --git a/onos-cli/README.md b/onos-cli/README.md new file mode 100644 index 0000000..32faf0f --- /dev/null +++ b/onos-cli/README.md @@ -0,0 +1,20 @@ + + +# onos-cli +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/onosproject/onos-cli/blob/master/LICENSE) +[![Go Report Card](https://goreportcard.com/badge/github.com/onosproject/onos-cli)](https://goreportcard.com/report/github.com/onosproject/onos-cli) +[![GoDoc](https://godoc.org/github.com/onosproject/onos-cli?status.svg)](https://godoc.org/github.com/onosproject/onos-cli) + +This is the implementation of a consolidated `onos` command-line interface for ONOS (µONOS Architecture) + +The goal is to provide a single CLI executable that can be used as a means to access CLI functionality +of a number of different ONOS subsystems, e.g. topo, config, control. + +* [Deploying onos-cli with Helm](docs/deployment.md) +* [ONOS command line client](docs/cli/onos.md) + + + diff --git a/onos-cli/onos-cli b/onos-cli/onos-cli new file mode 160000 index 0000000..3981659 --- /dev/null +++ b/onos-cli/onos-cli @@ -0,0 +1 @@ +Subproject commit 39816595f65c52a4d26927c24bba09991861645b diff --git a/onos-config/CODE_OF_CONDUCT.md b/onos-config/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..28be4cb --- /dev/null +++ b/onos-config/CODE_OF_CONDUCT.md @@ -0,0 +1,9 @@ + + +We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf). + +If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [conduct@opennetworking.org](conduct@opennetworking.org). diff --git a/onos-config/README.md b/onos-config/README.md new file mode 100644 index 0000000..ab3f5c4 --- /dev/null +++ b/onos-config/README.md @@ -0,0 +1,19 @@ + + +# onos-config +[![Go Report Card](https://goreportcard.com/badge/github.com/onosproject/onos-config)](https://goreportcard.com/report/github.com/onosproject/onos-config) +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/gojp/goreportcard/blob/master/LICENSE) +[![Coverage Status](https://img.shields.io/coveralls/github/onosproject/onos-config/badge.svg)](https://coveralls.io/github/onosproject/onos-config?branch=master) +[![GoDoc](https://godoc.org/github.com/onosproject/onos-config?status.svg)](https://godoc.org/github.com/onosproject/onos-config) + + +ONOS Configuration subsystem built using the µONOS architecture + +You can find all the documentation under [docs](docs) directory. +A good place to start is the [README](docs/README.md). + +Overall µONOS documentation is also published on its own [website](https://docs.onosproject.org). diff --git a/onos-config/onos-config b/onos-config/onos-config new file mode 160000 index 0000000..81df3d0 --- /dev/null +++ b/onos-config/onos-config @@ -0,0 +1 @@ +Subproject commit 81df3d0c46da9aa61ca340bb4396ec5d3b47cc9d diff --git a/onos-e2-sm/CODE_OF_CONDUCT.md b/onos-e2-sm/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..28be4cb --- /dev/null +++ b/onos-e2-sm/CODE_OF_CONDUCT.md @@ -0,0 +1,9 @@ + + +We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf). + +If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [conduct@opennetworking.org](conduct@opennetworking.org). diff --git a/onos-e2-sm/README.md b/onos-e2-sm/README.md new file mode 100644 index 0000000..c3b7675 --- /dev/null +++ b/onos-e2-sm/README.md @@ -0,0 +1,89 @@ + + +# onos-e2-sm +[O-RAN] defines the **E2 Service Models** in the form of "ASN.1" specifications. + +Each Service Model defines 5 top level objects: +1. **RAN Function Description** (from the E2Node, describes the supported actions and triggers) +1. **Event Trigger Defintion** (contained in a `RICSubscriptionRequest`, defines the conditions on which E2Node should send a `RICIndication`) +1. **Action Definition** (contained in a `RICSubscriptionRequest`, defines the actions on an E2Node) +1. **Indication Header** (contained in a `RICIndication`, describes general parameters of the source E2 Node) +1. **Indication Message** (contained in a `RICIndication`, describes specific parameters requested) + +## Implementation in SD-RAN +The `onos-e2-sm` project provides, for each of these Service Models: +* A Protobuf translation of these ASN.1 specifications e.g. [e2sm_kpm_ies.proto](servicemodels/e2sm_kpm/v1beta1/e2sm_kpm_ies.proto) +* Go code mapping between Protobuf and ASN.1 PER encoding + +The implementation can be accessed as either: +* a Go module e.g. `go get github.com/onosproject/onos-e2-sm/servicemodels/e2sm_kpm@v0.7.0` + (preferred for **xApps** who only need to access the Proto defintions) or +* as a Go **plugin** e.g. `e2sm_kpm.so.1.0.0` (allowing a loose coupling with `onos-e2t` and `ran-simulator`) + +> Since dynamically loaded modules in Go require being compiled in the code of the target they will plugin to, there +> are 2 versions of the plugin docker file produced `onosproject/service-model-docker-e2sm_kpm-1.0.0` +> and `onosproject/service-model-ransim-e2sm_kpm-1.0.0` + +> Third party vendors will be able to build their own Service Models and load them in to `onos-e2t` using the plugin method, +> and will be able to access the translated Protobuf in corresponding xApps + +### Key Performance Metrics (E2SM_KPM) +This is the first E2 Service Model to be handled by SD-RAN - it is for extracting statistics from the E2Node. + +Currently supported version is E2SM KPM v2.0.3. E2SM KPM v1 is partially implemented and not supported anymore. + +There is also an implementation of KPMv2 SM with Go-based APER library (produces APER bytes out of Protobuf). + + +### Native Interface (E2SM_NI) +While the Proto definitions have been created for this Service Model, the Go mapping code has not been implemented in SD-RAN yet. + +### RAN Control (E2SM_RC_PRE) +Pre-standard E2 Service model with PCI and Neighbor relation table information from E2 Nodes. + +There is also an implementation of RC-PRE SM with Go-based APER library. + +### Mobile HandOver (E2SM_MHO) +E2 Service model for handling Mobile HandOver use case. + +There is also an implementation of MHO SM with Go-based APER library. + +### RAN Slicing (E2SM_RSM) +E2 service model for handling RAN Slicing use case. It was implemented with Go-based APER library. + +## Development +Service models are created from the ASN1 models stored at: +https://github.com/onosproject/openairinterface5g/tree/develop-onf/openair2/RIC_AGENT/MESSAGES/ASN1/R01 + +From these: + +* Protobuf is generated with `asn1c -B` (requires the specially modified version of `asn1c` tool - [asn1c](https://github.com/onosproject/asn1c)) +* Go code is generated from this Protobuf as an interface/reusable layer e.g. [e2sm_kpm_ie.pb.go](servicemodels/e2sm_kpm/v1beta1/e2sm-kpm-ies/e2sm_kpm_ies.pb.go) +* C code is generated the version of the `asn1c` tool from the [O-RAN Software Community](https://gerrit.o-ran-sc.org/r/admin/repos/com/asn1c) + with `asn1c -fcompound-names -fincludes-quoted -fno-include-deps -findirect-choice -gen-PER -no-gen-OER -D.` e.g. [E2SM-KPM-IndicationHeader.h](servicemodels/e2sm_kpm/kpmctypes/E2SM-KPM-IndicationHeader.h) +* Then glue code is generated by hand (at first) using `CGO` (wrapping the C code in Go) e.g. [E2SM-KPM-IndicationHeader.go](servicemodels/e2sm_kpm/kpmctypes/E2SM-KPM-IndicationHeader.go) + * It's also possible to use `protoc-gen-cgo`, a `protoc` plugin that prints CGo code out of Protobuf. Some hand tweaks are still needed to be done. + +> To generate the C code with the O-RAN Software Community version of the `asn1c` tool, +> it must be installed on your system with `sudo make install`. +> This is because it takes skeleton file from `/usr/local/share/asn1c` +> regardless of where it is run from. + +### The E2AP (E2 Application Protocol) is not a Service Model, and so is kept completely inside the `onos-e2t`, see [here](https://github.com/onosproject/onos-e2t/blob/master/api/e2ap/README.md). + +[O-RAN]: https://www.o-ran.org/ + +# FAQ +### - How to create your own SM? +[Here](docs/sm-howto.md) you can find a tutorial on how to create your own SM. + +### - What to do if an encoding/decoding error happens? +A comprehensive guide on how to deal with encoding/decoding errors could be found [here](docs/encoding_issues-howto.md). +It also describes the APER tags usage within the Protobuf. + +### - Is there any description of the error messages produced by the Go APER library? +Yes, a brief description of the most common error messages can be found [here](https://github.com/onosproject/onos-lib-go/blob/master/pkg/asn1/aper/error_list.md). \ No newline at end of file diff --git a/onos-e2-sm/onos-e2-sm b/onos-e2-sm/onos-e2-sm new file mode 160000 index 0000000..d0b568b --- /dev/null +++ b/onos-e2-sm/onos-e2-sm @@ -0,0 +1 @@ +Subproject commit d0b568b60f1507ecdd8bc6eab10a91d2b2b0b1ad diff --git a/onos-e2t/CODE_OF_CONDUCT.md b/onos-e2t/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..07441c7 --- /dev/null +++ b/onos-e2t/CODE_OF_CONDUCT.md @@ -0,0 +1,8 @@ + +We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf). + +If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [conduct@opennetworking.org](conduct@opennetworking.org). diff --git a/onos-e2t/README.md b/onos-e2t/README.md new file mode 100644 index 0000000..a1bfdf6 --- /dev/null +++ b/onos-e2t/README.md @@ -0,0 +1,17 @@ + +# onos-e2t +E2 AP Termination module for ONOS SD-RAN (µONOS Architecture) + +## Overview + +The E2 Termination (E2T) acts as an intelligent proxy and adapter for managing the interactions betwen SD-RAN components and E2 nodes. The southbound of E2T implements the E2AP specification (ASN.1 over SCTP), and the northbound implements the onos-e2t API as specified within the [onos-api]. Messages traveling southbound through E2T nodes are converted from Protobuf to ASN.1, and those received from the environment are converted from ASN.1 to Protobuf before they're propagated up through the northbound API. This process can be extended for service models with plugins. + +The E2 termination is shipped as a [Docker] image and deployed with [Helm]. To build the Docker image, run `make images`. + +[onos-api]: https://github.com/onosproject/onos-api +[Docker]: https://www.docker.com/ +[Helm]: https://helm.sh diff --git a/onos-e2t/onos-e2t b/onos-e2t/onos-e2t new file mode 160000 index 0000000..2c7cbeb --- /dev/null +++ b/onos-e2t/onos-e2t @@ -0,0 +1 @@ +Subproject commit 2c7cbebee11da23a5056d9e459b7859253af9930 diff --git a/onos-exporter/README.md b/onos-exporter/README.md new file mode 100644 index 0000000..a363676 --- /dev/null +++ b/onos-exporter/README.md @@ -0,0 +1,107 @@ + + +# onos-exporter +The exporter for ONOS SD-RAN (µONOS Architecture) to scrape, format, and export KPIs to TSDB databases (e.g., Prometheus). + +## Overview +The onos-exporter realizes the collection of KPIs from multiple ONOS SD-RAN components via gRPC interfaces, properly label them according to their namespace and subsystem, and turn them available to be pulled (or pushed to) TSDBs. Currently the implementation supports Prometheus. +It also contain in its chart definitions the dependencies to enable the collection of logs from sd-ran pods. + +## Enable + +To enable logging in sdran components, in the onos-exporter chart values.yaml file enable the following components: +In the chart dependencies, fluent-bit realizes the collection of logs from kubernetes pods and stores them into opensearch database. + +```yaml +import: +... + fluent-bit: + enabled: true + opensearch: + enabled: true +``` + +Important: opensearch requires to set `sysctl -w vm.max_map_count=262144` (and restart the docker service), otherwise the pods stay in a crashloop state. + +Associated with the monitoring of sdran components is the onos-exporter component, the exporter for ONOS SD-RAN (µONOS Architecture) to scrape, format, and export onos KPIs to TSDB databases (e.g., Prometheus). Currently the implementation supports Prometheus. In order to enable onos-exporter, as shown below, make sure the prometheus-stack is enabled too in the onos-exporter chart values.yaml file. + +```yaml +import: +... + prometheus-stack: + enabled: true +``` + +The onos-exporter component supports scraping of metrics from onos-topo, onos-e2t, onos-uenib, onos-kpimon and onos-pci. + +## Deploy onos-exporter + +Given the deployment of sd-ran components already in place in the sdran namespace, onos-exporter can be deployed using the following helm command: + +```text +helm -n sdran install onos-exporter sdran/onos-exporter --set import.fluent-bit.enabled=true --set import.prometheus-stack.enabled=true --set import.opensearch.enabled=true +``` + +To remove onos-exporter deployment using helm run the following command. +```text +helm -n sdran uninstall onos-exporter +``` + + +## Visualize metrics in Grafana + +After deployed, the services and pods related to logging and monitoring will be accessible by making a port-forward rule to the grafana service on port 3000. + +```bash +kubectl -n sdran port-forward svc/onos-exporter-grafana 3000:80 +``` + +Open a browser and access `localhost:3000`. The credentials to access grafana are: +```txt +username: admin +password: prom-operator +``` + +To look at the grafana dashboard for the sdran component logs and KPIs, check in the left menu of grafana the option dashboards and select the submenu Manage (or just access in the browser the address http://localhost:3000/dashboards). + +In the menu that shows, look for the dashboard named `Kubernetes / SD-RAN KPIs` to check the KPIs of the sd-ran components (e.g., kpimon, pci, topo, uenib and e2t). + +Similarly, other dashboards can be found in the left menu of grafana, showing for instance each pod workload in the dashboad `Kubernetes / Compute Resources / Workload`. + + +## Visualize onos-exporter prometheus metrics + +To look at the onos-exporter metrics, it's possible to access the onos-exporter directly or visualize the metrics in grafana. + +To access the metrics directly have a port-forward kubectl command for onos-exporter service: + +```bash +kubectl -n sdran port-forward svc/onos-exporter 9861 +``` + +The example above shows the case when onos-exporter is deployed separately, in case it is deployed via RiaB, list the services (kubectl -n sdran get svc) in order to check what is the name of the grafana service to have the port-forward definition. + +Then access the address `localhost:9861/metrics` in the browser. The exporter shows golang related metrics too. + +To access the metrics using grafana, proceed with the access to grafana. After accessing grafana go to the Explore item on the left menu, on the openned window select the Prometheus data source, and type the name of the metrics to see its visualization and click on the Run query button. + + +## Visualize logs in opensearch dashboards + +Make a port-forward to opensearch-dashboards service on port 5601. + +```bash +kubectl -n sdran port-forward svc/onos-exporter-opensearch-dashboards 5601 +``` + +Open a browser and access `localhost:5601`. The credentials to access opensearch dashboards are: +```txt +username: admin +password: admin +``` + +In there, to access the logs, there is the need to set the index pattern, `fluentbit-*`, and explore the index using the Lucene query syntax. diff --git a/onos-exporter/onos-exporter b/onos-exporter/onos-exporter new file mode 160000 index 0000000..08d3d5d --- /dev/null +++ b/onos-exporter/onos-exporter @@ -0,0 +1 @@ +Subproject commit 08d3d5debee86a47dfb7cee82475e776e0d24544 diff --git a/onos-kpimon/CODE_OF_CONDUCT.md b/onos-kpimon/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..28be4cb --- /dev/null +++ b/onos-kpimon/CODE_OF_CONDUCT.md @@ -0,0 +1,9 @@ + + +We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf). + +If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [conduct@opennetworking.org](conduct@opennetworking.org). diff --git a/onos-kpimon/README.md b/onos-kpimon/README.md new file mode 100644 index 0000000..902251f --- /dev/null +++ b/onos-kpimon/README.md @@ -0,0 +1,37 @@ + + +# onos-kpimon +The xApplication for ONOS SD-RAN (µONOS Architecture) to monitor KPI + +## Overview +The `onos-kpimon` is the xApplication running over ONOS SD-RAN to monitor the KPI. +`onos-kpimon` collects KPIs reported by E2 nodes through the KPM service model version 2.0. +Since ONOS SD-RAN has multiple micro-services running on the Kubernetes platform, `onos-kpimon` should run on the Kubernetes along with the other ONOS SD-RAN micro-services. +In order to deploy `onos-kpimon` on the Kubernetes, a Helm chart is necessary, which is in the `sdran-helm-charts` repository. +Note that this application should be running together with the other SD-RAN micro-services, such as `Atomix`, `onos-operator`, `onos-e2t`, `onos-uenib`, `onos-topo`, and `onos-cli`). +Easily, `sd-ran` umbrella chart can be used to deploy all essential micro-services and `onos-kpimon`. + +## Interaction with the other ONOS SD-RAN micro-services +To begin with, `onos-kpimon` makes a subscription with E2 nodes connected to `onos-e2t` through `onos-topo` based ONOS xApplication SDK. +Creating a subscription, `onos-kpimon` sets `report interval` and `granularity period` which are the monitoring interval parameters. +Once the subscription is done successfully, each E2 node starts sending indication messages periodically to report KPIs to `onos-kpimon`. +Then, `onos-kpimon` decodes each indication message that has KPI monitoring reports and store them to both KPIMON local store, or `onos-uenib`. +A user can check the stored monitoring results through `onos-cli` as below. +Also, if Prometheus and Grafana are enabled, the user can see the stored monitoring results through Grafana dashboard or Prometheus web GUI. + +## Command Line Interface +Go to the `onos-cli`, and command below: +```bash +$ onos kpimon list metrics +Node ID Cell Object ID Cell Global ID Time RRC.Conn.Avg RRC.Conn.Max RRC.ConnEstabAtt.Sum RRC.ConnEstabSucc.Sum RRC.ConnReEstabAtt.HOFail RRC.ConnReEstabAtt.Other RRC.ConnReEstabAtt.Sum RRC.ConnReEstabAtt.reconfigFail +5153 13842601454c001 1454c001 06:23:44.0 0 4 0 0 0 0 0 0 +5153 13842601454c002 1454c002 06:23:44.0 0 1 0 0 0 0 0 0 +5153 13842601454c003 1454c003 06:23:44.0 6 6 0 0 0 0 0 0 +5154 138426014550001 14550001 06:23:44.0 0 5 0 0 0 0 0 0 +5154 138426014550002 14550002 06:23:44.0 4 4 0 0 0 0 0 0 +5154 138426014550003 14550003 06:23:44.0 0 2 0 0 0 0 0 0 +``` diff --git a/onos-kpimon/onos-kpimon b/onos-kpimon/onos-kpimon new file mode 160000 index 0000000..2f332ac --- /dev/null +++ b/onos-kpimon/onos-kpimon @@ -0,0 +1 @@ +Subproject commit 2f332ac2fb47a9d9d7e4055b3f130996bdfc0d08 diff --git a/onos-mho/CODE_OF_CONDUCT.md b/onos-mho/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..28be4cb --- /dev/null +++ b/onos-mho/CODE_OF_CONDUCT.md @@ -0,0 +1,9 @@ + + +We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf). + +If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [conduct@opennetworking.org](conduct@opennetworking.org). diff --git a/onos-mho/README.md b/onos-mho/README.md new file mode 100644 index 0000000..7b015a7 --- /dev/null +++ b/onos-mho/README.md @@ -0,0 +1,58 @@ + + +# onos-mho +Mobile Hand Over (MHO) xApplication for µONOS RIC + +## Overview +[µONOS RIC](https://docs.sd-ran.org/master/index.html) supports collection of per-UE mobility data from E2 nodes for the purpose of enabling development of sophisticated mobility management xApplications. The collected UE data is available to xApplications via the SDKs. `onos-mho` is a sample xApplication that implements a simple A3 event based handover function to demonstrate the mobility management capabilities of µONOS RIC platform. + +The E2 Service Model for Mobile HandOver (E2SM-MHO) specifies procedures over the E2 interface to subscribe to and receive indications of UE mobility information and trigger handovers through control messages. The service model defines two types of indications - 1) UE measurement reports and 2) UE RRC state changes. The UE measurement reports can be triggered by A3 events or periodic. The complete E2SM-MHO ASN.1 specification is available in the +[onos-e2-sm](https://github.com/onosproject/onos-e2-sm/blob/master/servicemodels/e2sm_mho/v1/e2sm-mho.asn1) repo. + +The onos-mho xApp interfaces with µONOS RIC, using the Golang SDK, to subscribe for A3 measurement reports from E2 nodes that support the E2SM-MHO service model. In addition to the A3 Events, onos-mho can be configured to subscribe to RRC state changes and periodic UE measurement reports as well. onos-mho processes the measurement event based on its configured A3 Event parameters. If a handover decision is made, onos-mho sends a handover control message to the E2 node to trigger a handover. In addition, onos-mho also updates `UE-NIB` with UE related information such as RRC state, signal strengths for serving and neighbor cells. + +onos-mho is shipped as a [Docker](https://www.docker.com/) image and deployed with [Helm](https://helm.sh/). To build the Docker image, run `make images`. + +## Getting Started +The E2SM-MHO service model is currently only supported by [RANSim](https://github.com/onosproject/ran-simulator) and not by real CU/DU/gNB. onos-mho can be deployed, alongwith the other µONOS micro-services and `RANSim`, using the [sdran-helm-charts]. Alternatively, it can also be deployed using `SDRAN-in-a-box (RIAB)`. + +### Deploy using Helm charts + +Refer to the [µONOS](https://docs.onosproject.org/developers/deploy_with_helm/) and SD-RAN documentation on how to deploy µONOS SD-RAN micro-services with the sd-ran umbrella helm chart. onos-mho is not enabled by default in the sd-ran umbrella chart. To deploy onos-mho with the other µONOS SD-RAN micro-services, either enable it in the sd-ran helm chart or on the command line as follows: +```bash +helm install --set import.ran-simulator.enabled=true --set import.onos-mho.enabled=true sd-ran sd-ran +``` +By default, RANSim uses the `model.yaml` model file. To use a different model, e.g. the two-cell-two-node-model, specify the model as follows: +```bash +helm install --set import.ran-simulator.enabled=true --set import.onos-mho.enabled=true --set ran-simulator.pci.modelName=two-cell-two-node-model sd-ran sd-ran +``` + +### Deploy using RiaB + +Refer to the [SDRAN-in-a-box](https://docs.sd-ran.org/master/riab_install_index.html) (RIAB) documentation on how to deploy onos-mho within RIAB. For example, the following command deploys `latest` version of onos-mho and µONOS SD-RAN micro-services: +```bash +make riab OPT=mho VER=latest +``` + +### Command Line Interface +The following commands are available in [onos-cli](https://github.com/onosproject/onos-cli) for viewing onos-mho related information: +```bash +$ onos mho get cells +$ onos mho get ues +$ onos uenib get ues [-v] +$ onos uenib get ue [-v] +``` +The information from the above commands on UE handovers and RRC states can be compared to information provided by RANSim using the following CLI commands: +```bash +$ onos ransim get cells +$ onos ransim get ues +$ onos ransim get ue +``` + +### RANSim models +The generic **model.yaml** model, which simulates UEs moving on randomly generated routes, can be used with onos-mho to test handovers. Alternatively, the **two-cell-two-node-model.yaml** model can be used to test onos-mho handover functionality in a more controlled and deterministic manner. Refer to documentation on [RANSim models](https://github.com/onosproject/ran-simulator/blob/master/docs/model.md) for further information. + diff --git a/onos-mho/onos-mho b/onos-mho/onos-mho new file mode 160000 index 0000000..afd47a8 --- /dev/null +++ b/onos-mho/onos-mho @@ -0,0 +1 @@ +Subproject commit afd47a8e7ed5860b70b6c9bf48bdbdfe267d72c5 diff --git a/onos-mlb/CODE_OF_CONDUCT.md b/onos-mlb/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..28be4cb --- /dev/null +++ b/onos-mlb/CODE_OF_CONDUCT.md @@ -0,0 +1,9 @@ + + +We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf). + +If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [conduct@opennetworking.org](conduct@opennetworking.org). diff --git a/onos-mlb/README.md b/onos-mlb/README.md new file mode 100644 index 0000000..2c06251 --- /dev/null +++ b/onos-mlb/README.md @@ -0,0 +1,79 @@ + + +# onos-mlb +The xApplication for ONOS SD-RAN (µONOS Architecture) to balance load among connected cells + +## Overview +The `onos-mlb` is the xApplication running over ONOS SD-RAN to balance the load among connected cells. +For the load balancing, this application adjusts neighbor cells' cell individual offset (Ocn). +If a cell becomes overloaded, this application tries to offload the cell's load to the neighbor cells that have enough capacity. +Adjusting neighbor cells' `Ocn` triggers measurement events; it triggers handover events from a cell to it's neighbor cells. +As a result, by adjusting `Ocn`, the load of overloaded cell will be offloaded to the neighbor cells. + +## Limitation +As of now, `onos-mlb` application only supports the scenario where an E2 node manages only a single cell. +It does not support the E2 node that controls multiple cells. + +## Algorithm description +To begin with, `onos-mlb` defines each cell's load as `the number of active UEs`, not considering other factors yet. +If a cell services the most active UEs, the `onos-mlb` application considers that the cell suffers from the heaviest load. +Then, this application defines two thresholds: (i) `overload threshold` and (ii) `target threshold`. +A cell with the load that exceeds the `overloaded threshold` is an overloaded cell. +On the other hands, a cell with the load that is less than `target threshold` has enough capacity. + +With the above definition, there are two conditions. +(1) if a cell's load > `overload threshold` and its neighbor cell's load < `target threshold`, the xApplication increases `Ocn` of the neighbor cell. +(2) if a cell's load < `target threshold`, the xApplication decreases all neighbors' `Ocn`. + +The increased `Ocn` makes the measurement event happening sensitively, which brings about more handover events happening to move some UEs to the neighbor cells, i.e., offloading. +On the contrary, the measurement events happen conservatively with the decreased `Ocn`; it leads to the less handover events happening to avoid neighbor cells overloaded. + +The described algorithm runs periodically. By default, it is set to 10 seconds. + +The `Ocn` delta value (i.e., how many the application changes Ocn value) is configurable. By default, it is set to 3 to 6. + +## Interaction with other ONOS SD-RAN micro-services +Unlike other xApplications such as `onos-kpimon` and `onos-pci`, `onos-mlb` xApplication does not make a subscription with a specific service model. +In order to monitor cells, it uses `onos-uenib` and `onos-topo`. +Basically, `onos-kpimon` and `onos-pci` store the number of active UEs and cell topology to `onos-uenib`. +In addition, `onos-e2t` stores the basic cell information to `onos-topo`. +`onos-mlb` just periodically scrapes `onos-uenib` and `onos-topo`. +Then, it runs the algorithm with the scraped information as inputs. +After deciding each cell's `Ocn` values, `onos-mlb` sends the control message to the E2 node. +This control message is encoded with `RC-Pre` service model. + +## Command line interface +Go to `onos-cli` and command below for each purpose. +```bash +onos-cli-594848b59d-dr6bv:~$ # to see Ocn values for each cell +onos-cli-594848b59d-dr6bv:~$ onos mlb list ocns +sCell node ID sCell PLMN ID sCell cell ID sCell object ID nCell PLMN ID nCell cell ID Ocn [dB] +5153 138426 1454c001 87893173159116801 138426 1454c002 0 +5153 138426 1454c001 87893173159116801 138426 1454c003 6 +5154 138426 1454c002 87893173159116802 138426 1454c001 0 +5154 138426 1454c002 87893173159116802 138426 1454c003 6 +5155 138426 1454c003 87893173159116803 138426 1454c001 -6 +5155 138426 1454c003 87893173159116803 138426 1454c002 -6 + +onos-cli-594848b59d-dr6bv:~$ # to see mlb parameters +onos-cli-594848b59d-dr6bv:~$ onos mlb list parameters +Name Value +interval [sec] 10 +Delta Ocn per step 3 +Overload threshold [%] 100 +Target threshold [%] 0 +Set parameters: + +onos-cli-594848b59d-dr6bv:~# to change mlb parameters +onos-cli-594848b59d-dr6bv:~$ onos mlb set parameters --interval 20 +onos-cli-594848b59d-dr6bv:~$ onos mlb list parameters +Name Value +interval [sec] 20 +Delta Ocn per step 3 +Overload threshold [%] 100 +Target threshold [%] 0 +``` \ No newline at end of file diff --git a/onos-mlb/onos-mlb b/onos-mlb/onos-mlb new file mode 160000 index 0000000..bcdbaff --- /dev/null +++ b/onos-mlb/onos-mlb @@ -0,0 +1 @@ +Subproject commit bcdbaff3562cbc88c941329ce99caffa31239e5d diff --git a/onos-operator/README.md b/onos-operator/README.md new file mode 100644 index 0000000..676b2a1 --- /dev/null +++ b/onos-operator/README.md @@ -0,0 +1,123 @@ + + +# Kubernetes Operator for µONOS + +This project provides a set of [Kubernetes operators][Operator pattern] for managing components of the µONOS +architecture. µONOS operators extend the Kubernetes API with [custom resources] and integrate µONOS subsystems +with the Kubernetes control plane. + +To install the µONOS operator you can use Helm as follows: + +```bash +> helm install -n kube-system onos-operator onosproject/onos-operator --wait +NAME: onos-operator +LAST DEPLOYED: Tue Oct 12 20:02:04 2021 +NAMESPACE: kube-system +STATUS: deployed +REVISION: 1 +TEST SUITE: None +``` +The operator consists of a `topo-operator` pod and `app-operator` pod, all of which will be installed in the +`kube-system` namespace by default. + +```bash +> kubectl get pods -n kube-system +NAME READY STATUS RESTARTS AGE +onos-operator-app-585d588d5c-ndvkr 1/1 Running 0 42m39s +onos-operator-topo-7ff4df6f57-6p8dv 1/1 Running 0 42m39s +``` + +## App Operator +The application operator registers a mutating admission webhook to intercept pod deployment requests. These +requests are inspected for presence of `proxy.onosproject.org/inject` metadata annotation. If this +annotation is present and its value is `true`, the deployment request will be augmented to include a +sidecar `onosproject/onos-proxy` container as part of the pod. + +For more information about see [onos-proxy]. + +## Topology Operator + +The topology operator extends the Kubernetes API with custom resources for defining µONOS topology objects. Topology +resources are propagated from the Kubernetes API to the [onos-topo] service via the [onos-api]. When a topology resource +is created, the topology operator adds the object to µONOS topology. When a topology resource is deleted, the operator +will remove the associated object from the µONOS topology. + +### Kind + +To define a topology object kind, create a `Kind` resource: + +```yaml +apiVersion: topo.onosproject.org/v1beta1 +kind: Kind +metadata: + name: e2-node +spec: + attributes: + foo: bar +``` + +### Entity + +To define a topology entity, create an `Entity` resource: + +```yaml +apiVersion: topo.onosproject.org/v1beta1 +kind: Entity +metadata: + name: e2-node-1 +spec: + kind: + name: e2-node + attributes: + baz: foo +``` + +### Relation + +To define a topology relation, create a `Relation` resource connecting a `source` and `target` entity: + +```yaml +apiVersion: topo.onosproject.org/v1beta1 +kind: Relation +metadata: + name: e2-node-1-e2t-1 +spec: + kind: + name: e2-connection + source: + name: e2-node-1 + target: + name: e2t-1 +``` + +### Dynamic topology management + +The topology operator supports dynamic entity sets with Kubernetes label selectors using the `Service` resource: + +```yaml +apiVersion: topo.onosproject.org/v1beta1 +kind: Service +metadata: + name: my-app +spec: + selector: + matchLabels: + name: my-app + kind: + name: my-app-node +``` + +The operator will automatically populate the µONOS topology with an entity for each pod matching the service's label +selector. This allows dynamic/autoscaling Kubernetes components like `ReplicaSet`s to be represented as dynamic +objects in the µONOS topology. + +[Operator pattern]: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/ +[custom resources]: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/ +[onos-api]: https://github.com/onosproject/onos-api +[onos-topo]: https://github.com/onosproject/onos-topo +[onos-config]: https://github.com/onosproject/onos-config +[onos-proxy]: https://github.com/onosproject/onos-proxy diff --git a/onos-operator/onos-operator b/onos-operator/onos-operator new file mode 160000 index 0000000..a2687b2 --- /dev/null +++ b/onos-operator/onos-operator @@ -0,0 +1 @@ +Subproject commit a2687b2616cee8cee1b0c84b5bc5df0a8b4c7c79 diff --git a/onos-pci/CODE_OF_CONDUCT.md b/onos-pci/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..28be4cb --- /dev/null +++ b/onos-pci/CODE_OF_CONDUCT.md @@ -0,0 +1,9 @@ + + +We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf). + +If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [conduct@opennetworking.org](conduct@opennetworking.org). diff --git a/onos-pci/README.md b/onos-pci/README.md new file mode 100644 index 0000000..e88d75e --- /dev/null +++ b/onos-pci/README.md @@ -0,0 +1,25 @@ + + +# onos-pci +PCI xAPP for ONOS SD-RAN (µONOS Architecture) + +## Overview +The onos-pci is an xApp running over ONOS SD-RAN and as of now it supports the following features: + +* Provides capability to subscribe to RC-PRE service model and receives indication messages from RAN simulator + +* Provides capability to send control requests to change PCI values in RAN simulator + +* Supports listing of PCI resources such metrics, neighbors, PCI, and PCI conflicts of cell(s) using CLI that is integrated with [onos-cli] + +* Detects PCI conflicts and resolves them based on an algorithm using cell neighbors information + + +See [README.md](docs/README.md) for details of running the onos-pci application. + + +[onos-cli]: https://github.com/onosproject/onos-cli \ No newline at end of file diff --git a/onos-pci/onos-pci b/onos-pci/onos-pci new file mode 160000 index 0000000..26b770f --- /dev/null +++ b/onos-pci/onos-pci @@ -0,0 +1 @@ +Subproject commit 26b770f1f307c9af2e34ffbcf5e952063c218fb7 diff --git a/onos-proxy/README.md b/onos-proxy/README.md new file mode 100644 index 0000000..6271633 --- /dev/null +++ b/onos-proxy/README.md @@ -0,0 +1,47 @@ + + +# onos-proxy +ONOS side-car proxy for various subsystems, e.g. E2T + +The main purpose of the sidecar proxy is to absorb the complexity of interfacing with various +µONOS subsystems. This allows relatively easy implementations of the SDK in various languages, without +re-implementing the complex algorithms for each language. + +Presently, the proxy implements only E2T service load-balancing and routing, but in future may be extended to accommodate sophisticated interactions with other +parts of teh µONOS platform. + +## Deployment +The proxy is intended to be deployed as a sidecar container as part of an application pod. Such deployment +can be arranged explicitly by including the proxy container details in the application Helm chart, but an +easier way is to include the following metadata annotation as part of the `deployment.yaml` file. + +```bigquery +annotations: + proxy.onosproject.org/inject: "true" +``` + +This annotation will be detected by the `onos-app-operator` via its admission hook which will augment the +deployment descriptor to include the proxy container as part of the application pod automatically. + +## E2 Services +The proxy container exposes a locally accessible port on `localhost:5151` where it hosts the following services: + +* E2 Control Service - allows issuing control requests to E2 nodes +* E2 Subscription Service - allows issuing subscribe and unsubscribe requests to E2 nodes + +The E2 proxy tracks the E2T and E2 node mastership state via `onos-topo` information and appropriately forwards +gRPC requests to the E2T instance which is presently the master for the given target E2 node. The target E2 node +ID is extracted from the E2AP request headers + +The mastership information is derived from the `MastershipState` aspect of the E2 node topology entities and +from the `controls` topology relations setup between the E2T and E2 node topology entities. + +The proxy does not manipulate the messages passed between the application and the E2T instances in any manner. + +## SDK Versions + +The `onos-ric-sdk-go` version `0.7.30` or greater and `onos-ric-sdk-py` version `0.1.6` or greater expect +the sidecar proxy to be deployed to work correctly. \ No newline at end of file diff --git a/onos-proxy/onos-proxy b/onos-proxy/onos-proxy new file mode 160000 index 0000000..268a5e0 --- /dev/null +++ b/onos-proxy/onos-proxy @@ -0,0 +1 @@ +Subproject commit 268a5e0f0f31a92c3be52c829a1952d52bf5ee12 diff --git a/onos-ric-python-apps/CODE_OF_CONDUCT.md b/onos-ric-python-apps/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..28be4cb --- /dev/null +++ b/onos-ric-python-apps/CODE_OF_CONDUCT.md @@ -0,0 +1,9 @@ + + +We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf). + +If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [conduct@opennetworking.org](conduct@opennetworking.org). diff --git a/onos-ric-python-apps/README.md b/onos-ric-python-apps/README.md new file mode 100644 index 0000000..feba3b3 --- /dev/null +++ b/onos-ric-python-apps/README.md @@ -0,0 +1,15 @@ + +# onos-ric-python-apps +ONOS RAN Intelligent Controller xApps authored in Python programming language + + +fb-ah-xapp: This app is an adapter to Airhop's eSON service, covering physical cell identifier +(PCI) confict resolution, and mobility load balancing (MLB). + +fb-kpimon-xapp: This app is used to get metrics from an E2 node and ship it to prometheus, an +open-source metrics system. diff --git a/onos-ric-python-apps/onos-ric-python-apps b/onos-ric-python-apps/onos-ric-python-apps new file mode 160000 index 0000000..65cba35 --- /dev/null +++ b/onos-ric-python-apps/onos-ric-python-apps @@ -0,0 +1 @@ +Subproject commit 65cba3537b488984c13d94d7a80b52463debb526 diff --git a/onos-ric-sdk-go/README.md b/onos-ric-sdk-go/README.md new file mode 100644 index 0000000..36c7c10 --- /dev/null +++ b/onos-ric-sdk-go/README.md @@ -0,0 +1,37 @@ + + +# onos-ric-sdk-go +[Go] Application SDK for ONOS RIC (µONOS Architecture) + +The goal of this library is to make application development as easy as possible. To that end, the library should rely +heavily on a set of newly established conventions that will result in certain default behaviours. +To allow some applications to depart from these defaults, the library should be written in a modular +fashion with high level abstractions and behaviours composed of lower-level ones. Most applications should be able +to rely on the top-level abstractions, but some apps may need to instead utilize the lower-level abstraction. + +## Installation + +The SDK is managed using [Go modules]. To include the SDK in your Go application, add the `github.com/onosproject/onos-ric-sdk-go` module to your `go.mod`: + +``` +go get github.com/onosproject/onos-ric-sdk-go +``` + +## Usage + +For the detail usage of each API, you can refer to the following links: + +[E2 API Usage](docs/e2.md) + +[O1 API Usage](docs/o1.md) + +[Topo API Usage](docs/topo.md) + +[A1 API Usage](docs/a1.md) + +[Go]: https://golang.org/ +[Go modules]: https://golang.org/ref/mod +[onos-config]: https://github.com/onosproject/onos-config diff --git a/onos-ric-sdk-go/onos-ric-sdk-go b/onos-ric-sdk-go/onos-ric-sdk-go new file mode 160000 index 0000000..8af1651 --- /dev/null +++ b/onos-ric-sdk-go/onos-ric-sdk-go @@ -0,0 +1 @@ +Subproject commit 8af1651ec083b92809f17dee122dfb9e86872d1d diff --git a/onos-ric-sdk-py/README.md b/onos-ric-sdk-py/README.md new file mode 100644 index 0000000..277f936 --- /dev/null +++ b/onos-ric-sdk-py/README.md @@ -0,0 +1,28 @@ +# onos-ric-sdk-py + +Python Application SDK for ONOS RIC (µONOS Architecture) + +## Description + +This SDK contains two modules, E2 and SDL. + +The SDK uses a sidecar proxy which implements the client side distributed system +and load-balancing logic necessary to communicate to the RIC. + +### E2 module + +The E2 module contains functions that interact with E2 nodes. Apps can subscribe +and unsubscribe to service models, and apps can send E2 control messages to +make changes to E2 nodes. The E2 module interacts with the e2t mode + +### SDL module + +The SDL module contains functions to get topology information from the RIC, for +entities such as E2 nodes and cells. This module to also includes functions to +read and write properties for E2 nodes and cells. + +## Developing + +Run lint/licensing/static checks: `make lint` + +Run unit tests (via `pytest`): `make test` diff --git a/onos-ric-sdk-py/onos-ric-sdk-py b/onos-ric-sdk-py/onos-ric-sdk-py new file mode 160000 index 0000000..1403a4f --- /dev/null +++ b/onos-ric-sdk-py/onos-ric-sdk-py @@ -0,0 +1 @@ +Subproject commit 1403a4f002fae79c22d6692649df42d8be3e11a7 diff --git a/onos-rsm/CODE_OF_CONDUCT.md b/onos-rsm/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..28be4cb --- /dev/null +++ b/onos-rsm/CODE_OF_CONDUCT.md @@ -0,0 +1,9 @@ + + +We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf). + +If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [conduct@opennetworking.org](conduct@opennetworking.org). diff --git a/onos-rsm/README.md b/onos-rsm/README.md new file mode 100644 index 0000000..31ac870 --- /dev/null +++ b/onos-rsm/README.md @@ -0,0 +1,82 @@ + + +# onos-rsm +The xApplication for ONOS-SDRAN (µONOS Architecture) to manage RAN slices + +## Overview +The `onos-rsm` is the xApplication running over ONOS SD-RAN for `RAN Slice Management (RSM)`. +The RAN slice has definitions related with `Quality of Service (QoS)` for associated UEs, such as `time frame rates` and `scheduling algorithms`. +In order to manage the RAN slice, this xApplication `creates`, `deletes`, and `updates` RAN slices through CLI. +Also, this xApplication associates a specific UE to a RAN slice so that the UE can achieve the QoS that is defined in the associated RAN slice. +The `onos-rsm` xApplication subscribes CU E2 nodes as well as DU E2 nodes. +CU E2 nodes report the `EPC Mobility Management (EMM) event` to the `onos-rsm` xApp. +On the other hands, DU E2 nodes receive control messages for RAN slice management and UE-slice association. +The `onos-rsm` xApplication stores all RAN slice information to `onos-topo` and `onos-uenib`. + +## Interaction with other ONOS SD-RAN micro-services +To begin with, `onos-rsm` subscribes `CUs` and `DUs` through `onos-e2t`. +Once `UE` is attached, the `CU` send the indication message to `onos-rsm` to report that the `UE` is connected. +Then, `onos-rsm` stores the attached `UE` information to `onos-uenib`. +When a user creates/deletes/updates a slice through `onos-cli`, `onos-rsm` sends a control message to `DU`. +Likewise, the user associates `UE` with a created slice through `onos-cli`, `onos-rsm` sends a control message to `DU`. +After sending the control message successfully, `onos-rsm` updates `onos-topo` and `onos-uenib`, accordingly. + +## Command Line Interface +Go to `onos-cli` and command below for each purpose + +* Create slice + * DU_E2_NODE_ID: target DU's E2 Node ID (e.g., e2:4/e00/3/c8). + * SCHEDULER_TYPE: scheduler type such as round robin (RR) and proportional fair (PF). + * SLICE_ID: this slice's ID (e.g., 1). + * WEIGHT: time frame rates (e.g., 30). It should be less than 80. + * SLICE_TYPE: downlink (DL) or uplink (UL). + +```bash +onos-cli$ kubectl exec -it deployment/onos-cli -n riab -- onos rsm create slice --e2NodeID --scheduler --sliceID --weight --sliceType + +# example: +onos-cli$ kubectl exec -it deployment/onos-cli -n riab -- onos rsm create slice --e2NodeID e2:4/e00/3/c8 --scheduler RR --sliceID 1 --weight 30 --sliceType DL +``` + +* Update slice + * DU_E2_NODE_ID: target DU's E2 Node ID (e.g., e2:4/e00/3/c8). + * SCHEDULER_TYPE: scheduler type such as round robin (RR) and proportional fair (PF). + * SLICE_ID: this slice's ID (e.g., 1). + * WEIGHT: time frame rates (e.g., 30). It should be less than 80. + * SLICE_TYPE: downlink (DL) or uplink (UL). + +```bash +onos-cli$ kubectl exec -it deployment/onos-cli -n riab -- onos rsm update slice --e2NodeID --scheduler --sliceID --weight --sliceType + +# example: +onos-cli$ kubectl exec -it deployment/onos-cli -n riab -- onos rsm update slice --e2NodeID e2:4/e00/3/c8 --scheduler RR --sliceID 1 --weight 50 --sliceType DL +``` + +* Delete slice + * DU_E2_NODE_ID: target DU's E2 Node ID (e.g., e2:4/e00/3/c8). + * SLICE_ID: this slice's ID (e.g., 1). + * SLICE_TYPE: downlink (DL) or uplink (UL). + +```bash +onos-cli$ kubectl exec -it deployment/onos-cli -n riab -- onos rsm delete slice --e2NodeID --sliceID --sliceType + +# example: +onos-cli$ kubectl exec -it deployment/onos-cli -n riab -- onos rsm delete slice --e2NodeID e2:4/e00/3/c8 --sliceID 1 --sliceType DL +``` + +* UE-slice association + * DU_E2_NODE_ID: target DU's E2 Node ID (e.g., e2:4/e00/3/c8). + * SLICE_ID: this slice's ID (e.g., 1). + * DRB_ID: DRB-ID for the bearer. It should be in onos-uenib. + * DU_UE_F1AP_ID: DU_UE_F1AP_ID. It should be in onos-uenib. + +```bash +onos-cli$ kubectl exec -it deployment/onos-cli -n riab -- onos rsm set association --dlSliceID --e2NodeID --drbID --DuUeF1apID + +# example: +onos-cli$ kubectl exec -it deployment/onos-cli -n riab -- onos rsm set association --dlSliceID 1 --e2NodeID e2:4/e00/3/c8 --drbID 5 --DuUeF1apID 1240 +``` \ No newline at end of file diff --git a/onos-rsm/onos-rsm b/onos-rsm/onos-rsm new file mode 160000 index 0000000..d9652e2 --- /dev/null +++ b/onos-rsm/onos-rsm @@ -0,0 +1 @@ +Subproject commit d9652e28456680ffc3379c249d555d634ba37f7e diff --git a/onos-topo/CODE_OF_CONDUCT.md b/onos-topo/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..b709e6c --- /dev/null +++ b/onos-topo/CODE_OF_CONDUCT.md @@ -0,0 +1,8 @@ + + +We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf). + +If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [conduct@opennetworking.org](conduct@opennetworking.org). diff --git a/onos-topo/README.md b/onos-topo/README.md new file mode 100644 index 0000000..1383726 --- /dev/null +++ b/onos-topo/README.md @@ -0,0 +1,140 @@ + + +# onos-topo +[![Go Report Card](https://goreportcard.com/badge/github.com/onosproject/onos-topo)](https://goreportcard.com/report/github.com/onosproject/onos-topo) +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/gojp/goreportcard/blob/master/LICENSE) +[![GoDoc](https://godoc.org/github.com/onosproject/onos-topo?status.svg)](https://godoc.org/github.com/onosproject/onos-topo) + +## Overview + +The µONOS Topology subsystem provides topology management for µONOS core services and applications. +The topology subsystem structures the topology information as a set of objects, which can be either +`Entity`, `Relation` or a `Kind`. + +* `Entity` objects are nodes in a graph and are generally intended to represent network devices, control entities, +control domains, and so on. +* `Relation` objects are edges in a graph and are intended to represent various types of relations between two +`Entity` objects, e.g. `contains`, `controls`, `implements`. +* `Kind` objects can be thought of as template or schema objects that represent an entity or a relation kind. +Strictly speaking, `Entity` or `Relation` instances do not have to be associated with a `Kind`, +but maintaining `Kind` associations can be used for schema validation and speeding up queries and is +therefore highly encouraged. + +## API +The `onos-topo` subsystem exposes the topology information via a [gRPC API] that supports the above abstractions. + +### Unique ID +Each `Entity`, `Relation` and `Kind` objects has a unique identifier that can be used to directly look it up, +update or delete it. + +### Aspects +The `Entity` and `Relation` objects themselves carry only the essential information for identifying them, +associating them with a particular kind and in case of `Relation`, for associating the two - source and target - +`Entity` objects. Clearly, while this is necessary, it is not sufficient to allow the platform or applications to +track other pertinent information about the entities and relations. + +Since different use-cases or applications require tracking different information, and these may vary for different +types of devices or network domains, the topology schema must be extensible to carry various aspects of information. +This is where the notion of `Aspect` comes in. An `Aspect` is a collection of structured information, modeled as a +Protobuf message (although this is not strictly necessary), which is attached to any type of object; generally +mostly an `Entity` or a `Relation`. + +Each object carries a mapping of aspect type (`TypeURL`) and Protobuf `Any` message. For example, to track a geo-location +of a network element, one can associate `onos.topo.Location` instance, populated with the appropriate longitude and +latitude with the `Entity` that represents that network element, with the `Location` being defined as follows: +```proto +// Geographical location; expected value type of "location" aspect +message Location { + double lat = 1; + double lng = 2; +} +``` + +Similarly, to track information about the cone of signal coverage for a radio-unit, one can attach `onos.topo.Coverage` +instance to an `Entity` representing the radio unit, with `Coverage` being defined as follows: +```proto +// Area of coverage; expected value type of "coverage" aspect +message Coverage { + int32 height = 1; + int32 arc_width = 2; + int32 azimuth = 3; + int32 tilt = 4; +} +``` + +The [current list of aspects](https://github.com/onosproject/onos-api/tree/master/proto/onos/topo) defined in `onos-api` includes the following: +* `onos.topo.Asset` - basic asset information for the device: model, HW, SW versions, serial number, etc. +* `onos.topo.Location` - geo location coordinates +* `onos.topo.Configurable` - info for devices that support configuration via gNMI +* `onos.topo.MastershipState` - for tracking mastership role +* `onos.topo.TLSOptoins` - TLS connection options +* `onos.topo.Protocols` - for tracking connectivity state of supported device control protocols +* `onos.topo.Coverage` - radio unit signal coverage cone information +* `onos.topo.E2Node` - information about an O-RAN E2 node +* `onos.topo.E2Cell` - information about an O-RAN E2 cell +* `onos.topo.AdHoc` - for tracking ad-hoc key/value string attributes (not labels) + +The above are merely examples of aspects. Network control platforms and applications can supply their own depending on +the needs of a particular use-case. + +### Labels +To assist in categorization of the topology objects, each object can carry a number of labels as meta-data. +Each label carries a value. + +For example the `deployment` label can have `production` or `staging` or `testing` as values. Or similarly, +`tier` label can have `access`, `fabric` or `backhaul` as values to indicate the area of network where the entity +belongs. + +### Filters +The topology API provides a `List` method to obtain a collection of objects. The caller can specify a number of +different filters to narrow the results. All topology objects will be returned if the request does not contain +any filters. + +* Type Filter - specifies which type(s) of objects - `Entity`, `Relation` or `Kind` - should be included. +* Kind Filter - specifies which kind(s) of objects should be included, e.g. `contains`, `controls` +* Labels Filter - specifies which label name/value(s) should be included, e.g. `tier=fabric` +* Relation Filter - specifies target entities related to a given source entity via a relation of a given kind + +Support for other filters may be added in the future. + +## Distribution +The topology subsystem is available as a [Docker] image and deployed with [Helm]. To build the Docker image, +run `make images`. + +### Visualizer +To assist developers in visualizing the entities and relations tracked by `onos-topo`, a simple graphic visualization +tool is available. It can be run locally via: +```bash +# Requires 'kubectl port-forward deploy/onos-topo 5150' to forward topo gRPC API +> go run cmd/topo-visualizer/topo-visualizer.go --service-address localhost:5150 +``` +and then simply opening `http://localhost:5152` using your web browser of choice. + +Alternatively, the visualizer can be run directly from the `onos-topo` docker container via: +```bash +# Requires 'kubectl port-forward deploy/onos-topo 5152' to forward visualizer HTTP/WS traffic +> k exec -it deploy/onos-topo -- /usr/local/bin/topo-visualizer +``` + +The visualizer uses `onos-topo` API to watch changes occurring on the topology and forwards +these changes via web-socket to the browser where it renders the various entities and relations using +a simple force layout graph. This allows the view to dynamically adjust to reflect the current topology state. + +Clicking on nodes (entities) and links (relations) will show the full contents of the entity or relation +as JSON structure. Nodes can be dragged around and the entire graph can be zoomed and panned within the viewport. + +The visualizer is presently under active development. + +## See Also +* [Deployment](docs/deployment.md) +* [CLI examples](docs/cli.md) +* [API examples (Golang)](docs/api-go.md) + + +[gRPC API]: https://github.com/onosproject/onos-api/blob/master/proto/onos/topo/topo.proto +[topology subcommands]: https://github.com/onosproject/onos-cli/blob/master/docs/cli/onos_topo.md +[Docker]: https://www.docker.com/ +[Helm]: https://helm.sh diff --git a/onos-topo/onos-topo b/onos-topo/onos-topo new file mode 160000 index 0000000..c075028 --- /dev/null +++ b/onos-topo/onos-topo @@ -0,0 +1 @@ +Subproject commit c075028a60c000f77440cf4c073292cf1b063e85 diff --git a/onos-uenib/README.md b/onos-uenib/README.md new file mode 100644 index 0000000..53043a9 --- /dev/null +++ b/onos-uenib/README.md @@ -0,0 +1,60 @@ + + +# onos-uenib +UE NIB subsystem for ONOS SD-RAN (µONOS Architecture) + +## Overview +This subsystem provides a central location for tracking information associated +with RAN user equipment (UE). + +Applications can associate various aspects of information with each UE either for their +one purpose or for sharing such state with other applications. The API and the system itself +is designed to allow for high rate of data mutation and with minimum latency. + +### Unique ID +Each UE object has a unique identifier that can be used to directly look it up, update or delete it. + +### Aspects +Since different use-cases or applications require tracking different information, and these may vary for different +types of user equipment, the schema must be extensible to carry various aspects of information. +This is where the notion of `Aspect` comes in. An `Aspect` is a collection of structured information, modeled as a +Protobuf message (although this is not strictly necessary), which is attached to the UE. In fact, UE entity carries +only its unique identifier, and the rest of the information is expressed via aspects, which are tracked as a map +of aspect type (`TypeURL`) and Protobuf `Any` message bindings. + +For example, to track UE cell connectivity, the system uses the `CellInfo` aspect defined as a `CellConnection` for the +serving cell and the list of candidate cells, defined as follows: + +```proto +// CellConnection represents UE cell connection. +message CellConnection { + string id = 1 [(gogoproto.customname) = "ID", (gogoproto.casttype) = "ID"]; + double signal_strength = 2;; +} + +// CellInfo provides data on serving cell and candidate cells. +message CellInfo { + CellConnection serving_cell = 1; + repeated CellConnection candidate_cells = 2; +} +``` + +Of course applications may define their own structures of information and attach them to the UE for their own purpose +or to share with other applications. + +## See Also +* [Deployment](docs/deployment.md) +* [CLI examples](docs/cli.md) +* [API examples (Golang)](docs/api-go.md) +* [topology subsystem] + + +[gRPC API]: https://github.com/onosproject/onos-api/blob/master/proto/onos/topo/topo.proto +[topology subcommands]: https://github.com/onosproject/onos-cli/blob/master/docs/cli/onos_topo.md +[Docker]: https://www.docker.com/ +[Helm]: https://helm.sh +[topology subsystem]: https://github.com/onosproject/onos-topo \ No newline at end of file diff --git a/onos-uenib/onos-uenib b/onos-uenib/onos-uenib new file mode 160000 index 0000000..31385d1 --- /dev/null +++ b/onos-uenib/onos-uenib @@ -0,0 +1 @@ +Subproject commit 31385d1a86dcd1dd55dd3f3ad786ade73c5ce93d diff --git a/ran-simulator/CODE_OF_CONDUCT.md b/ran-simulator/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..28be4cb --- /dev/null +++ b/ran-simulator/CODE_OF_CONDUCT.md @@ -0,0 +1,9 @@ + + +We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf). + +If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [conduct@opennetworking.org](conduct@opennetworking.org). diff --git a/ran-simulator/README.md b/ran-simulator/README.md new file mode 100644 index 0000000..f0bfb8d --- /dev/null +++ b/ran-simulator/README.md @@ -0,0 +1,45 @@ + + +# RAN Simulator + +This software allows simulation of a number of RAN CU/DU nodes and RU cells via the O-RAN E2AP standard. +The simulated RAN environment is described using a YAML model file loaded at start-up. +The simulator offers a gRPC API that can be used at run-time to induce changes in order to +simulate a dynamically changing environment. + +The main RAN simulator software is accompanied by a number of utilities that allow generation of YAML files +that describe large RAN topologies and various environmental metrics, e.g. PCI. + +CLI for the RAN simulator is available via `onos-cli ransim` usage and allows access to all major features of +the simulator gRPC API, for controlling and monitoring the changes to the simulated environment. + +* [Quick Start](docs/quick_start.md) +* [Simulation Models and APIs](docs/model.md) +* [E2 Nodes Simulation and Service Models](docs/e2.md) +* [Honeycomb Topology Generator](docs/topology_generator.md) + +## Architecture + +The following figure outlines the RAN simulator architecture: + +![RAN simulator Architecture](docs/images/ransim_architecture.jpg) + +* **E2 nodes**: Upper half of the RAN simulator is responsible to simulate e2 nodes where each E2 node implements an E2 agent using E2AP, and implement service models. + +* **RAN Environment**: Lower half of the RAN simulator is responsible to simulate RAN environment to support required RAN functions + for implementing E2 service models (e.g. simulating User Equipments (UEs), mobility, etc). + +* **Data Stores**: lower half and upper half are connected using data stores that stores information + about E2-nodes, E2-agents, UEs, RAN metrics, E2 subscriptions, etc. + +* **RAN simulator APIs**: RAN simulator provides a variety of gRPC APIs that can be used for controlling E2 nodes and RAN environment. + You can find more details about RAN simulator APIs here: [RAN simulator APIs](api.md) + +* **RAN simulator CLI**: RAN simulator is equipped with a command line interface which is integrated with + [onos-cli](https://github.com/onosproject/onos-cli) that allows to interact with RAN simulator to retrieve required information from data stores, + monitor RAN environment changes, create/remove/update RAN entities, metrics, etc. + The list of ransim commands is documented here [RAN simulator CLI](https://github.com/onosproject/onos-cli/blob/master/docs/cli/onos_ransim.md) diff --git a/ran-simulator/ran-simulator b/ran-simulator/ran-simulator new file mode 160000 index 0000000..9db3dd3 --- /dev/null +++ b/ran-simulator/ran-simulator @@ -0,0 +1 @@ +Subproject commit 9db3dd396bef9b0eaaadc325b0de2b616dca27b4 diff --git a/sdran-in-a-box/CODE_OF_CONDUCT.md b/sdran-in-a-box/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..28be4cb --- /dev/null +++ b/sdran-in-a-box/CODE_OF_CONDUCT.md @@ -0,0 +1,9 @@ + + +We expect all ONF employees, member companies, and participants to abide by our [Code of Conduct](https://www.opennetworking.org/wp-content/themes/onf/img/onf-code-of-conduct.pdf). + +If you are being harassed, notice that someone else is being harassed, or have any other concerns involving someone’s welfare, please notify a member of the ONF team or email [conduct@opennetworking.org](conduct@opennetworking.org). diff --git a/sdran-in-a-box/README.md b/sdran-in-a-box/README.md new file mode 100644 index 0000000..c258931 --- /dev/null +++ b/sdran-in-a-box/README.md @@ -0,0 +1,83 @@ + + +# SDRAN-in-a-Box (RiaB) +SDRAN-in-a-Box (RiaB) is a SD-RAN cluster which is able to operate within a single host machine . +It provides a development/test environment for developers/users in ONF SD-RAN community. +RiaB deploys SD-RAN infrastructure - the EPC ([OMEC](https://github.com/omec-project)), emulated RAN (CU/DU/UE), and ONOS RAN Intelligent Controller (ONOS RIC) services - over Kubernetes. +On top of the SD-RAN infrastructure, we can conduct end-to-end tests in terms of the user plane and the SD-RAN control plane. + +## Features +* Installs Kubernetes and Helm that are the required infrastructure for SD-RAN services +* Provides one of three choices to emulate/simulate Radio Access Networks (RANs) + * RAN-Simulator + * Simulates multiple E2 nodes (CU-CP/DU/RU) and UEs + * Generates SD-RAN control plane messages + * Does not support the LTE traffic + * OMEC / CU-CP / OAI nFAPI emulator for DU/UE + * Completely runs OMEC, a 4G/LTE core network - not emulation + * Completely runs CU-CP, which generates SD-RAN control plane messages - not emulation + * Emulates DU and UEs (up to three UEs) with OAI nAFPI emulator, which generate LTE control and user plane traffic + * OMEC / CU-CP / OAI DU and UE with USRP hardware and/or LTE smartphones + * Completely runs OMEC, a 4G/LTE core network - not emulation + * Completely runs CU-CP, which generates SD-RAN control plane messages - not emulation + * Completely runs OAI DU together with the CU-CP and a USRP device to open a cell - Software Defined Radio (SDR) device-based emulation which commercial LTE phones can attach + * Completely runs OAI UE with a USRP device to attach the cell the CU-CP and OAI DU opens +* Support End-to-End (E2E) connectivity test + * The user plane E2E test + * Works with CU-CP / OAI nFAPI emulator and CU-CP / OAI DU and UE with USRP hardware cases, since RAN-Sim does not support the data traffic + * The SD-RAN control plane E2E test + * Works with xAPPs such as onos-kpimon, onos-pci, onos-mlb and onos-mho + +## RiaB versions and options + +### Versions +RiaB has three versions: **latest**, **master-stable**, **dev**, and each release/tag such as **v1.0.0**, **v1.1.0**, **v1.1.1**, and **v1.2.0**. + +#### Latest version +The *latest* version of RiaB deploys latest Helm charts and latest Docker container images. + +#### Master-stable version +The *master-stable* version of RiaB deploys latest Helm charts but not latest Docker container images. +It deploys the Docker containers according to the image tag described in each Helm chart. + +#### Release/tag versions +The release/tag version such as *v1.0.0*, *v1.1.0*, *v1.1.1*, and *v1.2.0* deployes a specific SD-RAN release version of Helm charts and Docker container images. + +#### Dev version +The *dev* version deploys Helm charts in the `~/helm-charts/sdran-helm-charts` directory and Docker container images `sdran-in-a-box-values.yaml` file. +All other versions initially change the `~/helm-charts/sdran-helm-charts` branch to the specific version. +For example, the *latest* version and *master-stable* version change the the `~/helm-charts/sdran-helm-charts` branch to `master`, +while the *v1.0.0*, *v1.1.0*, *v1.1.1*, and *v1.2.0* versions change that branch to *v1.0.0*, *v1.1.0*, *v1.1.1*, and *v1.2.0*, respectively. +If we change some Helm chart code in `~/helm-charts/sdran-helm-charts` directory for a test, the above versions will reset to the *master* or a specific version branch. +However, since the *dev* option just uses the Helm chart in `~/helm-charts/sdran-helm-charts` as is, we can test the Helm chart chages. +Also, once we specify image tags in the `sdran-in-a-box-values.yaml` files, this version deploys the Docker containers with the Helm chart change. + +### Options +RiaB also has four options: **ONOS RIC with OAI nFAPI emulator**, **ONOS RIC with RAN-Simulator**, **ONOS RIC with OAI and USRP devices**, and **Facebook-AirHop xAPP use case**. + +#### ONOS RIC with OAI nFAPI emulator option +The *ONOS RIC with OAAI nFAPI emulator* option deploys ONOS RIC services (i.e., Atomix, onos-operator, onos-topo, onos-config, onos-cli, onos-e2t, onos-e2sub, etc) with OMEC, CU-CP, and OAI nFAPI emulator. +It supports E2E connectivities on the data plane and SD-RAN control plane. +The data plane is running without the real radio signal, but nFAPI. + +#### ONOS RIC with RAN-Simulator option +The *ONOS RIC with RAN-Simulator* option deploys ONOS RIC services with RAN-Simulator. +It supports an E2E connectivity on the SD-RAN control plane. + +#### ONOS RIC with OAI and USRP devices option +The *ONOS RIC with OAI and USRP devices* option deploys ONOS RIC services with OMEC, CU-CP, OAI DU, and OAI UE with USRP devices. +It supports E2E connectivities on the data plane and SD-RAN control plane. +The data plane is running with the real radio signal, so that we can also test with commercial LTE smartphones. + +#### Facebook-AirHop use case option +The *Facebook-AirHop use case* option is similar to the *ONOS RIC with RAN-Simulator* option. +The only difference is the PCI xAPP. +This option deploys the PCI xAPP from Facebook-AirHop, while *ONOS RIC with RAN-Simulator* option uses ONF ONOS-PCI xAPP. + + +## Detailed information +See [docs](docs) directory for details of RiaB. diff --git a/sdran-in-a-box/sdran-in-a-box b/sdran-in-a-box/sdran-in-a-box new file mode 160000 index 0000000..c39b6a0 --- /dev/null +++ b/sdran-in-a-box/sdran-in-a-box @@ -0,0 +1 @@ +Subproject commit c39b6a0aa74aaee9f46b739169cb32cb7630c14c