# 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`.
- **Ignition Support**: Generates and injects Ignition configuration for all supported OSs via the `fw_cfg` QEMU feature.
- **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

```text
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 configuration 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**:
   ```bash
   cd ansible-kvm-vms
   ```

2. **Run the deployment playbook**:
   ```bash
   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 configuration file based on your variables.
2. **Deployment**: `virt-install` is used to create the VM with UEFI boot. The `--sysinfo` flag is used to provide the Ignition config via the `fw_cfg` device, which the immutable OSs (CoreOS, Flatcar, MicroOS) process at first boot.

## 🌐 Accessing your VMs

The VMs are created on the default KVM NAT network. To find the IP address of your new VMs, run:
```bash
sudo virsh net-dhcp-leases-all default
```
Then SSH into them using your configured user:
```bash
ssh kvmuser@<vm-ip-address>
```