This repository provides a simple workspace for developers to deploy QEMU/KVM-based virtual machines on-demand and quickly.
The emergence of tools like libvirt and cloud-init has facilitated an ecosystem with better standardization and easier automation. With libvirt, you can automate the management of hosts and disk images based on different virtualization technologies using scripts. On the other hand, cloud-init offers a standardized way to configure operating systems during their initial boot. cloud-init is widely used in virtual machine images from major public and private cloud providers. The combination of these technologies has made it possible to create this workspace.
You can think of this workspace as a framework that includes business logic and predefined configurations that you can customize. To work with the workspace, simply execute the vm.sh file, which contains all the business logic. Each workspace supports only one virtual machine. If you need multiple virtual machines, you can clone this repo to different workspaces as much as needed. Then, you will be able to manage each virtual machine from the respective workspace.
💡 Follow the instructions of your Linux based operating system to install the requirements below.
-
libguestfs: Toolset for accessing and modifying VM images.
-
Bridge utils: Utilities for configuring the Linux ethernet bridge.
-
QEMU: Machine emulator and virtualizer.
-
Libvirt: Toolkit to manage virtualization platforms.
-
yq: Implementation of yq written by Andrey Kislyuk.
💡 This workspace is preconfigured so you can use it right now.
⚠️ This preconfiguration assumes that you have a network bridge namedvirbr0with the IP address192.168.122.1.
Deploy a virtual machine:
./vm.sh deploy
Connect to the virtual machine:
./vm.sh shell-ssh
Details of the preconfigured virtual machine:
| Name | debian-vm |
|---|---|
| OS | Debian 11 |
| CPUs | 1 |
| Memory | 512 MB |
| Disk size | 4 GB |
| User | tux |
| Password | P4ssW0rd.. |
| Auth methods | Password, SSH keys |
| IP address | 192.168.122.122 |
| SSH port | 22 |
Run the vm.sh script with with the help action to show the usage documentation:
❯ ./vm.sh help
help: ./vm.sh <action>
Valid actions are:
- deploy [force]: Create the VM and the vdisk.
- undeploy [force]: Remove the VM and the vdisk.
- redeploy [force]: Recreate the VM and the vdisk.
- start: Start the VM.
- stop: Stop the VM.
- restart: Restart the VM.
- status: Show the VM status.
- shell-vm: Attach to VM's serial console.
- shell-ssh: Connect to VM's SSH service.
- help: Prints help.
Example: ./vm.sh deploy
The various features of the virtual machine are configured in different files within the workspace. This is because the workspace leverages the cloud-init feature included in the cloud images for virtual machines.
Below, you will find information on how to configure the most important features of the virtual machine through different use cases.
The virtual hardware of the VM, such as the number of processors, the bridge device name or the size of assigned RAM memory, can be defined in the configuration file vm.yaml. The URI from which the virtual disk template will be downloaded is also defined here. It's a YAML-formatted file that accepts the following fields:
| Field | Value type | Value description |
|---|---|---|
| name | String | Name to use as VM name and hostname |
| os | String | Short ID of OS. List of valid values: osinfo-query os |
| cpu | Integer | Number of CPUs |
| mem_mb | Integer | Megabytes of RAM memory |
| vd_gb | Integer | Size in gigabytes for the virtual disk of the VM |
| vd_src | String | Remote URI of the virtual disk image template file |
| bridge | String | Name of the bridge device to connect the VM |
| mac_addr | String | MAC address for VM's ethernet interface |
The settings for system users, such as password, public key, home directory, or shell, are defined in the cloud-init/user-data.yaml file. Within this file, there is an object called users that contains a list of all system users and their configurations. The first user is always default, which is the regular user included in the virtual disk image templates. The next user in the list is the one used by the workspace to interact with the virtual machine. When the virtual machine is deployed, SSH keys are generated for this user, and the value of its ssh_authorized_keys field is overwritten with the content of the newly created public key. This field is defined as an empty string when the virtual machine is undeployed. You can find more configurations in this example. Please note that the configuration must follow the cloud-config syntax.
You can install additional software using the package manager provided by the operating system. This software is installed when the virtual machine is deployed. The configuration for the package manager and the packages to be installed is defined in the cloud-init/user-data.yaml file. You can refer to this example to learn more. Please note that the configuration must follow the cloud-config syntax.
Network configurations, such as IP address, gateway, and DNS servers, among others, are defined in the cloud-init/network-config.yaml file. The value of the macaddress field is automatically set (Using the value of the mac_addr field of vm.yaml) when the virtual machine is deployed and it's defined as an empty string when the virtual machine is undeployed. You can refer to this example or read the network-config documentation to learn more.
The hostname is defined in the cloud-init/meta-data.yaml file. The valid fields for this file are the same as those used by the EC2 metadata service in AWS. You can refer to this example or read the file formats documentation to learn more.
If you need to run specific commands from a terminal during the virtual machine deployment, you can define them in the cloud-init/user-data.yaml file. You can refer to this example to learn more. Please note that the configuration must follow the cloud-config syntax.
Documentation has more examples available for different use cases.
You don't need to deploy a new virtual machine every time you want to validate configuration files based on cloud-config syntax, in this case, the cloud-init/user-data.yaml file. The cloud-init program allows you to check the syntax correctness and provides additional information in case of errors.
If you want to use cloud-init to validate the files, you will need to install it according to the documentation provided by your Linux-based operating system. I haven't included it in the Requirements section because cloud-init is not strictly necessary for the workspace to function.
Run the following command to validate cloud-config formatted files:
cloud-init schema --config-file <file-name>
💡 Please note that these are the tested images, and the workspace may also work with other compatible images.
This workspace has been tested with the following images: