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 create
  70 ~~~~~~
  71
  72 The **create** command is used for creating a new volume inside the
  73 external storage. The ``VOL_NAME`` denotes the volume's name, which
  74 should be unique. After creation, Ganeti will refer to this volume by
  75 this name for all other actions.
  76
  77 Ganeti produces this name dynamically and ensures its uniqueness inside
  78 the Ganeti context. Therefore, you should make sure not to provision
  79 manually additional volumes inside the external storage with this type
  80 of name, because this will lead to conflicts and possible loss of data.
  81
  82 The ``VOL_SIZE`` variable denotes the size of the new volume to be
  83 created in mebibytes.
  84
  85 If the script ends successfully, a new volume of size ``VOL_SIZE``
  86 should exist inside the external storage. e.g:: a lun inside a NAS
  87 appliance.
  88
  89 The script returns ``0`` on success.
  90
  91 attach
  92 ~~~~~~
  93
  94 This command is used in order to make an already created volume visible
  95 to the physical node which will host the instance. This is done by
  96 mapping the already provisioned volume to a block device inside the host
  97 node.
  98
  99 The ``VOL_NAME`` variable denotes the volume to be mapped.
 100
 101 After successful attachment the script returns to its stdout a string,
 102 which is the full path of the block device to which the volume is
 103 mapped.  e.g:: /dev/dummy1
 104
 105 When attach returns, this path should be a valid block device on the
 106 host node.
 107
 108 The attach script should be idempotent if the volume is already mapped.
 109 If the requested volume is already mapped, then the script should just
 110 return to its stdout the path which is already mapped to.
 111
 112 detach
 113 ~~~~~~
 114
 115 This command is used in order to unmap an already mapped volume from the
 116 host node. Detach undoes everything attach did. This is done by
 117 unmapping the requested volume from the block device it is mapped to.
 118
 119 The ``VOL_NAME`` variable denotes the volume to be unmapped.
 120
 121 ``detach`` doesn't affect the volume itself. It just unmaps it from the
 122 host node. The volume continues to exist inside the external storage.
 123 It's just not accessible by the node anymore. This script doesn't return
 124 anything to its stdout.
 125
 126 The detach script should be idempotent if the volume is already
 127 unmapped. If the volume is not mapped, the script doesn't perform any
 128 action at all.
 129
 130 The script returns ``0`` on success.
 131
 132 remove
 133 ~~~~~~
 134
 135 This command is used to remove an existing volume from the external
 136 storage. The volume is permanently removed from inside the external
 137 storage along with all its data.
 138
 139 The ``VOL_NAME`` variable denotes the volume to be removed.
 140
 141 The script returns ``0`` on success.
 142
 143 grow
 144 ~~~~
 145
 146 This command is used to grow an existing volume of the external storage.
 147
 148 The ``VOL_NAME`` variable denotes the volume to grow.
 149
 150 The ``VOL_SIZE`` variable denotes the current volume's size (in
 151 mebibytes). The ``VOL_NEW_SIZE`` variable denotes the final size after
 152 the volume has been grown (in mebibytes).
 153
 154 The amount of grow can be easily calculated by the scipt and is:
 155
 156 grow_amount = VOL_NEW_SIZE - VOL_SIZE (in mebibytes)
 157
 158 Ganeti ensures that: ``VOL_NEW_SIZE`` > ``VOL_SIZE``
 159
 160 If the script returns successfully, then the volume inside the external
 161 storage will have a new size of ``VOL_NEW_SIZE``. This isn't immediately
 162 reflected to the instance's disk. See ``gnt-instance grow`` for more
 163 details on when the running instance becomes aware of its grown disk.
 164
 165 The script returns ``0`` on success.
 166
 167 setinfo
 168 ~~~~~~~
 169
 170 This script is used to add metadata to an existing volume. It is helpful
 171 when we need to keep an external, Ganeti-independent mapping between
 172 instances and volumes; primarily for recovery reasons. This is provider
 173 specific and the author of the provider chooses whether/how to implement
 174 this. You can just exit with ``0``, if you do not want to implement this
 175 feature, without harming the overall functionality of the provider.
 176
 177 The ``VOL_METADATA`` variable contains the metadata of the volume.
 178
 179 Currently, Ganeti sets this value to ``originstname+X`` where ``X`` is
 180 the instance's name.
 181
 182 The script returns ``0`` on success.
 183
 184 verify
 185 ~~~~~~
 186
 187 The *verify* script is used to verify consistency of the external
 188 parameters (ext-params) (see below). The command should take one or more
 189 arguments denoting what checks should be performed, and return a proper
 190 exit code depending on whether the validation failed or succeeded.
 191
 192 Currently, the script is not invoked by Ganeti, but should be present
 193 for future use and consistency with gnt-os-interface's verify script.
 194
 195 The script should return ``0`` on success.
 196
 197 TEXT FILES
 198 ----------
 199
 200 parameters.list
 201 ~~~~~~~~~~~~~~~
 202
 203 This file declares the parameters supported by the ExtStorage provider,
 204 one parameter per line, with name and description (space and/or tab
 205 separated). For example::
 206
 207     fromsnap Snapshot name to create the volume from
 208     nas_ip The IP of the NAS appliance
 209
 210 The parameters can then be used during instance add as follows::
 211
 212     # gnt-instance add --disk=0:fromsnap="file_name",nas_ip="1.2.3.4" ...
 213
 214 EXAMPLES
 215 --------
 216
 217 In the following examples we assume that you have already installed
 218 successfully two ExtStorage providers: ``pvdr1`` and ``pvdr2``
 219
 220 Add a new instance with a 10G first disk provided by ``pvdr1`` and a 20G
 221 second disk provided by ``pvdr2``::
 222
 223     # gnt-instance add -t ext --disk=0:size=10G,provider=pvdr1
 224                               --disk=1:size=20G,provider=pvdr2
 225
 226 Add a new instance with a 5G first disk provided by provider ``pvdr1``
 227 and also pass the ``prm1``, ``prm2`` parameters to the provider, with
 228 the corresponding values ``val1``, ``val2``::
 229
 230    # gnt-instance add -t ext
 231                       --disk=0:size=5G,provider=pvdr1,prm1=val1,prm2=val2
 232
 233 Modify an existing instance of disk type ``ext`` by adding a new 30G
 234 disk provided by provider ``pvdr2``::
 235
 236    # gnt-instance modify --disk 1:add,size=30G,provider=pvdr2 <instance>
 237
 238 Modify an existing instance of disk type ``ext`` by adding 2 new disks,
 239 of different providers, passing one parameter for the first one::
 240
 241    # gnt-instance modify --disk 2:add,size=3G,provider=pvdr1,prm1=val1
 242                          --disk 3:add,size=5G,provider=pvdr2
 243                          <instance>
 244
 245 NOTES
 246 -----
 247
 248 Backwards compatibility
 249 ~~~~~~~~~~~~~~~~~~~~~~~
 250
 251 The ExtStorage Interface was introduced in Ganeti 2.7.
 252 Ganeti 2.7 and up is compatible with the ExtStorage Interface.
 253
 254 Common behaviour
 255 ~~~~~~~~~~~~~~~~
 256
 257 All the scripts should display an usage message when called with a wrong
 258 number of arguments or when the first argument is ``-h`` or ``--help``.
 259
 260 .. vim: set textwidth=72 :
 261 .. Local Variables:
 262 .. mode: rst
 263 .. fill-column: 72
 264 .. End: