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