root / doc / admin.rst @ 0565f862
History | View | Annotate | Download (73.6 kB)
1 |
Ganeti administrator's guide |
---|---|
2 |
============================ |
3 |
|
4 |
Documents Ganeti version |version| |
5 |
|
6 |
.. contents:: |
7 |
|
8 |
.. highlight:: shell-example |
9 |
|
10 |
Introduction |
11 |
------------ |
12 |
|
13 |
Ganeti is a virtualization cluster management software. You are expected |
14 |
to be a system administrator familiar with your Linux distribution and |
15 |
the Xen or KVM virtualization environments before using it. |
16 |
|
17 |
The various components of Ganeti all have man pages and interactive |
18 |
help. This manual though will help you getting familiar with the system |
19 |
by explaining the most common operations, grouped by related use. |
20 |
|
21 |
After a terminology glossary and a section on the prerequisites needed |
22 |
to use this manual, the rest of this document is divided in sections |
23 |
for the different targets that a command affects: instance, nodes, etc. |
24 |
|
25 |
.. _terminology-label: |
26 |
|
27 |
Ganeti terminology |
28 |
++++++++++++++++++ |
29 |
|
30 |
This section provides a small introduction to Ganeti terminology, which |
31 |
might be useful when reading the rest of the document. |
32 |
|
33 |
Cluster |
34 |
~~~~~~~ |
35 |
|
36 |
A set of machines (nodes) that cooperate to offer a coherent, highly |
37 |
available virtualization service under a single administration domain. |
38 |
|
39 |
Node |
40 |
~~~~ |
41 |
|
42 |
A physical machine which is member of a cluster. Nodes are the basic |
43 |
cluster infrastructure, and they don't need to be fault tolerant in |
44 |
order to achieve high availability for instances. |
45 |
|
46 |
Node can be added and removed (if they host no instances) at will from |
47 |
the cluster. In a HA cluster and only with HA instances, the loss of any |
48 |
single node will not cause disk data loss for any instance; of course, |
49 |
a node crash will cause the crash of its primary instances. |
50 |
|
51 |
A node belonging to a cluster can be in one of the following roles at a |
52 |
given time: |
53 |
|
54 |
- *master* node, which is the node from which the cluster is controlled |
55 |
- *master candidate* node, only nodes in this role have the full cluster |
56 |
configuration and knowledge, and only master candidates can become the |
57 |
master node |
58 |
- *regular* node, which is the state in which most nodes will be on |
59 |
bigger clusters (>20 nodes) |
60 |
- *drained* node, nodes in this state are functioning normally but the |
61 |
cannot receive new instances; the intention is that nodes in this role |
62 |
have some issue and they are being evacuated for hardware repairs |
63 |
- *offline* node, in which there is a record in the cluster |
64 |
configuration about the node, but the daemons on the master node will |
65 |
not talk to this node; any instances declared as having an offline |
66 |
node as either primary or secondary will be flagged as an error in the |
67 |
cluster verify operation |
68 |
|
69 |
Depending on the role, each node will run a set of daemons: |
70 |
|
71 |
- the :command:`ganeti-noded` daemon, which controls the manipulation of |
72 |
this node's hardware resources; it runs on all nodes which are in a |
73 |
cluster |
74 |
- the :command:`ganeti-confd` daemon (Ganeti 2.1+) which runs on all |
75 |
nodes, but is only functional on master candidate nodes; this daemon |
76 |
can be disabled at configuration time if you don't need its |
77 |
functionality |
78 |
- the :command:`ganeti-rapi` daemon which runs on the master node and |
79 |
offers an HTTP-based API for the cluster |
80 |
- the :command:`ganeti-masterd` daemon which runs on the master node and |
81 |
allows control of the cluster |
82 |
|
83 |
Beside the node role, there are other node flags that influence its |
84 |
behaviour: |
85 |
|
86 |
- the *master_capable* flag denotes whether the node can ever become a |
87 |
master candidate; setting this to 'no' means that auto-promotion will |
88 |
never make this node a master candidate; this flag can be useful for a |
89 |
remote node that only runs local instances, and having it become a |
90 |
master is impractical due to networking or other constraints |
91 |
- the *vm_capable* flag denotes whether the node can host instances or |
92 |
not; for example, one might use a non-vm_capable node just as a master |
93 |
candidate, for configuration backups; setting this flag to no |
94 |
disallows placement of instances of this node, deactivates hypervisor |
95 |
and related checks on it (e.g. bridge checks, LVM check, etc.), and |
96 |
removes it from cluster capacity computations |
97 |
|
98 |
|
99 |
Instance |
100 |
~~~~~~~~ |
101 |
|
102 |
A virtual machine which runs on a cluster. It can be a fault tolerant, |
103 |
highly available entity. |
104 |
|
105 |
An instance has various parameters, which are classified in three |
106 |
categories: hypervisor related-parameters (called ``hvparams``), general |
107 |
parameters (called ``beparams``) and per network-card parameters (called |
108 |
``nicparams``). All these parameters can be modified either at instance |
109 |
level or via defaults at cluster level. |
110 |
|
111 |
Disk template |
112 |
~~~~~~~~~~~~~ |
113 |
|
114 |
The are multiple options for the storage provided to an instance; while |
115 |
the instance sees the same virtual drive in all cases, the node-level |
116 |
configuration varies between them. |
117 |
|
118 |
There are several disk templates you can choose from: |
119 |
|
120 |
``diskless`` |
121 |
The instance has no disks. Only used for special purpose operating |
122 |
systems or for testing. |
123 |
|
124 |
``file`` ***** |
125 |
The instance will use plain files as backend for its disks. No |
126 |
redundancy is provided, and this is somewhat more difficult to |
127 |
configure for high performance. |
128 |
|
129 |
``sharedfile`` ***** |
130 |
The instance will use plain files as backend, but Ganeti assumes that |
131 |
those files will be available and in sync automatically on all nodes. |
132 |
This allows live migration and failover of instances using this |
133 |
method. |
134 |
|
135 |
``plain`` |
136 |
The instance will use LVM devices as backend for its disks. No |
137 |
redundancy is provided. |
138 |
|
139 |
``drbd`` |
140 |
.. note:: This is only valid for multi-node clusters using DRBD 8.0+ |
141 |
|
142 |
A mirror is set between the local node and a remote one, which must be |
143 |
specified with the second value of the --node option. Use this option |
144 |
to obtain a highly available instance that can be failed over to a |
145 |
remote node should the primary one fail. |
146 |
|
147 |
.. note:: Ganeti does not support DRBD stacked devices: |
148 |
DRBD stacked setup is not fully symmetric and as such it is |
149 |
not working with live migration. |
150 |
|
151 |
``rbd`` |
152 |
The instance will use Volumes inside a RADOS cluster as backend for its |
153 |
disks. It will access them using the RADOS block device (RBD). |
154 |
|
155 |
``gluster`` ***** |
156 |
The instance will use a Gluster volume for instance storage. Disk |
157 |
images will be stored in the top-level ``ganeti/`` directory of the |
158 |
volume. This directory will be created automatically for you. |
159 |
|
160 |
``ext`` |
161 |
The instance will use an external storage provider. See |
162 |
:manpage:`ganeti-extstorage-interface(7)` for how to implement one. |
163 |
|
164 |
.. note:: |
165 |
Disk templates marked with an asterisk require Ganeti to access the |
166 |
file system. Ganeti will refuse to do so unless you whitelist the |
167 |
relevant paths in :pyeval:`pathutils.FILE_STORAGE_PATHS_FILE`. |
168 |
|
169 |
The default paths used by Ganeti are: |
170 |
|
171 |
=============== =================================================== |
172 |
Disk template Default path |
173 |
=============== =================================================== |
174 |
``file`` :pyeval:`pathutils.DEFAULT_FILE_STORAGE_DIR` |
175 |
``sharedfile`` :pyeval:`pathutils.DEFAULT_SHARED_FILE_STORAGE_DIR` |
176 |
``gluster`` :pyeval:`pathutils.DEFAULT_GLUSTER_STORAGE_DIR` |
177 |
=============== =================================================== |
178 |
|
179 |
Those paths can be changed at ``gnt-cluster init`` time. See |
180 |
:manpage:`gnt-cluster(8)` for details. |
181 |
|
182 |
|
183 |
IAllocator |
184 |
~~~~~~~~~~ |
185 |
|
186 |
A framework for using external (user-provided) scripts to compute the |
187 |
placement of instances on the cluster nodes. This eliminates the need to |
188 |
manually specify nodes in instance add, instance moves, node evacuate, |
189 |
etc. |
190 |
|
191 |
In order for Ganeti to be able to use these scripts, they must be place |
192 |
in the iallocator directory (usually ``lib/ganeti/iallocators`` under |
193 |
the installation prefix, e.g. ``/usr/local``). |
194 |
|
195 |
“Primary” and “secondary” concepts |
196 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
197 |
|
198 |
An instance has a primary and depending on the disk configuration, might |
199 |
also have a secondary node. The instance always runs on the primary node |
200 |
and only uses its secondary node for disk replication. |
201 |
|
202 |
Similarly, the term of primary and secondary instances when talking |
203 |
about a node refers to the set of instances having the given node as |
204 |
primary, respectively secondary. |
205 |
|
206 |
Tags |
207 |
~~~~ |
208 |
|
209 |
Tags are short strings that can be attached to either to cluster itself, |
210 |
or to nodes or instances. They are useful as a very simplistic |
211 |
information store for helping with cluster administration, for example |
212 |
by attaching owner information to each instance after it's created:: |
213 |
|
214 |
$ gnt-instance add … %instance1% |
215 |
$ gnt-instance add-tags %instance1% %owner:user2% |
216 |
|
217 |
And then by listing each instance and its tags, this information could |
218 |
be used for contacting the users of each instance. |
219 |
|
220 |
Jobs and OpCodes |
221 |
~~~~~~~~~~~~~~~~ |
222 |
|
223 |
While not directly visible by an end-user, it's useful to know that a |
224 |
basic cluster operation (e.g. starting an instance) is represented |
225 |
internally by Ganeti as an *OpCode* (abbreviation from operation |
226 |
code). These OpCodes are executed as part of a *Job*. The OpCodes in a |
227 |
single Job are processed serially by Ganeti, but different Jobs will be |
228 |
processed (depending on resource availability) in parallel. They will |
229 |
not be executed in the submission order, but depending on resource |
230 |
availability, locks and (starting with Ganeti 2.3) priority. An earlier |
231 |
job may have to wait for a lock while a newer job doesn't need any locks |
232 |
and can be executed right away. Operations requiring a certain order |
233 |
need to be submitted as a single job, or the client must submit one job |
234 |
at a time and wait for it to finish before continuing. |
235 |
|
236 |
For example, shutting down the entire cluster can be done by running the |
237 |
command ``gnt-instance shutdown --all``, which will submit for each |
238 |
instance a separate job containing the “shutdown instance” OpCode. |
239 |
|
240 |
|
241 |
Prerequisites |
242 |
+++++++++++++ |
243 |
|
244 |
You need to have your Ganeti cluster installed and configured before you |
245 |
try any of the commands in this document. Please follow the |
246 |
:doc:`install` for instructions on how to do that. |
247 |
|
248 |
Instance management |
249 |
------------------- |
250 |
|
251 |
Adding an instance |
252 |
++++++++++++++++++ |
253 |
|
254 |
The add operation might seem complex due to the many parameters it |
255 |
accepts, but once you have understood the (few) required parameters and |
256 |
the customisation capabilities you will see it is an easy operation. |
257 |
|
258 |
The add operation requires at minimum five parameters: |
259 |
|
260 |
- the OS for the instance |
261 |
- the disk template |
262 |
- the disk count and size |
263 |
- the node specification or alternatively the iallocator to use |
264 |
- and finally the instance name |
265 |
|
266 |
The OS for the instance must be visible in the output of the command |
267 |
``gnt-os list`` and specifies which guest OS to install on the instance. |
268 |
|
269 |
The disk template specifies what kind of storage to use as backend for |
270 |
the (virtual) disks presented to the instance; note that for instances |
271 |
with multiple virtual disks, they all must be of the same type. |
272 |
|
273 |
The node(s) on which the instance will run can be given either manually, |
274 |
via the ``-n`` option, or computed automatically by Ganeti, if you have |
275 |
installed any iallocator script. |
276 |
|
277 |
With the above parameters in mind, the command is:: |
278 |
|
279 |
$ gnt-instance add \ |
280 |
-n %TARGET_NODE%:%SECONDARY_NODE% \ |
281 |
-o %OS_TYPE% \ |
282 |
-t %DISK_TEMPLATE% -s %DISK_SIZE% \ |
283 |
%INSTANCE_NAME% |
284 |
|
285 |
The instance name must be resolvable (e.g. exist in DNS) and usually |
286 |
points to an address in the same subnet as the cluster itself. |
287 |
|
288 |
The above command has the minimum required options; other options you |
289 |
can give include, among others: |
290 |
|
291 |
- The maximum/minimum memory size (``-B maxmem``, ``-B minmem``) |
292 |
(``-B memory`` can be used to specify only one size) |
293 |
|
294 |
- The number of virtual CPUs (``-B vcpus``) |
295 |
|
296 |
- Arguments for the NICs of the instance; by default, a single-NIC |
297 |
instance is created. The IP and/or bridge of the NIC can be changed |
298 |
via ``--net 0:ip=IP,link=BRIDGE`` |
299 |
|
300 |
See :manpage:`ganeti-instance(8)` for the detailed option list. |
301 |
|
302 |
For example if you want to create an highly available instance, with a |
303 |
single disk of 50GB and the default memory size, having primary node |
304 |
``node1`` and secondary node ``node3``, use the following command:: |
305 |
|
306 |
$ gnt-instance add -n node1:node3 -o debootstrap -t drbd -s 50G \ |
307 |
instance1 |
308 |
|
309 |
There is a also a command for batch instance creation from a |
310 |
specification file, see the ``batch-create`` operation in the |
311 |
gnt-instance manual page. |
312 |
|
313 |
Regular instance operations |
314 |
+++++++++++++++++++++++++++ |
315 |
|
316 |
Removal |
317 |
~~~~~~~ |
318 |
|
319 |
Removing an instance is even easier than creating one. This operation is |
320 |
irreversible and destroys all the contents of your instance. Use with |
321 |
care:: |
322 |
|
323 |
$ gnt-instance remove %INSTANCE_NAME% |
324 |
|
325 |
.. _instance-startup-label: |
326 |
|
327 |
Startup/shutdown |
328 |
~~~~~~~~~~~~~~~~ |
329 |
|
330 |
Instances are automatically started at instance creation time. To |
331 |
manually start one which is currently stopped you can run:: |
332 |
|
333 |
$ gnt-instance startup %INSTANCE_NAME% |
334 |
|
335 |
Ganeti will start an instance with up to its maximum instance memory. If |
336 |
not enough memory is available Ganeti will use all the available memory |
337 |
down to the instance minimum memory. If not even that amount of memory |
338 |
is free Ganeti will refuse to start the instance. |
339 |
|
340 |
Note, that this will not work when an instance is in a permanently |
341 |
stopped state ``offline``. In this case, you will first have to |
342 |
put it back to online mode by running:: |
343 |
|
344 |
$ gnt-instance modify --online %INSTANCE_NAME% |
345 |
|
346 |
The command to stop the running instance is:: |
347 |
|
348 |
$ gnt-instance shutdown %INSTANCE_NAME% |
349 |
|
350 |
If you want to shut the instance down more permanently, so that it |
351 |
does not require dynamically allocated resources (memory and vcpus), |
352 |
after shutting down an instance, execute the following:: |
353 |
|
354 |
$ gnt-instance modify --offline %INSTANCE_NAME% |
355 |
|
356 |
.. warning:: Do not use the Xen or KVM commands directly to stop |
357 |
instances. If you run for example ``xm shutdown`` or ``xm destroy`` |
358 |
on an instance Ganeti will automatically restart it (via |
359 |
the :command:`ganeti-watcher(8)` command which is launched via cron). |
360 |
|
361 |
Querying instances |
362 |
~~~~~~~~~~~~~~~~~~ |
363 |
|
364 |
There are two ways to get information about instances: listing |
365 |
instances, which does a tabular output containing a given set of fields |
366 |
about each instance, and querying detailed information about a set of |
367 |
instances. |
368 |
|
369 |
The command to see all the instances configured and their status is:: |
370 |
|
371 |
$ gnt-instance list |
372 |
|
373 |
The command can return a custom set of information when using the ``-o`` |
374 |
option (as always, check the manpage for a detailed specification). Each |
375 |
instance will be represented on a line, thus making it easy to parse |
376 |
this output via the usual shell utilities (grep, sed, etc.). |
377 |
|
378 |
To get more detailed information about an instance, you can run:: |
379 |
|
380 |
$ gnt-instance info %INSTANCE% |
381 |
|
382 |
which will give a multi-line block of information about the instance, |
383 |
it's hardware resources (especially its disks and their redundancy |
384 |
status), etc. This is harder to parse and is more expensive than the |
385 |
list operation, but returns much more detailed information. |
386 |
|
387 |
Changing an instance's runtime memory |
388 |
+++++++++++++++++++++++++++++++++++++ |
389 |
|
390 |
Ganeti will always make sure an instance has a value between its maximum |
391 |
and its minimum memory available as runtime memory. As of version 2.6 |
392 |
Ganeti will only choose a size different than the maximum size when |
393 |
starting up, failing over, or migrating an instance on a node with less |
394 |
than the maximum memory available. It won't resize other instances in |
395 |
order to free up space for an instance. |
396 |
|
397 |
If you find that you need more memory on a node any instance can be |
398 |
manually resized without downtime, with the command:: |
399 |
|
400 |
$ gnt-instance modify -m %SIZE% %INSTANCE_NAME% |
401 |
|
402 |
The same command can also be used to increase the memory available on an |
403 |
instance, provided that enough free memory is available on its node, and |
404 |
the specified size is not larger than the maximum memory size the |
405 |
instance had when it was first booted (an instance will be unable to see |
406 |
new memory above the maximum that was specified to the hypervisor at its |
407 |
boot time, if it needs to grow further a reboot becomes necessary). |
408 |
|
409 |
Export/Import |
410 |
+++++++++++++ |
411 |
|
412 |
You can create a snapshot of an instance disk and its Ganeti |
413 |
configuration, which then you can backup, or import into another |
414 |
cluster. The way to export an instance is:: |
415 |
|
416 |
$ gnt-backup export -n %TARGET_NODE% %INSTANCE_NAME% |
417 |
|
418 |
|
419 |
The target node can be any node in the cluster with enough space under |
420 |
``/srv/ganeti`` to hold the instance image. Use the ``--noshutdown`` |
421 |
option to snapshot an instance without rebooting it. Note that Ganeti |
422 |
only keeps one snapshot for an instance - any previous snapshot of the |
423 |
same instance existing cluster-wide under ``/srv/ganeti`` will be |
424 |
removed by this operation: if you want to keep them, you need to move |
425 |
them out of the Ganeti exports directory. |
426 |
|
427 |
Importing an instance is similar to creating a new one, but additionally |
428 |
one must specify the location of the snapshot. The command is:: |
429 |
|
430 |
$ gnt-backup import -n %TARGET_NODE% \ |
431 |
--src-node=%NODE% --src-dir=%DIR% %INSTANCE_NAME% |
432 |
|
433 |
By default, parameters will be read from the export information, but you |
434 |
can of course pass them in via the command line - most of the options |
435 |
available for the command :command:`gnt-instance add` are supported here |
436 |
too. |
437 |
|
438 |
Import of foreign instances |
439 |
+++++++++++++++++++++++++++ |
440 |
|
441 |
There is a possibility to import a foreign instance whose disk data is |
442 |
already stored as LVM volumes without going through copying it: the disk |
443 |
adoption mode. |
444 |
|
445 |
For this, ensure that the original, non-managed instance is stopped, |
446 |
then create a Ganeti instance in the usual way, except that instead of |
447 |
passing the disk information you specify the current volumes:: |
448 |
|
449 |
$ gnt-instance add -t plain -n %HOME_NODE% ... \ |
450 |
--disk 0:adopt=%lv_name%[,vg=%vg_name%] %INSTANCE_NAME% |
451 |
|
452 |
This will take over the given logical volumes, rename them to the Ganeti |
453 |
standard (UUID-based), and without installing the OS on them start |
454 |
directly the instance. If you configure the hypervisor similar to the |
455 |
non-managed configuration that the instance had, the transition should |
456 |
be seamless for the instance. For more than one disk, just pass another |
457 |
disk parameter (e.g. ``--disk 1:adopt=...``). |
458 |
|
459 |
Instance kernel selection |
460 |
+++++++++++++++++++++++++ |
461 |
|
462 |
The kernel that instances uses to bootup can come either from the node, |
463 |
or from instances themselves, depending on the setup. |
464 |
|
465 |
Xen-PVM |
466 |
~~~~~~~ |
467 |
|
468 |
With Xen PVM, there are three options. |
469 |
|
470 |
First, you can use a kernel from the node, by setting the hypervisor |
471 |
parameters as such: |
472 |
|
473 |
- ``kernel_path`` to a valid file on the node (and appropriately |
474 |
``initrd_path``) |
475 |
- ``kernel_args`` optionally set to a valid Linux setting (e.g. ``ro``) |
476 |
- ``root_path`` to a valid setting (e.g. ``/dev/xvda1``) |
477 |
- ``bootloader_path`` and ``bootloader_args`` to empty |
478 |
|
479 |
Alternatively, you can delegate the kernel management to instances, and |
480 |
use either ``pvgrub`` or the deprecated ``pygrub``. For this, you must |
481 |
install the kernels and initrds in the instance and create a valid GRUB |
482 |
v1 configuration file. |
483 |
|
484 |
For ``pvgrub`` (new in version 2.4.2), you need to set: |
485 |
|
486 |
- ``kernel_path`` to point to the ``pvgrub`` loader present on the node |
487 |
(e.g. ``/usr/lib/xen/boot/pv-grub-x86_32.gz``) |
488 |
- ``kernel_args`` to the path to the GRUB config file, relative to the |
489 |
instance (e.g. ``(hd0,0)/grub/menu.lst``) |
490 |
- ``root_path`` **must** be empty |
491 |
- ``bootloader_path`` and ``bootloader_args`` to empty |
492 |
|
493 |
While ``pygrub`` is deprecated, here is how you can configure it: |
494 |
|
495 |
- ``bootloader_path`` to the pygrub binary (e.g. ``/usr/bin/pygrub``) |
496 |
- the other settings are not important |
497 |
|
498 |
More information can be found in the Xen wiki pages for `pvgrub |
499 |
<http://wiki.xensource.com/xenwiki/PvGrub>`_ and `pygrub |
500 |
<http://wiki.xensource.com/xenwiki/PyGrub>`_. |
501 |
|
502 |
KVM |
503 |
~~~ |
504 |
|
505 |
For KVM also the kernel can be loaded either way. |
506 |
|
507 |
For loading the kernels from the node, you need to set: |
508 |
|
509 |
- ``kernel_path`` to a valid value |
510 |
- ``initrd_path`` optionally set if you use an initrd |
511 |
- ``kernel_args`` optionally set to a valid value (e.g. ``ro``) |
512 |
|
513 |
If you want instead to have the instance boot from its disk (and execute |
514 |
its bootloader), simply set the ``kernel_path`` parameter to an empty |
515 |
string, and all the others will be ignored. |
516 |
|
517 |
Instance HA features |
518 |
-------------------- |
519 |
|
520 |
.. note:: This section only applies to multi-node clusters |
521 |
|
522 |
.. _instance-change-primary-label: |
523 |
|
524 |
Changing the primary node |
525 |
+++++++++++++++++++++++++ |
526 |
|
527 |
There are three ways to exchange an instance's primary and secondary |
528 |
nodes; the right one to choose depends on how the instance has been |
529 |
created and the status of its current primary node. See |
530 |
:ref:`rest-redundancy-label` for information on changing the secondary |
531 |
node. Note that it's only possible to change the primary node to the |
532 |
secondary and vice-versa; a direct change of the primary node with a |
533 |
third node, while keeping the current secondary is not possible in a |
534 |
single step, only via multiple operations as detailed in |
535 |
:ref:`instance-relocation-label`. |
536 |
|
537 |
Failing over an instance |
538 |
~~~~~~~~~~~~~~~~~~~~~~~~ |
539 |
|
540 |
If an instance is built in highly available mode you can at any time |
541 |
fail it over to its secondary node, even if the primary has somehow |
542 |
failed and it's not up anymore. Doing it is really easy, on the master |
543 |
node you can just run:: |
544 |
|
545 |
$ gnt-instance failover %INSTANCE_NAME% |
546 |
|
547 |
That's it. After the command completes the secondary node is now the |
548 |
primary, and vice-versa. |
549 |
|
550 |
The instance will be started with an amount of memory between its |
551 |
``maxmem`` and its ``minmem`` value, depending on the free memory on its |
552 |
target node, or the operation will fail if that's not possible. See |
553 |
:ref:`instance-startup-label` for details. |
554 |
|
555 |
If the instance's disk template is of type rbd, then you can specify |
556 |
the target node (which can be any node) explicitly, or specify an |
557 |
iallocator plugin. If you omit both, the default iallocator will be |
558 |
used to determine the target node:: |
559 |
|
560 |
$ gnt-instance failover -n %TARGET_NODE% %INSTANCE_NAME% |
561 |
|
562 |
Live migrating an instance |
563 |
~~~~~~~~~~~~~~~~~~~~~~~~~~ |
564 |
|
565 |
If an instance is built in highly available mode, it currently runs and |
566 |
both its nodes are running fine, you can migrate it over to its |
567 |
secondary node, without downtime. On the master node you need to run:: |
568 |
|
569 |
$ gnt-instance migrate %INSTANCE_NAME% |
570 |
|
571 |
The current load on the instance and its memory size will influence how |
572 |
long the migration will take. In any case, for both KVM and Xen |
573 |
hypervisors, the migration will be transparent to the instance. |
574 |
|
575 |
If the destination node has less memory than the instance's current |
576 |
runtime memory, but at least the instance's minimum memory available |
577 |
Ganeti will automatically reduce the instance runtime memory before |
578 |
migrating it, unless the ``--no-runtime-changes`` option is passed, in |
579 |
which case the target node should have at least the instance's current |
580 |
runtime memory free. |
581 |
|
582 |
If the instance's disk template is of type rbd, then you can specify |
583 |
the target node (which can be any node) explicitly, or specify an |
584 |
iallocator plugin. If you omit both, the default iallocator will be |
585 |
used to determine the target node:: |
586 |
|
587 |
$ gnt-instance migrate -n %TARGET_NODE% %INSTANCE_NAME% |
588 |
|
589 |
Moving an instance (offline) |
590 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
591 |
|
592 |
If an instance has not been create as mirrored, then the only way to |
593 |
change its primary node is to execute the move command:: |
594 |
|
595 |
$ gnt-instance move -n %NEW_NODE% %INSTANCE% |
596 |
|
597 |
This has a few prerequisites: |
598 |
|
599 |
- the instance must be stopped |
600 |
- its current primary node must be on-line and healthy |
601 |
- the disks of the instance must not have any errors |
602 |
|
603 |
Since this operation actually copies the data from the old node to the |
604 |
new node, expect it to take proportional to the size of the instance's |
605 |
disks and the speed of both the nodes' I/O system and their networking. |
606 |
|
607 |
Disk operations |
608 |
+++++++++++++++ |
609 |
|
610 |
Disk failures are a common cause of errors in any server |
611 |
deployment. Ganeti offers protection from single-node failure if your |
612 |
instances were created in HA mode, and it also offers ways to restore |
613 |
redundancy after a failure. |
614 |
|
615 |
Preparing for disk operations |
616 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
617 |
|
618 |
It is important to note that for Ganeti to be able to do any disk |
619 |
operation, the Linux machines on top of which Ganeti runs must be |
620 |
consistent; for LVM, this means that the LVM commands must not return |
621 |
failures; it is common that after a complete disk failure, any LVM |
622 |
command aborts with an error similar to:: |
623 |
|
624 |
$ vgs |
625 |
/dev/sdb1: read failed after 0 of 4096 at 0: Input/output error |
626 |
/dev/sdb1: read failed after 0 of 4096 at 750153695232: Input/output error |
627 |
/dev/sdb1: read failed after 0 of 4096 at 0: Input/output error |
628 |
Couldn't find device with uuid 't30jmN-4Rcf-Fr5e-CURS-pawt-z0jU-m1TgeJ'. |
629 |
Couldn't find all physical volumes for volume group xenvg. |
630 |
|
631 |
Before restoring an instance's disks to healthy status, it's needed to |
632 |
fix the volume group used by Ganeti so that we can actually create and |
633 |
manage the logical volumes. This is usually done in a multi-step |
634 |
process: |
635 |
|
636 |
#. first, if the disk is completely gone and LVM commands exit with |
637 |
“Couldn't find device with uuid…” then you need to run the command:: |
638 |
|
639 |
$ vgreduce --removemissing %VOLUME_GROUP% |
640 |
|
641 |
#. after the above command, the LVM commands should be executing |
642 |
normally (warnings are normal, but the commands will not fail |
643 |
completely). |
644 |
|
645 |
#. if the failed disk is still visible in the output of the ``pvs`` |
646 |
command, you need to deactivate it from allocations by running:: |
647 |
|
648 |
$ pvs -x n /dev/%DISK% |
649 |
|
650 |
At this point, the volume group should be consistent and any bad |
651 |
physical volumes should not longer be available for allocation. |
652 |
|
653 |
Note that since version 2.1 Ganeti provides some commands to automate |
654 |
these two operations, see :ref:`storage-units-label`. |
655 |
|
656 |
.. _rest-redundancy-label: |
657 |
|
658 |
Restoring redundancy for DRBD-based instances |
659 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
660 |
|
661 |
A DRBD instance has two nodes, and the storage on one of them has |
662 |
failed. Depending on which node (primary or secondary) has failed, you |
663 |
have three options at hand: |
664 |
|
665 |
- if the storage on the primary node has failed, you need to re-create |
666 |
the disks on it |
667 |
- if the storage on the secondary node has failed, you can either |
668 |
re-create the disks on it or change the secondary and recreate |
669 |
redundancy on the new secondary node |
670 |
|
671 |
Of course, at any point it's possible to force re-creation of disks even |
672 |
though everything is already fine. |
673 |
|
674 |
For all three cases, the ``replace-disks`` operation can be used:: |
675 |
|
676 |
# re-create disks on the primary node |
677 |
$ gnt-instance replace-disks -p %INSTANCE_NAME% |
678 |
# re-create disks on the current secondary |
679 |
$ gnt-instance replace-disks -s %INSTANCE_NAME% |
680 |
# change the secondary node, via manual specification |
681 |
$ gnt-instance replace-disks -n %NODE% %INSTANCE_NAME% |
682 |
# change the secondary node, via an iallocator script |
683 |
$ gnt-instance replace-disks -I %SCRIPT% %INSTANCE_NAME% |
684 |
# since Ganeti 2.1: automatically fix the primary or secondary node |
685 |
$ gnt-instance replace-disks -a %INSTANCE_NAME% |
686 |
|
687 |
Since the process involves copying all data from the working node to the |
688 |
target node, it will take a while, depending on the instance's disk |
689 |
size, node I/O system and network speed. But it is (barring any network |
690 |
interruption) completely transparent for the instance. |
691 |
|
692 |
Re-creating disks for non-redundant instances |
693 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
694 |
|
695 |
.. versionadded:: 2.1 |
696 |
|
697 |
For non-redundant instances, there isn't a copy (except backups) to |
698 |
re-create the disks. But it's possible to at-least re-create empty |
699 |
disks, after which a reinstall can be run, via the ``recreate-disks`` |
700 |
command:: |
701 |
|
702 |
$ gnt-instance recreate-disks %INSTANCE% |
703 |
|
704 |
Note that this will fail if the disks already exists. The instance can |
705 |
be assigned to new nodes automatically by specifying an iallocator |
706 |
through the ``--iallocator`` option. |
707 |
|
708 |
Conversion of an instance's disk type |
709 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
710 |
|
711 |
It is possible to convert between a non-redundant instance of type |
712 |
``plain`` (LVM storage) and redundant ``drbd`` via the ``gnt-instance |
713 |
modify`` command:: |
714 |
|
715 |
# start with a non-redundant instance |
716 |
$ gnt-instance add -t plain ... %INSTANCE% |
717 |
|
718 |
# later convert it to redundant |
719 |
$ gnt-instance stop %INSTANCE% |
720 |
$ gnt-instance modify -t drbd -n %NEW_SECONDARY% %INSTANCE% |
721 |
$ gnt-instance start %INSTANCE% |
722 |
|
723 |
# and convert it back |
724 |
$ gnt-instance stop %INSTANCE% |
725 |
$ gnt-instance modify -t plain %INSTANCE% |
726 |
$ gnt-instance start %INSTANCE% |
727 |
|
728 |
The conversion must be done while the instance is stopped, and |
729 |
converting from plain to drbd template presents a small risk, especially |
730 |
if the instance has multiple disks and/or if one node fails during the |
731 |
conversion procedure). As such, it's recommended (as always) to make |
732 |
sure that downtime for manual recovery is acceptable and that the |
733 |
instance has up-to-date backups. |
734 |
|
735 |
Debugging instances |
736 |
+++++++++++++++++++ |
737 |
|
738 |
Accessing an instance's disks |
739 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
740 |
|
741 |
From an instance's primary node you can have access to its disks. Never |
742 |
ever mount the underlying logical volume manually on a fault tolerant |
743 |
instance, or will break replication and your data will be |
744 |
inconsistent. The correct way to access an instance's disks is to run |
745 |
(on the master node, as usual) the command:: |
746 |
|
747 |
$ gnt-instance activate-disks %INSTANCE% |
748 |
|
749 |
And then, *on the primary node of the instance*, access the device that |
750 |
gets created. For example, you could mount the given disks, then edit |
751 |
files on the filesystem, etc. |
752 |
|
753 |
Note that with partitioned disks (as opposed to whole-disk filesystems), |
754 |
you will need to use a tool like :manpage:`kpartx(8)`:: |
755 |
|
756 |
# on node1 |
757 |
$ gnt-instance activate-disks %instance1% |
758 |
node3:disk/0:… |
759 |
$ ssh node3 |
760 |
# on node 3 |
761 |
$ kpartx -l /dev/… |
762 |
$ kpartx -a /dev/… |
763 |
$ mount /dev/mapper/… /mnt/ |
764 |
# edit files under mnt as desired |
765 |
$ umount /mnt/ |
766 |
$ kpartx -d /dev/… |
767 |
$ exit |
768 |
# back to node 1 |
769 |
|
770 |
After you've finished you can deactivate them with the deactivate-disks |
771 |
command, which works in the same way:: |
772 |
|
773 |
$ gnt-instance deactivate-disks %INSTANCE% |
774 |
|
775 |
Note that if any process started by you is still using the disks, the |
776 |
above command will error out, and you **must** cleanup and ensure that |
777 |
the above command runs successfully before you start the instance, |
778 |
otherwise the instance will suffer corruption. |
779 |
|
780 |
Accessing an instance's console |
781 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
782 |
|
783 |
The command to access a running instance's console is:: |
784 |
|
785 |
$ gnt-instance console %INSTANCE_NAME% |
786 |
|
787 |
Use the console normally and then type ``^]`` when done, to exit. |
788 |
|
789 |
Other instance operations |
790 |
+++++++++++++++++++++++++ |
791 |
|
792 |
Reboot |
793 |
~~~~~~ |
794 |
|
795 |
There is a wrapper command for rebooting instances:: |
796 |
|
797 |
$ gnt-instance reboot %instance2% |
798 |
|
799 |
By default, this does the equivalent of shutting down and then starting |
800 |
the instance, but it accepts parameters to perform a soft-reboot (via |
801 |
the hypervisor), a hard reboot (hypervisor shutdown and then startup) or |
802 |
a full one (the default, which also de-configures and then configures |
803 |
again the disks of the instance). |
804 |
|
805 |
Instance OS definitions debugging |
806 |
+++++++++++++++++++++++++++++++++ |
807 |
|
808 |
Should you have any problems with instance operating systems the command |
809 |
to see a complete status for all your nodes is:: |
810 |
|
811 |
$ gnt-os diagnose |
812 |
|
813 |
.. _instance-relocation-label: |
814 |
|
815 |
Instance relocation |
816 |
~~~~~~~~~~~~~~~~~~~ |
817 |
|
818 |
While it is not possible to move an instance from nodes ``(A, B)`` to |
819 |
nodes ``(C, D)`` in a single move, it is possible to do so in a few |
820 |
steps:: |
821 |
|
822 |
# instance is located on A, B |
823 |
$ gnt-instance replace-disks -n %nodeC% %instance1% |
824 |
# instance has moved from (A, B) to (A, C) |
825 |
# we now flip the primary/secondary nodes |
826 |
$ gnt-instance migrate %instance1% |
827 |
# instance lives on (C, A) |
828 |
# we can then change A to D via: |
829 |
$ gnt-instance replace-disks -n %nodeD% %instance1% |
830 |
|
831 |
Which brings it into the final configuration of ``(C, D)``. Note that we |
832 |
needed to do two replace-disks operation (two copies of the instance |
833 |
disks), because we needed to get rid of both the original nodes (A and |
834 |
B). |
835 |
|
836 |
Network Management |
837 |
------------------ |
838 |
|
839 |
Ganeti used to describe NICs of an Instance with an IP, a MAC, a connectivity |
840 |
link and mode. This had three major shortcomings: |
841 |
|
842 |
* there was no easy way to assign a unique IP to an instance |
843 |
* network info (subnet, gateway, domain, etc.) was not available on target |
844 |
node (kvm-ifup, hooks, etc) |
845 |
* one should explicitly pass L2 info (mode, and link) to every NIC |
846 |
|
847 |
Plus there was no easy way to get the current networking overview (which |
848 |
instances are on the same L2 or L3 network, which IPs are reserved, etc). |
849 |
|
850 |
All the above required an external management tool that has an overall view |
851 |
and provides the corresponding info to Ganeti. |
852 |
|
853 |
gnt-network aims to support a big part of this functionality inside Ganeti and |
854 |
abstract the network as a separate entity. Currently, a Ganeti network |
855 |
provides the following: |
856 |
|
857 |
* A single IPv4 pool, subnet and gateway |
858 |
* Connectivity info per nodegroup (mode, link) |
859 |
* MAC prefix for each NIC inside the network |
860 |
* IPv6 prefix/Gateway related to this network |
861 |
* Tags |
862 |
|
863 |
IP pool management ensures IP uniqueness inside this network. The user can |
864 |
pass `ip=pool,network=test` and will: |
865 |
|
866 |
1. Get the first available IP in the pool |
867 |
2. Inherit the connectivity mode and link of the network's netparams |
868 |
3. NIC will obtain the MAC prefix of the network |
869 |
4. All network related info will be available as environment variables in |
870 |
kvm-ifup scripts and hooks, so that they can dynamically manage all |
871 |
networking-related setup on the host. |
872 |
|
873 |
Hands on with gnt-network |
874 |
+++++++++++++++++++++++++ |
875 |
|
876 |
To create a network do:: |
877 |
|
878 |
# gnt-network add --network=192.0.2.0/24 --gateway=192.0.2.1 test |
879 |
|
880 |
Please see all other available options (--add-reserved-ips, --mac-prefix, |
881 |
--network6, --gateway6, --tags). |
882 |
|
883 |
Currently, IPv6 info is not used by Ganeti itself. It only gets exported |
884 |
to NIC configuration scripts and hooks via environment variables. |
885 |
|
886 |
To make this network available on a nodegroup you should specify the |
887 |
connectivity mode and link during connection:: |
888 |
|
889 |
# gnt-network connect test bridged br100 default nodegroup1 |
890 |
|
891 |
To add a NIC inside this network:: |
892 |
|
893 |
# gnt-instance modify --net -1:add,ip=pool,network=test inst1 |
894 |
|
895 |
This will let a NIC obtain a unique IP inside this network, and inherit the |
896 |
nodegroup's netparams (bridged, br100). IP here is optional. If missing the |
897 |
NIC will just get the L2 info. |
898 |
|
899 |
To move an existing NIC from a network to another and remove its IP:: |
900 |
|
901 |
# gnt-instance modify --net -1:ip=none,network=test1 inst1 |
902 |
|
903 |
This will release the old IP from the old IP pool and the NIC will inherit the |
904 |
new nicparams. |
905 |
|
906 |
On the above actions there is a extra option `--no-conflicts-ckeck`. This |
907 |
does not check for conflicting setups. Specifically: |
908 |
|
909 |
1. When a network is added, IPs of nodes and master are not being checked. |
910 |
2. When connecting a network on a nodegroup, IPs of instances inside this |
911 |
nodegroup are not checked whether they reside inside the subnet or not. |
912 |
3. When specifying explicitly a IP without passing a network, Ganeti will not |
913 |
check if this IP is included inside any available network on the nodegroup. |
914 |
|
915 |
External components |
916 |
+++++++++++++++++++ |
917 |
|
918 |
All the aforementioned steps assure NIC configuration from the Ganeti |
919 |
perspective. Of course this has nothing to do, how the instance eventually will |
920 |
get the desired connectivity (IPv4, IPv6, default routes, DNS info, etc) and |
921 |
where will the IP resolve. This functionality is managed by the external |
922 |
components. |
923 |
|
924 |
Let's assume that the VM will need to obtain a dynamic IP via DHCP, get a SLAAC |
925 |
address, and use DHCPv6 for other configuration information (in case RFC-6106 |
926 |
is not supported by the client, e.g. Windows). This means that the following |
927 |
external services are needed: |
928 |
|
929 |
1. A DHCP server |
930 |
2. An IPv6 router sending Router Advertisements |
931 |
3. A DHCPv6 server exporting DNS info |
932 |
4. A dynamic DNS server |
933 |
|
934 |
These components must be configured dynamically and on a per NIC basis. |
935 |
The way to do this is by using custom kvm-ifup scripts and hooks. |
936 |
|
937 |
snf-network |
938 |
~~~~~~~~~~~ |
939 |
|
940 |
The snf-network package [1,3] includes custom scripts that will provide the |
941 |
aforementioned functionality. `kvm-vif-bridge` and `vif-custom` is an |
942 |
alternative to `kvm-ifup` and `vif-ganeti` that take into account all network |
943 |
info being exported. Their actions depend on network tags. Specifically: |
944 |
|
945 |
`dns`: will update an external DDNS server (nsupdate on a bind server) |
946 |
|
947 |
`ip-less-routed`: will setup routes, rules and proxy ARP |
948 |
This setup assumes a pre-existing routing table along with some local |
949 |
configuration and provides connectivity to instances via an external |
950 |
gateway/router without requiring nodes to have an IP inside this network. |
951 |
|
952 |
`private-filtered`: will setup ebtables rules to ensure L2 isolation on a |
953 |
common bridge. Only packets with the same MAC prefix will be forwarded to the |
954 |
corresponding virtual interface. |
955 |
|
956 |
`nfdhcpd`: will update an external DHCP server |
957 |
|
958 |
nfdhcpd |
959 |
~~~~~~~ |
960 |
|
961 |
snf-network works with nfdhcpd [2,3]: a custom user space DHCP |
962 |
server based on NFQUEUE. Currently, nfdhcpd replies on BOOTP/DHCP requests |
963 |
originating from a tap or a bridge. Additionally in case of a routed setup it |
964 |
provides a ra-stateless configuration by responding to router and neighbour |
965 |
solicitations along with DHCPv6 requests for DNS options. Its db is |
966 |
dynamically updated using text files inside a local dir with inotify |
967 |
(snf-network just adds a per NIC binding file with all relevant info if the |
968 |
corresponding network tag is found). Still we need to mangle all these |
969 |
packets and send them to the corresponding NFQUEUE. |
970 |
|
971 |
Known shortcomings |
972 |
++++++++++++++++++ |
973 |
|
974 |
Currently the following things are some know weak points of the gnt-network |
975 |
design and implementation: |
976 |
|
977 |
* Cannot define a network without an IP pool |
978 |
* The pool defines the size of the network |
979 |
* Reserved IPs must be defined explicitly (inconvenient for a big range) |
980 |
* Cannot define an IPv6 only network |
981 |
|
982 |
Future work |
983 |
+++++++++++ |
984 |
|
985 |
Any upcoming patches should target: |
986 |
|
987 |
* Separate L2, L3, IPv6, IP pool info |
988 |
* Support a set of IP pools per network |
989 |
* Make IP/network in NIC object take a list of entries |
990 |
* Introduce external scripts for node configuration |
991 |
(dynamically create/destroy bridges/routes upon network connect/disconnect) |
992 |
|
993 |
[1] https://code.grnet.gr/git/snf-network |
994 |
[2] https://code.grnet.gr/git/snf-nfdhcpd |
995 |
[3] deb http:/apt.dev.grnet.gr/ wheezy/ |
996 |
|
997 |
Node operations |
998 |
--------------- |
999 |
|
1000 |
There are much fewer node operations available than for instances, but |
1001 |
they are equivalently important for maintaining a healthy cluster. |
1002 |
|
1003 |
Add/readd |
1004 |
+++++++++ |
1005 |
|
1006 |
It is at any time possible to extend the cluster with one more node, by |
1007 |
using the node add operation:: |
1008 |
|
1009 |
$ gnt-node add %NEW_NODE% |
1010 |
|
1011 |
If the cluster has a replication network defined, then you need to pass |
1012 |
the ``-s REPLICATION_IP`` parameter to this option. |
1013 |
|
1014 |
A variation of this command can be used to re-configure a node if its |
1015 |
Ganeti configuration is broken, for example if it has been reinstalled |
1016 |
by mistake:: |
1017 |
|
1018 |
$ gnt-node add --readd %EXISTING_NODE% |
1019 |
|
1020 |
This will reinitialise the node as if it's been newly added, but while |
1021 |
keeping its existing configuration in the cluster (primary/secondary IP, |
1022 |
etc.), in other words you won't need to use ``-s`` here. |
1023 |
|
1024 |
Changing the node role |
1025 |
++++++++++++++++++++++ |
1026 |
|
1027 |
A node can be in different roles, as explained in the |
1028 |
:ref:`terminology-label` section. Promoting a node to the master role is |
1029 |
special, while the other roles are handled all via a single command. |
1030 |
|
1031 |
Failing over the master node |
1032 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
1033 |
|
1034 |
If you want to promote a different node to the master role (for whatever |
1035 |
reason), run on any other master-candidate node the command:: |
1036 |
|
1037 |
$ gnt-cluster master-failover |
1038 |
|
1039 |
and the node you ran it on is now the new master. In case you try to run |
1040 |
this on a non master-candidate node, you will get an error telling you |
1041 |
which nodes are valid. |
1042 |
|
1043 |
Changing between the other roles |
1044 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
1045 |
|
1046 |
The ``gnt-node modify`` command can be used to select a new role:: |
1047 |
|
1048 |
# change to master candidate |
1049 |
$ gnt-node modify -C yes %NODE% |
1050 |
# change to drained status |
1051 |
$ gnt-node modify -D yes %NODE% |
1052 |
# change to offline status |
1053 |
$ gnt-node modify -O yes %NODE% |
1054 |
# change to regular mode (reset all flags) |
1055 |
$ gnt-node modify -O no -D no -C no %NODE% |
1056 |
|
1057 |
Note that the cluster requires that at any point in time, a certain |
1058 |
number of nodes are master candidates, so changing from master candidate |
1059 |
to other roles might fail. It is recommended to either force the |
1060 |
operation (via the ``--force`` option) or first change the number of |
1061 |
master candidates in the cluster - see :ref:`cluster-config-label`. |
1062 |
|
1063 |
Evacuating nodes |
1064 |
++++++++++++++++ |
1065 |
|
1066 |
There are two steps of moving instances off a node: |
1067 |
|
1068 |
- moving the primary instances (actually converting them into secondary |
1069 |
instances) |
1070 |
- moving the secondary instances (including any instances converted in |
1071 |
the step above) |
1072 |
|
1073 |
Primary instance conversion |
1074 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
1075 |
|
1076 |
For this step, you can use either individual instance move |
1077 |
commands (as seen in :ref:`instance-change-primary-label`) or the bulk |
1078 |
per-node versions; these are:: |
1079 |
|
1080 |
$ gnt-node migrate %NODE% |
1081 |
$ gnt-node evacuate -s %NODE% |
1082 |
|
1083 |
Note that the instance “move” command doesn't currently have a node |
1084 |
equivalent. |
1085 |
|
1086 |
Both these commands, or the equivalent per-instance command, will make |
1087 |
this node the secondary node for the respective instances, whereas their |
1088 |
current secondary node will become primary. Note that it is not possible |
1089 |
to change in one step the primary node to another node as primary, while |
1090 |
keeping the same secondary node. |
1091 |
|
1092 |
Secondary instance evacuation |
1093 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
1094 |
|
1095 |
For the evacuation of secondary instances, a command called |
1096 |
:command:`gnt-node evacuate` is provided and its syntax is:: |
1097 |
|
1098 |
$ gnt-node evacuate -I %IALLOCATOR_SCRIPT% %NODE% |
1099 |
$ gnt-node evacuate -n %DESTINATION_NODE% %NODE% |
1100 |
|
1101 |
The first version will compute the new secondary for each instance in |
1102 |
turn using the given iallocator script, whereas the second one will |
1103 |
simply move all instances to DESTINATION_NODE. |
1104 |
|
1105 |
Removal |
1106 |
+++++++ |
1107 |
|
1108 |
Once a node no longer has any instances (neither primary nor secondary), |
1109 |
it's easy to remove it from the cluster:: |
1110 |
|
1111 |
$ gnt-node remove %NODE_NAME% |
1112 |
|
1113 |
This will deconfigure the node, stop the ganeti daemons on it and leave |
1114 |
it hopefully like before it joined to the cluster. |
1115 |
|
1116 |
Replication network changes |
1117 |
+++++++++++++++++++++++++++ |
1118 |
|
1119 |
The :command:`gnt-node modify -s` command can be used to change the |
1120 |
secondary IP of a node. This operation can only be performed if: |
1121 |
|
1122 |
- No instance is active on the target node |
1123 |
- The new target IP is reachable from the master's secondary IP |
1124 |
|
1125 |
Also this operation will not allow to change a node from single-homed |
1126 |
(same primary and secondary ip) to multi-homed (separate replication |
1127 |
network) or vice versa, unless: |
1128 |
|
1129 |
- The target node is the master node and `--force` is passed. |
1130 |
- The target cluster is single-homed and the new primary ip is a change |
1131 |
to single homed for a particular node. |
1132 |
- The target cluster is multi-homed and the new primary ip is a change |
1133 |
to multi homed for a particular node. |
1134 |
|
1135 |
For example to do a single-homed to multi-homed conversion:: |
1136 |
|
1137 |
$ gnt-node modify --force -s %SECONDARY_IP% %MASTER_NAME% |
1138 |
$ gnt-node modify -s %SECONDARY_IP% %NODE1_NAME% |
1139 |
$ gnt-node modify -s %SECONDARY_IP% %NODE2_NAME% |
1140 |
$ gnt-node modify -s %SECONDARY_IP% %NODE3_NAME% |
1141 |
... |
1142 |
|
1143 |
The same commands can be used for multi-homed to single-homed except the |
1144 |
secondary IPs should be the same as the primaries for each node, for |
1145 |
that case. |
1146 |
|
1147 |
Storage handling |
1148 |
++++++++++++++++ |
1149 |
|
1150 |
When using LVM (either standalone or with DRBD), it can become tedious |
1151 |
to debug and fix it in case of errors. Furthermore, even file-based |
1152 |
storage can become complicated to handle manually on many hosts. Ganeti |
1153 |
provides a couple of commands to help with automation. |
1154 |
|
1155 |
Logical volumes |
1156 |
~~~~~~~~~~~~~~~ |
1157 |
|
1158 |
This is a command specific to LVM handling. It allows listing the |
1159 |
logical volumes on a given node or on all nodes and their association to |
1160 |
instances via the ``volumes`` command:: |
1161 |
|
1162 |
$ gnt-node volumes |
1163 |
Node PhysDev VG Name Size Instance |
1164 |
node1 /dev/sdb1 xenvg e61fbc97-….disk0 512M instance17 |
1165 |
node1 /dev/sdb1 xenvg ebd1a7d1-….disk0 512M instance19 |
1166 |
node2 /dev/sdb1 xenvg 0af08a3d-….disk0 512M instance20 |
1167 |
node2 /dev/sdb1 xenvg cc012285-….disk0 512M instance16 |
1168 |
node2 /dev/sdb1 xenvg f0fac192-….disk0 512M instance18 |
1169 |
|
1170 |
The above command maps each logical volume to a volume group and |
1171 |
underlying physical volume and (possibly) to an instance. |
1172 |
|
1173 |
.. _storage-units-label: |
1174 |
|
1175 |
Generalized storage handling |
1176 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
1177 |
|
1178 |
.. versionadded:: 2.1 |
1179 |
|
1180 |
Starting with Ganeti 2.1, a new storage framework has been implemented |
1181 |
that tries to abstract the handling of the storage type the cluster |
1182 |
uses. |
1183 |
|
1184 |
First is listing the backend storage and their space situation:: |
1185 |
|
1186 |
$ gnt-node list-storage |
1187 |
Node Name Size Used Free |
1188 |
node1 /dev/sda7 673.8G 0M 673.8G |
1189 |
node1 /dev/sdb1 698.6G 1.5G 697.1G |
1190 |
node2 /dev/sda7 673.8G 0M 673.8G |
1191 |
node2 /dev/sdb1 698.6G 1.0G 697.6G |
1192 |
|
1193 |
The default is to list LVM physical volumes. It's also possible to list |
1194 |
the LVM volume groups:: |
1195 |
|
1196 |
$ gnt-node list-storage -t lvm-vg |
1197 |
Node Name Size |
1198 |
node1 xenvg 1.3T |
1199 |
node2 xenvg 1.3T |
1200 |
|
1201 |
Next is repairing storage units, which is currently only implemented for |
1202 |
volume groups and does the equivalent of ``vgreduce --removemissing``:: |
1203 |
|
1204 |
$ gnt-node repair-storage %node2% lvm-vg xenvg |
1205 |
Sun Oct 25 22:21:45 2009 Repairing storage unit 'xenvg' on node2 ... |
1206 |
|
1207 |
Last is the modification of volume properties, which is (again) only |
1208 |
implemented for LVM physical volumes and allows toggling the |
1209 |
``allocatable`` value:: |
1210 |
|
1211 |
$ gnt-node modify-storage --allocatable=no %node2% lvm-pv /dev/%sdb1% |
1212 |
|
1213 |
Use of the storage commands |
1214 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
1215 |
|
1216 |
All these commands are needed when recovering a node from a disk |
1217 |
failure: |
1218 |
|
1219 |
- first, we need to recover from complete LVM failure (due to missing |
1220 |
disk), by running the ``repair-storage`` command |
1221 |
- second, we need to change allocation on any partially-broken disk |
1222 |
(i.e. LVM still sees it, but it has bad blocks) by running |
1223 |
``modify-storage`` |
1224 |
- then we can evacuate the instances as needed |
1225 |
|
1226 |
|
1227 |
Cluster operations |
1228 |
------------------ |
1229 |
|
1230 |
Beside the cluster initialisation command (which is detailed in the |
1231 |
:doc:`install` document) and the master failover command which is |
1232 |
explained under node handling, there are a couple of other cluster |
1233 |
operations available. |
1234 |
|
1235 |
.. _cluster-config-label: |
1236 |
|
1237 |
Standard operations |
1238 |
+++++++++++++++++++ |
1239 |
|
1240 |
One of the few commands that can be run on any node (not only the |
1241 |
master) is the ``getmaster`` command:: |
1242 |
|
1243 |
# on node2 |
1244 |
$ gnt-cluster getmaster |
1245 |
node1.example.com |
1246 |
|
1247 |
It is possible to query and change global cluster parameters via the |
1248 |
``info`` and ``modify`` commands:: |
1249 |
|
1250 |
$ gnt-cluster info |
1251 |
Cluster name: cluster.example.com |
1252 |
Cluster UUID: 07805e6f-f0af-4310-95f1-572862ee939c |
1253 |
Creation time: 2009-09-25 05:04:15 |
1254 |
Modification time: 2009-10-18 22:11:47 |
1255 |
Master node: node1.example.com |
1256 |
Architecture (this node): 64bit (x86_64) |
1257 |
… |
1258 |
Tags: foo |
1259 |
Default hypervisor: xen-pvm |
1260 |
Enabled hypervisors: xen-pvm |
1261 |
Hypervisor parameters: |
1262 |
- xen-pvm: |
1263 |
root_path: /dev/sda1 |
1264 |
… |
1265 |
Cluster parameters: |
1266 |
- candidate pool size: 10 |
1267 |
… |
1268 |
Default instance parameters: |
1269 |
- default: |
1270 |
memory: 128 |
1271 |
… |
1272 |
Default nic parameters: |
1273 |
- default: |
1274 |
link: xen-br0 |
1275 |
… |
1276 |
|
1277 |
There various parameters above can be changed via the ``modify`` |
1278 |
commands as follows: |
1279 |
|
1280 |
- the hypervisor parameters can be changed via ``modify -H |
1281 |
xen-pvm:root_path=…``, and so on for other hypervisors/key/values |
1282 |
- the "default instance parameters" are changeable via ``modify -B |
1283 |
parameter=value…`` syntax |
1284 |
- the cluster parameters are changeable via separate options to the |
1285 |
modify command (e.g. ``--candidate-pool-size``, etc.) |
1286 |
|
1287 |
For detailed option list see the :manpage:`gnt-cluster(8)` man page. |
1288 |
|
1289 |
The cluster version can be obtained via the ``version`` command:: |
1290 |
$ gnt-cluster version |
1291 |
Software version: 2.1.0 |
1292 |
Internode protocol: 20 |
1293 |
Configuration format: 2010000 |
1294 |
OS api version: 15 |
1295 |
Export interface: 0 |
1296 |
|
1297 |
This is not very useful except when debugging Ganeti. |
1298 |
|
1299 |
Global node commands |
1300 |
++++++++++++++++++++ |
1301 |
|
1302 |
There are two commands provided for replicating files to all nodes of a |
1303 |
cluster and for running commands on all the nodes:: |
1304 |
|
1305 |
$ gnt-cluster copyfile %/path/to/file% |
1306 |
$ gnt-cluster command %ls -l /path/to/file% |
1307 |
|
1308 |
These are simple wrappers over scp/ssh and more advanced usage can be |
1309 |
obtained using :manpage:`dsh(1)` and similar commands. But they are |
1310 |
useful to update an OS script from the master node, for example. |
1311 |
|
1312 |
Cluster verification |
1313 |
++++++++++++++++++++ |
1314 |
|
1315 |
There are three commands that relate to global cluster checks. The first |
1316 |
one is ``verify`` which gives an overview on the cluster state, |
1317 |
highlighting any issues. In normal operation, this command should return |
1318 |
no ``ERROR`` messages:: |
1319 |
|
1320 |
$ gnt-cluster verify |
1321 |
Sun Oct 25 23:08:58 2009 * Verifying global settings |
1322 |
Sun Oct 25 23:08:58 2009 * Gathering data (2 nodes) |
1323 |
Sun Oct 25 23:09:00 2009 * Verifying node status |
1324 |
Sun Oct 25 23:09:00 2009 * Verifying instance status |
1325 |
Sun Oct 25 23:09:00 2009 * Verifying orphan volumes |
1326 |
Sun Oct 25 23:09:00 2009 * Verifying remaining instances |
1327 |
Sun Oct 25 23:09:00 2009 * Verifying N+1 Memory redundancy |
1328 |
Sun Oct 25 23:09:00 2009 * Other Notes |
1329 |
Sun Oct 25 23:09:00 2009 - NOTICE: 5 non-redundant instance(s) found. |
1330 |
Sun Oct 25 23:09:00 2009 * Hooks Results |
1331 |
|
1332 |
The second command is ``verify-disks``, which checks that the instance's |
1333 |
disks have the correct status based on the desired instance state |
1334 |
(up/down):: |
1335 |
|
1336 |
$ gnt-cluster verify-disks |
1337 |
|
1338 |
Note that this command will show no output when disks are healthy. |
1339 |
|
1340 |
The last command is used to repair any discrepancies in Ganeti's |
1341 |
recorded disk size and the actual disk size (disk size information is |
1342 |
needed for proper activation and growth of DRBD-based disks):: |
1343 |
|
1344 |
$ gnt-cluster repair-disk-sizes |
1345 |
Sun Oct 25 23:13:16 2009 - INFO: Disk 0 of instance instance1 has mismatched size, correcting: recorded 512, actual 2048 |
1346 |
Sun Oct 25 23:13:17 2009 - WARNING: Invalid result from node node4, ignoring node results |
1347 |
|
1348 |
The above shows one instance having wrong disk size, and a node which |
1349 |
returned invalid data, and thus we ignored all primary instances of that |
1350 |
node. |
1351 |
|
1352 |
Configuration redistribution |
1353 |
++++++++++++++++++++++++++++ |
1354 |
|
1355 |
If the verify command complains about file mismatches between the master |
1356 |
and other nodes, due to some node problems or if you manually modified |
1357 |
configuration files, you can force an push of the master configuration |
1358 |
to all other nodes via the ``redist-conf`` command:: |
1359 |
|
1360 |
$ gnt-cluster redist-conf |
1361 |
|
1362 |
This command will be silent unless there are problems sending updates to |
1363 |
the other nodes. |
1364 |
|
1365 |
|
1366 |
Cluster renaming |
1367 |
++++++++++++++++ |
1368 |
|
1369 |
It is possible to rename a cluster, or to change its IP address, via the |
1370 |
``rename`` command. If only the IP has changed, you need to pass the |
1371 |
current name and Ganeti will realise its IP has changed:: |
1372 |
|
1373 |
$ gnt-cluster rename %cluster.example.com% |
1374 |
This will rename the cluster to 'cluster.example.com'. If |
1375 |
you are connected over the network to the cluster name, the operation |
1376 |
is very dangerous as the IP address will be removed from the node and |
1377 |
the change may not go through. Continue? |
1378 |
y/[n]/?: %y% |
1379 |
Failure: prerequisites not met for this operation: |
1380 |
Neither the name nor the IP address of the cluster has changed |
1381 |
|
1382 |
In the above output, neither value has changed since the cluster |
1383 |
initialisation so the operation is not completed. |
1384 |
|
1385 |
Queue operations |
1386 |
++++++++++++++++ |
1387 |
|
1388 |
The job queue execution in Ganeti 2.0 and higher can be inspected, |
1389 |
suspended and resumed via the ``queue`` command:: |
1390 |
|
1391 |
$ gnt-cluster queue info |
1392 |
The drain flag is unset |
1393 |
$ gnt-cluster queue drain |
1394 |
$ gnt-instance stop %instance1% |
1395 |
Failed to submit job for instance1: Job queue is drained, refusing job |
1396 |
$ gnt-cluster queue info |
1397 |
The drain flag is set |
1398 |
$ gnt-cluster queue undrain |
1399 |
|
1400 |
This is most useful if you have an active cluster and you need to |
1401 |
upgrade the Ganeti software, or simply restart the software on any node: |
1402 |
|
1403 |
#. suspend the queue via ``queue drain`` |
1404 |
#. wait until there are no more running jobs via ``gnt-job list`` |
1405 |
#. restart the master or another node, or upgrade the software |
1406 |
#. resume the queue via ``queue undrain`` |
1407 |
|
1408 |
.. note:: this command only stores a local flag file, and if you |
1409 |
failover the master, it will not have effect on the new master. |
1410 |
|
1411 |
|
1412 |
Watcher control |
1413 |
+++++++++++++++ |
1414 |
|
1415 |
The :manpage:`ganeti-watcher(8)` is a program, usually scheduled via |
1416 |
``cron``, that takes care of cluster maintenance operations (restarting |
1417 |
downed instances, activating down DRBD disks, etc.). However, during |
1418 |
maintenance and troubleshooting, this can get in your way; disabling it |
1419 |
via commenting out the cron job is not so good as this can be |
1420 |
forgotten. Thus there are some commands for automated control of the |
1421 |
watcher: ``pause``, ``info`` and ``continue``:: |
1422 |
|
1423 |
$ gnt-cluster watcher info |
1424 |
The watcher is not paused. |
1425 |
$ gnt-cluster watcher pause %1h% |
1426 |
The watcher is paused until Mon Oct 26 00:30:37 2009. |
1427 |
$ gnt-cluster watcher info |
1428 |
The watcher is paused until Mon Oct 26 00:30:37 2009. |
1429 |
$ ganeti-watcher -d |
1430 |
2009-10-25 23:30:47,984: pid=28867 ganeti-watcher:486 DEBUG Pause has been set, exiting |
1431 |
$ gnt-cluster watcher continue |
1432 |
The watcher is no longer paused. |
1433 |
$ ganeti-watcher -d |
1434 |
2009-10-25 23:31:04,789: pid=28976 ganeti-watcher:345 DEBUG Archived 0 jobs, left 0 |
1435 |
2009-10-25 23:31:05,884: pid=28976 ganeti-watcher:280 DEBUG Got data from cluster, writing instance status file |
1436 |
2009-10-25 23:31:06,061: pid=28976 ganeti-watcher:150 DEBUG Data didn't change, just touching status file |
1437 |
$ gnt-cluster watcher info |
1438 |
The watcher is not paused. |
1439 |
|
1440 |
The exact details of the argument to the ``pause`` command are available |
1441 |
in the manpage. |
1442 |
|
1443 |
.. note:: this command only stores a local flag file, and if you |
1444 |
failover the master, it will not have effect on the new master. |
1445 |
|
1446 |
Node auto-maintenance |
1447 |
+++++++++++++++++++++ |
1448 |
|
1449 |
If the cluster parameter ``maintain_node_health`` is enabled (see the |
1450 |
manpage for :command:`gnt-cluster`, the init and modify subcommands), |
1451 |
then the following will happen automatically: |
1452 |
|
1453 |
- the watcher will shutdown any instances running on offline nodes |
1454 |
- the watcher will deactivate any DRBD devices on offline nodes |
1455 |
|
1456 |
In the future, more actions are planned, so only enable this parameter |
1457 |
if the nodes are completely dedicated to Ganeti; otherwise it might be |
1458 |
possible to lose data due to auto-maintenance actions. |
1459 |
|
1460 |
Removing a cluster entirely |
1461 |
+++++++++++++++++++++++++++ |
1462 |
|
1463 |
The usual method to cleanup a cluster is to run ``gnt-cluster destroy`` |
1464 |
however if the Ganeti installation is broken in any way then this will |
1465 |
not run. |
1466 |
|
1467 |
It is possible in such a case to cleanup manually most if not all traces |
1468 |
of a cluster installation by following these steps on all of the nodes: |
1469 |
|
1470 |
1. Shutdown all instances. This depends on the virtualisation method |
1471 |
used (Xen, KVM, etc.): |
1472 |
|
1473 |
- Xen: run ``xm list`` and ``xm destroy`` on all the non-Domain-0 |
1474 |
instances |
1475 |
- KVM: kill all the KVM processes |
1476 |
- chroot: kill all processes under the chroot mountpoints |
1477 |
|
1478 |
2. If using DRBD, shutdown all DRBD minors (which should by at this time |
1479 |
no-longer in use by instances); on each node, run ``drbdsetup |
1480 |
/dev/drbdN down`` for each active DRBD minor. |
1481 |
|
1482 |
3. If using LVM, cleanup the Ganeti volume group; if only Ganeti created |
1483 |
logical volumes (and you are not sharing the volume group with the |
1484 |
OS, for example), then simply running ``lvremove -f xenvg`` (replace |
1485 |
'xenvg' with your volume group name) should do the required cleanup. |
1486 |
|
1487 |
4. If using file-based storage, remove recursively all files and |
1488 |
directories under your file-storage directory: ``rm -rf |
1489 |
/srv/ganeti/file-storage/*`` replacing the path with the correct path |
1490 |
for your cluster. |
1491 |
|
1492 |
5. Stop the ganeti daemons (``/etc/init.d/ganeti stop``) and kill any |
1493 |
that remain alive (``pgrep ganeti`` and ``pkill ganeti``). |
1494 |
|
1495 |
6. Remove the ganeti state directory (``rm -rf /var/lib/ganeti/*``), |
1496 |
replacing the path with the correct path for your installation. |
1497 |
|
1498 |
7. If using RBD, run ``rbd unmap /dev/rbdN`` to unmap the RBD disks. |
1499 |
Then remove the RBD disk images used by Ganeti, identified by their |
1500 |
UUIDs (``rbd rm uuid.rbd.diskN``). |
1501 |
|
1502 |
On the master node, remove the cluster from the master-netdev (usually |
1503 |
``xen-br0`` for bridged mode, otherwise ``eth0`` or similar), by running |
1504 |
``ip a del $clusterip/32 dev xen-br0`` (use the correct cluster ip and |
1505 |
network device name). |
1506 |
|
1507 |
At this point, the machines are ready for a cluster creation; in case |
1508 |
you want to remove Ganeti completely, you need to also undo some of the |
1509 |
SSH changes and log directories: |
1510 |
|
1511 |
- ``rm -rf /var/log/ganeti /srv/ganeti`` (replace with the correct |
1512 |
paths) |
1513 |
- remove from ``/root/.ssh`` the keys that Ganeti added (check the |
1514 |
``authorized_keys`` and ``id_dsa`` files) |
1515 |
- regenerate the host's SSH keys (check the OpenSSH startup scripts) |
1516 |
- uninstall Ganeti |
1517 |
|
1518 |
Otherwise, if you plan to re-create the cluster, you can just go ahead |
1519 |
and rerun ``gnt-cluster init``. |
1520 |
|
1521 |
Replacing the SSH and SSL keys |
1522 |
++++++++++++++++++++++++++++++ |
1523 |
|
1524 |
Ganeti uses both SSL and SSH keys, and actively modifies the SSH keys on |
1525 |
the nodes. As result, in order to replace these keys, a few extra steps |
1526 |
need to be followed: :doc:`cluster-keys-replacement` |
1527 |
|
1528 |
Monitoring the cluster |
1529 |
---------------------- |
1530 |
|
1531 |
Starting with Ganeti 2.8, a monitoring daemon is available, providing |
1532 |
information about the status and the performance of the system. |
1533 |
|
1534 |
The monitoring daemon runs on every node, listening on TCP port 1815. Each |
1535 |
instance of the daemon provides information related to the node it is running |
1536 |
on. |
1537 |
|
1538 |
.. include:: monitoring-query-format.rst |
1539 |
|
1540 |
Tags handling |
1541 |
------------- |
1542 |
|
1543 |
The tags handling (addition, removal, listing) is similar for all the |
1544 |
objects that support it (instances, nodes, and the cluster). |
1545 |
|
1546 |
Limitations |
1547 |
+++++++++++ |
1548 |
|
1549 |
Note that the set of characters present in a tag and the maximum tag |
1550 |
length are restricted. Currently the maximum length is 128 characters, |
1551 |
there can be at most 4096 tags per object, and the set of characters is |
1552 |
comprised by alphanumeric characters and additionally ``.+*/:@-``. |
1553 |
|
1554 |
Operations |
1555 |
++++++++++ |
1556 |
|
1557 |
Tags can be added via ``add-tags``:: |
1558 |
|
1559 |
$ gnt-instance add-tags %INSTANCE% %a% %b% %c% |
1560 |
$ gnt-node add-tags %INSTANCE% %a% %b% %c% |
1561 |
$ gnt-cluster add-tags %a% %b% %c% |
1562 |
|
1563 |
|
1564 |
The above commands add three tags to an instance, to a node and to the |
1565 |
cluster. Note that the cluster command only takes tags as arguments, |
1566 |
whereas the node and instance commands first required the node and |
1567 |
instance name. |
1568 |
|
1569 |
Tags can also be added from a file, via the ``--from=FILENAME`` |
1570 |
argument. The file is expected to contain one tag per line. |
1571 |
|
1572 |
Tags can also be remove via a syntax very similar to the add one:: |
1573 |
|
1574 |
$ gnt-instance remove-tags %INSTANCE% %a% %b% %c% |
1575 |
|
1576 |
And listed via:: |
1577 |
|
1578 |
$ gnt-instance list-tags |
1579 |
$ gnt-node list-tags |
1580 |
$ gnt-cluster list-tags |
1581 |
|
1582 |
Global tag search |
1583 |
+++++++++++++++++ |
1584 |
|
1585 |
It is also possible to execute a global search on the all tags defined |
1586 |
in the cluster configuration, via a cluster command:: |
1587 |
|
1588 |
$ gnt-cluster search-tags %REGEXP% |
1589 |
|
1590 |
The parameter expected is a regular expression (see |
1591 |
:manpage:`regex(7)`). This will return all tags that match the search, |
1592 |
together with the object they are defined in (the names being show in a |
1593 |
hierarchical kind of way):: |
1594 |
|
1595 |
$ gnt-cluster search-tags %o% |
1596 |
/cluster foo |
1597 |
/instances/instance1 owner:bar |
1598 |
|
1599 |
Autorepair |
1600 |
---------- |
1601 |
|
1602 |
The tool ``harep`` can be used to automatically fix some problems that are |
1603 |
present in the cluster. |
1604 |
|
1605 |
It is mainly meant to be regularly and automatically executed |
1606 |
as a cron job. This is quite evident by considering that, when executed, it does |
1607 |
not immediately fix all the issues of the instances of the cluster, but it |
1608 |
cycles the instances through a series of states, one at every ``harep`` |
1609 |
execution. Every state performs a step towards the resolution of the problem. |
1610 |
This process goes on until the instance is brought back to the healthy state, |
1611 |
or the tool realizes that it is not able to fix the instance, and |
1612 |
therefore marks it as in failure state. |
1613 |
|
1614 |
Allowing harep to act on the cluster |
1615 |
++++++++++++++++++++++++++++++++++++ |
1616 |
|
1617 |
By default, ``harep`` checks the status of the cluster but it is not allowed to |
1618 |
perform any modification. Modification must be explicitly allowed by an |
1619 |
appropriate use of tags. Tagging can be applied at various levels, and can |
1620 |
enable different kinds of autorepair, as hereafter described. |
1621 |
|
1622 |
All the tags that authorize ``harep`` to perform modifications follow this |
1623 |
syntax:: |
1624 |
|
1625 |
ganeti:watcher:autorepair:<type> |
1626 |
|
1627 |
where ``<type>`` indicates the kind of intervention that can be performed. Every |
1628 |
possible value of ``<type>`` includes at least all the authorization of the |
1629 |
previous one, plus its own. The possible values, in increasing order of |
1630 |
severity, are: |
1631 |
|
1632 |
- ``fix-storage`` allows a disk replacement or another operation that |
1633 |
fixes the instance backend storage without affecting the instance |
1634 |
itself. This can for example recover from a broken drbd secondary, but |
1635 |
risks data loss if something is wrong on the primary but the secondary |
1636 |
was somehow recoverable. |
1637 |
- ``migrate`` allows an instance migration. This can recover from a |
1638 |
drained primary, but can cause an instance crash in some cases (bugs). |
1639 |
- ``failover`` allows instance reboot on the secondary. This can recover |
1640 |
from an offline primary, but the instance will lose its running state. |
1641 |
- ``reinstall`` allows disks to be recreated and an instance to be |
1642 |
reinstalled. This can recover from primary&secondary both being |
1643 |
offline, or from an offline primary in the case of non-redundant |
1644 |
instances. It causes data loss. |
1645 |
|
1646 |
These autorepair tags can be applied to a cluster, a nodegroup or an instance, |
1647 |
and will act where they are applied and to everything in the entities sub-tree |
1648 |
(e.g. a tag applied to a nodegroup will apply to all the instances contained in |
1649 |
that nodegroup, but not to the rest of the cluster). |
1650 |
|
1651 |
If there are multiple ``ganeti:watcher:autorepair:<type>`` tags in an |
1652 |
object (cluster, node group or instance), the least destructive tag |
1653 |
takes precedence. When multiplicity happens across objects, the nearest |
1654 |
tag wins. For example, if in a cluster with two instances, *I1* and |
1655 |
*I2*, *I1* has ``failover``, and the cluster itself has both |
1656 |
``fix-storage`` and ``reinstall``, *I1* will end up with ``failover`` |
1657 |
and *I2* with ``fix-storage``. |
1658 |
|
1659 |
Limiting harep |
1660 |
++++++++++++++ |
1661 |
|
1662 |
Sometimes it is useful to stop harep from performing its task temporarily, |
1663 |
and it is useful to be able to do so without distrupting its configuration, that |
1664 |
is, without removing the authorization tags. In order to do this, suspend tags |
1665 |
are provided. |
1666 |
|
1667 |
Suspend tags can be added to cluster, nodegroup or instances, and act on the |
1668 |
entire entities sub-tree. No operation will be performed by ``harep`` on the |
1669 |
instances protected by a suspend tag. Their syntax is as follows:: |
1670 |
|
1671 |
ganeti:watcher:autorepair:suspend[:<timestamp>] |
1672 |
|
1673 |
If there are multiple suspend tags in an object, the form without timestamp |
1674 |
takes precedence (permanent suspension); or, if all object tags have a |
1675 |
timestamp, the one with the highest timestamp. |
1676 |
|
1677 |
Tags with a timestamp will be automatically removed when the time indicated by |
1678 |
the timestamp is passed. Indefinite suspension tags have to be removed manually. |
1679 |
|
1680 |
Result reporting |
1681 |
++++++++++++++++ |
1682 |
|
1683 |
Harep will report about the result of its actions both through its CLI, and by |
1684 |
adding tags to the instances it operated on. Such tags will follow the syntax |
1685 |
hereby described:: |
1686 |
|
1687 |
ganeti:watcher:autorepair:result:<type>:<id>:<timestamp>:<result>:<jobs> |
1688 |
|
1689 |
If this tag is present a repair of type ``type`` has been performed on |
1690 |
the instance and has been completed by ``timestamp``. The result is |
1691 |
either ``success``, ``failure`` or ``enoperm``, and jobs is a |
1692 |
*+*-separated list of jobs that were executed for this repair. |
1693 |
|
1694 |
An ``enoperm`` result is an error state due to permission problems. It |
1695 |
is returned when the repair cannot proceed because it would require to perform |
1696 |
an operation that is not allowed by the ``ganeti:watcher:autorepair:<type>`` tag |
1697 |
that is defining the instance autorepair permissions. |
1698 |
|
1699 |
NB: if an instance repair ends up in a failure state, it will not be touched |
1700 |
again by ``harep`` until it has been manually fixed by the system administrator |
1701 |
and the ``ganeti:watcher:autorepair:result:failure:*`` tag has been manually |
1702 |
removed. |
1703 |
|
1704 |
Job operations |
1705 |
-------------- |
1706 |
|
1707 |
The various jobs submitted by the instance/node/cluster commands can be |
1708 |
examined, canceled and archived by various invocations of the |
1709 |
``gnt-job`` command. |
1710 |
|
1711 |
First is the job list command:: |
1712 |
|
1713 |
$ gnt-job list |
1714 |
17771 success INSTANCE_QUERY_DATA |
1715 |
17773 success CLUSTER_VERIFY_DISKS |
1716 |
17775 success CLUSTER_REPAIR_DISK_SIZES |
1717 |
17776 error CLUSTER_RENAME(cluster.example.com) |
1718 |
17780 success CLUSTER_REDIST_CONF |
1719 |
17792 success INSTANCE_REBOOT(instance1.example.com) |
1720 |
|
1721 |
More detailed information about a job can be found via the ``info`` |
1722 |
command:: |
1723 |
|
1724 |
$ gnt-job info %17776% |
1725 |
Job ID: 17776 |
1726 |
Status: error |
1727 |
Received: 2009-10-25 23:18:02.180569 |
1728 |
Processing start: 2009-10-25 23:18:02.200335 (delta 0.019766s) |
1729 |
Processing end: 2009-10-25 23:18:02.279743 (delta 0.079408s) |
1730 |
Total processing time: 0.099174 seconds |
1731 |
Opcodes: |
1732 |
OP_CLUSTER_RENAME |
1733 |
Status: error |
1734 |
Processing start: 2009-10-25 23:18:02.200335 |
1735 |
Processing end: 2009-10-25 23:18:02.252282 |
1736 |
Input fields: |
1737 |
name: cluster.example.com |
1738 |
Result: |
1739 |
OpPrereqError |
1740 |
[Neither the name nor the IP address of the cluster has changed] |
1741 |
Execution log: |
1742 |
|
1743 |
During the execution of a job, it's possible to follow the output of a |
1744 |
job, similar to the log that one get from the ``gnt-`` commands, via the |
1745 |
watch command:: |
1746 |
|
1747 |
$ gnt-instance add --submit … %instance1% |
1748 |
JobID: 17818 |
1749 |
$ gnt-job watch %17818% |
1750 |
Output from job 17818 follows |
1751 |
----------------------------- |
1752 |
Mon Oct 26 00:22:48 2009 - INFO: Selected nodes for instance instance1 via iallocator dumb: node1, node2 |
1753 |
Mon Oct 26 00:22:49 2009 * creating instance disks... |
1754 |
Mon Oct 26 00:22:52 2009 adding instance instance1 to cluster config |
1755 |
Mon Oct 26 00:22:52 2009 - INFO: Waiting for instance instance1 to sync disks. |
1756 |
… |
1757 |
Mon Oct 26 00:23:03 2009 creating os for instance instance1 on node node1 |
1758 |
Mon Oct 26 00:23:03 2009 * running the instance OS create scripts... |
1759 |
Mon Oct 26 00:23:13 2009 * starting instance... |
1760 |
$ |
1761 |
|
1762 |
This is useful if you need to follow a job's progress from multiple |
1763 |
terminals. |
1764 |
|
1765 |
A job that has not yet started to run can be canceled:: |
1766 |
|
1767 |
$ gnt-job cancel %17810% |
1768 |
|
1769 |
But not one that has already started execution:: |
1770 |
|
1771 |
$ gnt-job cancel %17805% |
1772 |
Job 17805 is no longer waiting in the queue |
1773 |
|
1774 |
There are two queues for jobs: the *current* and the *archive* |
1775 |
queue. Jobs are initially submitted to the current queue, and they stay |
1776 |
in that queue until they have finished execution (either successfully or |
1777 |
not). At that point, they can be moved into the archive queue using e.g. |
1778 |
``gnt-job autoarchive all``. The ``ganeti-watcher`` script will do this |
1779 |
automatically 6 hours after a job is finished. The ``ganeti-cleaner`` |
1780 |
script will then remove archived the jobs from the archive directory |
1781 |
after three weeks. |
1782 |
|
1783 |
Note that ``gnt-job list`` only shows jobs in the current queue. |
1784 |
Archived jobs can be viewed using ``gnt-job info <id>``. |
1785 |
|
1786 |
Special Ganeti deployments |
1787 |
-------------------------- |
1788 |
|
1789 |
Since Ganeti 2.4, it is possible to extend the Ganeti deployment with |
1790 |
two custom scenarios: Ganeti inside Ganeti and multi-site model. |
1791 |
|
1792 |
Running Ganeti under Ganeti |
1793 |
+++++++++++++++++++++++++++ |
1794 |
|
1795 |
It is sometimes useful to be able to use a Ganeti instance as a Ganeti |
1796 |
node (part of another cluster, usually). One example scenario is two |
1797 |
small clusters, where we want to have an additional master candidate |
1798 |
that holds the cluster configuration and can be used for helping with |
1799 |
the master voting process. |
1800 |
|
1801 |
However, these Ganeti instance should not host instances themselves, and |
1802 |
should not be considered in the normal capacity planning, evacuation |
1803 |
strategies, etc. In order to accomplish this, mark these nodes as |
1804 |
non-``vm_capable``:: |
1805 |
|
1806 |
$ gnt-node modify --vm-capable=no %node3% |
1807 |
|
1808 |
The vm_capable status can be listed as usual via ``gnt-node list``:: |
1809 |
|
1810 |
$ gnt-node list -oname,vm_capable |
1811 |
Node VMCapable |
1812 |
node1 Y |
1813 |
node2 Y |
1814 |
node3 N |
1815 |
|
1816 |
When this flag is set, the cluster will not do any operations that |
1817 |
relate to instances on such nodes, e.g. hypervisor operations, |
1818 |
disk-related operations, etc. Basically they will just keep the ssconf |
1819 |
files, and if master candidates the full configuration. |
1820 |
|
1821 |
Multi-site model |
1822 |
++++++++++++++++ |
1823 |
|
1824 |
If Ganeti is deployed in multi-site model, with each site being a node |
1825 |
group (so that instances are not relocated across the WAN by mistake), |
1826 |
it is conceivable that either the WAN latency is high or that some sites |
1827 |
have a lower reliability than others. In this case, it doesn't make |
1828 |
sense to replicate the job information across all sites (or even outside |
1829 |
of a “central” node group), so it should be possible to restrict which |
1830 |
nodes can become master candidates via the auto-promotion algorithm. |
1831 |
|
1832 |
Ganeti 2.4 introduces for this purpose a new ``master_capable`` flag, |
1833 |
which (when unset) prevents nodes from being marked as master |
1834 |
candidates, either manually or automatically. |
1835 |
|
1836 |
As usual, the node modify operation can change this flag:: |
1837 |
|
1838 |
$ gnt-node modify --auto-promote --master-capable=no %node3% |
1839 |
Fri Jan 7 06:23:07 2011 - INFO: Demoting from master candidate |
1840 |
Fri Jan 7 06:23:08 2011 - INFO: Promoted nodes to master candidate role: node4 |
1841 |
Modified node node3 |
1842 |
- master_capable -> False |
1843 |
- master_candidate -> False |
1844 |
|
1845 |
And the node list operation will list this flag:: |
1846 |
|
1847 |
$ gnt-node list -oname,master_capable %node1% %node2% %node3% |
1848 |
Node MasterCapable |
1849 |
node1 Y |
1850 |
node2 Y |
1851 |
node3 N |
1852 |
|
1853 |
Note that marking a node both not ``vm_capable`` and not |
1854 |
``master_capable`` makes the node practically unusable from Ganeti's |
1855 |
point of view. Hence these two flags should be used probably in |
1856 |
contrast: some nodes will be only master candidates (master_capable but |
1857 |
not vm_capable), and other nodes will only hold instances (vm_capable |
1858 |
but not master_capable). |
1859 |
|
1860 |
|
1861 |
Ganeti tools |
1862 |
------------ |
1863 |
|
1864 |
Beside the usual ``gnt-`` and ``ganeti-`` commands which are provided |
1865 |
and installed in ``$prefix/sbin`` at install time, there are a couple of |
1866 |
other tools installed which are used seldom but can be helpful in some |
1867 |
cases. |
1868 |
|
1869 |
lvmstrap |
1870 |
++++++++ |
1871 |
|
1872 |
The ``lvmstrap`` tool, introduced in :ref:`configure-lvm-label` section, |
1873 |
has two modes of operation: |
1874 |
|
1875 |
- ``diskinfo`` shows the discovered disks on the system and their status |
1876 |
- ``create`` takes all not-in-use disks and creates a volume group out |
1877 |
of them |
1878 |
|
1879 |
.. warning:: The ``create`` argument to this command causes data-loss! |
1880 |
|
1881 |
cfgupgrade |
1882 |
++++++++++ |
1883 |
|
1884 |
The ``cfgupgrade`` tools is used to upgrade between major (and minor) |
1885 |
Ganeti versions, and to roll back. Point-releases are usually |
1886 |
transparent for the admin. |
1887 |
|
1888 |
More information about the upgrade procedure is listed on the wiki at |
1889 |
http://code.google.com/p/ganeti/wiki/UpgradeNotes. |
1890 |
|
1891 |
There is also a script designed to upgrade from Ganeti 1.2 to 2.0, |
1892 |
called ``cfgupgrade12``. |
1893 |
|
1894 |
cfgshell |
1895 |
++++++++ |
1896 |
|
1897 |
.. note:: This command is not actively maintained; make sure you backup |
1898 |
your configuration before using it |
1899 |
|
1900 |
This can be used as an alternative to direct editing of the |
1901 |
main configuration file if Ganeti has a bug and prevents you, for |
1902 |
example, from removing an instance or a node from the configuration |
1903 |
file. |
1904 |
|
1905 |
.. _burnin-label: |
1906 |
|
1907 |
burnin |
1908 |
++++++ |
1909 |
|
1910 |
.. warning:: This command will erase existing instances if given as |
1911 |
arguments! |
1912 |
|
1913 |
This tool is used to exercise either the hardware of machines or |
1914 |
alternatively the Ganeti software. It is safe to run on an existing |
1915 |
cluster **as long as you don't pass it existing instance names**. |
1916 |
|
1917 |
The command will, by default, execute a comprehensive set of operations |
1918 |
against a list of instances, these being: |
1919 |
|
1920 |
- creation |
1921 |
- disk replacement (for redundant instances) |
1922 |
- failover and migration (for redundant instances) |
1923 |
- move (for non-redundant instances) |
1924 |
- disk growth |
1925 |
- add disks, remove disk |
1926 |
- add NICs, remove NICs |
1927 |
- export and then import |
1928 |
- rename |
1929 |
- reboot |
1930 |
- shutdown/startup |
1931 |
- and finally removal of the test instances |
1932 |
|
1933 |
Executing all these operations will test that the hardware performs |
1934 |
well: the creation, disk replace, disk add and disk growth will exercise |
1935 |
the storage and network; the migrate command will test the memory of the |
1936 |
systems. Depending on the passed options, it can also test that the |
1937 |
instance OS definitions are executing properly the rename, import and |
1938 |
export operations. |
1939 |
|
1940 |
sanitize-config |
1941 |
+++++++++++++++ |
1942 |
|
1943 |
This tool takes the Ganeti configuration and outputs a "sanitized" |
1944 |
version, by randomizing or clearing: |
1945 |
|
1946 |
- DRBD secrets and cluster public key (always) |
1947 |
- host names (optional) |
1948 |
- IPs (optional) |
1949 |
- OS names (optional) |
1950 |
- LV names (optional, only useful for very old clusters which still have |
1951 |
instances whose LVs are based on the instance name) |
1952 |
|
1953 |
By default, all optional items are activated except the LV name |
1954 |
randomization. When passing ``--no-randomization``, which disables the |
1955 |
optional items (i.e. just the DRBD secrets and cluster public keys are |
1956 |
randomized), the resulting file can be used as a safety copy of the |
1957 |
cluster config - while not trivial, the layout of the cluster can be |
1958 |
recreated from it and if the instance disks have not been lost it |
1959 |
permits recovery from the loss of all master candidates. |
1960 |
|
1961 |
move-instance |
1962 |
+++++++++++++ |
1963 |
|
1964 |
See :doc:`separate documentation for move-instance <move-instance>`. |
1965 |
|
1966 |
users-setup |
1967 |
+++++++++++ |
1968 |
|
1969 |
Ganeti can either be run entirely as root, or with every daemon running as |
1970 |
its own specific user (if the parameters ``--with-user-prefix`` and/or |
1971 |
``--with-group-prefix`` have been specified at ``./configure``-time). |
1972 |
|
1973 |
In case split users are activated, they are required to exist on the system, |
1974 |
and they need to belong to the proper groups in order for the access |
1975 |
permissions to files and programs to be correct. |
1976 |
|
1977 |
The ``users-setup`` tool, when run, takes care of setting up the proper |
1978 |
users and groups. |
1979 |
|
1980 |
When invoked without parameters, the tool runs in interactive mode, showing the |
1981 |
list of actions it will perform and asking for confirmation before proceeding. |
1982 |
|
1983 |
Providing the ``--yes-do-it`` parameter to the tool prevents the confirmation |
1984 |
from being asked, and the users and groups will be created immediately. |
1985 |
|
1986 |
.. TODO: document cluster-merge tool |
1987 |
|
1988 |
|
1989 |
Other Ganeti projects |
1990 |
--------------------- |
1991 |
|
1992 |
Below is a list (which might not be up-to-date) of additional projects |
1993 |
that can be useful in a Ganeti deployment. They can be downloaded from |
1994 |
the project site (http://code.google.com/p/ganeti/) and the repositories |
1995 |
are also on the project git site (http://git.ganeti.org). |
1996 |
|
1997 |
NBMA tools |
1998 |
++++++++++ |
1999 |
|
2000 |
The ``ganeti-nbma`` software is designed to allow instances to live on a |
2001 |
separate, virtual network from the nodes, and in an environment where |
2002 |
nodes are not guaranteed to be able to reach each other via multicasting |
2003 |
or broadcasting. For more information see the README in the source |
2004 |
archive. |
2005 |
|
2006 |
ganeti-htools |
2007 |
+++++++++++++ |
2008 |
|
2009 |
Before Ganeti version 2.5, this was a standalone project; since that |
2010 |
version it is integrated into the Ganeti codebase (see |
2011 |
:doc:`install-quick` for instructions on how to enable it). If you run |
2012 |
an older Ganeti version, you will have to download and build it |
2013 |
separately. |
2014 |
|
2015 |
For more information and installation instructions, see the README file |
2016 |
in the source archive. |
2017 |
|
2018 |
.. vim: set textwidth=72 : |
2019 |
.. Local Variables: |
2020 |
.. mode: rst |
2021 |
.. fill-column: 72 |
2022 |
.. End: |