15.7. 操作

15.7.1. 启动虚拟机操作

启动操作会启动一个停止的、关闭的或挂起的虚拟机。

例 15.45. 启动虚拟机的操作

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>
在启动操作中可以使用一个 vm 项作为参数。如果使用了这个 vm 项,虚拟机会在启动时使用这个项中的值来覆盖系统设置。在 REST API 中使用带有 vm 项的启动操作与在管理门户或用户门户中使用只运行一次窗口的作用相同。这些设置会在虚拟机被停止前一直有效。这些设置包括 osdomainplacement_policycdromsstatelessdisplay type

例 15.46. 使用指定的参数启动虚拟机

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <pause>true</pause>
    <vm>
        <stateless>true</stateless>
        <display>
            <type>spice</type>
        </display>
        <os>
            <boot dev="cdrom"/>
        </os>
        <cdroms>
            <cdrom>
                <file id="windows-xp.iso"/>
            </cdrom>
        </cdroms>
        <floppies>
            <floppy>
                <file id="virtio-win_x86.vfd"/>
            </floppy>
       </floppies>
        <domain>
            <name>domain.example.com</name>
            <user>
                <user_name>domain_user</user_name>
                <password>domain_password</password>
            </user>
        </domain>
        <placement_policy>
            <host id="02447ac6-bcba-448d-ba2b-f0f453544ed2"/>       
        </placement_policy>
    </vm>
</action>

注意

  • domain 项只用于运行 Windows 操作系统的虚拟机,来使它在使用 start 操作引导时覆盖系统的相应参数。domain 项决定了 Windows 虚拟机需要加入的域。如果域没有存在于 domains 集合中,这个项将需要额外的 user 身份验证信息,包括一个 user_namepassword。如果域存在于 domains 集合中,这个操作将不需要额外的 user 身份验证信息。
  • CD 镜像和软盘文件需要已存在于 ISO 域中。如果还没有存在于 ISO 域中,使用 ISO 上传工具来它们上传到域中。如需了解更多相关信息,请参阅 The ISO Uploader Tool

15.7.2. 启动虚拟机时使用 Cloud-Init 操作

Cloud-Init 是一个自动化虚拟机初始设置的工具程序。您可以使用这个工具来配置主机名、网络接口、DNS 服务、认证密钥,以及设置用户名和密码。您还可以使用 custom_script 来指定一个在虚拟机引导时运行的自定义脚本。

注意

cloud-init 项只能被用来启动安装了 cloud-init 软件包的虚拟机。当 cloud-init 项被使用时,在 initialization 项内,但在 cloud-init 项外的所有项都会被忽略。

例 15.47. 在启动虚拟机时使用 Cloud-Init 的操作

以下示例演示了如何在启动虚拟机时使用 Cloud-Init 工具来设置主机名、修改 root 密码、为 eth0 接口设置静态 IP、配置 DNS,以及为 root 用户添加一个 SSH 密钥。
POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/start HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <vm>
       <initialization>
        <cloud_init>
          <host>
           <address>MyHost.MyDomain.com</address>
          </host>
          <users>
           <user>
            <user_name>root</user_name>
            <password>p@55w0rd!</password>
           </user>
          </users>
          <network_configuration>
           <nics>
            <nic>
              <name>eth0</name>
              <boot_protocol>static</boot_protocol>
              <network>
                <ip address="192.168.122.31" netmask="255.255.255.0" gateway="192.168.122.1"/>
              </network>
              <on_boot>true</on_boot>
            </nic>
           </nics>
           <dns>
            <servers>
              <host>
                <address>192.168.122.1</address>
              </host>
            </servers>
            <search_domains>
              <host>
                <address>MyDomain.com</address>
              </host>
            </search_domains>
          </dns>
        </network_configuration>
        <authorized_keys>
         <authorized_key>
           <user>
             <user_name>root</user_name>
           </user>
           <key>ssh-rsa AAAAB3Nza[...]75zkdD root@MyDomain.com</key>
         </authorized_key>
        </authorized_keys>
       </cloud_init>
       <custom_script><![CDATA[your script]]></custom_script>
      </initialization>
  </vm>
</action>

15.7.3. 停止虚拟机操作

停止操作会强制停止虚拟机的运行。

例 15.48. 停止虚拟机的操作

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/stop HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

