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 PNF, VNF or CNF there is the need to
14 get some values for some parameters.
16 For example, it may be necessary to provide a VNF management @ip
17 Address or a VNF instance name. Those parameters can be necessary
18 to create cloud resources or to configure the VNF at application level.
20 The initial implementation of ONAP required operators to provide
21 preload data spreadsheet for each PNF/VNF/CNF Instance that is being
22 instantiated via ONAP which was error prone and was not operationally
23 a scalable solution for telcos. As part of the ONAP CDS component introduction
24 in Casablanca release, the user, that wants to instantiate a new VNF/CNF,
25 does not need to get and provide those data.
27 Of course the “user” may be a human but may be also an application that uses
28 the “instantiation” API on ONAP NBI or ONAP SO.
30 ONAP CDS component is then in charge of resolving those parameters
37 Full CDS documentation is here <../../../../submodules/ccsdk/cds.git/docs/index.rst>
39 It offers automated solution out of the box by delivering network intent
40 declarative package during design time phase that automated the provisioning
41 and/or network configuration network intent.
43 At instantiation time, CDS controller will find (assign) the values
44 according some “recipies” described in a "Controller Blueprint Archive”:
45 a collection of files that CDS controller will use to proceed
48 Thanks to CDS, at instantiation time, the user, that wants to instantiate
49 a new VNF, does not need to get and provide those data himself.
50 Of course the “user” may be a human but may be also
51 an application that uses the “instantiation” API on ONAP NBI or ONAP SO.
53 Less effort for the “user”, but more effort for the “designer”
54 that needs to pre-defined all necessary recipies
57 The purpose of the following text is to describe various files and content
58 that are necessary to the CDS controller to resolve any parameters.
60 To illustrate the subject, let's take an example: a service composed of
63 That software will be installed on a simple ubuntu image.
69 * `Step 1 : identify the parameters needed for instantiation`_
70 * `Step 2: identify the parameters needed for post-instantiation`_
71 * `Step 3: identify the data source for each parameter`_
72 * `Step 4: add new data definition in CDS resource dictionary`_
73 * `Step 5: write template files`_
74 * `Step 6: write mapping files`_
75 * `Step 7: write scripts`_
76 * `Step 8: write the "CDS blueprint" file`_
77 * `Step 9: build the "Controller Blueprint Archive” (cba)`_
78 * `Step 10: attached the cba to a service definition`_
79 * `Step 11: distribute the service`_
80 * `Step 12: instantiate the service and check`_
83 Step 1 : identify the parameters needed for instantiation
84 ---------------------------------------------------------
86 To instantiate a freeradius VNF, a Heat Template can be used. Several
87 parameters are defined in that template: vnf_name, image_name,
90 This Heat Template is a first place to find the parameters that need
98 # Metadata required by ONAP
99 vnf_id: FreeRadius-VNF
100 vf_module_id: FreeRadius-VF-module
101 vnf_name: FreeRadius-VNF-name
103 # Server parameters, naming required by ONAP
104 image_name: ubuntu-16.04-daily
105 flavor_name: onap.small
106 pub_key: ssh-rsa AAAAB3Nza...UwMtE0oHV47zQABx root@qvocrobot-virtual-machine
107 key_name: FreeRadius-key
108 freeRadius_name_0: FreeRadius-VM-name
109 freeradius_ip: 10.0.0.100
111 # Network parameters, naming required by ONAP
112 onap_private_net_id: admin
116 In the following section, only part of those parameters will be automated
117 by CDS (just for illustration).
125 In real, all parameters need to be processed
126 (or at least those that change from one VNF instance to the other)
128 Step 2: identify the parameters needed for post-instantiation
129 -------------------------------------------------------------
131 Also, a freeradius VNF is software that will be able to accept or reject
132 some connection requests. Only declared "users" can be accepted by
135 To be able to proceed, it is necessary to declare (=configure) some "users"
136 in a file located in /etc/freeradius/users in the VM where the freeradius
137 software is installed.
139 At this step, the designer needs to know the VNF specificities. It is
140 application-level parameters. For example: configure a firewall rule in
141 a firewall VNF, declare a "user" in a AAA radius VNF...
143 In the freeradius example (an opensource AAA radius solution),
144 the following parameters can be automated via CDS:
149 Step 3: identify the data source for each parameter
150 ---------------------------------------------------
152 The parameter list that the Designer decided to automate:
162 Here after the decision/solution that the designer may take:
164 **vnf_name** will be resolved using a "naming" application (micro-service),
167 **image_name** will be resolved via a default value in the template
169 **flavor_name** will be resolved via an input that will be provided
170 in the instantiation request.
172 **pub_key** will be resolved via an input that will be provided
173 in the instantiation request.
175 **freeradius_ip** will be resolved using an IP Address Management (IPAM)
176 application, provided by ONAP (Netbox).
178 **user_name** and **user_password** will be resolved via inputs
179 that will be provided in the instantiation request.
181 Step 4: add new data definition in CDS resource dictionary
182 ----------------------------------------------------------
184 In CDS, there is a database that will contain all resource Definitions
185 in order to be able to re-use those resources.
187 Service Designer needs to check about existing resources in the disctionary.
189 By default, some resources are pre-loaded when installing ONAP platform.
191 Preloaded resources (parameter definition): Resources_.
193 For the freeradius use-case, there are 3 resources to add
194 in the resource dictionary:
198 curl -k 'https://cds-ui:30497/resourcedictionary/save' -X POST -H 'Content-type: application/json' \
200 "name": "radius_test_user",
201 "tags": "radius_test_user",
202 "data_type": "string",
203 "description": "radius_test_user",
204 "entry_schema": "string",
205 "updatedBy": "Seaudi, Abdelmuhaimen <abdelmuhaimen.seaudi@orange.com>",
207 "tags": "radius_test_user",
208 "name": "radius_test_user",
210 "description": "radius_test_user",
213 "updated-by": "Seaudi, Abdelmuhaimen <abdelmuhaimen.seaudi@orange.com>",
216 "type": "source-input"
219 "type": "source-default",
223 "type": "source-rest",
227 "url-path": "/restconf/config/GENERIC-RESOURCE-API:services/service/$service-instance-id/service-data/vnfs/vnf/$vnf-id/vnf-data/vnf-topology/vnf-parameters-data/param/radius_test_user",
228 "path": "/param/0/value",
229 "input-key-mapping": {
230 "service-instance-id": "service-instance-id",
233 "output-key-mapping": {
234 "radius_test_user": "value"
236 "key-dependencies": ["service-instance-id",
247 curl -k 'https://cds-ui:30497/resourcedictionary/save' -X POST -H 'Content-type: application/json' \
249 "name": "radius_test_password",
250 "tags": "radius_test_password",
251 "data_type": "string",
252 "description": "radius_test_password",
253 "entry_schema": "string",
254 "updatedBy": "Seaudi, Abdelmuhaimen <abdelmuhaimen.seaudi@orange.com>",
256 "tags": "radius_test_password",
257 "name": "radius_test_password",
259 "description": "radius_test_password",
262 "updated-by": "Seaudi, Abdelmuhaimen <abdelmuhaimen.seaudi@orange.com>",
265 "type": "source-input"
268 "type": "source-default",
272 "type": "source-rest",
276 "url-path": "/restconf/config/GENERIC-RESOURCE-API:services/service/$service-instance-id/service-data/vnfs/vnf/$vnf-id/vnf-data/vnf-topology/vnf-parameters-data/param/radius_test_password",
277 "path": "/param/0/value",
278 "input-key-mapping": {
279 "service-instance-id": "service-instance-id",
282 "output-key-mapping": {
283 "radius_test_password": "value"
285 "key-dependencies": ["service-instance-id",
296 curl -k 'https://cds-ui:30497/resourcedictionary/save' -X POST -H 'Content-type: application/json' \
298 "name": "freeradius_ip",
299 "tags": "freeradius_ip",
300 "data_type": "string",
301 "description": "freeradius_ip",
302 "entry_schema": "string",
303 "updatedBy": "Seaudi, Abdelmuhaimen <abdelmuhaimen.seaudi@orange.com>",
305 "tags": "freeradius_ip",
306 "name": "freeradius_ip",
308 "description": "freeradius_ip",
311 "updated-by": "Seaudi, Abdelmuhaimen <abdelmuhaimen.seaudi@orange.com>",
314 "type": "source-input"
317 "type": "source-default",
321 "type": "source-rest",
325 "url-path": "/restconf/config/GENERIC-RESOURCE-API:services/service/$service-instance-id/service-data/vnfs/vnf/$vnf-id/vnf-data/vnf-topology/vnf-parameters-data/param/freeradius_ip",
326 "path": "/param/0/value",
327 "input-key-mapping": {
328 "service-instance-id": "service-instance-id",
331 "output-key-mapping": {
332 "freeradius_ip": "value"
334 "key-dependencies": ["service-instance-id",
344 Step 5: write template files
345 ----------------------------
347 In this example, Designer needs to create 3 "templates".
349 - VNF level :download:`VNF_template_file <freeradius_example/before_enrichment/CBA_freeradius/Templates/vnf-template.vtl>`
350 - VFmodule level :download:`VFmodule_template_file <freeradius_example/before_enrichment/CBA_freeradius/Templates/radius-template.vtl>`
351 - post-instantiation VNF level :download:`VNF_config_template_file <freeradius_example/before_enrichment/CBA_freeradius/Templates/userconfig-template.vtl>`
353 CDS makes use of "velocity template" or "Jinja template" files.
355 This way, CDS is able to generate the desired datastructure
356 with resolved values, that will then be sent to the target system:
358 - openstack when instantiating the VNF/VF-module
359 - instantiated VNF when doing some post-instantiation operation
361 There are two sections in each velocity file:
363 - "resource-accumulator-resolved-data": a list of all parameters
364 - "capability-data": a list of "capabilities" to process and resolv a parameter
366 ONAP SDNC provides some "capabilities":
374 There is an SDNC Directed Graph associated to each of those "capability".
376 Service Designer needs to know about those capabilitie with their
377 input/output, in order to re-use them.
379 In case, Service Designer wants to use a new capability, a solution will be
380 to create a Directed Graph and update the Self-serve-vnf-assign and/or
381 Self-serve-vf-module-assign Directed Graph by adding a new
382 entry in the list of capabilities (node: set ss.capability.execution-order[])
386 Step 6: write mapping files
387 ---------------------------
389 Along with each velocity template, Designer needs to create a
392 This is the place where the Designer explains, for each parameter:
394 - value source: the system or database that will provide the value
397 At VNF instantiation step, values are often coming from input (in the request
400 At VF module instantion step, values are often coming from SDNC database
401 (stored values from VNF instantiation step).
403 Resolved data are always stored in SDNC database (MDSAL)
407 - "input": parameter/value is provided in the request
408 - "sdnc": parameter/value is coming from the SDNC database (MDSAL)
410 - "default": always take the default value
411 - "processor-db": coming from SDNC but MariaDB database via SQL request
413 Other sources are possible.
415 For the freeradius example, there are then 3 mapping files:
417 - VNF level :download:`VNF_mapping_file <freeradius_example/before_enrichment/CBA_freeradius/Templates/vnf-mapping.json>`
418 - VFmodule level :download:`VFmodule_mapping_file <freeradius_example/before_enrichment/CBA_freeradius/Templates/radius-mapping.json>`
419 - post-instantiation VNF level :download:`VNF_config_mapping_file <freeradius_example/before_enrichment/CBA_freeradius/Templates/userconfig-mapping.json>`
421 Step 7: write scripts
422 ---------------------
424 Sometimes, it will be necessary to use some scripts (python, kotlin,
425 ansible...) to process some operation.
427 Those scripts needs to be part of the "Controller Blueprint Archive” (cba).
429 In freeradius example, a :download:`Kotlin script <freeradius_example/before_enrichment/CBA_freeradius/Scripts/kotlin/kotlin.kt>` is used
430 to get data, open an ssh tunnel to the VNF and add the user/password
431 in the /etc/freeradius/users file.
433 Step 8: write the "CDS blueprint" file
434 --------------------------------------
436 The "designer" will then create a "CDS blueprint".
438 It is a JSON file and for the freeradius usecase, it is called
441 This file will be the main entry point for CDS controller
442 to understand what need to be processed and how to process it.
444 The content of that file is composed of several sections conforming to TOSCA
447 Part of the file is provided by the Service Designer but it will them be
448 automatically completed by CDS controller via an "enrichment" operation
453 In a short, this file will contain information about:
455 - any parameters or external sources needed to resolve parameters,
456 - all the resolve actions needed during the instantiation of a service,
457 - any post-instantiation steps that need to run after the service
458 instance is up and running
459 - all necessary template files
461 For the freeradius example, here is the :download:`CDS blueprint <freeradius_example/before_enrichment/CBA_freeradius/Definitions/freeradius.json>`
464 Step 9: build the "Controller Blueprint Archive” (cba)
465 ------------------------------------------------------
467 Having created velocity templates, mapping files, scripts and a first
468 CDS blueprint version,
469 it is now simple to create the "Controller Blueprint Archive” (cba).
471 This is a "zip-like" archive file that will have the following structure
476 For the freeradius example, here is the :download:`cba archive <freeradius_example/before_enrichment/CBA_freeradius.cba>` before enrichment.
478 To complete that cba, an "enrichment" operation is needed.
480 Service Designer can use two methods:
482 - using CDS User Interface
485 Service Designer needs to send the cba to CDS-UI pod and requests
488 Here is the example using CDS-UI rest API:
493 https://cds-ui:30497/controllerblueprint/enrich-blueprint \
494 -H 'Accept: application/json, text/plain, */*' \
495 -H 'Accept-Encoding: gzip, deflate, br' \
496 -H 'Accept-Language: en-US,en;q=0.9,ar;q=0.8,fr;q=0.7' \
497 -H 'Cache-Control: no-cache' \
498 -H 'Connection: keep-alive' \
499 -H 'Content-Length: 16488' \
500 -H 'Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryamjjRAAflAzY4XR5' \
501 -H 'Host: cds-ui:30497' \
502 -H 'Origin: https://cds-ui:30497' \
503 -H 'Postman-Token: 5e895c04-577a-4610-97e6-5d3881fd96c5,508c40d9-65da-47bc-a3a8-038d64f44a94' \
504 -H 'Referer: https://cds-ui:30497/blueprint' \
505 -H 'Sec-Fetch-Mode: cors' \
506 -H 'Sec-Fetch-Site: same-origin' \
507 -H 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.70 Safari/537.36' \
508 -H 'cache-control: no-cache' \
509 -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
510 -F 'file=@/home/user/dev/CBA_freeradius.cba' -k
512 Result will be that the cba will contains several new files in "Definition"
513 folder of the cba. Also, the CDS blueprint file (freeradius.json) will
516 The cba is now ready to be onboarded in ONAP SDC along with
517 a service definition.
519 For the freeradius example, here is the :download:`cba archive <freeradius_example/after_enrichment/CBA_freeradius.cba>` after enrichment.
521 Step 10: attached the cba to a service definition
522 -------------------------------------------------
524 In SDC, when defining a service, Designer will attach the cba archive
525 to the service definition, using the "deployment" section.
527 Note that the template_name and template_version are to be added to the
528 service model in SDC under assignment parameters section, and this will
529 tell SO which blueprint to use for the service model that is being
532 SDC sdnc_artifact_name = CBA blueprint json filename, e.g. “vnf”,
533 we will see below that we will have vnf-mapping.json and vnf-template.vtl
534 templates in the blueprint.
536 SDC sdnc_model_name = CBA Metadata template_name, e.g. “test”,
537 we can see in the below screenshot the metadata section showing template name.
539 SDC sdnc_model_verion = CBA Metadata template_version, e.g. “1.0.0”,
540 we can see in the below screenshot the metadata section showing
545 Step 11: distribute the service
546 -------------------------------
548 In SDC, when distributing the service, the CDS controller will be
549 informed that a new cba archive is available.
551 CDS controller will then collect the cba archive.
553 Step 12: instantiate the service and check
554 ------------------------------------------
556 Here is the ONAP SO api request to instantiate the freeradius service:
561 http://84.39.34.234:30277/onap/so/infra/serviceInstantiation/v7/serviceInstances \
563 -H 'Accept-Encoding: gzip, deflate' \
564 -H 'Authorization: Basic SW5mcmFQb3J0YWxDbGllbnQ6cGFzc3dvcmQxJA==' \
565 -H 'Cache-Control: no-cache' \
566 -H 'Connection: keep-alive' \
567 -H 'Content-Length: 4581' \
568 -H 'Content-Type: application/json' \
569 -H 'Cookie: JSESSIONID=DAFA0915D8D644A5E01BB499A1769365' \
570 -H 'Host: 84.39.34.234:30277' \
571 -H 'Postman-Token: 02273554-69e5-426b-83ce-675462a14436,eea8e2dc-fbce-45ac-82d7-19fdca83804a' \
572 -H 'User-Agent: PostmanRuntime/7.19.0' \
573 -H 'cache-control: no-cache' \
577 "globalSubscriberId": "Demonstration"
580 "suppressRollback": false,
581 "productFamilyId": "a9a77d5a-123e-4ca2-9eb9-0b015d2ee0fb",
582 "requestorId": "adt",
585 "cloudConfiguration": {
586 "lcpCloudRegionId": "fr1",
587 "tenantId": "6270eaa820934710960682c506115453",
588 "cloudOwner":"CloudOwner"
590 "requestParameters": {
591 "subscriptionServiceType": "vLB",
594 "Homing_Solution": "none"
604 "modelName": "freeradius5",
605 "modelVersionId": "f7538c8d-c27c-46f9-8c2c-f01eb2a19bfa",
606 "modelInvariantUuid": "cd322f8b-0496-4126-b3d6-200adceaf11f",
607 "modelVersion": "1.0",
608 "modelCustomizationId": "bc976d7c-bf2c-4da5-9b6b-815d9ea22b92",
609 "modelInstanceName": "freeradius5 0"
611 "cloudConfiguration": {
612 "lcpCloudRegionId": "fr1",
613 "tenantId": "6270eaa820934710960682c506115453"
616 "platformName": "test"
619 "lineOfBusinessName": "LOB-Demonstration"
621 "productFamilyId": "a9a77d5a-123e-4ca2-9eb9-0b015d2ee0fb",
622 "instanceName": "freeradius5 0",
625 "onap_private_net_id": "olc-onap",
626 "onap_private_subnet_id": "olc-onap",
627 "pub_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCs84Cy8+qi/jvucay0BwFtOq3ian0ulTXFGxkZcZCR0N48j88pbHJaEqb9e25MAsrfH+7Etb9Kd5nbBThEL/i0AyHXnDsc80Oq0sqlLcfLo3SGSurkrNoRofHboJ5Hn+N9SlWN5FCQGbTx1w3rjqR4LasAI6XxH9xpXSFyyge6ysVXH0cYaZ8sg98nFZa1fPJR9L8COjZvF+EYudub2RC5HVyV/sx7bliNFo9JwQh6du1abG4G7ZDjTIcYwYp21iq52UzWU28RVcAyY6AQZJu2lHLdsr8fPvyeWZpC5EqGsxI1G609m9G/dURRKwYfez/f2ATzpn5QjEX7LrLWBM8r Generated-by-Nova",
628 "image_name": "Ubuntu 16.04",
629 "flavor_name":"n1.cw.standard-1",
630 "sec_group":"olc-open",
631 "cloud_env":"openstack",
632 "public_net_id": "olc-public",
633 "aic-cloud-region": "fr1",
634 "key_name":"olc-key",
635 "vf-naming-policy": "SDNC_Policy.Config_MS_ONAP_VNF_NAMING_TIMESTAMP",
636 "radius_test_user": "Rene-Robert",
637 "radius_test_password": "SecretPassword"
643 "modelName": "Freeradius5..radius..module-0",
644 "modelVersionId": "e08d6d0f-27ea-4b46-a2d1-0d60c49fca59",
645 "modelInvariantUuid": "fdb408c6-6dd1-4a0c-88ca-ebc3ff77b445",
647 "modelCustomizationId": "e82a94de-6dff-4dc9-a57e-335315c8fdae"
649 "instanceName": "Freeradius5..radius..module-0",
659 "modelVersion": "1.0",
660 "modelVersionId": "4dacb612-935f-4755-91a1-78af64331c42",
661 "modelInvariantId": "98d65302-3be3-4828-a116-1bedb2919048",
662 "modelName": "freeradius5",
663 "modelType": "service"
671 "projectName": "Project-Demonstration"
674 "owningEntityId": "67f2e84c-734d-4e90-a1e4-d2ffa2e75849",
675 "owningEntityName": "OE-Demonstration"
678 "modelVersion": "1.0",
679 "modelVersionId": "4dacb612-935f-4755-91a1-78af64331c42",
680 "modelInvariantId": "98d65302-3be3-4828-a116-1bedb2919048",
681 "modelName": "freeradius5",
682 "modelType": "service"
687 .. |image1| image:: ../media/cds-blueprint.png
688 .. |image2| image:: ../media/cba.png
689 .. |image3| image:: ../media/capabilities.png
690 .. |image4| image:: ../media/sdc.png
691 .. _Resources: https://git.onap.org/ccsdk/cds/tree/components/model-catalog/resource-dictionary/starter-dictionary