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 布尔值	主机启动时启动虚拟机。 选项 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 或未设置，则 undefine 仅在不存在 nvram 或其他元数据时执行。否则，任务失败，并且客户机保持定义不变。 true 和选项 flags 不应一起提供。在这种情况下，undefine 将忽略 true，仅考虑 flags 并发出警告。 选项 false true
mutate_flags 列表 / 元素=字符串	对于每个 mutate_flag，我们将以某种方式修改给定的 XML ADD_UUID 将在缺少的情况下将现有域的 UUID 添加到 xml ADD_MAC_ADDRESSES 将查找现有域中具有匹配别名的接口并复制 MAC 地址。匹配的接口不需要是相同类型或源网络。 ADD_MAC_ADDRESSES_FUZZY 将尝试将传入的接口与共享相同类型和源网络/设备的现有域的接口匹配。它可能并不总是产生预期的结果，特别是如果域有多个接口连接到同一个主机设备，而只有其中一些设备具有 时。请谨慎使用，针对您的特定用例进行一些测试！ 选项 "ADD_UUID" ← (默认) "ADD_MAC_ADDRESSES" "ADD_MAC_ADDRESSES_FUZZY" 默认值： ["ADD_UUID"]
name 别名：guest 字符串	正在管理的客户机虚拟机的名称。请注意，虚拟机必须使用 xml 预先定义。 除非 *command* 为 list_vms 或 info，否则此选项是必需的。
state 字符串	请注意，对于 shutdown 等状态请求可能存在一些滞后，因为这些请求仅指虚拟机状态。启动客户机后，它可能无法立即访问。 state 和 command 是相互排斥的，除非 command=list_vms。在这种情况下，将列出指定状态下的所有虚拟机。 选项 "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 列表 / 元素=字符串	远程系统上定义的虚拟机列表。 返回值： 成功 示例： ["build.example.org", "dev.example.org"]
状态 字符串	虚拟机的状态，包括运行中、崩溃、暂停和关机。 返回值： 成功 示例： "success"

作者

• Ansible核心团队

• Michael DeHaan

• Seth Vidal (@skvidal)

资源链接

• 问题追踪器
• 代码库（源码）