home-server/ansible/README.md

Home Server Ansible Configuration

This directory contains Ansible playbooks for managing the Proxmox home server environment.

Directory Structure

• inventory/: Contains the inventory file hosts.ini where you define your servers.
• playbooks/: Contains the actual Ansible playbooks.
• ansible.cfg: Local Ansible configuration.
• requirements.yml: List of Ansible collections required.

Setup

1. Install Requirements:

   ansible-galaxy install -r requirements.yml
   

2. Configure Inventory: Edit inventory/hosts.ini and update the following:

   • ansible_host: The IP address of your Proxmox node.
   • ansible_user: The SSH user (usually root).
   • proxmox_api_*: Variables if you plan to use API-based modules in the future.

   Note: Ensure you have SSH key access to your Proxmox node for passwordless login, or uncomment ansible_ssh_pass.

Available Playbooks

Create Ubuntu Cloud Template (playbooks/create_ubuntu_template.yml)

This playbook downloads a generic Ubuntu 22.04 Cloud Image and converts it into a Proxmox VM Template.

Usage:

# Run the playbook
ansible-playbook playbooks/create_ubuntu_template.yml

Variables: You can override variables at runtime or by editing the playbook:

• template_id: Default 9000
• template_name: Default ubuntu-2204-cloud
• storage_pool: Default local-lvm

Example overriding variables:

ansible-playbook playbooks/create_ubuntu_template.yml -e "template_id=9001 template_name=my-custom-template"

Manage VM Playbook (playbooks/manage_vm.yml)

This unified playbook allows you to manage VMs (create from template, delete, backup, create template) across your Proxmox hosts.

Usage:

The playbook target defaults to the proxmox group, but you should usually specify a specific host using target_host variable or -l limit.

1. Create a New Template:

   ansible-playbook playbooks/manage_vm.yml -e "proxmox_action=create_template vmid=9003 template_name=my-ubuntu-template"
   

2. Create a VM from Template:

   ansible-playbook playbooks/manage_vm.yml -e "proxmox_action=create_vm vmid=9002 new_vmid=105 new_vm_name=my-new-vm"
   

3. Delete a VM:

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

4. Backup a VM:

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

Variables:

• proxmox_action: One of create_template, create_vm, delete_vm, backup_vm (Default: create_vm)
• target_host: The host to run on (Default: proxmox group). Example: -e "target_host=mercury"

See roles/proxmox_vm/defaults/main.yml for all available configuration options.