diff --git a/doc/source/specs/stx-8.0/approved/oran-spec-compliance_2010278_o2-interfaces.rst b/doc/source/specs/stx-8.0/approved/oran-spec-compliance_2010278_o2-interfaces.rst new file mode 100644 index 0000000..8695dc4 --- /dev/null +++ b/doc/source/specs/stx-8.0/approved/oran-spec-compliance_2010278_o2-interfaces.rst @@ -0,0 +1,794 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. http://creativecommons.org/licenses/by/3.0/legalcode + +============================================ +O-RAN Specification Compliant O2 Interfaces +============================================ + +Storyboard: +https://storyboard.openstack.org/#!/story/2010278 + + +To facilitate the integration of components in context of O-RAN architecture, +O-RAN Alliance publishes a set of specifications to normalize the interfaces +between them, as far as O-Cloud concerned, the O2 interfaces are specified +between O-Cloud and O-RAN SMO. As part of effort to make StarlingX be compliant +to O-RAN specifications, oran O2 service is developed and integrated into +StarlingX (either standalone mode or distributed cloud mode) to expose O2 +interfaces towards to SMO. + +Problem description +=================== + +Users want to integrate StarlingX as O-Cloud to O-RAN SMO via O2 interfaces +published by O-RAN Specifications as below: + +`WG6: O-RAN O2ims Interface Specification v3.00 `_ + +`WG6: O-RAN O2dms Interface Specification: Kubernetes Native API Profile for +Containerized NFs v2.00 `_ + +Hence it is expected that following O2 services are deployed over StarlingX: + +* O2ims_InfrastructureInventory +* O2ims_InfrastructureMonitoring +* O2dms in Kubernetes native API profile + +Use Cases +--------- + +This feature addresses several use cases specified by: +`WG6: O-RAN Cloudification and Orchestration Use Cases and Requirements for +O-RAN Virtualized RAN v5.00 `_ + +Specifically, the following Use cases and Requirements should be realized: + +* O-Cloud Registration and Initialization Use Case +* O-Cloud Inventory Update Use Case +* Network Function Basic Use Cases +* Fault Use Cases + +The use cases above should be applicable to StarlingX in either standalone +mode or distributed cloud mode. + +Proposed change +=============== + +An `oran-o2 service ` has been developed as part of INF project of o-ran +software community. + +This oran-o2 service has been designed and implemented to host the o2ims +services including O2ims_InfrastructureInventory, +O2ims_InfrastructureMonitoring, and other O2 services in future to represent +StarlingX as an O-RAN Specifications compliant O-Cloud. + +This oran-o2 service will be packaged as a new FluxCD based containerized +application. Users decide whether to deploy this oran-o2 service and when. +In case of StarlingX in distributed cloud mode, oran-o2 will be deployed +over system controller only. + +Fundamentally, the oran-o2 services act as a mapping layer to map between +StarlingX resources and corresponding service objects of O-RAN specifications. + +Specifically, the following O-RAN service objects are mapped to StarlingX +resources: + +================= ================================ =========================== +O-RAN model StarlingX in standalone mode StarlingX in distributed + cloud mode +================= ================================ =========================== +O-Cloud a StarlingX instance a System Controller and all + subclouds it manages +ResourceType StarlingX sysinv API resource StarlingX sysinv API + kind resource kind, refer /o2ims + -infrastructureInventory/v1 + /resourceTypes for examples +ResourcePool a StarlingX instance a instance of subcloud, + refer to /o2ims- + infrastructureInventory/v1 + /resourcePools for examples +Resource Specific instance of StarlingX Specific instance of + sysinv API resource sysinv API resource, + refer to /o2ims- + infrastructureInventory/v1 + /resourcePools/ + {resourcePoolID}/resources + for examples +DeploymentManager a single Kubernetes cluster a single Kubernetes cluster + hosted by a StarlingX instance hosted by a subcloud, + refer to /o2ims- + infrastructureInventory/v1 + /deploymentManagers + for examples +AlarmDefinition Fault Management Alarm Message Fault Management Alarm + definition Message definition +AlarmEventRecord an occurrence of Fault an occurrence of Fault + Management Alarm Message Management Alarm Message +AlarmSeverity Fault Management Alarm Severity Fault Management Alarm + Severity +================= ================================ =========================== + +.. + The resources of RegionOne of system controller can also be + represented as a ResourcePool as well as DeploymentManager + +As implementation of o2ims services, the oran o2 service monitors sysinv +resources via sysinv api, builds a cache of resources compliant to O-RAN O2 +model as inventory and persists them into internal database. + +On the other hand, oran o2 service exposes this inventory to SMO through a set +of O2 APIs for querying resources as well as subscribing to get notification upon +the inventory changes and alarm changes. + +As implementation of o2dms, the kubernetes clsuters hosted by StarlingX will +be exposed as O2dms in kubernetes native API profile, while the access +information of these clusters are exposed as deploymentmanager object as part +of o2ims inventory. So SMO could query the it to extract the access +crendentials, and interact directly with the specific kubernetes cluster with +kubernetes native APIs. + +To make oran o2 service survive through the migration of oran-o2 pods among +different StarlingX hosts, the inventory database is persisted by leveraging +kubernetes PV volumes. + +Alternatives +------------ + +It has been considered to couple the o2ims service with sysinv service to +optimize the efficiency of monitoring sysinv resource changes. However, given +that O-RAN specifications is still in early stage of its rapid evolution +progress, it is decided to decouple these two services and integrating them +by utilizing existing sysinv API for now. + +Data model impact +----------------- + +As part of the o2ims inventory, a new group of tables will be introduced to +persist O-RAN modeling compliant objects representing StarlingX sysinv resources. +This inventory is internally managed as part of deployment of oran o2 service. +The diagram below shows the new table names and relationships. + +.. + +-----------+ + +-----+ ocloud +---+ + | +-----------+ | + | | + | | + |N |N + +------------+------+ +----------+-----+ +------------------+ + | | | resourcepool | | alarmSubscription| + |deploymentmanager | | | | | + +-------------------+ +-------+--------+ +------------------+ + | + +--------------+ | + | subscription | |N + +--------------+ +-------+--------+ +-----------------+ + | resource |1 |alarmEventRecord | + +---------------+ | +----+ | + | configuration | +------+---------+ +------+----------+ + +---------------+ | | + | | + |1 | + +------+---------+ 1 | + | resourcetype +-----------+ + +----------------+ + +The resourcetype table is populated with predefined resourcetypes as below: +- pserver +- pserver_cpu +- pserver_mem +- pserver_ethernet +- pserver_if + +The resource table contains specific o2ims resources which represents the +corresponding sysinv resource accordingly to predefined resourcetypes. The +resource are organized in a hierachical way to represent the relationship +between each other, e.g. an instance of pserver_cpu refers to a instance of +pserver with its parentid. an instance of pserver refers to an instance of +resourcepool which represents the subcloud. + +The resourcepool table contains representations of each subcloud. + +The deploymentmanager table contains representations of kubernetes cluster +for each subcloud + +The ocloud table contains a single representation of StarlingX instance in +either standalone mode or distributed cloud mode. + +The subscription table contains information of subscribers which are interested +in receiving notification upon the changes of o2ims inventory. + +The configuration table contains provisioning information, e.g., smo endpoint +for o-cloud registration + +The alarmSubscription table contains information of subscribers which are +integrated in receiving alarm notification. + +The alarmEventRecord table contains information of alarms generated by +StarlingX system. + + +REST API impact +--------------- + +Following the spec of O-RAN Alliance as of this writing, +`WG6: O-RAN O2ims Interface Specification v3.00 `_, the following APIs will be added: + +o2ims-infrastructureInventory/v1 +________________________________ + +GET o2ims-infrastructureInventory/v1 + +RESP: + +.. + { + "oCloudId": "42700a14-21d6-405c-a362-e691b20656b1", + "globalcloudId": cfac6bda-21d6-405c-a362-e691b20656b1, + "name": "StarlingX instance name", + "description": "An ocloud", + "serviceUri": + "http://128.224.115.35:30205/o2ims-infrastructureInventory/v1/" + } + +/o2ims-infrastructureInventory/v1/resourceTypes +_______________________________________________ + +GET /o2ims-infrastructureInventory/v1/resourceTypes + +RESP: + +.. + [ + { + "resourceTypeId": "dcce9bcc-fb38-4e49-bf84-4f1519f3b031", + "name": "pserver", + "vendor": null, + "version": "", + "description": "", + "alarmDictionary": {} + }, + { + "resourceTypeId": "f5bdc0a0-eee7-426a-8d07-b56f950a94d2", + "name": "pserver_cpu", + "vendor": null, + "version": "", + "description": "", + "alarmDictionary": {} + }, + { + "resourceTypeId": "0d24f2ce-a0fa-460f-a65c-541b694110e5", + "name": "pserver_mem", + "vendor": null, + "version": "", + "description": "", + "alarmDictionary": {} + }, + { + "resourceTypeId": "7a150a2d-5107-4bfc-ada8-c6c4b037430c", + "name": "pserver_ethernet", + "vendor": null, + "version": "", + "description": "", + "alarmDictionary": {} + }, + { + "resourceTypeId": "63557eda-f8e1-4a52-82fa-f3e6f52fea9f", + "name": "pserver_if", + "vendor": null, + "version": "", + "description": "", + "alarmDictionary": {} + } + ] + +/o2ims-infrastructureInventory/v1/resourceTypes/{resourceTypeID } +_________________________________________________________________ + +GET /o2ims-infrastructureInventory/v1/resourceTypes/ +dcce9bcc-fb38-4e49-bf84-4f1519f3b031 + +RESP: + +.. + { + "resourceTypeId": "dcce9bcc-fb38-4e49-bf84-4f1519f3b031", + "name": "pserver", + "vendor": "vendor1", + "version": "v1", + "description": "desc1", + "alarmDictionary": {} + } + +/o2ims-infrastructureInventory/v1/resourcePools +_______________________________________________ + +GET /o2ims-infrastructureInventory/v1/resourcePools + +RESP: + +.. + [ + { + "resourcePoolId": "42700a14-21d6-405c-a362-e691b20656b1", + "name": "subcloud1", + "globalLocationId": "42700a14-21d6-405c-a362-e691b20656b1", + "location": "location1", + "description": "A Resource Pool", + "oCloudId": "" + } + ] + + +/o2ims-infrastructureInventory/v1/resourcePools/{resourcePoolID} +________________________________________________________________ + +GET /o2ims-infrastructureInventory/v1/resourcePools/ +42700a14-21d6-405c-a362-e691b20656b1 + +RESP: + +.. + { + "resourcePoolId": "42700a14-21d6-405c-a362-e691b20656b1", + "name": "subcloud1", + "globalLocationId": "42700a14-21d6-405c-a362-e691b20656b1", + "location": "location1", + "description": "A Resource Pool", + "oCloudId": "" + } + + +/o2ims-infrastructureInventory/v1/resourcePools/{resourcePoolID}/resources +__________________________________________________________________________ +?{filters} +__________ + +GET o2ims-infrastructureInventory/v1/resourcePools/ +42700a14-21d6-405c-a362-e691b20656b1/resources?resourceTypeName=pserver + +RESP: + +.. + [ + { + "resourceId": "67e71e16-6264-4ac0-b57f-815cf6b7dc70", + "resourceTypeId": "dcce9bcc-fb38-4e49-bf84-4f1519f3b031", + "resourcePoolId": "42700a14-21d6-405c-a362-e691b20656b1", + "name": "controller-0", + "parentId": null, + "description": "A physical server resource", + "globalAssetId": "" + }, + { + "resourceId": "54d74187-775e-46dd-b8b0-5875a14223d8", + "resourceTypeId": "dcce9bcc-fb38-4e49-bf84-4f1519f3b031", + "resourcePoolId": "42700a14-21d6-405c-a362-e691b20656b1", + "name": "controller-1", + "parentId": null, + "description": "A physical server resource", + "globalAssetId": "" + } + ] + +o2ims-infrastructureInventory/v1/resourcePools/{resourcePoolID}/resources/ +__________________________________________________________________________ +{resourceID} +____________ + +GET o2ims-infrastructureInventory/v1/resourcePools/ +42700a14-21d6-405c-a362-e691b20656b1/resources/ +67e71e16-6264-4ac0-b57f-815cf6b7dc70 + +RESP: + +.. + { + "resourceId": "67e71e16-6264-4ac0-b57f-815cf6b7dc70", + "resourceTypeId": "dcce9bcc-fb38-4e49-bf84-4f1519f3b031", + "resourcePoolId": "42700a14-21d6-405c-a362-e691b20656b1", + "name": "controller-0", + "parentId": null, + "description": "A physical server resource", + "globalAssetId": "", + "elements": "", + "children": [ + { + "resourceId": "d380122a-fa29-4813-a77a-8b36a1aa257d", + "resourceTypeId": "f5bdc0a0-eee7-426a-8d07-b56f950a94d2", + "resourcePoolId": "42700a14-21d6-405c-a362-e691b20656b1", + "name": "67e71e16-cpu-0", + "parentId": "67e71e16-6264-4ac0-b57f-815cf6b7dc70", + "description": "A CPU resource of the physical server", + "elements": "", + "children": null + } + ] + } + + +/o2ims-infrastructureInventory/v1/subscriptions +_______________________________________________ + +POST /o2ims-infrastructureInventory/v1/subscriptions + +.. + { + "callback": "https://1.2.3.4/smo_observer", + "consumerSubscriptionId": "observerid1", + "filter": "filter1=value1" + } + +RESP: + +.. + { + "subscriptionId": "7900907e-b60a-4cfd-b6a5-dae760a865f0" + } + +GET /o2ims-infrastructureInventory/v1/subscriptions + +RESP: + +.. + [ + { + "subscriptionId": "7900907e-b60a-4cfd-b6a5-dae760a865f0", + "callback": "https://1.2.3.4/smo_observer", + "consumerSubscriptionId": "observerid1", + "filter": "filter1=value1" + } + ] + +/o2ims-infrastructureInventory/v1/subscriptions/{subscriptionID} +________________________________________________________________ + +GET /o2ims-infrastructureInventory/v1/subscriptions/ +7900907e-b60a-4cfd-b6a5-dae760a865f0 + +RESP: + +.. + { + "subscriptionId": "7900907e-b60a-4cfd-b6a5-dae760a865f0", + "callback": "https://1.2.3.4/smo_observer", + "consumerSubscriptionId": "observerid1", + "filter": "filter1=value1" + } + +DELETE /o2ims-infrastructureInventory/v1/subscriptions/ +7900907e-b60a-4cfd-b6a5-dae760a865f0 + +RESP: None + +/o2ims-infrastructureInventory/v1/deploymentManagers +____________________________________________________ + +GET /o2ims-infrastructureInventory/v1/deploymentManagers + +RESP: + +.. + [ + { + "deploymentManagerId": "9fc43d52-b73a-366a-b08f-e89cbbf82532", + "name": "cfac6bda-486c-401b-8451-9cb226eb3884.kubernetes", + "description": "A DMS", + "serviceUri": "http://128.224.115.35:30205/o2dms/v1/9fc43d52-b73a-366a-b08f-e89cbbf82532", + "supportedLocations": "", + "capabilities": "", + "capacity": "", + "oCloudId": "" + } + ] + +/o2ims-infrastructureInventory/v1/deploymentManagers/{deploymentManagerID} +__________________________________________________________________________ + +GET /o2ims-infrastructureInventory/v1/deploymentManagers/ +9fc43d52-b73a-366a-b08f-e89cbbf82532 + +RESP: + +.. + { + "deploymentManagerId": "9fc43d52-b73a-366a-b08f-e89cbbf82532", + "name": "cfac6bda-486c-401b-8451-9cb226eb3884.kubernetes", + "description": "A DMS", + "serviceUri": "https://128.224.115.34:6443", + "supportedLocations": "", + "capabilities": "", + "capacity": "", + "oCloudId": "" + } + +/o2ims-infrastructureMonitoring/v1/alarms +_________________________________________ + +GET /o2ims-InfrastructureMonitoring/v1/alarms + +RESP: + +.. + [ + { + "alarmEventRecordId": "9fc43d52-b73a-366a-b08f-e89cbbf82532", + "resourceTypeID": "cfac6bda-486c-401b-8451-9cb226eb3884", + "resourceID": "feac6bda-486c-401b-8451-9cb226eb3123", + "alarmDefinitionID": "100.101", + "probableCauseID": "", + "alarmRaisedTime": "2022-09-01T08:01:12", + "alarmAcknowledgeTime": "", + "alarmAcknowledged": false, + "perceivedSeverity": 3, + "extensions": [] + } + ] + +/o2ims-infrastructureMonitoring/v1/alarms/{alarmEventRecordID} +______________________________________________________________ + +GET /o2ims-InfrastructureMonitoring/v1/alarms/ +9fc43d52-b73a-366a-b08f-e89cbbf82532 + +RESP: + +.. + { + "alarmEventRecordId": "9fc43d52-b73a-366a-b08f-e89cbbf82532", + "resourceTypeID": "cfac6bda-486c-401b-8451-9cb226eb3884", + "resourceID": "feac6bda-486c-401b-8451-9cb226eb3123", + "alarmDefinitionID": "100.101", + "probableCauseID": "", + "alarmRaisedTime": "2022-09-01T08:01:12", + "alarmAcknowledgeTime": "", + "alarmAcknowledged": false, + "perceivedSeverity": 3, + "extensions": [] + } + +/o2ims-infrastructureMonitoring/v1/alarmSubscriptions +_____________________________________________________ + +POST /o2ims-infrastructureMonitoring/v1/alarmSubscriptions + +.. + { + "consumerSubscriptionId": "bfec6bda-486c-401b-8451-9cb226eb3999", + "filter": "severity<=2", + "callback": "https://1.2.3.4/alarm_observer1" + } + +RESP: + +.. + { + "alarmSubscriptionId": "aef43d52-b73a-366a-b08f-e89cbbf82111", + "consumerSubscriptionId": "bfec6bda-486c-401b-8451-9cb226eb3999", + "filter": "severity<=2", + "callback": "https://1.2.3.4/alarm_observer1" + } + +GET /o2ims-infrastructureMonitoring/v1/alarmSubscriptions + +RESP: + +.. + [ + { + "alarmSubscriptionId": "aef43d52-b73a-366a-b08f-e89cbbf82111", + "consumerSubscriptionId": "bfec6bda-486c-401b-8451-9cb226eb3999", + "filter": "severity<=2", + "callback": "https://1.2.3.4/alarm_observer1" + } + ] + +/o2ims-infrastructureMonitoring/v1/alarmSubscriptions/{alarmSubscriptionId} +___________________________________________________________________________ + +GET /o2ims-infrastructureMonitoring/v1/alarmSubscriptions/ +aef43d52-b73a-366a-b08f-e89cbbf82111 + +RESP: + +.. + { + "alarmSubscriptionId": "aef43d52-b73a-366a-b08f-e89cbbf82111", + "consumerSubscriptionId": "bfec6bda-486c-401b-8451-9cb226eb3999", + "filter": "severity<=2", + "callback": "https://1.2.3.4/alarm_observer1" + } + +DELETE /o2ims-infrastructureMonitoring/v1/alarmSubscriptions/ +aef43d52-b73a-366a-b08f-e89cbbf82111 + +RESP: None + +Security impact +--------------- + +oran-o2 services exposes API endpoints towards a single SMO which should be +specified during provisioning time, so it is critical to reach mutually trusts +with following approach: + +* The SMO API endpoint which is provisioned to oran-o2 for O-Cloud registration + should be protected by https. +* The oran-o2 API endpoint will be protected by https, the certificate + management will be manually done for now, and will be integrated with + cert-manager in future. +* An initial token will be provided to SMO during O-Cloud registration. +* SMO should use that token to request oran-o2 service via API endpoint. +* The token should be renewed before it is expired and dispatch to SMO by + oran-o2 service +* The token received from SMO via its API requests will be validated against + authentication provider. The authentication provider is the kubernetes + APIserver which hosts the oran o2 service, and can be extended in future to + support other authentication providers, e.g., the openstack keystone service + of StarlingX. +* The token management will be manually done for now and will be automated + in future. +* There is no user sensitive data involved. +* There is no need for cryptography, but need hashing for checksum of + resource information. +* There is no need for sudor or any elevated privileges. +* The oran-o2 requires openstack admin permission to interact with sysinv APIs. +* The oran-o2 requires a kubernetes service account with binding of a + clusterRole to able to interact with kubernetes APIserver. + +Other end user impact +--------------------- + +This oran-o2 service exposes new set of APIs for SMO, but it does not affect +existing python-client of other StarlingX services + +Performance Impact +------------------ + +The oran-o2 service should be no impact on system performance for following +reasons: + +* As mentioned in problem description, oran-o2 will monitor the changes of + sysinv resources via sysinv API, hence there is a background task polling + the sysinv resources via sysinv API periodically. The configurable polling + interval is in seconds level and executed in a sequential way for + querying sysinv resources. It is expected this periodic task will not impact + system's performance. +* There are no database queries to system. +* There is no locking to access system resource exclusively. +* The oran-o2 service is deployed as kubernetes workload hence the consumed + resources are predicted by resource allocation at deployment phase. + +Other deployer impact +--------------------- + +None + +Developer impact +---------------- + +This is a new and standalone system application, it will not impact developers +working on other features. + +Upgrade impact +-------------- + +The oran-o2 has dependencies on few sysinv API as well as the kubernetes +version, it should be upgraded accordingly if these components upgrading breaks +the dependencies. + +The oran-o2 does not affect the system's upgrade since it is designed as a +standalone system application deployed over system. + +The oran-o2 is implemented in cloud native way, it supports migration between hosts +by nature. + +Implementation +============== + +Assignee(s) +----------- + +Primary assignee: + Bin Yang + +Other contributors: + Rong Zhang + David Liu + +Repos Impacted +-------------- + +starlingx/app-oran-o2 + +Work Items +---------- + +* Create oran-o2 application package based on ORAN-SC release deliverable +* Create FluxCD App Package by integrating oran-o2 application to FluxCD +* Update the docs.starlingx.io for the instructions of oran-o2 application + deployment and configuration, and API reference of oran-o2 services. + +Dependencies +============ + + +This specification depends upon the open source upstream: + +O-RAN Software Community/INF project/ORAN-O2 services implementation in G +Release + + +Testing +======= + +Functional testing will be performed on StarlingX in AIO-SX, AIO-DX, +Standard and DC configurations, which includes: + +* O2 application lifecycle management in StarlingX +* O2 Use cases verification which demonstrates the Compliance of ORAN Spec Interfaces + +Documentation Impact +==================== + +This work will primarily impact deployer and developers. + +The API reference documentation will be provided for integrating with ORAN SMO. + +The deployment guide document will be provided for deployer of StarlingX. + +StarlingX release notes describing this feature will also be provided. + +References +========== + +* `WG6: O-RAN Cloudification and Orchestration Use Cases and Requirements for + O-RAN Virtualized RAN v5.00 `_ + +* `WG6: O-RAN O2ims Interface Specification v3.00 `_ + +* `WG6: O-RAN O2dms Interface Specification: Kubernetes Native API Profile for + Containerized NFs v2.00 `_ + +* `O-RAN SC INF project, ORAN-O2 services implementation in G release ` + +Acronyms +-------- + +- 3GPP: Third Generation Partnership Project +- 5G: Fifth-Generation Mobile Communications +- CNF: Containerized Network Function +- DMS: O-Cloud Deployment Management Services +- SMO: Service Management and Orchestration +- FOCOM: Federated O-Cloud Orchestration & Management +- IM: Information Model +- IMS: O-Cloud Infrastructure Management Services +- LCM: Life Cycle Management +- NF: Network Function +- NFO: Network Function Orchestration +- NFVI: Network Function Virtualization Infrastructure +- O-CU: O-RAN Central Unit as defined by O-RAN ALLIANCE +- O-CU-CP: O-CU Control Plane +- O-CU-UP: O-CU User Plane +- O-DU: O-RAN Distributed Unit (uses Lower-level Split) + +History +======= + +None