ansible_role_proxmox_provision/README.md

# ansible_role_proxmox_provision

> A reusable Ansible role template for for Proxmox VE 
> with a focus on provisioning and managing.  

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Ansible Version](https://img.shields.io/badge/Ansible-2.12+-blue)](https://www.ansible.com/)
[![Proxmox](https://img.shields.io/badge/Proxmox-9-orange?logo=proxmox&logoColor=white)](https://www.proxmox.com/)  

## 📌 Key Features

✅ **Proxmox VE Optimized** - Specifically designed for Proxmox Virtual Environment
⬜ **Idempotent** - Safe to run multiple times
⏳ **Security Hardened** - Follows Ansible security best practices
⏳ **Modular** - Clear separation of concerns
⏳ **Documented** - Comprehensive README and variable documentation
⏳ **Tested** - Includes example playbook for validation

## 📊 Compatibility Matrix

| Feature                  | VE 7 | VE 8 | VE 9 |
| ------------------------ | ---- | ---- | ---- |
| No-subscription repo     | ✅    | ✅    | ✅    |
| Enterprise repo disabled | ✅    | ✅    | ✅    |
| Subscription nag removed | ✅    | ✅    | ✅    |
| Swap handling            | ✅    | ✅    | ✅    |
| Logrotate protection     | ✅    | ✅    | ✅    |
| Powertop auto-tune       | ✅    | ✅    | ✅    |


## 📂 Directory Structure

```text
ansible_role_proxmox_provision/
├── README.md          # This file
├── defaults/          # Default role variables (overridable)
│   └── main.yml
├── handlers/          # Role handlers (for follow-up actions)
│   └── main.yml
├── meta/              # Role metadata
│   └── main.yml
├── tasks/             # Main role tasks
│   ├── logrotate.yml       # logrotate setup
│   ├── main.yml            # Core tasks
│   ├── powertop.yml        # powertop setup
│   ├── repos.yml           # Repository setup
│   ├── subscription.yml    # Subscription nag removal
│   └── swap.yml            # Swap setup
├── templates/         # Jinja2 templates
└── vars/              # Non-overridable variables
    └── main.yml
```

## 🔧 Configuration

## Default Variables (`defaults/main.yml`)

```yaml
# Default values for role variables
## Swap handling
proxmox_disable_swap: true
proxmox_swapiness: 10
proxmox_min_ram_mb_for_no_swap: 16384

## Powertop
proxmox_enable_powertop: true

## Logrotate
proxmox_logrotate_maxsize: "100M"
proxmox_logrotate_rotate: 7
```

## Example usage

### Example Playbook (example-playbook.yml)

```yaml
---
- hosts: proxmox_hosts
  roles:
    - role: ansible_role_proxmox_provision
      vars:
        proxmox_disable_swap: false
        proxmox_swapiness: 20
        proxmox_enable_powertop: true
```

### 3. Run the Playbook

```bash
ansible-playbook -i inventory.ini example-playbook.yml
```

## 🚀 Installation and Setup

### Prerequisites

- Ansible 2.12 or higher
- Python 3.8 or higher
- Proxmox VE 7.x or higher
- Root/sudo access to Proxmox hosts

### Installation

1. Clone this repository or add as a dependency in your project:

```bash
git clone https://server.com/user/ansible_role_proxmox_provision.git
```

## 📄 License

This project is licensed under the MIT License  
See the [LICENSE](LICENSE) file for details.

## TODO

⏳ Make the nag patch checksum-based (auto-repatch after upgrades)
❌ Add kernel power-saving tunables ?
🔄 Split into VE version–aware tags ?
🕒 refactor  
✗ debug  
⭐ Improve documentation