14.7. 子集合

14.7.1. 主机网络接口子集合

14.7.1.1. 主机网络接口子集合

nics 子集合代表了主机的物理网络接口。使用带有 All-Content: true 头的 GET 请求可以获取额外的信息。表述中的每个 host_nic 项都代表一个网络接口，并包括以下项：

表 14.3. 主机网络接口的项

项类型描述属性
name字符串主机网络接口名，如 eth0。 [a]
link rel="statistics"关系主机网络接口统计数据的 statistics 子集合链接。
link rel="labels"关系主机网络接口标签的 labels 子集合链接。
link rel="master"关系主绑定接口的标识（如果有从接口）。
host id=GUID主机的标识。
network id=GUID指定网卡所连接的网络。 [b]
mac address=字符串接口的 MAC 地址。
ip address= netmask= gateway= mtu=复杂数据接口的 IP 级别配置。 
mtu复杂数据网络接口的最大传输单位。 
--boot_protocol列举在主机启动时分配 IP 地址的协议，它的有效值包括在 capabilities 中。 
status列举网络接口的连接状态。这些状态在 capabilities 下的 host_nic_states 中列出。
vlan id整数接口所代表的 VLAN。
bonding复杂数据绑定接口的 options 和 slave NIC 列表。 [c]
bridged布尔值指定是否是桥接网络。true 代表桥接网络，false 代表非桥接网络。 
properties复杂数据为网络的网桥选项定义自定义属性。每个 property 都包括 name 和 value 子项。 
[a] 只在添加绑定接口时需要。其它接口是只读的，不需要被添加。
[b] 只在添加绑定接口时需要。其它接口是只读的，不需要被添加。
[c] 只在添加绑定接口时需要。其它接口是只读的，不需要被添加。

例 14.9. 主机上的网络接口的 XML 表述

<host_nic id="00000000-0000-0000-0000-000000000000"
  href="/api/hosts/00000000-0000-0000-0000-000000000000/nics/
  00000000-0000-0000-0000-000000000000">
  <actions>
    <link rel="attach"
      href="/api/hosts/00000000-0000-0000-0000-000000000000/nics/
      00000000-0000-0000-0000-000000000000/attach"/>
    <link rel="detach"
      href="/api/hosts/00000000-0000-0000-0000-000000000000/nics/
      00000000-0000-0000-0000-000000000000/detach"/>
  </actions>
  <name>bond0</name>
  <link rel="labels"
    href= "/api/hosts/00000000-0000-0000-0000-000000000000/nics/
    00000000-0000-0000-0000-000000000000/labels"/>
  <link rel="statistics"
    href="/api/hosts/00000000-0000-0000-0000-000000000000/nics/
    00000000-0000-0000-0000-000000000000/statistics"/>      
  <host id="00000000-0000-0000-0000-000000000000"
    href="/api/hosts/00000000-0000-0000-0000-000000000000"/>
  <network id="00000000-0000-0000-0000-000000000000"
    href="/api/networks/00000000-0000-0000-0000-000000000000"/>
  <mac address="00:00:00:00:00:00"/>
  <ip address="XX.XX.XX.XX" netmask="255.255.255.0" gateway="XX.XX.XX.XX"/>
  <boot_protocol>dhcp</boot_protocol>
  <status>
    <state>up</state>
  </status>
  <bonding>
    <options>
      ...
    </options>
    <slaves>
      <host_nic id="00000000-0000-0000-0000-000000000000"/>
      <host_nic id="00000000-0000-0000-0000-000000000000"/>
    </slaves>
  </bonding>
  <mtu>1500</mtu>
  <bridged>true</bridged>
  <custom_configuration>false</custom_configuration>
  <properties>
    <property>
      <name>bridge_opts</name>
      <value>
        forward_delay=1500 group_fwd_mask=0x0 multicast_snooping=1
      </value>
    </property>
  </properties>
</host_nic>
您在使用 REST API 时，只能创建绑定接口。其它网络接口可以通过使用 PUT 请求更新它们的 network、ip 和 boot_protocol 项。
当添加一个网络接口时，name 和 network 项是必需的。使用 id 属性或 name 项来指定 network 项。 
POST /api/hosts HTTP/1.1
Accept: application/xml
Content-type: application/xml

