Stack/ansible-kvm-vms

Ansible KVM Immutable OS Provisioner

This project provides an Ansible-based framework to automatically provision virtual machines using KVM on a Linux host. It specifically targets immutable operating systems: Fedora CoreOS, Flatcar Container Linux, and openSUSE MicroOS.

🚀 Features

• Automated Host Setup: Installs and configures libvirt, qemu-kvm, and libguestfs-tools.
• Immutable OS Support: Handles the specific boot-time configuration requirements for:
  • CoreOS/Flatcar: Generates and injects Ignition JSON configurations.
  • MicroOS: Generates and injects Cloud-init user-data.
• Custom User Provisioning: Automatically creates a default user with a hashed password and injects your SSH public key.
• Modular Design: Uses Ansible roles for host preparation, configuration generation, and VM provisioning.

📂 Project Structure

ansible-kvm-vms/
├── inventory                # Defines the KVM host (defaults to localhost)
├── group_vars/
│   └── all.yml              # Global settings: user, password, and SSH key path
├── vars/
│   └── vms.yml              # List of VMs to create with CPU, RAM, and Disk specs
├── roles/
│   ├── kvm_host_setup/      # Installs virtualization dependencies on the host
│   ├── os_config/           # Generates Ignition/Cloud-init config files
│   └── vm_provision/        # Downloads images and creates VMs via virt-install
└── playbooks/
    └── create_vms.yml       # Main orchestration playbook

🛠 Prerequisites

Before running the playbooks, ensure the following:

1. Hardware Virtualization: Enabled in your BIOS/UEFI (VT-x or AMD-V).
2. Ansible: Installed on your control node.
3. Sudo Access: The user running the playbook must have sudo privileges on the KVM host.
4. SSH Key: You should have an SSH public key generated (usually at ~/.ssh/id_vms.pub).

⚙️ Configuration

1. Global Settings

Edit group_vars/all.yml to set your desired credentials:

• vm_user: The username for the VM.
• vm_password: The password for the user (will be hashed automatically).
• vm_ssh_public_key: The absolute path to your .pub key file.

2. VM Definitions

Edit vars/vms.yml to add or modify the VMs you wish to deploy. You can specify:

• name: Unique name for the VM.
• os_type: One of coreos, flatcar, or microos.
• os_variant: The virt-install OS variant string.
• cpu, ram, disk: Resource allocations.

📖 Usage

1. Navigate to the project directory:

   cd ansible-kvm-vms
   

2. Run the deployment playbook:

   ansible-playbook -i inventory playbooks/create_vms.yml --ask-become-pass
   

🔍 How it Works

Since immutable OSs do not use traditional installers, this setup uses a "seed" approach:

1. Config Generation: The os_config role creates a JSON (Ignition) or YAML (Cloud-init) file based on your variables.
2. Image Customization: The vm_provision role downloads the official .qcow2 cloud image and uses virt-customize (from libguestfs-tools) to inject the configuration directly into the disk image before the VM is started.
3. Deployment: virt-install is used to create the VM with UEFI boot and the customized disk.

🌐 Accessing your VMs

The VMs are created on the default KVM NAT network. To find the IP address of your new VMs, run:

sudo virsh net-dhcp-leases-all default

Then SSH into them using your configured user:

ssh kvmuser@<vm-ip-address>