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 volume template must define ``outputs`` for each Cinder volume resource
  52 universally unique identifier (UUID) (i.e. ECOMP Volume Template Output
  53 Parameters.
  54
  55 -  The VNF Incremental Module or Base Module must define input
  56    parameters that match each Volume output parameter (i.e., ONAP Volume
  57    Template Output Parameters).
  58
  59    -  ONAP will supply the volume template outputs automatically to the
  60       bases/incremental template input parameters.
  61
  62 -  Volume modules may utilize nested Heat templates.
  63
  64 .. req::
  65     :id: R-270358
  66     :target: VNF
  67     :keyword: MUST
  68     :validation_mode: static
  69     :introduced: casablanca
  70
  71     A VNF's Heat Orchestration Template's Cinder Volume Template **MUST**
  72     contain either
  73
  74     * An ``OS::Cinder::Volume`` resource
  75     * An ``OS::Heat::ResourceGroup`` resource that references a Nested YAML
  76       file that contains an ``OS::Cinder::Volume`` resource
  77     * A resource that defines the property ``type`` as a Nested YAML file
  78       (i.e., static nesting) and the Nested YAML contains
  79       an ``OS::Cinder::Volume`` resource
  80
  81 Optional Property availability_zone
  82 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  83
  84 .. req::
  85     :id: R-25190
  86     :target: VNF
  87     :keyword: SHOULD NOT
  88     :updated: casablanca
  89
  90     A VNF's Heat Orchestration Template's Resource ``OS::Cinder::Volume``
  91     **SHOULD NOT** declare the property ``availability_zone``.
  92
  93 If the property is used, the value **MUST**
  94 be enumerated in the environment file and must be set to ``nova``, which
  95 is the default. There are no requirements on the parameter naming
  96 convention with the exception that the naming convention **MUST NOT** be the
  97 same as the ``OS::Nova::Server`` property ``availability_zone`` (i.e.,
  98 ``availability_zone_{index}``).
  99
 100 Optional Property volume_type
 101 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 102
 103 OpenStack supports multiple volume types. If the ``OS::Cinder::Volume``
 104 optional property ``volume_type`` is not specified, the OpenStack default
 105 ``volume type`` is used. If a specific volume type is required, the property
 106 is used and the value **MUST** be enumerated in the environment file. There
 107 are no requirements on the parameter naming convention.
 108
 109 Cinder Volume Examples
 110 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 111
 112 *Examples: Volume Template*
 113
 114 A VNF has a Cinder volume module, named incremental_volume.yaml,
 115 that creates an independent Cinder volume for a VM in the module
 116 incremental.yaml. The incremental_volume.yaml defines a parameter in
 117 the output section, dns_volume_id_0 which is the UUID of the cinder volume.
 118 dns_volume_id_0 is defined as a parameter in incremental.yaml.
 119 ONAP captures the UUID value of dns_volume_id_0 from the volume module
 120 output statement and provides the value to the incremental module.
 121
 122 Note that the example below is not a complete Heat Orchestration
 123 Template. The {vm-type} has been defined as "dns".
 124
 125 incremental_volume.yaml
 126
 127 .. code-block:: yaml
 128
 129   parameters:
 130     vnf_name:
 131       type: string
 132     dns_volume_size_0:
 133       type: number
 134   ...
 135
 136   resources:
 137     dns_volume_0:
 138       type: OS::Cinder::Volume
 139       properties:
 140         name:
 141           str_replace:
 142             template: VNF_NAME_volume_0
 143             params:
 144               VNF_NAME: { get_param: vnf_name }
 145         size: {get_param: dns_volume_size_0}
 146   ...
 147   outputs:
 148     dns_volume_id_0:
 149       value: {get_resource: dns_volume_0}
 150   ...
 151
 152 incremental.yaml
 153
 154 .. code-block:: yaml
 155
 156   parameters:
 157     dns_server_0:
 158       type: string
 159     dns_volume_id_0:
 160       type: string
 161   ...
 162
 163   resources:
 164     dns_server_0:
 165       type: OS::Nova::Server
 166       properties:
 167         name: {get_param: dns_name_0}
 168         networks:
 169   ...
 170     dns_volume_attach_0:
 171       type: OS::Cinder::VolumeAttachment
 172       properties:
 173         instance_uuid: { get_resource: dns_server_0 }
 174         volume_id: { get_param: dns_volume_id_0 }