Getting Started
Install dependencies and create your first KVM virtual machine.
Requirements
- Host OS: Debian 12 (Bookworm)
- Packages:
qemu-kvm, libvirt-daemon-system, libvirt-clients, ovmf, swtpm
Installation
# Clone the repository
git clone https://github.com/mars-base/ansible-vms.git
cd ansible-vms
# Install Python dependencies
uv sync # or: pip install -r requirements.txt
# Setup configuration files
cp ansible.cfg.example ansible.cfg # edit with your host name
cp hosts.ini.example hosts.ini # edit with your host name
cp vms.csv.example vms.csv # edit with your VM definitions
Quick Start
# Install required packages on KVM host
ap playbooks/install-dependencies.yaml
# Create VMs defined in vms.csv
ap playbooks/create-vm.yaml
Project Structure
ansible-vms/
├── ansible.cfg.example # Ansible config template
├── hosts.ini.example # Inventory template
├── vms.csv # VM definitions (CSV-driven)
├── pyproject.toml # Python dependencies (uv)
├── requirements.txt # pip dependencies
├── group_vars/
│ ├── all/ # Global variables
│ └── kvm_hosts/ # KVM host variables
├── host_vars/ # Per-host variables
├── playbooks/
│ ├── create-vm.yaml # Create VMs from vms.csv
│ ├── destroy-vm.yaml # Destroy VMs
│ ├── list-vms.yaml # List VMs
│ ├── snapshot-vm.yaml # Manage VM snapshots
│ ├── setup-user.yaml # Setup user accounts on Linux VMs
│ ├── start-vm.yaml # Start VMs
│ ├── stop-vm.yaml # Stop VMs
│ └── restart-vm.yaml # Restart VMs
├── roles/
│ └── create_vm/ # VM creation role (libvirt XML)
├── scripts/ # Helper scripts
├── tools/ # Utility scripts (vm-console, vm-login)
└── var/ # Runtime data (logs, facts cache)
Next Steps