VNF Parameter resolution templating

Overview

When instantiating a Service composed of connectivity, PNF, VNF or CNF there is the need to set the parameter values for the created instances.

For example, it may be necessary to provide a VNF management @ip Address or a VNF instance name. Those parameters can be necessary to create cloud resources or to configure the VNF at application level.

In the first releases of ONAP the operator needed to provide these parameters as preload data via datasheet or API call before instantiating each PNF/VNF/CNF. This was an error-prone manual step that interferes with an automated and scalable service instantiation. As part of the ONAP CDS component introduction in Casablanca release, the user, that wants to instantiate a new VNF/CNF, does not need to get and provide those data.

Of course the “user” may be a human but may be also an application that uses the “instantiation” API on ONAP NBI or ONAP SO.

ONAP CDS component is then in charge of resolving those parameters automatically.

The detailed CDS documentation can be found here: CONTROLLER DESIGN STUDIO (CDS)

It offers automated solution out of the box by delivering network intent declarative package during design time phase that automated the provisioning and/or network configuration network intent.

At instantiation time, CDS controller will find (assign) the values according some “recipies” described in a “Controller Blueprint Archive”: a collection of files that CDS controller will use to proceed parameter resolution.

Thanks to CDS, at instantiation time, the user, that wants to instantiate a new VNF, does not need to get and provide those data himself. Of course the “user” may be a human but may be also an application that uses the “instantiation” API on ONAP NBI or ONAP SO.

Less effort for the “user”, but more effort for the “designer” that needs to pre-defined all necessary recipies during design time.

The purpose of the following text is to describe various files and content that are necessary to the CDS controller to resolve any parameters.

To illustrate the subject, let’s take an example: a service composed of an “ubuntu” VNF. That service will be called “ubuntuCDS” in ONAP SDC for that example.

That VNF will be based on a simple ubuntu image. That VF will be called ubuntuCDS in ONAP SDC for that example.

WARNING: all operations need to be adapted to your context (platform, service, identifiers…)

Pre-requisite

There are two problems with ONAP ElAlto release:

wrong Directed Graphs

In ONAP Elalto, a problem was detected about Directed Graphs: JIRA_SDNC_949

The workaround is to upload/replace the following two Directed Graph in SDNC (via DG Builder UI for example).

VNF topology assign: DG_VNF_ASSIGN.

VF-Module topology assign: DG_VFMODULE_ASSIGN.

wrong URL in CDS-UI pod

CDS-UI pod needs to communicate with CDS BluePrint processor to perform “enrichment”, “publish”, “deploy” operations.

The URL is not correct in the OOM file used to deploy CDS UI.

If you have permission, you can change the url via:

kubectl edit deployment -n onap {{cds ui pod id}}

API_BLUEPRINT_CONTROLLER_HTTP_BASE_URL parameter must have the following value

http://cds-blueprints-processor-http:8080/api/v1

Those problems should be corrected in next ONAP release.

Design process

Step 1: identify the parameters needed for instantiation

To instantiate an “ubuntu” VNF, a Heat Template can be used. Several parameters are defined in that template: vnf_name, image_name, management @ip…

This Heat Template is a first place to identify the parameters that need to be resolved.

Our example:

parameters:
# Metadata required by ONAP
vnf_id: ubuntuCDS-VNF
vf_module_id: ubuntuCDS-VF-module
vnf_name: ubuntuCDS-VNF-name

# Server parameters, naming required by ONAP
ubuntuCDS_image_name: ubuntu-18
ubuntuCDS_flavor_name: onap.small
ubuntuCDS_pub_key: ssh-rsa AAAAB3VHCx...vVL8l1BrX3BY0R8D imported-openssh-key
ubuntuCDS_name_0: ubuntuCDS

# Network parameters, naming required by ONAP
admin_plane_net_name: admin

Step 2: identify the parameters needed for post-instantiation

Post-instantiation activity will occur after the VNF is instantiated.

Typically, it can be adding a first firewall rule in a firewall VNF.

