docs/userguide/feature.userguide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) Ulas C. Kozat Huawei R&D USA
   4
   5 .. image:: ../etc/opnfv-logo.png
   6   :height: 40
   7   :width: 200
   8   :alt: OPNFV
   9   :align: left
  10 .. these two pipes are to seperate the logo from the first title
  11 |
  12 |
  13 Domino Description
  14 ==================
  15
  16 Domino provides a distribution service for Network Service Descriptors (NSDs) and
  17 Virtual Network Function Descriptors (VNFDs) that are composed using Tosca Simple
  18 Profile for Network Functions Virtualization
  19 (http://docs.oasis-open.org/tosca/tosca-nfv/v1.0/tosca-nfv-v1.0.html).
  20 Domino service is targeted towards supporting many SDN controllers, service orchestrators,
  21 VNF Managers (VNFMs), Virtual Infastructure Managers (VIMs), Operation and Business Support
  22 Systems that produce and/or consume NSDs and VNFDs.
  23
  24 Producers of NSDs and VNFDs use Domino Service as an entry point to publish these
  25 descriptors. Consumers of NSDs and VNFDs subscribe with the Domino Service and declare
  26 their resource capabilities to onboard and perform Life Cycle Management (LCM) for Network
  27 Services (NSs) and Virtual Network Functions (VNFs). Thus, Domino acts as a broker for
  28 NSs and VNFs described in a Tosca template.
  29
  30
  31 Domino Capabilities and Usage
  32 =============================
  33
  34 Labels in Domino
  35 ----------------
  36
  37 Domino's pub/sub architecture is based on labels (see :numref:`fig-label` below).
  38 Each Template Producer and Template Consumer is expected to run a local Domino Client
  39 to publish templates and subscribe for labels.
  40
  41 .. _fig-label:
  42
  43 .. figure:: ../etc/domino_pubsub_system.jpeg
  44     :width: 350px
  45     :align: center
  46     :height: 300px
  47     :alt: alternate text
  48     :figclass: align-center
  49
  50     Domino provides a pub/sub server for NSDs and VNFDs
  51
  52 Domino Service does not interpret what the labels mean. Domino derives labels directly from
  53 the normative definitions in TOSCA Simple YAML Profile for NFV. Domino parses the policy
  54 rules included in the NSD/VNFD, form "policy" labels, and determine which resources are
  55 associated with which set of labels. Domino identifies which Domino Clients can host
  56 which resource based on the label subscriptions by these clients. Once mapping of resources
  57 to the clients are done, new NSDs/VNFDs are created based on the mapping. These new
  58 NSDs/VNFDs are translated and delivered to the clients.
  59
  60 Label Format and Examples
  61 -------------------------
  62
  63 Domino supports policy labels in the following form:
  64
  65 .. code-block:: bash
  66
  67   <policytype>:properties:<key:value>
  68
  69 Orchestrators, controllers, and managers use Domino service to announce their
  70 capabilities by defining labels in this form and subscribing for these labels with
  71 the Domino Server.
  72
  73 For instance a particular VIM that is capable of performing an
  74 affinity based VNF or VDU placement at host machine granularity can specify a label
  75 in the form:
  76
  77 .. code-block:: bash
  78
  79   tosca.policies.Placement.affinity:properties:granularity:hostlevel
  80
  81 When the VIM registers with the Domino Service and subscribed for that label, Domino views
  82 this VIM as a candidate location that can host a VNF or VDU requesting affinity based
  83 placement policy at host machine granularity.
  84
  85 Another use case is the announcement of lifecycle management capabilities for VNFs and
  86 VNF Forwarding Graphs (VNFFG) by different SDN Controllers (SDN-Cs), VNFMs, or VIMs.
  87 For instance
  88
  89 .. code-block:: bash
  90
  91   tosca.policies.Scaling.VNFFG:properties:session_continuity:true
  92
  93 can be used as a label to indicate that when a scaling operation on a VNFFG (e.g., add
  94 more VNFs into the graph) is requested, existing session can still be enforced to go
  95 through the same chain of VNF instances.
  96
  97 To utilize Domino's domain mapping services for virtual network resources (e.g., VNF, VDU,
  98 VNFFG, CP, VL, etc.), a network service or network function request must include
  99 policy rules that are composed of policy types and property values that match to the
 100 label announcements of these domains. For instance, when a TOSCA template includes a
 101 policy rule with type "tosca.policies.Scaling.VNFFG" and property field
 102 "session_continuity" set as "true" targeting one or more VNFFGs, this serves as the hint
 103 for the Domino Server to identify all the Domain Clients that subscribed the label
 104 "tosca.policies.Scaling.VNFFG:properties:session_continuity:true".
 105
 106 Template Example for Label Extraction
 107 -------------------------------------
 108
 109 Consider the following NSD TOSCA template:
 110
 111 .. code-block:: bash
 112
 113   tosca_definitions_version: tosca_simple_profile_for_nfv_1_0_0
 114   description: Template for deploying a single server with predefined properties.
 115   metadata:
 116     template_name: TOSCA NFV Sample Template
 117   policy_types:
 118     tosca.policies.Placement.Geolocation:
 119       description: Geolocation policy
 120       derived_from: tosca.policies.Placement
 121   topology_template:
 122     node_templates:
 123       VNF1:
 124         type: tosca.nodes.nfv.VNF
 125         properties:
 126           id: vnf1
 127           vendor: acmetelco
 128           version: 1.0
 129       VNF2:
 130         type: tosca.nodes.nfv.VNF
 131         properties:
 132           id: vnf2
 133           vendor: ericsson
 134           version: 1.0
 135       VNF3:
 136         type: tosca.nodes.nfv.VNF
 137         properties:
 138           id: vnf3
 139           vendor: huawei
 140           version: 1.0
 141     policies:
 142       - rule1:
 143           type: tosca.policies.Placement.Geolocation
 144           targets: [ VNF1 ]
 145           properties:
 146             region: [ us-west-1 ]
 147       - rule2:
 148           type: tosca.policies.Placement.Geolocation
 149           targets: [ VNF2, VNF3 ]
 150           properties:
 151             region: [ us-west-1 , us-west-2 ]
 152
 153 Domino Server extracts all possible policy labels by exhaustively concatenating key-value
 154 pairs under the properties section of the policy rules to the policy type of these rules:
 155
 156 .. code-block:: bash
 157
 158   tosca.policies.Placement.Geolocation:properties:region:us-west-1
 159   tosca.policies.Placement.Geolocation:properties:region:us-west-2
 160
 161 Furthermore, Domino Server iterates over the targets specified under policy rules to generate a set of labels for each target node:
 162
 163 .. code-block:: bash
 164
 165   required_labels['VNF1'] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 }
 166   required_labels['VNF2'] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 , tosca.policies.Placement.Geolocation:properties:region:us-west-2}
 167   required_labels['VNF3'] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 , tosca.policies.Placement.Geolocation:properties:region:us-west-2}
 168
 169 When a Template Consuming site (e.g., VNFM or VIM) registers with the Domino Server using
 170 Domino Client, it becomes an eligible candidate for template distribution with an initially
 171 empty set of label subscriptions. Suppose three different Domino Clients register with the
 172 Domino Server and subscribe for some or none of the policy labels such that the Domino Server
 173 has the current subscription state as follows:
 174
 175 .. code-block:: bash
 176
 177   subscribed_labels[site-1] = { } #this is empty set
 178   subscribed_labels[site-2] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 }
 179   subscribed_labels[site-3] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 ,  tosca.policies.Placement.Geolocation:properties:region:us-west-2}
 180
 181
 182 Based on the TOSCA example and hypothetical label subscriptions above, Domino Server identifies
 183 all the VNFs can be hosted by Site-3, while VNF1 can be hosted by both Site-2 and Site-3.
 184 Note that Site-1 cannot host any of the VNFs listed in the TOSCA file. When a VNF can be hosted
 185 by multiple sites, Domino Server picks the site that can host the most number of VNFs. When not
 186 all VNFs can be hosted on the same site, the TOSCA file is partitioned into multiple files, one
 187 for each site. These files share a common part (e.g, meta-data, policy-types, version,
 188 description, virtual resources that are not targeted by any policy rule, etc.). Each site
 189 specific file has also a non-common part that only appears in that file (i.e., virtual
 190 resources explicitly assigned to that site and the policy rules that accompany those virtual
 191 resources.
 192
 193 In the current Domino convention, if a VNF (or any virtual resource) does not have a policy
 194 rule (i.e., it is not specified as a target in any of the policy rules) and it also is not
 195 dependent on any VNF (or any virtual resource) that is assigned to another site, that resource
 196 is wild carded by default and treated as part of the "common part". Also note that currently
 197 Domino does not support all or nothing semantics: if some of the virtual resources are not
 198 mappable to any domain because they are targets of policy rules that are not supported by any
 199 site, these portions will be excluded while the remaining virtual resources will be still be
 200 part of one or more template files to be distributed to hosting sites. When NSDs and VNFDs are
 201 prepared, these conventions must be kept in mind. In the future releases, these conventions can
 202 change based on the new use cases.
 203
 204 For the example above, no partitioning would occur as all VNFs are mapped onto site-3;
 205 Domino Server simply delivers the Tosca file to Domino Client hosted on site-3. When TOSCA
 206 cannot be consumed by a particular site directly, Domino Server can utilize
 207 existing translators (e.g., heat-translator) to first translate the template before delivery.
 208
 209 Internal Processing Pipeline at Domino Server
 210 ---------------------------------------------
 211
 212 :numref:`fig-pipe` shows the block diagram for the processing stages of a published TOSCA template.
 213 Domino Client issues an RPC call publish(tosca file). Domino Server passes the received tosca
 214 file to Label Extractor that outputs resource labels. Domain Mapper uses the extracted labels
 215 and tosca file to find mappings from resources to domains as well as the resource dependencies.
 216 Resource to domain mappings and resource dependencies are utilized to partition the
 217 orchestration template into individual resource orchestration templates (one for each domain).
 218 If a translation is required (e.g., TOSCA to HOT), individual resource orchestration templates
 219 are first translated and then placed on a template distribution workflow based on resource
 220 dependencies. Message Sender block in the server takes one distribution task at a time from the
 221 workflow generator and pushes the orchestration template to the corresponding Domino Client.
 222
 223 .. _fig-pipe:
 224
 225 .. figure:: ../etc/domino_server_processing.png
 226     :width: 400px
 227     :align: center
 228     :height: 350px
 229     :alt: alternate text
 230     :figclass: align-center
 231
 232     Domino Service Processing Pipeline
 233
 234 Resource Scheduling
 235 -------------------
 236
 237 Domino Service currently supports maximum packing strategy when a  virtual resource type can
 238 be hosted on multiple candidate sites. Initially, Domino Scheduler identifies virtual resources
 239 that has only one feasible site for hosting. Each such virtual resource is trivially assigned
 240 to its only feasible site. The remaining virtual resources with multiple candidate locations
 241 are sequentially allocated to one of their candidate locations that has the most virtual
 242 resource assignments so far. Note that wildcarded resources are assigned to all sites. To
 243 prevent wildcarding within the current release, (i) all sites must subscribed to a base policy
 244 with a dummy key-value pair defined under the properties tab and (ii) all the independent
 245 resources must be specified as target of that policy in NSD or VNFD file.
 246
 247 Domino and API Usage Guidelines and Examples
 248 ============================================
 249
 250 Using domino-cli Client
 251 -----------------------
 252
 253 Prerequisites:
 254
 255 1. Make sure that domino-cli.py is in +x mode.
 256
 257 2. Change directory to where domino-cli.py, DominoClient.py and DominoServer.py are located or include file path in the PATH environment variable.
 258
 259 3. Start the Domino Server:
 260
 261 .. code-block:: bash
 262
 263   ./DominoServer.py --log=debug
 264
 265 4. Start the Domino Client:
 266
 267 .. code-block:: bash
 268
 269   ./DominoClient.py -p <portnumber> --cliport <cli-portnumber> --log=debug
 270
 271 Note1: The default log level is WARNING and omitting --log option will lead to minimal/no logging on the console
 272
 273 Note2: domino_conf.py file includes most of the default values
 274
 275 * Registration Command
 276
 277 Command line input:
 278
 279 .. code-block:: bash
 280
 281   ./domino-cli.py <cli-portnumber> register
 282
 283 This message has the following fields that are automatically filled in.
 284
 285 .. code-block:: bash
 286
 287   Message Type (= REGISTER)
 288   DESIRED UDID (= if not allocated, this will be assigned as Unique Domino ID)
 289   Sequence Number (=incremented after each RPC call)
 290   IP ADDR (= IP address of DOMINO Client to be used by DOMINO Server for future RPC Calls to this client)
 291   TCP PORT (= TCP port of DOMINO Client to be used by DOMINO Server for future RPC Calls to this client)
 292   Supported Templates (= Null, this field not used currently)
 293
 294 * Heart Beat Command
 295
 296 Command line input:
 297
 298 .. code-block:: bash
 299
 300   ./domino-cli.py <cli-portnumber> heartbeat
 301
 302 This message has the following fields that are automatically filled in.
 303
 304 .. code-block:: bash
 305
 306   Message Type (= HEART_BEAT)
 307   UDID (= Unique Domino ID assigned during registration)
 308   Sequence Number (=incremented after each RPC call)
 309
 310 * Label and Template Type Subscription Command
 311
 312 .. code-block:: bash
 313
 314   ./domino-cli.py <cli-portnumber> subscribe -l <labelname> -t <templatetype>
 315
 316 Note that -l can be substituted by --label and -t can be substituted by --ttype.
 317
 318 More than one label or template type can be subscribed within the same command line as comma separated labels or template types
 319
 320 .. code-block:: bash
 321
 322   ./domino-cli.py <cli-portnumber> subscribe -l <label1>,<label2>,<labeln> -t <ttype1>,<ttype2>,<ttypen>
 323
 324 To subscribe more than one label or template type, one can also repeat the options -l and -t, e.g.:
 325
 326 .. code-block:: bash
 327
 328   ./domino-cli.py <cli-portnumber> subscribe -l <label1> -l <label2> -l <labeln> -t <ttype1> -t <ttype2> -t <ttypen>
 329
 330 It is safe to call subscribe command multiple times with duplicate labels.
 331
 332 This message has the following fields that are automatically filled in.
 333
 334 .. code-block:: bash
 335
 336   Message Type (= SUBSCRIBE)
 337   UDID (= Unique Domino ID assigned during registration)
 338   Sequence Number (=incremented after each RPC call)
 339   Template Operation (= APPEND)
 340   Label Operation (= APPEND)
 341
 342 The following fields are filled in based on arguments passed on via -l/--label and -t/--ttype flags
 343
 344 Subscribe RPC also supports options for label using
 345   --lop=APPEND/DELETE/OVERWRITE
 346 and for supported template types using
 347   --top=APPEND/DELETE/OVERWRITE.
 348 When unspecified, the default is APPEND.
 349 DELETE deletes existing labels (template types) specified in the current call via key -l/--label (-t/--ttype).
 350 OVERWRITE removes the current set of labels (template types) and sets it to the new set of values passed in the same RPC call.
 351
 352 By default, no translation service is provided. Currently, only TOSCA to Heat
 353 Orchestration Template (HOT) translation is supported using OpenStack
 354 heat-translator library. A domain that requires HOT files must subscribe HOT
 355 template type using
 356
 357 .. code-block:: bash
 358
 359   ./domino-cli.py <cli-portnumber> subscribe -t hot
 360
 361 * Template Publishing Command
 362
 363 .. code-block:: bash
 364
 365   ./domino-cli.py <cli-portnumber> publish -t <toscafile>
 366
 367 Note that -t can be substituted by --tosca-file.
 368
 369 If -t or --tosca-file flag is used multiple times, the last tosca file passed as input will be used. This usage is not recommended as undefined/unintended results may emerge as the Domino client will continue to publish.
 370
 371 This message has the following fields that are automatically filled in.
 372
 373 .. code-block:: bash
 374
 375   Message Type (= SUBSCRIBE)
 376   UDID (= Unique Domino ID assigned during registration)
 377   Sequence Number (=incremented after each RPC call)
 378   Template Type (= TOSCA)
 379   Template File
 380
 381 Interactive CLI mode
 382 --------------------
 383
 384 To enter this mode, start Domino Client with interactive console option set as true, i.e., --iac=true:
 385
 386 .. code-block:: bash
 387
 388   ./DominoClient -p <portnumber> --iax=true --log=DEBUG
 389
 390 The rest of the API calls are the same as in the case of using domino-cli.py except that at the prompt there is no need to write "domino-cli.py <cli-portnumber>, e.g.,:
 391
 392 .. code-block:: bash
 393
 394   >>register
 395   >>heartbeat
 396   >>subscribe -l <label1> -t <ttype1>
 397   >>publish -t <toscafile>
 398
 399 The interactive CLI mode is mainly supported for manual testing.