openstack/tacker
Code Issues Proposed changes

Add docs of VNF Package and VNFD with ETSI NFV-SOL

Browse Source 
Usage guides for VNF Package based on NFV-SOL004 and VNFD based on
NFV-SOL001 are added in user docs.

Change-Id: Ibd227b2704c04b3dd2f4fe99dffc4fd498bff3f6
This commit is contained in:
Yoshito Ito 2020-08-20 12:42:35 +09:00
parent d60436b0d3
commit 8a918b540f
4 changed files with 520 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
doc/source/_images/vnfd-sol001.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 27 KiB

2
doc/source/user/index.rst
View File

@ -45,6 +45,8 @@ Use cases
.. toctree::
:maxdepth: 1
vnf-package
vnfd-sol001
alarm_monitoring_usage_guide.rst
dynamic_vnffg_usage_guide.rst
enhanced_placement_awareness_usage_guide.rst

263
doc/source/user/vnf-package.rst Normal file
View File

@ -0,0 +1,263 @@
===========
VNF Package
===========
VNF Package is a ZIP file including VNFD, software images for VM, and other
artifact resources such as scripts and config files. The directory structure
and file contents are defined in `NFV-SOL004 v2.6.1`_.
According to `NFV-SOL004 v2.6.1`_, VNF Package should be the ZIP file format
with the `TOSCA-Simple-Profile-YAML-v1.1`_ Specifications. The ZIP file is
called TOSCA YAML Cloud Service Archive (CSAR), and two different structures
are available:
* CSAR with TOSCA-Metadata directory
* CSAR zip without TOSCA-Metadata directory
.. note:: For more detailed definitions of CSAR, see section 16 in
`TOSCA-Simple-Profile-YAML-v1.1`_.
Some examples for VNF Package are available in Tacker repository.
* https://opendev.org/openstack/tacker/
CSAR with TOSCA-Metadata directory
----------------------------------
The directory structure:
* **TOSCA-Metadata/TOSCA.meta**
* **Definitions/**
* **Files/images/**
* (optional) **Scripts/**
* (optional) **<manifest file name>.mf**
.. code-block::
!----TOSCA-Metadata
!---- TOSCA.meta
!----Definitions
!---- etsi_nfv_sol001_common_types.yaml
!---- etsi_nfv_sol001_vnfd_types.yaml
!---- vnfd_top.yaml
!---- vnfd_df_1.yaml
!---- ..
!---- vnfd_df_x.yaml
!---- vnfd_types.yaml
!----Files
!---- images
!---- image_1.img
!---- ..
!---- image_x.img
!----Scripts (optional)
!---- install.sh
!---- manifest.mf
TOSCA-Metadata/TOSCA.meta
^^^^^^^^^^^^^^^^^^^^^^^^^
According to `TOSCA-Simple-Profile-YAML-v1.1`_ specifications, the
``TOSCA.meta`` metadata file is described in `TOSCA-1.0-specification`_,
and it should have the following contents:
* *TOSCA-Meta-File-Version*: This is the version number of the TOSCA meta
file format and must be "1.0".
* *CSAR-Version*: This is the version number of the CSAR specification and
must be "1.1"
* *Created-By*: The person or vendor, respectively, who created the CSAR.
* *Entry-Definitions*: This is the reference to the top-level VNFD file in
**Definitions/** directory.
* (optional) *ETSI-Entry-Manifest*: This is the reference to the manifest
file. When this key/value is not provided, Tacker tries to find the manifest
file with the name of top-level VNF file as ``<VNFD file name>.mf``.
In ``TOSCA.meta`` file, artifact resources related information, which is also
possible to locate in manifest file, can be described in the following manner
according to `TOSCA-1.0-specification`_ section 16.2:
.. note:: It is highly recommended to put artifacts information in the
manifest file other than in TOSCA.meta file because it's more
simple and easy to understand.
* (optional) *artifact info* - describes location and digest of all files
other than VNFD YAML files.
* *Name*: The path and identifier of the file.
* *Content-Type*: The type of the file described. This type is a MIME type
complying with the type/subtype structure.
* *Algorithm*: The name of hash algorithm. "SHA-224", "SHA-256", "SHA-384",
and "SHA-512" are supported.
* *Hash*: Text string corresponding to the hexadecimal representation.
.. note:: For software images, note that the algorithm of hash calculation is
the same as the `Glance configuration`_, the default is "SHA-512".
The software images are not additionalArtifacts but softwareImages
according to `NFV-SOL005 v2.6.1`_.
.. note:: The "Name" and "Content-Type" attributes are defined in
`TOSCA-1.0-specification`_ section 16.2. The "Algorithm" and "Hash" are
requirement from `NFV-SOL004 v2.6.1`_ section 5.3 and
`NFV-SOL005 v2.6.1`_ section 9.5.3.3, the checksum field is required
and the manner should be the same with the manifest file.
Example:
.. code-block:: yaml
TOSCA-Meta-File-Version: 1.0
CSAR-Version: 1.1
Created-By: Tacker
Entry-Definitions: vnfd_top.yaml
ETSI-Entry-Manifest: manifest.mf
Name: manifest.mf
Content-Type: text/plain
Algorithm: SHA-256
Hash: 09e5a788acb180162c51679ae4c998039fa6644505db2415e35107d1ee213943
Name: scripts/install.sh
Content-Type: application/x-sh
Algorithm: SHA-256
Hash: d0e7828293355a07c2dccaaa765c80b507e60e6167067c950dc2e6b0da0dbd8b
Name: https://www.example.com/example.sh
Content-Type: application/x-sh
Algorithm: SHA-256
Hash: 36f945953929812aca2701b114b068c71bd8c95ceb3609711428c26325649165
Definitions/
^^^^^^^^^^^^
All VNFD YAML files are located here. How to create VNFD composed of plural
deployment flavours is described in :doc:`./vnfd-sol001`.
VNFD type files provided from `ETSI NFV-SOL001 repository`_ are also included:
* etsi_nfv_sol001_common_types.yaml
* etsi_nfv_sol001_vnfd_types.yaml
Files/images/
^^^^^^^^^^^^^
VNF Software Images are located here. These files are also described in
``TOSCA.meta`` or manifest file as artifacts.
Scripts/
^^^^^^^^
Any script files are located here. These scripts are executed in Action
Driver or Management Driver. All these files also appear in ``TOSCA.meta``
or manifest file as artifacts.
.. TODO(yoshito-ito): add links to ActionDriver and MgmtDriver.
How to implement and utilize Action Driver is described in
:doc:`../admin/action-driver` and Management Driver is described in
:doc:`../admin/management-driver`.
<manifest file name>.mf
^^^^^^^^^^^^^^^^^^^^^^^
The manifest file contains two types of information, *metadata* and *artifact*
*info*. *metadata* is optional and *artifact info* is required when one or
more artifacts are included in the VNF Package file such as software images,
scripts or config files. This *artifact info* is also possible to be in
``TOSCA.meta`` file.
* (optional) *metadata* - is optional metadata for the VNF Package file.
* *vnf_product_name*: The product name of VNF.
* *vnf_provider_id*: The ID of VNF provider.
* *vnf_package_version*: The version of the VNF Package file.
* *vnf_release_date_time*: The format according to `IETF RFC 3339`_.
.. note:: The *metadata* in manifest file is not stored in Tacker DB.
* *artifact info* - describes location and digest of all files other than
VNFD YAML files.
* *Source*: The path and identifier of the file.
* *Algorithm*: The name of hash algorithm. "SHA-224", "SHA-256", "SHA-384",
and "SHA-512" are supported.
* *Hash*: Text string corresponding to the hexadecimal representation.
Example:
.. code-block:: yaml
metadata:
vnf_product_name: VNF
vnf_provider_id: Tacker
vnf_package_version: 1.0
vnf_release_date_time: 2020-01-01T10:00:00+09:00
Source: VNFD.yaml
Algorithm: SHA-256
Hash: 09e5a788acb180162c51679ae4c998039fa6644505db2415e35107d1ee213943
Source: scripts/install.sh
Algorithm: SHA-256
Hash: d0e7828293355a07c2dccaaa765c80b507e60e6167067c950dc2e6b0da0dbd8b
Source: https://www.example.com/example.sh
Algorithm: SHA-256
Hash: 36f945953929812aca2701b114b068c71bd8c95ceb3609711428c26325649165
CSAR zip without TOSCA-Metadata directory
-----------------------------------------
The file structure:
* **<VNFD file name>.yaml**
* **Definitions/**
* **<manifest file name>.yaml**
.. code-block::
!---- vnfd_top.yaml
!----Definitions/
!---- etsi_nfv_sol001_common_types.yaml
!---- etsi_nfv_sol001_vnfd_types.yaml
!---- vnfd_top.yaml
!---- vnfd_df_1.yaml
!---- ..
!---- vnfd_df_x.yaml
!---- vnfd_types.yaml
!---- vnfd_top.mf
<VNFD file name>.yaml
^^^^^^^^^^^^^^^^^^^^^
This is the top-level VNFD file. It can import additional VNFD files from
**Definitions/** directory.
Definitions/
^^^^^^^^^^^^
All VNFD YAML files other than top-level VNFD are located here. How to create
VNFD composed of plural deployment flavours is described in
:doc:`./vnfd-sol001`.
VNFD type files provided from `ETSI NFV-SOL001 repository`_ may be included:
* etsi_nfv_sol001_common_types.yaml
* etsi_nfv_sol001_vnfd_types.yaml
<manifest file name>.yaml
^^^^^^^^^^^^^^^^^^^^^^^^^
The manifest file has an extension .mf, the same name as the top-level VNFD
YAML file. The contents is exactly same as described in the previous section.
.. _TOSCA-Simple-Profile-YAML-v1.1 : http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.1/TOSCA-Simple-Profile-YAML-v1.1.html
.. _TOSCA-1.0-specification : http://docs.oasis-open.org/tosca/TOSCA/v1.0/os/TOSCA-v1.0-os.pdf
.. _Glance configuration : https://docs.openstack.org/glance/latest/user/signature.html#using-the-signature-verification
.. _ETSI NFV-SOL001 repository : https://forge.etsi.org/rep/nfv/SOL001
.. _IETF RFC 3339 : https://tools.ietf.org/html/rfc3339
.. _NFV-SOL004 v2.6.1 : https://www.etsi.org/deliver/etsi_gs/NFV-SOL/001_099/004/02.06.01_60/gs_NFV-SOL004v020601p.pdf
.. _NFV-SOL005 v2.6.1 : https://www.etsi.org/deliver/etsi_gs/NFV-SOL/001_099/005/02.06.01_60/gs_NFV-SOL005v020601p.pdf

255
doc/source/user/vnfd-sol001.rst Normal file
View File

@ -0,0 +1,255 @@
==============================================
VNF Descriptor (VNFD) based on ETSI NFV-SOL001
==============================================
This document describes how to create your VNFD files based on ETSI
`NFV-SOL001 v2.6.1`_. The VNFD is modelled by using one or more TOSCA service
template as defined in `TOSCA-Simple-Profile-yaml-v1.2`_. The VNFD is a
component of a VNF package and takes YAML format files.
The VNFD is composed of four different kinds of files:
**Type definition files** - define properties of each resource.
**Topology template files** - describe the actual design of VNF.
#. ETSI NFV types definition file
#. User defined types definition file
#. top-level topology template file
#. topology template file with deployment flavour
Example:
.. code-block::
Definitions/
!---- etsi_nfv_sol001_common_types.yaml
!---- etsi_nfv_sol001_vnfd_types.yaml
!---- vnfd_top.yaml
!---- vnfd_df_1.yaml
!---- ..
!---- vnfd_df_x.yaml
!---- vnfd_types.yaml
Deployment flavour model
------------------------
To design VNF with a VNFD, "deployment flavour model" is helpful. An example
of the model is shown below:
.. figure:: ../_images/vnfd-sol001.png
:figwidth: 700 px
:align: left
:scale: 80 %
The *top-level topology template file* describes the abstract design of VNF.
In the example, the VNF has a Connection Point (CP) to an External Virtual
Link (ExtVL). The CP and Virtual Link (VL) are mapped to a Port and a Virtual
network, respectively.
The actual design of VNF is described in *topology template files with*
*deployment flavour*. In the example, two different deployment flavours,
"simple" and "complex" are provided. The "simple" has only a Virtualised
Deployment Unit (VDU), which represents a VM while the "complex" has two VDUs.
It is possible to design plural topologies for a VNF with deployment flavour.
The deployed topology is specified with a deployment flavour ID in the
Instantiation request parameter.
Type definition files
---------------------
Type definition files contain all required "Types" appeared in **service**
**template files**. The resources described in **topology template files** are
defined as "Types" in **type definition files**.
There are nine groups of type definition in `NFV-SOL001 v2.6.1`_.
* Data Types: ``data_types``
* Artifact Types: ``artifact_types``
* Capability Types: ``capability_types``
* Requirements Types: ``requirements_types``
* Relationship Types: ``relationship_types``
* Interface Types: ``interface_types``
* Node Types: ``node_types``
* Group Types: ``group_types``
* Policy Types: ``policy_types``
1. ETSI NFV types definition file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ETSI NFV provides two types definition files [1]_ which contain all defined
type definitions in `NFV-SOL001 v2.6.1`_. These files are generally imported
from *top-level service template file*.
* `etsi_nfv_sol001_common_types.yaml`_
* `etsi_nfv_sol001_vnfd_types.yaml`_
2. User defined types definition file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Users can extend their own types definition from `NFV-SOL001 v2.6.1`_. In most
cases, Users need to extend ``tosca.nodes.nfv.VNF`` to define your VNF node
types. The contents in the file are:
* **tosca_definitions_version** - is always "tosca_simple_yaml_1_2".
* **description** - is the description of the file.
* **imports** - are the types definition files from ETSI NFV.
* **node_types** - is the key to describe the extension of
``tosca.nodes.nfv.VNF`` to define your VNF.
* (optional) **data_types** - is the key to define your own data types.
The ``tosca.nodes.nfv.VNF`` type described in **node_types** field is defined
in section 6.8.1 in `NFV-SOL001 v2.6.1`_. Its required properties are:
* *descriptor_id* - is "VNFD ID" and required when creating VNF instance.
* *descriptor_version* - is version of the VNFD.
* *provider* - is name of provider who provide the VNFD.
* *product_name* - is name of the VNF.
* *software_version** - is version of the software for the VNF.
* *vnfm_info* - is identifies VNFM(s) compatible with the VNF described in
this version of the VNFD. The default can be "Tacker".
* *flavour_id* - is ID of deployment flavour to be used in Instantiation.
* *flavour_description* - is description of the deployment flavour. The
default can be "" (empty string).
Topology template files
-----------------------
The topology template files describe the topology of VNF. The topology is
defined with the following contents:
* **tosca_definitions_version** - is always "tosca_simple_yaml_1_2".
* **description** - is the description of the file.
* **imports** - are the types definition files from ETSI NFV and the user
defined types definition file.
* **topology_template** - describe the topology of VNF with node templates.
The **topology_template** field is defined in section 3.9 in
`TOSCA-Simple-Profile-yaml-v1.2`_. All keys are optional, but some keys are
important to describe the topology:
* (optional) *description* - is the description of file.
* *inputs* - is a list of input parameters.
* *node_templates* - is a list of node template definitions.
* (optional) *relationship_templates* - a list of relationship templates.
* *groups* - is a list of group definitions whose members are node templates
defined within the same topology template.
* *policies* - is a list of policy definitions.
* *outputs* - is a list of output parameters.
* *substitution_mappings* - is a declaration that exports the topology
template as an implementation of a node type.
* (optional) *workflows* - is a map of imperative workflow definition for the
topology template.
3. Top-level topology template file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The *top-level topology template file* describes the abstract design of VNF.
In this file, the ``node_template`` is provided with user defined VNF type
derived from ``tosca.nodes.nfv.VNF``. The file includes:
* **tosca_definitions_version**: tosca_simple_yaml_1_2
* **description**: A description of this file.
* **imports**
* `etsi_nfv_sol001_common_types.yaml`_
* `etsi_nfv_sol001_vnfd_types.yaml`_
* <user defined types definition files>
* **topology_template**
* *inputs*:
* selected_flavour: The deployment flavour selected in Instantiation
* *node_templates*:
* <name of VNF>:
* type: The user defined VNF Type derived from ``tosca.nodes.nfv.VNF``
* properties:
* descriptor_id: The VNFD ID created by User
* descriptor_version: The version of VNFD
* provider: The name of provider
* product_name: The name of product
* software_version: The version of VNf software
* vnfm_info: ["Tacker"]
* flavour_id: { get_input: selected_flavour }
* requirements: The properties provided in lower-level topology template
with a deployment flavour
.. note:: The required properties are defined in section 6.8.1 in
`NFV-SOL001 v2.6.1`_. The ``flavour_description`` is provided in the
lower-level topology template and not included here.
4. Topology template file with deployment flavour
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The lower-level topology template provides a deployment flavour ID and its
detailed design of VNF. The abstract design of VNF with user defined VNF Type
is referred from ``substitution_mappings`` key and also added some properties
in ``node_templates``. The ``node_templates`` field contains the detailed
resources such as VDU and CP. The file includes:
* **tosca_definitions_version**: tosca_simple_yaml_1_2
* **description**: A description of this file.
* **imports**
* etsi_nfv_sol001_common_types.yaml
* etsi_nfv_sol001_vnfd_types.yaml
* <user defined types definition files>
* **topology_template**
* *inputs*:
* descriptor_id: The VNFD ID created by User
* provider: The name of provider
* product_name: The name of product
* software_version: The version of VNf software
* descriptor_version: The version of VNFD
* vnfm_info: The identifies VNFM(s) compatible
* flavour_id: The deployment flavour ID
* flavour_description: The description of deployment flavour.
* *substitution_mappings*:
* node_type: The user defined VNf Type
* properties:
* flavour_id: The deployment flavour of this file
* requirements:
* virtual_link_external: A list of CP and VL for external network
* *node_template*:
* VNF resource
* VDU resources
* CP resources
* VL resources
* Other resources
* *policies*:
* Scaling resources
* Affinity resources
* Other resources
.. note:: The requirements field in *substitution_mappings* describes external
network topology for the abstract VNF. In the case of example in
deployment flavour section, ``virtual_link_external`` can be a list
of [CP, ExtVL].
.. TODO(yoshito-ito): add links to the examples of VNFD.
.. [1] https://forge.etsi.org/rep/nfv/SOL001
.. _TOSCA-Simple-Profile-yaml-v1.2 : http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.2/TOSCA-Simple-Profile-YAML-v1.2.html
.. _NFV-SOL001 v2.6.1 : https://www.etsi.org/deliver/etsi_gs/NFV-SOL/001_099/001/02.06.01_60/gs_NFV-SOL001v020601p.pdf
.. _etsi_nfv_sol001_common_types.yaml : https://forge.etsi.org/rep/nfv/SOL001/raw/master/etsi_nfv_sol001_common_types.yaml
.. _etsi_nfv_sol001_vnfd_types.yaml : https://forge.etsi.org/rep/nfv/SOL001/raw/master/etsi_nfv_sol001_vnfd_types.yaml