In the ubuntuCDS example, there is no such parameter.

Step 3: identify the resolution method for each parameter

Here after the decision/solution that the designer may take:

vnf_name will be resolved via an input that will be provided in the instantiation request.

ubuntuCDS_image_name will be resolved via an input that will be provided in the instantiation request.

ubuntuCDS_flavor_name will be resolved via an input that will be provided in the instantiation request.

ubuntuCDS_pub_key will be resolved via an input that will be provided in the instantiation request.

admin_plane_net_name will be resolved via an input that will be provided in the instantiation request.

Service Designer needs also to know that some parameters will be automatically resolved by ONAP SO and/or ONAP SDNC.

  • service-instance-id

  • vnf-id

  • vf_module_id

For each resolution method, Service Designer needs to identify all necessary parameters that must be provided to the resoluton method in order to obtain the resolution.

Also, Service Designer needs to know that ONAP will instantiate a service, a list of VNF that are composing the service and, for each VNF, a “VF-module” will be instantiated.

Step 4: add new data definition in CDS resource dictionary

In CDS, there is a database that will contain all resource Definitions in order to be able to re-use those resources from one service to an other.

Service Designer needs to check about existing resource definitions in the dictionary.

By default, some resources are pre-loaded when installing ONAP platform.

Preloaded resources (parameter definition): Resources.

Be careful: the content of the resource dictionary is not the same from one ONAP release to an other.

If Service Designer sees that there is an existing parameter that corresponds to the need, he has the possibility to re-use it in the mapping file(s), but maybe with a different name.

For example, “image_name” is already defined in the resource dictionary but, it is named “freeRadius_image_name” in the Heat files.

For the ubuntuCDS example, there is no need to add any entry in the data_dictionary

“curls” requests example to declare a new resource Here

Step 5: write template files

In this Ubuntu example, Designer needs to create 2 “templates” files. Naming of those files is important. For VNF, prefix name must be equal to the VF name in ONAP SDC. For the VFmodule, prefix name must be equal to the name of the Heat template.

CDS makes use of “velocity template” or “Jinja template” files.

This way, CDS is able to generate the desired datastructure with resolved values, that will then be sent to the target system:

  • openstack when instantiating the Heat stack

  • instantiated VNF when doing some post-instantiation operation

There are two sections in each velocity file:

  • “resource-accumulator-resolved-data”: a list of all parameters

  • “capability-data”: a list of “capabilities” to process and resolve a parameter

A capability can be an other way to resolve a parameter, using a directed graph.

A capability may also be an action to be performed such as modifying a data in ONAP AAI.

ONAP SDNC provides those “capabilities”:

  • generate-name

  • vlan-tag-assign

  • netbox-ip-assign

  • aai-vnf-put

There is an SDNC Directed Graph associated to each of those “capability”.

Service Designer needs to know about those capabilities with their input/output, in order to re-use them. Especially, Service Designer needs to know inputs because those inputs need to be part of the templates.

In case Service Designer wants to use a new capability, a solution is to create a Directed Graph and update the self-serve-vnf-assign and/or self-serve-vf-module-assign Directed Graph by adding a new entry in the list of capabilities (node: set ss.capability.execution-order[])

The “aai-vfmodule-put” capability is important to be part of a vf-module template because it will be used to put the vf-module-name in AAI and ONAP SO will use that value to name the heat stack.

image3

About the name/value of each parameter, Service Designer needs to understand how various information will map between the various files needed by CDS.

image5

And be very careful with “_” or “-”

Step 6: write mapping files

Along with each velocity template, Designer needs to create a “mapping” file.

This is the place where the Designer explains, for each parameter:

  • value source: the system or database that will provide the value

  • default value

At VNF instantiation step, values are often coming from input (in the request sent by the user, in the “instanceParams” section of the vnf).

At VF module instantion step, values can come form input also in the request sent by the user, in the “instanceParams” section of the vf-module)

Resolved data are always stored in SDNC database (MDSAL)

