84 lines
3.5 KiB
Markdown
84 lines
3.5 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`.
|
|
- **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
|
|
|
|
```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/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**:
|
|
```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) 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:
|
|
```bash
|
|
sudo virsh net-dhcp-leases-all default
|
|
```
|
|
Then SSH into them using your configured user:
|
|
```bash
|
|
ssh kvmuser@<vm-ip-address>
|
|
```
|