feat ✨: Update README.md with improved formatting and added notes & best practices
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.
This commit is contained in:
217
README.md
217
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/
|
ANSIBLE_PROXMOX_VM/
|
||||||
defaults/
|
├─ defaults/
|
||||||
main.yml
|
│ └─ main.yml
|
||||||
tasks/
|
├─ tasks/
|
||||||
main.yml
|
│ └─ main.yml
|
||||||
templates/
|
├─ templates/
|
||||||
cloudinit_userdata.yaml.j2
|
│ ├─ cloudinit_userdata.yaml.j2
|
||||||
cloudinit_vendor.yaml.j2
|
│ └─ cloudinit_vendor.yaml.j2
|
||||||
README.md
|
└─ README.md
|
||||||
|
```
|
||||||
|
|
||||||
Requirements
|
## Requirements
|
||||||
Proxmox API / Environment
|
|
||||||
|
|
||||||
This role runs on the Proxmox host via localhost, using qm CLI commands.
|
- Proxmox API / Environment
|
||||||
Therefore:
|
- 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).
|
The image is automatically downloaded if not present:
|
||||||
|
|
||||||
Proxmox must have a storage pool such as local-lvm.
|
|
||||||
|
|
||||||
Debian Cloud Image
|
|
||||||
|
|
||||||
Downloaded automatically if not present:
|
|
||||||
|
|
||||||
|
```
|
||||||
/var/lib/vz/template/qemu/debian-genericcloud-amd64.qcow2
|
/var/lib/vz/template/qemu/debian-genericcloud-amd64.qcow2
|
||||||
|
```
|
||||||
|
|
||||||
Variables (defaults/main.yml)
|
## Variables (`defaults/main.yml`)
|
||||||
Base VM settings
|
|
||||||
|
```yaml
|
||||||
|
# Base VM settings
|
||||||
vm_id: 150
|
vm_id: 150
|
||||||
hostname: debian-template-base
|
hostname: debian-template-base
|
||||||
memory: 4096
|
memory: 4096
|
||||||
@@ -76,44 +63,34 @@ storage: local-lvm
|
|||||||
mac_address: "DE:AD:BE:EF:44:55"
|
mac_address: "DE:AD:BE:EF:44:55"
|
||||||
cpu_type: host
|
cpu_type: host
|
||||||
|
|
||||||
Networking
|
# Networking
|
||||||
|
ip_mode: dhcp # or 'static'
|
||||||
Choose DHCP:
|
|
||||||
|
|
||||||
ip_mode: dhcp
|
|
||||||
ipconfig0: "ip=dhcp"
|
|
||||||
|
|
||||||
|
|
||||||
Or static:
|
|
||||||
|
|
||||||
ip_mode: static
|
|
||||||
ip_address: "192.168.1.60/24"
|
ip_address: "192.168.1.60/24"
|
||||||
gateway: "192.168.1.1"
|
gateway: "192.168.1.1"
|
||||||
dns:
|
dns:
|
||||||
- "1.1.1.1"
|
- "1.1.1.1"
|
||||||
- "8.8.8.8"
|
- "8.8.8.8"
|
||||||
|
|
||||||
ipconfig0: "{{ 'ip=dhcp' if ip_mode == 'dhcp' else 'ip=' + ip_address + ',gw=' + gateway }}"
|
ipconfig0: "{{ 'ip=dhcp' if ip_mode == 'dhcp' else 'ip=' + ip_address + ',gw=' + gateway }}"
|
||||||
|
|
||||||
Cloud-Init user
|
# Cloud‑Init user
|
||||||
ci_user: debian
|
ci_user: debian
|
||||||
ci_password: "SecurePass123"
|
ci_password: "SecurePass123"
|
||||||
ssh_key_path: "~/.ssh/id_rsa.pub"
|
ssh_key_path: "~/.ssh/id_rsa.pub"
|
||||||
timezone: "Europe/Berlin"
|
timezone: "Europe/Berlin"
|
||||||
|
|
||||||
Disk
|
# Disk
|
||||||
resize_disk: true
|
resize_disk: true
|
||||||
resize_size: "16G"
|
resize_size: "16G"
|
||||||
|
|
||||||
GPU passthrough
|
# GPU passthrough
|
||||||
gpu_passthrough: false
|
gpu_passthrough: false
|
||||||
gpu_device: "0000:01:00.0"
|
gpu_device: "0000:01:00.0"
|
||||||
virtio_gpu: false
|
virtio_gpu: false
|
||||||
|
|
||||||
UEFI + TPM
|
# UEFI + TPM
|
||||||
enable_tpm: false
|
enable_tpm: false
|
||||||
|
|
||||||
Templates + Clones
|
# Templates + Clones
|
||||||
make_template: true
|
make_template: true
|
||||||
create_clones: true
|
create_clones: true
|
||||||
clones:
|
clones:
|
||||||
@@ -121,83 +98,71 @@ clones:
|
|||||||
hostname: app01
|
hostname: app01
|
||||||
ip: "192.168.1.81/24"
|
ip: "192.168.1.81/24"
|
||||||
gateway: "192.168.1.1"
|
gateway: "192.168.1.1"
|
||||||
|
```
|
||||||
|
|
||||||
How to Use
|
## Usage
|
||||||
1. Include the role in your playbook
|
|
||||||
|
### Include the role in a playbook
|
||||||
|
|
||||||
|
```yaml
|
||||||
- hosts: proxmox
|
- hosts: proxmox
|
||||||
become: true
|
become: true
|
||||||
roles:
|
roles:
|
||||||
- ANSIBLE_PROXMOX_VM
|
- ANSIBLE_PROXMOX_VM
|
||||||
|
```
|
||||||
|
|
||||||
|
### Run directly
|
||||||
|
|
||||||
Or run directly:
|
```bash
|
||||||
|
|
||||||
ansible-playbook tasks/main.yml -i inventory
|
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 <clone_id>`
|
||||||
|
2. Set hostname & Cloud‑Init netplan
|
||||||
|
3. Start the VM
|
||||||
|
|
||||||
|
### Example `clones` section
|
||||||
|
|
||||||
|
```yaml
|
||||||
clones:
|
clones:
|
||||||
- id: 301
|
- id: 301
|
||||||
hostname: app01
|
hostname: app01
|
||||||
ip: "192.168.1.81/24"
|
ip: "192.168.1.81/24"
|
||||||
gateway: "192.168.1.1"
|
gateway: "192.168.1.1"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cloud‑Init Templates
|
||||||
|
|
||||||
The role will:
|
### `templates/cloudinit_userdata.yaml.j2`
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
Defines:
|
Defines:
|
||||||
|
- `users`
|
||||||
|
- SSH key
|
||||||
|
- password
|
||||||
|
- timezone
|
||||||
|
- package updates
|
||||||
|
- custom commands
|
||||||
|
|
||||||
users
|
### `templates/cloudinit_vendor.yaml.j2`
|
||||||
|
|
||||||
SSH key
|
|
||||||
|
|
||||||
password
|
|
||||||
|
|
||||||
timezone
|
|
||||||
|
|
||||||
package updates
|
|
||||||
|
|
||||||
custom command execution
|
|
||||||
|
|
||||||
Vendor Data
|
|
||||||
|
|
||||||
templates/cloudinit_vendor.yaml.j2
|
|
||||||
|
|
||||||
Defines:
|
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.
|
- Switch to `community.general.proxmox` API module instead of CLI
|
||||||
|
- Validate clone IDs
|
||||||
If cloning fails with invalid IP, check formatting: "192.168.1.81/24".
|
- Automated post‑deployment provisioning (Ansible SSH into clones)
|
||||||
|
- Publish as a Galaxy‑ready role
|
||||||
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
|
|
||||||
|
|||||||
Reference in New Issue
Block a user