root / man / ganeti-extstorage-interface.rst @ 4edaf707
History | View | Annotate | Download (8.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 |
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: |