From 735b8680ee2e546bbaceb9ffb4ae8db043779516 Mon Sep 17 00:00:00 2001 From: Ulas Kozat Date: Thu, 16 Feb 2017 11:17:14 -0800 Subject: JIRA DOMINO-23 new directory structure new API description split documents Change-Id: Iedffd5266c19f9713930011ef8fde7e55fd3ae66 Signed-off-by: Ulas Kozat --- docs/development/overview/feature.overview.rst | 237 +++++++++++++ docs/development/overview/index.rst | 11 + docs/installationprocedure/featureconfig.rst | 40 --- docs/installationprocedure/index.rst | 21 -- .../installation.instructions.rst | 57 --- docs/release/installation/featureconfig.rst | 40 +++ docs/release/installation/index.rst | 21 ++ .../installation/installation.instructions.rst | 50 +++ docs/release/userguide/feature.userguide.rst | 177 ++++++++++ docs/release/userguide/index.rst | 11 + docs/userguide/api-documentation.rst | 169 --------- docs/userguide/feature.userguide.rst | 393 --------------------- docs/userguide/index.rst | 12 - docs/userguide/overview.rst | 241 ------------- 14 files changed, 547 insertions(+), 933 deletions(-) create mode 100644 docs/development/overview/feature.overview.rst create mode 100644 docs/development/overview/index.rst delete mode 100644 docs/installationprocedure/featureconfig.rst delete mode 100644 docs/installationprocedure/index.rst delete mode 100644 docs/installationprocedure/installation.instructions.rst create mode 100644 docs/release/installation/featureconfig.rst create mode 100644 docs/release/installation/index.rst create mode 100644 docs/release/installation/installation.instructions.rst create mode 100644 docs/release/userguide/feature.userguide.rst create mode 100644 docs/release/userguide/index.rst delete mode 100755 docs/userguide/api-documentation.rst delete mode 100644 docs/userguide/feature.userguide.rst delete mode 100644 docs/userguide/index.rst delete mode 100644 docs/userguide/overview.rst diff --git a/docs/development/overview/feature.overview.rst b/docs/development/overview/feature.overview.rst new file mode 100644 index 0000000..4ef8d16 --- /dev/null +++ b/docs/development/overview/feature.overview.rst @@ -0,0 +1,237 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +================== +Domino Description +================== + +Domino provides a distribution service for Network Service Descriptors (NSDs) and +Virtual Network Function Descriptors (VNFDs) that are composed using Tosca Simple +Profile for Network Functions Virtualization +(http://docs.oasis-open.org/tosca/tosca-nfv/v1.0/tosca-nfv-v1.0.html). +Domino service is targeted towards supporting many Software Defined Network (SDN) controllers, +Service Orchestrators (SOs), VNF Managers (VNFMs), Virtual Infastructure Managers (VIMs), +Operation and Business Support Systems that produce and/or consume NSDs and VNFDs. + +Producers of NSDs and VNFDs use Domino Service through Service Access Points (SAPs) or End Points (EPs) +to publish these descriptors. Consumers of NSDs and VNFDs subscribe with the Domino Service through +the same SAPs/EPs and declare their resource capabilities to onboard and perform Life Cycle Management +(LCM) for Network Services (NSs) and Virtual Network Functions (VNFs). Thus, Domino acts as a service +broker for NSs and VNFs modeled in a Tosca template. + +============================= +Domino Capabilities and Usage +============================= + +Labels in Domino +================ + +Domino's pub/sub architecture is based on labels (see Fig. 1 below). +Each Template Producer and Template Consumer is expected to run a local Domino Client +to publish templates and subscribe for labels. + +.. _fig-label: + +.. figure:: ../../etc/domino_pubsub_system.jpeg + :width: 350px + :align: center + :height: 300px + :alt: alternate text + :figclass: align-center + + Domino provides a pub/sub server for NSDs and VNFDs + +Domino Service does not interpret what the labels mean. Domino derives labels directly from +the normative definitions in TOSCA Simple YAML Profile for NFV. Domino parses the policy +rules included in the NSD/VNFD, form "policy" labels, and determine which resources are +associated with which set of labels. Domino identifies which Domino Clients can host +which resource based on the label subscriptions by these clients. Once mapping of resources +to the clients are done, new NSDs/VNFDs are created based on the mapping. These new +NSDs/VNFDs are translated and delivered to the clients. + +Label Format and Examples +========================= + +Domino supports policy labels in the following form: + +.. code-block:: bash + + :properties: + +Orchestrators, controllers, and managers use Domino service to announce their +capabilities by defining labels in this form and subscribing for these labels with +the Domino Server. + +For instance a particular VIM that is capable of performing an +affinity based VNF or VDU placement at host machine granularity can specify a label +in the form: + +.. code-block:: bash + + tosca.policies.Placement.affinity:properties:granularity:hostlevel + +When the VIM registers with the Domino Service and subscribed for that label, Domino views +this VIM as a candidate location that can host a VNF or VDU requesting affinity based +placement policy at host machine granularity. + +Another use case is the announcement of lifecycle management capabilities for VNFs and +VNF Forwarding Graphs (VNFFG) by different SDN Controllers (SDN-Cs), VNFMs, or VIMs. +For instance + +.. code-block:: bash + + tosca.policies.Scaling.VNFFG:properties:session_continuity:true + +can be used as a label to indicate that when a scaling operation on a VNFFG (e.g., add +more VNFs into the graph) is requested, existing session can still be enforced to go +through the same chain of VNF instances. + +To utilize Domino's domain mapping services for virtual network resources (e.g., VNF, VDU, +VNFFG, CP, VL, etc.), a network service or network function request must include +policy rules that are composed of policy types and property values that match to the +label announcements made by these domains. For instance, when a TOSCA template includes a +policy rule with type "tosca.policies.Scaling.VNFFG" and property field +"session_continuity" set as "true" targeting one or more VNFFGs, this serves as the hint +for the Domino Server to identify all the Domain Clients that subscribed the label +"tosca.policies.Scaling.VNFFG:properties:session_continuity:true". + +Template Example for Label Extraction +===================================== + +Consider the following NSD TOSCA template: + +.. code-block:: bash + + tosca_definitions_version: tosca_simple_profile_for_nfv_1_0_0 + description: Template for deploying a single server with predefined properties. + metadata: + template_name: TOSCA NFV Sample Template + policy_types: + tosca.policies.Placement.Geolocation: + description: Geolocation policy + derived_from: tosca.policies.Placement + topology_template: + node_templates: + VNF1: + type: tosca.nodes.nfv.VNF + properties: + id: vnf1 + vendor: acmetelco + version: 1.0 + VNF2: + type: tosca.nodes.nfv.VNF + properties: + id: vnf2 + vendor: ericsson + version: 1.0 + VNF3: + type: tosca.nodes.nfv.VNF + properties: + id: vnf3 + vendor: huawei + version: 1.0 + policies: + - rule1: + type: tosca.policies.Placement.Geolocation + targets: [ VNF1 ] + properties: + region: [ us-west-1 ] + - rule2: + type: tosca.policies.Placement.Geolocation + targets: [ VNF2, VNF3 ] + properties: + region: [ us-west-1 , us-west-2 ] + +Domino Server extracts all possible policy labels by exhaustively concatenating key-value +pairs under the properties section of the policy rules to the policy type of these rules: + +.. code-block:: bash + + tosca.policies.Placement.Geolocation:properties:region:us-west-1 + tosca.policies.Placement.Geolocation:properties:region:us-west-2 + +Furthermore, Domino Server iterates over the targets specified under policy rules to generate a set of labels for each target node: + +.. code-block:: bash + + required_labels['VNF1'] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 } + required_labels['VNF2'] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 , tosca.policies.Placement.Geolocation:properties:region:us-west-2} + required_labels['VNF3'] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 , tosca.policies.Placement.Geolocation:properties:region:us-west-2} + +When a Template Consuming site (e.g., VNFM or VIM) registers with the Domino Server using +Domino Client, it becomes an eligible candidate for template distribution with an initially +empty set of label subscriptions. Suppose three different Domino Clients register with the +Domino Server and subscribe for some or none of the policy labels such that the Domino Server +has the current subscription state as follows: + +.. code-block:: bash + + subscribed_labels[site-1] = { } #this is empty set + subscribed_labels[site-2] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 } + subscribed_labels[site-3] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 , tosca.policies.Placement.Geolocation:properties:region:us-west-2} + + +Based on the TOSCA example and hypothetical label subscriptions above, Domino Server identifies +all the VNFs can be hosted by Site-3, while VNF1 can be hosted by both Site-2 and Site-3. +Note that Site-1 cannot host any of the VNFs listed in the TOSCA file. When a VNF can be hosted +by multiple sites, Domino Server picks the site that can host the most number of VNFs. When not +all VNFs can be hosted on the same site, the TOSCA file is partitioned into multiple files, one +for each site. These files share a common part (e.g, meta-data, policy-types, version, +description, virtual resources that are not targeted by any policy rule, etc.). Each site +specific file has also a non-common part that only appears in that file (i.e., virtual +resources explicitly assigned to that site and the policy rules that accompany those virtual +resources. + +In the current Domino convention, if a VNF (or any virtual resource) does not have a policy +rule (i.e., it is not specified as a target in any of the policy rules) and it also is not +dependent on any VNF (or any virtual resource) that is assigned to another site, that resource +is wild carded by default and treated as part of the "common part". Also note that currently +Domino does not support all or nothing semantics: if some of the virtual resources are not +mappable to any domain because they are targets of policy rules that are not supported by any +site, these portions will be excluded while the remaining virtual resources will be still be +part of one or more template files to be distributed to hosting sites. When NSDs and VNFDs are +prepared, these conventions must be kept in mind. In the future releases, these conventions can +change based on the new use cases. + +For the example above, no partitioning would occur as all VNFs are mapped onto site-3; +Domino Server simply delivers the Tosca file to Domino Client hosted on site-3. When TOSCA +cannot be consumed by a particular site directly, Domino Server can utilize +existing translators (e.g., heat-translator) to first translate the template before delivery. + +Internal Processing Pipeline at Domino Server +============================================= + +Fig. 2 shows the block diagram for the processing stages of a published TOSCA template. +Domino Client issues an RPC call publish(tosca file). Domino Server passes the received tosca +file to Label Extractor that outputs resource labels. Domain Mapper uses the extracted labels +and tosca file to find mappings from resources to domains as well as the resource dependencies. +Resource to domain mappings and resource dependencies are utilized to partition the +orchestration template into individual resource orchestration templates (one for each domain). +If a translation is required (e.g., TOSCA to HOT), individual resource orchestration templates +are first translated and then placed on a template distribution workflow based on resource +dependencies. Message Sender block in the server takes one distribution task at a time from the +workflow generator and pushes the orchestration template to the corresponding Domino Client. + +.. _fig-pipe: + +.. figure:: ../../etc/domino_server_processing.png + :width: 400px + :align: center + :height: 350px + :alt: alternate text + :figclass: align-center + + Domino Service Processing Pipeline + +Resource Scheduling +=================== + +Domino Service currently supports maximum packing strategy when a virtual resource type can +be hosted on multiple candidate sites. Initially, Domino Scheduler identifies virtual resources +that has only one feasible site for hosting. Each such virtual resource is trivially assigned +to its only feasible site. The remaining virtual resources with multiple candidate locations +are sequentially allocated to one of their candidate locations that has the most virtual +resource assignments so far. Note that wildcarded resources are assigned to all sites. To +prevent wildcarding within the current release, (i) all sites must subscribed to a base policy +with a dummy key-value pair defined under the properties tab and (ii) all the independent +resources must be specified as target of that policy in NSD or VNFD file. diff --git a/docs/development/overview/index.rst b/docs/development/overview/index.rst new file mode 100644 index 0000000..e38a573 --- /dev/null +++ b/docs/development/overview/index.rst @@ -0,0 +1,11 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +***************** +Domino User Guide +***************** + +.. toctree:: + :maxdepth: 3 + + feature.overview.rst diff --git a/docs/installationprocedure/featureconfig.rst b/docs/installationprocedure/featureconfig.rst deleted file mode 100644 index 5364dbe..0000000 --- a/docs/installationprocedure/featureconfig.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -.. image:: ../etc/opnfv-logo.png - :height: 40 - :width: 200 - :alt: OPNFV - :align: left -.. these two pipes are to seperate the logo from the first title -| -| -Domino Configuration -==================== -Domino Server and Clients can be configured via (i) passing command line options -(see API documentation) and (ii) the configuration file "domino_conf.py" under the -main directory. - -* The default file for logging is set as none and log level set as "WARNING". - -Domino Server -------------- -* The default server unique user ID is set as 0 in the configuration file. - -* The default TCP port for RPC calls is set as 9090 in the configuration file. - -* The default database file for Domino Server is set as "dominoserver.db" under the main directory - -* The default folder for keeping published TOSCA files and pushed parts is set as "toscafiles" in the configuration file via variable TOSCADIR. - -Domino Client -------------- -* The default mode of CLI is non-interactive (i.e., Domino CLI Utility is used). This can be changed when the DominoClient is launched by passing the flags --log or -l followed by the -log level choice from the set {ERROR, WARNING, INFO, DEBUG} (not case sensitive). This overwrites the log level default specified in the configuration file. - -* The default Domino Server IP is set as "localhost". This can be overwritten at the time of launching DominoClient via the option flags -i or --ipaddr followed by the IP address of the actual server hosting the Domino Server. - -* The default Domino Client TCP port for RPC calls is set as 9091 in the configuration file. It can be overwritten when the DominoClient is launched by passing the flags --port or -p followed by the port number. - -* The default folder for keeping preceived TOSCA files is set as "toscafiles" in the configuration file via variable TOSCA_RX_DIR. - diff --git a/docs/installationprocedure/index.rst b/docs/installationprocedure/index.rst deleted file mode 100644 index f77c38a..0000000 --- a/docs/installationprocedure/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -.. image:: ../etc/opnfv-logo.png - :height: 40 - :width: 200 - :alt: OPNFV - :align: left -| -| -********************** -Installation procedure -********************** -Colorado 1.0 ------------- - -.. toctree:: - :maxdepth: 2 - - installation.instructions.rst - featureconfig.rst diff --git a/docs/installationprocedure/installation.instructions.rst b/docs/installationprocedure/installation.instructions.rst deleted file mode 100644 index 790a5f0..0000000 --- a/docs/installationprocedure/installation.instructions.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -.. image:: ../etc/opnfv-logo.png - :height: 40 - :width: 200 - :alt: OPNFV - :align: left -.. these two pipes are to seperate the logo from the first title -| -| -Domino Installation -=================== - -Note: The steps below are tested for Ubuntu (16.04, 14.04) and OS X El Capitan. - -Prerequisites -------------- -* git -* python-pip -* python (version =2.7) -* tosca-parser (version >=0.4.0) -* heat-translator (version >=0.5.0) - -Installation Steps (Single Node) --------------------------------- - -* Step-0: Prepare Environment - -.. code-block:: bash - - > $sudo pip install tosca-parser - > $sudo pip install heat-translator - > $sudo pip install requests - -* Step-1: Get the Domino code - -.. code-block:: bash - - git clone https://gerrit.opnfv.org/gerrit/domino -b stable/colorado - -* Step-2: Go to the main domino directory - -.. code-block:: bash - - cd domino - -You should see DominoClient.py, DominoServer.py, and domino-cli.py as executables. - -Installation Steps (Multiple Node) ----------------------------------- - -Repeat the installation steps for single node on each node. The script -run_multinode.sh under ./domino/tests directory deploys the Domino Code on three -hosts from a deployment node and tests RPC calls. The private key location and -remote host IP addresses must be manually entered and IS_IPandKEY_CONFIGURED=false -must be changed to IS_IPandKEY_CONFIGURED=true. diff --git a/docs/release/installation/featureconfig.rst b/docs/release/installation/featureconfig.rst new file mode 100644 index 0000000..5364dbe --- /dev/null +++ b/docs/release/installation/featureconfig.rst @@ -0,0 +1,40 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +.. image:: ../etc/opnfv-logo.png + :height: 40 + :width: 200 + :alt: OPNFV + :align: left +.. these two pipes are to seperate the logo from the first title +| +| +Domino Configuration +==================== +Domino Server and Clients can be configured via (i) passing command line options +(see API documentation) and (ii) the configuration file "domino_conf.py" under the +main directory. + +* The default file for logging is set as none and log level set as "WARNING". + +Domino Server +------------- +* The default server unique user ID is set as 0 in the configuration file. + +* The default TCP port for RPC calls is set as 9090 in the configuration file. + +* The default database file for Domino Server is set as "dominoserver.db" under the main directory + +* The default folder for keeping published TOSCA files and pushed parts is set as "toscafiles" in the configuration file via variable TOSCADIR. + +Domino Client +------------- +* The default mode of CLI is non-interactive (i.e., Domino CLI Utility is used). This can be changed when the DominoClient is launched by passing the flags --log or -l followed by the +log level choice from the set {ERROR, WARNING, INFO, DEBUG} (not case sensitive). This overwrites the log level default specified in the configuration file. + +* The default Domino Server IP is set as "localhost". This can be overwritten at the time of launching DominoClient via the option flags -i or --ipaddr followed by the IP address of the actual server hosting the Domino Server. + +* The default Domino Client TCP port for RPC calls is set as 9091 in the configuration file. It can be overwritten when the DominoClient is launched by passing the flags --port or -p followed by the port number. + +* The default folder for keeping preceived TOSCA files is set as "toscafiles" in the configuration file via variable TOSCA_RX_DIR. + diff --git a/docs/release/installation/index.rst b/docs/release/installation/index.rst new file mode 100644 index 0000000..f77c38a --- /dev/null +++ b/docs/release/installation/index.rst @@ -0,0 +1,21 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +.. image:: ../etc/opnfv-logo.png + :height: 40 + :width: 200 + :alt: OPNFV + :align: left +| +| +********************** +Installation procedure +********************** +Colorado 1.0 +------------ + +.. toctree:: + :maxdepth: 2 + + installation.instructions.rst + featureconfig.rst diff --git a/docs/release/installation/installation.instructions.rst b/docs/release/installation/installation.instructions.rst new file mode 100644 index 0000000..4e18491 --- /dev/null +++ b/docs/release/installation/installation.instructions.rst @@ -0,0 +1,50 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +=================== +Domino Installation +=================== + +Note: The steps below are tested for Ubuntu (16.04, 14.04) and OS X El Capitan. + +Prerequisites +------------- +* git +* python-pip +* python (version =2.7) +* tosca-parser (version >=0.4.0) +* heat-translator (version >=0.5.0) + +Installation Steps (Single Node) +-------------------------------- + +* Step-0: Prepare Environment + +.. code-block:: bash + + > $sudo pip install tosca-parser + > $sudo pip install heat-translator + > $sudo pip install requests + +* Step-1: Get the Domino code + +.. code-block:: bash + + git clone https://gerrit.opnfv.org/gerrit/domino -b stable/danube + +* Step-2: Go to the main domino directory + +.. code-block:: bash + + cd domino + +You should see DominoClient.py, DominoServer.py, and domino-cli.py as executables. + +Installation Steps (Multiple Node) +---------------------------------- + +Repeat the installation steps for single node on each node. The script +run_multinode.sh under ./domino/tests directory deploys the Domino Code on three +hosts from a deployment node and tests RPC calls. The private key location and +remote host IP addresses must be manually entered and IS_IPandKEY_CONFIGURED=false +must be changed to IS_IPandKEY_CONFIGURED=true. diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst new file mode 100644 index 0000000..920c2ec --- /dev/null +++ b/docs/release/userguide/feature.userguide.rst @@ -0,0 +1,177 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +============================================ +Domino and API Usage Guidelines and Examples +============================================ + +Using domino-cli Client +======================= + +Prerequisites: + +1. Make sure that domino-cli.py is in +x mode. + +2. Change directory to where domino-cli.py, DominoClient.py and DominoServer.py are located or include file path in the PATH environment variable. + +3. Start the Domino Server: + +.. code-block:: bash + + ./DominoServer.py --log=debug + +4. Start the Domino Client: + +.. code-block:: bash + + ./DominoClient.py -p --cliport --log=debug + +Note1: The default log level is WARNING and omitting --log option will lead to minimal/no logging on the console + +Note2: domino_conf.py file includes most of the default values + +* Registration Command + +Command line input: + +.. code-block:: bash + + ./domino-cli.py register + +This message has the following fields that are automatically filled in. + +.. code-block:: bash + + Message Type (= REGISTER) + DESIRED UDID (= if not allocated, this will be assigned as Unique Domino ID) + Sequence Number (=incremented after each RPC call) + IP ADDR (= IP address of DOMINO Client to be used by DOMINO Server for future RPC Calls to this client) + TCP PORT (= TCP port of DOMINO Client to be used by DOMINO Server for future RPC Calls to this client) + Supported Templates (= Null, this field not used currently) + +* Heart Beat Command + +Command line input: + +.. code-block:: bash + + ./domino-cli.py heartbeat + +This message has the following fields that are automatically filled in. + +.. code-block:: bash + + Message Type (= HEART_BEAT) + UDID (= Unique Domino ID assigned during registration) + Sequence Number (=incremented after each RPC call) + +* Label and Template Type Subscription Command + +.. code-block:: bash + + ./domino-cli.py subscribe -l -t + +Note that -l can be substituted by --label and -t can be substituted by --ttype. + +More than one label or template type can be subscribed within the same command line as comma separated labels or template types + +.. code-block:: bash + + ./domino-cli.py subscribe -l ,, -t ,, + +To subscribe more than one label or template type, one can also repeat the options -l and -t, e.g.: + +.. code-block:: bash + + ./domino-cli.py subscribe -l -l -l -t -t -t + +It is safe to call subscribe command multiple times with duplicate labels. + +This message has the following fields that are automatically filled in. + +.. code-block:: bash + + Message Type (= SUBSCRIBE) + UDID (= Unique Domino ID assigned during registration) + Sequence Number (=incremented after each RPC call) + Template Operation (= APPEND) + Label Operation (= APPEND) + +The following fields are filled in based on arguments passed on via -l/--label and -t/--ttype flags + +Subscribe RPC also supports options for label using + --lop=APPEND/DELETE/OVERWRITE +and for supported template types using + --top=APPEND/DELETE/OVERWRITE. +When unspecified, the default is APPEND. +DELETE deletes existing labels (template types) specified in the current call via key -l/--label (-t/--ttype). +OVERWRITE removes the current set of labels (template types) and sets it to the new set of values passed in the same RPC call. + +By default, no translation service is provided. Currently, only TOSCA to Heat +Orchestration Template (HOT) translation is supported using OpenStack +heat-translator library. A domain that requires HOT files must subscribe HOT +template type using + +.. code-block:: bash + + ./domino-cli.py subscribe -t hot + +* Template Publishing Command + +.. code-block:: bash + + ./domino-cli.py publish -t + +Note that -t can be substituted with --tosca-file. + +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. + +This message has the following fields that are automatically filled in. + +.. code-block:: bash + + Message Type (= PUBLISH) + UDID (= Unique Domino ID assigned during registration) + Sequence Number (=incremented after each RPC call) + Template Type (= TOSCA) + Template File + +Since Danube release, Domino Server supports stateful updates for template publishing. The following command can be used to update the service template for an existing Template Unique ID (TUID): + +.. code-block:: bash + + ./domino-cli.py publish -t -k + +Note that -k can be substituted with --tuid. When Domino Server receives this command, it verifies whether +the client previously published the provided TUID. If such TUID does not exist, then Domino Server returns +FAILED response back to the client. If such TUID exists, Domino Server recomputes which resources are +mapped onto which domains and updates each domain with the new VNF and NS descriptors. If a previously +utilized domain is no longer targeted, it is updated with a null descriptor. + +* Template Listing Command + +.. code-block:: bash + + ./domino-cli.py list-tuids + +Queries all the Template Unique IDs (TUIDs) published by the Domino Client from the Domino Server. + +Interactive CLI mode +-------------------- + +To enter this mode, start Domino Client with interactive console option set as true, i.e., --iac=true: + +.. code-block:: bash + + ./DominoClient -p --iax=true --log=DEBUG + +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 , e.g.,: + +.. code-block:: bash + + >>register + >>heartbeat + >>subscribe -l -t + >>publish -t + +The interactive CLI mode is mainly supported for manual testing. diff --git a/docs/release/userguide/index.rst b/docs/release/userguide/index.rst new file mode 100644 index 0000000..2092cf7 --- /dev/null +++ b/docs/release/userguide/index.rst @@ -0,0 +1,11 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +***************** +Domino User Guide +***************** + +.. toctree:: + :maxdepth: 3 + + feature.userguide.rst diff --git a/docs/userguide/api-documentation.rst b/docs/userguide/api-documentation.rst deleted file mode 100755 index 166da6a..0000000 --- a/docs/userguide/api-documentation.rst +++ /dev/null @@ -1,169 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -.. image:: ../etc/opnfv-logo.png - :height: 40 - :width: 200 - :alt: OPNFV - :align: left -.. these two pipes are to seperate the logo from the first title -| -| -Domino API and Usage -==================== - -Using domino-cli Client ------------------------ - -Prerequisites: - -1. Make sure that domino-cli.py is in +x mode. - -2. Change directory to where domino-cli.py, DominoClient.py and DominoServer.py are located or include file path in the PATH environment variable. - -3. Start the Domino Server: - -.. code-block:: bash - - ./DominoServer.py --log=debug - -4. Start the Domino Client: - -.. code-block:: bash - - ./DominoClient.py -p --cliport --log=debug - -Note1: The default log level is WARNING and omitting --log option will lead to minimal/no logging on the console - -Note2: domino_conf.py file includes most of the default values - -* Registration Command - -Command line input: - -.. code-block:: bash - - ./domino-cli.py register - -This message has the following fields that are automatically filled in. - -.. code-block:: bash - - Message Type (= REGISTER) - DESIRED UDID (= if not allocated, this will be assigned as Unique Domino ID) - Sequence Number (=incremented after each RPC call) - IP ADDR (= IP address of DOMINO Client to be used by DOMINO Server for future RPC Calls to this client) - TCP PORT (= TCP port of DOMINO Client to be used by DOMINO Server for future RPC Calls to this client) - Supported Templates (= Null, this field not used currently) - -* Heart Beat Command - -Command line input: - -.. code-block:: bash - - ./domino-cli.py heartbeat - -This message has the following fields that are automatically filled in. - -.. code-block:: bash - - Message Type (= HEART_BEAT) - UDID (= Unique Domino ID assigned during registration) - Sequence Number (=incremented after each RPC call) - -* Label and Template Type Subscription Command - -.. code-block:: bash - - ./domino-cli.py subscribe -l -t - -Note that -l can be substituted by --label and -t can be substituted by --ttype. - -More than one label or template type can be subscribed within the same command line as comma separated labels or template types - -.. code-block:: bash - - ./domino-cli.py subscribe -l ,, -t ,, - -To subscribe more than one label or template type, one can also repeat the options -l and -t, e.g.: - -.. code-block:: bash - - ./domino-cli.py subscribe -l -l -l -t -t -t - -It is safe to call subscribe command multiple times with duplicate labels. - -This message has the following fields that are automatically filled in. - -.. code-block:: bash - - Message Type (= SUBSCRIBE) - UDID (= Unique Domino ID assigned during registration) - Sequence Number (=incremented after each RPC call) - Template Operation (= APPEND) - Label Operation (= APPEND) - -The following fields are filled in based on arguments passed on via -l/--label and -t/--ttype flags - -Subscribe RPC also supports options for label using - --lop=APPEND/DELETE/OVERWRITE -and for supported template types using - --top=APPEND/DELETE/OVERWRITE. -When unspecified, the default is APPEND. -DELETE deletes existing labels (template types) specified in the current call via key -l/--label (-t/--ttype). -OVERWRITE removes the current set of labels (template types) and sets it to the new set of values passed in the same RPC call. - -By default, no translation service is provided. Currently, only TOSCA to Heat -Orchestration Template (HOT) translation is supported using OpenStack -heat-translator library. A domain that requires HOT files must subscribe HOT -template type using - -.. code-block:: bash - - ./domino-cli.py subscribe -t hot - -* Template Publishing Command - -.. code-block:: bash - - ./domino-cli.py publish -t - -Note that -t can be substituted by --tosca-file. - -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. - -This message has the following fields that are automatically filled in. - -.. code-block:: bash - - Message Type (= SUBSCRIBE) - UDID (= Unique Domino ID assigned during registration) - Sequence Number (=incremented after each RPC call) - Template Type (= TOSCA) - Template File - - -Interactive CLI mode --------------------- - -To enter this mode, start Domino Client with interactive console option set as true, i.e., --iac=true: - -.. code-block:: bash - - ./DominoClient -p --iax=true --log=DEBUG - -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 , e.g.,: - -.. code-block:: bash - - >>register - >>heartbeat - >>subscribe -l -t - >>publish -t - -The interactive CLI mode is mainly supported for manual testing. - -Revision: _sha1_ - -Build date: |today| diff --git a/docs/userguide/feature.userguide.rst b/docs/userguide/feature.userguide.rst deleted file mode 100644 index 664553d..0000000 --- a/docs/userguide/feature.userguide.rst +++ /dev/null @@ -1,393 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. (c) Ulas C. Kozat Huawei R&D USA - -================== -Domino Description -================== - -Domino provides a distribution service for Network Service Descriptors (NSDs) and -Virtual Network Function Descriptors (VNFDs) that are composed using Tosca Simple -Profile for Network Functions Virtualization -(http://docs.oasis-open.org/tosca/tosca-nfv/v1.0/tosca-nfv-v1.0.html). -Domino service is targeted towards supporting many SDN controllers, service orchestrators, -VNF Managers (VNFMs), Virtual Infastructure Managers (VIMs), Operation and Business Support -Systems that produce and/or consume NSDs and VNFDs. - -Producers of NSDs and VNFDs use Domino Service as an entry point to publish these -descriptors. Consumers of NSDs and VNFDs subscribe with the Domino Service and declare -their resource capabilities to onboard and perform Life Cycle Management (LCM) for Network -Services (NSs) and Virtual Network Functions (VNFs). Thus, Domino acts as a broker for -NSs and VNFs described in a Tosca template. - -============================= -Domino Capabilities and Usage -============================= - -Labels in Domino -================ - -Domino's pub/sub architecture is based on labels (see Fig. 1 below). -Each Template Producer and Template Consumer is expected to run a local Domino Client -to publish templates and subscribe for labels. - -.. _fig-label: - -.. figure:: ../etc/domino_pubsub_system.jpeg - :width: 350px - :align: center - :height: 300px - :alt: alternate text - :figclass: align-center - - Domino provides a pub/sub server for NSDs and VNFDs - -Domino Service does not interpret what the labels mean. Domino derives labels directly from -the normative definitions in TOSCA Simple YAML Profile for NFV. Domino parses the policy -rules included in the NSD/VNFD, form "policy" labels, and determine which resources are -associated with which set of labels. Domino identifies which Domino Clients can host -which resource based on the label subscriptions by these clients. Once mapping of resources -to the clients are done, new NSDs/VNFDs are created based on the mapping. These new -NSDs/VNFDs are translated and delivered to the clients. - -Label Format and Examples -========================= - -Domino supports policy labels in the following form: - -.. code-block:: bash - - :properties: - -Orchestrators, controllers, and managers use Domino service to announce their -capabilities by defining labels in this form and subscribing for these labels with -the Domino Server. - -For instance a particular VIM that is capable of performing an -affinity based VNF or VDU placement at host machine granularity can specify a label -in the form: - -.. code-block:: bash - - tosca.policies.Placement.affinity:properties:granularity:hostlevel - -When the VIM registers with the Domino Service and subscribed for that label, Domino views -this VIM as a candidate location that can host a VNF or VDU requesting affinity based -placement policy at host machine granularity. - -Another use case is the announcement of lifecycle management capabilities for VNFs and -VNF Forwarding Graphs (VNFFG) by different SDN Controllers (SDN-Cs), VNFMs, or VIMs. -For instance - -.. code-block:: bash - - tosca.policies.Scaling.VNFFG:properties:session_continuity:true - -can be used as a label to indicate that when a scaling operation on a VNFFG (e.g., add -more VNFs into the graph) is requested, existing session can still be enforced to go -through the same chain of VNF instances. - -To utilize Domino's domain mapping services for virtual network resources (e.g., VNF, VDU, -VNFFG, CP, VL, etc.), a network service or network function request must include -policy rules that are composed of policy types and property values that match to the -label announcements of these domains. For instance, when a TOSCA template includes a -policy rule with type "tosca.policies.Scaling.VNFFG" and property field -"session_continuity" set as "true" targeting one or more VNFFGs, this serves as the hint -for the Domino Server to identify all the Domain Clients that subscribed the label -"tosca.policies.Scaling.VNFFG:properties:session_continuity:true". - -Template Example for Label Extraction -===================================== - -Consider the following NSD TOSCA template: - -.. code-block:: bash - - tosca_definitions_version: tosca_simple_profile_for_nfv_1_0_0 - description: Template for deploying a single server with predefined properties. - metadata: - template_name: TOSCA NFV Sample Template - policy_types: - tosca.policies.Placement.Geolocation: - description: Geolocation policy - derived_from: tosca.policies.Placement - topology_template: - node_templates: - VNF1: - type: tosca.nodes.nfv.VNF - properties: - id: vnf1 - vendor: acmetelco - version: 1.0 - VNF2: - type: tosca.nodes.nfv.VNF - properties: - id: vnf2 - vendor: ericsson - version: 1.0 - VNF3: - type: tosca.nodes.nfv.VNF - properties: - id: vnf3 - vendor: huawei - version: 1.0 - policies: - - rule1: - type: tosca.policies.Placement.Geolocation - targets: [ VNF1 ] - properties: - region: [ us-west-1 ] - - rule2: - type: tosca.policies.Placement.Geolocation - targets: [ VNF2, VNF3 ] - properties: - region: [ us-west-1 , us-west-2 ] - -Domino Server extracts all possible policy labels by exhaustively concatenating key-value -pairs under the properties section of the policy rules to the policy type of these rules: - -.. code-block:: bash - - tosca.policies.Placement.Geolocation:properties:region:us-west-1 - tosca.policies.Placement.Geolocation:properties:region:us-west-2 - -Furthermore, Domino Server iterates over the targets specified under policy rules to generate a set of labels for each target node: - -.. code-block:: bash - - required_labels['VNF1'] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 } - required_labels['VNF2'] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 , tosca.policies.Placement.Geolocation:properties:region:us-west-2} - required_labels['VNF3'] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 , tosca.policies.Placement.Geolocation:properties:region:us-west-2} - -When a Template Consuming site (e.g., VNFM or VIM) registers with the Domino Server using -Domino Client, it becomes an eligible candidate for template distribution with an initially -empty set of label subscriptions. Suppose three different Domino Clients register with the -Domino Server and subscribe for some or none of the policy labels such that the Domino Server -has the current subscription state as follows: - -.. code-block:: bash - - subscribed_labels[site-1] = { } #this is empty set - subscribed_labels[site-2] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 } - subscribed_labels[site-3] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 , tosca.policies.Placement.Geolocation:properties:region:us-west-2} - - -Based on the TOSCA example and hypothetical label subscriptions above, Domino Server identifies -all the VNFs can be hosted by Site-3, while VNF1 can be hosted by both Site-2 and Site-3. -Note that Site-1 cannot host any of the VNFs listed in the TOSCA file. When a VNF can be hosted -by multiple sites, Domino Server picks the site that can host the most number of VNFs. When not -all VNFs can be hosted on the same site, the TOSCA file is partitioned into multiple files, one -for each site. These files share a common part (e.g, meta-data, policy-types, version, -description, virtual resources that are not targeted by any policy rule, etc.). Each site -specific file has also a non-common part that only appears in that file (i.e., virtual -resources explicitly assigned to that site and the policy rules that accompany those virtual -resources. - -In the current Domino convention, if a VNF (or any virtual resource) does not have a policy -rule (i.e., it is not specified as a target in any of the policy rules) and it also is not -dependent on any VNF (or any virtual resource) that is assigned to another site, that resource -is wild carded by default and treated as part of the "common part". Also note that currently -Domino does not support all or nothing semantics: if some of the virtual resources are not -mappable to any domain because they are targets of policy rules that are not supported by any -site, these portions will be excluded while the remaining virtual resources will be still be -part of one or more template files to be distributed to hosting sites. When NSDs and VNFDs are -prepared, these conventions must be kept in mind. In the future releases, these conventions can -change based on the new use cases. - -For the example above, no partitioning would occur as all VNFs are mapped onto site-3; -Domino Server simply delivers the Tosca file to Domino Client hosted on site-3. When TOSCA -cannot be consumed by a particular site directly, Domino Server can utilize -existing translators (e.g., heat-translator) to first translate the template before delivery. - -Internal Processing Pipeline at Domino Server -============================================= - -Fig. 2 shows the block diagram for the processing stages of a published TOSCA template. -Domino Client issues an RPC call publish(tosca file). Domino Server passes the received tosca -file to Label Extractor that outputs resource labels. Domain Mapper uses the extracted labels -and tosca file to find mappings from resources to domains as well as the resource dependencies. -Resource to domain mappings and resource dependencies are utilized to partition the -orchestration template into individual resource orchestration templates (one for each domain). -If a translation is required (e.g., TOSCA to HOT), individual resource orchestration templates -are first translated and then placed on a template distribution workflow based on resource -dependencies. Message Sender block in the server takes one distribution task at a time from the -workflow generator and pushes the orchestration template to the corresponding Domino Client. - -.. _fig-pipe: - -.. figure:: ../etc/domino_server_processing.png - :width: 400px - :align: center - :height: 350px - :alt: alternate text - :figclass: align-center - - Domino Service Processing Pipeline - -Resource Scheduling -=================== - -Domino Service currently supports maximum packing strategy when a virtual resource type can -be hosted on multiple candidate sites. Initially, Domino Scheduler identifies virtual resources -that has only one feasible site for hosting. Each such virtual resource is trivially assigned -to its only feasible site. The remaining virtual resources with multiple candidate locations -are sequentially allocated to one of their candidate locations that has the most virtual -resource assignments so far. Note that wildcarded resources are assigned to all sites. To -prevent wildcarding within the current release, (i) all sites must subscribed to a base policy -with a dummy key-value pair defined under the properties tab and (ii) all the independent -resources must be specified as target of that policy in NSD or VNFD file. - -============================================ -Domino and API Usage Guidelines and Examples -============================================ - -Using domino-cli Client -======================= - -Prerequisites: - -1. Make sure that domino-cli.py is in +x mode. - -2. Change directory to where domino-cli.py, DominoClient.py and DominoServer.py are located or include file path in the PATH environment variable. - -3. Start the Domino Server: - -.. code-block:: bash - - ./DominoServer.py --log=debug - -4. Start the Domino Client: - -.. code-block:: bash - - ./DominoClient.py -p --cliport --log=debug - -Note1: The default log level is WARNING and omitting --log option will lead to minimal/no logging on the console - -Note2: domino_conf.py file includes most of the default values - -* Registration Command - -Command line input: - -.. code-block:: bash - - ./domino-cli.py register - -This message has the following fields that are automatically filled in. - -.. code-block:: bash - - Message Type (= REGISTER) - DESIRED UDID (= if not allocated, this will be assigned as Unique Domino ID) - Sequence Number (=incremented after each RPC call) - IP ADDR (= IP address of DOMINO Client to be used by DOMINO Server for future RPC Calls to this client) - TCP PORT (= TCP port of DOMINO Client to be used by DOMINO Server for future RPC Calls to this client) - Supported Templates (= Null, this field not used currently) - -* Heart Beat Command - -Command line input: - -.. code-block:: bash - - ./domino-cli.py heartbeat - -This message has the following fields that are automatically filled in. - -.. code-block:: bash - - Message Type (= HEART_BEAT) - UDID (= Unique Domino ID assigned during registration) - Sequence Number (=incremented after each RPC call) - -* Label and Template Type Subscription Command - -.. code-block:: bash - - ./domino-cli.py subscribe -l -t - -Note that -l can be substituted by --label and -t can be substituted by --ttype. - -More than one label or template type can be subscribed within the same command line as comma separated labels or template types - -.. code-block:: bash - - ./domino-cli.py subscribe -l ,, -t ,, - -To subscribe more than one label or template type, one can also repeat the options -l and -t, e.g.: - -.. code-block:: bash - - ./domino-cli.py subscribe -l -l -l -t -t -t - -It is safe to call subscribe command multiple times with duplicate labels. - -This message has the following fields that are automatically filled in. - -.. code-block:: bash - - Message Type (= SUBSCRIBE) - UDID (= Unique Domino ID assigned during registration) - Sequence Number (=incremented after each RPC call) - Template Operation (= APPEND) - Label Operation (= APPEND) - -The following fields are filled in based on arguments passed on via -l/--label and -t/--ttype flags - -Subscribe RPC also supports options for label using - --lop=APPEND/DELETE/OVERWRITE -and for supported template types using - --top=APPEND/DELETE/OVERWRITE. -When unspecified, the default is APPEND. -DELETE deletes existing labels (template types) specified in the current call via key -l/--label (-t/--ttype). -OVERWRITE removes the current set of labels (template types) and sets it to the new set of values passed in the same RPC call. - -By default, no translation service is provided. Currently, only TOSCA to Heat -Orchestration Template (HOT) translation is supported using OpenStack -heat-translator library. A domain that requires HOT files must subscribe HOT -template type using - -.. code-block:: bash - - ./domino-cli.py subscribe -t hot - -* Template Publishing Command - -.. code-block:: bash - - ./domino-cli.py publish -t - -Note that -t can be substituted by --tosca-file. - -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. - -This message has the following fields that are automatically filled in. - -.. code-block:: bash - - Message Type (= SUBSCRIBE) - UDID (= Unique Domino ID assigned during registration) - Sequence Number (=incremented after each RPC call) - Template Type (= TOSCA) - Template File - -Interactive CLI mode --------------------- - -To enter this mode, start Domino Client with interactive console option set as true, i.e., --iac=true: - -.. code-block:: bash - - ./DominoClient -p --iax=true --log=DEBUG - -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 , e.g.,: - -.. code-block:: bash - - >>register - >>heartbeat - >>subscribe -l -t - >>publish -t - -The interactive CLI mode is mainly supported for manual testing. diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst deleted file mode 100644 index a9c402b..0000000 --- a/docs/userguide/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. (c) Ulas C. Kozat Huawei R&D USA - -***************** -Domino User Guide -***************** - -.. toctree:: - :maxdepth: 3 - - feature.userguide.rst diff --git a/docs/userguide/overview.rst b/docs/userguide/overview.rst deleted file mode 100644 index b6c6409..0000000 --- a/docs/userguide/overview.rst +++ /dev/null @@ -1,241 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -.. image:: ../etc/opnfv-logo.png - :height: 40 - :width: 200 - :alt: OPNFV - :align: left -.. these two pipes are to seperate the logo from the first title -| -| -Domino Overview -=============== - -Domino provides a distribution service for Network Service Descriptors (NSDs) and -Virtual Network Function Descriptors (VNFDs) that are composed using Tosca Simple -Profile for Network Functions Virtualization -(http://docs.oasis-open.org/tosca/tosca-nfv/v1.0/tosca-nfv-v1.0.html). -Domino service is targeted towards supporting many SDN controllers, service orchestrators, -VNF Managers (VNFMs), Virtual Infastructure Managers (VIMs), Operation and Business Support -Systems that produce and/or consume NSDs and VNFDs. - -Producers of NSDs and VNFDs use Domino Service as an entry point to publish these -descriptors. Consumers of NSDs and VNFDs subscribe with the Domino Service and declare -their resource capabilities to onboard and perform Life Cycle Management (LCM) for Network -Services (NSs) and Virtual Network Functions (VNFs). Thus, Domino acts as a broker for -NSs and VNFs described in a Tosca template. - -Labels in Domino ----------------- - -Domino's pub/sub architecture is based on labels (see :numref:`fig-label` below). -Each Template Producer and Template Consumer is expected to run a local Domino Client -to publish templates and subscribe for labels. - -.. _fig-label: - -.. figure:: ../etc/domino_pubsub_system.jpeg - :width: 350px - :align: center - :height: 300px - :alt: alternate text - :figclass: align-center - - Domino provides a pub/sub server for NSDs and VNFDs - -Domino Service does not interpret what the labels mean. Domino derives labels directly from -the normative definitions in TOSCA Simple YAML Profile for NFV. Domino parses the policy -rules included in the NSD/VNFD, form "policy" labels, and determine which resources are -associated with which set of labels. Domino identifies which Domino Clients can host -which resource based on the label subscriptions by these clients. Once mapping of resources -to the clients are done, new NSDs/VNFDs are created based on the mapping. These new -NSDs/VNFDs are translated and delivered to the clients. - -Label Format and Examples -------------------------- - -Domino supports policy labels in the following form: - -.. code-block:: bash - - :properties: - -Orchestrators, controllers, and managers use Domino service to announce their -capabilities by defining labels in this form and subscribing for these labels with -the Domino Server. - -For instance a particular VIM that is capable of performing an -affinity based VNF or VDU placement at host machine granularity can specify a label -in the form: - -.. code-block:: bash - - tosca.policies.Placement.affinity:properties:granularity:hostlevel - -When the VIM registers with the Domino Service and subscribed for that label, Domino views -this VIM as a candidate location that can host a VNF or VDU requesting affinity based -placement policy at host machine granularity. - -Another use case is the announcement of lifecycle management capabilities for VNFs and -VNF Forwarding Graphs (VNFFG) by different SDN Controllers (SDN-Cs), VNFMs, or VIMs. -For instance - -.. code-block:: bash - - tosca.policies.Scaling.VNFFG:properties:session_continuity:true - -can be used as a label to indicate that when a scaling operation on a VNFFG (e.g., add -more VNFs into the graph) is requested, existing session can still be enforced to go -through the same chain of VNF instances. - -To utilize Domino's domain mapping services for virtual network resources (e.g., VNF, VDU, -VNFFG, CP, VL, etc.), a network service or network function request must include -policy rules that are composed of policy types and property values that match to the -label announcements of these domains. For instance, when a TOSCA template includes a -policy rule with type "tosca.policies.Scaling.VNFFG" and property field -"session_continuity" set as "true" targeting one or more VNFFGs, this serves as the hint -for the Domino Server to identify all the Domain Clients that subscribed the label -"tosca.policies.Scaling.VNFFG:properties:session_continuity:true". - -Template Example for Label Extraction -------------------------------------- - -Consider the following NSD TOSCA template: - -.. code-block:: bash - - tosca_definitions_version: tosca_simple_profile_for_nfv_1_0_0 - description: Template for deploying a single server with predefined properties. - metadata: - template_name: TOSCA NFV Sample Template - policy_types: - tosca.policies.Placement.Geolocation: - description: Geolocation policy - derived_from: tosca.policies.Placement - topology_template: - node_templates: - VNF1: - type: tosca.nodes.nfv.VNF - properties: - id: vnf1 - vendor: acmetelco - version: 1.0 - VNF2: - type: tosca.nodes.nfv.VNF - properties: - id: vnf2 - vendor: ericsson - version: 1.0 - VNF3: - type: tosca.nodes.nfv.VNF - properties: - id: vnf3 - vendor: huawei - version: 1.0 - policies: - - rule1: - type: tosca.policies.Placement.Geolocation - targets: [ VNF1 ] - properties: - region: [ us-west-1 ] - - rule2: - type: tosca.policies.Placement.Geolocation - targets: [ VNF2, VNF3 ] - properties: - region: [ us-west-1 , us-west-2 ] - -Domino Server extracts all possible policy labels by exhaustively concatenating key-value -pairs under the properties section of the policy rules to the policy type of these rules: - -.. code-block:: bash - - tosca.policies.Placement.Geolocation:properties:region:us-west-1 - tosca.policies.Placement.Geolocation:properties:region:us-west-2 - -Furthermore, Domino Server iterates over the targets specified under policy rules to generate a set of labels for each target node: - -.. code-block:: bash - - required_labels['VNF1'] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 } - required_labels['VNF2'] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 , tosca.policies.Placement.Geolocation:properties:region:us-west-2} - required_labels['VNF3'] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 , tosca.policies.Placement.Geolocation:properties:region:us-west-2} - -When a Template Consuming site (e.g., VNFM or VIM) registers with the Domino Server using -Domino Client, it becomes an eligible candidate for template distribution with an initially -empty set of label subscriptions. Suppose three different Domino Clients register with the -Domino Server and subscribe for some or none of the policy labels such that the Domino Server -has the current subscription state as follows: - -.. code-block:: bash - - subscribed_labels[site-1] = { } #this is empty set - subscribed_labels[site-2] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 } - subscribed_labels[site-3] = { tosca.policies.Placement.Geolocation:properties:region:us-west-1 , tosca.policies.Placement.Geolocation:properties:region:us-west-2} - - -Based on the TOSCA example and hypothetical label subscriptions above, Domino Server identifies -all the VNFs can be hosted by Site-3, while VNF1 can be hosted by both Site-2 and Site-3. -Note that Site-1 cannot host any of the VNFs listed in the TOSCA file. When a VNF can be hosted -by multiple sites, Domino Server picks the site that can host the most number of VNFs. When not -all VNFs can be hosted on the same site, the TOSCA file is partitioned into multiple files, one -for each site. These files share a common part (e.g, meta-data, policy-types, version, -description, virtual resources that are not targeted by any policy rule, etc.). Each site -specific file has also a non-common part that only appears in that file (i.e., virtual -resources explicitly assigned to that site and the policy rules that accompany those virtual -resources. - -In the current Domino convention, if a VNF (or any virtual resource) does not have a policy -rule (i.e., it is not specified as a target in any of the policy rules) and it also is not -dependent on any VNF (or any virtual resource) that is assigned to another site, that resource -is wild carded by default and treated as part of the "common part". Also note that currently -Domino does not support all or nothing semantics: if some of the virtual resources are not -mappable to any domain because they are targets of policy rules that are not supported by any -site, these portions will be excluded while the remaining virtual resources will be still be -part of one or more template files to be distributed to hosting sites. When NSDs and VNFDs are -prepared, these conventions must be kept in mind. In the future releases, these conventions can -change based on the new use cases. - -For the example above, no partitioning would occur as all VNFs are mapped onto site-3; -Domino Server simply delivers the Tosca file to Domino Client hosted on site-3. When TOSCA -cannot be consumed by a particular site directly, Domino Server can utilize -existing translators (e.g., heat-translator) to first translate the template before delivery. - -Internal Processing Pipeline at Domino Server ---------------------------------------------- - -:numref:`fig-pipe` shows the block diagram for the processing stages of a published TOSCA template. -Domino Client issues an RPC call publish(tosca file). Domino Server passes the received tosca -file to Label Extractor that outputs resource labels. Domain Mapper uses the extracted labels -and tosca file to find mappings from resources to domains as well as the resource dependencies. -Resource to domain mappings and resource dependencies are utilized to partition the -orchestration template into individual resource orchestration templates (one for each domain). -If a translation is required (e.g., TOSCA to HOT), individual resource orchestration templates -are first translated and then placed on a template distribution workflow based on resource -dependencies. Message Sender block in the server takes one distribution task at a time from the -workflow generator and pushes the orchestration template to the corresponding Domino Client. - -.. _fig-pipe: - -.. figure:: ../etc/domino_server_processing.png - :width: 400px - :align: center - :height: 350px - :alt: alternate text - :figclass: align-center - - Domino Service Processing Pipeline - -Resource Scheduling -------------------- - -Domino Service currently supports maximum packing strategy when a virtual resource type can -be hosted on multiple candidate sites. Initially, Domino Scheduler identifies virtual resources -that has only one feasible site for hosting. Each such virtual resource is trivially assigned -to its only feasible site. The remaining virtual resources with multiple candidate locations -are sequentially allocated to one of their candidate locations that has the most virtual -resource assignments so far. Note that wildcarded resources are assigned to all sites. To -prevent wildcarding within the current release, (i) all sites must subscribed to a base policy -with a dummy key-value pair defined under the properties tab and (ii) all the independent -resources must be specified as target of that policy in NSD or VNFD file. - -- cgit 1.2.3-korg