Create Proxmox snapshots via Ansible

When working with Proxmox LXC or VM containers, it’s prudent to take a snapshot before applying updates. Snapshots provide an instant rollback point if the update causes failures.

Introduction

When it comes to automating snapshots in Proxmox, many ready-made solutions look convenient at first glance. But in practice, they often introduce unnecessary complexity:

• You need to manually enter VM or LXC IDs instead of using something intuitive like the hostname.
• You must explicitly define the Proxmox node within a cluster, even though this information is already available to the system.
• You end up depending on external Python libraries like proxmoxer or on CLI wrappers that need to be installed and maintained on every host.

With a native Ansible role built directly on the Proxmox API, these obstacles disappear. The role automatically determines the correct ID from the hostname and resolves the node internally. No manual input, no extra software, no cluster-specific hacks. Just your Ansible playbooks and the native Proxmox API.

A simpler approach with Ansible

Creating a Snapshot via Proxmox GUI:

1. Log in to the Proxmox web interface.
2. Navigate to the container or VM you want to protect.
3. Click Snapshots in the left-hand menu.
4. Click Take Snapshot.
5. Provide a descriptive name like pre_update_YYYYMMDD_HHMM and optional comment.
6. Click Take Snapshot to create the point-in-time backup.

This snapshot can be restored instantly if an update breaks the container. It doesn’t have to be this complicated. With a native Ansible role built directly on the Proxmox API, these obstacles disappear. The role automatically determines the correct ID from the hostname and resolves the node internally.

Creating a custom Proxmox role for Ansible (GUI)

For automation, it’s best to create a dedicated role with minimal permissions instead of using a full admin account. We’ll call this role CRAnsible.

Step 1: Create the Role

1. Log in to the Proxmox web interface.
2. Navigate to Datacenter → Permissions → Roles.
3. Click Add.
4. Name the role: CRAnsible.
5. Select the privileges needed:
   • VM.Snapshot – create, list, and restore snapshots
   • VM.Audit – view VM/container configuration and state
   • Sys.Audit – view system-wide status, needed for API queries on nodes and LXC containers
   • VM.PowerMgmt – needed if you want to start, stop, or reboot VMs/LXCs via the API
6. Click Add to create the role.

Step 2: Create a dedicated user

1. Go to Datacenter → Permissions → Users → Add.
2. Enter a username, e.g., ansible@pve.
3. Set a secure password or create an API token.

Step 3: Create a dedicated user

Security Note: When using the GUI, you can create either a user with a password or a user with an API token for automation. Using an API token is generally safer, because it can be limited in scope, easily revoked, and avoids exposing your main password.

• To create an API token in the GUI:
  1. Go to Datacenter → Permissions → API Tokens.
  2. Select your automation user (e.g., ansible@pve).
  3. Click API Tokens → Add.
  4. Give it a name e.g. Token ID: token-ansible and optional expiration date.
  5. Use the generated token in Ansible for authentication.

Important: Make sure to record the API token secret immediately, as it will only be displayed once and cannot be retrieved later.

Step 4: Assign the Role to the API Token

Navigate to Datacenter → Permissions → Add → API Token Permission.

• Select Path: / (or limit it to a specific node or container if desired)
• Select User: ansible@pve
• Select API Token: your newly created token
• Assign Role: CRAnsible
• Confirm with Add to apply the permission

Optional CLI Setup

Note: In the CLI, role assignments must be explicitly applied via ACLs, unlike in the GUI where the assignment is automatic.

You can also create the user via the Proxmox CLI:

# Step 1: Create the custom role CRAnsible
pveum roleadd CRAnsible -privs "VM.Snapshot VM.Audit Sys.Audit VM.PowerMgmt"

# Step 2: Create the automation user
# Realm 'pve' is the default, you can also use 'pam' if needed.
pveum useradd ansible@pve -comment "Ansible automation user"

# Step 3: Create an API token for the automation user
# This will output the token ID and secret (the secret is shown only once!)
pveum usertoken add ansible@pve token-ansible --comment "API token for Ansible automation"

# Step 4: Assign the role to the API token
# Here we give cluster-wide rights (path '/'). Adjust if you want to restrict to a node or VM.
pveum aclmod / -user ansible@pve!token-ansible -role CRAnsible

Now Ansible can authenticate using ansible@pve with either a password or an API token, and create snapshots before performing updates.

Testing Proxmox API Access from the command line

https://pve.proxmox.com/wiki/Proxmox_VE_API

To quickly check if your Proxmox host and API token are working, use curl from your Ansible host:

curl -k -s \
  -H 'Authorization: PVEAPIToken=YOUR_TOKEN' \
  https://YOUR_PROXMOX_HOST:8006/api2/json/nodes

• -k ignores self-signed SSL certificates.
• -s enables silent mode, suppressing progress and extra info so only the raw output (e.g., JSON) is displayed.
• Replace YOUR_TOKEN with your API token (user@realm!tokenid=secret) and YOUR_PROXMOX_HOST with the Proxmox hostname or IP.
  • Username: ansible
  • Realm: pve
  • Token ID: token-ansible
  • Token Secret: 12345678-ABCD-1234-ABCD-1234567890AB
• So YOUR_TOKEN should be replaced with: ansible@pve!token-ansible=12345678-ABCD-1234-ABCD-1234567890AB

If successful, you’ll get a JSON listing of all nodes in the cluster. Without jq installed the output will appear in a single compact line rather than pretty-printed JSON.

{
  "data": [
    {"node": "pve01", "status": "online"},
    {"node": "pve02", "status": "online"}
  ]
}

This confirms that the API is reachable and you can query nodes, VMs, and containers in your playbooks.

Running an Ansible task for Proxmox API calls

When working with Proxmox in an Ansible playbook, it’s important to ensure that API calls are executed from a host that has network access to the Proxmox cluster. Typically, this is the Ansible control machine, not the managed hosts. The following example demonstrates a clean way to test the Proxmox API using the uri module with delegation.

- name: Test Proxmox API via uri from control host
  ansible.builtin.uri:
    url: "https://{{ dnf_update_proxmox_host }}:8006/api2/json/nodes"
    method: GET
    headers:
      Authorization: 'PVEAPIToken={{ dnf_update_proxmox_api_token }}'
    validate_certs: no
    timeout: 60
  delegate_to: localhost
  run_once: true
  register: uri_connection_test

- name: Show Proxmox API response
  ansible.builtin.debug:
    var: uri_connection_test.json

Key Points

validate_certs: no
Skips SSL verification. This is convenient when using Proxmox with self-signed certificates, but for production a valid certificate should be preferred.

delegate_to: localhost
Runs the task on the Ansible control machine (the host where you run Ansible), not on the managed hosts. This ensures that the API call is executed in an environment that can reliably reach the Proxmox API.

run_once: true
Ensures the API is queried only once, even if the play targets multiple hosts.

Why delegate_to is crucial for Proxmox API calls

By default, Ansible tasks run on the managed hosts. For Proxmox API calls, this means each task attempts to reach the Proxmox API from the managed host itself. In practice, this often fails because the managed host might not have network access to the Proxmox cluster, DNS resolution may not work, or port 8006 could be blocked.

Using delegate_to: localhost forces the task to run on the Ansible control machine – the host with full access to the Proxmox API. This avoids network issues, eliminates timeouts, and ensures tasks execute reliably. It is also more efficient: tasks like querying nodes or creating snapshots only need to run once, not on every host.

In short: without delegation, you risk failed or hanging tasks. delegate_to ensures API calls are executed in the correct environment, making it an essential technique when managed hosts cannot directly reach central services.

bash: !tokenid=...: event not found

-H 'Authorization: PVEAPIToken=ansible@pve!tokenid=SECRET'

HTTP/1.1 401 no tokenid specified

USER@REALM!TOKENID=SECRET

curl -k -s \
  -H 'Authorization: PVEAPIToken=ansible@pve!automation=12345678-ABCD-1234-ABCD-1234567890AB' \
  https://pve01.examplecorp.io:8006/api2/json/nodes

curl -k -v \
  -H 'Authorization: PVEAPIToken=ansible@pve!token-ansible=12345678-ABCD-1234-ABCD-1234567890AB' \
  https://pve01.examplecorp.io:8006/api2/json/nodes

{"data":null,"message":"Permission check failed (/nodes/pve03, Sys.Audit)"}

{"data":[]}

QEMU VMs: []
LXC containers: []

Core Features of the ansible-proxmox-snapshot Automation

• Pre-update snapshots for Proxmox QEMU VMs and LXC containers
• Automatic target resolution based on inventory_hostname
• Direct API integration — no additional host-side scripts required
• Supports snapshot rotation and retention (if configured in the role)
• Role-level configuration via defaults/main.yml or group_vars
• Fully idempotent and safe to run multiple times

Summary

By combining Ansible automation with Proxmox snapshots, you achieve:

• Safe and repeatable DNF updates.
• Service state verification.
• Detailed reporting.
• A rollback mechanism for containers.

This workflow is especially useful for home labs, test environments, or production clusters, ensuring updates don’t introduce downtime or configuration drift.