132 lines
3.8 KiB
Markdown
132 lines
3.8 KiB
Markdown
# 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 >= 9.1.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.
|