Note1: if service designer wants to re-use for vf-module a parameter/value from VNF “userParams” section, then the source will be from “SDNC” in the vf-module mapping file.

Note2: service-instance-id, vnf-id and vf_module_id are parameters considered as “input” from CDS point of view but in reality they are resolved by ONAP SO with ONAP AAI. Thus, those parameters are not “input” from ONAP SO point of view: service designer has not need to provide those parameters in service instantiation request (step 12).

For the ubuntu example, there are then 2 mapping files. File names are important and must be aligned with vtl template names.

Step 7: write scripts

Sometimes, it will be necessary to use some scripts (python, kotlin, ansible…) to process some post-configuration operation.

Those scripts needs to be part of the “Controller Blueprint Archive” (cba).

No such script for the ubuntuCDS example.

Step 8: write the “blueprint” file

The “designer” will then create a “blueprint”.

It is a JSON file and for the ubuntuCDS usecase, it is called ubuntuCDS.json. Name must be aligned with VF name in ONAP SDC.

This file will be the main entry point for CDS blueprint processor. This processor will use that file to understand what need to be processed and how to process it.

The content of that file is composed of several sections conforming to TOSCA specifications.

image1

For the ubuntu example CDS blueprint before enrichment.

This example is the minimum that is required to simply instantiate a VNF.

Some extension can then be added in order to define additional operations.

Step 9: build the “Controller Blueprint Archive” (cba)

Having created velocity templates, mapping files and a first CDS blueprint version, it is now simple to create the “Controller Blueprint Archive” (cba).

This is a “zip-like” archive file that will have the following structure and content (“environment”, “scripts” and “plans” are optional):

image2

For the ubuntu example cba archive before enrichment.

To complete that cba, an “enrichment” operation is needed.

Service Designer can use two methods:

  • using CDS User Interface

  • using CDS rest API

Service Designer needs to send the cba to CDS-UI pod and requests the enrichment, then save and then download.

Result will be that the cba will now contains several new files in “Definition” folder of the cba.

The “blueprint” file will also be completed.

The “enriched” cba is now ready to be onboarded in ONAP SDC along with a service definition.

For the ubuntu example cba archive after enrichment.

Step 10: attached the cba to a service definition

In SDC, when defining a VF, Designer will attach the cba archive to the VF definition, using the “deployment artifact” section.

Having define all necessary VF, Service Designer will create a SERVICE in SDC.

Service Designer will compose the SERVICE with appropriate VF(s) and will have to modify PROPERTIES in the “properties assignement” section.

Service Designer needs to provide values for sdnc_artifact_name, sdnc_model_name and sdnc_model_verion.

This will tell SO which blueprint to use for the service model that is being instantiate

SDC sdnc_artifact_name = CBA blueprint json filename, e.g. “ubuntuCDS”, we will see below that we will have vnf-mapping.json and vnf-template.vtl templates in the blueprint.

SDC sdnc_model_name = CBA Metadata template_name, e.g. “ubuntuCDS”, we can see in the below screenshot the metadata section showing template name.

SDC sdnc_model_verion = CBA Metadata template_version, e.g. “1.0.0”, we can see in the below screenshot the metadata section showing template version.

image4

Step 11: distribute the service

In SDC, when distributing the service, the CDS controller will be informed that a new cba archive is available.

CDS controller will then collect the cba archive.

Step 12: instantiate the service and check

Here is an example of an ONAP SO api request to instantiate the ubuntu service.

This request is used to instantiate a service using the “Macro” mode.

Do not try to use that example as-is: you need to adapt all values to your platform/service model.

In this example, the request contains several “inputs” at VNF level and several “inputs” at VF-module level.

All various “id” and “version” are some copy/paste information that Service Designer has the possibility to find in the TOSCA service template created in ONAP SDC.

This request will instantiate a “service”, a “VNF” and a “VF-module”. That “service” instance is attached to the customer named “JohnDoe” with service subscription named “ubuntCDS” (supposed already declared in your ONAP AAI).

In case the instantiation fails, a roolback is performed (parameter “suppressRollback” = false)

