openstack/tacker
Code Issues Proposed changes

Adds devref guides for VNFFG

Browse Source 
implements: blueprint tacker-vnffg

Change-Id: Ie1bcec2f9e671c63e4d950826bb53f0f9a5b6f10
Signed-off-by: Tim Rozet <trozet@redhat.com>
This commit is contained in:
Tim Rozet 2016-09-23 15:50:07 -04:00
parent cd5089593f
commit 0cc329e500
3 changed files with 377 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

146
doc/source/devref/vnffg_usage_guide.rst Normal file
View File

@ -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
<https://github.com/openstack/tacker/tree/doc/source/devref
/vnffgd_template_description.rst>`_ 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
<https://github.com/openstack/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
<https://wiki.openstack.org/wiki/Neutron/ServiceInsertionAndChaining>`_.
Creating the VNFFGD
~~~~~~~~~~~~~~~~~~~
Once OpenStack/Devstack along with Tacker has been successfully installed,
deploy a sample VNFFGD template such as the one `here <https://github.com/
openstack/tacker/tree/master/samples/tosca-templates/vnffgd/
tosca-vnffgd-sample.yaml>`_.
*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 <vnffgd file> <vnffgd name>**
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 <vnffg-id>**
**--vnffgd-name <vnffgd name>**
**--vnf-mapping <vnf mapping>**
**--symmetrical <boolean>**
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 <nfp id>**
- **tacker chain-list**
- **tacker chain-show <chain id>**
- **tacker classifier-list**
- **tacker classifier-show <classifier id>**
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

229
doc/source/devref/vnffgd_template_description.rst Normal file
View File

@ -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 <http://docs.oasis-open.org/tosca/tosca-nfv/
v1.0/tosca-nfv-v1.0.html>`_.
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 <https:
//github.com/openstack/tacker/tree/master/samples/tosca-templates/vnffgd>`_.
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 <https://github
.com/openstack/tacker/blob/master/tacker/vnfm/
tosca/lib/tacker_nfv_defs.yaml>`_ 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
<https://github.com/openstack/tacker/blob/master/tacker/vnfm/tosca/lib/
tacker_nfv_defs.yaml>`_ 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 <http://docs.oasis-open
.org/tosca/tosca-nfv/v1.0/csd03/tosca-nfv-v1.0-csd03
.html#_Toc447714727>`_.
: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]

2
doc/source/index.rst
View File

@ -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
=================