X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/f70bb622cb36fd7626c44b92726d3eb181071980..107102afa6161982c9c9a5c69378e7773b002367:/man/gnt-instance.rst diff --git a/man/gnt-instance.rst b/man/gnt-instance.rst index fbfeef3..c08ea4f 100644 --- a/man/gnt-instance.rst +++ b/man/gnt-instance.rst @@ -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. @@ -385,6 +387,19 @@ spice\_use\_vdagent Enables or disables passing mouse events via SPICE vdagent. +cpu\_type + Valid for the KVM hypervisor. + + This parameter determines the emulated cpu for the instance. If this + parameter is empty (which is the default configuration), it will not + be passed to KVM. + + Be aware of setting this parameter to ``"host"`` if you have nodes + with different CPUs from each other. Live migration may stop working + in this situation. + + For more information please refer to the KVM manual. + acpi Valid for the Xen HVM and KVM hypervisors. @@ -411,9 +426,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. @@ -527,14 +543,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. @@ -898,7 +949,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``). @@ -1215,7 +1266,7 @@ REPLACE-DISKS [\--disks *idx*] {*instance*} **replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy] -{\--iallocator *name* \| \--node *node* } {*instance*} +{{-I\|\--iallocator} *name* \| \--node *node* } {*instance*} **replace-disks** [\--submit] [\--early-release] [\--ignore-ipolicy] {\--auto} {*instance*} @@ -1266,7 +1317,7 @@ options. ACTIVATE-DISKS ^^^^^^^^^^^^^^ -**activate-disks** [\--submit] [\--ignore-size] {*instance*} +**activate-disks** [\--submit] [\--ignore-size] [\--wait-for-sync] {*instance*} Activates the block devices of the given instance. If successful, the command will show the location and name of the block devices:: @@ -1288,6 +1339,13 @@ where the configuration has gotten out of sync with the real-world in LVM devices). This should not be used in normal cases, but only when activate-disks fails without it. +The ``--wait-for-sync`` option will ensure that the command returns only +after the instance's disks are synchronised (mostly for DRBD); this can +be useful to ensure consistency, as otherwise there are no commands that +can wait until synchronisation is done. However when passing this +option, the command will have additional output, making it harder to +parse the disk information. + Note that it is safe to run this command while the instance is already running. @@ -1318,8 +1376,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 +1395,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 +1420,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 @@ -1365,7 +1431,8 @@ instance. RECREATE-DISKS ^^^^^^^^^^^^^^ -| **recreate-disks** [\--submit] [-n node1:[node2]] +| **recreate-disks** [\--submit] +| [{-n node1:[node2] \| {-I\|\--iallocator *name*}}] | [\--disk=*N*[:[size=*VAL*][,mode=*ro\|rw*]]] {*instance*} Recreates all or a subset of disks of the given instance. @@ -1391,6 +1458,11 @@ passed must equal the number of nodes that the instance currently has. Note that changing nodes is only allowed when all disks are replaced, e.g. when no ``--disk`` option is passed. +Another method of chosing which nodes to place the instance on is by +using the specified iallocator, passing the ``--iallocator`` option. +The primary and secondary nodes will be chosen by the specified +iallocator plugin. + See **ganeti(7)** for a description of ``--submit`` and other common options.