commit e1a991a0caf9ef0b8d9b7d9fa86310b12356f434 Author: Yoshito Ito Date: Thu Aug 20 12:42:35 2020 +0900 Add docs of VNF Package and VNFD with ETSI NFV-SOL Usage guides for VNF Package based on NFV-SOL004 and VNFD based on NFV-SOL001 are added in user docs. Change-Id: Ibd227b2704c04b3dd2f4fe99dffc4fd498bff3f6 (cherry picked from commit 8a918b540fe66aebe8deceb0dc91823ffa953b13) diff --git a/doc/source/_images/vnfd-sol001.png b/doc/source/_images/vnfd-sol001.png new file mode 100644 index 0000000..6cda0d0 Binary files /dev/null and b/doc/source/_images/vnfd-sol001.png differ diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 2215fd4..c845633 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -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 diff --git a/doc/source/user/vnf-package.rst b/doc/source/user/vnf-package.rst new file mode 100644 index 0000000..6219749 --- /dev/null +++ b/doc/source/user/vnf-package.rst @@ -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) **.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 ``.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`. + +.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: + +* **.yaml** +* **Definitions/** +* **.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 + + +.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 + +.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 diff --git a/doc/source/user/vnfd-sol001.rst b/doc/source/user/vnfd-sol001.rst new file mode 100644 index 0000000..96c8872 --- /dev/null +++ b/doc/source/user/vnfd-sol001.rst @@ -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`_ + * + +* **topology_template** + + * *inputs*: + + * selected_flavour: The deployment flavour selected in Instantiation + + * *node_templates*: + + * : + + * 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 + * + +* **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