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