红帽全球峰会15.6. 子集合
15.6.1. 磁盘子集合
复制链接链接已复制到粘贴板!
15.6.1.1. 磁盘子集合
复制链接链接已复制到粘贴板!
disks 子集合代表了虚拟机上的所有虚拟硬盘。一个 disk 表述包括以下项：
| 项 | 类型 | 描述 | 属性 |
|---|---|---|---|
link rel="statistics" | 关系 | 虚拟机磁盘统计数据的 statistics 子集合链接。 |
|
link rel="permissions" | 关系 | 到 permissions 子集合的链接。 |
|
alias | 字符串 | 磁盘的唯一 ID。使用 alias 而不是使用 name。 | |
image_id | 字符串 | 保存在所定义的存储域中的虚拟机镜像标识。 | |
storage_domains | 复杂数据 | 与磁盘相关联的存储域。每个 storage_domain 项都包括一个带有存储域 GUID 的 id 属性。使用 POST 更新这个项可以执行从一个数据存储域到另一个数据存储域的磁盘实时迁移操作。 |
[a] |
size | 整数 | 磁盘大小（以字节为单位）。已被 provisioned_size 所替代。 |
|
provisioned_size | 整数 | 配置的磁盘大小（以字节为单位） |
|
actual_size | 整数 | 磁盘的实际大小（以字节为单位） |
|
status | illegal、invalid、locked 或 ok | 磁盘设备的状态。capabilities 下的 disk_states 列出了它的值。 |
|
interface | 列举 | 连接到磁盘设备的接口驱动类型。capabilities 包括了有效的值。 | |
format | 列举 | 底层的存储格式。capabilities 包括了有效的值。使用 Copy On Write（COW）可以创建快照，但对系统性能会有一些影响；Raw 不能创建快照，但可以提供更好的性能。 |
|
sparse | 布尔值：true 或 false | true：磁盘所使用的物理存储无法被预先分配。 |
|
bootable | 布尔值：true 或 false | true：磁盘被设为可引导。 | |
--shareable | 布尔值：true 或 false | true：磁盘可以被多个虚拟机共享。 | |
wipe_after_delete | 布尔值：true 或 false | 如果为 true，在磁盘被删除后，这个磁盘的底层物理存储会被清零。此选项会增加数据的安全性，但同时会消耗大量的操作资源，并会增加删除过程所需的时间。 | |
propagate_errors | 布尔值：true 或 false | true：当磁盘出现错误时，不会导致虚拟机暂停，而是把磁盘错误传递给虚拟机的 OS。 | |
vm id= | GUID | 包括虚拟机的 ID。 |
|
quota id= | GUID | 为磁盘设置一个配额。 | |
lun_storage | 复杂数据 | 为存储使用的直接 LUN 的标识。需要一个包括 iSCSI 或 FCP 设备详情的 logical_unit 项。 |
|
active | 布尔值（Boolean） | 指定磁盘是否连接到虚拟机。 |
|
read_only | 布尔值（Boolean） | 定义磁盘是否为只读。 | |
link rel="disk_profile" | 关系 | 到 disk_profile 子集合的链接。 | |
[a]
这个项只有在磁盘被添加到虚拟机，而不是通过虚拟机模板创建时才需要
| |||
例 15.10. 磁盘设备的 XML 表述
添加一个新虚拟磁盘。添加新虚拟磁盘需要
provisioned_size 项。使用 storage_domains 项指定磁盘要在哪个存储域中创建。同一个虚拟机的多个磁盘可以存在于不同的存储域中。
例 15.11. 在虚拟机上创建一个新磁盘设备
为虚拟机添加一个新的外部（direct LUN）磁盘。这个调用需要
lun_storage 和 logical_unit 项来包括 iSCSI 或 FCP 设备的详细信息。
例 15.12. 在虚拟机上创建一个新的 direct LUN 磁盘设备
在创建完成后，
alias、description、storage_domains、provisioned_size、interface、bootable、shareable、wipe_after_delete 和 propagate_errors 项都可以被更新。
用户可以在不需要暂停、休眠、重启虚拟机的情况下调整虚拟磁盘的大小。
例 15.13. 更新虚拟机磁盘
例 15.14. 把虚拟机磁盘的大小改为 20GB。
注意
以上实例中的磁盘大小是通过以下公式计算的：
20480MB * 1024 2 = 21474836480 字节
例 15.15. 重新命名一个虚拟机磁盘
删除虚拟机磁盘需要一个
DELETE 请求。
例 15.16. 删除虚拟机磁盘
DELETE /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1 HTTP/1.1 204 No Content
DELETE /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1
HTTP/1.1 204 No Content
15.6.1.2. 磁盘克隆
复制链接链接已复制到粘贴板!
使用带有
clone 项的模板克隆磁盘。在创建虚拟机时，把 disks 子集合的 clone 项设置为 true。这会使用基本模板克隆磁盘，并把它附加到虚拟机上。
例 15.17. 使用模板克隆一个磁盘
以下实例在创建虚拟机时使用模板克隆一个磁盘。
重要
基于磁盘名称对虚拟机磁盘进行搜索需要
alias 搜索参数，而不是 name。
15.6.1.3. 磁盘统计数据子集合
复制链接链接已复制到粘贴板!
每个虚拟机都包括一个
statistics 子集合来提供与磁盘相关的统计数据。每个 statistic 包括以下项：
| 项 | 类型 | 描述 |
|---|---|---|
name | 字符串 | 统计数据记录的唯一标识。 |
description | 字符串 | 统计数据的描述。 |
unit | 字符串 | 统计数据值所使用的单位。 |
type | GAUGE 或 COUNTER | 统计数据类型。 |
values type= | INTEGER 或 DECIMAL | 统计数据值的数据类型。 |
value | 复杂数据 | 包括 datum 的数据集。 |
datum | 请参阅 values type | value 中的一条数据。 |
disk id= | 关系 | 与包括 disk 资源的关系。 |
下表列出了虚拟机磁盘的统计数据类型信息。
|
名称
|
描述
|
|---|---|
data.current.read |
读磁盘操作的数据传输频率（字节/每秒）
|
data.current.write |
写磁盘操作的数据传输频率（字节/每秒）
|
例 15.18. 虚拟机统计数据子集合的 XML 表述
注意
这个
statistics 子集合是只读的。
15.6.1.4. 附加浮动磁盘和取消附加浮动磁盘的操作
复制链接链接已复制到粘贴板!
使用
POST 请求在虚拟机的 disks 子集合中附加主 rel="disks" 集合中的一个磁盘。包括被附加的磁盘 id。
例 15.19. 附加浮动磁盘
使用对磁盘资源的
DELETE 请求来从虚拟机的 disks 子集合中取消附加一个磁盘，但需要包括一个 detach 项来确保磁盘不会被破坏。
例 15.20. 从虚拟机上取消附加的磁盘
15.6.1.5. 激活和取消激活操作
复制链接链接已复制到粘贴板!
每个虚拟机磁盘都提供了一组
activate 和 deactivate 操作来为虚拟机添加磁盘，或从虚拟机上删除磁盘。
例 15.21. 激活虚拟机磁盘操作
例 15.22. 取消激活虚拟机磁盘操作
使用这些操作来为虚拟机“热插”磁盘，并激活新添加的磁盘。
重要
“热插”功能只支持 VirtIO 磁盘，虚拟机操作系统必须支持“热插”操作。支持这个功能的操作系统包括：
- Red Hat Enterprise Linux 6；
- Red Hat Enterprise Linux 5；
- Windows Server 2008； 和
- Windows Server 2003。
15.6.2. 网络接口子集合
复制链接链接已复制到粘贴板!
15.6.2.1. 网络接口子集合
复制链接链接已复制到粘贴板!
nics 子集合代表了虚拟机上的所有网络接口设备。一个 nics 表述包括以下项：
| 项 | 类型 | 描述 | 属性 |
|---|---|---|---|
link rel="statistics" | 关系 | 虚拟机网络接口统计数据的 statistics 子集合链接。 |
|
network id= | GUID | 接口需要连接到的网络标识。可以是一个空的网络 ID |
|
interface | 列举 | nic 使用的驱动类型。capabilities 包括了有效的值。 | |
mac address= | 字符串 | 接口的 MAC 地址。 |
|
port_mirroring | 复杂数据 | 指定 NIC 是否接收镜像的网络数据。使用一组 network id= 来定义 networks 项。 | |
plugged | 布尔值 | 指定 NIC 是否被插到虚拟机上。 |
|
linked | 布尔值 | 指定 NIC 是否被连接到虚拟机上。 |
|
例 15.23. 网络接口的 XML 表述
当添加一个网络接口时，
name 和 network 项是必需的。使用 id 属性或 name 项来指定 network 项。
例 15.24. 创建一个虚拟机 NIC
API 用户可以使用
PUT 请求修改网络接口。
例 15.25. 更新虚拟机 NIC
API 用户可以使用
DELETE 请求删除网络接口。
例 15.26. 删除虚拟机 NIC
DELETE /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/ 7a3cff5e-3cc4-47c2-8388-9adf16341f5e HTTP/1.1 HTTP/1.1 204 No Content
DELETE /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/
7a3cff5e-3cc4-47c2-8388-9adf16341f5e HTTP/1.1
HTTP/1.1 204 No Content
重要
“热插”功能只在虚拟机操作系统支持“热插”操作时才被支持。支持这个功能的操作系统包括：
- Red Hat Enterprise Linux 6；
- Red Hat Enterprise Linux 5；
- Windows Server 2008 和
- Windows Server 2003。
15.6.2.2. 网络接口统计数据子集合
复制链接链接已复制到粘贴板!
每个虚拟机网络接口都有一个提供网络接口统计数据的
statistics 子集合。每个 statistic 都包括以下项：
| 项 | 类型 | 描述 |
|---|---|---|
name | 字符串 | 统计数据记录的唯一标识。 |
description | 字符串 | 统计数据的描述。 |
unit | 字符串 | 统计数据值所使用的单位。 |
type | GAUGE 或 COUNTER | 统计数据类型。 |
values type= | INTEGER 或 DECIMAL | 统计数据值的数据类型。 |
value | 复杂数据 | 包括 datum 的数据集。 |
datum | 请参阅 values type | value 中的一条数据。 |
nic id= | 关系 | 与包括 nic 资源的关系。 |
下表列出了虚拟机网络接口的统计数据类型。
|
名称
|
描述
|
|---|---|
data.current.rx |
数据接收频率（字节/每秒）
|
data.current.tx |
数据传输频率（字节/每秒）
|
errors.total.rx |
接收数据中的错误总数
|
errors.total.tx |
传输数据中的错误总数
|
例 15.27. 虚拟机 NIC 统计数据子集合的 XML 表述
注意
这个
statistics 子集合是只读的。
15.6.3. 虚拟 NUMA 节点子集合
复制链接链接已复制到粘贴板!
numanodes 子集合代表了一个虚拟机上的所有虚拟 NUMA 节点。一个 vm_numa_node 会包括以下项：
| 项 | 类型 | 描述 | 属性 |
|---|---|---|---|
index | 整数 | 虚拟 NUMA 节点的索引号。 |
|
memory | 整数 | 分配给虚拟 NUMA 节点的内存数量（以 MB 为单位）。 |
|
cpu | 复杂数据 | 与这个虚拟 NUMA 节点相关联的 CPU 拓扑。每个 core 项包括一个 index 属性代表相关联的内核索引号。 |
|
vm id= | GUID | 包括虚拟机的 ID。 |
|
numa_node_pins | 复杂数据 | 把虚拟 NUMA 节点固定到一个主机的 NUMA 节点。每个 numa_node_pin 项包括一个 pinned="true" 布尔值，以及主机 NUMA 节点的 index 号。 |
例 15.28. 一个虚拟 NUMA 节点的 XML 表述
在添加一个新虚拟 NUMA 节点时，需要
index、memory 和 cpu 项。
例 15.29. 把一个新的虚拟 NUMA 节点添加到一个虚拟机
使用
PUT 请求来更新一个虚拟 NUMA 节点。您可以使用一个 PUT 请求来把一个虚拟 NUMA 节点固定到一个主机上的一个物理 NUMA 节点上。
例 15.30. 更新一个虚拟 NUMA 节点
使用
DELETE 请求删除一个虚拟 NUMA 节点。
例 15.31. 删除一个虚拟 NUMA 节点
DELETE /api/vms/c7ecd2dc-dbd3-4419-956f-1249651c0f2b/numanodes/3290b973-ed3e-4f0b-bbf5-9be10d229e50 HTTP/1.1 HTTP/1.1 204 No Content
DELETE /api/vms/c7ecd2dc-dbd3-4419-956f-1249651c0f2b/numanodes/3290b973-ed3e-4f0b-bbf5-9be10d229e50 HTTP/1.1
HTTP/1.1 204 No Content15.6.4. CD-ROM 子集合
复制链接链接已复制到粘贴板!
cdroms 子集合代表了虚拟机上的 CD-ROM 设备。一个 cdrom 表述包括以下项：
| 项 | 类型 | 描述 | 属性 |
|---|---|---|---|
file id= | 字符串/文件名 | ISO 镜像的标识。 |
例 15.32. CD-ROM 设备的 XML 表述
使用带有
file id 项的 PUT 请求来添加一个新 CD-ROM 资源。
例 15.33. 添加一个新 CD-ROM 文件
API 使用
PUT 请求更换 CD-ROM：
例 15.34. 更换 CD-ROM 文件
API 使用一个带有额外
current URI 参数的 PUT 请求来更换当前会话中使用的 CD-ROM：
例 15.35. 更换当前会话中的 CD-ROM 文件
要临时弹出 CD-ROM，发送一个到虚拟机的
cdroms 子集合的 PUT 请求，这个请求中需要使用 current=true 参数：
例 15.36. 在当前会话中弹出 CD-ROM 文件
注意
重启虚拟机后会自动连接到 CD-ROM。
要永久弹出 CD-ROM，向虚拟机的
cdroms 子集合发送 PUT 请求：
例 15.37. 永久弹出 CD-ROM 文件
注意
虚拟机只包括一个 CD-ROM 设备。
15.6.5. 快照子集合
复制链接链接已复制到粘贴板!
15.6.5.1. 快照子集合
复制链接链接已复制到粘贴板!
虚拟机使用快照来保存和恢复磁盘的状态。和其它集合相似，用户可以使用
rel="snapshot" 子集合表述和管理快照。
每个虚拟机快照都由一个单独的、带有以下项的
snapshot 项来表述：
| 项 | 类型 | 描述 | 属性 |
|---|---|---|---|
vm id= | GUID | 快照所属虚拟机的 ID 和 URI。 |
|
link rel="restore" | 关系 | 到恢复虚拟机快照的一个链接。 |
|
link rel="prev" | 关系 | 虚拟机前一个快照的标识。 |
|
type | 字符串 | 快照的类型。例如，active 或 regular。 |
|
date | xsd:dateTime 格式：YYYY-MM-DDThh:mm:ss | 快照被创建的日期和时间。 |
|
snapshot_status | 字符串 | 快照的当前状态。 |
|
persist_memorystate | 布尔值 | 指定在进行快照时，是否在快照中包括虚拟机内存的状态。 |
|
注意
不能使用
PUT 修改快照。
例 15.38. 虚拟机快照的 XML 表述
使用带有
All-Content: true 头的、对虚拟机快照的 GET 请求可以获得包括额外的、代表快照的 OVF 数据。
如果
Accept 头为空，它会被默认设置为 application/xml，数据由 HTML 项来代表，因此不会影响到 XML tag。如果指定 Accept: application/json 头，返回的数据会使用标准的 XML tag。这个示例使用标准块格式构成。
例 15.39. 代表一个快照的 ovf 数据的 XML
您可以为正在运行的主机进行快照（实时快照），或使用
POST 来关闭虚拟机：
例 15.40. 创建一个虚拟机的快照
您可以在快照表述中使用
rel="restore" 操作链接来恢复虚拟机快照：
例 15.41. 恢复虚拟机快照
15.6.5.2. 通过快照克隆虚拟机
复制链接链接已复制到粘贴板!
API 提供了一个使用其它虚拟机快照创建虚拟机的功能。API 用户可以在创建新虚拟机时保留原始虚拟机的所有快照。
使用快照创建虚拟机需要在标准的虚拟机表述中添加一个
snapshots 项。用户需要向 vms 集合发送一个 POST 请求。
snapshots 项包括了一个 snapshot id= 项来指定创建虚拟机需要基于的快照。
例 15.42. 从快照克隆虚拟机
15.6.6. 统计数据子集合
复制链接链接已复制到粘贴板!
每个虚拟机都包括一个
statistics 子集合来提供与虚拟机相关的统计数据。每个 statistic 包括以下项：
| 项 | 类型 | 描述 |
|---|---|---|
name | 字符串 | 统计数据记录的唯一标识。 |
description | 字符串 | 统计数据的描述。 |
unit | 字符串 | 统计数据值所使用的单位。 |
type | GAUGE 或 COUNTER | 统计数据类型。 |
values type= | INTEGER 或 DECIMAL | 统计数据值的数据类型。 |
value | 复杂数据 | 包括 datum 的数据集。 |
datum | 请参阅 values type | value 中的一条数据。 |
vm id= | 关系 | 与包括 vm 资源的关系。 |
下表列出了虚拟机的统计数据类型。
|
名称
|
描述
|
|---|---|
memory.installed |
为虚拟机使用分配的总内存数量（以字节为单位）。
|
memory.used |
虚拟机当前使用的内存（以字节为单位）。
|
cpu.current.guest |
虚拟机使用的 CPU 百分数。
|
cpu.current.hypervisor |
hypervisor 消耗的 CPU 百分数。
|
cpu.current.total |
当前使用的 CPU 百分比。
|
例 15.43. 虚拟机统计数据子集合 XML 表述
注意
虚拟机的
statistics 子集合是只读的。
15.6.7. 显示虚拟机对话信息
复制链接链接已复制到粘贴板!
为虚拟机发一个
GET 请求并使用 session 子集合来查看初始 SPICE 控制台会话的用户的会话信息，以及登录到这个虚拟机的用户的会话信息。
虚拟机的
session 信息作为子集合被列出：
例 15.44. 显示一个虚拟机的会话信息
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}