Managing a Proxmox environment can take up a lot of time, especially as your infrastructure grows. Wouldn’t it be easier if you could automate those repetitive tasks? That’s where Ansible comes in. In this guide, you’ll learn how to combine Proxmox and Ansible for smooth automation, from deploying VMs to managing backups and snapshots.
What Are Proxmox and Ansible?
Let’s start with the basics. Proxmox Virtual Environment (VE) is an open-source virtualization platform that lets you run virtual machines (VMs) and containers on your servers. It combines KVM for VMs and LXC for containers, all managed through a web interface or API.
Ansible is an open-source automation tool that uses simple YAML files called playbooks to describe tasks like installing software, configuring systems, or managing cloud resources. With its agentless architecture, you only need SSH access or an API endpoint, no extra software on your targets.
When we talk about “proxmox ansible,” we mean using Ansible playbooks to control and automate tasks in your Proxmox cluster.
Why Use Ansible With Proxmox?
Manual management works fine when you have just a few VMs or containers. But as your environment grows, manual steps become slow and error-prone. Here’s why many admins use Ansible with Proxmox:
Consistency: Playbooks ensure every VM or container is created the same way.
Speed: Deploy dozens of VMs or apply updates across nodes in minutes.
Documentation: Your infrastructure setup lives in code, and it's easy to review or share.
Flexibility: Integrate with other tools (like monitoring or backup) using the same language.
You can automate not just VM creation but also configuration changes, network setups, user management, backups, snapshots, and more, all from one place.
How to Automate VM Deployment on Proxmox Using Ansible
Automating VM deployment is one of the most common “proxmox ansible” use cases. Let’s walk through it step by step, from beginner-friendly basics up to advanced customization.
Step 1: Prepare Your Environment
Before running any playbooks, make sure your environment is ready:
1. Install Ansible (version 2.12+ recommended) on your control machine.
2. Install required collections:
ansible-galaxy collection install community.general
3. Install Python dependencies:
pip install proxmoxer requests
4. Create an API token in the Proxmox web UI under Datacenter > Permissions > API Tokens, or via CLI:
pveum user token add root@pam ansible-token --privsep=0
Remember: The secret will only be shown once, thus store it securely!
It’s best practice to encrypt sensitive credentials using ansible-vault.
Step 2: Write Your Inventory and Variables
Define your inventory file (hosts.ini). If running locally:
[proxmox]
localhost ansible_connection=local
Create a variables file (vars/proxmox_credentials.yml):
---
proxmox_host: pve01.lab.local
proxmox_user: root@pam
proxmox_token_id: ansible-token
proxmox_token_secret: "your-token-secret-here"
Encrypt this file using ansible-vault if possible.
Step 3: Create a Playbook for VM Deployment
Here’s a basic example using the community.general.proxmox_kvm module:
---
- name: Create a Proxmox VM from template
hosts: localhost
gather_facts: false
vars_files:
- vars/proxmox_credentials.yml
tasks:
- name: Clone cloud-init template
community.general.proxmox_kvm:
api_host: "{{ proxmox_host }}"
api_user: "{{ proxmox_user }}"
api_token_id: "{{ proxmox_token_id }}"
api_token_secret: "{{ proxmox_token_secret }}"
node: pve01 # Node where template exists
clone: ubuntu-cloudinit-template # Template name in GUI (source)
name: web-01 # New VM's name
storage: local-lvm # Storage target for new disk(s)
full: true # Full clone instead of linked clone
timeout: 90 # Wait time for operation (seconds)
register: vm_result
- name: Start new VM after cloning
community.general.proxmox_kvm:
api_host: "{{ proxmox_host }}"
api_user: "{{ proxmox_user }}"
api_token_id: "{{ proxmox_token_id }}"
api_token_secret: "{{ proxmox_token_secret }}"
node: pve01 # Same node as above unless migrated later
vmid: "{{ vm_result.vmid | default(110) }}" # Use returned ID if available
state: started # Power on the new VMKey Points:
The node parameter must match where your template lives; clone should match the template’s display name exactly as seen in the GUI; adjust storage, name, and other parameters as needed; when deploying multiple VMs at once, define them as dictionaries within a list variable such as vms, then loop over them in your playbook.
Step 4 (Intermediate): Customize With Cloud-init
Cloud-init lets you set hostnames, static IPs, SSH keys and more for each deployed machine right from first boot.
For example:
tasks:
- name: Set cloud-init config after cloning
community.general.proxmox_kvm:
api_host : "{{ proxmox_host }}"
api_user : "{{ proxmox_user }}"
api_token_id : "{{ proxmox_token_id}}"
api_token_secret : "{{proxmox _token_secret}}"
node : pve01
clone : ubuntu-cloudinit-template
name : web-02
storage : local-lvm
full : true
ciuser : deploy # Default login user inside guest OS
cipassword : "securepassword" # Password for ciuser
sshkeys : "{{ lookup('file', '~/.ssh/deploy.pub') }}"
ipconfig0 : "ip=192.168.1.110/24,gw=192.168.1.1"
register : vm_result_cloudinitIf deploying several VMs at once with unique settings per machine:
vars:
vms:
- { name: web-03, ipconfig0:"ip=192.168.1.111/24,gw=192.168.1.1" }
- { name: db-01 , ipconfig0:"ip=192.168.1.112/24,gw=192.168.1.1" }
tasks:
- name : Deploy multiple VMs with custom configs
community.general.proxmok_kvm :
api_host : "{{ proxmox_host }}"
api_user : "{{proxmox_user}}"
api_token_id :"{{proxmox_token_id}}"
api_token_secret :"{{proxmox_token_secret}}"
node :"pve01"
clone :"ubuntu-cloudinit-template"
storage :"local-lvm"
full :"true"
ciuser :"deploy"
cipassword :"securepassword"
sshkeys :"{{ lookup('file', '~/.ssh/deploy.pub') }}"
ipconfig0 :"{{ item.ipconfig0 }}"
name :"{{ item.name }}"
loop :"{{ vms }}"
throttle :1This approach ensures each cloned machine gets unique settings automatically.
Step 5 (Advanced): Avoid Parallelism Issues
Deploying many VMs across several nodes at once can cause locking errors (“trying to acquire lock…”). To prevent conflicts during bulk operations within one playbook run, especially when looping over multiple items, use task-level concurrency controls like throttle.
For example:
tasks:
- name : Clone multiple VMs safely
community.general.proxmo_x_kvm :
...parameters...
loop :"{{ vms }}"
throttle :1 # Only one operation runs at a timeThis prevents simultaneous attempts that might conflict within the cluster.
Best Practices for Automating Prox m o x with Ansib le
Automating infrastructure brings speed but also risk if not done carefully! Here are some proven practices that help keep things safe while maximizing efficiency:
Always create separate API tokens per automation workflow and grant only minimal privileges needed by each playbook (“VM.Audit”, “VM.Allocate”, etc.). Test all new playbooks against non-production nodes before rolling out changes cluster-wide; even small mistakes can have big impact at scale!
If running commands from outside your cluster, for instance from CI/CD pipelines, use delegate_to so actions execute directly against localhost rather than remote hosts unnecessarily.
Use tags wisely so you can run only relevant parts of complex playbooks (--tags deploy, --tags backup). This saves time during troubleshooting or partial rollouts.
Remember idempotency matters! Some modules may report “changed” even when nothing changed; suppress noisy output by registering results then setting custom change conditions using changed_when.
Finally, document everything clearly inside both code comments AND version control commit messages so future admins know what was intended.
How to Manage Backups and Snapshots on Proxmox With Ansible
Backups and snapshots are essential for disaster recovery, but clicking through them manually doesn’t scale well! Here’s how you can automate these processes with “proxmox ansible”.
Snapshot Management Example
With Ansible modules like community.general.proxmox_snap, creating or rolling back snapshots becomes routine work instead of risky guesswork!
---
- name :'Manage snapshots before upgrade'
hosts :'localhost'
gather_facts:false
vars_files:['vars/pro xm ox_credentials.yml']
tasks :
- name:'Take pre-upgrade snapshot'
community.general.pro xm ox_snap :
api_host :'{{ proxmox_host }}'
api_user :'{{ proxmox_user }}'
api_token_id :'{{ proxmox_token_id }}'
api_token_secret :'{{ proxmox_token_secret }}'
vmid :110 # Target VM ID
snapname :'pre-upgrade' # Name of snapshot
description :"Snapshot before system upgrade"
state :'present' # Create snapshot
- name:'Rollback if needed'
community.general.pro xm ox_snap :
api_host :'{{ pro xm ox_host }}'
...other params...
snapname:'pre-upgrade'
state:'rollback'
when:'rollback_needed | default(false)'You can also remove old snapshots automatically by setting state:absent.
Backup Job Automation (Pro Tip)
For scheduled backups across many VMs/containers or entire clusters, you can use modules such as community.general.proxmox_backup. These let you define retention policies so old backups are pruned without manual cleanup.
Bulk operations are possible too; fetch all production-tagged VMs via API calls then loop over them with snapshot/backup modules.
Introducing Vinchin Backup & Recovery
Given these native options may not cover every scenario, especially complex migrations or compliance-driven protection, it makes sense to consider specialized solutions like Vinchin Backup & Recovery next. Vinchin supports over 19 virtualization platforms including VMware, Hyper-V, and Proxmox, and physical servers, databases, plus both on-premises and cloud-based file storage to meet diverse IT needs across industries.
If migration flexibility is important, Vinchin enables seamless full-system migration across virtual, physical, and cloud environments. It provides real-time backup and replication with automated failover to minimize RPO and RTO, along with integrity checks and test restores to ensure recoverability. Disaster recovery is supported through retention policies, long-term archiving, and remote DR orchestration.
A free 60-day trial plus comprehensive documentation and responsive support engineers ensure smooth deployment in any environment.
Prox m o x Ansib le FAQs
Q1: What minimum permissions does my API token need?
Grant only required privileges such as “VM.Audit”, “VM.Backup”, “Datastore.AllocateSpace” depending on task scope; avoid giving full admin rights unless necessary.
Q2: Can I manage both KVM virtual machines and LXC containers?
Yes; use community.general.proxmo_x_kvm module for KVM/QEMU virtual machines and community.general.proxmo_x module for LXC containers.
Q3: How do I set static IP addresses during deployment?
Use cloud-init enabled templates; pass IP config via the ipconfig0 parameter in your playbook task definition when cloning each VM.
Conclusion
Combining Proxmox VE with Ansible brings speed, consistency, and safety to daily operations from rapid deployments through robust backup routines. For advanced data protection across hybrid architectures, consider Vinchin Backup & Recovery, as it covers everything from routine jobs to disaster recovery planning.
