Модуль community.proxmox.proxmox_backup — запуск резервного копирования ВМ в кластере Proxmox VE

Примечание

Этот модуль входит в коллекцию community.proxmox (версия 1.6.0).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Для установки используйте: ansible-galaxy collection install community.proxmox. Для работы с этим модулем необходимы дополнительные требования; подробности см. в разделе Требования.

Чтобы использовать модуль в плейбуке, укажите: community.proxmox.proxmox_backup.

Краткое описание
Требования
Параметры
Атрибуты
Примеры
Возвращаемые значения

Краткое описание

Позволяет создавать резервные копии гостей KVM и LXC в кластере Proxmox VE.
Предоставляет возможность создавать отдельную резервную копию через графический интерфейс, а также использовать функцию немедленного запуска из расписания резервного копирования кластера.
Минимальные привилегии, необходимые для использования этого модуля, — VM.Backup и Datastore.AllocateSpace для соответствующих ВМ и хранилища.
Большинство параметров необязательны. Если они не заданы, кластер выберет значения по умолчанию.
Обратите внимание, что этот модуль не является идемпотентным. Он всегда запускает новое резервное копирование (кроме режима проверки).

Требования

На хосте, выполняющем этот модуль, должны быть установлены следующие компоненты.

proxmoxer >= 2.0
requests

Параметры

Параметр	Комментарии
api_host строка / обязательный	Укажите целевой хост кластера Proxmox VE. Если параметр не задан, используется переменная среды `PROXMOX_HOST`.
api_password строка	Укажите пароль для аутентификации. Если параметр не задан, используется переменная среды `PROXMOX_PASSWORD`.
api_port целое число	Укажите целевой порт кластера Proxmox VE. Если параметр не задан, используется переменная среды `PROXMOX_PORT`.
api_timeout целое число	Лимит времени для запросов к API Proxmox VE. По умолчанию: `5`
api_token_id строка	Укажите идентификатор токена. Если параметр не задан, используется переменная среды `PROXMOX_TOKEN_ID`.
api_token_secret строка	Укажите секрет токена. Если параметр не задан, используется переменная среды `PROXMOX_TOKEN_SECRET`.
api_user строка / обязательный	Укажите пользователя для аутентификации. Если параметр не задан, используется переменная среды `PROXMOX_USER`.
backup_mode строка	Режим создания резервных копий в Proxmox. По умолчанию создаётся снимок работающей системы, включающий память. Описание различий см. на странице https://pve.proxmox.com/pve-docs/chapter-vzdump.html#_backup_modes. Варианты: `"snapshot"` ← (по умолчанию) `"suspend"` `"stop"`
bandwidth целое число	Ограничение пропускной способности ввода-вывода (в КиБ/с) при записи резервной копии. Значение `0` означает отсутствие ограничений.
ca_path путь	Путь к локальному сертификату, который будет использоваться для проверки TLS-соединений. Игнорируется, если `validate_certs=false`.
change_detection_mode строка	Задаёт режим обнаружения изменений (доступен начиная с Proxmox VE 8.3). Используется только при резервном копировании контейнеров. Proxmox без предупреждения игнорирует этот параметр для гостей KVM. Варианты: `"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`. Если указать идентификатор узла, на котором нет ваших vmids или пула, их резервные копии созданы не будут!
notification_mode строка	Определяет, какую систему уведомлений использовать. Варианты: `"auto"` ← (по умолчанию) `"legacy-sendmail"` `"notification-system"`
performance_tweaks строка	Включает другие параметры, связанные с производительностью. Значение необходимо указать в виде строки с разделёнными запятыми парами «ключ—значение». Например: `max-workers=2,pbs-entries-max=2`.
pool строка	Укажите имя пула, чтобы ограничить резервное копирование гостями из этого пула. Обязательно, если `mode=pool`. Также обязательно, если у пользователя есть разрешение VM.Backup только для этого пула.
protected логическое значение	Помечает резервные копии как защищённые. «Операция может завершиться ошибкой, если в бэкенде PBS включена проверка, из-за этой ошибки: https://bugzilla.proxmox.com/show_bug.cgi?id=4289». Варианты: `false` `true`
retention строка	Использует пользовательские параметры хранения вместо параметров по умолчанию из конфигурации кластера (обычно `"keep-all=1"`). Всегда требуется разрешение Datastore.Allocate для конечной точки хранилища. Указание срока хранения, отличного от `keep-all=1`, может запустить очистку хранилища, если из-за заданного вами периода необходимо удалить существующую резервную копию. Для удаления требуются разрешения `Datastore.Modify` или `Datastore.Prune` на хранилище резервных копий.
storage строка / обязательный	Сохраняет архив резервной копии в этом хранилище.
validate_certs логическое значение	Проверяет TLS-сертификаты, используемые для подключения к API Proxmox VE. В настоящее время значение по умолчанию — `false`; в community.proxmox 2.0.0 оно изменится на `true`. Если параметр не задан, используется переменная среды `PROXMOX_VALIDATE_CERTS`. Варианты: `false` `true`
vmids список / элементы=целые числа	Идентификаторы экземпляров, для которых необходимо создать резервные копии. Допустимо только, если `mode=include`.
wait логическое значение	Ожидать завершения резервного копирования. Задание завершается с ошибкой, если не выполнится успешно в течение указанного времени ожидания. Варианты: `false` ← (по умолчанию) `true`
wait_timeout целое число	Количество секунд ожидания завершения резервного копирования. Учитывается только, если `wait=true`. По умолчанию: `10`

Атрибуты

Атрибут	Поддержка	Описание
action_group	Группа действий: community.proxmox.proxmox	Используйте `group/community.proxmox.proxmox` в `module_defaults`, чтобы задать значения по умолчанию для этого модуля.
check_mode	Поддержка: полная	Может работать в `check_mode` и возвращать прогнозируемый статус изменений, не изменяя целевой объект.
diff_mode	Поддержка: нет	В режиме diff будут возвращены сведения об изменениях (или о том, что, возможно, требуется изменить в `check_mode`).

Примеры

- name: Backup all vms in the Proxmox cluster to storage mypbs
  community.proxmox.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.proxmox.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.proxmox.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.proxmox.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 список / элементы=словари	Список узлов и идентификаторов их задач. Возвращается: при успехе
node строка	Идентификатор узла. Возвращается: при успехе
status строка	Последний известный статус задачи. Неизвестен, если `wait=false`. Возвращается: при успехе Возможные значения: `"unknown"` `"success"` `"failed"`
upid строка	UPID кластера Proxmox, необходимый для получения сведений о задаче. Возвращает OK, если после вызова узел кластера не создал задачу, например, из-за отсутствия подходящих объектов. Возвращается: при успехе

Авторы

Raphael Grieger (@IamLunchbox)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/proxmox/proxmox_backup_module.html