Skip to end of metadata
Go to start of metadata

Supporting Documentation: ONAP Wiki Design Time Data Model

In order to import a Virtual Function Component (VFC) into the SDC portal using .YAML/YML files, please follow the guidelines and examples laid out below.


Primary Steps

The primary steps required for importing a VFC are as follows:

  • Login to the SDC Portal as a designer. (User: cs0008 Password: demo123456!)
  • Create a .YAML or .YML file containing the required information about the VFC
  • Use the “Import VFC” button found in the “Home” tab of SDC
  • Fill in required metadata for differentiating the VFC
  • Press “Create”


YAML/YML File Format

The most important aspect is correctly coding your .YAML/YML file. This file will define the node_type, properties, capabilities and requirements of your VFC.


TOSCA Definition Version

The TOSCA definition version must reside in the first line of the file. The correct version to use currently is: tosca_simple_yaml_1_1. (This may change in the future.) The version is defined by using the statement:

tosca_definitions_version: tosca_simple_yaml_1_1 

Node Type

The node type is used to define which nodes this node is derived from. A full list of possible node types can be found in the supporting document mentioned at the top of this page. Currently the correct node type to use for a VFC import is:

org.openecomp.resource.{chosenName}.{optionalAddition}

Where {chosenName} is replaced with your chosen name for the new VFC node you are creating. This node type name can be extended, for differentiation purposes, by adding optional further names. Simply by adding a period “ . “ and then your optional name after the {chosenName} section of the node type namespace, you can differentiate between new node types. You can also add multiple {optionalAddition}’s to the end of the namespace. Below you can find multiple examples of working VFC node type namespaces for VFC importing:

The node type namespace must be followed by a definition of the node type from which your VFC will be derived. This is defined through the statement:

derived_from: {chosenNodeType}

Where {chosenNodeType} is the node type that your VFC will be derived from. The majority of VFC’s will be derived from the base node type which is as follows:

tosca.nodes.Root

Should you choose to derive your VFC from another VFC, for example, your new VFC will inherit all of the properties, capabilities and requirements of the parent node. The node type is extremely important, as it is the primary method of differentiating the VFC’s that you create/import in SDC.

Other than the TOSCA definition version and the node type definition, the remaining “properties”, “capabilities” and “requirements” can come in any order and the VFC import function will still recognise the file format. The best practise however is to order them with “properties” coming first, directly below the node type definition, then followed by “capabilities” and finally “requirements”. This is the layout that an exported TOSCA template from SDC follows. Should a VFC have no “properties”, “capabilities” or “requirements” they can safely be left out of the template.


Properties [Optional]

The properties are user defined and can be given individual descriptions, types and default values. The properties of a VFC are defined directly below the node type definition. They follow the format found below:


properties:

{property1Name}:

                                {property1Detail1}

                                {property1Detail2}

                                {property1Detail3}

{property2Name}:

                                {property2Detail1}

                                {property2Detail2}

                                {property2Detail3}

 

Where {property1Name} is the user defined name of the first property of the VFC and {property1Detail1} through to {property1Detail3} are the defining aspects of the property {property1Name}. A VFC can also have any number of different properties, providing they follow the correct format.

Below is an example layout of a simple property for a VFC:


properties:

                integerProperty:

                                type: integer

                                description: A test integer

                                default: 1

stringProperty:

                                type: string

                                description: A test string

                                default: The default string

 

The only required definition in a property is its “type”. The “description” and “default” definitions are optional on all properties.

These properties can be found in the VFC’s “Properties” tab once imported/created, the default values for them can also be entered on this page. However, before a VFC is used within a service, the properties will need to be declared for them to be editable within the service’s own “Properties” tab. This can be achieved by ticking the check box to the left of each property you want to declare, in the VFC’s “Properties” tab, and then pressing declare at the top of the properties box.


Capabilities [Optional]

The capabilities of a node refer to it’s ability to be "connected" to by other nodes, based on their requirements. The capabilities generally follow the layout of the properties above as can be seen from the format shown below:


capabilities:

{capabilityName}:

type: {capabilityType}

occurrences:

- {numberOfOccurences}

- {boundedORUnbounded}

 

Where {capabilityName} is the user defined name of the capability, {capabilityType} is the type of capability, {numberOfOccurences} is an integer referring to the number of this type of capability that exist for this VFC and {boundedOrUnbounded} is either “BOUNDED” or “UNBOUNDED” as required.

You cannot have multiple entries of the same type of capability, instead please ensure you simply increment the {numberOfOccurences} integer as required. A full list of possible capability types can be found in the supporting document mentioned at the top of this page.


Requirements [Optional]

The requirements of a VFC follow a very similar format to the capabilities, with slight differences. Namely they require a reference to the type of capability that they “connect” to and a reference to the type of relationship involved. The following layout shows how a requirement should be formatted:


requirements:

- {requirementName}:

occurrences:

- {numberOfOccurences}

- {boundedORUnbounded}

capability: {capabilityTypeReference}

relationship: {relationshipTypeReference}

 

Where {requirementName} is the user defined name of the capability, {numberOfOccurences} is an integer referring to the number of this type of capability that exist for this VFC and {boundedOrUnbounded} is either “BOUNDED” or “UNBOUNDED” as required. {capabilityTypeReference} is the type of capability type that can connect to this requirement and {relationshipTypeReference} is the type of relationship involved with this requirement. A full list of possible capability types and relationship types can be found in the supporting document mentioned at the top of this page.


Example Formats

Here you can find multiple example .YAML/YML files for importing/creating VFC’s

Example 1

Below you can find the simplest .YAML/YML file layout possible to import as a VFC:


tosca_definitions_version: tosca_simple_yaml_1_1

node_types:

org.openecomp.resource.{chosenName}:

derived_from: tosca.nodes.Root

 

Where {chosenName} is any string of your choice, it must be different to all other nodes within SDC.

This VFC will contain no properties, and no capabilities/requirements. (Note: due to the VFC being derived from the tosca.nodes.Root, they will receive a simple node dependency requirement and a node feature capability, all nodes must have at least these as the simplest node you can derive from is the Root node.)


Example 2

Below you can find a .YAML/YML file layout for importing a VFC with some simple properties, 2 binding requirements and 2 binding capabilities:


tosca_definitions_version: tosca_simple_yaml_1_1

node_types:

org.openecomp.resource.vfc.BindingNode:

derived_from: tosca.nodes.Root

properties:

role:

description: A string for defining the role of this node.

type: string

numberId:

type: integer

description: An integer for defining the number ID of this node.

default: 1

active:

type: boolean

description: A boolean for verifying if this node is active.

default: true

capabilities:

binding:

type: tosca.capabilities.network.Bindable

occurrences:

- 2

- UNBOUNDED

requirements:

- binding:

occurrences:

- 2

- UNBOUNDED

capability: tosca.capabilities.network.Bindable

relationship: tosca.relationships.network.BindsTo


Hello World Example of Capabilities/Requirements


As both capabilities and requirements are required in order to "connect" different nodes, it is possible to define nodes with only capabilities, requirements or both. 

The image shown below shows a snippet from the "Composition" view of a Virtual Function (VF). It shows a single node with the "Bindable" requirement binding to a single node with a "Bindable" capability.

Building upon this example, a third type of node which has a "Bindable" requirement and capability is placed between the 2 previous nodes. This can been seen in the image below:


 

The 3 .YML files used to import the individual VFCs can be found below:

These VFCs were then added into a VF and bound together within the "Composition" view. The VF was then exported in a .CSAR file archive, the typical TOSCA artifact export type from SDC. The .CSAR can be found below:


Should you have any questions relating to this topic, please comment them below.

Supporting Links:

The links below can supplement VFC creation, troubleshooting and service design using the VFCs:

ONAP Glossary: https://wiki.onap.org/display/DW/Glossary

Error logging: http://onap.readthedocs.io/en/latest/submodules/sdc.git/docs/logging.html#pol4050

Service Design: http://onap.readthedocs.io/en/latest/guides/onap-user/servicedesigner.html





4 Comments

  1. Is "VFC" here referring to "Virtual Function Component" or "Virtual Function Controller"?

  2. It refers to Virtual Function Component. I've updated the post as I noticed that I mentioned Controller when I meant Component, thank you. 

  3. On ONAP Casablanca importing example resource-BindingTutorialVirtualFunction-csar.csar give errors:

    ERROR
    Each CSAR file must contain MainServiceTemplate.mf file.
    ERROR
    Each CSAR file must contain MainServiceTemplate.yaml file.
    ERROR
    File : csar.meta , are not allowed.

    Seams like example file is outdated.

  4. Hi Marek,

    The example CSAR resource-BindingTutorialVirtualFunction-csar.csar is the CSAR that is exported from SDC, not an example to be used for onboarding. It simply contains all of the artifacts/files that make up the service and VNF(s).

    The example is not outdated, it is a different type of CSAR. If you need a CSAR for onboarding a VSP/Service then you will need to follow a completely different layout, or SDC will not accept it.


    If you do need an example version of a CSAR for onboarding services, please let me know and I can provide one.