libvirt-instance

libvirt-instance是一个用于创建虚拟机的命令行工具。它使用Libvirt API，并与其他Libvirt应用程序兼容。

将其视为对virt-install的一个更有观点的替代品。

项目目标

• 通过提供将一些常用配置作为预设分组的方式，使操作员通过命令行界面创建Libvirt虚拟机（VM）变得更加简单。
• 提供一个方便的方式来在Libvirt上部署云实例，而无需使用元数据服务（使用NoCloud数据源向实例提供元数据）。

该工具不支持删除Libvirt资源，并且到目前为止没有计划实现该功能。任何删除操作都可以使用virsh执行。

安装

此软件包依赖于libvirt-python。在虚拟环境中安装可能需要安装GCC、Python3和Libvirt开发操作系统包。如果您使用RockyLinux 9，请运行dnf --enablerepo=devel install gcc python3-devel libvirt-devel以安装这些包。

否则（当不使用虚拟环境时），安装python3-libvirt操作系统包应该足够。

可以通过运行pip3 install libvirt-instance安装libvirt-instance。它需要Python 3.9+才能运行。

展示

虽然本地和远程的Libvirt守护进程都受到支持，但以下示例为了简化使用了本地Libvirt守护进程。这些命令应该由具有足够Libvirt访问权限的用户执行。

URI=qemu:///system

# All operations on disks are done using the Libvirt pool APIs.
# Libvirt doesn't usually come with any storage pools defined, so let's define
# one named "images".
virsh -c "$URI" pool-define-as images dir --target /var/lib/libvirt/images
virsh -c "$URI" pool-autostart images
virsh -c "$URI" pool-start images

# Create a config file with a preset for disks from the above pool,
# and a preset for network interfaces in the default Libvirt NAT network (this
# network exists by default).
cat <<"EOF" >./libvirt-instance-config.yaml
preset:
  disk:
    local:
      type: volume
      pool: images
      bus: virtio
      cache: none
  interface:
    nat:
      type: network
      model-type: virtio
      network: default
EOF

# Fetch a cloud image from the Internet and upload it to Libvirt as a volume,
# so we can use it as the base image for VM disks.
curl -LfsS \
  https://download.fedoraproject.org/pub/fedora/linux/releases/37/Cloud/x86_64/images/Fedora-Cloud-Base-37-1.7.x86_64.raw.xz \
  | xzcat >./f37-cloud-amd64.raw
image_size=$(stat --printf="%s" ./f37-cloud-amd64.raw)
virsh -c "$URI" vol-create-as images f37-cloud-amd64.raw "${image_size}b" --format raw
virsh -c "$URI" vol-upload f37-cloud-amd64.raw ./f37-cloud-amd64.raw --pool images

# Generate a passphraseless SSH key for this demo.
ssh-keygen -f mykey -N ''

# Create user-data.
cat <<EOF >./user-data
#cloud-config
ssh_authorized_keys:
  - $(cat ./mykey.pub)
packages:
  - nginx
runcmd:
  - systemctl start nginx
EOF

# Create network-config.
cat <<"EOF" >./network-config
version: 2
ethernets:
    eth0:
        dhcp4: false
        dhcp6: false
        addresses:
          - 192.168.122.10/24
        gateway4: 192.168.122.1
        nameservers:
          addresses:
            - 1.1.1.1
            - 8.8.8.8
EOF

# Create the VM.
# headless-server-x86_64 is a built-in domain preset.
instance_id=$(
  libvirt-instance -c "$URI" --config-file ./libvirt-instance-config.yaml create \
                   --domain-preset headless-server-x86_64 \
                   --memory 2GiB \
                   --vcpu 2 \
                   --disk local,5GiB,source=f37-cloud-amd64.raw \
                   --nic nat \
                   --cloud-seed-disk=local \
                   --cloud-user-data-file ./user-data \
                   --cloud-network-config-file ./network-config \
                   myvm \
    | jq -er '."instance-id"')

# Start the VM.
virsh -c "$URI" start "$instance_id"

# Wait until cloud-init has finished executing.
until
  ssh -i mykey \
      -o IdentitiesOnly=true \
      -o StrictHostKeyChecking=no \
      -o UserKnownHostsFile=/dev/null \
      fedora@192.168.122.10 \
      cloud-init status --wait
do
  sleep 1
done

# Get a page from Nginx on the VM.
curl http://192.168.122.10/

# Cleanup.
virsh -c "$URI" destroy "$instance_id"
virsh -c "$URI" undefine "$instance_id" --nvram --remove-all-storage