<host_nic>
    <name>MyNIC</name>
    <network id="00000000-0000-0000-0000-000000000000">
        <name>MyNetwork</name>
    </network>
</host_nic>
您在使用 REST API 时，可以通过一个 PUT 请求修改网络接口。 
PUT /api/hosts/00000000-0000-0000-0000-000000000000/nics/
00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<host_nic>
    <ip address="XX.XX.XX.XX" netmask="255.255.255.0" gateway="XX.XX.XX.XX"/>
</host_nic>
您在使用 REST API 时，可以通过一个 DELETE 请求删除网络接口。 
DELETE /api/hosts/00000000-0000-0000-0000-000000000000/nics/
00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content

14.7.1.2. 绑定接口

绑定接口由带有 bonding 项的 host_nic 资源来代表。

表 14.4. 绑定接口属性

项类型描述属性
options复杂数据绑定接口的 option 项列表。每个 option 都包括了 name 和 value 属性。 [a]
slaves复杂数据绑定接口的从 host_nic id= 项列表。 [b]
[a] 只在添加绑定接口时需要。其它接口是只读的，不需要被添加。
[b] 只在添加绑定接口时需要。其它接口是只读的，不需要被添加。
API 用户在创建新的 host_nic（POST）或更新 host_nic（PUT）时可以创建新的绑定。使用 id 或 name 项指定从 host_nic 项。

例 14.10. 创建绑定接口

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<host_nic>
    <name>bond4</name>
    <network id="e657d631-657d-42bb-a536-73501a085d85"/>
    <bonding>
        <options>
            ...
        </options>
        <slaves>
            <host_nic id="eb14e154-5e73-4f7f-bf6b-7f52609d94ec"/>
            <host_nic id="6aede5ca-4c54-4b37-a81b-c0d6b53558ea"/>
        </slaves>
    </bonding>
</host_nic>

重要

绑定接口的有效值只包括 bond0、bond1、bond2、bond3 和 bond4。
使用一个对绑定接口的 DELETE 请求可以删除它。

重要

对绑定接口配置的改变必须被明确提交。

14.7.1.3. 网络接口自定义属性

自定义属性可以被应用到网络接口。每个属性都包括 name 和 value 子项。为了修改网络接口的自定义属性，需要执行一个带有 setupnetworks 操作的 POST 请求。

表 14.5. 主机网络接口的自定义桥接选项的项

项类型描述
name字符串属性的唯一标识。桥接选项有 bridge_opts 的一组名称。
value字符串桥接选项，有一个有效的关键字和值（格式是 [key]=[value]）代表。使用白空格符可以分隔多个项。以下列出的是有效的关键字，以及相关的值示例：

forward_delay=1500
gc_timer=3765 
group_addr=1:80:c2:0:0:0
group_fwd_mask=0x0
hash_elasticity=4
hash_max=512
hello_time=200
hello_timer=70
max_age=2000
multicast_last_member_count=2
multicast_last_member_interval=100
multicast_membership_interval=26000
multicast_querier=0
multicast_querier_interval=25500
multicast_query_interval=13000
multicast_query_response_interval=1000
multicast_query_use_ifaddr=0
multicast_router=1
multicast_snooping=1
multicast_startup_query_count=2
multicast_startup_query_interval=3125

例 14.11. 主机网络接口属性子集合的 XML 表述

<host_nic>
  ...
  <properties>
    <property>
      <name>bridge_opts</name>
      <value>
        forward_delay=1500 group_fwd_mask=0x0 multicast_snooping=1
      </value>
    </property>
  </properties>
  ...
</host_nic>

14.7.1.4. 网络接口统计数据

每个主机网络接口都有一个提供主机网络统计数据的 statistics 子集合。每个 statistic 都包括以下项：

表 14.6. 主机网络接口统计数据项

项类型描述
name字符串统计数据记录的唯一标识。
description字符串统计数据的描述。
unit字符串统计数据值所使用的单位。
typeGAUGE 或 COUNTER统计数据类型。
values type=INTEGER 或 DECIMAL统计数据值的数据类型。
value复杂数据包括 datum 的数据集。
datum请参阅 values typevalue 中的一条数据。
host_nic id=关系与包括 host_nic 资源的关系。
下表列出了主机的网络接口的统计数据类型。

