community.general.proxmox_backup module – Start a VM backup in Proxmox VE cluster
Note
This module is part of the community.general collection (version 10.1.0).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.general.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.general.proxmox_backup.
New in community.general 10.1.0
Synopsis
Allows you to create backups of KVM and LXC guests in Proxmox VE cluster.
Offers the GUI functionality of creating a single backup as well as using the run-now functionality from the cluster backup schedule.
The mininum required privileges to use this module are
VM.BackupandDatastore.AllocateSpacefor the respective VMs and storage.Most options are optional and if unspecified will be chosen by the Cluster and its default values.
Note that this module is not idempotent. It always starts a new backup (when not in check mode).
Requirements
The below requirements are needed on the host that executes this module.
proxmoxer
requests
Parameters
Parameter |
Comments |
|---|---|
Specify the target host of the Proxmox VE cluster. |
|
Specify the password to authenticate with. You can use |
|
Specify the target port of the Proxmox VE cluster. Uses the |
|
Specify the token ID. Requires |
|
Specify the token secret. Requires |
|
Specify the user to authenticate with. |
|
The mode how Proxmox performs backups. The default is, to create a runtime snapshot including memory. Check https://pve.proxmox.com/pve-docs/chapter-vzdump.html#_backup_modes for an explanation of the differences. Choices:
|
|
Limit the I/O bandwidth (in KiB/s) to write backup. |
|
Set the change detection mode (available from Proxmox VE 8.3). Is only used when backing up containers, Proxmox silently ignores this option when applied to kvm guests. Choices:
|
|
Enable additional compression of the backup archive.
Choices:
|
|
The number of threads zstd will use to compress the backup.
Is ignored if you specify |
|
Specify the description of the backup. Needs to be a single line, newline and backslash need to be escaped as If you need variable interpolation, you can set the content as usual through ansible jinja templating and/or let Proxmox substitute templates. Proxmox currently supports Default: |
|
Enable backup fleecing. Works only for virtual machines and their disks. Must be entered as a string, containing key-value pairs in a list. |
|
Specifices the mode to select backup targets. Choices:
|
|
Only execute the backup job for the given node. This option is usually used if If you specify a node ID and your vmids or pool do not reside there, they will not be backed up! |
|
Determine which notification system to use. Choices:
|
|
Enable other performance-related settings. Must be entered as a string, containing comma separated key-value pairs. For example: |
|
Specify a pool name to limit backups to guests to the given pool. Required, when Also required, when your user only has VM.Backup permission for this single pool. |
|
Marks backups as protected. “Might fail, when the PBS backend has verify enabled due to this bug: https://bugzilla.proxmox.com/show_bug.cgi?id=4289“ Choices:
|
|
Use custom retention options instead of those from the default cluster configuration (which is usually Always requires Datastore.Allocate permission at the storage endpoint. Specifying a retention time other than Deleting requires |
|
Store the backup archive on this storage. |
|
If This should only be used on personally controlled sites using self-signed certificates. Choices:
|
|
The instance ids to be backed up. Only valid, if |
|
Wait for the backup to be finished. Fails, if job does not succeed successfully within the given timeout. Choices:
|
|
Attributes
Attribute |
Support |
Description |
|---|---|---|
Action group: community.general.proxmox |
Use |
|
Support: full |
Can run in |
|
Support: none |
Will return details on what has changed (or possibly needs changing in |
Examples
- name: Backup all vms in the Proxmox cluster to storage mypbs
community.general.proxmox_backup:
api_user: root@pam
api_password: secret
api_host: node1
storage: mypbs
mode: all
- name: Backup VMID 100 by stopping it and set an individual retention
community.general.proxmox_backup:
api_user: root@pam
api_password: secret
api_host: node1
backup-mode: stop
mode: include
retention: keep-daily=5, keep-last=14, keep-monthly=4, keep-weekly=4, keep-yearly=0
storage: mypbs
vmid: [100]
- name: Backup all vms on node node2 to storage mypbs and wait for the task to finish
community.general.proxmox_backup:
api_user: test@pve
api_password: 1q2w3e
api_host: node2
storage: mypbs
mode: all
node: node2
wait: true
wait_timeout: 30
- name: Use all the options
community.general.proxmox_backup:
api_user: root@pam
api_password: secret
api_host: node1
bandwidth: 1000
backup_mode: suspend
compress: zstd
compression_threads: 0
description: A single backup for {% raw %}{{ guestname }}{% endraw %}
mode: include
notification_mode: notification-system
protected: true
retention: keep-monthly=1, keep-weekly=1
storage: mypbs
vmids:
- 100
- 101
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
List of nodes and their task IDs. Returned: on success |
|
Node ID. Returned: on success |
|
Last known task status. Will be unknown, if Returned: on success Can only return:
|
|
Proxmox cluster UPID, which is needed to lookup task info. Returns OK, when a cluster node did not create a task after being called, e.g. due to no matching targets. Returned: on success |