更多示例

创建基于非镜像的虚拟机也是一个选择。

具有两个磁盘和以PXE启动作为首选选项的虚拟机

libvirt-instance -c "$URI" --config-file ./libvirt-instance-config.yaml create \
                 --domain-preset headless-server-x86_64 \
                 --memory 2GiB \
                 --vcpu 2 \
                 --disk local,5GiB,boot-order=2 \
                 --disk local,10GiB \
                 --nic nat,boot-order=1 \
                 myvm

还支持替代/非原生架构。 libvirt-instance 内置两个域预设 - headless-server-x86_64 和 headless-server-aarch64。更多预设可以在配置文件中定义。

运行 libvirt-instance get-config 查看当前定义的预设。

具有加密磁盘的虚拟机

cat <<EOF >./secret.xml
<secret ephemeral='no' private='yes'>
  <uuid>8eb167eb-b3bb-4047-91f4-a3ca1eb643ab</uuid>
</secret>
EOF

virsh -c "$URI" secret-define ./secret.xml

virsh -c "$URI" secret-set-value 8eb167eb-b3bb-4047-91f4-a3ca1eb643ab --interactive
# Enter new value for secret:

# encryption-secret could also be specified in a preset in libvirt-instance-config.yaml.
libvirt-instance -c "$URI" --config-file ./libvirt-instance-config.yaml create \
                 --domain-preset headless-server-x86_64 \
                 --memory 2GiB \
                 --vcpu 2 \
                 --disk local,5GiB,encryption-secret=8eb167eb-b3bb-4047-91f4-a3ca1eb643ab \
                 --disk local,10GiB,encryption-secret=8eb167eb-b3bb-4047-91f4-a3ca1eb643ab \
                 --nic nat \
                 myvm

在非ARM KVM主机上的基于ARM云镜像的Fedora虚拟机

curl -LfsS \
  https://download.fedoraproject.org/pub/fedora/linux/releases/37/Cloud/aarch64/images/Fedora-Cloud-Base-37-1.7.aarch64.raw.xz \
  | xzcat >./f37-cloud-arm64.raw
image_size=$(stat --printf="%s" ./f37-cloud-arm64.raw)
virsh -c "$URI" vol-create-as images f37-cloud-arm64.raw "${image_size}b" --format raw
virsh -c "$URI" vol-upload f37-cloud-arm64.raw ./f37-cloud-arm64.raw --pool images

libvirt-instance -c "$URI" --config-file ./libvirt-instance-config.yaml create \
                 --domain-preset headless-server-aarch64 \
                 --cpu-model cortex-a57 \
                 --domain-type qemu \
                 --memory 2GiB \
                 --vcpu 2 \
                 --disk local,5GiB,source=f37-cloud-arm64.raw \
                 --nic nat \
                 --cloud-seed-disk=local \
                 --cloud-user-data-file ./user-data \
                 --cloud-network-config-file ./network-config \
                 myvm

配置文件

一些默认和预设已经内置。配置文件是一种添加更多预设或覆盖现有预设和设置的方法。

目前支持三种类型的预设： domain、disk 和 interface。

配置文件的默认位置是 /etc/libvirt-instance-config.yaml。使用 CLI 参数 --config-file 可以覆盖该位置。

运行 libvirt-instance get-config 查看当前配置。

域预设

示例配置片段

preset:
  domain:
    windows-server:
      arch-name: x86_64
      machine-type: pc
      xml-file: /path/to/windows-server-base.xml

上述预设可以在创建新虚拟机时使用 CLI 中的 --domain-preset windows-server 选项进行选择。

arch-name 可以是目标主机支持的任何架构（例如 x86_64、aarch64）。

machine-type 可以是任何机器类型（例如 pc、q35、virt），这些类型由所选架构支持。

xml-file 指定一个包含一些 域 XML 的文件，用作创建的虚拟机的基础。工具将自动使用预设和 CLI 参数中的信息将架构、域、机器类型、CPU（数量和型号）、内存大小、网络接口、磁盘（包括任何必要的SCSI控制器）条目填充到基本 XML 中。

域 XML 可以通过 xml 键内联提供。

磁盘预设

所有磁盘操作都使用 Libvirt 池 API 完成，因此磁盘预设只能引用 Libvirt 池。

目前支持 dir、logical 和 rbd 池。

示例配置片段

