first commit

README.md

@@ -0,0 +1,131 @@
+# 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:**
+  - `ubuntu24vm` - Ubuntu 24 VM template
+  - `ubuntu24lxc` - Ubuntu 24 LXC template
+- **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
+
+```yaml
+- community.general >= 8.0.0
+- ansible.posix >= 1.5.0
+```
+
+Install with:
+```bash
+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](playbooks/provision.yml):
+```yaml
+proxmox_api_host: "192.168.0.166"
+```
+
+### Target Nodes
+
+Modify available nodes in the `Jenkinsfile` parameters section.
+
+### Templates
+
+Update template names in the respective role task files:
+- [roles/proxmox_vm/tasks/main.yml](roles/proxmox_vm/tasks/main.yml)
+- [roles/proxmox_lxc/tasks/main.yml](roles/proxmox_lxc/tasks/main.yml)
+
+## License
+
+This project is provided as-is for home lab and educational use.