For that example, no “homing” and the “cloud” tenant is explicitely provided (supposed already declared in your ONAP AAI)

curl -X POST \
http://so.api.simpledemo.onap.org:30277/onap/so/infra/serviceInstantiation/v7/serviceInstances \
-H 'Accept: application/json' \
-H 'Authorization: Basic SW5mcmFQb3J0YWxDbGllbnQ6cGFzc3dvcmQxJA==' \
-H 'Content-Type: application/json' \
-H 'X-ONAP-PartnerName: NBI' \
-H 'cache-control: no-cache' \
-d '{
   "requestDetails": {
      "subscriberInfo": {
            "globalSubscriberId": "JohnDoe"
      },
      "requestInfo": {
            "suppressRollback": false,
            "productFamilyId": "Useless_But_Mandatory",
            "requestorId": "adt",
            "instanceName": "My_ubuntuCDS_service_instance_001",
            "source": "VID"
      },
      "cloudConfiguration": {
            "lcpCloudRegionId": "RegionOne",
            "tenantId": "71cf9d931d9e4b8e9fcca50d97c1cf96",
            "cloudOwner": "ONAP"
      },
      "requestParameters": {
            "subscriptionServiceType": "ubuntuCDS",
            "userParams": [
               {
                  "Homing_Solution": "none"
               },
               {
                  "service": {
                        "instanceParams": [],
                        "instanceName": "My_ubuntuCDS_service_instance_001",
                        "resources": {
                           "vnfs": [
                              {
                                    "modelInfo": {
                                       "modelName": "ubuntuCDS",
                                       "modelVersionId": "c6a5534e-76d5-4128-97bf-ad3b72208d53",
                                       "modelInvariantUuid": "ed3064e7-62c0-494c-bb9b-4f56d1ad157e",
                                       "modelVersion": "1.0",
                                       "modelCustomizationId": "6a32fb56-191e-4d11-a0cc-44b779aba4fc",
                                       "modelInstanceName": "ubuntuCDS 0"
                                    },
                                    "cloudConfiguration": {
                                       "lcpCloudRegionId": "RegionOne",
                                       "tenantId": "71cf9d931d9e4b8e9fcca50d97c1cf96"
                                    },
                                    "platform": {
                                       "platformName": "Useless_But_Mandatory"
                                    },
                                    "productFamilyId": "Useless_But_Mandatory",
                                    "instanceName": "My_VNF_ubuntuCDS_instance_001",
                                    "instanceParams": [
                                       {
                                          "vnf_name": "My_VNF_ubuntuCDS_instance_001"
                                       }
                                    ],
                                    "vfModules": [
                                       {
                                          "modelInfo": {
                                                "modelName": "Ubuntucds..base_ubuntuCDS..module-0",
                                                "modelVersionId": "3025cd36-b170-4667-abb1-2bae1f297844",
                                                "modelInvariantUuid": "0101f9e0-7beb-4b58-92c7-ba3324b5a54d",
                                                "modelVersion": "1",
                                                "modelCustomizationId": "9bca4d4b-e27c-4652-a61e-b1b4ebca503d"
                                          },
                                          "instanceName": "My_vfModule_ubuntuCDS_instance_001",
                                          "instanceParams": [
                                                {
                                                   "vnf_name": "My_VNF_ubuntuCDS_instance_001",
                                                   "vf_module_name": "My_vfModule_ubuntuCDS_instance_001",
                                                   "ubuntuCDS_pub_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDY15cdBmIs2XOpe4EiFCsaY6bmUmK/GysMoLl4UG51JCfJwvwoWCoA+6mDIbymZxhxq9IGxilp/yTA6WQ9s/5pBag1cUMJmFuda9PjOkXl04jgqh5tR6I+GZ97AvCg93KAECis5ubSqw1xOCj4utfEUtPoF1OuzqM/lE5mY4N6VKXn+fT7pCD6cifBEs6JHhVNvs5OLLp/tO8Pa3kKYQOdyS0xc3rh+t2lrzvKUSWGZbX+dLiFiEpjsUL3tDqzkEMNUn4pdv69OJuzWHCxRWPfdrY9Wg0j3mJesP29EBht+w+EC9/kBKq+1VKdmsXUXAcjEvjovVL8l1BrX3BY0R8D imported-openssh-key",
                                                   "ubuntuCDS_image_name": "ubuntu-18.04-daily",
                                                   "ubuntuCDS_flavor_name": "onap.small",
                                                   "ubuntuCDS_name_0": "ubuntuCDS-VM-001",
                                                   "admin_plane_net_name": "admin"
                                                }
                                          ]
                                       }
                                    ]
                              }
                           ]
                        },
                        "modelInfo": {
                           "modelVersion": "1.0",
                           "modelVersionId": "10369444-1e06-4d5d-974b-362bcfd19533",
                           "modelInvariantId": "32e00b49-eff8-443b-82a8-b75fbb6e3867",
                           "modelName": "ubuntuCDS",
                           "modelType": "service"
                        }
                  }
               }
            ],
            "aLaCarte": false,
            "usePreload": false
      },
      "owningEntity": {
            "owningEntityId": "Useless_But_Mandatory",
            "owningEntityName": "Useless_But_Mandatory"
      },
      "modelInfo": {
            "modelVersion": "1.0",
            "modelVersionId": "10369444-1e06-4d5d-974b-362bcfd19533",
            "modelInvariantId": "32e00b49-eff8-443b-82a8-b75fbb6e3867",
            "modelName": "ubuntuCDS",
            "modelType": "service"
      }
   }
}'

