home-server/ansible/README.md

Proxmox VM Management Suite

A comprehensive Ansible automation suite for managing Proxmox Virtual Machines. This suite allows you to easily create Cloud-Init templates, provision new VMs, manage backups, and decommission resources across multiple Proxmox hosts.

Features

• Template Management:
  • Automatically download Cloud Images (Ubuntu, Debian, etc.).
  • Pre-configured with Cloud-Init (SSH keys, IP Config).
  • Support for selecting images from a curated list or custom URLs.
• VM Provisioning:
  • Clone from templates (Full or Linked clones).
  • Auto-start option.
• Lifecycle Management:
  • Backup VMs (Snapshot mode).
  • Delete/Purge VMs.
• Security:
  • Automatic SSH Key Injection: Automatically adds a defined Admin SSH key to every template.
  • Support for injecting additional SSH keys per deployment.

Setup

1. Requirements

Install the required Ansible collections:

ansible-galaxy install -r requirements.yml

2. Configuration

Edit roles/proxmox_vm/defaults/main.yml to set your global defaults, specifically the Admin SSH Key.

Important Variable to Change:

# ansible/roles/proxmox_vm/defaults/main.yml
admin_ssh_key: "ssh-ed25519 AAAAC3... your-actual-public-key"

Usage

The main entry point is the playbook playbooks/manage_vm.yml. You control the behavior using the proxmox_action variable.

1. Create a Cloud-Init Template

You can create a template by selecting a predefined alias (e.g., ubuntu-22.04) or providing a custom URL.

Option A: Select from List (Default) Current aliases: ubuntu-22.04, ubuntu-24.04, debian-12.

# Create Ubuntu 22.04 Template (ID: 9000)
ansible-playbook playbooks/manage_vm.yml \
  -e "proxmox_action=create_template vmid=9000 template_name=ubuntu-22-template image_alias=ubuntu-22.04"

Option B: Custom URL

ansible-playbook playbooks/manage_vm.yml \
  -e "proxmox_action=create_template \
      vmid=9001 \
      template_name=custom-linux \
      image_source_type=url \
      custom_image_url='https://example.com/image.qcow2'"

2. Create a VM from Template

Clone a valid template to a new VM.

ansible-playbook playbooks/manage_vm.yml \
  -e "proxmox_action=create_vm \
      vmid=9000 \
      new_vmid=105 \
      new_vm_name=web-server-01"

3. Backup a VM

Create a snapshot backup of a specific VM.

ansible-playbook playbooks/manage_vm.yml \
  -e "proxmox_action=backup_vm vmid=105"

4. Delete a VM

Stop and purge a VM.

ansible-playbook playbooks/manage_vm.yml \
  -e "proxmox_action=delete_vm vmid=105"

Advanced Usage

Handling Multiple Hosts

You can target a specific Proxmox node using the target_host variable.

ansible-playbook playbooks/manage_vm.yml -e "proxmox_action=create_vm ... target_host=mercury"

Injecting Additional SSH Keys

You can add extra SSH keys for a specific run (or add them to the defaults file).

ansible-playbook playbooks/manage_vm.yml \
  -e "proxmox_action=create_template ... additional_ssh_keys=['ssh-rsa AAAAB3... key1', 'ssh-ed25519 AAAA... key2']"

Directory Structure

• roles/proxmox_vm/: Core logic role.
  • defaults/main.yml: Configuration variables (Images, Keys, Defaults).
  • tasks/: Action modules (create_template.yml, create_vm.yml, etc.).
• inventory/: Host definitions.