code.grnet.gr Git - ganeti-local/blob - man/ganeti-extstorage-interface.rst

   1 ganeti-extstorage-interface(7) Ganeti | Version @GANETI_VERSION@
   2 ================================================================
   3
   4 Name
   5 ----
   6
   7 ganeti-extstorage-interface - Specifications for ExtStorage providers
   8
   9 DESCRIPTION
  10 -----------
  11
  12 The method for supporting external shared storage in Ganeti is to have
  13 an ExtStorage provider for each external shared storage hardware type.
  14 The ExtStorage provider is a set of files (executable scripts and text
  15 files), contained inside a directory which is named after the provider.
  16 This directory must be present across all nodes of a nodegroup (Ganeti
  17 doesn't replicate it), in order for the provider to be usable by Ganeti
  18 for this nodegroup (valid). The external shared storage hardware should
  19 also be accessible by all nodes of this nodegroup too.
  20
  21 REFERENCE
  22 ---------
  23
  24 There are seven required files: *create*, *attach*, *detach*, *remove*,
  25 *grow*, *verify* (executables) and *parameters.list* (text file).
  26
  27 Common environment
  28 ~~~~~~~~~~~~~~~~~~
  29
  30 All commands will get their input via environment variables. A common
  31 set of variables will be exported for all commands, and some of them
  32 might have extra ones. Note that all counts are zero-based.
  33
  34 Since Ganeti version 2.5, the environment will be cleaned up before
  35 being passed to scripts, therefore they will not inherit the environment
  36 in with which the ganeti node daemon was started. If you depend on any
  37 environment variables (non-Ganeti), then you will need to define or
  38 source them appropriately.
  39
  40 VOL_NAME
  41     The name of the volume. This is unique for Ganeti and it uses it
  42     to refer to a specific volume inside the external storage. Its
  43     format is ``UUID.ext.diskX`` where ``UUID`` is produced by Ganeti
  44     and is unique inside the Ganeti context. ``X`` is the number of the
  45     disk count.
  46
  47 VOL_SIZE
  48     The volume's size in mebibytes.
  49
  50 VOL_NEW_SIZE
  51     Available only to the **grow** script. It declares the new size of
  52     the volume after grow (in mebibytes). To find the amount of grow,
  53     the scipt should calculate the number VOL_NEW_SIZE - VOL_SIZE.
  54
  55 EXTP_*name*
  56     Each ExtStorage parameter (see below) will be exported in its own
  57     variable, prefixed with ``EXTP_``, and upper-cased. For example, a
  58     ``fromsnap`` parameter will be exported as ``EXTP_FROMSNAP``.
  59
  60 EXECUTABLE SCRIPTS
  61 ------------------
  62
  63
  64 create
  65 ~~~~~~
  66
  67 The **create** command is used for creating a new volume inside the
  68 external storage. The ``VOL_NAME`` denotes the volume's name, which
  69 should be unique. After creation, Ganeti will refer to this volume by
  70 this name for all other actions.
  71
  72 Ganeti produces this name dynamically and ensures its uniqueness inside
  73 the Ganeti context. Therefore, you should make sure not to provision
  74 manually additional volumes inside the external storage with this type
  75 of name, because this will lead to conflicts and possible loss of data.
  76
  77 The ``VOL_SIZE`` variable denotes the size of the new volume to be
  78 created in mebibytes.
  79
  80 If the script ends successfully, a new volume of size ``VOL_SIZE``
  81 should exist inside the external storage. e.g:: a lun inside a NAS
  82 appliance.
  83
  84 The script returns ``0`` on success.
  85
  86 attach
  87 ~~~~~~
  88
  89 This command is used in order to make an already created volume visible
  90 to the physical node which will host the instance. This is done by
  91 mapping the already provisioned volume to a block device inside the host
  92 node.
  93
  94 The ``VOL_NAME`` variable denotes the volume to be mapped.
  95
  96 After successful attachment the script returns to its stdout a string,
  97 which is the full path of the block device to which the volume is
  98 mapped.  e.g:: /dev/dummy1
  99
 100 When attach returns, this path should be a valid block device on the
 101 host node.
 102
 103 The attach script should be idempotent if the volume is already mapped.
 104 If the requested volume is already mapped, then the script should just
 105 return to its stdout the path which is already mapped to.
 106
 107 detach
 108 ~~~~~~
 109
 110 This command is used in order to unmap an already mapped volume from the
 111 host node. Detach undoes everything attach did. This is done by
 112 unmapping the requested volume from the block device it is mapped to.
 113
 114 The ``VOL_NAME`` variable denotes the volume to be unmapped.
 115
 116 ``detach`` doesn't affect the volume itself. It just unmaps it from the
 117 host node. The volume continues to exist inside the external storage.
 118 It's just not accessible by the node anymore. This script doesn't return
 119 anything to its stdout.
 120
 121 The detach script should be idempotent if the volume is already
 122 unmapped. If the volume is not mapped, the script doesn't perform any
 123 action at all.
 124
 125 The script returns ``0`` on success.
 126
 127 remove
 128 ~~~~~~
 129
 130 This command is used to remove an existing volume from the external
 131 storage. The volume is permanently removed from inside the external
 132 storage along with all its data.
 133
 134 The ``VOL_NAME`` variable denotes the volume to be removed.
 135
 136 The script returns ``0`` on success.
 137
 138 grow
 139 ~~~~
 140
 141 This command is used to grow an existing volume of the external storage.
 142
 143 The ``VOL_NAME`` variable denotes the volume to grow.
 144
 145 The ``VOL_SIZE`` variable denotes the current volume's size (in
 146 mebibytes). The ``VOL_NEW_SIZE`` variable denotes the final size after
 147 the volume has been grown (in mebibytes).
 148
 149 The amount of grow can be easily calculated by the scipt and is:
 150
 151 grow_amount = VOL_NEW_SIZE - VOL_SIZE (in mebibytes)
 152
 153 Ganeti ensures that: ``VOL_NEW_SIZE`` > ``VOL_SIZE``
 154
 155 If the script returns successfully, then the volume inside the external
 156 storage will have a new size of ``VOL_NEW_SIZE``. This isn't immediately
 157 reflected to the instance's disk. See ``gnt-instance grow`` for more
 158 details on when the running instance becomes aware of its grown disk.
 159
 160 The script returns ``0`` on success.
 161
 162 verify
 163 ~~~~~~
 164
 165 The *verify* script is used to verify consistency of the external
 166 parameters (ext-params) (see below). The command should take one or more
 167 arguments denoting what checks should be performed, and return a proper
 168 exit code depending on whether the validation failed or succeeded.
 169
 170 Currently, the script is not invoked by Ganeti, but should be present
 171 for future use and consistency with gnt-os-interface's verify script.
 172
 173 The script should return ``0`` on success.
 174
 175 TEXT FILES
 176 ----------
 177
 178
 179 parameters.list
 180 ~~~~~~~~~~~~~~~
 181
 182 This file declares the parameters supported by the ExtStorage provider,
 183 one parameter per line, with name and description (space and/or tab
 184 separated). For example::
 185
 186     fromsnap Snapshot name to create the volume from
 187     nas_ip The IP of the NAS appliance
 188
 189 The parameters can then be used during instance add as follows::
 190
 191     # gnt-instance add --disk=0:fromsnap="file_name",nas_ip="1.2.3.4" ...
 192
 193 NOTES
 194 -----
 195
 196 Backwards compatibility
 197 ~~~~~~~~~~~~~~~~~~~~~~~
 198
 199 The ExtStorage Interface was introduced in Ganeti 2.6.
 200 Ganeti 2.6 and up is compatible with the ExtStorage Interface.
 201
 202 Common behaviour
 203 ~~~~~~~~~~~~~~~~
 204
 205 All the scripts should display an usage message when called with a wrong
 206 number of arguments or when the first argument is ``-h`` or ``--help``.
 207
 208 .. vim: set textwidth=72 :
 209 .. Local Variables:
 210 .. mode: rst
 211 .. fill-column: 72
 212 .. End: