1 .. This work is licensed under a Creative Commons Attribution 4.0
2 .. International License. http://creativecommons.org/licenses/by/4.0
3 .. Copyright 2019 ONAP Contributors. All rights reserved.
5 .. _doc_guide_user_des_param_assign:
7 VNF Parameter resolution templating
8 ===================================
13 When instantiating a Service composed of connectivity, PNF,
14 VNF or CNF there is the need to set the parameter values for the
17 For example, it may be necessary to provide a VNF management @ip
18 Address or a VNF instance name. Those parameters can be necessary
19 to create cloud resources or to configure the VNF at application level.
21 In the first releases of ONAP the operator needed to provide these parameters
22 as preload data via datasheet or API call before instantiating each
24 This was an error-prone manual step that interferes with an automated and
25 scalable service instantiation.
26 As part of the ONAP CDS component introduction
27 in Casablanca release, the user, that wants to instantiate a new VNF/CNF,
28 does not need to get and provide those data.
30 Of course the “user” may be a human but may be also an application that uses
31 the “instantiation” API on ONAP NBI or ONAP SO.
33 ONAP CDS component is then in charge of resolving those parameters
40 Full CDS documentation is here <../../../../submodules/ccsdk/cds.git/docs/index.rst>
42 It offers automated solution out of the box by delivering network intent
43 declarative package during design time phase that automated the provisioning
44 and/or network configuration network intent.
46 At instantiation time, CDS controller will find (assign) the values
47 according some “recipies” described in a "Controller Blueprint Archive”:
48 a collection of files that CDS controller will use to proceed
51 Thanks to CDS, at instantiation time, the user, that wants to instantiate
52 a new VNF, does not need to get and provide those data himself.
53 Of course the “user” may be a human but may be also
54 an application that uses the “instantiation” API on ONAP NBI or ONAP SO.
56 Less effort for the “user”, but more effort for the “designer”
57 that needs to pre-defined all necessary recipies
60 The purpose of the following text is to describe various files and content
61 that are necessary to the CDS controller to resolve any parameters.
63 To illustrate the subject, let's take an example: a service composed of
64 an "ubuntu" VNF. That service will be called "ubuntuCDS" in ONAP SDC
67 That VNF will be based on a simple ubuntu image. That VF will be called
68 ubuntuCDS in ONAP SDC for that example.
70 WARNING: all operations need to be adapted to your context
71 (platform, service, identifiers...)
76 There are two problems with ONAP ElAlto release:
78 **wrong Directed Graphs**
80 In ONAP Elalto, a problem was detected about Directed Graphs: JIRA_SDNC_949_
82 The workaround is to upload/replace the following two Directed Graph in SDNC
83 (via DG Builder UI for example).
85 VNF topology assign: DG_VNF_ASSIGN_.
87 VF-Module topology assign: DG_VFMODULE_ASSIGN_.
90 **wrong URL in CDS-UI pod**
92 CDS-UI pod needs to communicate with CDS BluePrint processor to perform
93 "enrichment", "publish", "deploy" operations.
95 The URL is not correct in the OOM file used to deploy CDS UI.
97 If you have permission, you can change the url via:
101 kubectl edit deployment -n onap {{cds ui pod id}}
103 API_BLUEPRINT_CONTROLLER_HTTP_BASE_URL parameter must have the following value
107 http://cds-blueprints-processor-http:8080/api/v1
110 Those problems should be corrected in next ONAP release.
115 * `Step 1: identify the parameters needed for instantiation`_
116 * `Step 2: identify the parameters needed for post-instantiation`_
117 * `Step 3: identify the resolution method for each parameter`_
118 * `Step 4: add new data definition in CDS resource dictionary`_
119 * `Step 5: write template files`_
120 * `Step 6: write mapping files`_
121 * `Step 7: write scripts`_
122 * `Step 8: write the "blueprint" file`_
123 * `Step 9: build the "Controller Blueprint Archive” (cba)`_
124 * `Step 10: attached the cba to a service definition`_
125 * `Step 11: distribute the service`_
126 * `Step 12: instantiate the service and check`_
129 Step 1: identify the parameters needed for instantiation
130 --------------------------------------------------------
132 To instantiate an "ubuntu" VNF, a Heat Template can be used. Several
133 parameters are defined in that template: vnf_name, image_name,
136 This Heat Template is a first place to identify the parameters that need
144 # Metadata required by ONAP
145 vnf_id: ubuntuCDS-VNF
146 vf_module_id: ubuntuCDS-VF-module
147 vnf_name: ubuntuCDS-VNF-name
149 # Server parameters, naming required by ONAP
150 ubuntuCDS_image_name: ubuntu-18
151 ubuntuCDS_flavor_name: onap.small
152 ubuntuCDS_pub_key: ssh-rsa AAAAB3VHCx...vVL8l1BrX3BY0R8D imported-openssh-key
153 ubuntuCDS_name_0: ubuntuCDS
155 # Network parameters, naming required by ONAP
156 admin_plane_net_name: admin
158 Step 2: identify the parameters needed for post-instantiation
159 -------------------------------------------------------------
161 Post-instantiation activity will occur after the VNF is instantiated.
163 Typically, it can be adding a first firewall rule in a firewall VNF.
165 In the ubuntuCDS example, there is no such parameter.
168 Step 3: identify the resolution method for each parameter
169 ---------------------------------------------------------
171 Here after the decision/solution that the designer may take:
173 **vnf_name** will be resolved via an input that will be provided
174 in the instantiation request.
176 **ubuntuCDS_image_name** will be resolved via an input that will be provided
177 in the instantiation request.
179 **ubuntuCDS_flavor_name** will be resolved via an input that will be provided
180 in the instantiation request.
182 **ubuntuCDS_pub_key** will be resolved via an input that will be provided
183 in the instantiation request.
185 **admin_plane_net_name** will be resolved via an input that will be provided
186 in the instantiation request.
188 Service Designer needs also to know that some parameters will be
189 automatically resolved by ONAP SO and/or ONAP SDNC.
191 - service-instance-id
195 For each resolution method, Service Designer needs to identify all
196 necessary parameters that must be provided to the resoluton method
197 in order to obtain the resolution.
199 Also, Service Designer needs to know that ONAP will instantiate
200 a service, a list of VNF that are composing the service and, for each VNF,
201 a "VF-module" will be instantiated.
204 Step 4: add new data definition in CDS resource dictionary
205 ----------------------------------------------------------
207 In CDS, there is a database that will contain all resource Definitions
208 in order to be able to re-use those resources from one service to an other.
210 Service Designer needs to check about existing resource definitions
213 By default, some resources are pre-loaded when installing ONAP platform.
215 Preloaded resources (parameter definition): Resources_.
217 Be careful: the content of the resource dictionary is not the same from
218 one ONAP release to an other.
220 If Service Designer sees that there is an existing parameter
221 that corresponds to the need, he has the possibility to re-use it
222 in the mapping file(s), but maybe with a different name.
224 For example, "image_name" is already defined in the resource dictionary but,
225 it is named "freeRadius_image_name" in the Heat files.
227 For the ubuntuCDS example, there is no need to add any entry in the
230 "curls" requests example to declare a new resource
231 :download:`Here <ubuntu_example/curls_resource_dictionary.txt>`
233 Step 5: write template files
234 ----------------------------
236 In this Ubuntu example, Designer needs to create 2 "templates" files.
237 Naming of those files is important. For VNF, prefix name must be equal to the
238 VF name in ONAP SDC. For the VFmodule, prefix name must be equal to the name
239 of the Heat template.
241 - VNF level :download:`VNF_template_file <ubuntu_example/cba-before-enrichment\
242 /Templates/ubuntuCDS-template.vtl>`
243 - VF-module level :download:`VFmodule_template_file <ubuntu_example/cba-before\
244 -enrichment/Templates/base_ubuntuCDS-template.vtl>`
246 CDS makes use of "velocity template" or "Jinja template" files.
248 This way, CDS is able to generate the desired datastructure
249 with resolved values, that will then be sent to the target system:
251 - openstack when instantiating the Heat stack
252 - instantiated VNF when doing some post-instantiation operation
254 There are two sections in each velocity file:
256 - "resource-accumulator-resolved-data": a list of all parameters
257 - "capability-data": a list of "capabilities" to process and resolve
260 A capability can be an other way to resolve a parameter,
261 using a directed graph.
263 A capability may also be an action to be performed such as modifying
266 ONAP SDNC provides those "capabilities":
274 There is an SDNC Directed Graph associated to each of those "capability".
276 Service Designer needs to know about those capabilities with their
277 input/output, in order to re-use them. Especially, Service Designer needs
278 to know inputs because those inputs need to be part of the templates.
280 In case Service Designer wants to use a new capability, a solution is
281 to create a Directed Graph and update the self-serve-vnf-assign and/or
282 self-serve-vf-module-assign Directed Graph by adding a new
283 entry in the list of capabilities (node: set ss.capability.execution-order[])
285 The "aai-vfmodule-put" capability is important to be part of a vf-module
286 template because it will be used to put the vf-module-name in AAI
287 and ONAP SO will use that value to name the heat stack.
292 About the name/value of each parameter, Service Designer needs to understand
293 how various information will map between the various files needed by CDS.
297 And be very careful with "_" or "-"
299 Step 6: write mapping files
300 ---------------------------
302 Along with each velocity template, Designer needs to create a
305 This is the place where the Designer explains, for each parameter:
307 - value source: the system or database that will provide the value
310 At VNF instantiation step, values are often coming from input (in the request
311 sent by the user, in the "instanceParams" section of the vnf).
313 At VF module instantion step, values can come form input also in the request
314 sent by the user, in the "instanceParams" section of the vf-module)
316 Resolved data are always stored in SDNC database (MDSAL)
318 Note1: if service designer wants to re-use for vf-module a
319 parameter/value from VNF "userParams" section,
320 then the source will be from "SDNC" in the vf-module mapping file.
322 Note2: service-instance-id, vnf-id and vf_module_id are parameters considered
323 as "input" from CDS point of view but in reality they are resolved by ONAP SO
324 with ONAP AAI. Thus, those parameters are not "input" from ONAP SO
325 point of view: service designer has not need to provide those parameters in
326 service instantiation request (step 12).
328 For the ubuntu example, there are then 2 mapping files.
329 File names are important and must be aligned with vtl template names.
331 - VNF level :download:`VNF_mapping_file <ubuntu_example/cba-before-enrichment\
332 /Templates/ubuntuCDS-mapping.json>`
333 - VFmodule level :download:`VFmodule_mapping_file <ubuntu_example/cba-before-\
334 enrichment/Templates/base_ubuntuCDS-mapping.json>`
336 Step 7: write scripts
337 ---------------------
339 Sometimes, it will be necessary to use some scripts (python, kotlin,
340 ansible...) to process some post-configuration operation.
342 Those scripts needs to be part of the "Controller Blueprint Archive” (cba).
344 No such script for the ubuntuCDS example.
347 Step 8: write the "blueprint" file
348 --------------------------------------
350 The "designer" will then create a "blueprint".
352 It is a JSON file and for the ubuntuCDS usecase, it is called
354 Name must be aligned with VF name in ONAP SDC.
356 This file will be the main entry point for CDS blueprint processor.
357 This processor will use that file to understand what need to
358 be processed and how to process it.
360 The content of that file is composed of several sections conforming to TOSCA
365 For the ubuntu example :download:`CDS blueprint <ubuntu_example/cba-before-\
366 enrichment/Definitions/ubuntuCDS.json>` before enrichment.
368 This example is the minimum that is required to simply instantiate a
371 Some extension can then be added in order to define additional
374 Step 9: build the "Controller Blueprint Archive” (cba)
375 ------------------------------------------------------
377 Having created velocity templates, mapping files and a first
378 CDS blueprint version,
379 it is now simple to create the "Controller Blueprint Archive” (cba).
381 This is a "zip-like" archive file that will have the following structure
382 and content ("environment", "scripts" and "plans" are optional):
386 For the ubuntu example :download:`cba archive <ubuntu_example/cba-before-\
387 enrichment/cba-before-enrichment.zip>` before enrichment.
389 To complete that cba, an "enrichment" operation is needed.
391 Service Designer can use two methods:
393 - using CDS User Interface
396 Service Designer needs to send the cba to CDS-UI pod and requests
397 the enrichment, then save and then download.
399 Result will be that the cba will now contains several new files in "Definition"
402 The "blueprint" file will also be completed.
404 The "enriched" cba is now ready to be onboarded in ONAP SDC along with
405 a service definition.
407 For the ubuntu example :download:`cba archive <ubuntu_example/cba-after\
408 -enrichment/cba-ubuntuCDS-enriched.zip>` after enrichment.
410 Step 10: attached the cba to a service definition
411 -------------------------------------------------
413 In SDC, when defining a VF, Designer will attach the cba archive
414 to the VF definition, using the "deployment artifact" section.
416 Having define all necessary VF, Service Designer will create a SERVICE in SDC.
418 Service Designer will compose the SERVICE with appropriate VF(s) and will have
419 to modify PROPERTIES in the "properties assignement" section.
421 Service Designer needs to provide values for sdnc_artifact_name,
422 sdnc_model_name and sdnc_model_verion.
424 This will tell SO which blueprint to use for the service model that is being
427 SDC sdnc_artifact_name = CBA blueprint json filename, e.g. “ubuntuCDS”,
428 we will see below that we will have vnf-mapping.json and vnf-template.vtl
429 templates in the blueprint.
431 SDC sdnc_model_name = CBA Metadata template_name, e.g. “ubuntuCDS”,
432 we can see in the below screenshot the metadata section showing template name.
434 SDC sdnc_model_verion = CBA Metadata template_version, e.g. “1.0.0”,
435 we can see in the below screenshot the metadata section showing
440 Step 11: distribute the service
441 -------------------------------
443 In SDC, when distributing the service, the CDS controller will be
444 informed that a new cba archive is available.
446 CDS controller will then collect the cba archive.
448 Step 12: instantiate the service and check
449 ------------------------------------------
451 Here is an example of an ONAP SO api request to
452 instantiate the ubuntu service.
454 This request is used to instantiate a service using the "Macro" mode.
456 Do not try to use that example as-is: you need to adapt all values to your
457 platform/service model.
459 In this example, the request contains several "inputs" at VNF level and
460 several "inputs" at VF-module level.
462 All various "id" and "version" are some copy/paste information that
463 Service Designer has the possibility to find in the TOSCA service
464 template created in ONAP SDC.
466 This request will instantiate a "service", a "VNF" and a "VF-module".
467 That "service" instance is attached to the customer named "JohnDoe" with
468 service subscription named "ubuntCDS"
469 (supposed already declared in your ONAP AAI).
471 In case the instantiation fails, a roolback is performed (parameter
472 "suppressRollback" = false)
474 For that example, no "homing" and the "cloud" tenant is explicitely
475 provided (supposed already declared in your ONAP AAI)
480 http://so.api.simpledemo.onap.org:30277/onap/so/infra/serviceInstantiation/v7/serviceInstances \
481 -H 'Accept: application/json' \
482 -H 'Authorization: Basic SW5mcmFQb3J0YWxDbGllbnQ6cGFzc3dvcmQxJA==' \
483 -H 'Content-Type: application/json' \
484 -H 'X-ONAP-PartnerName: NBI' \
485 -H 'cache-control: no-cache' \
489 "globalSubscriberId": "JohnDoe"
492 "suppressRollback": false,
493 "productFamilyId": "Useless_But_Mandatory",
494 "requestorId": "adt",
495 "instanceName": "My_ubuntuCDS_service_instance_001",
498 "cloudConfiguration": {
499 "lcpCloudRegionId": "RegionOne",
500 "tenantId": "71cf9d931d9e4b8e9fcca50d97c1cf96",
503 "requestParameters": {
504 "subscriptionServiceType": "ubuntuCDS",
507 "Homing_Solution": "none"
511 "instanceParams": [],
512 "instanceName": "My_ubuntuCDS_service_instance_001",
517 "modelName": "ubuntuCDS",
518 "modelVersionId": "c6a5534e-76d5-4128-97bf-ad3b72208d53",
519 "modelInvariantUuid": "ed3064e7-62c0-494c-bb9b-4f56d1ad157e",
520 "modelVersion": "1.0",
521 "modelCustomizationId": "6a32fb56-191e-4d11-a0cc-44b779aba4fc",
522 "modelInstanceName": "ubuntuCDS 0"
524 "cloudConfiguration": {
525 "lcpCloudRegionId": "RegionOne",
526 "tenantId": "71cf9d931d9e4b8e9fcca50d97c1cf96"
529 "platformName": "Useless_But_Mandatory"
531 "productFamilyId": "Useless_But_Mandatory",
532 "instanceName": "My_VNF_ubuntuCDS_instance_001",
535 "vnf_name": "My_VNF_ubuntuCDS_instance_001"
541 "modelName": "Ubuntucds..base_ubuntuCDS..module-0",
542 "modelVersionId": "3025cd36-b170-4667-abb1-2bae1f297844",
543 "modelInvariantUuid": "0101f9e0-7beb-4b58-92c7-ba3324b5a54d",
545 "modelCustomizationId": "9bca4d4b-e27c-4652-a61e-b1b4ebca503d"
547 "instanceName": "My_vfModule_ubuntuCDS_instance_001",
550 "vnf_name": "My_VNF_ubuntuCDS_instance_001",
551 "vf_module_name": "My_vfModule_ubuntuCDS_instance_001",
552 "ubuntuCDS_pub_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDY15cdBmIs2XOpe4EiFCsaY6bmUmK/GysMoLl4UG51JCfJwvwoWCoA+6mDIbymZxhxq9IGxilp/yTA6WQ9s/5pBag1cUMJmFuda9PjOkXl04jgqh5tR6I+GZ97AvCg93KAECis5ubSqw1xOCj4utfEUtPoF1OuzqM/lE5mY4N6VKXn+fT7pCD6cifBEs6JHhVNvs5OLLp/tO8Pa3kKYQOdyS0xc3rh+t2lrzvKUSWGZbX+dLiFiEpjsUL3tDqzkEMNUn4pdv69OJuzWHCxRWPfdrY9Wg0j3mJesP29EBht+w+EC9/kBKq+1VKdmsXUXAcjEvjovVL8l1BrX3BY0R8D imported-openssh-key",
553 "ubuntuCDS_image_name": "ubuntu-18.04-daily",
554 "ubuntuCDS_flavor_name": "onap.small",
555 "ubuntuCDS_name_0": "ubuntuCDS-VM-001",
556 "admin_plane_net_name": "admin"
565 "modelVersion": "1.0",
566 "modelVersionId": "10369444-1e06-4d5d-974b-362bcfd19533",
567 "modelInvariantId": "32e00b49-eff8-443b-82a8-b75fbb6e3867",
568 "modelName": "ubuntuCDS",
569 "modelType": "service"
578 "owningEntityId": "Useless_But_Mandatory",
579 "owningEntityName": "Useless_But_Mandatory"
582 "modelVersion": "1.0",
583 "modelVersionId": "10369444-1e06-4d5d-974b-362bcfd19533",
584 "modelInvariantId": "32e00b49-eff8-443b-82a8-b75fbb6e3867",
585 "modelName": "ubuntuCDS",
586 "modelType": "service"
591 In response, ONAP SO will immediately provide a requestId and a service
594 The instantiation will take some time. It will be necessary
595 to perform a "GET" on the request to check the result.
600 http://so.api.simpledemo.onap.org:30277/onap/so/infra/orchestrationRequests/v7/{{requestID}} \
601 -H 'Accept: application/json' \
602 -H 'Authorization: Basic SW5mcmFQb3J0YWxDbGllbnQ6cGFzc3dvcmQxJA==' \
603 -H 'Content-Type: application/json' \
604 -H 'X-FromAppId: AAI' \
605 -H 'X-TransactionId: get_aai_subscr' \
606 -H 'cache-control: no-cache'
613 - debug.log in CDS blueprint processor pod
614 - debug.log into SO Bpmn pod
615 - karaf.log into SDNC pod
617 .. |image1| image:: ../media/cds-blueprint.png
618 .. |image2| image:: ../media/cba.png
619 .. |image3| image:: ../media/capabilities.png
620 .. |image4| image:: ../media/sdc.png
621 .. |image5| image:: ../media/mapping.png
622 .. _JIRA_SDNC_949: https://jira.onap.org/browse/SDNC-949
623 .. _Resources: https://git.onap.org/ccsdk/cds/tree/components/model-catalog/resource-dictionary/starter-dictionary
624 .. _DG_VNF_ASSIGN: https://gerrit.onap.org/r/gitweb?p=sdnc/oam.git;a=blob_plain;f=platform-logic/generic-resource-api/src/main/json/GENERIC-RESOURCE-API_vnf-topology-operation-assign.json;hb=HEAD
625 .. _DG_VFMODULE_ASSIGN: https://gerrit.onap.org/r/gitweb?p=sdnc/oam.git;a=blob_plain;f=platform-logic/generic-resource-api/src/main/json/GENERIC-RESOURCE-API_vf-module-topology-operation-assign.json;hb=HEAD