Merge "Add VNFD template usage guide"
This commit is contained in:
commit
2d2c4b7953
doc/source
537
doc/source/devref/vnfd_template_description.rst
Normal file
537
doc/source/devref/vnfd_template_description.rst
Normal file
@ -0,0 +1,537 @@
|
||||
VNF Descriptor Template Guide
|
||||
=============================
|
||||
Overview
|
||||
--------
|
||||
|
||||
This document explains VNFD 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 VNF in Tacker is defined in a
|
||||
template known as VNF Descriptor (VNFD). The template is based on TOSCA
|
||||
standards and is written in YAML. It is on-boarded in a VNF catalog.
|
||||
|
||||
Each VNFD 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 VNF under node_template field.
|
||||
node_template:
|
||||
Describes node types of a VNF.
|
||||
VDU:
|
||||
Describes properties and capabilities of Virtual Deployment
|
||||
Unit.
|
||||
CP:
|
||||
Describes properties and capabilities of Connection Point.
|
||||
VL:
|
||||
Describes properties and capabilities of Virtual Link.
|
||||
|
||||
For examples, please refer sample VNFD templates available at `GitHub <https:
|
||||
//github.com/openstack/tacker/tree/master/samples/tosca-templates/vnfd>`_.
|
||||
|
||||
Node types
|
||||
----------
|
||||
A VNF includes **VDU/s**, **connection point/s** and **virtual link/s**. Hence
|
||||
a valid VNFD must have these 3 components. Each component is referred as a
|
||||
node and can have certain type, capabilities, properties, attributes and
|
||||
requirements. These components are described under **node_templates** in the
|
||||
VNFD template. **node_templates** is a child of **topology_template**.
|
||||
|
||||
VDU
|
||||
---
|
||||
Virtual Deployment Unit is a basic part of VNF. It is the VM that hosts the
|
||||
network function.
|
||||
|
||||
:type:
|
||||
tosca.nodes.nfv.VDU.Tacker
|
||||
:properties:
|
||||
Describes the properties like image to be used in VDU, availability zone in
|
||||
which VDU is to be spawned, management driver to be used to manage the VDU,
|
||||
flavor describing physical properties for the VDU to be spawned, monitoring
|
||||
policies for the VDU, providing user data in form of custom commands to the
|
||||
VDU. A complete list of VDU properties currently supported by Tacker are
|
||||
listed `here <https://github.com/openstack/tacker/blob/master/tacker/vm/
|
||||
tosca/lib/tacker_nfv_defs.yaml>`_ under **properties** section of
|
||||
**tosca.nodes.nfv.VDU.Tacker** field
|
||||
|
||||
Specifying VDU properties
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
A very simple VDU with 10 GB disk, 2 GB RAM, 2 CPUs, cirros image and in nova
|
||||
availability zone can be described as:
|
||||
|
||||
::
|
||||
|
||||
topology_template:
|
||||
node_templates:
|
||||
VDU1:
|
||||
type: tosca.nodes.nfv.VDU.Tacker
|
||||
properties:
|
||||
image: cirros-0.3.4-x86_64-uec
|
||||
availability_zone: nova
|
||||
capabilities:
|
||||
nfv_compute:
|
||||
properties:
|
||||
disk_size: 10 GB
|
||||
mem_size: 2048 MB
|
||||
num_cpus: 2
|
||||
|
||||
Using Nova flavors for VDU
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
OpenStack specific **flavors** can also be used to describe VDU configuration.
|
||||
|
||||
::
|
||||
|
||||
topology_template:
|
||||
node_templates:
|
||||
VDU1:
|
||||
type: tosca.nodes.nfv.VDU.Tacker
|
||||
properties:
|
||||
image: cirros-0.3.4-x86_64-uec
|
||||
flavor: m1.tiny
|
||||
availability_zone: nova
|
||||
|
||||
However, when both **nfv_compute properties** and **flavor** are mentioned in
|
||||
a VNFD, **flavor** setting will take precedence.
|
||||
|
||||
Monitoring the VDU
|
||||
""""""""""""""""""
|
||||
A VDU can be monitored by pinging it on port 22 for 3 times at an interval of
|
||||
2 seconds every 20 seconds. Number of retries be 6 and timeout of 2 seconds.
|
||||
It can be re-spawned in case ping fails. This is described under
|
||||
**monitoring_policy**.
|
||||
|
||||
::
|
||||
|
||||
..
|
||||
VDU1:
|
||||
type: tosca.nodes.nfv.VDU.Tacker
|
||||
properties:
|
||||
monitoring_policy:
|
||||
name: ping
|
||||
parameters:
|
||||
monitoring_delay: 20
|
||||
count: 3
|
||||
interval: 2
|
||||
timeout: 2
|
||||
actions:
|
||||
failure: respawn
|
||||
retry: 6
|
||||
port: 22
|
||||
|
||||
Providing user data
|
||||
"""""""""""""""""""
|
||||
Custom commands to be run on VDU once it is spawned can be specified in a VNFD
|
||||
template as user data.
|
||||
|
||||
::
|
||||
|
||||
..
|
||||
VDU1:
|
||||
type: tosca.nodes.nfv.VDU.Tacker
|
||||
properties:
|
||||
user_data_format: RAW
|
||||
user_data: |
|
||||
#!/bin/sh
|
||||
echo "Adding this line to demofile" > /tmp/demofile
|
||||
|
||||
Configuring a VDU
|
||||
"""""""""""""""""
|
||||
A VDU can be configured as a specific Network Function under **config**
|
||||
section in VNFD template. A sample template configuring a VDU as a firewall
|
||||
can be viewed in a `sample file <https://github.com/openstack/tacker/blob/
|
||||
master/samples/tosca-templates/vnfd/tosca-config-openwrt-with-firewall.yaml>`_.
|
||||
|
||||
Specifying external image
|
||||
"""""""""""""""""""""""""
|
||||
:artifacts:
|
||||
To specify an image via a file or an external link
|
||||
|
||||
An image URL can be specified as **artifacts**. Tacker will specify the image
|
||||
location in HOT (Heat Template) and pass it to heat-api. Heat will then spawn
|
||||
the VDU with that image.
|
||||
|
||||
::
|
||||
|
||||
..
|
||||
VDU1:
|
||||
type: tosca.nodes.nfv.VDU.Tacker
|
||||
artifacts:
|
||||
VNFImage:
|
||||
type: tosca.artifacts.Deployment.Image.VM
|
||||
file: http://download.cirros-cloud.net/0.3.4/ \
|
||||
cirros-0.3.4-x86_64-uec.tar.gz
|
||||
|
||||
VDU Capabilities
|
||||
^^^^^^^^^^^^^^^^
|
||||
Computational properties of a VDU are described as its capabilities. Allocated
|
||||
RAM size, allocated disk size, memory page size, number of CPUs, number of
|
||||
cores per CPU, number of threads per core can be specified.
|
||||
|
||||
A VDU with 10 GB disk, 2 GB RAM, 2 CPUs, 4 KB of memory page and dedicated CPU
|
||||
can be specified as below. Thread and core counts can be specified as shown.
|
||||
|
||||
::
|
||||
|
||||
..
|
||||
VDU1:
|
||||
type: tosca.nodes.nfv.VDU.Tacker
|
||||
capabilities:
|
||||
nfv_compute:
|
||||
properties:
|
||||
disk_size: 10 GB
|
||||
mem_size: 2048 MB
|
||||
num_cpus: 2
|
||||
mem_page_size: small
|
||||
cpu_allocation:
|
||||
cpu_affinity: dedicated
|
||||
thread_count: 4
|
||||
core_count: 2
|
||||
|
||||
:capabilities:
|
||||
|
||||
+---------------------+---------------+-----------+--------------------------+
|
||||
|Name |Type |Constraints|Description |
|
||||
+---------------------+---------------+-----------+--------------------------+
|
||||
|nfv_compute |Compute. |None |Describes the configurat |
|
||||
| |Container. | |ion of the VM on which |
|
||||
| |Architecture | |the VDU resides |
|
||||
+---------------------+---------------+-----------+--------------------------+
|
||||
|
||||
Compute Container Architecture
|
||||
""""""""""""""""""""""""""""""
|
||||
:type:
|
||||
tosca.capabilities.Compute.Container.Architecture
|
||||
|
||||
:properties:
|
||||
|
||||
+---------------+--------+--------+---------------+--------------------------+
|
||||
|Name |Required|Type |Constraints |Description |
|
||||
+---------------+--------+--------+---------------+--------------------------+
|
||||
|mem_page_size |No |String |One of below |Indicates page size of the|
|
||||
| | | | |VM |
|
||||
| | | | | |
|
||||
| (in MB) | | |- small |- small maps to 4 KB |
|
||||
| | | |- large |- large maps to 2 MB |
|
||||
| | | |- any (default)|- any maps to system's |
|
||||
| | | | | default |
|
||||
| | | |- custom |- custom sets the size to |
|
||||
| | | | | specified value |
|
||||
+---------------+--------+--------+---------------+--------------------------+
|
||||
|cpu_allocation |No |CPUAllo-| |CPU allocation requirement|
|
||||
| | |cation | |like dedicated CPUs, |
|
||||
| | | | |socket/thread count |
|
||||
+---------------+--------+--------+---------------+--------------------------+
|
||||
|numa_node_count|No |Integer | |Symmetric count of NUMA |
|
||||
| | | | |nodes to expose to VM. |
|
||||
| | | | |vCPU and Memory is split |
|
||||
| | | | |equally across this |
|
||||
| | | | |number of NUMA |
|
||||
+---------------+--------+--------+---------------+--------------------------+
|
||||
|numa_nodes |No |Map of |Symmetric |Asymmetric allocation of |
|
||||
| | |NUMA |numa_node_count|vCPU and memory across |
|
||||
| | | |should not be |the specified NUMA nodes |
|
||||
| | | |specified | |
|
||||
+---------------+--------+--------+---------------+--------------------------+
|
||||
|
||||
CPUAllocation
|
||||
"""""""""""""
|
||||
This describes the granular CPU allocation requirements for VDUs.
|
||||
|
||||
:type:
|
||||
tosca.datatypes.compute.Container.Architecture.CPUAllocation
|
||||
|
||||
:properties:
|
||||
|
||||
+-----------------+-------+------------+-------------------------------------+
|
||||
|Name |Type |Constraints |Description |
|
||||
+-----------------+-------+------------+-------------------------------------+
|
||||
|cpu_affinity |String |One of |Describes whether vCPU need to be |
|
||||
| | | |pinned to dedicated CPU core or |
|
||||
| | |- shared |shared dynamically |
|
||||
| | |- dedicated | |
|
||||
+-----------------+-------+------------+-------------------------------------+
|
||||
|thread_allocation|String |One of |Describes thread allocation |
|
||||
| | | |requirement |
|
||||
| | |- avoid | |
|
||||
| | |- separate | |
|
||||
| | |- isolate | |
|
||||
| | |- prefer | |
|
||||
+-----------------+-------+------------+-------------------------------------+
|
||||
|socket_count |Integer| None |Number of CPU sockets |
|
||||
+-----------------+-------+------------+-------------------------------------+
|
||||
|core_count |Integer| None |Number of cores per socket |
|
||||
+-----------------+-------+------------+-------------------------------------+
|
||||
|thread_count |Integer| None |Number of threads per core |
|
||||
+-----------------+-------+------------+-------------------------------------+
|
||||
|
||||
NUMA architecture
|
||||
"""""""""""""""""
|
||||
Following code snippet describes symmetric NUMA topology requirements for VDUs.
|
||||
|
||||
::
|
||||
|
||||
..
|
||||
VDU1:
|
||||
capabilities:
|
||||
nfv_compute:
|
||||
properties:
|
||||
numa_node_count: 2
|
||||
numa_nodes: 3
|
||||
|
||||
For asymmetric NUMA architecture:
|
||||
|
||||
::
|
||||
|
||||
..
|
||||
VDU1:
|
||||
capabilities:
|
||||
nfv_compute:
|
||||
properties:
|
||||
mem_size: 4096 MB
|
||||
num_cpus: 4
|
||||
numa_nodes:
|
||||
node0:
|
||||
id: 0
|
||||
vcpus: [0,1]
|
||||
mem_size: 1024 MB
|
||||
node1:
|
||||
id: 1
|
||||
vcpus: [2,3]
|
||||
mem_size: 3072 MB
|
||||
|
||||
:type:
|
||||
tosca.datatypes.compute.Container.Architecture.NUMA
|
||||
|
||||
:properties:
|
||||
|
||||
+--------+---------+-----------+-------------------------------------------+
|
||||
|Name |Type |Constraints|Description |
|
||||
+--------+---------+-----------+-------------------------------------------+
|
||||
|id |Integer | >= 0 |CPU socket identifier |
|
||||
+--------+---------+-----------+-------------------------------------------+
|
||||
|vcpus |Map of |None |List of specific host cpu numbers within a |
|
||||
| |integers | |NUMA socket complex |
|
||||
+--------+---------+-----------+-------------------------------------------+
|
||||
|mem_size|scalar- | >= 0MB |Size of memory allocated from this NUMA |
|
||||
| |unit.size| |memory bank |
|
||||
+--------+---------+-----------+-------------------------------------------+
|
||||
|
||||
Connection Points
|
||||
-----------------
|
||||
Connection point is used to connect the internal virtual link or outside
|
||||
virtual link. It may be a virtual port, a virtual NIC address, a physical port
|
||||
or a physical NIC address. Each connection point has to bind to a VDU. A CP
|
||||
always requires a virtual link and a virtual binding associated with it.
|
||||
|
||||
A code snippet for virtual NIC (Connection Point) without anti-spoof
|
||||
protection and is accessible by the user. It is connected to VDU1 and VL1.
|
||||
|
||||
::
|
||||
|
||||
..
|
||||
topology_template:
|
||||
node_templates:
|
||||
VDU1:
|
||||
..
|
||||
CP1:
|
||||
type: tosca.nodes.nfv.CP.Tacker
|
||||
properties:
|
||||
type: vnic
|
||||
anti_spoof_protection: false
|
||||
management: true
|
||||
requirements:
|
||||
- virtualLink:
|
||||
node: VL1
|
||||
- virtualBinding:
|
||||
node: VDU1
|
||||
VL1:
|
||||
..
|
||||
|
||||
:type:
|
||||
tosca.nodes.nfv.CP.Tacker
|
||||
|
||||
:properties:
|
||||
|
||||
+-------------------------+--------+-------+-----------+----------------------+
|
||||
| Name |Required|Type |Constraints| Description |
|
||||
+-------------------------+--------+-------+-----------+----------------------+
|
||||
| type | Yes |String | None | Could be anything |
|
||||
| | | | | like virtual port, |
|
||||
| | | | | virtual NIC address, |
|
||||
| | | | | physical port, |
|
||||
| | | | | physical NIC address |
|
||||
+-------------------------+--------+-------+-----------+----------------------+
|
||||
| anti_spoofing_protection| No |Boolean| None | Indicates whether |
|
||||
| | | | | anti_spoof rule is |
|
||||
| | | | | enabled for the VNF |
|
||||
| | | | | or not. Applicable |
|
||||
| | | | | only when CP type is |
|
||||
| | | | | virtual NIC |
|
||||
+-------------------------+--------+-------+-----------+----------------------+
|
||||
| management | No |Boolean| None | Specifies whether the|
|
||||
| | | | | CP is accessible by |
|
||||
| | | | | the user or not |
|
||||
+-------------------------+--------+-------+-----------+----------------------+
|
||||
|
||||
:requirements:
|
||||
|
||||
+---------------+--------------------+-------------------+-------------------+
|
||||
|Name |Capability |Relationship |Description |
|
||||
+---------------+--------------------+-------------------+-------------------+
|
||||
|virtualLink |nfv.VirtualLinkable |nfv.VirtualLinksTo |States the VL node |
|
||||
| | | |to connect to |
|
||||
+---------------+--------------------+-------------------+-------------------+
|
||||
|virtualbinding |nfv.VirtualBindable |nfv.VirtualBindsTo |States the VDU |
|
||||
| | | |node to connect to |
|
||||
+---------------+--------------------+-------------------+-------------------+
|
||||
|
||||
Virtual Links
|
||||
-------------
|
||||
Virtual link provides connectivity between VDUs. It represents the logical
|
||||
virtual link entity.
|
||||
|
||||
An example of a virtual link whose vendor is Acme and is attached to network
|
||||
net-01 is as shown below.
|
||||
|
||||
::
|
||||
|
||||
..
|
||||
topology_template:
|
||||
node_templates:
|
||||
VDU1:
|
||||
..
|
||||
CP1:
|
||||
..
|
||||
VL1:
|
||||
type: tosca.nodes.nfv.VL
|
||||
properties:
|
||||
vendor: Acme
|
||||
network_name: net-01
|
||||
|
||||
:type:
|
||||
tosca.nodes.nfv.VL
|
||||
|
||||
:properties:
|
||||
|
||||
+------------+----------+--------+-------------+-----------------------------+
|
||||
|Name | Required | Type | Constraints | Description |
|
||||
+------------+----------+--------+-------------+-----------------------------+
|
||||
|vendor | Yes | String | None | Vendor generating this VL |
|
||||
+------------+----------+--------+-------------+-----------------------------+
|
||||
|network_name| Yes | String | None | Name of the network to which|
|
||||
| | | | | VL is to be attached |
|
||||
+------------+----------+--------+-------------+-----------------------------+
|
||||
|
||||
Multiple nodes
|
||||
--------------
|
||||
Multiple node types can be defined in a VNFD.
|
||||
|
||||
::
|
||||
|
||||
..
|
||||
topology_template:
|
||||
node_templates:
|
||||
VDU1:
|
||||
..
|
||||
VDU2:
|
||||
..
|
||||
CP1:
|
||||
..
|
||||
CP2:
|
||||
..
|
||||
VL1:
|
||||
..
|
||||
VL2:
|
||||
..
|
||||
|
||||
Summary
|
||||
-------
|
||||
To summarize VNFD is written in YAML and describes a VNF topology. It has
|
||||
three node types, each with different capabilities and requirements. Below is
|
||||
a template which mentions all node types with all available options.
|
||||
|
||||
::
|
||||
|
||||
tosca_definitions_version: tosca_simple_profile_for_nfv_1_0_0
|
||||
description: Sample VNFD template mentioning possible values for each node.
|
||||
metadata:
|
||||
template_name: sample-tosca-vnfd-template-guide
|
||||
topology_template:
|
||||
node_templates:
|
||||
VDU:
|
||||
type: tosca.nodes.nfv.VDU.Tacker
|
||||
capabilities:
|
||||
nfv_compute:
|
||||
properties:
|
||||
mem_page_size: [small, large, any, custom]
|
||||
cpu_allocation:
|
||||
cpu_affinity: [shared, dedicated]
|
||||
thread_allocation: [avoid, separate, isolate, prefer]
|
||||
socket_count: any integer
|
||||
core_count: any integer
|
||||
thread_count: any integer
|
||||
numa_node_count: any integer
|
||||
numa_nodes:
|
||||
node0: [ id: >=0, vcpus: [host CPU numbers], mem_size: >= 0MB]
|
||||
properties:
|
||||
image: Image to be used in VM
|
||||
flavor: Nova supported flavors
|
||||
availability_zone: available availability zone
|
||||
mem_size: in MB
|
||||
disk_size: in GB
|
||||
num_cpus: any integer
|
||||
metadata:
|
||||
entry_schema:
|
||||
config_drive: [true, false]
|
||||
monitoring_policy:
|
||||
name: [ping, noop, http-ping]
|
||||
parameters:
|
||||
monitoring_delay: delay time
|
||||
count: any integer
|
||||
interval: time to wait between monitoring
|
||||
timeout: monitoring timeout time
|
||||
actions:
|
||||
[failure: respawn, failure: terminate, failure: log]
|
||||
retry: Number of retries
|
||||
port: specific port number if any
|
||||
config: Configuring the VDU as per the network function requirements
|
||||
mgmt_driver: [default=noop]
|
||||
service_type: type of network service to be done by VDU
|
||||
user_data: custom commands to be executed on VDU
|
||||
user_data_format: format of the commands
|
||||
key_name: user key
|
||||
artifacts:
|
||||
VNFImage:
|
||||
type: tosca.artifacts.Deployment.Image.VM
|
||||
file: file to be used for image
|
||||
CP:
|
||||
type: tosca.nodes.nfv.CP.Tacker
|
||||
properties:
|
||||
management: [true, false]
|
||||
anti_spoofing_protection: [true, false]
|
||||
type: [ sriov, vnic ]
|
||||
requirements:
|
||||
- virtualLink:
|
||||
node: VL to link to
|
||||
- virtualBinding:
|
||||
node: VDU to bind to
|
||||
VL:
|
||||
type: tosca.nodes.nfv.VL
|
||||
properties:
|
||||
network_name: name of network to attach to
|
||||
vendor: Acme
|
@ -48,6 +48,7 @@ Feature Documentation
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
devref/vnfd_template_description.rst
|
||||
devref/monitor-api.rst
|
||||
devref/vnfd_template_parameterization.rst
|
||||
devref/enhanced_placement_awareness_usage_guide.rst
|
||||
|
Loading…
Reference in New Issue
Block a user