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

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