Libvirt 虚拟机

这个角色用于在 KVM 虚拟机监视器上配置和创建（或销毁）虚拟机。

要求

主机应启用虚拟化技术 (VT) 并预先配置有 libvirt/KVM。

角色变量

• libvirt_vm_default_console_log_dir: 用于存储虚拟机控制台日志的默认目录，如果没有提供虚拟机特定的日志文件路径。默认为 "/var/log/libvirt-consoles"。

• libvirt_vm_default_uuid_deterministic: UUID 是否应该通过对虚拟机名称进行哈希计算。如果不使用，则 UUID 在定义虚拟机时由 libvirt 随机生成。默认为 False。

• libvirt_vm_image_cache_path: 用于缓存下载镜像的目录。默认为 "/tmp/"。

• libvirt_volume_default_images_path: 存储实例镜像的目录。默认为 '/var/lib/libvirt/images'。

• libvirt_volume_default_type: 实例使用的后备卷类型。默认为 volume。可选项包括 block、file、network 和 volume。

• libvirt_volume_default_format: 角色创建的卷的格式。默认为 qcow2。可选项包括 raw、qcow2、vmdk。详细信息请参见 man virsh。

• libvirt_volume_default_device: 控制设备在来宾操作系统中的显示方式。默认为 disk。可选项包括 cdrom 和 disk。

• libvirt_vm_engine: 虚拟化引擎。如果未设置，角色将尝试自动检测使用的最佳引擎。

• libvirt_vm_emulator: 模拟器二进制文件的路径。如果未设置，角色将尝试自动检测要使用的正确模拟器。

• libvirt_cpu_mode_default: 如果 libvirt_cpu_mode 或 vm.cpu_mode 未定义，则为默认的 CPU 模式。

• libvirt_vm_arch: CPU 架构，默认为 x86_64。

• libvirt_vm_uri: 覆盖 libvirt 连接 URI。有关更多详细信息，请参见 libvirt 文档。

• libvirt_vm_virsh_default_env: 此字典中的变量会添加到执行 virsh 命令时使用的环境中。

• libvirt_vm_clock_offset: 如果定义，实例的时钟偏移将设置为提供的值。当未定义时，同步设置为 localtime。

• libvirt_vm_trust_guest_rx_filters: 是否信任来宾接收过滤器。这与虚拟机接口的 trustGuestRxFilters 属性相映射。默认为 false。

• libvirt_vms: 要创建/销毁的虚拟机列表。每个虚拟机可能有以下属性：

  • state: 设置为 present 创建或 absent 销毁虚拟机。默认为 present。

  • name: 分配给虚拟机的名称。

  • uuid: 要手动分配给虚拟机的 UUID。如果指定，则不使用 uuid_deterministic 或 libvirt_vm_default_uuid_deterministic。

  • uuid_deterministic: 覆盖 libvirt_vm_default_uuid_deterministic 中的默认值。

  • memory_mb: 分配给虚拟机的内存，以兆字节为单位。

  • vcpus: 分配给虚拟机的虚拟 CPU 核心数。

  • machine: 虚拟机类型。如果 libvirt_vm_engine 为 kvm 默认为 None，否则为 pc-1.0。

  • cpu_mode: 虚拟机 CPU 模式。如果 libvirt_vm_engine 为 kvm 默认为 host-passthrough，否则为 host-model。可以设置为 none 以不配置 CPU 模式。

  • clock_offset: 覆盖 libvirt_vm_clock_offset 中的默认值。

  • enable_vnc: 如果为真，则在 localhost 上启用 VNC 监听，以与 VirtManager 和类似工具一起使用。

  • enable_spice: 如果为真，则启用 SPICE 监听，以与虚拟机管理器和类似工具一起使用。

  • enable_guest_virtio: 如果为真，则启用来宾 virtio 设备，以与 Qemu 客户端代理一起使用。

  • volumes: 附加到虚拟机的卷列表。每个卷通过以下字典定义：

    • type: 实例使用的后备卷类型。所有 libvirt_volume_default_type 的选项在这里都是有效的。默认为 libvirt_volume_default_type。
    • pool: 中卷分配应使用的存储池的名称或 UUID。当 type 为 volume 时必需。
    • name: 与创建的卷关联的名称；对于 file 类型的卷，如果希望创建时包含扩展名，则包括扩展名。
    • file_path: file 类型卷的映像应该放置的位置；默认为 libvirt_volume_default_images_path。
    • device: 控制设备在来宾操作系统中的显示方式。所有 libvirt_volume_default_device 的选项在这里都是有效的。默认为 libvirt_volume_default_type。
    • capacity: 卷容量，当类型为 network 时可以后缀 k、M、G、T、P 或 E，当类型为 disk 时则为 MB、GB、TB 等（当类型为 disk 或 network 时必需）。
    • auth: 如果需要，身份验证详细信息。如果需要身份验证，则需要提供 username、type 和 uuid 或 usage。不应同时提供 uuid 和 usage。
    • source: 当类型为 network 时，远程卷的来源。“protocol”、“name”和“hosts_list”必须提供。“port”是可选的。
    • format: 卷的格式。所有 libvirt_volume_default_format 的选项在这里都是有效的。默认为 libvirt_volume_default_format。
    • image: （可选）初始化卷的图像 URL（完整复制）。
    • checksum: （可选）图像的校验和，以避免不必要的下载。
    • backing_image: （可选）假定与相同存储池的后备卷的名称（写时复制）。
    • image 和 backing_image 是互斥选项。
    • target: （可选）手动影响卷的类型和顺序。
    • dev: （可选）类型为 block 时的块设备路径。
    • remote_src: （可选）当类型为 file 或 block 时，指定 image 是否指向远程文件（true）或指向启动脚本的主机上的本地文件（false）。默认为 true。

  • usb_devices: 应从主机提供给虚拟机的 USB 设备列表。

    每个 USB 设备通过以下字典定义：

    • vendor: USB 设备的供应商 ID。
    • product: USB 设备的产品 ID。

    注意 - 如果虚拟机已配置但 USB 设备未连接，Libvirt 会报错。

    要从运行的主机（以 sudo / root 身份且连接了 USB 设备）获取 USB 设备的供应商 ID 和产品 ID，请运行 lsusb -v。以下是附加的 Sandisk USB 闪存驱动器示例，供应商 ID: 0x0781 和产品 ID: 0x5567。

    lsusb -v | grep -A4 -i sandisk
    
      idVendor           0x0781 SanDisk Corp.
      idProduct          0x5567 Cruzer Blade
      bcdDevice            1.00
      iManufacturer           1 
      iProduct                2 
    

  • interfaces: 附加到虚拟机的网络接口列表。每个网络接口通过以下字典定义：

    • type: 接口的类型。可选值：

      • network: 将接口附加到指定的 Libvirt 虚拟网络。这是默认值。
      • direct: 使用 macvtap 驱动直接将接口附加到主机的物理接口之一。

    • network: 接口应附加到的网络名称。仅当接口 type 为 network 时必须指定。

    • mac: 虚拟实例的“硬件”地址，如果缺失则会创建一个。

    • source: 定义此虚拟机接口应附加到的主机接口的字典。仅当接口 type 为 direct 时，必须指定。包括以下属性：

      • dev: 此虚拟机接口应附加到的主机接口的名称。
      • mode: 选项包括 vepa、bridge、private 和 passthrough。详细信息请参见 man virsh。默认为 vepa。

    • trust_guest_rx_filters: 是否信任来宾接收过滤器。这与虚拟机接口的 trustGuestRxFilters 属性相映射。默认为 libvirt_vm_trust_guest_rx_filters。

    • model: 接口模型的名称。例如 e1000 或 ne2k_pci，如果未定义则默认为 virtio。

    • alias: 可选的接口别名。这可以用于通过名称将特定网络配置与持久网络设备关联。用户定义的别名始终以 ua- 为前缀以确保合规（不带 ua- 的别名会被 libvirt 忽略）。如果未定义，默认为由 libvirt 管理的 vnetX。

  • console_log_enabled: 如果为 true，则将控制台输出记录到 console_log_path 指定的文件中，而 不是 路由到 PTY。如果 false，则直接将终端输出路由到串行端口 0 的 PTY。默认为 false。

  • console_log_path: 控制台日志文件的路径。默认为 {{ libvirt_vm_default_console_log_dir }}/{{ name }}-console.log。

  • start: 在定义虚拟机后是否立即启动虚拟机。默认为 true。

  • autostart: 是否在主机启动时启动虚拟机。默认为 true。

  • boot_firmware: 可以是 bios 或 efi。默认为 bios。

  • xml_file: 可选地提供一个修改后的 XML 模板。根据默认的 vm.xml.j2 模板进行基本定制，以包含角色使用的预期 jinja 表达式。

