adf3756965662ce59fa793104bfe22501a34f38c
[vnfrqts/requirements.git] /
1 .. Licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
3 .. Copyright 2017 AT&T Intellectual Property.  All rights reserved.
4
5 .. _Nova Server - Metadata Parameters:
6
7 Resource: OS::Nova::Server - Metadata Parameters
8 --------------------------------------------------------------------------------
9
10 The OS::Nova::Server Resource property metadata is an optional
11 OpenStack property.
12 The table below summarizes the mandatory and optional metadata
13 supported by ONAP.
14
15 The sections that follow provides the requirements associated with each
16 metadata parameter.
17
18 .. csv-table:: **Table 5 OS::Nova::Server Mandatory and Optional Metadata**
19    :header: Metadata Parameter Name, Parameter Type, Required, Parameter Value Provided to Heat
20    :align: center
21    :widths: auto
22
23    vnf_id, string, **MUST**, ONAP
24    vf_module_id, string, **MUST**, ONAP
25    vnf_name, string, **MUST**, ONAP
26    vf_module_name, string, **SHOULD**, ONAP
27    vm_role, string, **MAY**, YAML or Environment File
28    vf_module_index, string, **MAY**, ONAP
29    workload_context, string, **SHOULD**, ONAP
30    environment_context, string, **SHOULD**, ONAP
31
32 vnf_id
33 ^^^^^^^^^
34
35 The OS::Nova::Server Resource metadata map value parameter 'vnf_id'
36 is an ONAP generated UUID that identifies the VNF.  The value
37 is provided by ONAP to the VNF's Heat Orchestration
38 Template at orchestration time.
39
40
41 .. req::
42     :id: R-37437
43     :target: VNF
44     :keyword: MUST
45
46     A VNF's Heat Orchestration Template's OS::Nova::Server
47     Resource **MUST** contain the metadata map value parameter 'vnf_id'.
48
49 .. req::
50     :id: R-07507
51     :target: VNF
52     :keyword: MUST
53
54     A VNF's Heat Orchestration Template's OS::Nova::Server
55     Resource metadata map value parameter 'vnf_id' **MUST** be declared
56     as type: 'string'.
57
58 .. req::
59     :id: R-55218
60     :target: VNF
61     :keyword: MUST NOT
62
63     A VNF's Heat Orchestration Template's OS::Nova::Server
64     Resource metadata map value parameter 'vnf_id' **MUST NOT** have
65     parameter contraints defined.
66
67 .. req::
68     :id: R-20856
69     :target: VNF
70     :keyword: MUST NOT
71
72     A VNF's Heat Orchestration Template's OS::Nova::Server
73     Resource metadata map value parameter 'vnf_id' **MUST NOT** be
74     enumerated in the Heat Orchestration Template's environment file.
75
76 .. req::
77     :id: R-44491
78     :target: VNF
79     :keyword: MUST NOT
80
81     If a VNF's Heat Orchestration Template's OS::Nova::Server
82     Resource metadata map value parameter 'vnf_id' is passed into a
83     Nested YAML file, the parameter name 'vnf_id' **MUST NOT** change.
84
85 *Example 'vnf_id' Parameter Definition*
86
87 .. code-block:: yaml
88
89   parameters:
90
91     vnf_id:
92       type: string
93       description: Unique ID for this VNF instance
94
95 vf_module_id
96 ^^^^^^^^^^^^^^^^^^^^
97
98 The OS::Nova::Server Resource metadata map value parameter 'vf_module_id'
99 is an ONAP generated UUID that identifies the VF Module (e.g., Heat
100 Orchestration Template).  The value
101 is provided by ONAP to the VNF's Heat Orchestration
102 Template at orchestration time.
103
104
105 .. req::
106     :id: R-71493
107     :target: VNF
108     :keyword: MUST
109
110     A VNF's Heat Orchestration Template's OS::Nova::Server
111     Resource **MUST** contain the metadata map value parameter
112     'vf_module_id'.
113
114 .. req::
115     :id: R-82134
116     :target: VNF
117     :keyword: MUST
118
119     A VNF's Heat Orchestration Template's OS::Nova::Server
120     Resource metadata map value parameter 'vf_module_id' **MUST**
121     be declared as type: 'string'.
122
123 .. req::
124     :id: R-98374
125     :target: VNF
126     :keyword: MUST NOT
127
128     A VNF's Heat Orchestration Template's OS::Nova::Server
129     Resource metadata map value parameter 'vf_module_id' **MUST NOT**
130     have parameter contraints defined.
131
132 .. req::
133     :id: R-72871
134     :target: VNF
135     :keyword: MUST NOT
136
137     A VNF's Heat Orchestration Template's OS::Nova::Server
138     Resource metadata map value parameter 'vf_module_id' **MUST NOT**
139     be enumerated in the Heat Orchestration Template's environment file.
140
141 .. req::
142     :id: R-86237
143     :target: VNF
144     :keyword: MUST NOT
145
146     If a VNF's Heat Orchestration Template's OS::Nova::Server
147     Resource metadata map value parameter 'vf_module_id' is passed
148     into a Nested YAML file, the parameter name 'vf_module_id'
149     **MUST NOT** change.
150
151 *Example 'vf_module_id' Parameter Definition*
152
153 .. code-block:: yaml
154
155   parameters:
156
157     vnf_module_id:
158       type: string
159       description: Unique ID for this VNF module instance
160
161
162 vnf_name
163 ^^^^^^^^^
164
165 The OS::Nova::Server Resource metadata map value parameter 'vnf_name'
166 is the ONAP generated alphanumeric name of the deployed VNF instance.
167 The value
168 is provided by ONAP to the VNF's Heat Orchestration
169 Template at orchestration time.
170 The parameter must be declared as type: string
171
172
173 .. req::
174     :id: R-72483
175     :target: VNF
176     :keyword: MUST
177
178     A VNF's Heat Orchestration Template's OS::Nova::Server
179     Resource **MUST** contain the metadata map value parameter
180     'vnf_name'.
181
182 .. req::
183     :id: R-62428
184     :target: VNF
185     :keyword: MUST
186
187     A VNF's Heat Orchestration Template's OS::Nova::Server
188     Resource metadata map value parameter 'vnf_name' **MUST** be
189     declared as type: 'string'.
190
191 .. req::
192     :id: R-44318
193     :target: VNF
194     :keyword: MUST NOT
195
196     A VNF's Heat Orchestration Template's OS::Nova::Server
197     Resource metadata map value parameter 'vnf_name' **MUST NOT** have
198     parameter contraints defined.
199
200 .. req::
201     :id: R-36542
202     :target: VNF
203     :keyword: MUST NOT
204
205     A VNF's Heat Orchestration Template's OS::Nova::Server
206     Resource metadata map value parameter 'vnf_name' **MUST NOT** be
207     enumerated in the Heat Orchestration Template's environment file.
208
209 .. req::
210     :id: R-16576
211     :target: VNF
212     :keyword: MUST NOT
213
214     If a VNF's Heat Orchestration Template's OS::Nova::Server
215     Resource metadata map value parameter 'vnf_name' is passed into a
216     Nested YAML file, the parameter name 'vnf_name' **MUST NOT** change.
217
218 *Example 'vnf_name' Parameter Definition*
219
220 .. code-block:: yaml
221
222   parameters:
223
224     vnf_name:
225       type: string
226       description: Unique name for this VNF instance
227
228 vf_module_name
229 ^^^^^^^^^^^^^^^^^^
230
231 The OS::Nova::Server Resource metadata map value parameter 'vf_module_name'
232 is the deployment name of the heat stack created (e.g., <STACK_NAME>) from the
233 VNF's Heat Orchestration template
234 in the command 'Heat stack-create'
235 (e.g., 'Heat stack-create [-f <FILE>] [-e <FILE>] <STACK_NAME>').
236 The 'vf_module_name' (e.g., <STACK_NAME> is specified as
237 part of the orchestration process.
238
239
240 .. req::
241     :id: R-68023
242     :target: VNF
243     :keyword: SHOULD
244
245     A VNF's Heat Orchestration Template's OS::Nova::Server
246     Resource **SHOULD** contain the metadata map value parameter
247     'vf_module_name'.
248
249 .. req::
250     :id: R-39067
251     :target: VNF
252     :keyword: MUST
253
254     A VNF's Heat Orchestration Template's OS::Nova::Server
255     Resource metadata map value parameter 'vf_module_name' **MUST**
256     be declared as type: 'string'.
257
258 .. req::
259     :id: R-15480
260     :target: VNF
261     :keyword: MUST NOT
262
263     A VNF's Heat Orchestration Template's OS::Nova::Server
264     Resource metadata map value parameter 'vf_module_name'
265     **MUST NOT** have parameter contraints defined.
266
267 .. req::
268     :id: R-80374
269     :target: VNF
270     :keyword: MUST NOT
271
272     A VNF's Heat Orchestration Template's OS::Nova::Server
273     Resource metadata map value parameter 'vf_module_name'
274     **MUST NOT** be enumerated in the Heat Orchestration Template's
275     environment file.
276
277 .. req::
278     :id: R-49177
279     :target: VNF
280     :keyword: MUST
281
282     If a VNF's Heat Orchestration Template's OS::Nova::Server
283     Resource metadata map value parameter 'vf_module_name' is passed
284     into a Nested YAML file, the parameter name 'vf_module_name'
285     **MUST NOT** change.
286
287 *Example 'vf_module_name' Parameter Definition*
288
289 .. code-block:: yaml
290
291   parameters:
292
293     vf_module_name:
294       type: string
295       description: Unique name for this VNF Module instance
296
297 vm_role
298 ^^^^^^^^^
299
300 The OS::Nova::Server Resource metadata map value parameter 'vm-role'
301 is a metadata tag that describes the role of the Virtual Machine.
302 The 'vm_role' is stored in ONAP's A&AI module and is
303 available for use by other ONAP components and/or north bound systems.
304
305
306 .. req::
307     :id: R-85328
308     :target: VNF
309     :keyword: MAY
310
311     A VNF's Heat Orchestration Template's OS::Nova::Server
312     Resource **MAY** contain the metadata map value parameter 'vm_role'.
313
314 .. req::
315     :id: R-95430
316     :target: VNF
317     :keyword: MUST
318
319     A VNF's Heat Orchestration Template's OS::Nova::Server
320     Resource metadata map value parameter 'vm_role' **MUST** be
321     declared as type: 'string'.
322
323 .. req::
324     :id: R-67597
325     :target: VNF
326     :keyword: MUST NOT
327
328     A VNF's Heat Orchestration Template's OS::Nova::Server
329     Resource metadata map value parameter 'vm_role' **MUST NOT** have
330     parameter contraints defined.
331
332
333 .. req::
334     :id: R-46823
335     :target: VNF
336     :keyword: MUST
337
338     A VNF's Heat Orchestration Template's OS::Nova::Server
339     Resource metadata map value parameter 'vnf_name' **MUST** be
340     either
341
342      - enumerated in the VNF's Heat Orchestration
343        Template's environment file.
344
345      - hard coded in the VNF's Heat Orchestration
346        Template's OS::Nova::Resource metadata property.
347
348 Defining the 'vm_role' as the '{vm-type}' is a recommended convention
349
350
351 .. req::
352     :id: R-86476
353     :target: VNF
354     :keyword: MUST
355
356     If a VNF's Heat Orchestration Template's OS::Nova::Server
357     Resource metadata map value parameter 'vm_role' value **MUST** only
358     contain alphanumeric characters and underscores '_'.
359
360 .. req::
361     :id: R-70757
362     :target: VNF
363     :keyword: MUST NOT
364
365     If a VNF's Heat Orchestration Template's OS::Nova::Server
366     Resource metadata map value parameter 'vm_role' is passed into a
367     Nested YAML file, the parameter name 'vm_role' **MUST NOT** change.
368
369 *Example 'vm_role' Parameter Definition*
370
371 .. code-block:: yaml
372
373   parameters:
374
375     vm_role:
376       type: string
377       description: Unique role for this VM
378
379 *Example: 'vm-role' Definition: Hard Coded in
380 OS::Nova::Resource metadata property*
381
382 .. code-block:: yaml
383
384   resources:
385
386     dns_server_0
387       type: OS::Nova::Server
388       properties:
389         . . . .
390         metadata:
391           vm_role: dns
392
393 *Example 'vm-role' Definition: Defined in Environment file
394 and retrieved via 'get_param'*
395
396 .. code-block:: yaml
397
398   resources:
399
400     dns_server_0:
401       type: OS::Nova::Server
402       properties:
403         . . . .
404         metadata:
405           vm_role: { get_param: vm_role }
406
407 Example vnf_id, vf_module_id, vnf_name, vf_module_name, vm_role
408 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
409
410 The example below depicts part of a Heat Orchestration Template
411 that uses the five of the OS::Nova::Server metadata parameter
412 discussed in this section. The {vm-type} has been defined as lb
413 for load balancer.
414
415 .. code-block:: yaml
416
417   parameters:
418     lb_name_0
419       type: string
420       description: VM Name for lb VM 0
421     vnf_name:
422       type: string
423       description: Unique name for this VNF instance
424     vnf_id:
425       type: string
426       description: Unique ID for this VNF instance
427     vf_module_name:
428       type: string
429       description: Unique name for this VNF Module instance
430     vf_module_id:
431       type: string
432       description: Unique ID for this VNF Module instance
433     vm_role:
434       type: string
435       description: Unique role for this VM
436   resources:
437     lb_server_0:
438       type: OS::Nova::Server
439       properties:
440         name: { get_param: lb_name_0 }
441         ...
442         metadata:
443           vnf_name: { get_param: vnf_name }
444           vnf_id: { get_param: vnf_id }
445           vf_module_name: { get_param: vf_module_name }
446           vf_module_id: { get_param: vf_module_id }
447           vm_role: lb
448
449 vf_module_index
450 ^^^^^^^^^^^^^^^^^^
451
452
453 .. req::
454     :id: R-50816
455     :target: VNF
456     :keyword: MAY
457
458     A VNF's Heat Orchestration Template's OS::Nova::Server
459     Resource **MAY** contain the metadata map value parameter
460     'vf_module_index'.
461
462 .. req::
463     :id: R-54340
464     :target: VNF
465     :keyword: MUST
466
467     A VNF's Heat Orchestration Template's OS::Nova::Server
468     Resource metadata map value parameter 'vf_module_index' **MUST** be
469     declared as type: 'number'.
470
471 .. req::
472     :id: R-09811
473     :target: VNF
474     :keyword: MUST NOT
475
476     A VNF's Heat Orchestration Template's OS::Nova::Server
477     Resource metadata map value parameter 'vf_module_index' **MUST NOT**
478     have parameter contraints defined.
479
480 .. req::
481     :id: R-37039
482     :target: VNF
483     :keyword: MUST NOT
484
485     A VNF's Heat Orchestration Template's OS::Nova::Server
486     Resource metadata map value parameter 'vf_module_index' **MUST NOT**
487     be enumerated in the Heat Orchestration Template's environment file.
488
489 .. req::
490     :id: R-22441
491     :target: VNF
492     :keyword: MUST NOT
493
494     If a VNF's Heat Orchestration Template's OS::Nova::Server
495     Resource metadata map value parameter 'vf\_module\_index' is passed
496     into a Nested YAML file, the parameter name 'vf\_module\_index'
497     **MUST NOT** change.
498
499 .. req::
500     :id: R-55306
501     :target: VNF
502     :keyword: MUST NOT
503
504     If a VNF's Heat Orchestration Template's OS::Nova::Server
505     Resource metadata map value parameter 'vf_module_index' **MUST NOT** be
506     used in a VNF's Volume Template; it is not supported.
507
508 The vf_module_index parameter indicates which instance of the module is being
509 deployed into the VNF.
510 This parameter may be used in cases where multiple instances of the same
511 incremental module may be instantiated for scaling purposes. The index
512 can be used in the Heat Orchestration Template for indexing into a
513 pseudo-constant array parameter when unique values are required for each
514 module instance, e.g., for fixed private IP addresses on VM types.
515
516 The vf_module_index will start at 0 for the first instance of a module
517 type. Subsequent instances of the same module type will receive the
518 lowest unused index. This means that indexes will be reused if a module
519 is deleted and re-added. As an example, if three copies of a module are
520 deployed with vf_module_index values of 0, 1, and 2 then subsequently
521 the second one is deleted (index 1), and then re-added, index 1 will be
522 reused.
523
524 *Example*
525
526 In this example, the {vm-type} has been defined as oam_vm to represent
527 an OAM VM. An incremental heat module is used to deploy the OAM VM. The
528 OAM VM attaches to an internal control network which has a
529 {network-role} of ctrl. A maximum of four OAM VMs can be deployed. The
530 environment file contains the four IP addresses that each successive OAM
531 VM will be assigned. The vf_module_index is used as the index to
532 determine the IP assignment.
533
534 Environment File
535
536 .. code-block:: yaml
537
538   parameters:
539     oam_vm_int_ctrl_ips: 10.10.10.1,10.10.10.2,10.10.10.3,10.10.10.4
540
541 YAML File
542
543 .. code-block:: yaml
544
545  parameters:
546    vf_module_index:
547      type: number
548      description: Unique index for this VNF Module instance
549    oam_vm_name_0:
550      type: string
551      description: VM Name for lb VM 0
552    int_ctrl_net_id:
553      type: string
554      description: Neutron UUID for the internal control network
555    oam_vm_int_ctrl_ips:
556      type: comma_delimited_list
557      description: Fixed IP assignments for oam VMs on the internal control
558      network
559  resources:
560    oam_vm_server_0:
561      type: OS::Nova::Server
562      properties:
563        name: { get_param: oam_vm_name_0 }
564        networks:
565          port: { get_resource: oam_vm_0_int_ctrl_port_0 }
566
567        . . .
568
569        metadata:
570          vf_module_index: { get_param: vf_module_index }
571    oam_vm_0_int_ctrl_port_0:
572      type: OS::Neutron::Port
573      properties:
574        network: { get_param: int_ctrl_net_id }
575        fixed_ips: [ { "ip_address": {get_param: [ oam_vm_int_ctrl_ips, { get_param, vf_module_index}]}}]
576
577 workload_context
578 ^^^^^^^^^^^^^^^^^^^^^
579
580 .. req::
581     :id: R-47061
582     :target: VNF
583     :keyword: SHOULD
584
585     A VNF's Heat Orchestration Template's OS::Nova::Server
586     Resource **SHOULD** contain the metadata map value parameter
587     'workload_context'.
588
589 .. req::
590     :id: R-74978
591     :target: VNF
592     :keyword: MUST
593
594     A VNF's Heat Orchestration Template's OS::Nova::Server
595     Resource metadata map value parameter 'workload_context' **MUST** be
596     declared as type: 'string'.
597
598 .. req::
599     :id: R-34055
600     :target: VNF
601     :keyword: MUST NOT
602
603     A VNF's Heat Orchestration Template's OS::Nova::Server
604     Resource metadata map value parameter 'workload_context' **MUST NOT**
605     have parameter contraints defined.
606
607 .. req::
608     :id: R-02691
609     :target: VNF
610     :keyword: MUST NOT
611
612     A VNF's Heat Orchestration Template's OS::Nova::Server
613     Resource metadata map value parameter 'workload_context' **MUST NOT**
614     be enumerated in the Heat Orchestration Template's environment file.
615
616 .. req::
617     :id: R-75202
618     :target: VNF
619     :keyword: MUST NOT
620
621     If a VNF's Heat Orchestration Template's OS::Nova::Server
622     Resource metadata map value parameter 'workload_context' is passed
623     into a Nested YAML file, the parameter name 'workload_context'
624     **MUST NOT** change.
625
626 The 'workload\_context' parameter value will be chosen by the Service Model
627 Distribution context client in VID and will be supplied to the
628 Heat Orchestration Template by ONAP at orchestration time.
629
630 *Example Parameter Definition*
631
632 .. code-block:: yaml
633
634   parameters:
635     workload_context:
636       type: string
637       description: Workload Context for this VNF instance
638
639
640 *Example OS::Nova::Server with metadata*
641
642 .. code-block:: yaml
643
644   resources:
645     . . .
646
647     {vm-type}_server_{index}:
648        type: OS::Nova::Server
649        properties:
650          name:
651          flavor:
652          image:
653         ...
654        metadata:
655           vnf_name: { get_param: vnf_name }
656           vnf_id: { get_param: vnf_id }
657           vf_module_name: { get_param: vf_module_name }
658           vf_module_id: { get_param: vf_module_id }
659           workload_context: {get_param: workload_context}
660
661 environment_context
662 ^^^^^^^^^^^^^^^^^^^^^
663
664 .. req::
665     :id: R-88536
666     :target: VNF
667     :keyword: SHOULD
668
669     A VNF's Heat Orchestration Template's OS::Nova::Server
670     Resource **SHOULD** contain the metadata map value parameter
671     'environment_context'.
672
673 .. req::
674     :id: R-20308
675     :target: VNF
676     :keyword: MUST
677
678     A VNF's Heat Orchestration Template's OS::Nova::Server
679     Resource metadata map value parameter 'environment_context' **MUST**
680     be declared as type: 'string'.
681
682 .. req::
683     :id: R-56183
684     :target: VNF
685     :keyword: MUST NOT
686
687     A VNF's Heat Orchestration Template's OS::Nova::Server
688     Resource metadata map value parameter 'environment_context' **MUST NOT**
689     have parameter contraints defined.
690
691 .. req::
692     :id: R-13194
693     :target: VNF
694     :keyword: MUST NOT
695
696     A VNF's Heat Orchestration Template's OS::Nova::Server
697     Resource metadata map value parameter 'environment_context' **MUST NOT**
698     be enumerated in the Heat Orchestration Template's environment file.
699
700 .. req::
701     :id: R-62954
702     :target: VNF
703     :keyword: MUST NOT
704
705     If a VNF's Heat Orchestration Template's OS::Nova::Server
706     Resource metadata map value parameter 'environment_context' is
707     passed into a Nested YAML file, the parameter name
708     'environment_context' **MUST NOT** change.
709
710 The 'environment_context' parameter value will be defined by the
711 service designer as part of the service model during the SDC
712 on-boarding process and will be supplied to the Heat Orchestration
713 Template by ONAP at orchestration time.
714
715
716 *Example Parameter Definition*
717
718 .. code-block:: yaml
719
720   parameters:
721     environment_context:
722       type: string
723       description: Environment Context for this VNF instance
724
725
726 *Example OS::Nova::Server with metadata*
727
728 .. code-block:: yaml
729
730   resources:
731     . . .
732
733     {vm-type}_server_{index}:
734        type: OS::Nova::Server
735        properties:
736          name:
737          flavor:
738          image:
739         ...
740        metadata:
741           vnf_name: { get_param: vnf_name }
742           vnf_id: { get_param: vnf_id }
743           vf_module_name: { get_param: vf_module_name }
744           vf_module_id: { get_param: vf_module_id }
745           workload_context: {get_param: workload_context}
746           environment_context: {get_param: environment_context }