表 14.7. 主机 NIC 统计数据类型

名称
描述
data.current.rx
数据接收频率（字节/每秒）
data.current.tx
数据传输频率（字节/每秒）
errors.total.rx
接收数据中的错误总数
errors.total.tx
传输数据中的错误总数

例 14.12. 网络接口统计数据子集合的 XML 表述

<statistics>
    <statistic id="ecd0559f-e88f-3330-94b4-1f091b0ffdf7"
      href="/api/hosts/25fcdd2e-d452-11e0-bb4d-525400d75548/nics/
      c34728e8-4338-4540-ac9b-86b8582e602e/statistics/
      ecd0559f-e88f-3330-94b4-1f091b0ffdf7">
        <name>data.current.rx</name>
        <description>Receive data rate</description>
        <values type="DECIMAL">
            <value>
                <datum>0</datum>
            </value>
        </values>
        <type>GAUGE</type>
        <unit>BYTES_PER_SECOND</unit>
        <host_nic id="c34728e8-4338-4540-ac9b-86b8582e602e"
          href="/api/hosts/25fcdd2e-d452-11e0-bb4d-525400d75548/nics/
          c34728e8-4338-4540-ac9b-86b8582e602e"/>
    </statistic>
    ...
</statistics>

注意

这个 statistics 子集合是只读的。

14.7.1.5. 操作

14.7.1.5.1. 为主机附加网络接口的操作
把主机网络接口附加到一个网络，这意味着这个网络可以通过被附加的网络接口卡进行访问。使用 id 或 name 项指定网络接口卡要被附加到的网络。

例 14.13. 把主机网络接口卡附加到网络的操作

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/e8f02fdf-3d7b-4135-86e1-1bf185570cd8/attach HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <network id="e657d631-657d-42bb-a536-73501a085d85"/>
</action>

重要

对网络配置的改变必须被明确提交。
14.7.1.5.2. 从主机上删除网络接口卡的操作
从主机上删除网络接口卡。使用 id 或 name 项来指定网络接口卡要从哪个网络上删除。

例 14.14. 从网络上删除网络接口卡的操作

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/e8f02fdf-3d7b-4135-86e1-1bf185570cd8/detach HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <network id="e657d631-657d-42bb-a536-73501a085d85"/>
</action>

重要

对网络配置的改变必须被明确提交。
14.7.1.5.3. 多网络设置操作
主机的 nics 集合中包括了一个设置多网络接口卡的操作。在 setupnetworks 操作中执行一个 POST 请求。

例 14.15. 设置多主机网络接口的操作

POST /api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/nics/setupnetworks HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <host_nics>
        <host_nic id="41561e1c-c653-4b45-b9c9-126630e8e3b9">
            <name>em1</name>
            <network id="00000000-0000-0000-0000-000000000009"/>
            <boot_protocol>dhcp</boot_protocol>
        </host_nic<
        <host_nic id="3c3f442f-948b-4cdc-9a48-89bb0593cfbd">
            <name>em2</name>
            <network id="00000000-0000-0000-0000-000000000010"/>
            <ip address="10.35.1.247" netmask="255.255.254.0"
              gateway="10.35.1.254"/>
            <boot_protocol>static</boot_protocol>
        </host_nic>
        <checkConnectivity>true</checkConnectivity>
        <connectivityTimeout>60</connectivityTimeout>
        <force>false</false>
    </host_nics>
</action>
这个操作会更新所有指定的、带有标准 NIC 项的网络接口资源。这个请求包括了下表中介绍的额外项。

表 14.8. 多主机网络接口设置的额外项

项类型描述
checkConnectivity布尔值设置为 true 来对主机和 Red Hat Enterprise Virtualization Manager 间的连接进行验证。如果连接断开，Red Hat Enterprise Virtualization Manager 会恢复它的设置。
connectivityTimeout整数连接的断开超时时间。
force布尔值设置为 true 来强制应用改变（即使连接已被断开）。
14.7.1.5.4. 为网络接口卡附加标签的操作
您可以为主机网络接口卡附加一个标签，使用这个标签可以把逻辑网络和有相同标签的物理主机网络接口进行关联。

