serverbee.virt_guest_manage

Virtual Guest Management Role

This role uses the official Ansible virt module to manage RHEL-based virtual machines using KVM as the hypervisor. By default, it uses the AlmaLinux version of RHEL. You can manage all your virtual machines (VMs) directly through settings in group_vars or host_vars. A key feature of this role is that it allows for the parallel installation of all virtual machines defined in virt_guest_list.

Getting Started

Supported Operating System Versions for VMs

• CentOS el6 (not tested with the latest version of the role)
• CentOS el7
• AlmaLinux el8
• AlmaLinux el9

Update Default Values to Suit Your Needs

1. Set a custom password by updating virt_guest_init_passwd.
2. Find and set the closest mirror for downloading all components of the RHEL installer.

Limitations of This Role

This role can manage LVM-based virtual disks for VMs, but you need to create Physical Volumes (PVs) and Volume Groups (VGs) before using it. You can set virtual network interfaces in two ways: using an existing Linux bridge or using libvirt networking. The last option can be managed with virt_network_list directly in this role.

Variables

General Variables

• virt_guest_dependency_qemu_kvm_role: [optional, default true]: Enables a dependency role for qemu-kvm.
• virt_guest_mirror: [default: http://repo.almalinux.org]: AlmaLinux mirror used to install the OS.
• virt_guest_os_location: [default: {{ virt_guest_mirror }}/almalinux/9/BaseOS/x86_64/os]: Path where AlmaLinux OS components are stored.
• virt_guest_kickstart_config_dir: [default: /tmp/kickstart]: Path for creating kickstart files.
• virt_guest_kickstart_config_port: [default: 8000]: Port for downloading kickstart config during installation.
• virt_guest_kickstart_config_url: [default: ip of a Hypervisor]: URL for downloading kickstart config during installation.
• virt_guest_kickstart_config_serve_timeout: [default: 90]: Time in seconds to serve kickstart files.
• virt_guest_kickstart_installation_timeout: [default: 480]: Time in seconds to finish kickstart installation.
• virt_guest_init_passwd: [required]: Root user password for first login.
• virt_guest_init_hostname: [default: fresh-installed.local]: Initial hostname of the virtual machine.

Virtual Network List Variables

• virt_network_list: [required, default: {}]: Definitions for virtual networks.
• virt_network_list.key: [required]: Name of the virtual network (e.g., br-nat0:).
• virt_network_list.key.router: [required]: IP address of the virtual router (e.g., 192.168.2.1).
• virt_network_list.key.netmask: [required]: Netmask of the virtual network (e.g., 255.255.255.0).
• virt_network_list.key.start: [required]: First IP in the virtual network range (e.g., 192.168.2.1).
• virt_network_list.key.end: [required]: Last IP in the virtual network range (e.g., 192.168.2.254).

Virtual Guest List Variables

• virt_guest_list: [required, default: {}]: Definitions for virtual guests.
• virt_guest_list.key: [required]: Name of the virtual machine (e.g., example-vm:).
• virt_guest_list.key.autostart: [optional, default true]: Enable autostart for the VM.
• virt_guest_list.key.uuid: [required]: Unique identifier for the VM (e.g., ad852ffe-07d9-43ec-9f5a-ced644f9a7a5).
• virt_guest_list.key.cpu: [optional, default 1]: Number of CPU cores.
• virt_guest_list.key.ram: [optional, default 2]: Amount of RAM in GiB.
• virt_guest_list.key.disk: [required]: Definitions for VM disks.
• More disk and network settings are listed in detail within the original document.

Dependencies

This role requires the serverbee.qemu_kvm role.

Examples

Simple Example

---
- hosts: localhost 
  roles:
    - serverbee.virt_guest_manage
  vars:
    virt_guest_list:
      example-vm:
        uuid: 7eb09567-83b8-4aab-916e-24924d6a0f89
        disk:
          sda:
            vg: vg_local
            lv: lv_vm_example
            size: 10G
        network:
          eth0:
            mac: 52:54:00:16:01:bc
            bridge: br0 

Full Options Example

---
- hosts: localhost 
  roles:
    - serverbee.virt_guest_manage
  vars:
    virt_network_list:
      br-nat0:
        router: 192.168.2.1
        netmask: 255.255.255.0
        start: 192.168.2.2
        end: 192.168.2.254

    virt_guest_list:
      example-vm:
        autostart: false
        uuid: 7eb09567-83b8-4aab-916e-24924d6a0f89
        cpu: 2 # Core
        ram: 4 # GiB
        disk:
          sda:
            type: block
            format: raw
            vg: vg_local
            lv: lv_vm_example-first
            size: 20%VG
            fstype: ext4
          vdb:
            type: file
            format: qcow2
            format_options: preallocation=metadata
            name: example-second-drive
            size: 5G
        network:
          eth0: 
            mac: 52:54:00:16:01:bc 
            bridge: br0 
            model: virtio 
            ip: 172.16.2.2 
            netmask: 255.255.255.248 
            gateway: 172.16.2.1
            dns: 172.16.2.1 
          eth1:
            mac: 52:54:00:16:02:ba
            network: br-nat0
            model: e1000
        vnc_enable: true

Additional Information

Monitoring VM Installation Progress

You can check if your VM responds to ping requests. If it doesn’t, use the virsh command-line tool to view your VMs and monitor each installation progress. The virsh command is automatically installed with this role. Use the following commands:

$ virsh list --all
$ virsh console example-vm

Timeout for Installation Completion

The variable virt_guest_kickstart_installation_timeout is set to 480 seconds by default. If your VM struggles to shut down before completing installation, you may need to increase the timeout. Ensure you set the closest mirror, preferably within the same country as your hosting provider, to enhance download speed by updating virt_guest_mirror and virt_guest_os_location.

Running Playbook for a Single VM

If you have multiple VMs but wish to manage only one, you can speed up the playbook execution by adding an extra variable vm:

$ ansible-playbook virt-guest-manage.yml --extra-vars vm=example-vm

You can pass the name of only one virtual machine at a time.

Re-running VM Installation

To re-run a VM installation, you must manually remove all existing components first:

$ virsh list --all
$ virsh destroy example-vm
$ virsh undefine example-vm
$ lvremove vg_local/lv_vm_example

This role does not support automated re-installation to prevent loss of existing data.

License

GPLv3 License

Author Information

Vitaly Yakovenko