docs/Chapter5/Heat/ONAP Heat Cinder Volumes.rst

   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 .. _ONAP Heat Cinder Volumes:
   6
   7 ONAP Heat Cinder Volumes
   8 ----------------------------
   9
  10 Cinder Volumes are created with the heat resource OS::Cinder::Volume.
  11
  12 As stated in :need:`R-46119`, :need:`R-90748`, :need:`R-03251`, a
  13 VNF's Heat Orchestration Template's Resource OS::Heat::CinderVolume
  14 **MAY** be defined in a Base Module, Incremental Module, or Cinder
  15 Volume Module.
  16
  17 ONAP supports the independent deployment of a Cinder volume via separate
  18 Heat Orchestration Templates, the Cinder Volume module. This allows the
  19 volume to persist after VNF deletion so that they can be reused on
  20 another instance (e.g., during a failover activity).
  21
  22 A Base Module or Incremental Module may have a corresponding volume
  23 module. Use of separate volume modules is optional. A Cinder volume may
  24 be embedded within the Base Module or Incremental Module if persistence
  25 is not required.
  26
  27 If a VNF Base Module or Incremental Module has an independent volume
  28 module, the scope of volume templates must be 1:1 with Base module or
  29 Incremental module. A single volume module must create only the volumes
  30 required by a single Incremental module or Base module.
  31
  32 As stated in :need:`R-11200`, a VNF's Cinder Volume Module, when it exists,
  33 **MUST** be 1:1 with a Base module or Incremental module.  That is,
  34 A single volume module must create only the volumes required by a
  35 single Incremental module or Base module.
  36
  37 As stated in :need:`R-30395`, a VNF's Cinder Volume Module **MAY** utilize
  38 nested heat.
  39
  40 As stated in :need:`R-89913`, a VNF's Heat Orchestration Template's Cinder
  41 Volume Module Output Parameter(s) **MUST** include the
  42 UUID(s) of the Cinder Volumes created in template,
  43 while others **MAY** be included.
  44
  45 As stated in :need:`R-07443`, a VNF's Heat Orchestration Templates' Cinder
  46 Volume Module Output Parameter's name and type **MUST** match the input
  47 parameter name and type in the corresponding Base Module or Incremental
  48 Module unless the Output Parameter is of the type ``comma_delimited_list``,
  49 then the corresponding input parameter **MUST** be declared as type ``json``.
  50
  51 A single volume module must create only the volumes
  52 required by a single Incremental module or Base module.
  53
  54 The following rules apply to independent volume Heat templates:
  55
  56 .. req::
  57     :id: R-79531
  58     :target: VNF
  59     :keyword: MUST
  60
  61     The VNF Heat Orchestration Template **MUST** define
  62     "outputs" in the volume template for each Cinder volume
  63     resource universally unique identifier (UUID) (i.e. ONAP
  64     Volume Template Output Parameters).
  65
  66 -  The VNF Incremental Module or Base Module must define input
  67    parameters that match each Volume output parameter (i.e., ONAP Volume
  68    Template Output Parameters).
  69
  70    -  ONAP will supply the volume template outputs automatically to the
  71       bases/incremental template input parameters.
  72
  73 -  Volume modules may utilize nested Heat templates.
  74
  75 .. req::
  76     :id: R-270358
  77     :target: VNF
  78     :keyword: MUST
  79     :validation_mode: static
  80     :updated: casablanca
  81
  82     A VNF's Heat Orchestration Template's Cinder Volume Template **MUST**
  83     contain either
  84
  85     * An ``OS::Cinder::Volume`` resource
  86     * An ``OS::Heat::ResourceGroup`` resource that references a Nested YAML
  87       file that contains an ``OS::Cinder::Volume`` resource
  88     * A resource that defines the property ``type`` as a Nested YAML file
  89       (i.e., static nesting) and the Nested YAML contains
  90       an ``OS::Cinder::Volume`` resource
  91
  92 Optional Property availability_zone
  93 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  94
  95 .. req::
  96     :id: R-25190
  97     :target: VNF
  98     :keyword: SHOULD NOT
  99     :updated: casablanca
 100
 101     A VNF's Heat Orchestration Template's Resource ``OS::Cinder::Volume``
 102     **SHOULD NOT** declare the property ``availability_zone``.
 103
 104 If the property is used, the value **MUST**
 105 be enumerated in the environment file and must be set to ``nova``, which
 106 is the default. There are no requirements on the parameter naming
 107 convention with the exception that the naming convention **MUST NOT** be the
 108 same as the ``OS::Nova::Server`` property ``availability_zone`` (i.e.,
 109 ``availability_zone_{index}``).
 110
 111 Optional Property volume_type
 112 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 113
 114 OpenStack supports multiple volume types. If the ``OS::Cinder::Volume``
 115 optional property ``volume_type`` is not specified, the OpenStack default
 116 ``volume type`` is used. If a specific volume type is required, the property
 117 is used and the value **MUST** be enumerated in the environment file. There
 118 are no requirements on the parameter naming convention.
 119
 120 Cinder Volume Examples
 121 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 122
 123 *Examples: Volume Template*
 124
 125 A VNF has a Cinder volume module, named incremental_volume.yaml,
 126 that creates an independent Cinder volume for a VM in the module
 127 incremental.yaml. The incremental_volume.yaml defines a parameter in
 128 the output section, dns_volume_id_0 which is the UUID of the cinder volume.
 129 dns_volume_id_0 is defined as a parameter in incremental.yaml.
 130 ONAP captures the UUID value of dns_volume_id_0 from the volume module
 131 output statement and provides the value to the incremental module.
 132
 133 Note that the example below is not a complete Heat Orchestration
 134 Template. The {vm-type} has been defined as "dns".
 135
 136 incremental_volume.yaml
 137
 138 .. code-block:: yaml
 139
 140   parameters:
 141     vnf_name:
 142       type: string
 143     dns_volume_size_0:
 144       type: number
 145   ...
 146
 147   resources:
 148     dns_volume_0:
 149       type: OS::Cinder::Volume
 150       properties:
 151         name:
 152           str_replace:
 153             template: VNF_NAME_volume_0
 154             params:
 155               VNF_NAME: { get_param: vnf_name }
 156         size: {get_param: dns_volume_size_0}
 157   ...
 158   outputs:
 159     dns_volume_id_0:
 160       value: {get_resource: dns_volume_0}
 161   ...
 162
 163 incremental.yaml
 164
 165 .. code-block:: yaml
 166
 167   parameters:
 168     dns_server_0:
 169       type: string
 170     dns_volume_id_0:
 171       type: string
 172   ...
 173
 174   resources:
 175     dns_server_0:
 176       type: OS::Nova::Server
 177       properties:
 178         name: {get_param: dns_name_0}
 179         networks:
 180   ...
 181     dns_volume_attach_0:
 182       type: OS::Cinder::VolumeAttachment
 183       properties:
 184         instance_uuid: { get_resource: dns_server_0 }
 185         volume_id: { get_param: dns_volume_id_0 }