例 14.16. 为网络接口卡附加标签的操作

POST /api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/labels HTTP/1.1
Accept: application/xml
Content-type: application/xml

<label id="Label_001" />
14.7.1.5.5. 为网络接口卡删除标签
从物理主机网络接口中删除一个标签需要一个 DELETE 请求。

例 14.17. 从网络接口卡中删除标签

DELETE /api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/labels/[label_id] HTTP/1.1

HTTP/1.1 204 No Content

14.7.2. 存储子集合

14.7.2.1. 存储子集合

storage 子集合提供了一组主机可用的 iSCSI 和 FCP 存储表述列表。这个存储被用来创建存储域。
子集合中的每个 storage 表述都代表了一个 SCSI LUN。

例 14.18. 主机上的存储子集合的 XML 表述

<host_storage>
    <storage id="82fb123b-321e-40a1-9889-95dcd2654463"
      href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/storage/
      82fb123b-321e-40a1-9889-95dcd2654463">
        <name>LUN0</name>
        <type>iscsi</type>
        <logical_unit id="LUN0">
            <address>mysan.example.com</address>
            <target>iqn.2009-08.com.example:mysan.foobar</target>
        </logical_unit>
    </storage>
</host_storage>

注意

host_storage 集合是只读的。

重要

本节中所使用的 API 还处于试用阶段，今后它们可能会有变化。产品的向下兼容声明不适用于这些 API。

14.7.3. 主机 NUMA 节点子集合

14.7.3.1. NUMA 节点子集合

numanodes 子集合代表了主机的 NUMA 拓扑。子集合中的每个 host_numa_node 项都代表了一个 NUMA 节点。

例 14.19. 主机上的 numanodes 子集合的 XML 表述

<host_numa_nodes>
    <host_numa_node href="/api/hosts/f6735fa9-4ee5-47ce-b750-a87863736cc2/numanodes/91d8537c-699e-460b-9a70-285f651e7d68" id="91d8537c-699e-460b-9a70-285f651e7d68">
        <link href="/api/hosts/f6735fa9-4ee5-47ce-b750-a87863736cc2/numanodes/91d8537c-699e-460b-9a70-285f651e7d68/statistics" rel="statistics"/>
        <host href="/api/hosts/f6735fa9-4ee5-47ce-b750-a87863736cc2" id="f6735fa9-4ee5-47ce-b750-a87863736cc2"/>
        <index>0</index>
        <memory>8157</memory>
        <cpu>
            <cores>
                <core index="0"/>
                <core index="2"/>
                <core index="4"/>
                <core index="6"/>
            </cores>
        </cpu>
        <node_distance>10 16</node_distance>
    </host_numa_node>
    <host_numa_node href="/api/hosts/f6735fa9-4ee5-47ce-b750-a87863736cc2/numanodes/4b18926e-6faf-43f5-9fc2-0503f1531562" id="4b18926e-6faf-43f5-9fc2-0503f1531562">
        <link href="/api/hosts/f6735fa9-4ee5-47ce-b750-a87863736cc2/numanodes/4b18926e-6faf-43f5-9fc2-0503f1531562/statistics" rel="statistics"/>
        <host href="/api/hosts/f6735fa9-4ee5-47ce-b750-a87863736cc2" id="f6735fa9-4ee5-47ce-b750-a87863736cc2"/>
        <index>2</index>
        <memory>8175</memory>
        <cpu>
            <cores>
                <core index="1"/>
                <core index="3"/>
                <core index="5"/>
                <core index="7"/>
            </cores>
        </cpu>
        <node_distance>16 10</node_distance>
    </host_numa_node>
</host_numa_nodes>

注意

host_numa_nodes 子集合是只读的。

14.7.3.2. NUMA 节点统计数据

每个主机 NUMA 节点都包括了一个 NUMA 统计数据的 statistics 子集合。statistic 包括以下项：

表 14.9. 主机的 NUMA 节点统计数据的项

