docs/userguide/overview.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 .. image:: ../etc/opnfv-logo.png
   5   :height: 40
   6   :width: 200
   7   :alt: OPNFV
   8   :align: left
   9 .. these two pipes are to seperate the logo from the first title
  10 |
  11 |
  12 Domino Overview
  13 ===============
  14
  15 Domino provides a distribution service for Network Service Descriptors (NSDs) and
  16 Virtual Network Function Descriptors (VNFDs) that are composed using Tosca Simple
  17 Profile for 20 Network Functions Virtualization
  18 (http://docs.oasis-open.org/tosca/tosca-nfv/v1.0/tosca-nfv-v1.0.html).
  19 Domino service is targeted towards supporting many SDN controllers, service orchestrators,
  20 VNF Managers (VNFMs), Virtual Infastructure Managers (VIMs), Operation and Business Support
  21 Systems that produce and/or consume NSDs and VNFDs.
  22
  23 Producers of NSDs and VNFDs use Domino Service as an entry point to publish these
  24 descriptors. Consumers of NSDs and VNFDs subscribe with the Domino Service and declare
  25 their resource capabilities to onboard and perform Life Cycle Management (LCM) for Network
  26 Services (NSs) and Virtual Network Functions (VNFs). Thus, Domino acts as a broker for
  27 NSs and VNFs described in a Tosca template.
  28
  29 Labels in Domino
  30 ----------------
  31
  32 Domino's pub/sub architecture is based on labels (see :numref:`fig-label` below).
  33 Each Template Producer and Template Consumer is expected to run a local Domino Client
  34 to publish templates and subscribe for labels.
  35
  36 .. _fig-label:
  37
  38 .. figure:: ../etc/domino_pubsub_system.jpeg
  39     :width: 350px
  40     :align: center
  41     :height: 300px
  42     :alt: alternate text
  43     :figclass: align-center
  44
  45     Domino provides a pub/sub server for NSDs and VNFDs
  46
  47 Domino Service does not interpret what the labels mean. Domino derives labels directly from
  48 the normative definitions in TOSCA Simple YAML Profile for NFV. Domino parses the policy
  49 rules included in the NSD/VNFD, form "policy" labels, and determine which resources are
  50 associated with which set of labels. Domino identifies which Domino Clients can host
  51 which resource based on the label subscriptions by these clients. Once mapping of resources
  52 to the clients are done, new NSDs/VNFDs are created based on the mapping. These new
  53 NSDs/VNFDs are translated and delivered to the clients.
  54
  55 Label Format and Examples
  56 -------------------------
  57
  58 Domino supports policy labels in the following form:
  59
  60 .. code-block:: bash
  61
  62   <policytype>:properties:<key:value>
  63
  64 Orchestrators, controllers, and managers use Domino service to announce their
  65 capabilities by defining labels in this form and subscribing for these labels with
  66 the Domino Server.
  67
  68 For instance a particular VIM that is capable of performing an
  69 affinity based VNF or VDU placement at host machine granularity can specify a label
  70 in the form:
  71
  72 .. code-block:: bash
  73
  74   tosca.policies.Placement.affinity:properties:granularity:hostlevel
  75
  76 When the VIM registers with the Domino Service and subscribed for that label, Domino views
  77 this VIM as a candidate location that can host a VNF or VDU requesting affinity based
  78 placement policy at host machine granularity.
  79
  80 Another use case is the announcement of lifecycle management capabilities for VNFs and
  81 VNF Forwarding Graphs (VNFFG) by different SDN Controllers (SDN-Cs), VNFMs, or VIMs.
  82 For instance
  83
  84 .. code-block:: bash
  85
  86   tosca.policies.Scaling.VNFFG:properties:session_continuity:true
  87
  88 can be used as a label to indicate that when a scaling operation on a VNFFG (e.g., add
  89 more VNFs into the graph) is requested, existing session can still be enforced to go
  90 through the same chain of VNF instances.
  91
  92 To utilize Domino's domain mapping services for virtual network resources (e.g., VNF, VDU,
  93 VNFFG, CP, VL, etc.), a network service or network function request must include
  94 policy rules that are composed of policy types and property values that match to the
  95 label announcements of these domains. For instance, a TOSCA template that include a
  96 policy rule with type "tosca.policies.Scaling.VNFFG" and property field
  97 "session_continuity" set as "true" targeting one or more VNFFGs, this serves as the hint
  98 for the Domino Server to identify all the Domain Clients that subscribed the label
  99 "tosca.policies.Scaling.VNFFG:properties:session_continuity:true".
 100
 101 Template Example for Label Extraction
 102 -------------------------------------
 103
 104 Consider the following NSD TOSCA template:
 105
 106 .. code-block:: bash
 107
 108   tosca_definitions_version: tosca_simple_profile_for_nfv_1_0_0
 109   description: Template for deploying a single server with predefined properties.
 110   metadata:
 111     template_name: TOSCA NFV Sample Template
 112   policy_types:
 113     tosca.policies.Placement.Geolocation:
 114       description: Geolocation policy
 115       derived_from: tosca.policies.Placement
 116   topology_template:
 117     node_templates:
 118       VNF1:
 119         type: tosca.nodes.nfv.VNF
 120         properties:
 121           id: vnf1
 122           vendor: acmetelco
 123           version: 1.0
 124       VNF2:
 125         type: tosca.nodes.nfv.VNF
 126         properties:
 127           id: vnf2
 128           vendor: ericsson
 129           version: 1.0
 130       VNF3:
 131         type: tosca.nodes.nfv.VNF
 132         properties:
 133           id: vnf3
 134           vendor: huawei
 135           version: 1.0
 136     policies:
 137       - rule1:
 138           type: tosca.policies.Placement.Geolocation
 139           targets: [ VNF1 ]
 140           properties:
 141             region: [ us-west-1 ]
 142       - rule2:
 143           type: tosca.policies.Placement.Geolocation
 144           targets: [ VNF2, VNF3 ]
 145           properties:
 146             region: [ us-west-1 , us-west-2 ]
 147
 148 Domino Server extracts all possible policy labels by exhaustively concatenating key-value
 149 pairs under the properties section of the policy rules to the policy type of these rules:
 150
 151 .. code-block:: bash
 152
 153   tosca.policies.Placement.Geolocation:properties:region:us-west-1
 154   tosca.policies.Placement.Geolocation:properties:region:us-west-2
 155
 156 Furthermore, Domino Server iterates over the targets specified under policy rules to generate a set of labels for each target node:
 157
 158 .. code-block:: bash
 159
 160   required_labels['VNF1'] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 }
 161   required_labels['VNF2'] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 , tosca.policies.Placement.Geolocation:properties:region:us-west-2}
 162   required_labels['VNF3'] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 , tosca.policies.Placement.Geolocation:properties:region:us-west-2}
 163
 164 When a Template Consuming site (e.g., VNFM or VIM) registers with the Domino Server using
 165 Domino Client, it becomes an eligible candidate for template distribution with an initially
 166 empty set of label subscriptions. Suppose three different Domino Clients register with the
 167 Domino Server and subscribe for some or none of the policy labels such that the Domino Server
 168 has the current subscription state as follows:
 169
 170 .. code-block:: bash
 171
 172   subscribed_labels[site-1] = { } #this is empty set
 173   subscribed_labels[site-2] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 }
 174   subscribed_labels[site-3] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 ,  tosca.policies.Placement.Geolocation:properties:region:us-west-2}
 175
 176
 177 Based on the TOSCA example and hypothetical label subscriptions above, Domino Server identifies
 178 all the VNFs can be hosted by Site-3, while VNF1 can be hosted by both Site-2 and Site-3.
 179 Note that Site-1 cannot host any of the VNFs listed in the TOSCA file. When a VNF can be hosted
 180 by multiple sites, Domino Server picks the site that can host the most number of VNFs. When not
 181 all VNFs can be hosted on the same site, the TOSCA file is partitioned into multiple files, one
 182 for each site. These files share a common part (e.g, meta-data, policy-types, version,
 183 description, etc.) and non-common parts (e.g., VNFs not mapped onto a specific domain and their
 184 dependents are excluded from topology description and policy targets). In the current Domino
 185 convention, if a VNF (or any node) does not have a policy rule (i.e., it is not specified as a
 186 target in any of the policy rules), that resource is wild carded by default and treated as part
 187 of the "common part".  For the example above, no partitioning would occur as all VNFs are
 188 mapped onto site-3; Domino Server simply delivers the Tosca file to Domino Client hosted on
 189 site-3. When TOSCA cannot be consumed by a particular site directly, Domino Server can utilize
 190 existing translators (e.g., heat-translator) to first translate the template before delivery.
 191
 192 Typical Message Flow
 193 --------------------
 194
 195 Internal Pipeline
 196 -----------------