In response, ONAP SO will immediately provide a requestId and a service instance id.

The instantiation will take some time. It will be necessary to perform a “GET” on the request to check the result.

curl -X GET \
   http://so.api.simpledemo.onap.org:30277/onap/so/infra/orchestrationRequests/v7/{{requestID}} \
   -H 'Accept: application/json' \
   -H 'Authorization: Basic SW5mcmFQb3J0YWxDbGllbnQ6cGFzc3dvcmQxJA==' \
   -H 'Content-Type: application/json' \
   -H 'X-FromAppId: AAI' \
   -H 'X-TransactionId: get_aai_subscr' \
   -H 'cache-control: no-cache'

To delete the service instance, just add the service_instance_id in the URL and send a DELETE operation.

curl -X DELETE \
http://so.api.simpledemo.onap.org:30277/onap/so/infra/serviceInstantiation/v7/serviceInstances/{{service_instance_Id}} \
-H 'Accept: application/json' \
-H 'Authorization: Basic SW5mcmFQb3J0YWxDbGllbnQ6cGFzc3dvcmQxJA==' \
-H 'Content-Type: application/json' \
-H 'X-ONAP-PartnerName: NBI' \
-H 'cache-control: no-cache' \
-d '{
   "requestDetails": {
      "subscriberInfo": {
            "globalSubscriberId": "JohnDoe"
      },
      "requestInfo": {
            "suppressRollback": false,
            "productFamilyId": "Useless_But_Mandatory",
            "requestorId": "adt",
            "instanceName": "My_ubuntuCDS_service_instance_001",
            "source": "VID"
      },
      "cloudConfiguration": {
            "lcpCloudRegionId": "RegionOne",
            "tenantId": "71cf9d931d9e4b8e9fcca50d97c1cf96",
            "cloudOwner": "ONAP"
      },
      "requestParameters": {
            "subscriptionServiceType": "ubuntuCDS",
            "userParams": [
               {
                  "Homing_Solution": "none"
               },
               {
                  "service": {
                        "instanceParams": [],
                        "instanceName": "My_ubuntuCDS_service_instance_001",
                        "resources": {
                           "vnfs": [
                              {
                                    "modelInfo": {
                                       "modelName": "ubuntuCDS",
                                       "modelVersionId": "c6a5534e-76d5-4128-97bf-ad3b72208d53",
                                       "modelInvariantUuid": "ed3064e7-62c0-494c-bb9b-4f56d1ad157e",
                                       "modelVersion": "1.0",
                                       "modelCustomizationId": "6a32fb56-191e-4d11-a0cc-44b779aba4fc",
                                       "modelInstanceName": "ubuntuCDS 0"
                                    },
                                    "cloudConfiguration": {
                                       "lcpCloudRegionId": "RegionOne",
                                       "tenantId": "71cf9d931d9e4b8e9fcca50d97c1cf96"
                                    },
                                    "platform": {
                                       "platformName": "Useless_But_Mandatory"
                                    },
                                    "productFamilyId": "Useless_But_Mandatory",
                                    "instanceName": "My_VNF_ubuntuCDS_instance_001",
                                    "instanceParams": [
                                       {
                                          "vnf_name": "My_VNF_ubuntuCDS_instance_001"
                                       }
                                    ],
                                    "vfModules": [
                                       {
                                          "modelInfo": {
                                                "modelName": "Ubuntucds..base_ubuntuCDS..module-0",
                                                "modelVersionId": "3025cd36-b170-4667-abb1-2bae1f297844",
                                                "modelInvariantUuid": "0101f9e0-7beb-4b58-92c7-ba3324b5a54d",
                                                "modelVersion": "1",
                                                "modelCustomizationId": "9bca4d4b-e27c-4652-a61e-b1b4ebca503d"
                                          },
                                          "instanceName": "My_vfModule_ubuntuCDS_instance_001",
                                          "instanceParams": [
                                                {
                                                   "vnf_name": "My_VNF_ubuntuCDS_instance_001",
                                                   "vf_module_name": "My_vfModule_ubuntuCDS_instance_001",
                                                   "ubuntuCDS_pub_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDY15cdBmIs2XOpe4EiFCsaY6bmUmK/GysMoLl4UG51JCfJwvwoWCoA+6mDIbymZxhxq9IGxilp/yTA6WQ9s/5pBag1cUMJmFuda9PjOkXl04jgqh5tR6I+GZ97AvCg93KAECis5ubSqw1xOCj4utfEUtPoF1OuzqM/lE5mY4N6VKXn+fT7pCD6cifBEs6JHhVNvs5OLLp/tO8Pa3kKYQOdyS0xc3rh+t2lrzvKUSWGZbX+dLiFiEpjsUL3tDqzkEMNUn4pdv69OJuzWHCxRWPfdrY9Wg0j3mJesP29EBht+w+EC9/kBKq+1VKdmsXUXAcjEvjovVL8l1BrX3BY0R8D imported-openssh-key",
                                                   "ubuntuCDS_image_name": "ubuntu-18.04-daily",
                                                   "ubuntuCDS_flavor_name": "onap.small",
                                                   "ubuntuCDS_name_0": "ubuntuCDS-VM-001",
                                                   "admin_plane_net_name": "admin"
                                                }
                                          ]
                                       }
                                    ]
                              }
                           ]
                        },
                        "modelInfo": {
                           "modelVersion": "1.0",
                           "modelVersionId": "10369444-1e06-4d5d-974b-362bcfd19533",
                           "modelInvariantId": "32e00b49-eff8-443b-82a8-b75fbb6e3867",
                           "modelName": "ubuntuCDS",
                           "modelType": "service"
                        }
                  }
               }
            ],
            "aLaCarte": false,
            "usePreload": false
      },
      "owningEntity": {
            "owningEntityId": "Useless_But_Mandatory",
            "owningEntityName": "Useless_But_Mandatory"
      },
      "modelInfo": {
            "modelVersion": "1.0",
            "modelVersionId": "10369444-1e06-4d5d-974b-362bcfd19533",
            "modelInvariantId": "32e00b49-eff8-443b-82a8-b75fbb6e3867",
            "modelName": "ubuntuCDS",
            "modelType": "service"
      }
   }
}'

Trouble shooting

Have a look to

  • debug.log in CDS blueprint processor pod

  • debug.log into SO Bpmn pod

  • karaf.log into SDNC pod