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/
|
||||
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 <clone_id>`
|
||||
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
|
||||
- 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
|
||||
|
||||
Reference in New Issue
Block a user