diff --git a/doc/source/devref/vnffg_usage_guide.rst b/doc/source/devref/vnffg_usage_guide.rst new file mode 100644 index 000000000..a8846a2b8 --- /dev/null +++ b/doc/source/devref/vnffg_usage_guide.rst @@ -0,0 +1,146 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _ref-scale: + +==================== +VNF Forwarding Graph +==================== + +VNF Forwarding Graph or VNFFG feature in Tacker is used to orchestrate and +manage traffic through VNFs. In short, abstract VNFFG TOSCA definitions are +rendered into Service Function Chains (SFCs) and Classifiers. The SFC makes +up an ordered list of VNFs for traffic to traverse, while the classifier +decides which traffic should go through them. + +Similar to how VNFs are described by VNFDs, VNFFGs are described by VNF +Forwarding Graph Descriptors (VNFFGD). Please see the `devref guide +`_ on VNFFGD to learn more about +how a VNFFGD is defined. + +After creating a VNFFGD, a VNFFG is instantiated by a separate Tacker +command. This action will build the chain and classifier necessary to +realize the VNFFG. + +Prerequisites +~~~~~~~~~~~~~ + +VNFFG with OpenStack VIM relies on Neutron Networking-sfc to create SFC and +Classifiers. Therefore it is required to install `networking-sfc +`_ project +in order to use Tacker VNFFG. Networking-sfc also requires at least OVS 2.5 +.0, so also ensure that is installed. See the full `Networking-sfc guide +`_. + +Creating the VNFFGD +~~~~~~~~~~~~~~~~~~~ + +Once OpenStack/Devstack along with Tacker has been successfully installed, +deploy a sample VNFFGD template such as the one `here `_. + +*Note: A current constraint of the Forwarding Path policy match criteria is +to include the network_src_port_id, such as:* + +:: + + policy: + type: ACL + criteria: + - network_src_port_id: 640dfd77-c92b-45a3-b8fc-22712de480e1 + +This is required due to a limitation of Neutron networking-sfc and only +applies to an OpenStack VIM. + +Tacker provides the following CLI to create a VNFFGD: + +**tacker vnffgd-create --vnffgd-file ** + +Creating the VNFFG +~~~~~~~~~~~~~~~~~~ + +To create a VNFFG, you must have first created VNF instances of the same +VNFD types listed in the VNFFGD. Failure to do so will result in error when +trying to create a VNFFG. Note, the VNFD you define **must** include the +same Connection Point definitions as the ones you declared in your VNFFGD. + +Refer the 'Getting Started' link below on how to create a VNFD and deploy a +VNF: +http://docs.openstack.org/developer/tacker/install/getting_started.html + +Tacker provides the following CLI to create VNFFG: + + **tacker vnffg-create --vnffgd-id ** + **--vnffgd-name ** + **--vnf-mapping ** + **--symmetrical ** + +Here, + +* vnffgd-id/name - VNFFGD to use to instantiate this VNFFG +* vnf-mapping - Allows a list of logical VNFD to VNF instance mapping +* symmetrical - True/False + +VNF Mapping is used to declare which exact VNF instance to be used for +each VNF in the Forwarding Path. For example, imagine a Forwarding Path +'path' which includes VNF1 and VNF2 VNFDs. Two VNF instances already exist +(one from each VNFD): '91e32c20-6d1f-47a4-9ba7-08f5e5effe07', +'7168062e-9fa1-4203-8cb7-f5c99ff3ee1b'. The following command would then +map each VNFD defined in the VNFFGD Forwarding Path to the desired VNF +instance: + + **tacker vnffg-create --vnffgd-name myvnffgd** + **--vnf-mapping VNF1:'91e32c20-6d1f-47a4-9ba7-08f5e5effe07',** + **VNF2:'7168062e-9fa1-4203-8cb7-f5c99ff3ee1b'** + +Alternatively, if no vnf-mapping is provided then Tacker VNFFG will attempt +to search for VNF instances derived from the given VNFDs in the VNFFGD. If +multiple VNF instances exist for a given VNFD, the VNF instance chosen to be +used in the VNFFG is done at random. + +The symmetrical argument is used to indicate if reverse traffic should also +flow through the path. This creates an extra classifier to ensure return +traffic flows through the chain in a reverse path, otherwise this traffic +routed normally and does not enter the VNFFG. + +*Note: Enabling symmetrical is not currently supported by the OpenStack VIM +driver* + +Viewing a VNFFG +~~~~~~~~~~~~~~~ + +A VNFFG once created is instantiated as multiple sub-components. These +components include the VNFFG itself, which relies on a Network Forwarding +Path (NFP). The NFP is then composed of a Service Function Chain (SFC) and +a Classifier. The main command to view a VNFFG is 'tacker vnffg-show, +however there are several commands available in order to view the +sub-components for a rendered VNFFG: + +- **tacker nfp-list** +- **tacker nfp-show ** +- **tacker chain-list** +- **tacker chain-show ** +- **tacker classifier-list** +- **tacker classifier-show ** + +Known Issues and Limitations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Match criteria requires 'network_src_port_id' +- Only one Forwarding Path allowed per VNFFGD +- Matching on criteria with postfix 'name' does not work, for example + 'network_name' +- NSH attributes not yet supported +- Symmetrical is not supported by driver yet diff --git a/doc/source/devref/vnffgd_template_description.rst b/doc/source/devref/vnffgd_template_description.rst new file mode 100644 index 000000000..0a485cdaa --- /dev/null +++ b/doc/source/devref/vnffgd_template_description.rst @@ -0,0 +1,229 @@ +VNFFG Descriptor Template Guide +=============================== +Overview +-------- + +This document explains VNFFGD template structure and its various fields based +on TOSCA standards `V1.0 CSD 03 `_. + +The behavioural and deployment information of a VNFFG in Tacker is defined in a +template known as VNFFG Descriptor (VNFFGD). The template is based on TOSCA +standards and is written in YAML. It is on-boarded in a VNFFG catalog. + +Each VNFFGD template will have below fields: + +:: + + tosca_definitions_version: + This defines the TOSCA definition version on which the template is based. + The current version being tosca_simple_profile_for_nfv_1_0_0. + + tosca_default_namespace: + This is optional. It mentions default namespace which includes schema, + types version etc. + + description: + A short description about the template. + + metadata: + template_name: A name to be given to the template. + + topology_template: + Describes the topology of the VNFFG under node_template field. + node_template: + Describes node types of a VNFFG. + FP: + Describes properties and path of a Forwarding Path. + groups: + Describes groupings of nodes that have an implied relationship. + VNFFG: + Describes properties and members of a VNF Forwarding Graph. + +For examples, please refer sample VNFD templates available at `GitHub `_. + +Node types +---------- +For Tacker purposes a VNFFGD only includes **Forwarding Path**. In a full +Network Services Descriptor (NSD), it would include information about each +VNFD as well. However until that implementation, VNFD is described in a +separate template. Only a single Forwarding Path is currently supported. +**node_templates** is a child of **topology_template**. + +Forwarding Path +--------------- +Forwarding Path is a required entry in a VNFFGD. It describes the chain as +well as the classifier that will eventually be created to form a path +through a set of VNFs. + +:type: + tosca.nodes.nfv.FP.Tacker +:properties: + Describes the properties of a FP. These include id (path ID), policy + (traffic match policy to flow through the path), and path (chain of + VNFs/Connection Points). A complete list of VNFFG properties currently + supported by Tacker are listed `here `_ under **properties** section of + **tosca.nodes.nfv.FP.Tacker** field. + +Specifying FP properties +^^^^^^^^^^^^^^^^^^^^^^^^ +An example FP shown below: + +:: + + node_templates: + + Forwarding_path1: + type: tosca.nodes.nfv.FP.Tacker + description: creates path (CP11->CP12->CP32) + properties: + id: 51 + policy: + type: ACL + criteria: + - network_src_port_id: 640dfd77-c92b-45a3-b8fc-22712de480e1 + - destination_port_range: 80-1024 + - ip_proto: 6 + - ip_dst_prefix: 192.168.1.2/24 + path: + - forwarder: VNF1 + capability: CP1 + - forwarder: VNF2 + capability: CP2 + +id +"" +ID from the above example is used to identify the path. This path ID will +be used in future implementations of Network Service Header (NSH) to +identify paths via the Service Path Identifier (SPI) attribute. + +policy +"""""" +Policy defines the type of match policy that will be used to distinguish +which traffic should enter this Forwarding Path. The only currently +supported type is ACL (access-list). Please reference `tosca.nfv.datatypes.aclType +`_ under **properties** section for more information on +supported match criteria. + +path +"""" +Path defines an ordered list of nodes to traverse in a Forwarding Path. Each +node is really a logical port, which is defined in the path as a Connection +Point (CP) belonging to a specific VNFD. It is not necessary at VNFFGD +creation time to have predefined these VNFDs used in the path. They may be +created later. Up to 2 CPs may be listed (in order) per VNFD. If 2 are +listed, the first will be considered the ingress port for traffic and the +second will be the egress. If only one port is provided, then it will be +interpreted as both the ingress and egress port for traffic. + + +Groups +------ +In Tacker and TOSCA, the VNFFG itself is described in this section. There +may only be a single VNFFG described in each VNFFGD under this section. + +VNFFG +----- +VNFFG maps the Forwarding Path to other node types defined in the properties +section. + +:type: + tosca.groups.nfv.VNFFG +:properties: + Describes the properties of a VNFFG. These include vendor, version, + dependent_virtual_link, connection_points, constituent_vnfs. + . A complete list of VNFFG properties currently + supported by Tacker are listed in `TOSCA `_. +:members: + A list of Forwarding Paths which belong to this VNFFG. At the moment + only one is supported. + +Specifying VNFFG properties and members +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +An example VNFFG shown below: + +:: + + groups: + VNFFG1: + type: tosca.groups.nfv.VNFFG + description: HTTP to Corporate Net + properties: + vendor: tacker + version: 1.0 + number_of_endpoints: 2 + dependent_virtual_link: [VL1,VL2,VL3] + connection_point: [CP1,CP2] + constituent_vnfs: [VNF1,VNF2] + members: [Forwarding_path1] + +number_of_endpoints +""""""""""""""""""" +Number of CPs included in this VNFFG. + +dependent_virtual_link +"""""""""""""""""""""" +The Virtual Link Descriptors (VLD) that connect each VNF/CP in this +Forwarding Graph. + +connection_point +"""""""""""""""" +List of Connection Points defined in the Forwarding Path. + +constituent_vnfs +"""""""""""""""" +List of VNFD names used in this Forwarding Graph (also defined in Forwarding +Path). + +Summary +------- +To summarize VNFFGD is written in YAML and describes a VNFFG topology. It is +composed of a Forwarding Path and a VNFFG. A full VNFFGD is shown below: + +:: + + tosca_definitions_version: tosca_simple_profile_for_nfv_1_0_0 + + description: Sample VNFFG template + + topology_template: + description: Sample VNFFG template + + node_templates: + + Forwarding_path1: + type: tosca.nodes.nfv.FP.Tacker + description: creates path (CP12->CP22) + properties: + id: 51 + policy: + type: ACL + criteria: + - network_src_port_id: 640dfd77-c92b-45a3-b8fc-22712de480e1 + - destination_port_range: 80-1024 + - ip_proto: 6 + - ip_dst_prefix: 192.168.1.2/24 + path: + - forwarder: VNFD1 + capability: CP12 + - forwarder: VNFD2 + capability: CP22 + + groups: + VNFFG1: + type: tosca.groups.nfv.VNFFG + description: HTTP to Corporate Net + properties: + vendor: tacker + version: 1.0 + number_of_endpoints: 2 + dependent_virtual_link: [VL12,VL22] + connection_point: [CP12,CP22] + constituent_vnfs: [VNFD1,VNFD2] + members: [Forwarding_path1] diff --git a/doc/source/index.rst b/doc/source/index.rst index bf4f85870..0719a3476 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -57,6 +57,8 @@ Feature Documentation devref/scale_usage_guide.rst devref/alarm_monitoring_usage_guide.rst devref/event_logging.rst + devref/vnffgd_template_description.rst + devref/vnffg_usage_guide.rst API Documentation =================