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.
Entityobjects are nodes in a graph and are generally intended to represent network devices, control entities, control domains, and so on.Relationobjects are edges in a graph and are intended to represent various types of relations between twoEntityobjects, e.g.contains,controls,implements.Kindobjects can be thought of as template or schema objects that represent an entity or a relation kind. Strictly speaking,EntityorRelationinstances do not have to be associated with aKind, but maintainingKindassociations can be used for schema validation and speeding up queries and is therefore highly encouraged.
The onos-topo subsystem exposes the topology information via a gRPC API that supports the above abstractions.
Each Entity, Relation and Kind objects has a unique identifier that can be used to directly look it up,
update or delete it.
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:
// 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:
// 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 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 coordinatesonos.topo.Configurable- info for devices that support configuration via gNMIonos.topo.MastershipState- for tracking mastership roleonos.topo.TLSOptoins- TLS connection optionsonos.topo.Protocols- for tracking connectivity state of supported device control protocolsonos.topo.Coverage- radio unit signal coverage cone informationonos.topo.E2Node- information about an O-RAN E2 nodeonos.topo.E2Cell- information about an O-RAN E2 cellonos.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.
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.
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,RelationorKind- 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.
The topology subsystem is available as a Docker image and deployed with Helm. To build the Docker image,
run make images.
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:
# Requires 'kubectl port-forward deploy/onos-topo 5150' to forward topo gRPC API
> go run cmd/topo-visualizer/topo-visualizer.go --service-address localhost:5150and 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:
# Requires 'kubectl port-forward deploy/onos-topo 5152' to forward visualizer HTTP/WS traffic
> k exec -it deploy/onos-topo -- /usr/local/bin/topo-visualizerThe 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.