| .. This work is licensed under a Creative Commons Attribution 4.0 International License. |
| .. SPDX-License-Identifier: CC-BY-4.0 |
| .. Copyright (C) 2024 Nordix Foundation. All rights Reserved |
| .. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved |
| |
| Developer Guide |
| ############### |
| |
| Developer Guide Overview |
| ======================== |
| |
| In this guide, we explore the use of Topology & Inventory to manage the |
| topology and inventory data in your network. |
| |
| Introducing topology and inventory data |
| ======================================= |
| |
| Topology and inventory data is the information that represents entities |
| in a telecommunications network and the relationships between them that |
| provide insight into a particular aspect of the network of importance to |
| specific use cases. Topology and inventory data can be derived from |
| inventory, configuration, or other data. Topology & Inventory is being |
| updated autonomously based on changes in the network. |
| |
| Topology & Inventory supports several topology and inventory domains, |
| see the :doc:`Data Models </data-models-guide>` for |
| details on the topology and inventory model. The understanding of the |
| model is important to enable a user making queries on topology and |
| inventory data. The entities are modeled as managed objects (found under |
| the schema in the data dictionary) and grouped together in modules based |
| on functionality. See |
| :ref:`Supported domains <Supported domains>` |
| for the list of the topology and inventory domains currently supported |
| in Topology & Inventory capability. |
| |
| Concepts |
| -------- |
| |
| The building blocks of the Topology & Inventory are domains, entities, |
| and the relationships between each other. From a graph perspective, |
| entities are the vertices and relationships are the edges. These two |
| components are part of a subgraph, or the so-called domain. A |
| relationship can go beyond a single domain, since it can happen that the |
| two entities come from two separate ones. In this particular case, they |
| have a cross-domain relationship. |
| |
| Domain |
| ~~~~~~ |
| |
| A domain is a grouping of topology and inventory entities that handles |
| topology and inventory data. Topology and inventory data is the |
| information that represents entities in a telecommunications network and |
| the relationships between them that provides insight into a particular |
| aspect of the network of import to specific use cases. Topology and |
| inventory data can be derived from inventory, configuration, or other |
| data. Therefore, the topology and inventory model must define what the |
| telecoms network entities and relationships are. More information can be |
| found in :ref:`Supported domains <Supported domains>`. |
| The Topology Exposure and Inventory Management (TEIV) domain is the |
| parent domain used for entities and relationships. This domain can be |
| used in reading and querying topology and inventory data when the domain |
| name of an entity or relationship is not known. |
| |
| Entity |
| ~~~~~~ |
| |
| Entities are enabling the modelling and storage of complex network |
| infrastructure and relationships. The following are two examples of the |
| entities and their attributes from :doc:`Topology & Inventory Data |
| Models <data-models-guide>`. |
| |
| .. image:: _static/sample-entities.svg |
| :width: 900 |
| |
| Relationship |
| ~~~~~~~~~~~~ |
| |
| It is a bi-directional connection between two entities, one of which is |
| the originating side (A-side) and the other is the terminating side |
| (B-side). The order of the sides matters since it defines the |
| relationship itself which must be unique. A relationship between two |
| entities is based on the effect that one has on the other. An entity can |
| have one or multiple relationships which can be defined by the user. A |
| possible relationship between ManagedElement and GNBDUFunction can be |
| *MANAGEDELEMENT_MANAGES_GNBDUFUNCTION*. |
| |
| Topology & Inventory models |
| --------------------------- |
| |
| The Topology & Inventory objects are managed and standardized using YANG |
| models. These YANG models describe managed network entities and their |
| attributes, while also providing information on the relations between |
| the network entities. YANG data models are structured into modules and |
| submodules. Management instance data is a graph of objects which have |
| attributes (see the **schema** in the data models). |
| |
| The :doc:`Topology & Inventory Data Models <data-models-guide>` includes: |
| - Modules for each supported domain that describe the structure of the |
| managed objects within it as well as any relationships between them. - |
| Modules that describe cross-domain relationships. - Modules that define |
| proprietary extensions and types used to describe the structure of |
| objects and attributes within the domains. |
| |
| The following sample diagram shows some managed objects and their |
| relationships in the RAN domain. |
| |
| .. image:: _static/sample-object-relationships.svg |
| :width: 900 |
| |
| A direct relationship is a connection between two entities without any |
| in-between entity and an indirect relationship contains at least one. |
| NRCellDU has direct relationships with GNBDUFunction and |
| NRSectorCarrier, while it also has indirect relationships with |
| ManagedElement, AntennaCapability, and AntennaModule. |
| |
| Supported domains |
| ----------------- |
| |
| +-----------------------------------+-------------------------------------------------------+ |
| | Domain | Description | |
| +===================================+=======================================================+ |
| | RAN | | This model contains the topology entities and | |
| | | | relations in the RAN domain, which represents the | |
| | | | functional capability of the deployed RAN that | |
| | | | are relevant to rApps use cases. | |
| +-----------------------------------+-------------------------------------------------------+ |
| | EQUIPMENT | | This model contains the topology entities and | |
| | | | relations in the Equipment domain, which is | |
| | | | modeled to understand the physical location of | |
| | | | equipment such as antennas associated with a | |
| | | | cell/carrier and their relevant properties, for | |
| | | | example, tilt, max power, and so on. | |
| +-----------------------------------+-------------------------------------------------------+ |
| | OAM | | This model contains the topology entities and | |
| | | | relations in the O&M domain, which are intended | |
| | | | to represent management systems and management | |
| | | | interfaces. | |
| +-----------------------------------+-------------------------------------------------------+ |
| | CLOUD | | This model contains the topology entities and | |
| | | | relations in the RAN CLOUD domain, which | |
| | | | comprises cloud infrastructure and deployment | |
| | | | aspects that can be used in the topology model. | |
| +-----------------------------------+-------------------------------------------------------+ |
| | EQUIPMENT_TO_RAN | | This model contains the topology relations | |
| | | | between Equipment and RAN. | |
| +-----------------------------------+-------------------------------------------------------+ |
| | OAM_TO_RAN | | This model contains the topology relations | |
| | | | between O&M and RAN. | |
| +-----------------------------------+-------------------------------------------------------+ |
| | CLOUD_TO_RAN | | This model contains the RAN Cloud to RAN Logical | |
| | | | topology relations. | |
| +-----------------------------------+-------------------------------------------------------+ |
| | OAM_TO_CLOUD | | This model contains the RAN O&M to Cloud | |
| | | | topology relations. | |
| +-----------------------------------+-------------------------------------------------------+ |