项类型描述
name字符串统计数据记录的唯一标识。
description字符串统计数据的描述信息。
unit字符串统计数据值所使用的单位。
typeGAUGE 或 COUNTER统计数据类型。
values type=INTEGER 或 DECIMAL统计数据值的数据类型。
value复杂数据包括 datum 的数据集。
datum请参阅 values typevalue 中的一条数据。
host_numa_node id=关系与包括 numanode 资源的关系。
下表列出了主机 NUMA 节点的统计数据类型。

表 14.10. 主机 NUMA 节点统计数据

名称描述
memory.totalNUMA 节点的总内存数（以字节为单位）。
memory.usedNUMA 节点中使用的内存数（以字节为单位）。
memory.freeNUMA 节点中空闲的内存数（以字节为单位）。
cpu.current.user用户的 CPU 使用百分比。
cpu.current.system系统的 CPU 使用百分比。
cpu.current.idle空闲 CPU 使用百分比。

例 14.20. 主机 NUMA 统计数据子集合的 XML 表述

<statistics>
    <statistic href="/api/hosts/f6745fa9-4ee5-47ce-b750-a87863736cc2/numanodes/91d8537c-689e-460b-9a70-285f651e7d68/statistics/7816602b-c05c-3dc7-a4da-3769f7ad8896" id="7816602b-c05c-3dc7-a4da-3769f7ad8896">
        <name>memory.total</name>
        <description>Total memory</description>
        <values type="INTEGER">
            <value>
                <datum>8157</datum>
            </value>
        </values>
        <type>GAUGE</type>
        <unit>BYTES</unit>
        <host_numa_node href="/api/hosts/f6745fa9-4ee5-47ce-b750-a87863736cc2/numanodes/91d8537c-689e-460b-9a70-285f651e7d68" id="91d8537c-689e-460b-9a70-285f651e7d68"/>
    </statistic>
    ...
</statistics>

注意

主机 NUMA 的 statistics 子集合是只读的。

14.7.4. 主机统计数据子集合

14.7.4.1. 主机统计数据子集合

每个主机资源都包括了一个主机统计数据的 statistics 子集合。statistic 包括以下项：

表 14.11. 主机统计数据项

项类型描述
name字符串统计数据记录的唯一标识。
description字符串统计数据的描述。
unit字符串统计数据值所使用的单位。
typeGAUGE 或 COUNTER统计数据类型。
values type=INTEGER 或 DECIMAL统计数据值的数据类型。
value复杂数据包括 datum 的数据集。
datum请参阅 values typevalue 中的一条数据。
host id=关系与包括 host 资源的关系。
下表列出了主机统计数据类型。

表 14.12. 主机统计数据类型

名称
描述
memory.total
主机的总内存数（以字节为单位）。
memory.used
主机使用的内存数量（以字节为单位）。
memory.free
主机上空闲的内存数量（以字节为单位）。
memory.shared
主机共享的内存数量（以字节为单位）。
memory.buffers
I/O 缓冲区大小（以字节为单位）。
memory.cached
OS 缓存（以字节为单位）。
swap.total
主机的交换内存数量（以字节为单位）。
swap.free
主机上空闲的交换内存数量（以字节为单位）。
swap.used
主机使用的交换内存数量（以字节为单位）。
swap.cached
在主机内存中缓存的交换内存数量（以字节为单位）。
ksm.cpu.current
Kernel SamePage Merging 的 CPU 使用百分比。
cpu.current.user
用户的 CPU 使用百分比。
cpu.current.system
系统的 CPU 使用百分比。
cpu.current.idle
空闲 CPU 使用百分比。
cpu.load.avg.5m
CPU 负载 5 分钟平均值。

例 14.21. 主机统计数据子集合的 XML 表述

<statistics>
    <statistic id="4ae97794-f56d-3f05-a9e7-8798887cd1ac"
      href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3/
      statistics/4ae97794-f56d-3f05-a9e7-8798887cd1ac">
        <name>memory.total</name>
        <description>Total memory</description>
        <unit>BYTES</unit>
        <type>GUAGE</type>
        <values type="INTEGER">
            <value>
                <datum>3983540224<datum>
            </value>
        </values>
        <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
          href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
    </statistic>
    ...
</statistics>

注意

主机的 statistics 子集合是只读的。