docs/developer-guide/network-intent-composition-(nic)-developer-guide.rst

   1 Network Intent Composition (NIC) Developer Guide
   2 ================================================
   3
   4 Overview
   5 --------
   6
   7 The Network Intent Composition (NIC) provides four features:
   8
   9 -  odl-nic-core-hazelcast: Provides a distributed intent mapping
  10    service, implemented using hazelcast, that stores metadata needed by
  11    odl-nic-core feature.
  12
  13 -  odl-nic-core-mdsal: Provides an intent rest API to external
  14    applications for CRUD operations on intents, conflict resolution and
  15    event handling. Uses MD-SAL as backend.
  16
  17 -  odl-nic-console: Provides a karaf CLI extension for intent CRUD
  18    operations and mapping service operations.
  19
  20 -  odl-nic-renderer-of - Generic OpenFlow Renderer.
  21
  22 -  odl-nic-renderer-vtn - a feature that transforms an intent to a
  23    network modification using the VTN project
  24
  25 -  odl-nic-renderer-gbp - a feature that transforms an intent to a
  26    network modification using the Group Policy project
  27
  28 -  odl-nic-renderer-nemo - a feature that transforms an intent to a
  29    network modification using the NEMO project
  30
  31 -  odl-nic-listeners - adds support for event listening. (depends on:
  32    odl-nic-renderer-of)
  33
  34 -  odl-nic-neutron-integration - allow integration with openstack
  35    neutron to allow coexistence between existing neutron security rules
  36    and intents pushed by ODL applications.
  37
  38 *Only a single renderer feature should be installed at a time for the
  39 Boron release.*
  40
  41 odl-nic-core-mdsal XOR odl-nic-core-hazelcast
  42 ---------------------------------------------
  43
  44 This feature supplies the base models for the Network Intent Composition
  45 (NIC) capability. This includes the definition of intent as well as the
  46 configuration and operational data trees.
  47
  48 This feature only provides an information model. The interface for NIC
  49 is to modify the information model via the configuraiton data tree,
  50 which will trigger the renderer to make the appropriate changes in the
  51 controlled network.
  52
  53 Installation
  54 ------------
  55
  56 First you need to install one of the core installations:
  57 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  58
  59 ::
  60
  61     feature:install odl-nic-core-service-mdsal odl-nic-console
  62
  63 *OR*
  64
  65 ::
  66
  67     feature:install odl-nic-core-service-hazelcast odl-nic-console
  68
  69 Then pick a renderer:
  70 ~~~~~~~~~~~~~~~~~~~~~
  71
  72 ::
  73
  74     feature:install odl-nic-listeners (will install odl-nic-renderer-of)
  75
  76 *OR*
  77
  78 ::
  79
  80     feature:install odl-nic-renderer-vtn
  81
  82 *OR*
  83
  84 ::
  85
  86     feature:install odl-nic-renderer-gbp
  87
  88 *OR*
  89
  90 ::
  91
  92     feature:install odl-nic-renderer-nemo
  93
  94 REST Supported operations
  95 -------------------------
  96
  97 POST / PUT (configuration)
  98 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  99
 100 This operations create instances of an intent in the configuration data
 101 tree and trigger the creation or modification of an intent.
 102
 103 GET (configuration / operational)
 104 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 105
 106 This operation lists all or fetches a single intent from the data tree.
 107
 108 DELETE (configuration)
 109 ~~~~~~~~~~~~~~~~~~~~~~
 110
 111 This operation will cause an intent to be removed from the system and
 112 trigger any configuration changes on the network rendered from this
 113 intent to be removed.
 114
 115 odl-nic-cli user guide
 116 ----------------------
 117
 118 This feature provides karaf console CLI command to manipulate the intent
 119 data model. The CLI essentailly invokes the equivalent data operations.
 120
 121 intent:add
 122 ~~~~~~~~~~
 123
 124 Creates a new intent in the configuration data tree
 125
 126 ::
 127
 128     DESCRIPTION
 129             intent:add
 130
 131         Adds an intent to the controller.
 132
 133     Examples: --actions [ALLOW] --from <subject> --to <subject>
 134               --actions [BLOCK] --from <subject>
 135
 136     SYNTAX
 137             intent:add [options]
 138
 139     OPTIONS
 140             -a, --actions
 141                     Action to be performed.
 142                     -a / --actions BLOCK/ALLOW
 143                     (defaults to [BLOCK])
 144             --help
 145                     Display this help message
 146             -t, --to
 147                     Second Subject.
 148                     -t / --to <subject>
 149                     (defaults to any)
 150             -f, --from
 151                     First subject.
 152                     -f / --from <subject>
 153                     (defaults to any)
 154
 155 intent:delete
 156 ~~~~~~~~~~~~~
 157
 158 Removes an existing intent from the system
 159
 160 ::
 161
 162     DESCRIPTION
 163             intent:remove
 164
 165         Removes an intent from the controller.
 166
 167     SYNTAX
 168             intent:remove id
 169
 170     ARGUMENTS
 171             id  Intent Id
 172
 173 intent:list
 174 ~~~~~~~~~~~
 175
 176 Lists all the intents in the system
 177
 178 ::
 179
 180     DESCRIPTION
 181             intent:list
 182
 183         Lists all intents in the controller.
 184
 185     SYNTAX
 186             intent:list [options]
 187
 188     OPTIONS
 189             -c, --config
 190                     List Configuration Data (optional).
 191                     -c / --config <ENTER>
 192             --help
 193                     Display this help message
 194
 195 intent:show
 196 ~~~~~~~~~~~
 197
 198 Displays the details of a single intent
 199
 200 ::
 201
 202     DESCRIPTION
 203             intent:show
 204
 205         Shows detailed information about an intent.
 206
 207     SYNTAX
 208             intent:show id
 209
 210     ARGUMENTS
 211             id  Intent Id
 212
 213 intent:map
 214 ~~~~~~~~~~
 215
 216 List/Add/Delete current state from/to the mapping service.
 217
 218 ::
 219
 220     DESCRIPTION
 221             intent:map
 222
 223             List/Add/Delete current state from/to the mapping service.
 224
 225     SYNTAX
 226             intent:map [options]
 227
 228              Examples: --list, -l [ENTER], to retrieve all keys.
 229                        --add-key <key> [ENTER], to add a new key with empty contents.
 230                        --del-key <key> [ENTER], to remove a key with it's values."
 231                        --add-key <key> --value [<value 1>, <value 2>, ...] [ENTER],
 232                          to add a new key with some values (json format).
 233     OPTIONS
 234            --help
 235                Display this help message
 236            -l, --list
 237                List values associated with a particular key.
 238            -l / --filter <regular expression> [ENTER]
 239            --add-key
 240                Adds a new key to the mapping service.
 241            --add-key <key name> [ENTER]
 242            --value
 243                Specifies which value should be added/delete from the mapping service.
 244            --value "key=>value"... --value "key=>value" [ENTER]
 245                (defaults to [])
 246            --del-key
 247                Deletes a key from the mapping service.
 248            --del-key <key name> [ENTER]
 249
 250 Sample Use case: MPLS
 251 ---------------------
 252
 253 Description
 254 ~~~~~~~~~~~
 255
 256 The scope of this use-case is to add MPLS intents between two MPLS
 257 endpoints. The use-case tries to address the real-world scenario
 258 illustrated in the diagram below:
 259
 260 .. figure:: ./images/nic/MPLS_VPN_Service_Diagram.png
 261    :alt: MPLS VPN Service Diagram
 262
 263    MPLS VPN Service Diagram
 264
 265 where PE (Provider Edge) and P (Provider) switches are managed by
 266 OpenDaylight. In NIC’s terminology the endpoints are the PE switches.
 267 There could be many P switches between the PEs.
 268
 269 In order for NIC to recognize endpoints as MPLS endpoints, the user is
 270 expected to add mapping information about the PE switches to NIC’s
 271 mapping service to include the below properties:
 272
 273 1. MPLS Label to identify a PE
 274
 275 2. IPv4 Prefix for the customer site that are connected to a PE
 276
 277 3. Switch-Port: Ingress (or Egress) for source (or Destination) endpoint
 278    of the source (or Destination) PE
 279
 280 An intent:add between two MPLS endpoints renders OpenFlow rules for: 1.
 281 push/pop labels to the MPLS endpoint nodes after an IPv4 Prefix match.
 282 2. forward to port rule after MPLS label match to all the switches that
 283 form the shortest path between the endpoints (calculated using Dijkstra
 284 algorithm).
 285
 286 Additionally, we have also added constraints to Intent model for
 287 protection and failover mechanism to ensure end-to-end connectivity
 288 between endpoints. By specifying these constraints to intent:add the
 289 use-case aims to reduces the risk of connectivity failure due to a
 290 single link or port down event on a forwarding device.
 291
 292 -  Protection constraint: Constraint that requires an end-to-end
 293    connectivity to be protected by providing redundant paths.
 294
 295 -  Failover constraint: Constraint that specifies the type of failover
 296    implementation. slow-reroute: Uses disjoint path calculation
 297    algorithms like Suurballe to provide alternate end-to-end routes.
 298    fast-reroute: Uses failure detection feature in hardware forwarding
 299    device through OF group table features (Future plans) When no
 300    constraint is requested by the user we default to offering a since
 301    end-to-end route using Dijkstra shortest path.
 302
 303 How to use it?
 304 ~~~~~~~~~~~~~~
 305
 306 1. Start Karaf and install related features:
 307
 308    ::
 309
 310        feature:install odl-nic-core-service-mdsal odl-nic-core odl-nic-console odl-nic-listeners
 311        feature:install odl-dlux-all odl-dlux-core odl-dlux-yangui odl-dlux-yangvisualizer
 312
 313 2. Start mininet topology and verify in DLUX Topology page for the nodes
 314    and link.
 315
 316    ::
 317
 318        mn --controller=remote,ip=$CONTROLLER_IP --custom ~/shortest_path.py --topo shortest_path --switch ovsk,protocols=OpenFlow13
 319
 320    ::
 321
 322        cat shortest.py -->
 323        from mininet.topo import Topo
 324        from mininet.cli import CLI
 325        from mininet.net import Mininet
 326        from mininet.link import TCLink
 327        from mininet.util import irange,dumpNodeConnections
 328        from mininet.log import setLogLevel
 329
 330    ::
 331
 332        class Fast_Failover_Demo_Topo(Topo):
 333
 334    ::
 335
 336        def __init__(self):
 337            # Initialize topology and default options
 338            Topo.__init__(self)
 339
 340    ::
 341
 342        s1 = self.addSwitch('s1',dpid='0000000000000001')
 343        s2a = self.addSwitch('s2a',dpid='000000000000002a')
 344        s2b = self.addSwitch('s2b',dpid='000000000000002b')
 345        s2c = self.addSwitch('s2c',dpid='000000000000002c')
 346        s3 = self.addSwitch('s3',dpid='0000000000000003')
 347        self.addLink(s1, s2a)
 348        self.addLink(s1, s2b)
 349        self.addLink(s2b, s2c)
 350        self.addLink(s3, s2a)
 351        self.addLink(s3, s2c)
 352        host_1 = self.addHost('h1',ip='10.0.0.1',mac='10:00:00:00:00:01')
 353        host_2 = self.addHost('h2',ip='10.0.0.2',mac='10:00:00:00:00:02')
 354        self.addLink(host_1, s1)
 355        self.addLink(host_2, s3)
 356
 357    ::
 358
 359        topos = { 'shortest_path': ( lambda: Demo_Topo() ) }
 360
 361 3. Update the mapping service with required information
 362
 363    Sample payload:
 364
 365    ::
 366
 367        {
 368          "mappings": {
 369            "outer-map": [
 370              {
 371                "id": "uva",
 372                "inner-map": [
 373                  {
 374                    "inner-key": "ip_prefix",
 375                    "value": "10.0.0.1/32"
 376                  },
 377                  {
 378                    "inner-key": "mpls_label",
 379                    "value": "15"
 380                  },
 381                  {
 382                    "inner-key": "switch_port",
 383                    "value": "openflow:1:1"
 384                  }
 385                ]
 386              },
 387              {
 388                "id": "eur",
 389                "inner-map": [
 390                  {
 391                    "inner-key": "ip_prefix",
 392                    "value": "10.0.0.2/32"
 393                  },
 394                  {
 395                    "inner-key": "mpls_label",
 396                    "value": "16"
 397                  },
 398                  {
 399                    "inner-key": "switch_port",
 400                    "value": "openflow:3:1"
 401                  }
 402                ]
 403              }
 404            ]
 405          }
 406        }
 407
 408 4. Create bidirectional Intents using Karaf command line or RestCONF:
 409
 410    Example:
 411
 412    ::
 413
 414        intent:add -f uva -t eur -a ALLOW
 415        intent:add -f eur -t uva -a ALLOW
 416
 417 5. Verify by running ovs-ofctl command on mininet if the flows were pushed
 418    correctly to the nodes that form the shortest path.
 419
 420    Example:
 421
 422    ::
 423
 424        ovs-ofctl -O OpenFlow13 dump-flows s1
 425