Модуль community.libvirt.virt — управление виртуальными машинами, поддерживаемыми libvirt

Примечание

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

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

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

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

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

Обзор

Управление виртуальными машинами, поддерживаемыми libvirt.

Требования

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

python >= 2.6
привязки Python для libvirt
lxml

Параметры

Параметр	Комментарии
autostart boolean	Запускать виртуальную машину при загрузке узла. Варианты: `false` `true`
command string	Помимо управления состоянием доступны различные неидемпотентные команды. Варианты: `"create"` `"define"` `"destroy"` `"freemem"` `"get_xml"` `"get_interfaces"` `"info"` `"list_vms"` `"nodeinfo"` `"pause"` `"shutdown"` `"start"` `"status"` `"stop"` `"undefine"` `"unpause"` `"uuid"` `"virttype"`
flags list / elements=string	Передача дополнительных параметров. В настоящее время реализовано только для команды `undefine`. Укажите с помощью `undefine` метаданные, которые необходимо удалить. Этот параметр полезен, чтобы иметь возможность `undefine` гостевые системы с nvram UEFI. `nvram` и `keep_nvram` конфликтуют и являются взаимоисключающими. Если необходимо удалить все связанные метаданные, рассмотрите возможность использования параметра `force`. Варианты: `"managed_save"` `"snapshots_metadata"` `"nvram"` `"keep_nvram"` `"checkpoints_metadata"` `"delete_volumes"`
force boolean	Принудительное выполнение действия. В настоящее время реализовано только для команды `undefine`. Этот параметр можно использовать вместо указания всех `flags`. Если задано значение `true`, `undefine` также удаляет все связанные nvram и другие метаданные, если они существуют. Если задано значение `false` или параметр не указан, `undefine` выполняется, только если nvram и другие метаданные отсутствуют. В противном случае задача завершается ошибкой, а гостевая система остается определенной без изменений. Не следует одновременно указывать `true` и параметр `flags`. В этом случае `undefine` игнорирует `true`, учитывает только `flags` и выводит предупреждение. Варианты: `false` `true`
mutate_flags list / elements=string	Для каждого mutate_flag заданный XML будет изменен определенным образом. ADD_UUID добавит в XML UUID существующего домена, если он отсутствует. ADD_MAC_ADDRESSES найдет интерфейсы в существующем домене с совпадающим псевдонимом и скопирует их MAC-адрес. Совпадающий интерфейс не обязательно должен иметь тот же тип или исходную сеть. ADD_MAC_ADDRESSES_FUZZY попытается сопоставить входящие интерфейсы с интерфейсами существующего домена, имеющими тот же тип и исходную сеть/устройство. Результат может не всегда соответствовать ожиданиям, особенно если домен содержит несколько интерфейсов, подключенных к одному устройству узла, и только у некоторых из этих устройств есть элементы <mac>. Будьте осторожны и проведите тестирование для вашего конкретного случая использования! Варианты: `"ADD_UUID"` ← (по умолчанию) `"ADD_MAC_ADDRESSES"` `"ADD_MAC_ADDRESSES_FUZZY"` По умолчанию: `["ADD_UUID"]`
name псевдонимы: guest string	Имя управляемой гостевой виртуальной машины. Обратите внимание, что виртуальная машина должна быть предварительно определена с помощью XML. Этот параметр обязателен, если только command не имеет значение `list_vms` или `info`.
state string	Обратите внимание, что выполнение запросов состояния, например `shutdown`, может задерживаться, поскольку они относятся только к состояниям виртуальных машин. После запуска гостевая система может быть доступна не сразу. Параметры state и command взаимоисключающие, кроме случая, когда command=list_vms. В этом случае будут перечислены все виртуальные машины в указанном состоянии. Варианты: `"destroyed"` `"paused"` `"running"` `"shutdown"`
uri string	URI подключения к libvirt. По умолчанию: `"qemu:///system"`
xml string	XML-документ, используемый командой define. Необходимо указать необработанное содержимое XML с помощью `lookup`. XML нельзя задавать ссылкой на файл.

Атрибуты

Атрибут	Поддержка	Описание
check_mode	Поддержка: полная	Поддерживает check_mode.

Примеры

# a playbook task line:
- name: Start a VM
  community.libvirt.virt:
    name: alpha
    state: running

# /usr/bin/ansible invocations
# ansible host -m virt -a "name=alpha command=status"
# ansible host -m virt -a "name=alpha command=get_xml"
# ansible host -m virt -a "name=alpha command=create uri=lxc:///"

# defining and launching an LXC guest
- name: Define a VM
  community.libvirt.virt:
    command: define
    xml: "{{ lookup('template', 'container-template.xml.j2') }}"
    uri: 'lxc:///'
- name: start vm
  community.libvirt.virt:
    name: foo
    state: running
    uri: 'lxc:///'

# setting autostart on a qemu VM (default uri)
- name: Set autostart for a VM
  community.libvirt.virt:
    name: foo
    autostart: true

# Defining a VM and making is autostart with host. VM will be off after this task
- name: Define vm from xml and set autostart
  community.libvirt.virt:
    command: define
    xml: "{{ lookup('template', 'vm_template.xml.j2') }}"
    autostart: true

# Undefine VM only, if it has no existing nvram or other metadata
- name: Undefine qemu VM
  community.libvirt.virt:
    command: undefine
    name: foo

# Undefine VM and force remove all of its related metadata (nvram, snapshots, etc.)
- name: "Undefine qemu VM with force"
  community.libvirt.virt:
    command: undefine
    name: foo
    force: true

# Undefine VM and remove all of its specified metadata specified
# Result would the same as with force=true
- name: Undefine qemu VM with list of flags
  community.libvirt.virt:
    command: undefine
    name: foo
    flags: managed_save, snapshots_metadata, nvram, checkpoints_metadata

# Undefine VM, but keep its nvram
- name: Undefine qemu VM and keep its nvram
  community.libvirt.virt:
    command: undefine
    name: foo
    flags: keep_nvram

# Listing VMs
- name: List all VMs
  community.libvirt.virt:
    command: list_vms
  register: all_vms

- name: List only running VMs
  community.libvirt.virt:
    command: list_vms
    state: running
  register: running_vms

Возвращаемые значения

Общие возвращаемые значения описаны здесь. Ниже перечислены поля, уникальные для этого модуля:

Ключ	Описание
list_vms list / elements=string	Список виртуальных машин, определенных в удаленной системе. Возвращается: при успешном выполнении Пример: `["build.example.org", "dev.example.org"]`
status string	Состояние виртуальной машины: работает, аварийно завершена, приостановлена или выключена. Возвращается: при успешном выполнении Пример: `"success"`

Авторы

Ansible Core Team
Michael DeHaan
Seth Vidal (@skvidal)

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

© 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/libvirt/virt_module.html