ansible-proxmox_skill

Overview

This skill provides practical guidance and Ansible patterns for automating Proxmox VE using the community.proxmox collection while minimizing raw CLI usage. It shows when to prefer native Ansible modules, how to handle operations that require CLI, and recommended authentication and idempotency patterns. The content focuses on reliable, repeatable automation for VMs, clusters, Ceph, storage, and networking.

How this skill works

The skill inspects common Proxmox tasks and maps them to community.proxmox modules when available, falling back to CLI commands only when no module exists. It provides example playbook fragments, idempotency checks for CLI workflows, API token and root-password authentication patterns, and guidance for delegating API calls. It also documents cluster and Ceph workflows with checks to avoid destructive re-runs.

When to use it

• Creating, cloning, or configuring VMs and templates with Ansible and Proxmox.
• Managing users, groups, pools, ACLs, and storage via community.proxmox modules.
• Forming or joining Proxmox clusters where no native module exists (pvecm).
• Initializing or managing Ceph where complex CLI sequences are required (pveceph).
• Configuring node network interfaces and VLAN-aware bridges via Ansible.

Best practices

• Prefer community.proxmox modules over pvecm/pveum/pvesm/qm commands when modules exist.
• Delegate API-based tasks to localhost instead of running modules on managed nodes.
• Use API tokens for automation and limit root password use to local node operations.
• Wrap CLI commands with idempotency checks (pvecm status, pveceph status) to avoid repeated changes.
• Mark sensitive tasks no_log for secrets and use a secrets manager lookup for token secrets.

Example use cases

• Create a VM from a template using community.proxmox.proxmox_kvm delegated to localhost.
• Create and manage automation users and ACLs with community.proxmox.proxmox_user and proxmox_acl.
• Form a new Proxmox cluster by checking pvecm status, creating on primary, and adding secondaries.
• Initialize Ceph and create OSDs with pveceph commands wrapped in existence checks.
• Configure VLAN-aware bridges using community.general.interfaces_file and notify network reload.