1 ganeti-extstorage-interface(7) Ganeti | Version @GANETI_VERSION@
2 ================================================================
7 ganeti-extstorage-interface - Specifications for ExtStorage providers
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.
24 There are eight required files: *create*, *attach*, *detach*, *remove*,
25 *grow*, *setinfo*, *verify* (executables) and *parameters.list*
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.
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.
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
49 The volume's size in mebibytes.
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.
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``.
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.
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.
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.
82 The ``VOL_SIZE`` variable denotes the size of the new volume to be
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
89 The script returns ``0`` on success.
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
99 The ``VOL_NAME`` variable denotes the volume to be mapped.
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
105 When attach returns, this path should be a valid block device on the
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.
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.
119 The ``VOL_NAME`` variable denotes the volume to be unmapped.
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.
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
130 The script returns ``0`` on success.
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.
139 The ``VOL_NAME`` variable denotes the volume to be removed.
141 The script returns ``0`` on success.
146 This command is used to grow an existing volume of the external storage.
148 The ``VOL_NAME`` variable denotes the volume to grow.
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).
154 The amount of grow can be easily calculated by the scipt and is:
156 grow_amount = VOL_NEW_SIZE - VOL_SIZE (in mebibytes)
158 Ganeti ensures that: ``VOL_NEW_SIZE`` > ``VOL_SIZE``
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.
165 The script returns ``0`` on success.
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.
177 The ``VOL_METADATA`` variable contains the metadata of the volume.
179 Currently, Ganeti sets this value to ``originstname+X`` where ``X`` is
182 The script returns ``0`` on success.
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.
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.
195 The script should return ``0`` on success.
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::
207 fromsnap Snapshot name to create the volume from
208 nas_ip The IP of the NAS appliance
210 The parameters can then be used during instance add as follows::
212 # gnt-instance add --disk=0:fromsnap="file_name",nas_ip="1.2.3.4" ...
217 In the following examples we assume that you have already installed
218 successfully two ExtStorage providers: ``pvdr1`` and ``pvdr2``
220 Add a new instance with a 10G first disk provided by ``pvdr1`` and a 20G
221 second disk provided by ``pvdr2``::
223 # gnt-instance add -t ext --disk=0:size=10G,provider=pvdr1
224 --disk=1:size=20G,provider=pvdr2
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``::
230 # gnt-instance add -t ext
231 --disk=0:size=5G,provider=pvdr1,prm1=val1,prm2=val2
233 Modify an existing instance of disk type ``ext`` by adding a new 30G
234 disk provided by provider ``pvdr2``::
236 # gnt-instance modify --disk 1:add,size=30G,provider=pvdr2 <instance>
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::
241 # gnt-instance modify --disk 2:add,size=3G,provider=pvdr1,prm1=val1
242 --disk 3:add,size=5G,provider=pvdr2
248 Backwards compatibility
249 ~~~~~~~~~~~~~~~~~~~~~~~
251 The ExtStorage Interface was introduced in Ganeti 2.7.
252 Ganeti 2.7 and up is compatible with the ExtStorage Interface.
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``.
260 .. vim: set textwidth=72 :