# 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:
```bash
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:**
```yaml
# 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`.

```bash
# 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**
```bash
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.

```bash
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.

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

### 4. Delete a VM

Stop and purge a VM.

```bash
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.

```bash
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).

```bash
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.