root / man / gnt-instance.rst @ 5b53ca79
History | View | Annotate | Download (51.1 kB)
1 |
gnt-instance(8) Ganeti | Version @GANETI_VERSION@ |
---|---|
2 |
================================================= |
3 |
|
4 |
Name |
5 |
---- |
6 |
|
7 |
gnt-instance - Ganeti instance administration |
8 |
|
9 |
Synopsis |
10 |
-------- |
11 |
|
12 |
**gnt-instance** {command} [arguments...] |
13 |
|
14 |
DESCRIPTION |
15 |
----------- |
16 |
|
17 |
The **gnt-instance** command is used for instance administration in |
18 |
the Ganeti system. |
19 |
|
20 |
COMMANDS |
21 |
-------- |
22 |
|
23 |
Creation/removal/querying |
24 |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
25 |
|
26 |
ADD |
27 |
^^^ |
28 |
|
29 |
| **add** |
30 |
| {-t|--disk-template {diskless | file \| plain \| drbd}} |
31 |
| {--disk=*N*: {size=*VAL* \| adopt=*LV*}[,vg=*VG*][,metavg=*VG*][,mode=*ro\|rw*] |
32 |
| \| {-s|--os-size} *SIZE*} |
33 |
| [--no-ip-check] [--no-name-check] [--no-start] [--no-install] |
34 |
| [--net=*N* [:options...] \| --no-nics] |
35 |
| [{-B|--backend-parameters} *BEPARAMS*] |
36 |
| [{-H|--hypervisor-parameters} *HYPERVISOR* [: option=*value*... ]] |
37 |
| [{-O|--os-parameters} *param*=*value*... ] |
38 |
| [--file-storage-dir *dir\_path*] [--file-driver {loop \| blktap}] |
39 |
| {{-n|--node} *node[:secondary-node]* \| {-I|--iallocator} *name*} |
40 |
| {{-o|--os-type} *os-type*} |
41 |
| [--submit] |
42 |
| {*instance*} |
43 |
|
44 |
Creates a new instance on the specified host. The *instance* argument |
45 |
must be in DNS, but depending on the bridge/routing setup, need not be |
46 |
in the same network as the nodes in the cluster. |
47 |
|
48 |
The ``disk`` option specifies the parameters for the disks of the |
49 |
instance. The numbering of disks starts at zero, and at least one disk |
50 |
needs to be passed. For each disk, either the size or the adoption |
51 |
source needs to be given, and optionally the access mode (read-only or |
52 |
the default of read-write) and the LVM volume group can also be |
53 |
specified (via the ``vg`` key). For DRBD devices, a different VG can |
54 |
be specified for the metadata device using the ``metavg`` key. The |
55 |
size is interpreted (when no unit is given) in mebibytes. You can also |
56 |
use one of the suffixes *m*, *g* or *t* to specify the exact the units |
57 |
used; these suffixes map to mebibytes, gibibytes and tebibytes. |
58 |
|
59 |
When using the ``adopt`` key in the disk definition, Ganeti will |
60 |
reuse those volumes (instead of creating new ones) as the |
61 |
instance's disks. Ganeti will rename these volumes to the standard |
62 |
format, and (without installing the OS) will use them as-is for the |
63 |
instance. This allows migrating instances from non-managed mode |
64 |
(e.q. plain KVM with LVM) to being managed via Ganeti. Note that |
65 |
this works only for the \`plain' disk template (see below for |
66 |
template details). |
67 |
|
68 |
Alternatively, a single-disk instance can be created via the ``-s`` |
69 |
option which takes a single argument, the size of the disk. This is |
70 |
similar to the Ganeti 1.2 version (but will only create one disk). |
71 |
|
72 |
The minimum disk specification is therefore ``--disk 0:size=20G`` (or |
73 |
``-s 20G`` when using the ``-s`` option), and a three-disk instance |
74 |
can be specified as ``--disk 0:size=20G --disk 1:size=4G --disk |
75 |
2:size=100G``. |
76 |
|
77 |
The ``--no-ip-check`` skips the checks that are done to see if the |
78 |
instance's IP is not already alive (i.e. reachable from the master |
79 |
node). |
80 |
|
81 |
The ``--no-name-check`` skips the check for the instance name via |
82 |
the resolver (e.g. in DNS or /etc/hosts, depending on your setup). |
83 |
Since the name check is used to compute the IP address, if you pass |
84 |
this option you must also pass the ``--no-ip-check`` option. |
85 |
|
86 |
If you don't wat the instance to automatically start after |
87 |
creation, this is possible via the ``--no-start`` option. This will |
88 |
leave the instance down until a subsequent **gnt-instance start** |
89 |
command. |
90 |
|
91 |
The NICs of the instances can be specified via the ``--net`` |
92 |
option. By default, one NIC is created for the instance, with a |
93 |
random MAC, and set up according the the cluster level nic |
94 |
parameters. Each NIC can take these parameters (all optional): |
95 |
|
96 |
mac |
97 |
either a value or 'generate' to generate a new unique MAC |
98 |
|
99 |
ip |
100 |
specifies the IP address assigned to the instance from the Ganeti |
101 |
side (this is not necessarily what the instance will use, but what |
102 |
the node expects the instance to use) |
103 |
|
104 |
mode |
105 |
specifies the connection mode for this nic: routed or bridged. |
106 |
|
107 |
link |
108 |
in bridged mode specifies the bridge to attach this NIC to, in |
109 |
routed mode it's intended to differentiate between different |
110 |
routing tables/instance groups (but the meaning is dependent on |
111 |
the network script, see gnt-cluster(8) for more details) |
112 |
|
113 |
|
114 |
Of these "mode" and "link" are nic parameters, and inherit their |
115 |
default at cluster level. Alternatively, if no network is desired for |
116 |
the instance, you can prevent the default of one NIC with the |
117 |
``--no-nics`` option. |
118 |
|
119 |
The ``-o (--os-type)`` option specifies the operating system to be |
120 |
installed. The available operating systems can be listed with |
121 |
**gnt-os list**. Passing ``--no-install`` will however skip the OS |
122 |
installation, allowing a manual import if so desired. Note that the |
123 |
no-installation mode will automatically disable the start-up of the |
124 |
instance (without an OS, it most likely won't be able to start-up |
125 |
successfully). |
126 |
|
127 |
The ``-B (--backend-parameters)`` option specifies the backend |
128 |
parameters for the instance. If no such parameters are specified, the |
129 |
values are inherited from the cluster. Possible parameters are: |
130 |
|
131 |
memory |
132 |
the memory size of the instance; as usual, suffixes can be used to |
133 |
denote the unit, otherwise the value is taken in mebibites |
134 |
|
135 |
vcpus |
136 |
the number of VCPUs to assign to the instance (if this value makes |
137 |
sense for the hypervisor) |
138 |
|
139 |
auto\_balance |
140 |
whether the instance is considered in the N+1 cluster checks |
141 |
(enough redundancy in the cluster to survive a node failure) |
142 |
|
143 |
|
144 |
The ``-H (--hypervisor-parameters)`` option specified the hypervisor |
145 |
to use for the instance (must be one of the enabled hypervisors on the |
146 |
cluster) and optionally custom parameters for this instance. If not |
147 |
other options are used (i.e. the invocation is just -H *NAME*) the |
148 |
instance will inherit the cluster options. The defaults below show the |
149 |
cluster defaults at cluster creation time. |
150 |
|
151 |
The possible hypervisor options are as follows: |
152 |
|
153 |
boot\_order |
154 |
Valid for the Xen HVM and KVM hypervisors. |
155 |
|
156 |
A string value denoting the boot order. This has different meaning |
157 |
for the Xen HVM hypervisor and for the KVM one. |
158 |
|
159 |
For Xen HVM, The boot order is a string of letters listing the boot |
160 |
devices, with valid device letters being: |
161 |
|
162 |
a |
163 |
floppy drive |
164 |
|
165 |
c |
166 |
hard disk |
167 |
|
168 |
d |
169 |
CDROM drive |
170 |
|
171 |
n |
172 |
network boot (PXE) |
173 |
|
174 |
The default is not to set an HVM boot order which is interpreted |
175 |
as 'dc'. |
176 |
|
177 |
For KVM the boot order is either "floppy", "cdrom", "disk" or |
178 |
"network". Please note that older versions of KVM couldn't |
179 |
netboot from virtio interfaces. This has been fixed in more recent |
180 |
versions and is confirmed to work at least with qemu-kvm 0.11.1. |
181 |
|
182 |
blockdev\_prefix |
183 |
Valid for the Xen HVM and PVM hypervisors. |
184 |
|
185 |
Relevant to non-pvops guest kernels, in which the disk device names |
186 |
are given by the host. Allows one to specify 'xvd', which helps run |
187 |
Red Hat based installers, driven by anaconda. |
188 |
|
189 |
floppy\_image\_path |
190 |
Valid for the KVM hypervisor. |
191 |
|
192 |
The path to a floppy disk image to attach to the instance. This |
193 |
is useful to install Windows operating systems on Virt/IO disks |
194 |
because you can specify here the floppy for the drivers at |
195 |
installation time. |
196 |
|
197 |
cdrom\_image\_path |
198 |
Valid for the Xen HVM and KVM hypervisors. |
199 |
|
200 |
The path to a CDROM image to attach to the instance. |
201 |
|
202 |
cdrom2\_image\_path |
203 |
Valid for the KVM hypervisor. |
204 |
|
205 |
The path to a second CDROM image to attach to the instance. |
206 |
**NOTE**: This image can't be used to boot the system. To do that |
207 |
you have to use the 'cdrom\_image\_path' option. |
208 |
|
209 |
nic\_type |
210 |
Valid for the Xen HVM and KVM hypervisors. |
211 |
|
212 |
This parameter determines the way the network cards are presented |
213 |
to the instance. The possible options are: |
214 |
|
215 |
- rtl8139 (default for Xen HVM) (HVM & KVM) |
216 |
- ne2k\_isa (HVM & KVM) |
217 |
- ne2k\_pci (HVM & KVM) |
218 |
- i82551 (KVM) |
219 |
- i82557b (KVM) |
220 |
- i82559er (KVM) |
221 |
- pcnet (KVM) |
222 |
- e1000 (KVM) |
223 |
- paravirtual (default for KVM) (HVM & KVM) |
224 |
|
225 |
disk\_type |
226 |
Valid for the Xen HVM and KVM hypervisors. |
227 |
|
228 |
This parameter determines the way the disks are presented to the |
229 |
instance. The possible options are: |
230 |
|
231 |
- ioemu [default] (HVM & KVM) |
232 |
- ide (HVM & KVM) |
233 |
- scsi (KVM) |
234 |
- sd (KVM) |
235 |
- mtd (KVM) |
236 |
- pflash (KVM) |
237 |
|
238 |
|
239 |
cdrom\_disk\_type |
240 |
Valid for the KVM hypervisor. |
241 |
|
242 |
This parameter determines the way the cdroms disks are presented |
243 |
to the instance. The default behavior is to get the same value of |
244 |
the eariler parameter (disk_type). The possible options are: |
245 |
|
246 |
- paravirtual |
247 |
- ide |
248 |
- scsi |
249 |
- sd |
250 |
- mtd |
251 |
- pflash |
252 |
|
253 |
|
254 |
vnc\_bind\_address |
255 |
Valid for the Xen HVM and KVM hypervisors. |
256 |
|
257 |
Specifies the address that the VNC listener for this instance |
258 |
should bind to. Valid values are IPv4 addresses. Use the address |
259 |
0.0.0.0 to bind to all available interfaces (this is the default) |
260 |
or specify the address of one of the interfaces on the node to |
261 |
restrict listening to that interface. |
262 |
|
263 |
vnc\_tls |
264 |
Valid for the KVM hypervisor. |
265 |
|
266 |
A boolean option that controls whether the VNC connection is |
267 |
secured with TLS. |
268 |
|
269 |
vnc\_x509\_path |
270 |
Valid for the KVM hypervisor. |
271 |
|
272 |
If ``vnc_tls`` is enabled, this options specifies the path to the |
273 |
x509 certificate to use. |
274 |
|
275 |
vnc\_x509\_verify |
276 |
Valid for the KVM hypervisor. |
277 |
|
278 |
acpi |
279 |
Valid for the Xen HVM and KVM hypervisors. |
280 |
|
281 |
A boolean option that specifies if the hypervisor should enable |
282 |
ACPI support for this instance. By default, ACPI is disabled. |
283 |
|
284 |
pae |
285 |
Valid for the Xen HVM and KVM hypervisors. |
286 |
|
287 |
A boolean option that specifies if the hypervisor should enabled |
288 |
PAE support for this instance. The default is false, disabling PAE |
289 |
support. |
290 |
|
291 |
use\_localtime |
292 |
Valid for the Xen HVM and KVM hypervisors. |
293 |
|
294 |
A boolean option that specifies if the instance should be started |
295 |
with its clock set to the localtime of the machine (when true) or |
296 |
to the UTC (When false). The default is false, which is useful for |
297 |
Linux/Unix machines; for Windows OSes, it is recommended to enable |
298 |
this parameter. |
299 |
|
300 |
kernel\_path |
301 |
Valid for the Xen PVM and KVM hypervisors. |
302 |
|
303 |
This option specifies the path (on the node) to the kernel to boot |
304 |
the instance with. Xen PVM instances always require this, while |
305 |
for KVM if this option is empty, it will cause the machine to load |
306 |
the kernel from its disks. |
307 |
|
308 |
kernel\_args |
309 |
Valid for the Xen PVM and KVM hypervisors. |
310 |
|
311 |
This options specifies extra arguments to the kernel that will be |
312 |
loaded. device. This is always used for Xen PVM, while for KVM it |
313 |
is only used if the ``kernel_path`` option is also specified. |
314 |
|
315 |
The default setting for this value is simply ``"ro"``, which |
316 |
mounts the root disk (initially) in read-only one. For example, |
317 |
setting this to single will cause the instance to start in |
318 |
single-user mode. |
319 |
|
320 |
initrd\_path |
321 |
Valid for the Xen PVM and KVM hypervisors. |
322 |
|
323 |
This option specifies the path (on the node) to the initrd to boot |
324 |
the instance with. Xen PVM instances can use this always, while |
325 |
for KVM if this option is only used if the ``kernel_path`` option |
326 |
is also specified. You can pass here either an absolute filename |
327 |
(the path to the initrd) if you want to use an initrd, or use the |
328 |
format no\_initrd\_path for no initrd. |
329 |
|
330 |
root\_path |
331 |
Valid for the Xen PVM and KVM hypervisors. |
332 |
|
333 |
This options specifies the name of the root device. This is always |
334 |
needed for Xen PVM, while for KVM it is only used if the |
335 |
``kernel_path`` option is also specified. |
336 |
|
337 |
Please note, that if this setting is an empty string and the |
338 |
hypervisor is Xen it will not be written to the Xen configuration |
339 |
file |
340 |
|
341 |
serial\_console |
342 |
Valid for the KVM hypervisor. |
343 |
|
344 |
This boolean option specifies whether to emulate a serial console |
345 |
for the instance. |
346 |
|
347 |
disk\_cache |
348 |
Valid for the KVM hypervisor. |
349 |
|
350 |
The disk cache mode. It can be either default to not pass any |
351 |
cache option to KVM, or one of the KVM cache modes: none (for |
352 |
direct I/O), writethrough (to use the host cache but report |
353 |
completion to the guest only when the host has committed the |
354 |
changes to disk) or writeback (to use the host cache and report |
355 |
completion as soon as the data is in the host cache). Note that |
356 |
there are special considerations for the cache mode depending on |
357 |
version of KVM used and disk type (always raw file under Ganeti), |
358 |
please refer to the KVM documentation for more details. |
359 |
|
360 |
security\_model |
361 |
Valid for the KVM hypervisor. |
362 |
|
363 |
The security model for kvm. Currently one of *none*, *user* or |
364 |
*pool*. Under *none*, the default, nothing is done and instances |
365 |
are run as the Ganeti daemon user (normally root). |
366 |
|
367 |
Under *user* kvm will drop privileges and become the user |
368 |
specified by the security\_domain parameter. |
369 |
|
370 |
Under *pool* a global cluster pool of users will be used, making |
371 |
sure no two instances share the same user on the same node. (this |
372 |
mode is not implemented yet) |
373 |
|
374 |
security\_domain |
375 |
Valid for the KVM hypervisor. |
376 |
|
377 |
Under security model *user* the username to run the instance |
378 |
under. It must be a valid username existing on the host. |
379 |
|
380 |
Cannot be set under security model *none* or *pool*. |
381 |
|
382 |
kvm\_flag |
383 |
Valid for the KVM hypervisor. |
384 |
|
385 |
If *enabled* the -enable-kvm flag is passed to kvm. If *disabled* |
386 |
-disable-kvm is passed. If unset no flag is passed, and the |
387 |
default running mode for your kvm binary will be used. |
388 |
|
389 |
mem\_path |
390 |
Valid for the KVM hypervisor. |
391 |
|
392 |
This option passes the -mem-path argument to kvm with the path (on |
393 |
the node) to the mount point of the hugetlbfs file system, along |
394 |
with the -mem-prealloc argument too. |
395 |
|
396 |
use\_chroot |
397 |
Valid for the KVM hypervisor. |
398 |
|
399 |
This boolean option determines wether to run the KVM instance in a |
400 |
chroot directory. |
401 |
|
402 |
If it is set to ``true``, an empty directory is created before |
403 |
starting the instance and its path is passed via the -chroot flag |
404 |
to kvm. The directory is removed when the instance is stopped. |
405 |
|
406 |
It is set to ``false`` by default. |
407 |
|
408 |
migration\_downtime |
409 |
Valid for the KVM hypervisor. |
410 |
|
411 |
The maximum amount of time (in ms) a KVM instance is allowed to be |
412 |
frozen during a live migration, in order to copy dirty memory |
413 |
pages. Default value is 30ms, but you may need to increase this |
414 |
value for busy instances. |
415 |
|
416 |
This option is only effective with kvm versions >= 87 and qemu-kvm |
417 |
versions >= 0.11.0. |
418 |
|
419 |
cpu\_mask |
420 |
Valid for the LXC hypervisor. |
421 |
|
422 |
The processes belonging to the given instance are only scheduled |
423 |
on the specified CPUs. |
424 |
|
425 |
The parameter format is a comma-separated list of CPU IDs or CPU |
426 |
ID ranges. The ranges are defined by a lower and higher boundary, |
427 |
separated by a dash. The boundaries are inclusive. |
428 |
|
429 |
usb\_mouse |
430 |
Valid for the KVM hypervisor. |
431 |
|
432 |
This option specifies the usb mouse type to be used. It can be |
433 |
"mouse" or "tablet". When using VNC it's recommended to set it to |
434 |
"tablet". |
435 |
|
436 |
keymap |
437 |
Valid for the KVM hypervisor. |
438 |
|
439 |
This option specifies the keyboard mapping to be used. It is only |
440 |
needed when using the VNC console. For example: "fr" or "en-gb". |
441 |
|
442 |
|
443 |
The ``-O (--os-parameters)`` option allows customisation of the OS |
444 |
parameters. The actual parameter names and values depends on the OS |
445 |
being used, but the syntax is the same key=value. For example, setting |
446 |
a hypothetical ``dhcp`` parameter to yes can be achieved by:: |
447 |
|
448 |
gnt-instance add -O dhcp=yes ... |
449 |
|
450 |
The ``-I (--iallocator)`` option specifies the instance allocator |
451 |
plugin to use. If you pass in this option the allocator will select |
452 |
nodes for this instance automatically, so you don't need to pass them |
453 |
with the ``-n`` option. For more information please refer to the |
454 |
instance allocator documentation. |
455 |
|
456 |
The ``-t (--disk-template)`` options specifies the disk layout type |
457 |
for the instance. The available choices are: |
458 |
|
459 |
diskless |
460 |
This creates an instance with no disks. Its useful for testing only |
461 |
(or other special cases). |
462 |
|
463 |
file |
464 |
Disk devices will be regular files. |
465 |
|
466 |
plain |
467 |
Disk devices will be logical volumes. |
468 |
|
469 |
drbd |
470 |
Disk devices will be drbd (version 8.x) on top of lvm volumes. |
471 |
|
472 |
|
473 |
The optional second value of the ``-n (--node)`` is used for the drbd |
474 |
template type and specifies the remote node. |
475 |
|
476 |
If you do not want gnt-instance to wait for the disk mirror to be |
477 |
synced, use the ``--no-wait-for-sync`` option. |
478 |
|
479 |
The ``--file-storage-dir`` specifies the relative path under the |
480 |
cluster-wide file storage directory to store file-based disks. It is |
481 |
useful for having different subdirectories for different |
482 |
instances. The full path of the directory where the disk files are |
483 |
stored will consist of cluster-wide file storage directory + optional |
484 |
subdirectory + instance name. Example: |
485 |
``@RPL_FILE_STORAGE_DIR@``*/mysubdir/instance1.example.com*. This |
486 |
option is only relevant for instances using the file storage backend. |
487 |
|
488 |
The ``--file-driver`` specifies the driver to use for file-based |
489 |
disks. Note that currently these drivers work with the xen hypervisor |
490 |
only. This option is only relevant for instances using the file |
491 |
storage backend. The available choices are: |
492 |
|
493 |
loop |
494 |
Kernel loopback driver. This driver uses loopback devices to |
495 |
access the filesystem within the file. However, running I/O |
496 |
intensive applications in your instance using the loop driver |
497 |
might result in slowdowns. Furthermore, if you use the loopback |
498 |
driver consider increasing the maximum amount of loopback devices |
499 |
(on most systems it's 8) using the max\_loop param. |
500 |
|
501 |
blktap |
502 |
The blktap driver (for Xen hypervisors). In order to be able to |
503 |
use the blktap driver you should check if the 'blktapctrl' user |
504 |
space disk agent is running (usually automatically started via |
505 |
xend). This user-level disk I/O interface has the advantage of |
506 |
better performance. Especially if you use a network file system |
507 |
(e.g. NFS) to store your instances this is the recommended choice. |
508 |
|
509 |
|
510 |
The ``--submit`` option is used to send the job to the master daemon |
511 |
but not wait for its completion. The job ID will be shown so that it |
512 |
can be examined via **gnt-job info**. |
513 |
|
514 |
Example:: |
515 |
|
516 |
# gnt-instance add -t file --disk 0:size=30g -B memory=512 -o debian-etch \ |
517 |
-n node1.example.com --file-storage-dir=mysubdir instance1.example.com |
518 |
# gnt-instance add -t plain --disk 0:size=30g -B memory=512 -o debian-etch \ |
519 |
-n node1.example.com instance1.example.com |
520 |
# gnt-instance add -t plain --disk 0:size=30g --disk 1:size=100g,vg=san \ |
521 |
-B memory=512 -o debian-etch -n node1.example.com instance1.example.com |
522 |
# gnt-instance add -t drbd --disk 0:size=30g -B memory=512 -o debian-etch \ |
523 |
-n node1.example.com:node2.example.com instance2.example.com |
524 |
|
525 |
|
526 |
BATCH-CREATE |
527 |
^^^^^^^^^^^^ |
528 |
|
529 |
**batch-create** {instances\_file.json} |
530 |
|
531 |
This command (similar to the Ganeti 1.2 **batcher** tool) submits |
532 |
multiple instance creation jobs based on a definition file. The |
533 |
instance configurations do not encompass all the possible options for |
534 |
the **add** command, but only a subset. |
535 |
|
536 |
The instance file should be a valid-formed JSON file, containing a |
537 |
dictionary with instance name and instance parameters. The accepted |
538 |
parameters are: |
539 |
|
540 |
disk\_size |
541 |
The size of the disks of the instance. |
542 |
|
543 |
disk\_template |
544 |
The disk template to use for the instance, the same as in the |
545 |
**add** command. |
546 |
|
547 |
backend |
548 |
A dictionary of backend parameters. |
549 |
|
550 |
hypervisor |
551 |
A dictionary with a single key (the hypervisor name), and as value |
552 |
the hypervisor options. If not passed, the default hypervisor and |
553 |
hypervisor options will be inherited. |
554 |
|
555 |
mac, ip, mode, link |
556 |
Specifications for the one NIC that will be created for the |
557 |
instance. 'bridge' is also accepted as a backwards compatibile |
558 |
key. |
559 |
|
560 |
nics |
561 |
List of nics that will be created for the instance. Each entry |
562 |
should be a dict, with mac, ip, mode and link as possible keys. |
563 |
Please don't provide the "mac, ip, mode, link" parent keys if you |
564 |
use this method for specifying nics. |
565 |
|
566 |
primary\_node, secondary\_node |
567 |
The primary and optionally the secondary node to use for the |
568 |
instance (in case an iallocator script is not used). |
569 |
|
570 |
iallocator |
571 |
Instead of specifying the nodes, an iallocator script can be used |
572 |
to automatically compute them. |
573 |
|
574 |
start |
575 |
whether to start the instance |
576 |
|
577 |
ip\_check |
578 |
Skip the check for already-in-use instance; see the description in |
579 |
the **add** command for details. |
580 |
|
581 |
name\_check |
582 |
Skip the name check for instances; see the description in the |
583 |
**add** command for details. |
584 |
|
585 |
file\_storage\_dir, file\_driver |
586 |
Configuration for the file disk type, see the **add** command for |
587 |
details. |
588 |
|
589 |
|
590 |
A simple definition for one instance can be (with most of the |
591 |
parameters taken from the cluster defaults):: |
592 |
|
593 |
{ |
594 |
"instance3": { |
595 |
"template": "drbd", |
596 |
"os": "debootstrap", |
597 |
"disk_size": ["25G"], |
598 |
"iallocator": "dumb" |
599 |
}, |
600 |
"instance5": { |
601 |
"template": "drbd", |
602 |
"os": "debootstrap", |
603 |
"disk_size": ["25G"], |
604 |
"iallocator": "dumb", |
605 |
"hypervisor": "xen-hvm", |
606 |
"hvparams": {"acpi": true}, |
607 |
"backend": {"memory": 512} |
608 |
} |
609 |
} |
610 |
|
611 |
The command will display the job id for each submitted instance, as |
612 |
follows:: |
613 |
|
614 |
# gnt-instance batch-create instances.json |
615 |
instance3: 11224 |
616 |
instance5: 11225 |
617 |
|
618 |
REMOVE |
619 |
^^^^^^ |
620 |
|
621 |
**remove** [--ignore-failures] [--shutdown-timeout=*N*] [--submit] |
622 |
{*instance*} |
623 |
|
624 |
Remove an instance. This will remove all data from the instance and |
625 |
there is *no way back*. If you are not sure if you use an instance |
626 |
again, use **shutdown** first and leave it in the shutdown state for a |
627 |
while. |
628 |
|
629 |
The ``--ignore-failures`` option will cause the removal to proceed |
630 |
even in the presence of errors during the removal of the instance |
631 |
(e.g. during the shutdown or the disk removal). If this option is not |
632 |
given, the command will stop at the first error. |
633 |
|
634 |
The ``--shutdown-timeout`` is used to specify how much time to wait |
635 |
before forcing the shutdown (e.g. ``xm destroy`` in Xen, killing the |
636 |
kvm process for KVM, etc.). By default two minutes are given to each |
637 |
instance to stop. |
638 |
|
639 |
The ``--submit`` option is used to send the job to the master daemon |
640 |
but not wait for its completion. The job ID will be shown so that it |
641 |
can be examined via **gnt-job info**. |
642 |
|
643 |
Example:: |
644 |
|
645 |
# gnt-instance remove instance1.example.com |
646 |
|
647 |
|
648 |
LIST |
649 |
^^^^ |
650 |
|
651 |
| **list** |
652 |
| [--no-headers] [--separator=*SEPARATOR*] [--units=*UNITS*] [-v] |
653 |
| [{-o|--output} *[+]FIELD,...*] [--filter] [instance...] |
654 |
|
655 |
Shows the currently configured instances with memory usage, disk |
656 |
usage, the node they are running on, and their run status. |
657 |
|
658 |
The ``--no-headers`` option will skip the initial header line. The |
659 |
``--separator`` option takes an argument which denotes what will be |
660 |
used between the output fields. Both these options are to help |
661 |
scripting. |
662 |
|
663 |
The units used to display the numeric values in the output varies, |
664 |
depending on the options given. By default, the values will be |
665 |
formatted in the most appropriate unit. If the ``--separator`` option |
666 |
is given, then the values are shown in mebibytes to allow parsing by |
667 |
scripts. In both cases, the ``--units`` option can be used to enforce |
668 |
a given output unit. |
669 |
|
670 |
The ``-v`` option activates verbose mode, which changes the display of |
671 |
special field states (see **ganeti(7)**). |
672 |
|
673 |
The ``-o (--output)`` option takes a comma-separated list of output |
674 |
fields. The available fields and their meaning are: |
675 |
|
676 |
@QUERY_FIELDS_INSTANCE@ |
677 |
|
678 |
If the value of the option starts with the character ``+``, the new |
679 |
field(s) will be added to the default list. This allows one to quickly |
680 |
see the default list plus a few other fields, instead of retyping the |
681 |
entire list of fields. |
682 |
|
683 |
There is a subtle grouping about the available output fields: all |
684 |
fields except for ``oper_state``, ``oper_ram``, ``oper_vcpus`` and |
685 |
``status`` are configuration value and not run-time values. So if you |
686 |
don't select any of the these fields, the query will be satisfied |
687 |
instantly from the cluster configuration, without having to ask the |
688 |
remote nodes for the data. This can be helpful for big clusters when |
689 |
you only want some data and it makes sense to specify a reduced set of |
690 |
output fields. |
691 |
|
692 |
If exactly one argument is given and it appears to be a query filter |
693 |
(see **ganeti(7)**), the query result is filtered accordingly. For |
694 |
ambiguous cases (e.g. a single field name as a filter) the ``--filter`` |
695 |
(``-F``) option forces the argument to be treated as a filter (e.g. |
696 |
``gnt-instance list -F admin_state``). |
697 |
|
698 |
The default output field list is: ``name``, ``os``, ``pnode``, |
699 |
``admin_state``, ``oper_state``, ``oper_ram``. |
700 |
|
701 |
|
702 |
LIST-FIELDS |
703 |
~~~~~~~~~~~ |
704 |
|
705 |
**list-fields** [field...] |
706 |
|
707 |
Lists available fields for instances. |
708 |
|
709 |
|
710 |
INFO |
711 |
^^^^ |
712 |
|
713 |
**info** [-s \| --static] [--roman] {--all \| *instance*} |
714 |
|
715 |
Show detailed information about the given instance(s). This is |
716 |
different from **list** as it shows detailed data about the instance's |
717 |
disks (especially useful for the drbd disk template). |
718 |
|
719 |
If the option ``-s`` is used, only information available in the |
720 |
configuration file is returned, without querying nodes, making the |
721 |
operation faster. |
722 |
|
723 |
Use the ``--all`` to get info about all instances, rather than |
724 |
explicitly passing the ones you're interested in. |
725 |
|
726 |
The ``--roman`` option can be used to cause envy among people who like |
727 |
ancient cultures, but are stuck with non-latin-friendly cluster |
728 |
virtualization technologies. |
729 |
|
730 |
MODIFY |
731 |
^^^^^^ |
732 |
|
733 |
| **modify** |
734 |
| [{-H|--hypervisor-parameters} *HYPERVISOR\_PARAMETERS*] |
735 |
| [{-B|--backend-parameters} *BACKEND\_PARAMETERS*] |
736 |
| [--net add*[:options]* \| --net remove \| --net *N:options*] |
737 |
| [--disk add:size=*SIZE*[,vg=*VG*][,metavg=*VG*] \| --disk remove \| |
738 |
| --disk *N*:mode=*MODE*] |
739 |
| [{-t|--disk-template} plain | {-t|--disk-template} drbd -n *new_secondary*] [--no-wait-for-sync] |
740 |
| [--os-type=*OS* [--force-variant]] |
741 |
| [{-O|--os-parameters} *param*=*value*... ] |
742 |
| [--submit] |
743 |
| {*instance*} |
744 |
|
745 |
Modifies the memory size, number of vcpus, ip address, MAC address |
746 |
and/or nic parameters for an instance. It can also add and remove |
747 |
disks and NICs to/from the instance. Note that you need to give at |
748 |
least one of the arguments, otherwise the command complains. |
749 |
|
750 |
The ``-H (--hypervisor-parameters)``, ``-B (--backend-parameters)`` |
751 |
and ``-O (--os-parameters)`` options specifies hypervisor, backend and |
752 |
OS parameter options in the form of name=value[,...]. For details |
753 |
which options can be specified, see the **add** command. |
754 |
|
755 |
The ``-t (--disk-template)`` option will change the disk template of |
756 |
the instance. Currently only conversions between the plain and drbd |
757 |
disk templates are supported, and the instance must be stopped before |
758 |
attempting the conversion. When changing from the plain to the drbd |
759 |
disk template, a new secondary node must be specified via the ``-n`` |
760 |
option. The option ``--no-wait-for-sync`` can be used when converting |
761 |
to the ``drbd`` template in order to make the instance available for |
762 |
startup before DRBD has finished resyncing. |
763 |
|
764 |
The ``--disk add:size=``*SIZE* option adds a disk to the instance. The |
765 |
optional ``vg=``*VG* option specifies LVM volume group other than |
766 |
default vg to create the disk on. For DRBD disks, the ``metavg=``*VG* |
767 |
option specifies the volume group for the metadata device. The |
768 |
``--disk remove`` option will remove the last disk of the |
769 |
instance. The ``--disk`` *N*``:mode=``*MODE* option will change the |
770 |
mode of the Nth disk of the instance between read-only (``ro``) and |
771 |
read-write (``rw``). |
772 |
|
773 |
The ``--net add:``*options* option will add a new NIC to the |
774 |
instance. The available options are the same as in the **add** command |
775 |
(mac, ip, link, mode). The ``--net remove`` will remove the last NIC |
776 |
of the instance, while the ``--net`` *N*:*options* option will change |
777 |
the parameters of the Nth instance NIC. |
778 |
|
779 |
The option ``-o (--os-type)`` will change the OS name for the instance |
780 |
(without reinstallation). In case an OS variant is specified that is |
781 |
not found, then by default the modification is refused, unless |
782 |
``--force-variant`` is passed. An invalid OS will also be refused, |
783 |
unless the ``--force`` option is given. |
784 |
|
785 |
The ``--submit`` option is used to send the job to the master daemon |
786 |
but not wait for its completion. The job ID will be shown so that it |
787 |
can be examined via **gnt-job info**. |
788 |
|
789 |
All the changes take effect at the next restart. If the instance is |
790 |
running, there is no effect on the instance. |
791 |
|
792 |
REINSTALL |
793 |
^^^^^^^^^ |
794 |
|
795 |
| **reinstall** [{-o|--os-type} *os-type*] [--select-os] [-f *force*] |
796 |
| [--force-multiple] |
797 |
| [--instance \| --node \| --primary \| --secondary \| --all] |
798 |
| [{-O|--os-parameters} *OS\_PARAMETERS*] [--submit] {*instance*...} |
799 |
|
800 |
Reinstalls the operating system on the given instance(s). The |
801 |
instance(s) must be stopped when running this command. If the ``-o |
802 |
(--os-type)`` is specified, the operating system is changed. |
803 |
|
804 |
The ``--select-os`` option switches to an interactive OS reinstall. |
805 |
The user is prompted to select the OS template from the list of |
806 |
available OS templates. OS parameters can be overridden using ``-O |
807 |
(--os-parameters)`` (more documentation for this option under the |
808 |
**add** command). |
809 |
|
810 |
Since this is a potentially dangerous command, the user will be |
811 |
required to confirm this action, unless the ``-f`` flag is passed. |
812 |
When multiple instances are selected (either by passing multiple |
813 |
arguments or by using the ``--node``, ``--primary``, ``--secondary`` |
814 |
or ``--all`` options), the user must pass the ``--force-multiple`` |
815 |
options to skip the interactive confirmation. |
816 |
|
817 |
The ``--submit`` option is used to send the job to the master daemon |
818 |
but not wait for its completion. The job ID will be shown so that it |
819 |
can be examined via **gnt-job info**. |
820 |
|
821 |
RENAME |
822 |
^^^^^^ |
823 |
|
824 |
| **rename** [--no-ip-check] [--no-name-check] [--submit] |
825 |
| {*instance*} {*new\_name*} |
826 |
|
827 |
Renames the given instance. The instance must be stopped when running |
828 |
this command. The requirements for the new name are the same as for |
829 |
adding an instance: the new name must be resolvable and the IP it |
830 |
resolves to must not be reachable (in order to prevent duplicate IPs |
831 |
the next time the instance is started). The IP test can be skipped if |
832 |
the ``--no-ip-check`` option is passed. |
833 |
|
834 |
The ``--no-name-check`` skips the check for the new instance name via |
835 |
the resolver (e.g. in DNS or /etc/hosts, depending on your setup) and |
836 |
that the resolved name matches the provided name. Since the name check |
837 |
is used to compute the IP address, if you pass this option you must also |
838 |
pass the ``--no-ip-check`` option. |
839 |
|
840 |
The ``--submit`` option is used to send the job to the master daemon |
841 |
but not wait for its completion. The job ID will be shown so that it |
842 |
can be examined via **gnt-job info**. |
843 |
|
844 |
Starting/stopping/connecting to console |
845 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
846 |
|
847 |
STARTUP |
848 |
^^^^^^^ |
849 |
|
850 |
| **startup** |
851 |
| [--force] [--ignore-offline] |
852 |
| [--force-multiple] [--no-remember] |
853 |
| [--instance \| --node \| --primary \| --secondary \| --all \| |
854 |
| --tags \| --node-tags \| --pri-node-tags \| --sec-node-tags] |
855 |
| [{-H|--hypervisor-parameters} ``key=value...``] |
856 |
| [{-B|--backend-parameters} ``key=value...``] |
857 |
| [--submit] [--paused] |
858 |
| {*name*...} |
859 |
|
860 |
Starts one or more instances, depending on the following options. The |
861 |
four available modes are: |
862 |
|
863 |
--instance |
864 |
will start the instances given as arguments (at least one argument |
865 |
required); this is the default selection |
866 |
|
867 |
--node |
868 |
will start the instances who have the given node as either primary |
869 |
or secondary |
870 |
|
871 |
--primary |
872 |
will start all instances whose primary node is in the list of nodes |
873 |
passed as arguments (at least one node required) |
874 |
|
875 |
--secondary |
876 |
will start all instances whose secondary node is in the list of |
877 |
nodes passed as arguments (at least one node required) |
878 |
|
879 |
--all |
880 |
will start all instances in the cluster (no arguments accepted) |
881 |
|
882 |
--tags |
883 |
will start all instances in the cluster with the tags given as |
884 |
arguments |
885 |
|
886 |
--node-tags |
887 |
will start all instances in the cluster on nodes with the tags |
888 |
given as arguments |
889 |
|
890 |
--pri-node-tags |
891 |
will start all instances in the cluster on primary nodes with the |
892 |
tags given as arguments |
893 |
|
894 |
--sec-node-tags |
895 |
will start all instances in the cluster on secondary nodes with the |
896 |
tags given as arguments |
897 |
|
898 |
Note that although you can pass more than one selection option, the |
899 |
last one wins, so in order to guarantee the desired result, don't pass |
900 |
more than one such option. |
901 |
|
902 |
Use ``--force`` to start even if secondary disks are failing. |
903 |
``--ignore-offline`` can be used to ignore offline primary nodes and |
904 |
mark the instance as started even if the primary is not available. |
905 |
|
906 |
The ``--force-multiple`` will skip the interactive confirmation in the |
907 |
case the more than one instance will be affected. |
908 |
|
909 |
The ``--no-remember`` option will perform the startup but not change |
910 |
the state of the instance in the configuration file (if it was stopped |
911 |
before, Ganeti will still thinks it needs to be stopped). This can be |
912 |
used for testing, or for a one shot-start where you don't want the |
913 |
watcher to restart the instance if it crashes. |
914 |
|
915 |
The ``-H (--hypervisor-parameters)`` and ``-B (--backend-parameters)`` |
916 |
options specify temporary hypervisor and backend parameters that can |
917 |
be used to start an instance with modified parameters. They can be |
918 |
useful for quick testing without having to modify an instance back and |
919 |
forth, e.g.:: |
920 |
|
921 |
# gnt-instance start -H kernel_args="single" instance1 |
922 |
# gnt-instance start -B memory=2048 instance2 |
923 |
|
924 |
|
925 |
The first form will start the instance instance1 in single-user mode, |
926 |
and the instance instance2 with 2GB of RAM (this time only, unless |
927 |
that is the actual instance memory size already). Note that the values |
928 |
override the instance parameters (and not extend them): an instance |
929 |
with "kernel\_args=ro" when started with -H kernel\_args=single will |
930 |
result in "single", not "ro single". The ``--submit`` option is used |
931 |
to send the job to the master daemon but not wait for its |
932 |
completion. The job ID will be shown so that it can be examined via |
933 |
**gnt-job info**. |
934 |
|
935 |
The ``--paused`` option is only valid for Xen and kvm hypervisors. This |
936 |
pauses the instance at the start of bootup, awaiting ``gnt-instance |
937 |
console`` to unpause it, allowing the entire boot process to be |
938 |
monitored for debugging. |
939 |
|
940 |
Example:: |
941 |
|
942 |
# gnt-instance start instance1.example.com |
943 |
# gnt-instance start --node node1.example.com node2.example.com |
944 |
# gnt-instance start --all |
945 |
|
946 |
|
947 |
SHUTDOWN |
948 |
^^^^^^^^ |
949 |
|
950 |
| **shutdown** |
951 |
| [--timeout=*N*] |
952 |
| [--force-multiple] [--ignore-offline] [--no-remember] |
953 |
| [--instance \| --node \| --primary \| --secondary \| --all \| |
954 |
| --tags \| --node-tags \| --pri-node-tags \| --sec-node-tags] |
955 |
| [--submit] |
956 |
| {*name*...} |
957 |
|
958 |
Stops one or more instances. If the instance cannot be cleanly stopped |
959 |
during a hardcoded interval (currently 2 minutes), it will forcibly |
960 |
stop the instance (equivalent to switching off the power on a physical |
961 |
machine). |
962 |
|
963 |
The ``--timeout`` is used to specify how much time to wait before |
964 |
forcing the shutdown (e.g. ``xm destroy`` in Xen, killing the kvm |
965 |
process for KVM, etc.). By default two minutes are given to each |
966 |
instance to stop. |
967 |
|
968 |
The ``--instance``, ``--node``, ``--primary``, ``--secondary``, |
969 |
``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and |
970 |
``--sec-node-tags`` options are similar as for the **startup** command |
971 |
and they influence the actual instances being shutdown. |
972 |
|
973 |
The ``--submit`` option is used to send the job to the master daemon |
974 |
but not wait for its completion. The job ID will be shown so that it |
975 |
can be examined via **gnt-job info**. |
976 |
|
977 |
``--ignore-offline`` can be used to ignore offline primary nodes and |
978 |
force the instance to be marked as stopped. This option should be used |
979 |
with care as it can lead to an inconsistent cluster state. |
980 |
|
981 |
The ``--no-remember`` option will perform the shutdown but not change |
982 |
the state of the instance in the configuration file (if it was running |
983 |
before, Ganeti will still thinks it needs to be running). This can be |
984 |
useful for a cluster-wide shutdown, where some instances are marked as |
985 |
up and some as down, and you don't want to change the running state: |
986 |
you just need to disable the watcher, shutdown all instances with |
987 |
``--no-remember``, and when the watcher is activated again it will |
988 |
restore the correct runtime state for all instances. |
989 |
|
990 |
Example:: |
991 |
|
992 |
# gnt-instance shutdown instance1.example.com |
993 |
# gnt-instance shutdown --all |
994 |
|
995 |
|
996 |
REBOOT |
997 |
^^^^^^ |
998 |
|
999 |
| **reboot** |
1000 |
| [{-t|--type} *REBOOT-TYPE*] |
1001 |
| [--ignore-secondaries] |
1002 |
| [--shutdown-timeout=*N*] |
1003 |
| [--force-multiple] |
1004 |
| [--instance \| --node \| --primary \| --secondary \| --all \| |
1005 |
| --tags \| --node-tags \| --pri-node-tags \| --sec-node-tags] |
1006 |
| [--submit] |
1007 |
| [*name*...] |
1008 |
|
1009 |
Reboots one or more instances. The type of reboot depends on the value |
1010 |
of ``-t (--type)``. A soft reboot does a hypervisor reboot, a hard reboot |
1011 |
does a instance stop, recreates the hypervisor config for the instance |
1012 |
and starts the instance. A full reboot does the equivalent of |
1013 |
**gnt-instance shutdown && gnt-instance startup**. The default is |
1014 |
hard reboot. |
1015 |
|
1016 |
For the hard reboot the option ``--ignore-secondaries`` ignores errors |
1017 |
for the secondary node while re-assembling the instance disks. |
1018 |
|
1019 |
The ``--instance``, ``--node``, ``--primary``, ``--secondary``, |
1020 |
``--all``, ``--tags``, ``--node-tags``, ``--pri-node-tags`` and |
1021 |
``--sec-node-tags`` options are similar as for the **startup** command |
1022 |
and they influence the actual instances being rebooted. |
1023 |
|
1024 |
The ``--shutdown-timeout`` is used to specify how much time to wait |
1025 |
before forcing the shutdown (xm destroy in xen, killing the kvm |
1026 |
process, for kvm). By default two minutes are given to each instance |
1027 |
to stop. |
1028 |
|
1029 |
The ``--force-multiple`` will skip the interactive confirmation in the |
1030 |
case the more than one instance will be affected. |
1031 |
|
1032 |
Example:: |
1033 |
|
1034 |
# gnt-instance reboot instance1.example.com |
1035 |
# gnt-instance reboot --type=full instance1.example.com |
1036 |
|
1037 |
|
1038 |
CONSOLE |
1039 |
^^^^^^^ |
1040 |
|
1041 |
**console** [--show-cmd] {*instance*} |
1042 |
|
1043 |
Connects to the console of the given instance. If the instance is not |
1044 |
up, an error is returned. Use the ``--show-cmd`` option to display the |
1045 |
command instead of executing it. |
1046 |
|
1047 |
For HVM instances, this will attempt to connect to the serial console |
1048 |
of the instance. To connect to the virtualized "physical" console of a |
1049 |
HVM instance, use a VNC client with the connection info from the |
1050 |
**info** command. |
1051 |
|
1052 |
For Xen/kvm instances, if the instance is paused, this attempts to |
1053 |
unpause the instance after waiting a few seconds for the connection to |
1054 |
the console to be made. |
1055 |
|
1056 |
Example:: |
1057 |
|
1058 |
# gnt-instance console instance1.example.com |
1059 |
|
1060 |
|
1061 |
Disk management |
1062 |
~~~~~~~~~~~~~~~ |
1063 |
|
1064 |
REPLACE-DISKS |
1065 |
^^^^^^^^^^^^^ |
1066 |
|
1067 |
**replace-disks** [--submit] [--early-release] {-p} [--disks *idx*] |
1068 |
{*instance*} |
1069 |
|
1070 |
**replace-disks** [--submit] [--early-release] {-s} [--disks *idx*] |
1071 |
{*instance*} |
1072 |
|
1073 |
**replace-disks** [--submit] [--early-release] {--iallocator *name* |
1074 |
\| --new-secondary *NODE*} {*instance*} |
1075 |
|
1076 |
**replace-disks** [--submit] [--early-release] {--auto} |
1077 |
{*instance*} |
1078 |
|
1079 |
This command is a generalized form for replacing disks. It is |
1080 |
currently only valid for the mirrored (DRBD) disk template. |
1081 |
|
1082 |
The first form (when passing the ``-p`` option) will replace the disks |
1083 |
on the primary, while the second form (when passing the ``-s`` option |
1084 |
will replace the disks on the secondary node. For these two cases (as |
1085 |
the node doesn't change), it is possible to only run the replace for a |
1086 |
subset of the disks, using the option ``--disks`` which takes a list |
1087 |
of comma-delimited disk indices (zero-based), e.g. 0,2 to replace only |
1088 |
the first and third disks. |
1089 |
|
1090 |
The third form (when passing either the ``--iallocator`` or the |
1091 |
``--new-secondary`` option) is designed to change secondary node of |
1092 |
the instance. Specifying ``--iallocator`` makes the new secondary be |
1093 |
selected automatically by the specified allocator plugin, otherwise |
1094 |
the new secondary node will be the one chosen manually via the |
1095 |
``--new-secondary`` option. |
1096 |
|
1097 |
The fourth form (when using ``--auto``) will automatically determine |
1098 |
which disks of an instance are faulty and replace them within the same |
1099 |
node. The ``--auto`` option works only when an instance has only |
1100 |
faulty disks on either the primary or secondary node; it doesn't work |
1101 |
when both sides have faulty disks. |
1102 |
|
1103 |
The ``--submit`` option is used to send the job to the master daemon |
1104 |
but not wait for its completion. The job ID will be shown so that it |
1105 |
can be examined via **gnt-job info**. |
1106 |
|
1107 |
The ``--early-release`` changes the code so that the old storage on |
1108 |
secondary node(s) is removed early (before the resync is completed) |
1109 |
and the internal Ganeti locks for the current (and new, if any) |
1110 |
secondary node are also released, thus allowing more parallelism in |
1111 |
the cluster operation. This should be used only when recovering from a |
1112 |
disk failure on the current secondary (thus the old storage is already |
1113 |
broken) or when the storage on the primary node is known to be fine |
1114 |
(thus we won't need the old storage for potential recovery). |
1115 |
|
1116 |
Note that it is not possible to select an offline or drained node as a |
1117 |
new secondary. |
1118 |
|
1119 |
ACTIVATE-DISKS |
1120 |
^^^^^^^^^^^^^^ |
1121 |
|
1122 |
**activate-disks** [--submit] [--ignore-size] {*instance*} |
1123 |
|
1124 |
Activates the block devices of the given instance. If successful, the |
1125 |
command will show the location and name of the block devices:: |
1126 |
|
1127 |
node1.example.com:disk/0:/dev/drbd0 |
1128 |
node1.example.com:disk/1:/dev/drbd1 |
1129 |
|
1130 |
|
1131 |
In this example, *node1.example.com* is the name of the node on which |
1132 |
the devices have been activated. The *disk/0* and *disk/1* are the |
1133 |
Ganeti-names of the instance disks; how they are visible inside the |
1134 |
instance is hypervisor-specific. */dev/drbd0* and */dev/drbd1* are the |
1135 |
actual block devices as visible on the node. The ``--submit`` option |
1136 |
is used to send the job to the master daemon but not wait for its |
1137 |
completion. The job ID will be shown so that it can be examined via |
1138 |
**gnt-job info**. |
1139 |
|
1140 |
The ``--ignore-size`` option can be used to activate disks ignoring |
1141 |
the currently configured size in Ganeti. This can be used in cases |
1142 |
where the configuration has gotten out of sync with the real-world |
1143 |
(e.g. after a partially-failed grow-disk operation or due to rounding |
1144 |
in LVM devices). This should not be used in normal cases, but only |
1145 |
when activate-disks fails without it. |
1146 |
|
1147 |
Note that it is safe to run this command while the instance is already |
1148 |
running. |
1149 |
|
1150 |
DEACTIVATE-DISKS |
1151 |
^^^^^^^^^^^^^^^^ |
1152 |
|
1153 |
**deactivate-disks** [-f] [--submit] {*instance*} |
1154 |
|
1155 |
De-activates the block devices of the given instance. Note that if you |
1156 |
run this command for an instance with a drbd disk template, while it |
1157 |
is running, it will not be able to shutdown the block devices on the |
1158 |
primary node, but it will shutdown the block devices on the secondary |
1159 |
nodes, thus breaking the replication. |
1160 |
|
1161 |
The ``-f``/``--force`` option will skip checks that the instance is |
1162 |
down; in case the hypervisor is confused and we can't talk to it, |
1163 |
normally Ganeti will refuse to deactivate the disks, but with this |
1164 |
option passed it will skip this check and directly try to deactivate |
1165 |
the disks. This can still fail due to the instance actually running or |
1166 |
other issues. |
1167 |
|
1168 |
The ``--submit`` option is used to send the job to the master daemon |
1169 |
but not wait for its completion. The job ID will be shown so that it |
1170 |
can be examined via **gnt-job info**. |
1171 |
|
1172 |
GROW-DISK |
1173 |
^^^^^^^^^ |
1174 |
|
1175 |
**grow-disk** [--no-wait-for-sync] [--submit] {*instance*} {*disk*} |
1176 |
{*amount*} |
1177 |
|
1178 |
Grows an instance's disk. This is only possible for instances having a |
1179 |
plain or drbd disk template. |
1180 |
|
1181 |
Note that this command only change the block device size; it will not |
1182 |
grow the actual filesystems, partitions, etc. that live on that |
1183 |
disk. Usually, you will need to: |
1184 |
|
1185 |
#. use **gnt-instance grow-disk** |
1186 |
|
1187 |
#. reboot the instance (later, at a convenient time) |
1188 |
|
1189 |
#. use a filesystem resizer, such as ext2online(8) or |
1190 |
xfs\_growfs(8) to resize the filesystem, or use fdisk(8) to change |
1191 |
the partition table on the disk |
1192 |
|
1193 |
The *disk* argument is the index of the instance disk to grow. The |
1194 |
*amount* argument is given either as a number (and it represents the |
1195 |
amount to increase the disk with in mebibytes) or can be given similar |
1196 |
to the arguments in the create instance operation, with a suffix |
1197 |
denoting the unit. |
1198 |
|
1199 |
Note that the disk grow operation might complete on one node but fail |
1200 |
on the other; this will leave the instance with different-sized LVs on |
1201 |
the two nodes, but this will not create problems (except for unused |
1202 |
space). |
1203 |
|
1204 |
If you do not want gnt-instance to wait for the new disk region to be |
1205 |
synced, use the ``--no-wait-for-sync`` option. |
1206 |
|
1207 |
The ``--submit`` option is used to send the job to the master daemon |
1208 |
but not wait for its completion. The job ID will be shown so that it |
1209 |
can be examined via **gnt-job info**. |
1210 |
|
1211 |
Example (increase the first disk for instance1 by 16GiB):: |
1212 |
|
1213 |
# gnt-instance grow-disk instance1.example.com 0 16g |
1214 |
|
1215 |
|
1216 |
Also note that disk shrinking is not supported; use **gnt-backup |
1217 |
export** and then **gnt-backup import** to reduce the disk size of an |
1218 |
instance. |
1219 |
|
1220 |
RECREATE-DISKS |
1221 |
^^^^^^^^^^^^^^ |
1222 |
|
1223 |
**recreate-disks** [--submit] [--disks=``indices``] [-n node1:[node2]] |
1224 |
{*instance*} |
1225 |
|
1226 |
Recreates the disks of the given instance, or only a subset of the |
1227 |
disks (if the option ``disks`` is passed, which must be a |
1228 |
comma-separated list of disk indices, starting from zero). |
1229 |
|
1230 |
Note that this functionality should only be used for missing disks; if |
1231 |
any of the given disks already exists, the operation will fail. While |
1232 |
this is suboptimal, recreate-disks should hopefully not be needed in |
1233 |
normal operation and as such the impact of this is low. |
1234 |
|
1235 |
Optionally the instance's disks can be recreated on different |
1236 |
nodes. This can be useful if, for example, the original nodes of the |
1237 |
instance have gone down (and are marked offline), so we can't recreate |
1238 |
on the same nodes. To do this, pass the new node(s) via ``-n`` option, |
1239 |
with a syntax similar to the **add** command. The number of nodes |
1240 |
passed must equal the number of nodes that the instance currently |
1241 |
has. Note that changing nodes is only allowed for 'all disk' |
1242 |
replacement (when ``--disks`` is not passed). |
1243 |
|
1244 |
The ``--submit`` option is used to send the job to the master daemon |
1245 |
but not wait for its completion. The job ID will be shown so that it |
1246 |
can be examined via **gnt-job info**. |
1247 |
|
1248 |
Recovery |
1249 |
~~~~~~~~ |
1250 |
|
1251 |
FAILOVER |
1252 |
^^^^^^^^ |
1253 |
|
1254 |
**failover** [-f] [--ignore-consistency] [--shutdown-timeout=*N*] |
1255 |
[--submit] {*instance*} |
1256 |
|
1257 |
Failover will fail the instance over its secondary node. This works |
1258 |
only for instances having a drbd disk template. |
1259 |
|
1260 |
Normally the failover will check the consistency of the disks before |
1261 |
failing over the instance. If you are trying to migrate instances off |
1262 |
a dead node, this will fail. Use the ``--ignore-consistency`` option |
1263 |
for this purpose. Note that this option can be dangerous as errors in |
1264 |
shutting down the instance will be ignored, resulting in possibly |
1265 |
having the instance running on two machines in parallel (on |
1266 |
disconnected DRBD drives). |
1267 |
|
1268 |
The ``--shutdown-timeout`` is used to specify how much time to wait |
1269 |
before forcing the shutdown (xm destroy in xen, killing the kvm |
1270 |
process, for kvm). By default two minutes are given to each instance |
1271 |
to stop. |
1272 |
|
1273 |
The ``--submit`` option is used to send the job to the master daemon |
1274 |
but not wait for its completion. The job ID will be shown so that it |
1275 |
can be examined via **gnt-job info**. |
1276 |
|
1277 |
Example:: |
1278 |
|
1279 |
# gnt-instance failover instance1.example.com |
1280 |
|
1281 |
|
1282 |
MIGRATE |
1283 |
^^^^^^^ |
1284 |
|
1285 |
**migrate** [-f] {--cleanup} {*instance*} |
1286 |
|
1287 |
**migrate** [-f] [--allow-failover] [--non-live] |
1288 |
[--migration-mode=live\|non-live] {*instance*} |
1289 |
|
1290 |
Migrate will move the instance to its secondary node without |
1291 |
shutdown. It only works for instances having the drbd8 disk template |
1292 |
type. |
1293 |
|
1294 |
The migration command needs a perfectly healthy instance, as we rely |
1295 |
on the dual-master capability of drbd8 and the disks of the instance |
1296 |
are not allowed to be degraded. |
1297 |
|
1298 |
The ``--non-live`` and ``--migration-mode=non-live`` options will |
1299 |
switch (for the hypervisors that support it) between a "fully live" |
1300 |
(i.e. the interruption is as minimal as possible) migration and one in |
1301 |
which the instance is frozen, its state saved and transported to the |
1302 |
remote node, and then resumed there. This all depends on the |
1303 |
hypervisor support for two different methods. In any case, it is not |
1304 |
an error to pass this parameter (it will just be ignored if the |
1305 |
hypervisor doesn't support it). The option ``--migration-mode=live`` |
1306 |
option will request a fully-live migration. The default, when neither |
1307 |
option is passed, depends on the hypervisor parameters (and can be |
1308 |
viewed with the **gnt-cluster info** command). |
1309 |
|
1310 |
If the ``--cleanup`` option is passed, the operation changes from |
1311 |
migration to attempting recovery from a failed previous migration. In |
1312 |
this mode, Ganeti checks if the instance runs on the correct node (and |
1313 |
updates its configuration if not) and ensures the instances's disks |
1314 |
are configured correctly. In this mode, the ``--non-live`` option is |
1315 |
ignored. |
1316 |
|
1317 |
The option ``-f`` will skip the prompting for confirmation. |
1318 |
|
1319 |
If ``--allow-failover`` is specified it tries to fallback to failover if |
1320 |
it already can determine that a migration wont work (i.e. if the |
1321 |
instance is shutdown). Please note that the fallback will not happen |
1322 |
during execution. If a migration fails during execution it still fails. |
1323 |
|
1324 |
Example (and expected output):: |
1325 |
|
1326 |
# gnt-instance migrate instance1 |
1327 |
Migrate will happen to the instance instance1. Note that migration is |
1328 |
**experimental** in this version. This might impact the instance if |
1329 |
anything goes wrong. Continue? |
1330 |
y/[n]/?: y |
1331 |
* checking disk consistency between source and target |
1332 |
* ensuring the target is in secondary mode |
1333 |
* changing disks into dual-master mode |
1334 |
- INFO: Waiting for instance instance1 to sync disks. |
1335 |
- INFO: Instance instance1's disks are in sync. |
1336 |
* migrating instance to node2.example.com |
1337 |
* changing the instance's disks on source node to secondary |
1338 |
- INFO: Waiting for instance instance1 to sync disks. |
1339 |
- INFO: Instance instance1's disks are in sync. |
1340 |
* changing the instance's disks to single-master |
1341 |
# |
1342 |
|
1343 |
|
1344 |
MOVE |
1345 |
^^^^ |
1346 |
|
1347 |
**move** [-f] [--ignore-consistency] |
1348 |
[-n *node*] [--shutdown-timeout=*N*] [--submit] |
1349 |
{*instance*} |
1350 |
|
1351 |
Move will move the instance to an arbitrary node in the cluster. This |
1352 |
works only for instances having a plain or file disk template. |
1353 |
|
1354 |
Note that since this operation is done via data copy, it will take a |
1355 |
long time for big disks (similar to replace-disks for a drbd |
1356 |
instance). |
1357 |
|
1358 |
The ``--shutdown-timeout`` is used to specify how much time to wait |
1359 |
before forcing the shutdown (e.g. ``xm destroy`` in XEN, killing the |
1360 |
kvm process for KVM, etc.). By default two minutes are given to each |
1361 |
instance to stop. |
1362 |
|
1363 |
The ``--ignore-consistency`` option will make Ganeti ignore any errors |
1364 |
in trying to shutdown the instance on its node; useful if the |
1365 |
hypervisor is broken and you want to recuperate the data. |
1366 |
|
1367 |
The ``--submit`` option is used to send the job to the master daemon |
1368 |
but not wait for its completion. The job ID will be shown so that it |
1369 |
can be examined via **gnt-job info**. |
1370 |
|
1371 |
Example:: |
1372 |
|
1373 |
# gnt-instance move -n node3.example.com instance1.example.com |
1374 |
|
1375 |
|
1376 |
TAGS |
1377 |
~~~~ |
1378 |
|
1379 |
ADD-TAGS |
1380 |
^^^^^^^^ |
1381 |
|
1382 |
**add-tags** [--from *file*] {*instancename*} {*tag*...} |
1383 |
|
1384 |
Add tags to the given instance. If any of the tags contains invalid |
1385 |
characters, the entire operation will abort. |
1386 |
|
1387 |
If the ``--from`` option is given, the list of tags will be extended |
1388 |
with the contents of that file (each line becomes a tag). In this |
1389 |
case, there is not need to pass tags on the command line (if you do, |
1390 |
both sources will be used). A file name of ``-`` will be interpreted |
1391 |
as stdin. |
1392 |
|
1393 |
LIST-TAGS |
1394 |
^^^^^^^^^ |
1395 |
|
1396 |
**list-tags** {*instancename*} |
1397 |
|
1398 |
List the tags of the given instance. |
1399 |
|
1400 |
REMOVE-TAGS |
1401 |
^^^^^^^^^^^ |
1402 |
|
1403 |
**remove-tags** [--from *file*] {*instancename*} {*tag*...} |
1404 |
|
1405 |
Remove tags from the given instance. If any of the tags are not |
1406 |
existing on the node, the entire operation will abort. |
1407 |
|
1408 |
If the ``--from`` option is given, the list of tags to be removed will |
1409 |
be extended with the contents of that file (each line becomes a tag). |
1410 |
In this case, there is not need to pass tags on the command line (if |
1411 |
you do, tags from both sources will be removed). A file name of ``-`` |
1412 |
will be interpreted as stdin. |
1413 |
|
1414 |
.. vim: set textwidth=72 : |
1415 |
.. Local Variables: |
1416 |
.. mode: rst |
1417 |
.. fill-column: 72 |
1418 |
.. End: |