preset:
  disk:
    ceph-ssd:
      type: volume
      pool: ceph-rbd-ssd
      bus: scsi
      cache: writeback
    ceph-hdd:
      type: volume
      pool: ceph-rbd
      bus: virtio
      cache: writeback
    local-secure:
      type: volume
      pool: images
      bus: virtio
      cache: none
      encryption-format: luks
      encryption-secret: 8eb167eb-b3bb-4047-91f4-a3ca1eb643ab
      encryption-cipher: aes-256-cbc-sha256
      encryption-ivgen: essiv-sha256
    x86worker:
      type: volume
      pool: images
      bus: virtio
      cache: none
      source: fedora37-cloud-amd64.raw
      source-pool: ceph-rbd

上述 CLI 示例： --disk ceph-ssd,16GiB --disk ceph-hdd,1TiB、--disk x86worker,32GiB。

目前支持 type 的唯一值是 volume。

pool 指定目标 Libvirt 池以用于卷。此池也将用于在向域 XML 添加磁盘设备时检索有关卷的信息。

bus（可选）对于 virtio-blk 磁盘是 virtio，对于 virtio-scsi 磁盘是 scsi。默认为 virtio。

cache（可选）指定 Libvirt 支持的任何磁盘缓存模式。默认为 none。

source（可选）指定包含磁盘基本镜像的 Libvirt 卷。

source-pool（可选）指定 source 图像的 Libvirt 池。未指定时默认为 pool 的相同值。

boot-order（可选）设置设备在引导顺序中的位置。

encryption-secret（可选）指定一个 Libvirt 密钥 UUID，并在设置时启用磁盘加密。

encryption-format（可选）设置加密格式（默认为 luks）。

encryption-cipher（可选）指定加密密文详细信息。格式是 name-size-mode-hash，例如 aes-128-cbc-sha256。

encryption-ivgen（可选）指定初始化向量生成算法。格式是 name-hash，例如 essiv-sha256。

有关加密参数的更多信息，请参阅 Libvirt 存储卷加密 XML 格式文档。

在大多数情况下，域XML中生成的磁盘设备描述将是卷引用（<disk type="volume">）。一些池类型（例如rbd）目前还不支持后备卷磁盘（参见domain_conf.c#L29929-L29939）。当从这样的池添加磁盘时，libvirt-instance将透明地将磁盘定义内联到域XML中，使用池的信息（MONs、认证）。

接口预设

目前支持bridge和network类型接口。

示例配置片段

preset:
  interface:
    nat:
      type: network
      model-type: virtio
      network: default
    dmz:
      type: bridge
      model-type: virtio
      bridge: br0
    storage:
      type: bridge
      model-type: virtio
      bridge: br1
      mtu: 9000

上述CLI示例：--nic nat，--nic dmz --nic storage。

model-type（可选）指定Libvirt支持的任何模型类型（例如virtio、e1000、rtl8139等）。默认为virtio。

network指定type: network接口的Libvirt网络名称。

bridge指定type: bridge接口的现有网络桥名称。

mtu（可选）设置主机端TAP接口的MTU。注意，客机内部也需要配置MTU。

boot-order（可选）设置设备在引导顺序中的位置。

技术上，mac-address（可选）也可以在接口预设中指定，但更合理的是在命令行上指定任何MAC地址（例如--nic nat,mac-address=00:11:22:33:44:55:66）。

CLI选项

请参阅libvirt-instance --help和libvirt-instance create --help以获取CLI选项的完整列表。在“展示”和“更多示例”部分也有一些示例，说明了不同选项如何协同工作。

--disk <SPEC>可以指定多次，以将多个磁盘连接到虚拟机。磁盘使用<VM-NAME>-disk<N>命名方案创建。如果目标池中已存在具有相同名称的卷，则libvirt-instance将退出并显示错误。磁盘按命令行上指定的顺序连接到实例。

磁盘规范中可以包含pool、bus、cache、source、source-pool和boot-order选项，这些选项的优先级高于所选预设中对应的任何选项。例如：--disk local,10GiB,bus=scsi,cache=writeback,source=jammy-server-cloudimg-amd64.img。

--nic <SPEC>也可以指定多次。与--disk选项类似，--nic支持mac-address、model-type、network、bridge、mtu和boot-order选项。

--cloud-seed-disk启用cloud-init支持，当指定了--cloud-user-data-file或--cloud-network-config-file时是必需的。它类似于--disk，但没有大小部分。--cloud-seed-disk指定创建NoCloud种子磁盘时要使用的磁盘预设。种子磁盘的命名模式为<VM-NAME>-seed。示例：--cloud-seed-disk local,bus=scsi。

开发

请参阅DEVELOPING.md