81 lines
3.3 KiB
Markdown
81 lines
3.3 KiB
Markdown
# 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>
|
|
```
|