🖥️ Automated Virtual Machine Provisioning

This homelab supports two provisioning workflows for creating virtual machines on Proxmox:

Pure Ansible provisioning
Hybrid Terraform + Ansible provisioning

Both workflows produce the same final VM state. The difference is in how the VM is created and which tool manages the lifecycle. Everything after VM creation (cloud‑init, boot sequencing, cleanup, SSH hardening) is identical.

This page documents the architecture, workflow, and module/tooling used by each approach.

❗IMPORTANT: Virtual Machine Templates Provisioning a virtual machine relies on using a virtual machine template that is cloned during provisioning. For more information on how virtual machine templates are generated, 👉 see the Contributor Guide for Adding New Cloud-Init VM Templates.

🔧 Provisioning Modes

Mode	Description	When to Use
Ansible‑only	Uses Proxmox API modules to clone and configure the VM directly.	Simple, transparent, minimal dependencies.
Terraform + Ansible	Terraform creates and configures the VM; Ansible handles cloud‑init and post‑provision tasks.	When you want declarative VM definitions and Terraform state.

Both modes are fully supported.

🧭 High‑Level Workflow

Regardless of provisioning mode, the VM follows the same lifecycle:

┌───────────────────────────┐
│   Generate cloud-init     │
│        snippets           │
│  (user-data, meta-data)   │
└──────────────┬────────────┘
               │
               ▼
┌──────────────────────────┐
│   Clone VM from template │
└──────────────┬───────────┘
               │
               │
               │   ┌──────────────────────────────┐
               └──▶│  Optional: migrate VM to     │
                   │  correct node/storage        │
                   └──────────────┬───────────────┘
                                  │
                                  ▼
                     ┌──────────────────────────┐
                     │ Attach cloud-init disk   │
                     │  (inject snippets)       │
                     └──────────────┬───────────┘
                                    │
                                    ▼
                     ┌──────────────────────────┐
                     │        Start VM          │
                     │ (cloud-init begins)      │
                     └──────────────┬───────────┘
                                    │
                                    ▼
                     ┌──────────────────────────┐
                     │ Wait for cloud-init to   │
                     │        complete          │
                     └──────────────┬───────────┘
                                    │
                                    ▼
                     ┌──────────────────────────┐
                     │ Remove cloud-init disk   │
                     └──────────────┬───────────┘
                                    │
                                    ▼
                     ┌──────────────────────────┐
                     │        Reboot VM         │
                     │ (finalize configuration) │
                     └──────────────┬───────────┘
                                    │
                                    ▼
                     ┌──────────────────────────┐
                     │   Update known_hosts     │
                     │  (SSH trust bootstrap)   │
                     └──────────────┬───────────┘
                                    │
                                    ▼
                     ┌─────────────────────────────┐
                     │ VM ready for post‑provision │
                     │  (Python bootstrap, venv,   │
                     │   agents, config mgmt, etc.)│
                     └─────────────────────────────┘

🧱 Shared Architecture

Both workflows use the same components:

Cloud‑Init

Used for first‑boot configuration:

users and SSH keys
packages
network configuration
write_files
first‑boot commands

Cloud‑Init snippets are generated by Ansible in both workflows. For more information on how a Cloud-Init image is created,

👉 See: Cloud-Init

Boot Sequencing

After the VM exists:

Start VM
Wait for cloud‑init to finish
Remove cloud‑init disk
Reboot
Update known_hosts

This ensures a stable, predictable VM state.

🧬 What Differs Between the Two Workflows

VM Creation

Ansible‑Only

Uses the Proxmox API via:

community.proxmox.proxmox_kvm
community.proxmox.proxmox

Ansible performs:

cloning
CPU/RAM configuration
disk/NIC configuration
cloud‑init disk attachment

Terraform Workflow

Terraform performs:

cloning
hardware configuration
cloud‑init disk attachment
optional additional disks

Ansible takes over after the VM exists.

📦 Proxmox‑Related Modules

Module	Purpose
community.proxmox.proxmox_kvm	Clone VMs, configure CPU/RAM/disks/NICs, manage cloud‑init, start/stop VMs
community.proxmox.proxmox	General Proxmox API interactions, node/storage queries, lifecycle operations

📂 Provisioning Entry Point

The playbook that selects the provisioning mode:

playbooks/vms/provision_vm.yml

Selection logic:

vms_use_terraform: true   # Terraform + Ansible
vms_use_terraform: false  # Pure Ansible

This keeps the interface simple while allowing two backends.

🧩 Contributor Notes

Both workflows share the same cloud‑init, boot, cleanup, and SSH tasks.
Only the VM creation step differs.
New features should be added to both workflows unless they are specific to Terraform or Ansible.
The role is intentionally modular: each step is its own task file.
Terraform workflow is a drop‑in alternative, not a fork.