models/yang/odl-network-topology.yang

   1
   2 /*
   3  *
   4  *   Copyright 2016 RIFT.IO Inc
   5  *
   6  *   Licensed under the Apache License, Version 2.0 (the "License");
   7  *   you may not use this file except in compliance with the License.
   8  *   You may obtain a copy of the License at
   9  *
  10  *       http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  *   Unless required by applicable law or agreed to in writing, software
  13  *   distributed under the License is distributed on an "AS IS" BASIS,
  14  *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  *   See the License for the specific language governing permissions and
  16  *   limitations under the License.
  17  *
  18  *
  19  */
  20
  21 module odl-network-topology  {
  22     yang-version 1;
  23     namespace "urn:TBD:params:xml:ns:yang:network-topology";
  24     // replace with IANA namespace when assigned
  25     prefix "nt";
  26
  27     import ietf-inet-types { prefix "inet";  }
  28
  29     organization "TBD";
  30
  31     contact "WILL-BE-DEFINED-LATER";
  32
  33     description
  34         "This module defines a model for the topology of a network.
  35         Key design decisions are as follows:
  36         A topology consists of a set of nodes and links.
  37         Links are point-to-point and unidirectional.
  38         Bidirectional connections need to be represented through
  39         two separate links.
  40         Multipoint connections, broadcast domains etc can be represented
  41         through a hierarchy of nodes, then connecting nodes at
  42         upper layers of the hierarchy.";
  43
  44     revision 2013-10-21 {
  45         description
  46             "Initial revision.";
  47     }
  48
  49     typedef topology-id {
  50         type inet:uri;
  51         description
  52             "An identifier for a topology.";
  53     }
  54
  55     typedef node-id {
  56         type inet:uri;
  57         description
  58             "An identifier for a node in a topology.
  59             The identifier may be opaque.
  60             The identifier SHOULD be chosen such that the same node in a
  61             real network topology will always be identified through the
  62             same identifier, even if the model is instantiated in separate
  63             datastores. An implementation MAY choose to capture semantics
  64             in the identifier, for example to indicate the type of node
  65             and/or the type of topology that the node is a part of.";
  66     }
  67
  68
  69     typedef link-id {
  70         type inet:uri;
  71         description
  72             "An identifier for a link in a topology.
  73             The identifier may be opaque.
  74             The identifier SHOULD be chosen such that the same link in a
  75             real network topology will always be identified through the
  76             same identifier, even if the model is instantiated in separate
  77             datastores. An implementation MAY choose to capture semantics
  78             in the identifier, for example to indicate the type of link
  79             and/or the type of topology that the link is a part of.";
  80     }
  81
  82     typedef tp-id {
  83         type inet:uri;
  84         description
  85             "An identifier for termination points on a node.
  86             The identifier may be opaque.
  87             The identifier SHOULD be chosen such that the same TP in a
  88             real network topology will always be identified through the
  89             same identifier, even if the model is instantiated in separate
  90             datastores. An implementation MAY choose to capture semantics
  91             in the identifier, for example to indicate the type of TP
  92             and/or the type of node and topology that the TP is a part of.";
  93     }
  94
  95     typedef tp-ref {
  96         type leafref {
  97             path "/network-topology/topology/node/termination-point/tp-id";
  98         }
  99         description
 100             "A type for an absolute reference to a termination point.
 101             (This type should not be used for relative references.
 102             In such a case, a relative path should be used instead.)";
 103     }
 104     typedef topology-ref {
 105         type leafref {
 106             path "/network-topology/topology/topology-id";
 107         }
 108         description
 109             "A type for an absolute reference a topology instance.";
 110     }
 111
 112     typedef node-ref {
 113         type leafref {
 114             path "/network-topology/topology/node/node-id";
 115         }
 116         description
 117
 118             "A type for an absolute reference to a node instance.
 119             (This type should not be used for relative references.
 120             In such a case, a relative path should be used instead.)";
 121     }
 122
 123     typedef link-ref {
 124         type leafref {
 125             path "/network-topology/topology/link/link-id";
 126         }
 127         description
 128             "A type for an absolute reference a link instance.
 129             (This type should not be used for relative references.
 130             In such a case, a relative path should be used instead.)";
 131     }
 132
 133     grouping tp-attributes {
 134         description
 135             "The data objects needed to define a termination point.
 136             (This only includes a single leaf at this point, used
 137             to identify the termination point.)
 138             Provided in a grouping so that in addition to the datastore,
 139             the data can also be included in notifications.";
 140         leaf tp-id {
 141             type tp-id;
 142         }
 143         leaf-list tp-ref {
 144             type tp-ref;
 145             config false;
 146             description
 147                 "The leaf list identifies any termination points that the
 148                 termination point is dependent on, or maps onto.
 149                 Those termination points will themselves be contained
 150                 in a supporting node.
 151                 This dependency information can be inferred from
 152                 the dependencies between links.  For this reason,
 153                 this item is not separately configurable.  Hence no
 154                 corresponding constraint needs to be articulated.
 155                 The corresponding information is simply provided by the
 156                 implementing system.";
 157         }
 158     }
 159
 160     grouping node-attributes {
 161         description
 162             "The data objects needed to define a node.
 163             The objects are provided in a grouping so that in addition to
 164             the datastore, the data can also be included in notifications
 165             as needed.";
 166
 167         leaf node-id {
 168             type node-id;
 169             description
 170                 "The identifier of a node in the topology.
 171                 A node is specific to a topology to which it belongs.";
 172         }
 173         list supporting-node {
 174             description
 175                 "This list defines vertical layering information for nodes.
 176                 It allows to capture for any given node, which node (or nodes)
 177                 in the corresponding underlay topology it maps onto.
 178                 A node can map to zero, one, or more nodes below it;
 179                 accordingly there can be zero, one, or more elements in the list.
 180                 If there are specific layering requirements, for example
 181                 specific to a particular type of topology that only allows
 182                 for certain layering relationships, the choice
 183                 below can be augmented with additional cases.
 184                 A list has been chosen rather than a leaf-list in order
 185                 to provide room for augmentations, e.g. for
 186                 statistics or priorization information associated with
 187                 supporting nodes.";
 188             // This is not what was published in the initial draft,
 189             // added topology-ref leaf and added it to the key
 190             key "topology-ref node-ref";
 191             leaf topology-ref {
 192                 type topology-ref;
 193             }
 194             leaf node-ref {
 195                 type node-ref;
 196             }
 197         }
 198     }
 199
 200     grouping link-attributes {
 201         // This is a grouping, not defined inline with the link definition itself,
 202         // so it can be included in a notification, if needed
 203         leaf link-id {
 204             type link-id;
 205             description
 206                 "The identifier of a link in the topology.
 207                 A link is specific to a topology to which it belongs.";
 208         }
 209         container source {
 210             leaf source-node {
 211                 mandatory true;
 212                 type node-ref;
 213                 description
 214                     "Source node identifier, must be in same topology.";
 215             }
 216             leaf source-tp {
 217                 type tp-ref;
 218                 description
 219                     "Termination point within source node that terminates the link.";
 220
 221             }
 222         }
 223         container destination {
 224             leaf dest-node {
 225                 mandatory true;
 226                 type node-ref;
 227                 description
 228                     "Destination node identifier, must be in same topology.";
 229             }
 230             leaf dest-tp {
 231                 type tp-ref;
 232                 description
 233                     "Termination point within destination node that terminates the link.";
 234             }
 235         }
 236         list supporting-link {
 237             key "link-ref";
 238             leaf link-ref {
 239                 type link-ref;
 240             }
 241         }
 242     }
 243
 244
 245     container network-topology {
 246         list topology {
 247             description "
 248                 This is the model of an abstract topology.
 249                 A topology contains nodes and links.
 250                 Each topology MUST be identified by
 251                 unique topology-id for reason that a network could contain many
 252                 topologies.
 253             ";
 254             key "topology-id";
 255             leaf topology-id {
 256                 type topology-id;
 257                 description "
 258                     It is presumed that a datastore will contain many topologies. To
 259                     distinguish between topologies it is vital to have UNIQUE
 260                     topology identifiers.
 261                 ";
 262             }
 263             leaf server-provided {
 264                 type boolean;
 265                 config false;
 266                 description "
 267                     Indicates whether the topology is configurable by clients,
 268                     or whether it is provided by the server.  This leaf is
 269
 270                     populated by the server implementing the model.
 271                     It is set to false for topologies that are created by a client;
 272                     it is set to true otherwise.  If it is set to true, any
 273                     attempt to edit the topology MUST be rejected.
 274                 ";
 275             }
 276             container topology-types {
 277                 description
 278                     "This container is used to identify the type, or types
 279                     (as a topology can support several types simultaneously),
 280                     of the topology.
 281                     Topology types are the subject of several integrity constraints
 282                     that an implementing server can validate in order to
 283                     maintain integrity of the datastore.
 284                     Topology types are indicated through separate data nodes;
 285                     the set of topology types is expected to increase over time.
 286                     To add support for a new topology, an augmenting module
 287                     needs to augment this container with a new empty optional
 288                     container to indicate the new topology type.
 289                     The use of a container allows to indicate a subcategorization
 290                     of topology types.
 291                     The container SHALL NOT be augmented with any data nodes
 292                     that serve a purpose other than identifying a particular
 293                     topology type.
 294                 ";
 295             }
 296             list underlay-topology {
 297                 key "topology-ref";
 298                 leaf topology-ref {
 299                     type topology-ref;
 300                 }
 301                 // a list, not a leaf-list, to allow for potential augmentation
 302                 // with properties specific to the underlay topology,
 303                 // such as statistics, preferences, or cost.
 304                 description
 305                     "Identifies the topology, or topologies, that this topology
 306                     is dependent on.";
 307             }
 308
 309             list node {
 310                 description "The list of network nodes defined for the topology.";
 311                 key "node-id";
 312                 uses node-attributes;
 313                 must "boolean(../underlay-topology[*]/node[./supporting-nodes/node-ref])";
 314                     // This constraint is meant to ensure that a referenced node is in fact
 315                     // a node in an underlay topology.
 316                 list termination-point {
 317                     description
 318
 319                         "A termination point can terminate a link.
 320                         Depending on the type of topology, a termination point could,
 321                         for example, refer to a port or an interface.";
 322                     key "tp-id";
 323                     uses tp-attributes;
 324                 }
 325             }
 326
 327             list link {
 328                 description "
 329                     A Network Link connects a by Local (Source) node and
 330                     a Remote (Destination) Network Nodes via a set of the
 331                     nodes' termination points.
 332                     As it is possible to have several links between the same
 333                     source and destination nodes, and as a link could potentially
 334                     be re-homed between termination points, to ensure that we
 335                     would always know to distinguish between links, every link
 336                     is identified by a dedicated link identifier.
 337                     Note that a link models a point-to-point link, not a multipoint
 338                     link.
 339                     Layering dependencies on links in underlay topologies are
 340                     not represented as the layering information of nodes and of
 341                     termination points is sufficient.
 342                 ";
 343                 key "link-id";
 344                 uses link-attributes;
 345                 must "boolean(../underlay-topology/link[./supporting-link])";
 346                     // Constraint: any supporting link must be part of an underlay topology
 347                 must "boolean(../node[./source/source-node])";
 348                     // Constraint: A link must have as source a node of the same topology
 349                 must "boolean(../node[./destination/dest-node])";
 350                     // Constraint: A link must have as source a destination of the same topology
 351                 must "boolean(../node/termination-point[./source/source-tp])";
 352                     // Constraint: The source termination point must be contained in the source node
 353                 must "boolean(../node/termination-point[./destination/dest-tp])";
 354                     // Constraint: The destination termination point must be contained
 355                     // in the destination node
 356             }
 357         }
 358     }
 359 }