Statistics
| Branch: | Tag: | Revision:

root / man / ganeti-extstorage-interface.rst @ 855f9bad

History | View | Annotate | Download (7.8 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

    
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: