This page describe the vm_manager tool: https://github.com/seapath/vm_manager
Deploying a virtual machine on a SEAPATH cluster requires to handle many elements: ceph, qemu, libvirt, corosync. vm_manager was created as a wrapper around these components.
| vm_manager is not useful for a standalone SEAPATH hypervisor. If you wish to deploy a VM for that use case, refer to the deploy_vms_standalone.yaml playbook. |
The cluster_vm Ansible module is wrapper above vm_manager cli. A more detailed documentation can be generated from sources.
It can be called from a playbook to perform actions on VMs. For instance, an example of playbook that creates a VM from a predefined image disk and XML Libvirt configuration would be:
- name: Create and start guest0
cluster_vm:
name: guest0
command: create
system_image: my_disk.qcow2
xml: "{{ lookup('file', 'my_vm_config.xml', errors='strict') }}"
|
Playbooks can be executed in any hypervisor. Other playbook examples are stored in the example/playbooks/vm directory.
This section describes the VM architecture and the cluster_vm commands from a high-level point of view. Please read cluster_vm module documentation for further information.
| Like other Ansible modules, the cluster_vm documentation can also be displayed by executing ansible-doc cluster_vm command from the Ansible root repository. |
You will also find information on how to troubleshoot problems related to VM management on page Troubleshooting with vm_manager.
In the SEAPATH cluster the VMs can have several statuses:
The diagram below describes how a VM is stored in the SEAPATH cluster. All non-volatile VM data is stored using Ceph, which is in charge of the maintenance of the data-store and data replication between all the hypervisors.
Metadata provides information associated with a VM. It consists of a list of pairs (key, value) that are set at the moment of the VM creation. You can define as many metadata fields as you want but some keys are reserved:
KEY | VALUE MEANING |
vm_name | VM name |
_base_xml | Initial Libvirt XML VM configuration |
xml | Libvirt XML file used for the VM configuration. It is autogenerated by modifying the _base_xml file. |
The VM data disk is set when creating a new VM or cloning an existing one, as described in the schemas below.
Create a VM from scratch by importing an image disk with the create command:
- name: Create and start guest0
cluster_vm:
name: guest0
command: create
system_image: my_disk.qcow2
xml: "{{ lookup('file', 'my_vm_config.xml', errors='strict') }}"
|
Copy an existing VM with the clone command:
- name: Clone guest0 into guest1
cluster_vm:
name: guest1
src_name: guest0
command: clone
|
The network configuration inside the VMs is done with the playbook file cluster_setup_network.yaml. You need to use an inventory that describes the VMs instead of the cluster as in the example vms_inventory_example.yaml file.
Disk snapshots can be used to save the disk image data at a given moment, that can be later recovered.
Snapshots can be created when the VM is stopped or running, but if you perform a snapshot when the VM is running, only the data written on the disk will be saved.
Volatile data such as the content of the RAM or the data not written on the disk will not be stored on the snapshot. |
- name: Create a snapshot of guest0
cluster_vm:
name: guest0
command: create_snapshot
snapshot_name: snap1
|
You can restore the VM to a determined previous state by performing a rollback operation based on a snapshot. The data saved during the snapshot operation will be restored and replace the current disk image data. All current disk image data will be lost. The rollback operation does not remove the snapshot, it is possible to reuse the snapshot to re-apply a later rollback.
The rollback operation must be applied on a disabled machine. So if the VM is enabled, it will be automatically disabled before the rollback and re-enabled once the operation is finished.
- name: Rollback VM guest0 to snap0
cluster_vm:
name: guest0
command: rollback_snapshot
snapshot_name: snap0
|
With the cluster_vm module it is also possible to:
An example playbook that removes the snapshots created before a determined date would be:
# Example - Remove old snapshots
- name: Remove snapshots of guest0 older than January 24th 2021 8:00 AM
cluster_vm:
name: guest0
command: purge_image
purge_date:
date: '2021-01-24'
time: '08:00'
|
The purge operation can be performed regularly to avoid over space. This can be easily done with a tool like Ansible Tower or AWX.
Updating the VM data cannot be performed by the cluster_vm module, but you can use its snapshot system to cancel the update in case of error as described in the diagram below. To achieve this, you can base your playbook on the update skeleton example.
The VM configuration and metadata are immutable. To change them, you must create a new VM from the existing one with the clone command.
The file update configuration example can help you to create a playbook to achieve this operation according to the following diagram.
