DaanHoogland commented on a change in pull request #85: [WIP] Backup & Recovery Doc Guide URL: https://github.com/apache/cloudstack-documentation/pull/85#discussion_r386388504
########## File path: source/adminguide/virtual_machines.rst ########## @@ -801,236 +537,390 @@ following conditions: To manually live migrate a virtual machine -#. Log in to the CloudStack UI as a user or admin. +#. Log in to the CloudStack UI as a user or admin. + +#. In the left navigation, click Instances. + +#. Choose the VM that you want to migrate. + +#. Click the Migrate Instance button. |Migrateinstance.png| + +#. From the list of suitable hosts, choose the one to which you want to + move the VM. + + .. note:: + If the VM's storage has to be migrated along with the VM, this will + be noted in the host list. CloudStack will take care of the storage + migration for you. + +#. Click OK. + +.. note:: + (KVM) If the VM's storage has to be migrated along with the VM, from a mounted NFS storage pool to a cluster-wide mounted NFS storage pool, then the 'migrateVirtualMachineWithVolume' API has to be used. There is no UI integration for this feature. + + (CloudMonkey) > migrate virtualmachinewithvolume virtualmachineid=<virtual machine uuid> hostid=<destination host uuid> migrateto[i].volume=<virtual machine volume number i uuid> migrateto[i].pool=<destination storage pool uuid for volume number i> + + where i in [0,..,N] and N = number of volumes of the virtual machine + + + +Assigning VMs to Hosts +---------------------- + +At any point in time, each virtual machine instance is running on a +single host. How does CloudStack determine which host to place a VM on? +There are several ways: + +- Automatic default host allocation. CloudStack can automatically pick + the most appropriate host to run each virtual machine. + +- Instance type preferences. CloudStack administrators can specify that + certain hosts should have a preference for particular types of guest + instances. For example, an administrator could state that a host + should have a preference to run Windows guests. The default host + allocator will attempt to place guests of that OS type on such hosts + first. If no such host is available, the allocator will place the + instance wherever there is sufficient physical capacity. + +- Vertical and horizontal allocation. Vertical allocation consumes all + the resources of a given host before allocating any guests on a + second host. This reduces power consumption in the cloud. Horizontal + allocation places a guest on each host in a round-robin fashion. This + may yield better performance to the guests in some cases. + +- Admin users preferences. Administrators have the option to specify a + pod, cluster, or host to run the VM in. CloudStack will then select + a host within the given infrastructure. + +- End user preferences. Users can not control exactly which host will + run a given VM instance, but they can specify a zone for the VM. + CloudStack is then restricted to allocating the VM only to one of the + hosts in that zone. + +- Host tags. The administrator can assign tags to hosts. These tags can + be used to specify which host a VM should use. The CloudStack + administrator decides whether to define host tags, then create a + service offering using those tags and offer it to the user. + +- Affinity groups. By defining affinity groups and assigning VMs to + them, the user or administrator can influence (but not dictate) which + VMs should run on separate hosts. This feature is to let users + specify that certain VMs won't be on the same host. + +- CloudStack also provides a pluggable interface for adding new + allocators. These custom allocators can provide any policy the + administrator desires. + + +Affinity Groups +~~~~~~~~~~~~~~~ + +By defining affinity groups and assigning VMs to them, the user or +administrator can influence (but not dictate) which VMs should run on +separate hosts. This feature is to let users specify that VMs with the +same “host anti-affinity” type won’t be on the same host. This serves to +increase fault tolerance. If a host fails, another VM offering the same +service (for example, hosting the user's website) is still up and +running on another host. + +The scope of an affinity group is per user account. + + +Creating a New Affinity Group +''''''''''''''''''''''''''''' + +To add an affinity group: + +#. Log in to the CloudStack UI as an administrator or user. + +#. In the left navigation bar, click Affinity Groups. + +#. Click Add affinity group. In the dialog box, fill in the following + fields: + + - Name. Give the group a name. + + - Description. Any desired text to tell more about the purpose of + the group. + + - Type. The only supported type shipped with CloudStack is Host + Anti-Affinity. This indicates that the VMs in this group should + avoid being placed on the same host with each other. If you see + other types in this list, it means that your installation of + CloudStack has been extended with customized affinity group + plugins. + + +Assign a New VM to an Affinity Group +'''''''''''''''''''''''''''''''''''' + +To assign a new VM to an affinity group: + +- Create the VM as usual, as described in `“Creating + VMs” <virtual_machines.html#creating-vms>`_. In the Add Instance + wizard, there is a new Affinity tab where you can select the + affinity group. + + +Change Affinity Group for an Existing VM +'''''''''''''''''''''''''''''''''''''''' + +To assign an existing VM to an affinity group: + +#. Log in to the CloudStack UI as an administrator or user. -#. In the left navigation, click Instances. +#. In the left navigation bar, click Instances. -#. Choose the VM that you want to migrate. +#. Click the name of the VM you want to work with. -#. Click the Migrate Instance button. |Migrateinstance.png| +#. Stop the VM by clicking the Stop button. -#. From the list of suitable hosts, choose the one to which you want to - move the VM. +#. Click the Change Affinity button. |change-affinity-button.png| - .. note:: - If the VM's storage has to be migrated along with the VM, this will - be noted in the host list. CloudStack will take care of the storage - migration for you. -#. Click OK. +View Members of an Affinity Group +''''''''''''''''''''''''''''''''' -.. note:: - (KVM) If the VM's storage has to be migrated along with the VM, from a mounted NFS storage pool to a cluster-wide mounted NFS storage pool, then the 'migrateVirtualMachineWithVolume' API has to be used. There is no UI integration for this feature. +To see which VMs are currently assigned to a particular affinity group: - (CloudMonkey) > migrate virtualmachinewithvolume virtualmachineid=<virtual machine uuid> hostid=<destination host uuid> migrateto[i].volume=<virtual machine volume number i uuid> migrateto[i].pool=<destination storage pool uuid for volume number i> +#. In the left navigation bar, click Affinity Groups. - where i in [0,..,N] and N = number of volumes of the virtual machine +#. Click the name of the group you are interested in. +#. Click View Instances. The members of the group are listed. -Deleting VMs ------------- + From here, you can click the name of any VM in the list to access all + its details and controls. -Users can delete their own virtual machines. A running virtual machine -will be abruptly stopped before it is deleted. Administrators can delete -any virtual machines. -To delete a virtual machine: +Delete an Affinity Group +'''''''''''''''''''''''' -#. Log in to the CloudStack UI as a user or admin. +To delete an affinity group: -#. In the left navigation, click Instances. +#. In the left navigation bar, click Affinity Groups. -#. Choose the VM that you want to delete. +#. Click the name of the group you are interested in. -#. Click the Destroy Instance button. |Destroyinstance.png| +#. Click Delete. -#. Optionally both expunging and the deletion of any attached volumes can be enabled. + Any VM that is a member of the affinity group will be disassociated + from the group. The former group members will continue to run + normally on the current hosts, but if the VM is restarted, it will no + longer follow the host allocation rules from its former affinity + group. -Working with ISOs ------------------ +Changing a VM's Base Image +---------------------------- -CloudStack supports ISOs and their attachment to guest VMs. An ISO is a -read-only file that has an ISO/CD-ROM style file system. Users can -upload their own ISOs and mount them on their guest VMs. +Every VM is created from a base image, which is a template or ISO which +has been created and stored in CloudStack. Both cloud administrators and +end users can create and modify templates, ISOs, and VMs. -ISOs are uploaded based on a URL. HTTP is the supported protocol. Once -the ISO is available via HTTP specify an upload URL such as -http://my.web.server/filename.iso. +In CloudStack, you can change an existing VM's base image from one +template to another, or from one ISO to another. (You can not change +from an ISO to a template, or from a template to an ISO). -ISOs may be public or private, like templates.ISOs are not -hypervisor-specific. That is, a guest on vSphere can mount the exact -same image that a guest on KVM can mount. +For example, suppose there is a template based on a particular operating +system, and the OS vendor releases a software patch. The administrator +or user naturally wants to apply the patch and then make sure existing +VMs start using it. Whether a software update is involved or not, it's +also possible to simply switch a VM from its current template to any +other desired template. -ISO images may be stored in the system and made available with a privacy -level similar to templates. ISO images are classified as either bootable -or not bootable. A bootable ISO image is one that contains an OS image. -CloudStack allows a user to boot a guest VM off of an ISO image. Users -can also attach ISO images to guest VMs. For example, this enables -installing PV drivers into Windows. ISO images are not -hypervisor-specific. +To change a VM's base image, call the restoreVirtualMachine API command +and pass in the virtual machine ID and a new template ID. The template +ID parameter may refer to either a template or an ISO, depending on +which type of base image the VM was already using (it must match the +previous type of image). When this call occurs, the VM's root disk is +first destroyed, then a new root disk is created from the source +designated in the template ID parameter. The new root disk is attached +to the VM, and now the VM is based on the new template. +You can also omit the template ID parameter from the +restoreVirtualMachine call. In this case, the VM's root disk is +destroyed and recreated, but from the same template or ISO that was +already in use by the VM. -Adding an ISO -~~~~~~~~~~~~~ -To make additional operating system or other software available for use -with guest VMs, you can add an ISO. The ISO is typically thought of as -an operating system image, but you can also add ISOs for other types of -software, such as desktop applications that you want to be installed as -part of a template. +Advanced VM Instance Settings +------------------------------- -#. Log in to the CloudStack UI as an administrator or end user. +Each user VM has a set of "details" associated with it (as visible via listVirtualMachine API call) - those "details" are shown on the "Settings" tab of the VM in the GUI (words "setting(s)" and "detail(s)" are here used interchangeably). -#. In the left navigation bar, click Templates. +The Settings tab is always present/visible, but settings can be changed only when the VM is in a Stopped state. +Some VM details/settings can be hidden via "user.vm.blacklisted.details" global setting (you can find below the list of those hidden by default). -#. In Select View, choose ISOs. +When adding a new setting or modifying the existing ones, setting names are shown/offered in a drop-down list, as well as their possible values (with the exception of boolean or numerical values). -#. Click Add ISO. +Read-only details/settings that are hidden by default: -#. In the Add ISO screen, provide the following: +- rootdisksize +- cpuOvercommitRatio +- memoryOvercommitRatio +- Message.ReservedCapacityFreed.Flag - - **Name**: Short name for the ISO image. For example, CentOS 6.2 - 64-bit. +An example list of settings as well as their possible values are shown on the images below: - - **Description**: Display test for the ISO image. For example, - CentOS 6.2 64-bit. +|vm-settings-dropdown-list.PNG| +(VMware hypervisor) - - **URL**: The URL that hosts the ISO image. The Management Server - must be able to access this location via HTTP. If needed you can - place the ISO image directly on the Management Server +|vm-settings-values-dropdown-list.PNG| +(VMware disk controllers) - - **Zone**: Choose the zone where you want the ISO to be available, - or All Zones to make it available throughout CloudStack. +|vm-settings-values1-dropdown-list.PNG| +(VMware NIC models) - - **Bootable**: Whether or not a guest could boot off this ISO - image. For example, a CentOS ISO is bootable, a Microsoft Office - ISO is not bootable. +|vm-settings-values-dropdown-KVM-list.PNG| +(KVM disk controllers) - - **OS Type**: This helps CloudStack and the hypervisor perform - certain operations and make assumptions that improve the - performance of the guest. Select one of the following. - - If the operating system of your desired ISO image is listed, - choose it. +Virtual Machine Snapshots +========================== - - If the OS Type of the ISO is not listed or if the ISO is not - bootable, choose Other. +(Supported on VMware, XenServer and KVM (NFS only)) - - (XenServer only) If you want to boot from this ISO in PV mode, - choose Other PV (32-bit) or Other PV (64-bit) +In addition to the existing CloudStack ability to snapshot individual VM +volumes, you can take a VM snapshot to preserve all the VM's data +volumes as well as (optionally) its CPU/memory state. This is useful for +quick restore of a VM. For example, you can snapshot a VM, then make +changes such as software upgrades. If anything goes wrong, simply +restore the VM to its previous state using the previously saved VM +snapshot. - - (KVM only) If you choose an OS that is PV-enabled, the VMs - created from this ISO will have a SCSI (virtio) root disk. If - the OS is not PV-enabled, the VMs will have an IDE root disk. - The PV-enabled types are: +The snapshot is created using the hypervisor's native snapshot facility. +The VM snapshot includes not only the data volumes, but optionally also +whether the VM is running or turned off (CPU state) and the memory +contents. The snapshot is stored in CloudStack's primary storage. - - Fedora 13 +VM snapshots can have a parent/child relationship. Each successive +snapshot of the same VM is the child of the snapshot that came before +it. Each time you take an additional snapshot of the same VM, it saves +only the differences between the current state of the VM and the state +stored in the most recent previous snapshot. The previous snapshot +becomes a parent, and the new snapshot is its child. It is possible to +create a long chain of these parent/child snapshots, which amount to a +"redo" record leading from the current state of the VM back to the +original. - - Fedora 12 +After VM snapshots are created, they can be tagged with a key/value pair, +like many other resources in CloudStack. - - Fedora 11 +KVM supports VM snapshots when using NFS shared storage. If raw block storage +is used (i.e. Ceph), then VM snapshots are not possible, since there is no possibility +to write RAM memory content anywhere. - - Fedora 10 +If you need more information about VM snapshots on VMware, check out the +VMware documentation and the VMware Knowledge Base, especially +`Understanding virtual machine snapshots +<http://kb.vmware.com/selfservice/microsites/search.do?cmd=displayKC&externalId=1015180>`_. - - Fedora 9 - - Other PV +Limitations on VM Snapshots +---------------------------- - - Debian GNU/Linux +- If a VM has some stored snapshots, you can't attach new volume to the + VM or delete any existing volumes. If you change the volumes on the + VM, it would become impossible to restore the VM snapshot which was + created with the previous volume structure. If you want to attach a + volume to such a VM, first delete its snapshots. - - CentOS 5.3 +- VM snapshots which include both data volumes and memory can't be kept + if you change the VM's service offering. Any existing VM snapshots of + this type will be discarded. - - CentOS 5.4 +- You can't make a VM snapshot at the same time as you are taking a + volume snapshot. - - CentOS 5.5 +- You should use only CloudStack to create VM snapshots on hosts + managed by CloudStack. Any snapshots that you make directly on the + hypervisor will not be tracked in CloudStack. - - Red Hat Enterprise Linux 5.3 - - Red Hat Enterprise Linux 5.4 +Configuring VM Snapshots +-------------------------- - - Red Hat Enterprise Linux 5.5 +The cloud administrator can use global configuration variables to +control the behavior of VM snapshots. To set these variables, go through +the Global Settings area of the CloudStack UI. - - Red Hat Enterprise Linux 6 +.. cssclass:: table-striped table-bordered table-hover - .. note:: - It is not recommended to choose an older version of the OS than - the version in the image. For example, choosing CentOS 5.4 to - support a CentOS 6.2 image will usually not work. In these - cases, choose Other. +====================== ======================== +Configuration Description Type +====================== ======================== +vmsnapshots.max The maximum number of VM snapshots that can be saved for any given virtual machine in the cloud. The total possible number of VM snapshots in the cloud is (number of VMs) \* vmsnapshots.max. If the number of snapshots for any VM ever hits the maximum, the older ones are removed by the snapshot expunge job +vmsnapshot.create.wait Number of seconds to wait for a snapshot job to succeed before declaring failure and issuing an error. +====================== ======================== - - **Extractable**: Choose Yes if the ISO should be available for - extraction. - - **Public**: Choose Yes if this ISO should be available to other - users. +Using VM Snapshots +-------------------- - - **Featured**: Choose Yes if you would like this ISO to be more - prominent for users to select. The ISO will appear in the Featured - ISOs list. Only an administrator can make an ISO Featured. +To create a VM snapshot using the CloudStack UI: -#. Click OK. +#. Log in to the CloudStack UI as a user or administrator. - The Management Server will download the ISO. Depending on the size of - the ISO, this may take a long time. The ISO status column will - display Ready once it has been successfully downloaded into secondary - storage. Clicking Refresh updates the download percentage. +#. Click Instances. -#. **Important**: Wait for the ISO to finish downloading. If you move on - to the next task and try to use the ISO right away, it will appear to - fail. The entire ISO must be available before CloudStack can work - with it. +#. Click the name of the VM you want to snapshot. +#. Click the Take VM Snapshot button. |VMSnapshotButton.png| -Attaching an ISO to a VM -~~~~~~~~~~~~~~~~~~~~~~~~ + .. note:: + If a snapshot is already in progress, then clicking this button + will have no effect. -#. In the left navigation, click Instances. +#. Provide a name and description. These will be displayed in the VM + Snapshots list. -#. Choose the virtual machine you want to work with. +#. (For running VMs only) If you want to include the VM's memory in the + snapshot, click the Memory checkbox. This saves the CPU and memory + state of the virtual machine. If you don't check this box, then only + the current state of the VM disk is saved. Checking this box makes + the snapshot take longer. -#. Click the Attach ISO button. |iso.png| +#. Quiesce VM: check this box if you want to quiesce the file system on + the VM before taking the snapshot. Not supported on XenServer when + used with CloudStack-provided primary storage. -#. In the Attach ISO dialog box, select the desired ISO. + When this option is used with CloudStack-provided primary storage, + the quiesce operation is performed by the underlying hypervisor + (VMware is supported). When used with another primary storage + vendor's plugin, the quiesce operation is provided according to the + vendor's implementation. #. Click OK. +To delete a snapshot or restore a VM to the state saved in a particular +snapshot: -Changing a VM's Base Image -~~~~~~~~~~~~~~~~~~~~~~~~~~ +#. Navigate to the VM as described in the earlier steps. -Every VM is created from a base image, which is a template or ISO which -has been created and stored in CloudStack. Both cloud administrators and -end users can create and modify templates, ISOs, and VMs. +#. Click View VM Snapshots. -In CloudStack, you can change an existing VM's base image from one -template to another, or from one ISO to another. (You can not change -from an ISO to a template, or from a template to an ISO). +#. In the list of snapshots, click the name of the snapshot you want to + work with. -For example, suppose there is a template based on a particular operating -system, and the OS vendor releases a software patch. The administrator -or user naturally wants to apply the patch and then make sure existing -VMs start using it. Whether a software update is involved or not, it's -also possible to simply switch a VM from its current template to any -other desired template. +#. Depending on what you want to do: -To change a VM's base image, call the restoreVirtualMachine API command -and pass in the virtual machine ID and a new template ID. The template -ID parameter may refer to either a template or an ISO, depending on -which type of base image the VM was already using (it must match the -previous type of image). When this call occurs, the VM's root disk is -first destroyed, then a new root disk is created from the source -designated in the template ID parameter. The new root disk is attached -to the VM, and now the VM is based on the new template. + To delete the snapshot, click the Delete button. |delete-button.png| + + To revert to the snapshot, click the Revert button. |revert-vm.png| + +.. note:: + VM snapshots are deleted automatically when a VM is destroyed. You don't + have to manually delete the snapshots in this case. -You can also omit the template ID parameter from the -restoreVirtualMachine call. In this case, the VM's root disk is -destroyed and recreated, but from the same template or ISO that was -already in use by the VM. +Virtual Machine Backups (Backup and Recovery Feature) +====================================================== Review comment: over-underlining ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
