X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/13ddcb505250163c77b967950fa5c3d659ff1e3b..f5720846bac577abfa565b6ab1c75871da562c65:/man/gnt-instance.rst diff --git a/man/gnt-instance.rst b/man/gnt-instance.rst index c38c553..9c7c2a6 100644 --- a/man/gnt-instance.rst +++ b/man/gnt-instance.rst @@ -84,7 +84,7 @@ the resolver (e.g. in DNS or /etc/hosts, depending on your setup). Since the name check is used to compute the IP address, if you pass this option you must also pass the ``--no-ip-check`` option. -If you don't wat the instance to automatically start after +If you don't want the instance to automatically start after creation, this is possible via the ``--no-start`` option. This will leave the instance down until a subsequent **gnt-instance start** command. @@ -190,9 +190,11 @@ boot\_order as 'dc'. For KVM the boot order is either "floppy", "cdrom", "disk" or - "network". Please note that older versions of KVM couldn't - netboot from virtio interfaces. This has been fixed in more recent - versions and is confirmed to work at least with qemu-kvm 0.11.1. + "network". Please note that older versions of KVM couldn't netboot + from virtio interfaces. This has been fixed in more recent versions + and is confirmed to work at least with qemu-kvm 0.11.1. Also note + that if you have set the ``kernel_path`` option, that will be used + for booting, and this setting will be silently ignored. blockdev\_prefix Valid for the Xen HVM and PVM hypervisors. @@ -256,7 +258,7 @@ cdrom\_disk\_type This parameter determines the way the cdroms disks are presented to the instance. The default behavior is to get the same value of - the eariler parameter (disk_type). The possible options are: + the earlier parameter (disk_type). The possible options are: - paravirtual - ide @@ -411,9 +413,10 @@ kernel\_path Valid for the Xen PVM and KVM hypervisors. This option specifies the path (on the node) to the kernel to boot - the instance with. Xen PVM instances always require this, while - for KVM if this option is empty, it will cause the machine to load - the kernel from its disks. + the instance with. Xen PVM instances always require this, while for + KVM if this option is empty, it will cause the machine to load the + kernel from its disks (and the boot will be done accordingly to + ``boot_order``). kernel\_args Valid for the Xen PVM and KVM hypervisors. @@ -506,7 +509,7 @@ mem\_path use\_chroot Valid for the KVM hypervisor. - This boolean option determines wether to run the KVM instance in a + This boolean option determines whether to run the KVM instance in a chroot directory. If it is set to ``true``, an empty directory is created before @@ -527,14 +530,49 @@ migration\_downtime versions >= 0.11.0. cpu\_mask - Valid for the LXC hypervisor. + Valid for the Xen, KVM and LXC hypervisors. The processes belonging to the given instance are only scheduled on the specified CPUs. - The parameter format is a comma-separated list of CPU IDs or CPU - ID ranges. The ranges are defined by a lower and higher boundary, - separated by a dash. The boundaries are inclusive. + The format of the mask can be given in three forms. First, the word + "all", which signifies the common case where all VCPUs can live on + any CPU, based on the hypervisor's decisions. + + Second, a comma-separated list of CPU IDs or CPU ID ranges. The + ranges are defined by a lower and higher boundary, separated by a + dash, and the boundaries are inclusive. In this form, all VCPUs of + the instance will be mapped on the selected list of CPUs. Example: + ``0-2,5``, mapping all VCPUs (no matter how many) onto physical CPUs + 0, 1, 2 and 5. + + The last form is used for explicit control of VCPU-CPU pinnings. In + this form, the list of VCPU mappings is given as a colon (:) + separated list, whose elements are the possible values for the + second or first form above. In this form, the number of elements in + the colon-separated list _must_ equal the number of VCPUs of the + instance. + + Example:: + + # Map the entire instance to CPUs 0-2 + gnt-instance modify -H cpu_mask=0-2 my-inst + + # Map vCPU 0 to physical CPU 1 and vCPU 1 to CPU 3 (assuming 2 vCPUs) + gnt-instance modify -H cpu_mask=1:3 my-inst + + # Pin vCPU 0 to CPUs 1 or 2, and vCPU 1 to any CPU + gnt-instance modify -H cpu_mask=1-2:all my-inst + + # Pin vCPU 0 to any CPU, vCPU 1 to CPUs 1, 3, 4 or 5, and CPU 2 to + # CPU 0 (backslashes for escaping the comma) + gnt-instance modify -H cpu_mask=all:1\\,3-5:0 my-inst + + # Pin entire VM to CPU 0 + gnt-instance modify -H cpu_mask=0 my-inst + + # Turn off CPU pinning (default setting) + gnt-instance modify -H cpu_mask=all my-inst usb\_mouse Valid for the KVM hypervisor. @@ -677,7 +715,7 @@ hypervisor mac, ip, mode, link Specifications for the one NIC that will be created for the - instance. 'bridge' is also accepted as a backwards compatibile + instance. 'bridge' is also accepted as a backwards compatible key. nics @@ -858,8 +896,8 @@ MODIFY | [{-H|\--hypervisor-parameters} *HYPERVISOR\_PARAMETERS*] | [{-B|\--backend-parameters} *BACKEND\_PARAMETERS*] | [{-m|\--runtime-memory} *SIZE*] -| [\--net add*[:options]* \| \--net remove \| \--net *N:options*] -| [\--disk add:size=*SIZE*[,vg=*VG*][,metavg=*VG*] \| \--disk remove \| +| [\--net add*[:options]* \| \--net [*N*:]remove \| \--net *N:options*] +| [\--disk add:size=*SIZE*[,vg=*VG*][,metavg=*VG*] \| \--disk [*N*:]remove \| | \--disk *N*:mode=*MODE*] | [{-t|\--disk-template} plain | {-t|\--disk-template} drbd -n *new_secondary*] [\--no-wait-for-sync] | [\--os-type=*OS* [\--force-variant]] @@ -898,7 +936,7 @@ the default volume group to create the disk on. For DRBD disks, the ``metavg=``*VG* option specifies the volume group for the metadata device. ``--disk`` *N*``:add,size=``**SIZE** can be used to add a disk at a specific index. The ``--disk remove`` option will remove the -last disk of the instance. Use ``--disk ``*N*``:remove`` to remove a +last disk of the instance. Use ``--disk `` *N*``:remove`` to remove a disk by its index. The ``--disk`` *N*``:mode=``*MODE* option will change the mode of the Nth disk of the instance between read-only (``ro``) and read-write (``rw``). @@ -1050,7 +1088,7 @@ case the more than one instance will be affected. The ``--no-remember`` option will perform the startup but not change the state of the instance in the configuration file (if it was stopped -before, Ganeti will still thinks it needs to be stopped). This can be +before, Ganeti will still think it needs to be stopped). This can be used for testing, or for a one shot-start where you don't want the watcher to restart the instance if it crashes. @@ -1215,10 +1253,10 @@ REPLACE-DISKS [\--disks *idx*] {*instance*} **replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy] -{\--iallocator *name* \| \--node *node* } {*instance*} +{{-I\|\--iallocator} *name* \| {{-n|\--new-secondary} *node* } {*instance*} **replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy] -{\--auto} {*instance*} +{-a\|\--auto} {*instance*} This command is a generalized form for replacing disks. It is currently only valid for the mirrored (DRBD) disk template. @@ -1318,8 +1356,8 @@ options. GROW-DISK ^^^^^^^^^ -| **grow-disk** [\--no-wait-for-sync] [\--submit] {*instance*} {*disk*} -| {*amount*} +| **grow-disk** [\--no-wait-for-sync] [\--submit] [\--absolute] +| {*instance*} {*disk*} {*amount*} Grows an instance's disk. This is only possible for instances having a plain, drbd or rbd disk template. @@ -1337,10 +1375,15 @@ disk. Usually, you will need to: the partition table on the disk The *disk* argument is the index of the instance disk to grow. The -*amount* argument is given either as a number (and it represents the -amount to increase the disk with in mebibytes) or can be given similar -to the arguments in the create instance operation, with a suffix -denoting the unit. +*amount* argument is given as a number which can have a suffix (like the +disk size in instance create); if the suffix is missing, the value will +be interpreted as mebibytes. + +By default, the *amount* value represents the desired increase in the +disk size (e.g. an amount of 1G will take a disk of size 3G to 4G). If +the optional ``--absolute`` parameter is passed, then the *amount* +argument doesn't represent the delta, but instead the desired final disk +size (e.g. an amount of 8G will take a disk of size 4G to 8G). For instances with a drbd template, note that the disk grow operation might complete on one node but fail on the other; this will leave the @@ -1357,6 +1400,9 @@ Example (increase the first disk for instance1 by 16GiB):: # gnt-instance grow-disk instance1.example.com 0 16g +Example for increasing the disk size to a certain size:: + + # gnt-instance grow-disk --absolute instance1.example.com 0 32g Also note that disk shrinking is not supported; use **gnt-backup export** and then **gnt-backup import** to reduce the disk size of an @@ -1446,12 +1492,12 @@ Example:: MIGRATE ^^^^^^^ -**migrate** [-f] {\--cleanup} {*instance*} +| **migrate** [-f] [\--allow-failover] [\--non-live] +| [\--migration-mode=live\|non-live] [\--ignore-ipolicy] +| [\--no-runtime-changes] [\--submit] +| [{-n|\--target-node} *node* \| {-I|\--iallocator} *name*] {*instance*} -**migrate** [-f] [\--allow-failover] [\--non-live] -[\--migration-mode=live\|non-live] [\--ignore-ipolicy] -[\--no-runtime-changes] -[{-n|\--target-node} *node* \| {-I|\--iallocator} *name*] {*instance*} +| **migrate** [-f] \--cleanup [\--submit] {*instance*} Migrate will move the instance to its secondary node without shutdown. As with failover, it only works for instances having the drbd disk @@ -1483,7 +1529,7 @@ viewed with the **gnt-cluster info** command). If the ``--cleanup`` option is passed, the operation changes from migration to attempting recovery from a failed previous migration. In this mode, Ganeti checks if the instance runs on the correct node (and -updates its configuration if not) and ensures the instances's disks +updates its configuration if not) and ensures the instances' disks are configured correctly. In this mode, the ``--non-live`` option is ignored. @@ -1501,6 +1547,12 @@ The ``--no-runtime-changes`` option forbids migrate to alter an instance's runtime before migrating it (eg. ballooning an instance down because the target node doesn't have enough available memory). +If an instance has the backend parameter ``always\_failover`` set to +true, then the migration is automatically converted into a failover. + +See **ganeti(7)** for a description of ``--submit`` and other common +options. + Example (and expected output):: # gnt-instance migrate instance1 @@ -1562,7 +1614,8 @@ Example:: CHANGE-GROUP ~~~~~~~~~~~~ -**change-group** [\--iallocator *NAME*] [\--to *GROUP*...] {*instance*} +| **change-group** [\--submit] +| [\--iallocator *NAME*] [\--to *GROUP*...] {*instance*} This command moves an instance to another node group. The move is calculated by an iallocator, either given on the command line or as a @@ -1571,6 +1624,9 @@ cluster default. If no specific destination groups are specified using ``--to``, all groups except the one containing the instance are considered. +See **ganeti(7)** for a description of ``--submit`` and other common +options. + Example:: # gnt-instance change-group -I hail --to rack2 inst1.example.com