注意：以下变量已被弃用：libvirt_vm_state、libvirt_vm_name、libvirt_vm_memory_mb、libvirt_vm_vcpus、libvirt_vm_engine、libvirt_vm_machine、libvirt_vm_cpu_mode、libvirt_vm_volumes、libvirt_vm_interfaces 和 libvirt_vm_console_log_path。如果变量 libvirt_vms 未设置，则其默认值将是包含使用这些弃用变量的虚拟机规范的单例列表。

依赖项

如果使用 qcow2 格式的驱动，则需要 qemu-img（在 qemu-utils 包中）。

示例剧本

---
- name: 创建虚拟机
  hosts: hypervisor
  roles:
    - role: stackhpc.libvirt-vm
      libvirt_vms:
        - state: present
          name: 'vm1'
          memory_mb: 512
          vcpus: 2
          volumes:
            - name: 'data1'
              device: 'disk'
              format: 'qcow2'
              capacity: '400GB'
              pool: 'my-pool'
            - name: 'debian-10.2.0-amd64-netinst.iso'
              type: 'file'
              device: 'cdrom'
              format: 'raw'
              target: 'hda'  # ide 总线上的第一个设备
            - name: 'networkfs'
              type: 'network'
              format: 'raw'
              capacity: '50G'
              auth:
                username: 'admin'
                type: 'ceph'
                usage: 'rbd-pool'
              source:
                protocol: 'rbd'
                name: 'rbd/volume'
                hosts_list:
                  - 'mon1.example.org'
                  - 'mon2.example.org'
                  - 'mon3.example.org'
            - type: 'block'
              format: 'raw'
              dev: '/dev/sda'

          interfaces:
            - network: 'br-datacentre'
          
          usb_devices:
            - vendor: '0x0781'
              product: '0x5567'

        - state: present
          name: 'vm2'
          memory_mb: 1024
          vcpus: 1
          volumes:
            - name: 'data2'
              device: 'disk'
              format: 'qcow2'
              capacity: '200GB'
              pool: 'my-pool'
            - name: 'filestore'
              type: 'file'
              file_path: '/srv/cloud/images'
              capacity: '900GB'
          interfaces:
            - type: 'direct'
              source:
                dev: 'eth123'
                mode: 'private'
            - type: 'bridge'
              source:
                dev: 'br-datacentre'

作者信息

• Mark Goddard (mark@stackhpc.com)