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