proxmox-template-clone/README.md

Proxmox Template Clone

An Infrastructure-as-Code automation project for provisioning and configuring virtual machines (VMs) and Linux containers (LXCs) on a Proxmox cluster using Ansible and Jenkins.

Overview

This project automates the complete lifecycle of VM/LXC deployment:

• Clone VMs or LXCs from pre-built templates
• Configure system resources (CPU, RAM)
• Optionally install Docker and Docker Compose
• Optionally mount NFS shares
• All orchestrated through a Jenkins CI/CD pipeline

Project Structure

proxmox-template-clone/
├── Jenkinsfile                    # Jenkins pipeline definition
├── ansible.cfg                    # Ansible configuration
├── requirements.yml               # Galaxy collection dependencies
├── inventory/
│   └── hosts.yml                  # Ansible inventory
├── playbooks/
│   ├── provision.yml              # VM/LXC provisioning
│   └── configure.yml              # Post-provision configuration
└── roles/
    ├── proxmox_vm/                # VM cloning role
    ├── proxmox_lxc/               # LXC cloning role
    ├── docker/                    # Docker installation role
    └── nfs/                       # NFS mounting role

Requirements

Infrastructure

• Proxmox cluster with token-based API authentication
• Jenkins server with Ansible installed
• Pre-built templates (referenced by VMID):
  • VM template (VMID: 133)
  • LXC template (VMID: 109)
• Storage: local-lvm backend for VM/LXC disks

Jenkins Configuration

• SSH key pair at /var/lib/jenkins/.ssh/id_ed25519
• Proxmox API token stored as Jenkins credential with ID proxmox-resource-creator
  • Format: user@realm!tokenid=secret

Ansible Collections

- community.general >= 8.0.0
- community.proxmox >= 0.1.0
- ansible.posix >= 1.5.0

Install with:

ansible-galaxy install -r requirements.yml

Usage

Jenkins Pipeline Parameters

Parameter	Type	Default	Description
PROVISION_TYPE	Choice	-	VM or LXC
TARGET_NODE	Choice	-	Proxmox node (homeapp1, homeapp2, homestrg1, homeflux1)
HOSTNAME	String	-	Name for the new machine (required)
CPU_CORES	Integer	2	Number of CPU cores
RAM_GB	Integer	2	RAM in gigabytes
INSTALL_DOCKER	Boolean	false	Install Docker and Docker Compose
INSTALL_NFS	Boolean	false	Mount NFS share

Pipeline Workflow

1. Validate Parameters - Ensures hostname is provided and resources are valid
2. Install Collections - Downloads required Ansible Galaxy collections
3. Provision - Clones template and configures VM/LXC resources
4. Wait for Boot - Polls target machine until SSH is ready (up to 3 minutes)
5. Copy SSH Key - Enables passwordless SSH access for Jenkins
6. Configure - Runs system updates, installs Docker/NFS as requested

Configuration

Network

• Machines use .lan domain (e.g., hostname.lan)
• VMs bridge to vmbr0 using virtio
• LXCs use DHCP on eth0

NFS (Optional)

When enabled, mounts:

192.168.0.161:/mnt/share1/NFSFolder → /var/NFSFolder

Docker (Optional)

Installs:

• Docker CE
• Docker CLI
• containerd
• Docker Compose plugin
• Adds jenkins user to docker group

Customization

Proxmox API Host

Update the API host in playbooks/provision.yml:

proxmox_api_host: "192.168.0.166"

Target Nodes

Modify available nodes in the Jenkinsfile parameters section.

Templates

Template VMIDs are configured in the role defaults:

• roles/proxmox_vm/defaults/main.yml - VM template (VMID: 133)
• roles/proxmox_lxc/defaults/main.yml - LXC template (VMID: 109)

Update the values in these files to use different templates.

License

This project is provided as-is for home lab and educational use.