community.general.proxmox_backup 模块 – 在 Proxmox VE 集群中启动 VM 备份

注意

此模块是 community.general 集合（版本 10.1.0）的一部分。

如果您正在使用 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.general。您需要其他要求才能使用此模块，有关详细信息，请参阅 要求。

要在 Playbook 中使用它，请指定：community.general.proxmox_backup。

community.general 10.1.0 中的新增功能

概要

• 允许您在 Proxmox VE 集群中创建 KVM 和 LXC 访客的备份。

• 提供创建单个备份的 GUI 功能，以及使用集群备份计划中的“立即运行”功能。

• 使用此模块所需的最低权限是相应 VM 和存储的 VM.Backup 和 Datastore.AllocateSpace。

• 大多数选项是可选的，如果未指定，将由集群及其默认值选择。

• 请注意，此模块**不是幂等的**。它始终启动新的备份（当不在检查模式下时）。

要求

以下要求在执行此模块的主机上是必需的。

• proxmoxer

• requests

参数

参数	注释
api_host 字符串 / 必需	指定 Proxmox VE 集群的目标主机。
api_password 字符串	指定用于身份验证的密码。 您可以使用 PROXMOX_PASSWORD 环境变量。
api_port 整数 在 community.general 9.1.0 中添加	指定 Proxmox VE 集群的目标端口。 如果未指定，则使用 PROXMOX_PORT 环境变量。
api_token_id 字符串 在 community.general 1.3.0 中添加	指定令牌 ID。 需要 proxmoxer>=1.1.0 才能工作。
api_token_secret 字符串 在 community.general 1.3.0 中添加	指定令牌密钥。 需要 proxmoxer>=1.1.0 才能工作。
api_user 字符串 / 必需	指定用于身份验证的用户。
backup_mode 字符串	Proxmox 执行备份的方式。默认设置是创建包含内存的运行时快照。 查看 https://pve.proxmox.com/pve-docs/chapter-vzdump.html#_backup_modes，了解差异的说明。 选项 "snapshot" ←（默认） "suspend" "stop"
bandwidth 整数	限制写入备份的 I/O 带宽（以 KiB/s 为单位）。0 表示无限制。
change_detection_mode 字符串	设置变更检测模式（可从 Proxmox VE 8.3 开始使用）。 仅在备份容器时使用，当应用于 KVM 访客时，Proxmox 会静默忽略此选项。 选项 "legacy" "data" "metadata"
compress 字符串	启用备份存档的额外压缩。 0 将使用 Proxmox 建议的值，具体取决于您的存储目标。 选项 "0" "1" "gzip" "lzo" "zstd"
compression_threads 整数	zstd 将用于压缩备份的线程数。 0 使用可用内核的 50%，任何大于 0 的值都将精确使用这么多线程。 如果您指定 compress=gzip 或 compress=lzo，则会忽略此选项。
description 字符串	指定备份的描述。 需要是单行，换行符和反斜杠需要分别转义为 \n 和 \\。 如果您需要变量插值，您可以像往常一样通过 Ansible Jinja 模板设置内容，或者让 Proxmox 替换模板。 Proxmox 目前支持 {{cluster}}、{{guestname}}、{{node}} 和 {{vmid}} 作为模板变量。由于这也是 Jinja 分隔符，因此您需要将这些值设置为原始 Jinja。 默认值： "{{guestname}}"
fleecing 字符串	启用备份 fleecing。仅适用于虚拟机及其磁盘。 必须输入为字符串，其中包含列表中键值对。
mode 字符串 / 必需	指定选择备份目标的模式。 选项 “include”（包含） “all”（全部） “pool”（池）
node（节点） 字符串	仅为给定的节点执行备份作业。 如果使用 mode=all，则通常使用此选项。 如果指定了节点 ID，并且您的虚拟机 ID 或池不位于该节点上，则它们将不会被备份！
notification_mode（通知模式） 字符串	确定要使用的通知系统。 选项 "auto" ←（默认） “legacy-sendmail”（旧版 sendmail） “notification-system”（通知系统）
performance_tweaks（性能调整） 字符串	启用其他与性能相关的设置。 必须以字符串形式输入，包含逗号分隔的键值对。 例如：max-workers=2,pbs-entries-max=2。
pool（池） 字符串	指定一个池名称，以将备份限制为给定池中的虚拟机。 当 mode=pool 时是必需的。 当您的用户仅对此单个池具有 VM.Backup 权限时，也需要此项。
protected（受保护） boolean（布尔值）	将备份标记为受保护。 “当 PBS 后端启用验证时，由于此错误可能会失败：https://bugzilla.proxmox.com/show_bug.cgi?id=4289“ 选项 false（假） true（真）
retention（保留） 字符串	使用自定义保留选项，而不是默认集群配置中的选项（通常为 "keep-all"）。 始终需要在存储端点具有 Datastore.Allocate 权限。 如果由于您指定的时间范围而应删除现有备份，则指定除 keep-all=1 之外的保留时间可能会在数据存储上触发修剪。 删除需要备份存储上的 Datastore.Modify 或 Datastore.Prune 权限。
storage（存储） 字符串 / 必需	将备份存档存储在此存储上。
validate_certs（验证证书） boolean（布尔值）	如果为 false，则不会验证 SSL 证书。 这应仅在个人控制的、使用自签名证书的站点上使用。 选项 false ←（默认） true（真）
vmids（虚拟机 ID） list / elements=integer	要备份的实例 ID。 仅当 mode=include 时有效。
wait（等待） boolean（布尔值）	等待备份完成。 如果作业未在给定的超时时间内成功完成，则会失败。 选项 false ←（默认） true（真）
wait_timeout（等待超时） 整数	等待备份完成的秒数。 仅当 wait=true 时才会评估此项。 默认： 10

属性

属性	支持	描述
action_group（操作组）	操作组： community.general.proxmox	在 module_defaults 中使用 group/community.general.proxmox 来为此模块设置默认值。
check_mode（检查模式）	支持： 完整	可以在 check_mode 中运行，并返回更改状态预测，而无需修改目标。
diff_mode（差异模式）	支持： 无	当处于差异模式时，将返回有关已更改内容（或可能需要在 check_mode 中更改的内容）的详细信息。

示例

- 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

返回值

此处记录了常用的返回值 此处，以下是此模块特有的字段

键	描述
backups（备份） list / elements=dictionary	节点及其任务 ID 的列表。 返回： 成功时
node（节点） 字符串	节点 ID。 返回： 成功时
status（状态） 字符串	上次已知的任务状态。如果 wait=false，则将为 unknown。 返回： 成功时 只能返回 “unknown”（未知） “success”（成功） “failed”（失败）
upid 字符串	Proxmox 集群 UPID，这是查找任务信息所必需的。当集群节点在被调用后没有创建任务时（例如，由于没有匹配的目标），将返回 OK。 返回： 成功时

作者

• Raphael Grieger (@IamLunchbox)

集合链接

• 问题跟踪器
• 存储库（来源）
• 寻求帮助
• 提交错误报告
• 请求功能
• 沟通