From f76fb397ab779954c8202231d26037c3850e09be Mon Sep 17 00:00:00 2001 From: Jose Date: Sat, 15 Nov 2025 14:34:58 +0100 Subject: [PATCH] =?UTF-8?q?feat=20=E2=9C=A8:=20Update=20README.md=20with?= =?UTF-8?q?=20improved=20formatting=20and=20added=20notes=20&=20best=20pra?= =?UTF-8?q?ctices?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated the README.md file to improve readability and added notes on future improvements, such as API-based module support and automated post-deployment provisioning. --- README.md | 217 +++++++++++++++++++++++------------------------------- 1 file changed, 91 insertions(+), 126 deletions(-) diff --git a/README.md b/README.md index 8578863..a124a25 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,59 @@ -Ansible Role: Proxmox VM → Template → Clones (Cloud-Init) +# Ansible Role: Proxmox VM → Template → Clones (Cloud‑Init) -This role automates the full lifecycle of deploying a Debian GenericCloud VM on Proxmox, converting it into a template, and optionally creating multiple Cloud-Init clones with static or dynamic networking. +Automates the entire lifecycle of a Debian GenericCloud VM on Proxmox: +- Download the Debian image +- Create a base VM +- Optionally enable UEFI, SecureBoot, TPM 2.0, GPU passthrough +- Convert the VM into a template +- Spin up any number of Cloud‑Init clones with static or dynamic networking -It supports: +## Features -Downloading Debian GenericCloud image (qcow2) +- ✅ Auto‑download Debian Bookworm GenericCloud image +- ✅ Create VM (CPU, RAM, networking, storage) +- ✅ DHCP or static IP support +- ✅ Cloud‑Init: users, SSH keys, passwords, timezone, packages +- ✅ Optional TPM 2.0 + SecureBoot (OVMF) +- ✅ Optional GPU passthrough or VirtIO GPU +- ✅ Optional disk resize +- ✅ Convert base VM into a template +- ✅ Create multiple clones from template +- ✅ Start clones after creation -Creating and configuring a base VM +## Folder Structure -UEFI + Secure Boot + TPM 2.0 (optional) - -PCI or VirtIO GPU passthrough (optional) - -Disk import + optional resize - -Cloud-Init user and vendor templates - -Template conversion - -Automatic clone deployment with per-VM networking and hostname settings - -Features - -✔ Automatically downloads Debian Bookworm GenericCloud image -✔ Creates VM with CPU, RAM, networking, and storage settings -✔ Supports DHCP or static IPs -✔ Cloud-Init support: -– Users, SSH keys, passwords -– Timezone -– Packages -✔ Optional TPM 2.0 + SecureBoot (OVMF) -✔ Optional real GPU passthrough and VirtIO GPU -✔ Optional disk resize -✔ Convert base VM into a template -✔ Create any number of clones from template -✔ Start clones after creation - -Folder Structure +``` ANSIBLE_PROXMOX_VM/ - defaults/ - main.yml - tasks/ - main.yml - templates/ - cloudinit_userdata.yaml.j2 - cloudinit_vendor.yaml.j2 - README.md +├─ defaults/ +│ └─ main.yml +├─ tasks/ +│ └─ main.yml +├─ templates/ +│ ├─ cloudinit_userdata.yaml.j2 +│ └─ cloudinit_vendor.yaml.j2 +└─ README.md +``` -Requirements -Proxmox API / Environment +## Requirements -This role runs on the Proxmox host via localhost, using qm CLI commands. -Therefore: +- Proxmox API / Environment +- Role runs on the Proxmox host via localhost, using `qm` CLI commands. +- Ansible must have SSH access to the Proxmox node. +- User must have permission to run `qm` commands (root recommended). +- Proxmox storage pool such as `local-lvm`. -Ansible must have SSH access to the Proxmox node. +## Debian Cloud Image -The user must have permission to run qm commands (root recommended). - -Proxmox must have a storage pool such as local-lvm. - -Debian Cloud Image - -Downloaded automatically if not present: +The image is automatically downloaded if not present: +``` /var/lib/vz/template/qemu/debian-genericcloud-amd64.qcow2 +``` -Variables (defaults/main.yml) -Base VM settings +## Variables (`defaults/main.yml`) + +```yaml +# Base VM settings vm_id: 150 hostname: debian-template-base memory: 4096 @@ -76,44 +63,34 @@ storage: local-lvm mac_address: "DE:AD:BE:EF:44:55" cpu_type: host -Networking - -Choose DHCP: - -ip_mode: dhcp -ipconfig0: "ip=dhcp" - - -Or static: - -ip_mode: static +# Networking +ip_mode: dhcp # or 'static' ip_address: "192.168.1.60/24" gateway: "192.168.1.1" dns: - "1.1.1.1" - "8.8.8.8" - ipconfig0: "{{ 'ip=dhcp' if ip_mode == 'dhcp' else 'ip=' + ip_address + ',gw=' + gateway }}" -Cloud-Init user +# Cloud‑Init user ci_user: debian ci_password: "SecurePass123" ssh_key_path: "~/.ssh/id_rsa.pub" timezone: "Europe/Berlin" -Disk +# Disk resize_disk: true resize_size: "16G" -GPU passthrough +# GPU passthrough gpu_passthrough: false gpu_device: "0000:01:00.0" virtio_gpu: false -UEFI + TPM +# UEFI + TPM enable_tpm: false -Templates + Clones +# Templates + Clones make_template: true create_clones: true clones: @@ -121,83 +98,71 @@ clones: hostname: app01 ip: "192.168.1.81/24" gateway: "192.168.1.1" +``` -How to Use -1. Include the role in your playbook +## Usage + +### Include the role in a playbook + +```yaml - hosts: proxmox become: true roles: - ANSIBLE_PROXMOX_VM +``` +### Run directly -Or run directly: - +```bash ansible-playbook tasks/main.yml -i inventory +``` -Clone Creation Flow +## Clone Creation Flow -For each clone you define: +For each clone defined in `clones`: +1. `qm clone 150 ` +2. Set hostname & Cloud‑Init netplan +3. Start the VM + +### Example `clones` section + +```yaml clones: - id: 301 hostname: app01 ip: "192.168.1.81/24" gateway: "192.168.1.1" +``` +## Cloud‑Init Templates -The role will: - -Clone VM from template → qm clone 150 301 - -Set hostname + Cloud-Init netplan - -Start VM - -Cloud-Init Templates -User Data - -templates/cloudinit_userdata.yaml.j2 +### `templates/cloudinit_userdata.yaml.j2` Defines: +- `users` +- SSH key +- password +- timezone +- package updates +- custom commands -users - -SSH key - -password - -timezone - -package updates - -custom command execution - -Vendor Data - -templates/cloudinit_vendor.yaml.j2 +### `templates/cloudinit_vendor.yaml.j2` Defines: +- default packages +- DNS (optional) -default packages +## Notes & Best Practices -DNS (optional) +- Ensure Proxmox has snippets storage enabled (`Datacenter → Storage`). +- If cloning fails with an invalid IP, check the format: `"192.168.1.81/24"`. +- Both SSH keys and password login are supported (`ssh_pwauth: true`). +- If GPU passthrough is enabled, ensure the host kernel is configured for IOMMU. -Notes & Best Practices +## Future Improvements (optional) -Ensure Proxmox has snippets storage enabled under Datacenter → Storage. - -If cloning fails with invalid IP, check formatting: "192.168.1.81/24". - -Using both SSH keys + password login is possible (ssh_pwauth: true). - -If GPU passthrough is enabled, ensure the host kernel is configured for IOMMU. - -Future Improvements (optional) - -Add API-based module support (community.general.proxmox) instead of CLI - -Add validation for clone IDs - -Automated post-deployment provisioning (Ansible SSH into clones) - -Create a Galaxy-ready role \ No newline at end of file +- Switch to `community.general.proxmox` API module instead of CLI +- Validate clone IDs +- Automated post‑deployment provisioning (Ansible SSH into clones) +- Publish as a Galaxy‑ready role