community.libvirt.virt 模块 – 管理 libvirt 支持的虚拟机

注意

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

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

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

要在 playbook 中使用它，请指定：community.libvirt.virt。

概要 

管理 libvirt 支持的虚拟机。

要求 

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

python >= 2.6
libvirt python 绑定

参数 

参数	注释
autostart 布尔值	在主机启动时启动 VM。选项 `false` `true`
command 字符串	除了状态管理之外，还可以使用各种非幂等命令。选项 `"create"` `"define"` `"destroy"` `"freemem"` `"get_xml"` `"info"` `"list_vms"` `"nodeinfo"` `"pause"` `"shutdown"` `"start"` `"status"` `"stop"` `"undefine"` `"unpause"` `"virttype"`
flags 列表 / 元素=字符串	传递其他参数。目前仅使用命令 `undefine` 实现。使用 `undefine` 指定应删除哪些元数据。能够 `undefine` 带有 UEFI nvram 的访客的有用选项。`nvram` 和 `keep_nvram` 是冲突的并且互斥的。如果应删除所有相关元数据，请考虑选项 `force`。选项 `"managed_save"` `"snapshots_metadata"` `"nvram"` `"keep_nvram"` `"checkpoints_metadata"`
force 布尔值	强制执行操作。目前仅使用命令 `undefine` 实现。可以使用此选项来代替提供所有 `flags`。如果 `true`，则 `undefine` 还会删除任何相关的 nvram 或其他元数据（如果存在）。如果 `false` 或未设置，则仅当不存在 nvram 或其他元数据时，`undefine` 才会执行。否则，该任务将失败，并且访客将被保留定义而不进行更改。`true` 和选项 `flags` 不应一起提供。在这种情况下，`undefine` 将忽略 `true`，仅考虑 `flags` 并发出警告。选项 `false` `true`
mutate_flags 列表 / 元素=字符串	对于每个 mutate_flag，我们将以某种方式修改给定的 XML ADD_UUID 将现有域的 UUID 添加到 XML（如果缺少） ADD_MAC_ADDRESSES 将查找现有域中具有匹配别名的接口，并将 MAC 地址复制过来。匹配的接口不需要是相同的类型或源网络。 ADD_MAC_ADDRESSES_FUZZY 将尝试将传入接口与共享相同类型和源网络/设备的现有域的接口进行匹配。它可能并不总是产生预期的结果，特别是当域有多个接口连接到同一主机设备，并且只有其中一些设备具有 <mac> 时。请谨慎使用，并针对您的特定用例进行一些测试！选项 `"ADD_UUID"` ← (默认) `"ADD_MAC_ADDRESSES"` `"ADD_MAC_ADDRESSES_FUZZY"` 默认值： `["ADD_UUID"]`
name 别名：guest 字符串	被管理的访客 VM 的名称。请注意，VM 必须事先使用 XML 定义。除非 command 是 `list_vms` 或 `info`，否则此选项是必需的。
state 字符串	请注意，状态请求（如 `shutdown`）可能会有一些延迟，因为这些仅指 VM 状态。启动访客后，它可能不会立即访问。state 和 command 是互斥的，除非 command=list_vms。在这种情况下，将列出处于指定状态的所有 VM。选项 `"destroyed"` `"paused"` `"running"` `"shutdown"`
uri 字符串	Libvirt 连接 URI。默认值： `"qemu:///system"`
xml 字符串	与 define 命令一起使用的 XML 文档。必须使用 `lookup` 的原始 XML 内容。XML 不能引用文件。

示例 

# 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:
    name: foo

# Undefine VM and force remove all of its related metadata (nvram, snapshots, etc.)
- name: "Undefine qemu VM with force"
  community.libvirt.virt:
    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:
    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:
    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 列表 / 元素=字符串	在远程系统上定义的 vms 列表。已返回：成功示例： `["build.example.org", "dev.example.org"]`
status 字符串	VM 的状态，包括运行、崩溃、暂停和关闭。已返回：成功示例： `"success"`

作者

Ansible 核心团队
Michael DeHaan
Seth Vidal (@skvidal)