diff --git "a/docs/zh/docs/StratoVirt/\345\257\271\346\216\245iSula\345\256\211\345\205\250\345\256\271\345\231\250.md" "b/docs/zh/docs/StratoVirt/\345\257\271\346\216\245iSula\345\256\211\345\205\250\345\256\271\345\231\250.md" index ee9471f8c4ac3b31f33d5a738c8f63afdc09ca11..6f47f30d581ec47ecb938a21c571439e465c0756 100644 --- "a/docs/zh/docs/StratoVirt/\345\257\271\346\216\245iSula\345\256\211\345\205\250\345\256\271\345\231\250.md" +++ "b/docs/zh/docs/StratoVirt/\345\257\271\346\216\245iSula\345\256\211\345\205\250\345\256\271\345\231\250.md" @@ -1,146 +1,433 @@ -# 对接iSula安全容器 +# 管理虚拟机 ## 概述 -为了给容器提供更好的隔离环境，提高系统安全性，可以使用 iSula 安全容器，即将 StratoVirt 对接 iSula 安全容器。 +StratoVirt可以查询虚拟机信息并对虚拟机的资源和生命周期进行管理。由于StratoVirt使用QMP管理虚拟机，所以查询虚拟机信息，也需要先连接到虚拟机。 -## 对接iSula安全容器 -### **前提条件** -已安装 iSulad 和 kata-containers，并确保 iSulad 支持 kata-runtime 容器运行时和 devicemapper 存储驱动。 +## 查询虚拟机信息 -此处给出安装 iSulad 和 kata-containers 并进行相应配置的参考方法。 +### 简介： -1. 配置 yum 源，使用 root 权限安装 iSulad 和 kata-containers ： +StratoVirt可以查询虚拟机状态、vCPU拓扑信息、vCPU上线情况等。 - ```shell - # yum install iSulad - # yum install kata-containers - ``` +### 查询状态 -2. 制作并配置存储 Storage： +使用query-status命令查询虚拟机的运行状态。 - 需要用户规划好磁盘如/dev/sdxx,该磁盘会被格式化。 +- 用法： - ```shell - # pvcreate /dev/sdxx - # vgcreate isulaVG0 /dev/sdxx - # lvcreate --wipesignatures y -n thinpool isulaVG0 -l 95%VG - # lvcreate --wipesignatures y -n thinpoolmeta isulaVG0 -l 1%VG - # lvconvert -y --zero n -c 512K --thinpool isulaVG0/thinpool --poolmetadata isulaVG0/thinpoolmeta - ``` + **{ "execute": "query-status" }** - 在配置文件 /etc/lvm/profile/isulaVG0-thinpool.profile 中添加如下： +- 示例： - ``` - activation { - thin_pool_autoextend_threshold=80 - thin_pool_autoextend_percent=20 - } - ``` +``` +<- { "execute": "query-status" } +-> { "return": { "running": true,"singlestep": false,"status": "running" } +``` - 更改配置文件/etc/isulad/daemon.json中的storage-driver 和 storage-opts 如下：将默认存储驱动类型 overlay 配置成 devicemapper 。 - ``` - "storage-driver": "devicemapper", - "storage-opts": [ - "dm.thinpooldev=/dev/mapper/isulaVG0-thinpool", - "dm.fs=ext4", - "dm.min_free_space=10%" - ], - ``` -3. 重启 isulad ： +### 查询拓扑 - ```shell - # systemctl daemon-reload - # systemctl restart isulad - ``` +使用query-cpus命令查询所有CPU的拓扑结构。 -4. 确认 iSula 存储驱动是否配置成功： +- 用法： - ```shell - # isula info - ``` +**{ "execute": "query-cpus" }** - 若回显有如下信息，说明配置成功。 +- 示例： - ``` - Storage Driver: devicemapper - ``` +``` +<- { "execute": "query-cpus" } +-> {"return":[{"CPU":0,"arch":"x86","current":true,"halted":false,"props":{"core-id":0,"socket-id":0,"thread-id":0},"qom_path":"/machine/unattached/device[0]","thread_id":8439},{"CPU":1,"arch":"x86","current":true,"halted":false,"props":{"core-id":0,"socket-id":1,"thread-id":0},"qom_path":"/machine/unattached/device[1]","thread_id":8440}]} +``` -5. 打开/etc/isulad/daemon.json文件。如果没有配置kata-runtime，则配置runtime为kata-runtime。 +### 查询vCPU上线情况 - ```json - "runtimes": { - "kata-runtime": { - "path": "/usr/bin/kata-runtime", - "runtimeArgs": [ - "--kata-config", - "/usr/share/defaults/kata-containers/configuration.toml" - ] - } - }, - ``` +使用query-hotpluggable-cpus命令查询所有vCPU的online/offline情况。 - +- 用法： -### **对接指导** +**{ "execute": "query-hotpluggable-cpus" }** -StratoVirt 对接 iSula 安全容器即 StratoVirt 对接 iSula 安全容器中的 kata-runtime，此处给出对接操作指导。 +- 示例： +``` +<- { "execute": "query-hotpluggable-cpus" } +-> {"return":[{"props":{"core-id":0,"socket-id":0,"thread-id":0},"qom-path":"/machine/unattached/device[0]","type":"host-x86-cpu","vcpus-count":1},{"props":{"core-id":0,"socket-id":1,"thread-id":0},"qom-path":"/machine/unattached/device[1]","type":"host-x86-cpu","vcpus-count":1}]} +``` -1. 在任一目录（例如 /home 目录）新建脚本文件 stratovirt.sh 并使用 root 权限给文件添加执行权限： +其中，online的vCPU具有`qom-path`项，offline的vCPU则没有。 - ```shell - # touch /home/stratovirt.sh - # chmod +x /home/stratovirt.sh - ``` - stratovirt.sh 内容如下，用于指定 StratoVirt 路径： - ``` - #!/bin/bash - export STRATOVIRT_LOG_LEVEL=info # set log level which includes trace, debug, info, warn and error. - /usr/bin/stratovirt $@ - ``` +## 管理虚拟机生命周期 - ​ +### 简介 -2. 修改 kata 配置文件（默认路径为 /usr/share/defaults/kata-containers/configuration.toml ） 。将安全容器的 hypervisor 类型配置为 stratovirt，kernel 配置 StratoVirt 的 kernel 镜像绝对路径，initrd 配置为 kata-containers 的 initrd 镜像文件（使用 yum 安装 kata-containers 时，默认会下载这两个镜像文件并存放在 /var/lib/kata/ 目录，配置时也可以使用其他镜像 ）。 +StratoVirt可以对虚拟机进行启动、暂停、恢复、退出等生命周期进行管理。 - 配置参考如下：配置参考如下： +### 创建并启动虚拟机 - ```shell - [hypervisor.stratovirt] - path = "/home/stratovirt.sh" - kernel = "/var/lib/kata/vmlinux.bin" - initrd = "/var/lib/kata/kata-containers-initrd.img" - block_device_driver = "virtio-mmio" - use_vsock = true - enable_netmon = true - internetworking_model="tcfilter" - sandbox_cgroup_with_emulator = false - disable_new_netns = false - disable_block_device_use = false - disable_vhost_net = true - ``` +根据虚拟机配置可知，可以通过命令行参数或json文件指定虚拟机配置，并在主机通过stratovirt命令创建并启动虚拟机。 -3. 使用 root 权限 和 **isula** 命令运行 busybox 安全容器，完成 StratoVirt 和 安全容器的对接。 +- 使用命令行参数给出虚拟机配置，创建并启动虚拟机的命令如下： - ```shell - # isula run -tid --runtime=kata-runtime --net=none --name test busybox:latest sh - ``` +``` +$ /path/to/stratovirt -[参数1] [参数选项] -[参数2] [参数选项] ... +``` -4. 使用 **isula ps** 确认安全容器 test 正常运行，然后通过以下命令进入 test 容器。 - ``` - # isula exec –ti test sh - ``` - ​ +- 使用json文件给出虚拟机配置，创建并启动虚拟机的命令如下： + +``` +$ /path/to/stratovirt \ + -config /path/to/json \ + -api-channel unix:/path/to/socket +``` + +其中，/path/to/json为json配置文件的路径。/path/to/socket为用户指定的socket文件（如/tmp/stratovirt.socket），使用上述命令会自动创建socket文件。为确保虚拟机能够正常启动，在创建socket文件前确保该文件不存在。 + + + +> ![](./figures/zh-cn_image_0218587436.png) +> +> 虚拟机启动后，内部会有eth0和eth1两张网卡。这两张网卡预留用于网卡热插拔。热插的第一张网卡是eth0，热插的第二张网卡是eth1，目前只支持热插2张virtio-net网卡。 + + + +### 连接虚拟机 + +StratoVirt当前采用QMP管理虚拟机，暂停、恢复、退出虚拟机等操作需要通过QMP连接到虚拟机进行管理。 + +在主机上打开新的命令行窗口B，并使用root权限进行api-channel连接，参考命令如下： + +``` +# ncat -U /path/to/socket +``` + +连接建立后，会收到来自StratoVirt的问候消息，如下所示： + +``` +{"QMP":{"version":{"qemu":{"micro":1,"minor":0,"major":4},"package":""},"capabilities":[]}} +``` + +现在，可以在窗口B中输入QMP命令来管理虚拟机。 + + + +> ![](./figures/zh-cn_image_0218587436.png) +> +> QMP提供了stop、cont、quit和query-status等来管理和查询虚拟机状态。 +> +> 管理虚拟机的QMP命令均在窗口B中进行输入。符号：`<-`表示命令输入，`->`表示QMP结果返回。 + + + + + +### 暂停虚拟机 + +QMP提供了stop命令用于暂停虚拟机，即暂停虚拟机所有的vCPU。命令格式如下： + +**{"execute":"stop"}** + +**示例：** + +使用stop暂停该虚拟机的命令和回显如下： + +``` +<- {"execute":"stop"} +-> {"event":"STOP","data":{},"timestamp":{"seconds":1583908726,"microseconds":162739}} +-> {"return":{}} +``` + + + + + +### 恢复虚拟机 + +QMP提供了cont命令用于恢复处于暂停状态suspend的虚拟机，即恢复虚拟机所有vCPU的运行。命令格式如下： + +**{"execute":"cont"}** + +**示例：** + +使用cont恢复该虚拟机的命令和回显如下： + +``` +<- {"execute":"cont"} +-> {"event":"RESUME","data":{},"timestamp":{"seconds":1583908853,"microseconds":411394}} +-> {"return":{}} +``` + + + + + +### 退出虚拟机 + +QMP提供了quit命令用于退出虚拟机，即退出StratoVirt进程。命令格式如下： + +**{"execute":"quit"}** + +**示例：** + +``` +<- {"execute":"quit"} +-> {"return":{}} +-> {"event":"SHUTDOWN","data":{"guest":false,"reason":"host-qmp-quit"},"timestamp":{"ds":1590563776,"microseconds":519808}} +``` + + + +## 管理虚拟机资源 + +### 热插拔磁盘 + +StratoVirt支持在虚拟机运行过程中调整磁盘数量，即在不中断业务前提下，增加或删除虚拟机磁盘。 + +#### 热插磁盘 + +**用法：** + +``` +{"execute": "blockdev-add", "arguments": {"node-name": "drive-0", "file": {"driver": "file", "filename": "/path/to/block"}, "cache": {"direct": true}, "read-only": false}} +{"execute": "device_add", "arguments": {"id": "drive-0", "driver": "virtio-blk-mmio", "addr": "0x1"}} +``` + +**参数** + +- blockdev-add中的node-name要和device_add中的id一致，如上都是drive-0。 + +- /path/to/block是被热插磁盘的镜像路径，不能是启动rootfs的磁盘镜像。 +- 对于addr来说，它从0x0开始与虚拟机的vda映射，0x1与vdb映射，以此类推。为了兼容QMP协议，"addr"也可以用"lun"代替，但是lun=0与客户机的vdb映射。 +- 由于stratovirt支持的最大virtio-blk磁盘数量是6个，热插磁盘时请注意规格约束。 + + +**示例** + +``` +<- {"execute": "blockdev-add", "arguments": {"node-name": "drive-0", "file": {"driver": "file", "filename": "/path/to/block"}, "cache": {"direct": true}, "read-only": false}} +-> {"return": {}} +<- {"execute": "device_add", "arguments": {"id": "drive-0", "driver": "virtio-blk-mmio", "addr": "0x1"}} +-> {"return": {}} +``` + + + +#### 热拔磁盘 + +**用法：** + +**{"execute": "device_del", "arguments": {"id":"drive-0"}}** + +**参数：** + +id 为热拔磁盘的ID号。 + +**示例** + +``` +<- {"execute": "device_del", "arguments": {"id": "drive-0"}} +-> {"event":"DEVICE_DELETED","data":{"device":"drive-0","path":"drive-0"},"timestamp":{"seconds":1598513162,"microseconds":367129}} +-> {"return": {}} +``` + + + +### 热插拔网卡 + +StratoVirt支持在虚拟机运行过程中调整网卡数量，即在不中断业务前提下，给虚拟机增加或删除网卡。 + +#### 热插网卡 + +**准备工作（需要使用root权限）** + +1. 创建并启用Linux网桥，例如网桥名为 qbr0 的参考命令如下： + +```shell +# brctl addbr qbr0 +# ifconfig qbr0 up +``` + +2. 创建并启用 tap 设备，例如设备名为 tap0 的参考命令如下： + +```shell +# ip tuntap add tap0 mode tap +# ifconfig tap0 up +``` + +3. 添加 tap 设备到网桥： + +```shell +# brctl addif qbr0 tap0 +``` + + +**用法** + +``` +{"execute":"netdev_add", "arguments":{"id":"net-0", "ifname":"tap0"}} +{"execute":"device_add", "arguments":{"id":"net-0", "driver":"virtio-net-mmio", "addr":"0x0"}} +``` + +**参数** + +- netdev_add中的id应该和device_add中的id一致，ifname是后端的tap设备名称。 + +- 对于addr来说，它从0x0开始与虚拟机的eth0映射，0x1和虚拟机的eth1映射。 + +- 由于stratovirt支持的最大virtio-net数量为2个，热插网卡时请注意规格约束。 + + +**示例** + +``` +<- {"execute":"netdev_add", "arguments":{"id":"net-0", "ifname":"tap0"}} +-> {"return": {}} +<- {"execute":"device_add", "arguments":{"id":"net-0", "driver":"virtio-net-mmio", "addr":"0x0"}} +-> {"return": {}} +``` + +其中，addr:0x0,对应虚拟机内部的eth0。 + +#### 热拔网卡 + +**用法** + +**{"execute": "device_del", "arguments": {"id": "net-0"}}** + +**参数** + +id：网卡的ID号，例如net-0。 + +**示例** + +``` +<- {"execute": "device_del", "arguments": {"id": "net-0"}} +-> {"event":"DEVICE_DELETED","data":{"device":"net-0","path":"net-0"},"timestamp":{"seconds":1598513339,"microseconds":97310}} +-> {"return": {}} +``` + + + +## Ballon设备使用 + +使用balloon设备可以从虚拟机回收空闲的内存。Balloon通过qmp命令来调用。qmp命令使用如下： + +**用法：** + +``` +{"execute": "balloon", "arguments": {"value": 2147483648‬}} +``` + +**参数：** + +- value： 想要设置的guest内存大小值，单位为字节。如果该值大于虚拟机启动时配置的内存值，则以启动时配置的内存值为准。 + +**示例：** + +启动时配置的内存大小为4GiB，在虚拟机内部通过free命令查询虚拟机空闲内存大于2GiB，那么可以通过qmp命令设置guest内存大小为2147483648字节。 + +``` +<- {"execute": "balloon", "arguments": {"value": 2147483648‬}} +-> {"return": {}} +``` + +查询虚拟机的当前实际内存： + +``` +<- {"execute": "query-balloon"} +-> {"return":{"actual":2147483648}} +``` + + +## 虚拟机快照和从快照恢复 + +StratoVirt支持对处于暂停状态的虚拟机制作快照。StratoVirt可以以快照文件为模板进行热启动，批量创建新的虚拟机。只要制作快照的节点在虚拟机启动完成并进入用户态之后，热启动就能够跳过内核的启动阶段和用户态服务的初始化阶段，在极短的时间内启动虚拟机。 + +**用法：** + +**制作快照：** + +在虚拟机启动完成后，通过QMP命令暂停虚拟机： +``` +<- {"execute":"stop"} +-> {"event":"STOP","data":{},"timestamp":{"seconds":1583908726,"microseconds":162739}} +-> {"return":{}} +``` + +当虚拟机处于暂停状态下，能够通过以下QMP命令在特定的*绝对路径*创建虚拟机快照： +``` +<- {"execute":"migrate", "arguments":{"uri":"file:/path/to/template"}} +-> {"return":{}} +``` + +在给定的路径下，StratoVirt将会创建两个文件： +```shell +$ ls path/to/template +memory state +``` + +`state`文件包含虚拟机设备状态的信息，`memory`文件包含虚拟机guest内存的数据信息，文件大小随虚拟机配置的guest内存增长而增长。 + +**从快照创建虚拟机：** + +通过以下命令从快照中恢复虚拟机： + +```shell +$ /usr/bin/stratovirt \ + ...... + -incoming file:path/to/template +``` +此时启动虚拟机的命令行中设备的种类和数量必须与创建快照时保持一致。其中和设备拓扑相关的，如cpu数量，guest内存大小，设备号和类型是不能改变的。一些设备后端，如网络设备对应的tap设备，console设备对应的字符设备，vsock设备对应的guest-cid是可以进行修改的。 + +**参数** + +- uri： 快照的路径，当前版本只支持`file:`类型，后加上快照文件的绝对路径 + +**查看快照状态** + +可以通过`query-migrate`qmp命令来检查当前快照的状态： +``` +<- {"execute":"query-migrate"} +-> {"return":{"status":"completed"}} +``` + +当前在整个快照过程中，存在5种状态： + +- `None`: 快照资源没有准备完成 +- `Setup`: 快照资源准备完成，可以进行快照 +- `Active`: 处于制作快照状态中 +- `Completed`: 快照制作成功 +- `Failed`: 快照制作失败 + +### 注意事项 + +- 快照以及从快照启动特性支持的机型包括： + - microvm + - q35（x86_64平台） + - virt（aarch64平台） +- 在使用快照恢复时，配置的设备必须与制作快照时保持一致 +- 当使用microvm机型，并且在快照前使用了磁盘/网卡的热插特性，在恢复时需要将热插的磁盘/网卡配置进启动命令行 + + + +### 互斥特性 + +- 配置了以下设备时，不能使用快照及相关特性： + - vhost-net设备 + - vfio直通设备 + - balloon设备 +- 虚拟机使用了以下特性时，不能使用快照及相关特性： + - 大页内存 + - mem-shared开关 + - 内存后端文件（mem-path） - 至此，可以在 test 容器内运行容器命令。 \ No newline at end of file