refactor ♻️: Refactor README and update role for Proxmox VE provisioning

This refactoring includes updating the README, changing the role name to focus on Proxmox VE, enhancing compatibility matrix, and refactoring default values for role variables. Handlers are updated to manage apt cache, restart pveproxy, and reload systemd. Role metadata is also updated for better Proxmox VE provisioning.

README.md

@@ -1,30 +1,42 @@
-# ansible-role-template
+# ansible_role_proxmox_provision
 
-> A reusable Ansible role template for deploying and managing  
+> A reusable Ansible role template for for Proxmox VE 
-> applications/services with security best practices.
+> 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/)
-[![Platforms](https://img.shields.io/badge/Platforms-Debian-blue)](https://www.debian.org/)
+[![Proxmox](https://img.shields.io/badge/Proxmox-9-orange?logo=proxmox&logoColor=white)](https://www.proxmox.com/)  
 
 ## 📌 Key Features
 
-✅ **Idempotent** - Safe to run multiple times
+✅ **Proxmox VE Optimized** - Specifically designed for Proxmox Virtual Environment
-✅ **Security Hardened** - Follows Ansible security best practices
+⬜ **Idempotent** - Safe to run multiple times
-✅ **Modular** - Clear separation of concerns
+⏳ **Security Hardened** - Follows Ansible security best practices
-✅ **Documented** - Comprehensive README and variable documentation
+⏳ **Modular** - Clear separation of concerns
-✅ **Tested** - Includes example playbook for validation
+⏳ **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-template/
+ansible_role_proxmox_provision/
 ├── README.md          # This file
-├── defaults/          # Default role variables
+├── defaults/          # Default role variables (overridable)
 │   └── main.yml
-├── handlers/          # Role handlers
+├── handlers/          # Role handlers (for follow-up actions)
 │   └── main.yml
-├── files/             # Static files to deploy
 ├── meta/              # Role metadata
 │   └── main.yml
 ├── tasks/             # Main role tasks
@@ -36,38 +48,38 @@ ansible-role-template/
     └── main.yml
 ```
 
-## 🛠️ Development
-
-### Prerequisites
-
-- Ansible 2.12+
-- Python 3.8+
-
 ## 🔧 Configuration
 
 ## Default Variables (`defaults/main.yml`)
 
 ```yaml
 # Default values for role variables
-role_template_service_name: "default_service"
+## Swap handling
-role_template_service_port: 80
+proxmox_disable_swap: true
-role_template_backup_enabled: false
+proxmox_swapiness: 10
-role_template_service_backup_dir: "/var/backups/{{ role_template_service_name }}"
+proxmox_min_ram_mb_for_no_swap: 16384
-role_template_monitoring_enabled: false
+
+## Powertop
+proxmox_enable_powertop: true
+
+## Logrotate
+proxmox_logrotate_maxsize: "100M"
+proxmox_logrotate_rotate: 7
 ```
 
 ## Example usage
 
-### Example Playbook (`example-playbook.yml`)
+### Example Playbook (example-playbook.yml)
 
 ```yaml
 ---
-- hosts: all
+- hosts: proxmox_hosts
   roles:
-    - role: yourorg.ansible-role-template
+    - role: ansible_role_proxmox_provision
       vars:
-        role_template_service_name: "myapp"
+        proxmox_disable_swap: false
-        role_template_service_port: 8080
+        proxmox_swapiness: 20
+        proxmox_enable_powertop: true
 ```
 
 ### 3. Run the Playbook
@@ -76,6 +88,23 @@ role_template_monitoring_enabled: false
 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  
@@ -83,6 +112,9 @@ See the [LICENSE](LICENSE) file for details.
 
 ## TODO
 
-☐ refactor  
+⏳ Make the nag patch checksum-based (auto-repatch after upgrades)
-☐ debug  
+❌ Add kernel power-saving tunables ?
-☐ docs  
+🔄 Split into VE version–aware tags ?
+🕒 refactor  
+✗ debug  
+⭐ Improve documentation  

defaults/main.yml

@@ -1,38 +1,16 @@
 ---
-# ansible-role-template/defaults/main.yml
+# ansible_role_proxmox_provision/defaults/main.yml
 # Default values for role variables
 # ===================================
 
-# Service configuration
+# Swap handling
-role_template_service_name: "default_service"
+proxmox_disable_swap: true
-role_template_service_port: 80
+proxmox_swapiness: 10
+proxmox_min_ram_mb_for_no_swap: 16384
 
-# User and permissions
+# Powertop
-role_template_service_user: "nobody"
+proxmox_enable_powertop: true
-role_template_service_group: "nogroup"
-role_template_service_uid: 65534
-role_template_service_gid: 65534
-role_template_service_mode: "0755"
 
-# Directory structure
+# Logrotate
-role_template_service_dir: "/opt/{{ role_template_service_name }}"
+proxmox_logrotate_maxsize: "100M"
-role_template_service_backup_dir: "/var/backups/{{ role_template_service_name }}"
+proxmox_logrotate_rotate: 7
-
-# Systemd configuration (if applicable)
-role_template_systemd_enabled: false
-role_template_systemd_override_dir: "/etc/systemd/system/{{ role_template_service_name }}.d"
-
-# Security
-role_template_validate_certs: true
-role_template_ssl_ciphers: "HIGH:!aNULL:!MD5"
-role_template_ssl_protocols: "TLSv1.2:TLSv1.3"
-
-# Backup
-role_template_backup_enabled: false
-role_template_backup_retention: 7
-role_template_backup_archive_path: "/var/backups/{{ role_template_service_name }}/archive"
-
-# Monitoring (optional)
-role_template_monitoring_enabled: false
-role_template_monitoring_interval: 60
-role_template_monitoring_notify_email: "admin@example.com"

handlers/main.yml

@@ -1,45 +1,15 @@
 ---
-# ansible-role-template/handlers/main.yml
+# ansible_role_proxmox_provision/handlers/main.yml
 # Handlers for role
 # ==================
+- name: apt update
+  apt:
+    update_cache: yes
 
-# Service handlers
+- name: restart pveproxy
-- name: Restart {{ role_template_service_name }}
+  systemd:
-  ansible.builtin.service:
+    name: pveproxy
-    name: "{{ role_template_service_name }}"
     state: restarted
-  listen: "restart {{ role_template_service_name }}"
-  when: role_template_service_enabled
 
-- name: Reload systemd
+- name: reload systemd
-  ansible.builtin.systemd:
+  command: systemctl daemon-reexec
-    daemon_reload: true
-  listen: "restart {{ role_template_service_name }}"
-  when: role_template_systemd_enabled
-
-# Configuration handlers
-- name: Reload nginx
-  ansible.builtin.service:
-    name: nginx
-    state: reloaded
-  listen: "reload nginx"
-  when: "'nginx' in role_template_service_name"
-
-# Backup handlers
-- name: Rotate logs
-  ansible.builtin.command: logger -p local0.info "Rotating logs for {{ role_template_service_name }}"
-  changed_when: true
-  listen: "rotate logs"
-
-# Monitoring handlers
-- name: Notify monitoring
-  ansible.builtin.uri:
-    url: "{{ role_template_monitoring_webhook_url }}"
-    method: POST
-    body_format: json
-    body: "{{ lookup('template', 'monitoring_notification.json.j2') }}"
-    status_code: 200
-  delegate_to: localhost
-  run_once: true
-  listen: "notify monitoring"
-  when: role_template_monitoring_enabled

meta/main.yml

@@ -1,18 +1,15 @@
 ---
-# ansible-role-template/meta/main.yml
+# ansible_role_proxmox_provision/meta/main.yml
 galaxy_info:
-  role_name: ansible_role_template  # if absent directory name hosting role is used instead
+  role_name: ansible_role_proxmox_provision
   namespace: joseraj  # if absent, author is used instead
   author: joseraj
-  description: >
+  description: Proxmox VE tuning (repos, nag removal, swap, logrotate, powertop)
-    A reusable Ansible role template for deploying and managing applications/services
-    with security best practices, modularity, and idempotency.
   license: MIT
   min_ansible_version: "2.12"
   platforms:
     - name: Debian
       versions:
-        - buster
         - bullseye
         - bookworm
         - trixie

tasks/backup.yml

@@ -1,28 +0,0 @@
----
-# # ansible-role-template/tasks/backup.yml
-# Backup tasks
-# ============
-
-- name: backup | Ensure backup directory exists
-  ansible.builtin.file:
-    path: "{{ role_template_backup_dir }}"
-    state: directory
-    mode: "0750"
-    owner: root
-    group: root
-
-- name: backup | Create backup script
-  ansible.builtin.template:
-    src: templates/backup_script.sh.j2
-    dest: /usr/local/bin/backup_{{ role_template_service_name }}
-    mode: "0755"
-    owner: root
-    group: root
-
-- name: backup | Create cron job for backups
-  ansible.builtin.cron:
-    name: "Backup {{ role_template_service_name }}"
-    user: root
-    minute: "0"
-    hour: "3"
-    job: "/usr/local/bin/backup_{{ role_template_service_name }}"

tasks/logrotate.yml

@@ -0,0 +1,8 @@
+---
+- name: Configure Proxmox logrotate limits
+  template:
+    src: logrotate-pve.j2
+    dest: /etc/logrotate.d/proxmox
+    owner: root
+    group: root
+    mode: "0644"

tasks/main.yml

@@ -1,8 +1,23 @@
 ---
-# ansible-role-template/tasks/main.yml
+# ansible_role_proxmox_provision/tasks/main.yml
 # Main tasks for role
 # ===================
 
+- name: Disable enterprise repo, enable no-subscription
+  ansible.builtin.import_tasks: repos.yml
+
+- name: Remove the infamous subscription nag
+  ansible.builtin.import_tasks: subscription.yml
+
+- name: Disable swap or tune it
+  ansible.builtin.import_tasks: swap.yml
+
+- name: Stop logs from quietly murdering /
+  ansible.builtin.import_tasks: logrotate.yml
+
+- name: Install, auto-tune, and make it persistent
+  ansible.builtin.import_tasks: powertop.yml
+
 # Import backup tasks
 - name: Import backup tasks
   ansible.builtin.import_tasks: backup.yml

tasks/monitoring.yml

@@ -1,22 +0,0 @@
----
-# # ansible-role-template/tasks/monitoring.yml
-# Monitoring tasks
-# ================
-
-- name: monitoring | Ensure monitoring directory exists
-  ansible.builtin.file:
-    path: "/var/log/monitoring/{{ role_template_service_name }}"
-    state: directory
-    mode: "0755"
-
-- name: monitoring | Create monitoring configuration
-  ansible.builtin.template:
-    src: templates/monitoring_config.yml.j2
-    dest: "/etc/monitoring/{{ role_template_service_name }}.yml"
-    mode: "0640"
-
-- name: monitoring | Ensure monitoring service is running
-  ansible.builtin.service:
-    name: monitoring-service
-    state: started
-    enabled: yes

tasks/powertop.yml

@@ -0,0 +1,22 @@
+---
+- name: Install powertop
+  apt:
+    name: powertop
+    state: present
+    update_cache: yes
+  when: proxmox_enable_powertop
+
+- name: Create powertop systemd service
+  template:
+    src: powertop.service.j2
+    dest: /etc/systemd/system/powertop.service
+    mode: "0644"
+  when: proxmox_enable_powertop
+  notify: reload systemd
+
+- name: Enable and start powertop service
+  systemd:
+    name: powertop
+    enabled: true
+    state: started
+  when: proxmox_enable_powertop

tasks/repos.yml

@@ -0,0 +1,15 @@
+---
+- name: Remove enterprise repo files (all known locations)
+  file:
+    path: "{{ item }}"
+    state: absent
+  loop:
+    - /etc/apt/sources.list.d/pve-enterprise.list
+    - /etc/apt/sources.list.d/ceph.list
+
+- name: Enable Proxmox no-subscription repo
+  copy:
+    dest: /etc/apt/sources.list.d/pve-no-subscription.list
+    content: |
+      deb http://download.proxmox.com/debian/pve {{ ansible_distribution_release }} pve-no-subscription
+  notify: apt update

tasks/subscription.yml

@@ -0,0 +1,16 @@
+---
+- name: Remove subscription nag (legacy proxmoxlib.js)
+  replace:
+    path: /usr/share/javascript/proxmox-widget-toolkit/proxmoxlib.js
+    regexp: "if \\(data.status !== 'Active'\\)"
+    replace: "if (false)"
+  ignore_errors: true
+  notify: restart pveproxy
+
+- name: Remove subscription nag (minified bundle for VE 8/9)
+  replace:
+    path: /usr/share/javascript/proxmox-widget-toolkit/proxmoxlib.min.js
+    regexp: "data.status!=='Active'"
+    replace: "false"
+  ignore_errors: true
+  notify: restart pveproxy

tasks/swap.yml

@@ -0,0 +1,23 @@
+---
+- name: Set vm.swappiness
+  sysctl:
+    name: vm.swappiness
+    value: "{{ proxmox_swapiness }}"
+    state: present
+    reload: yes
+
+- name: Disable swap if host has enough RAM
+  command: swapoff -a
+  when:
+    - proxmox_disable_swap
+    - ansible_memtotal_mb >= proxmox_min_ram_mb_for_no_swap
+  changed_when: false
+
+- name: Remove swap from fstab
+  replace:
+    path: /etc/fstab
+    regexp: '^\S+\s+\S+\s+swap\s+.*$'
+    replace: ''
+  when:
+    - proxmox_disable_swap
+    - ansible_memtotal_mb >= proxmox_min_ram_mb_for_no_swap

templates/logrotate-pve.j2

@@ -0,0 +1,13 @@
+/var/log/pve/*.log /var/log/pve/tasks/*.log {
+    daily
+    rotate {{ proxmox_logrotate_rotate }}
+    compress
+    missingok
+    notifempty
+    maxsize {{ proxmox_logrotate_maxsize }}
+    create 0640 root adm
+    sharedscripts
+    postrotate
+        systemctl reload rsyslog >/dev/null 2>&1 || true
+    endscript
+}

templates/powertop.service.j2

@@ -0,0 +1,11 @@
+[Unit]
+Description=Powertop auto tune
+After=multi-user.target
+
+[Service]
+Type=oneshot
+ExecStart=/usr/sbin/powertop --auto-tune
+RemainAfterExit=true
+
+[Install]
+WantedBy=multi-user.target

vars/main.yml

@@ -1,2 +1,2 @@
 ---
-# ansible-role-template/vars/main.yml
+# ansible_role_proxmox_provision/vars/main.yml