15.7.4. 关闭虚拟机操作

关闭(shutdown)操作向虚拟机发送一个关闭请求。

例 15.49. 向虚拟机发送一个关闭请求操作

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/shutdown HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

15.7.5. 挂起虚拟机操作

挂起操作会把虚拟机状态保存到磁盘后停止它。使用启动操作可以启动被挂起的虚拟机,并恢复其状态。

例 15.50. 保存虚拟机的当前状态后挂起虚拟机的操作

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/suspend HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

15.7.6. 重启虚拟机操作

重启操作向虚拟机发出重启请求。

例 15.51. 向虚拟机发出重启请求的操作

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/reboot HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

15.7.7. 允许用户从一个外部控制台登录来访问虚拟机

这个登录操作将允许用户从 Red Hat Enterprise Virtualization 环境以外的控制台访问虚拟机。
这个操作需要安装 rhevm-guest-agent-gdm-pluginrhevm-guest-agent-pam-module 软件,ovirt-guest-agent 服务在虚拟机上运行。
为了可以通过一个外部控制台访问虚拟机,用户需要有虚拟机的适当权限。

例 15.52. 登录到一台虚拟机

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/logon HTTP/1.1
Content-Type: application/json
Content-Length: 2

{}

15.7.8. 从虚拟机池中删除虚拟机的操作

从虚拟机池中删除(detach)虚拟机的操作

例 15.53. 从虚拟机池中删除虚拟机的操作

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/detach HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

15.7.9. 迁移虚拟机操作

迁移操作把一个虚拟机迁移到另外一个物理主机。目标 host 项是一个可选项,如果没有使用,Red Hat Enterprise Virtualization Manager 会自动选择一个默认的主机进行迁移。如果 API 用户需要指定 host,用户可以使用 idname 参数。

例 15.54. 把虚拟机迁移到另外一个主机的操作。

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/migrate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
</action>

15.7.10. 取消虚拟机迁移操作

取消虚拟机迁移操作会停止所有把虚拟机迁移到其它主机的操作。

例 15.55. 取消虚拟机迁移操作

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/cancelmigration HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

15.7.11. 导出虚拟机操作

导出操作会把虚拟机导出到一个 export 存储域。目标存储域需要使用 storage_domain 来指定。
如果在目标域中存在同名的虚拟机,导出操作会报告一个错误。把 exclusive 参数设置为 true 可以改变这个行为,它会把虚拟机导入到目标域中,并覆盖其中同名的虚拟机。
如果不需要把虚拟机的快照包括在导出的虚拟机中,把 discard_snapshots 参数设置为 true

例 15.56. 把虚拟机导出到一个导出存储域的操作

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/export HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <storage_domain>
        <name>export1</name>
    </storage_domain>
    <exclusive>true</exclusive>
    <discard_snapshots>true</discard_snapshots>
</action>

15.7.12. 虚拟机票证(ticket)操作

票证操作会产生一个与时间相关的、用来为访问虚拟机进行验证的验证票证。客户端提供的 action 操作可以包括一个可选的 ticket 表述,它包括一个 value(如果令牌字符串需要使用特殊的格式)和(或)一个 expiry 值(以分钟代表)。这个请求会返回实际票证的值和过期的时间。

例 15.57. 为虚拟机创建用户验证令牌

POST /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <ticket>
        <expiry>120</expiry>
    </ticket>
</action>

200 OK
Content-Type: application/xml

<action id="94e07552-14ba-4c27-8ce6-2cc75190d3ef"
  href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket/
  94e07552-14ba-4c27-8ce6-2cc75190d3ef">
    <status>
        <state>complete</state>
    </status>
    <ticket>
        <value>5c7CSzK8Sw41</value>
        <expiry>120</expiry>
    </ticket>
    <link rel="parent"
      href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/>
    <link rel="replay"
      href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/ticket"/>
</action>

15.7.13. 强制删除虚拟机操作

API 用户可以使用 force 操作强制删除一个出现问题的虚拟机。这个操作需要一个 DELETE 方法。请求的内容项中包括了一个 action 表述,其中的 force 参数被设为 true。这个请求还需要一个额外的 Content-type: application/xml 头来处理内容项中的 XML 表述。

例 15.58. 强制删除虚拟机操作

DELETE /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <force>true</force>
</action>