manuals/user-guide/src/main/asciidoc/nic/nic-user.adoc

   1 == Network Intent Composition (NIC) User Guide
   2
   3 === Overview
   4 Network Intent Composition (NIC) is an interface that allows clients to
   5 express a desired state in an implementation-neutral form that will be
   6 enforced via modification of available resources under the control of
   7 the OpenDaylight system.
   8
   9 This description is purposely abstract as an intent interface might
  10 encompass network services, virtual devices, storage, etc.
  11
  12 The intent interface is meant to be a controller-agnostic interface
  13 so that "intents" are portable across implementations, such as OpenDaylight
  14 and ONOS. Thus an intent specification should not contain implementation
  15 or technology specifics.
  16
  17 The intent specification will be implemented by decomposing the intent
  18 and augmenting it with implementation specifics that are driven by
  19 local implementation rules, policies, and/or settings.
  20
  21 === Network Intent Composition (NIC) Architecture
  22 The core of the NIC architecture is the intent model, which specifies
  23 the details of the desired state. It is the responsibility of the NIC
  24 implementation transforms this desired state to the resources under
  25 the control of OpenDaylight. The component that transforms the
  26 intent to the implementation is typically referred to as a renderer.
  27
  28 For the Boron release, multiple, simultaneous renderers will not be supported.
  29 Instead either the VTN or GBP renderer feature can be installed, but
  30 not both.
  31
  32 For the Boron release, the only actions supported are "ALLOW" and
  33 "BLOCK". The "ALLOW" action indicates that traffic can flow between
  34 the source and destination end points, while "BLOCK" prevents that
  35 flow; although it is possible that an given implementation may augment
  36 the available actions with additional actions.
  37
  38 Besides transforming a desired state to an actual state it is the
  39 responsibility of a renderer to update the operational state tree for
  40 the NIC data model in OpenDaylight to reflect the intent which the
  41 renderer implemented.
  42
  43 === Configuring Network Intent Composition (NIC)
  44 For the Boron release there is no default implementation of a renderer,
  45 thus without an additional module installed the NIC will not function.
  46
  47 === Administering or Managing Network Intent Composition (NIC)
  48 There is no additional administration of management capabilities
  49 related to the Network Intent Composition features.
  50
  51 === Interactions
  52 A user can interact with the Network Intent Composition (NIC) either
  53 through the RESTful interface using standard RESTCONF operations and
  54 syntax or via the Karaf console CLI.
  55
  56 ==== REST
  57
  58 ===== Configuration
  59 The Network Intent Composition (NIC) feature supports the following REST
  60 operations against the configuration data store.
  61
  62 * POST - creates a new instance of an intent in the configuration store,
  63 which will trigger the realization of that intent. An ID _must_ be specified
  64 as part of this request as an attribute of the intent.
  65
  66 * GET - fetches a list of all configured intents or a specific configured
  67 intent.
  68
  69 * DELETE - removes a configured intent from the configuration store, which
  70 triggers the removal of the intent from the network.
  71
  72 ===== Operational
  73 The Network Intent Composition (NIC) feature supports the following REST
  74 operations against the operational data store.
  75
  76 * GET - fetches a list of all operational intents or a specific operational
  77 intent.
  78
  79 ==== Karaf Console CLI
  80 This feature provides karaf console CLI command to manipulate the intent
  81 data model. The CLI essentailly invokes the equivalent data operations.
  82
  83 ===== intent:add
  84
  85 Creates a new intent in the configuration data tree
  86
  87 ----
  88 DESCRIPTION
  89         intent:add
  90
  91     Adds an intent to the controller.
  92
  93 Examples: --actions [ALLOW] --from <subject> --to <subject>
  94           --actions [BLOCK] --from <subject>
  95
  96 SYNTAX
  97         intent:add [options]
  98
  99 OPTIONS
 100         -a, --actions
 101                 Action to be performed.
 102                 -a / --actions BLOCK/ALLOW
 103                 (defaults to [BLOCK])
 104         --help
 105                 Display this help message
 106         -t, --to
 107                 Second Subject.
 108                 -t / --to <subject>
 109                 (defaults to any)
 110         -f, --from
 111                 First subject.
 112                 -f / --from <subject>
 113                 (defaults to any)
 114 ----
 115
 116 ===== intent:delete
 117 Removes an existing intent from the system
 118
 119 ----
 120 DESCRIPTION
 121         intent:remove
 122
 123     Removes an intent from the controller.
 124
 125 SYNTAX
 126         intent:remove id
 127
 128 ARGUMENTS
 129         id  Intent Id
 130 ----
 131
 132 ===== intent:list
 133 Lists all the intents in the system
 134
 135 ----
 136 DESCRIPTION
 137         intent:list
 138
 139     Lists all intents in the controller.
 140
 141 SYNTAX
 142         intent:list [options]
 143
 144 OPTIONS
 145         -c, --config
 146                 List Configuration Data (optional).
 147                 -c / --config <ENTER>
 148         --help
 149                 Display this help message
 150 ----
 151
 152 ===== intent:show
 153 Displayes the details of a single intent
 154
 155 ----
 156 DESCRIPTION
 157         intent:show
 158
 159     Shows detailed information about an intent.
 160
 161 SYNTAX
 162         intent:show id
 163
 164 ARGUMENTS
 165         id  Intent Id
 166 ----
 167
 168
 169 ===== intent:map
 170
 171 List/Add/Delete current state from/to the mapping service.
 172
 173 ----
 174 DESCRIPTION
 175         intent:map
 176
 177         List/Add/Delete current state from/to the mapping service.
 178
 179 SYNTAX
 180         intent:map [options]
 181
 182          Examples: --list, -l [ENTER], to retrieve all keys.
 183                    --add-key <key> [ENTER], to add a new key with empty contents.
 184                    --del-key <key> [ENTER], to remove a key with it's values."
 185                    --add-key <key> --value [<value 1>, <value 2>, ...] [ENTER],
 186                      to add a new key with some values (json format).
 187 OPTIONS
 188        --help
 189            Display this help message
 190        -l, --list
 191            List values associated with a particular key.
 192        -l / --filter <regular expression> [ENTER]
 193        --add-key
 194            Adds a new key to the mapping service.
 195        --add-key <key name> [ENTER]
 196        --value
 197            Specifies which value should be added/delete from the mapping service.
 198        --value "key=>value"... --value "key=>value" [ENTER]
 199            (defaults to [])
 200        --del-key
 201            Deletes a key from the mapping service.
 202        --del-key <key name> [ENTER]
 203 ----
 204
 205 === NIC Usage Examples
 206
 207 In addition to the one example here, please see the wiki for more use cases:
 208 https://wiki.opendaylight.org/view/Network_Intent_Composition:Use_Cases
 209
 210 include::NIC_How_To_configure_VTN_Renderer.adoc[How to configure VTN Renderer]