REST API ガイド

Red Hat Enterprise Virtualization 3.6

Red Hat Enterprise Virtualization REST アプリケーションプログラミングインターフェースの使用

Red Hat Enterprise Virtualization Documentation Team

Red Hat Customer Content Services

概要

本ガイドは、Red Hat Enterprise Virtualization の Representational State Transfer (REST) API について説明します。

第1章 はじめに

Red Hat Enterprise Virtualization Manager は Representational State Transfer (REST) API を提供しています。API により、ソフトウェア開発者やシステム管理者は、標準の Web インターフェースを使用せずに Red Hat Enterprise Virtualization 環境を管理することができます。REST API は、開発者や管理者が Red Hat Enterprise Virtualization 環境の機能にカスタムスクリプトや標準の Hypertext Transfer Protocol (HTTP) を介して API にアクセスする外部アプリケーションを統合する場合に役立ちます。
REST API には、以下のようなメリットがあります。
  • 幅広いクライアントサポート: HTTP 対応のあらゆるプログラミング言語/フレームワーク/システムで使用することが可能
  • 自己記述型: 詳しい情報の多くは実行時に確認できるため、クライアントアプリケーションに必要な仮想化インフラストラクチャーの知識は最小限で済む
  • リソースベースのモデル: リソースベースの REST モデルにより仮想化プラットフォームを自然な形で管理することが可能
これにより、開発者および管理者は以下のような作業を行うことができます。
  • エンタープライズ IT システムとの統合
  • サードパーティーの仮想ソフトウェアとの統合
  • 自動メンテナンスやエラーチェックなどのタスクの実行
  • スクリプトによる Red Hat Enterprise Virtualization 環境内の反復タスクの自動化
本ガイドは、Red Hat Enterprise Virtualization Manager REST API の参考資料としてご利用ください。開発者および管理者を対象に、直接 REST API から、または提供されている Python ライブラリーを使用して Red Hat Enterprise Virtualization 環境の機能を十分にご活用いただくための手順および実例を記載しています。

1.1. Representational State Transfer

Representational State Transfer (REST) は、特定のサービスとそれらの表現にフォーカスした設計アーキテクチャーです。リソース表現は、サーバー上にある 1 つの特定管理対象要素に対応した情報の主要な抽象概念です。クライアントは Uniform Resource Identifier (URI) にあるサーバー要素に対して要求を送信し、GETPOSTPUTDELETE などの標準的な HTTP メソッドで操作を実行します。これにより、クライアントとサーバー間のステートレスな通信が提供され、各要求は他の要求に依存せずに機能し、その要求を完了するために必要な情報をすべて含みます。

1.2. Red Hat Enterprise Virtualization REST API の前提条件

Red Hat Enterprise Virtualization REST API の前提条件

  • ネットワーク接続された Red Hat Enterprise Virtualization Manager のインストール (REST API を含む)
  • REST API からの HTTP 要求を開始および受信するクライアントまたはプログラミングライブラリー。以下に例を示します。
    • Python ソフトウェア開発キット (SDK)
    • Java ソフトウェア開発キット (SDK)
    • cURL コマンドラインツール
    • RESTClient (RESTful Web サービスのデバッガー)
  • REST API の対話に使用する HTTP (Hypertext Transfer Protocol) についての知識。Hypertext Transfer Protocol についての説明は Internet Engineering Task Force 提供の RFC (Request for Comments) に記載されています (http://www.ietf.org/rfc/rfc2616.txt)。
  • API がリソース表現の構築に使用する Extensible Markup Language (XML) または JavaScript Object Notation (JSON) に関する知識。完全な XML 仕様は、W3C のサイト http://www.w3.org/TR/xml/ に掲載されています。また、ECMA International が http://www.ecma-international.org で JSON に関するドキュメントを無料で提供しています。

第2章 認証とセキュリティー

2.1. TLS/SSL 証明書

Red Hat Enterprise Virtualization Manager API で、Manager の SDK や CLI コンポーネントなどのクライアントソフトウェアとセキュアな対話を行うには、Hypertext Transfer Protocol Secure (HTTPS) [1] が必要です。これには、Red Hat Enterprise Virtualization Manager から証明書を取得してクライアントの証明書ストアにインポートするプロセスが伴います。

重要

セキュアなネットワーク接続を使用して Red Hat Enterprise Virtualization Manager から証明書を取得します。

手順2.1 証明書の取得

以下の 3 つのメソッドのいずれかを使用して、Red Hat Enterprise Virtualization Manager から証明書を取得してクライアントマシンに転送することができます。
  1. メソッド 1: コマンドラインツールを使用して Manager から証明書をダウンロードします。コマンドラインツールには、cURLWget などがあり、いずれも複数のプラットフォームで使用可能です。
    1. cURL の使用例
      $ curl -o rhevm.cer http://[rhevm-server]/ca.crt
    2. Wget の使用例
      $ wget -O rhevm.cer http://[rhevm-server]/ca.crt
  2. メソッド 2: Web ブラウザーを使用して、証明書がある場所に移動します。
    http://[rhevm-server]/ca.crt
    選択したブラウザーによって、証明書がダウンロードされる場合と、ブラウザーのキーストアにインポートされる場合とがあります。
    1. ブラウザーが証明書をダウンロードする場合には、そのファイルを rhevm.cer という名前で保存します。
      ブラウザーが証明書をインポートする場合には、ブラウザーの証明書オプションでその証明書をエクスポートし、rhevm.cer という名前で保存します。
  3. メソッド 3: Manager にログインしてトラストストアから証明書をエクスポートして、クライアントマシンにコピーします。
    1. Manager に root ユーザーとしてログインします。
    2. Java keytool 管理ユーティリティーを使用して、トラストストアから証明書をエクスポートします。
      $ keytool -exportcert -keystore /etc/pki/ovirt-engine/.truststore -alias cacert -storepass mypass -file rhevm.cer
      rhevm.cer という名前の証明書ファイルが作成されます。
    3. scp コマンドを使用して、証明書をクライアントマシンにコピーします。
      $ scp rhevm.cer [username]@[client-machine]:[directory]
上記のいずれの方法を実行した場合も、クライアントマシンには rhevm.cer という名前の証明書ファイルが作成されます。API ユーザーにより、このファイルがクライアントの証明書ストアにインポートされます。

手順2.2 クライアントへの証明書のインポート

  • クライアントへの証明書インポートの方法は、クライアント自体が証明書をどのように格納し、解釈するかによって異なります。本ガイドには、証明書のインポートの例をいくつか記載しています。Network Security Services (NSS) または Java keystore (JKS) を使用しないクライアントでの証明書インポートに関する詳細情報は、そのクライアントのマニュアルを参照してください。

2.2. HTTP 認証

Red Hat Enterprise Virtualization アカウントを持つユーザーは、REST API にアクセスできます。API ユーザーは、API を対象とする全要求において、必須の Red Hat Enterprise Virtualization Manager ユーザー名とパスワードを送信します。各要求は HTTP 基本認証 [2] を使用してこれらの認証情報をエンコードします。要求に適切な Authorization ヘッダーが記載されていない場合には、API は 401 Authorization Required を送信します。

例2.1 適切な認証情報なしの REST API へのアクセス

HEAD [base] HTTP/1.1
Host: [host]

HTTP/1.1 401 Authorization Required
要求は、指定したレルムに対して Authorization ヘッダー付きで発行されます。API ユーザーは、username@domain:password の形式で提供される認証情報内の適切な Red Hat Enterprise Virtualization Manager ドメインおよびユーザーをエンコードします。
以下の表には、認証情報を base64 でエンコードするプロセスをまとめています。

表2.1 API アクセス用の認証情報のエンコード

項目
ユーザー名rhevmadmin
ドメインdomain.example.com
パスワード123456
エンコードされていない認証情報rhevmadmin@domain.example.com:123456
base64 エンコードされた認証情報cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2
API ユーザーは、base64 でエンコードされた認証情報を以下のように提供します。

例2.2 適切な認証情報を使用した REST API へのアクセス

HEAD [base] HTTP/1.1
Host: [host]
Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2

HTTP/1.1 200 OK
...

重要

基本認証では、パスワードなどの潜在的な機密情報がプレーンテキストで送信されてしまいます。REST API には、プレーンテキストの要求をトランスポートレベルで暗号化する Hypertext Transfer Protocol Secure (HTTPS) が必要です。

重要

base64 ライブラリーによっては、結果を複数行に分け、行末には改行文字を付けることがあります。そのような場合には、ヘッダーが破損し、要求に問題が発生します。認証ヘッダーには、エンコードされた認証情報がヘッダー内に一行で記載されている必要があります。

2.3. 認証セッション

API は、認証セッションサポートの機能も提供します。API ユーザーが認証情報とともに最初の要求を送信すると、それ以降に送信する要求はすべて、セッション cookie を使用して認証することができます。以下の手順は、認証済みセッションを使用する方法を示しています。

手順2.3 認証済みセッションの要求

  1. Authorization および Prefer: persistent-auth を使用して要求を送信します。
    HEAD [base] HTTP/1.1
    Host: [host]
    Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2
    Prefer: persistent-auth
    
    HTTP/1.1 200 OK
    ...
    
    これにより、次のヘッダーの応答が返されます。
    Set-Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK; Path=/api; Secure
    
    JSESSIONID= 値を確認してください。上記の例では、この値は JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK です。
  2. 以降の要求にはすべて Prefer: persistent-auth ヘッダーと JSESSIONID= 値を指定した cookie ヘッダーを使用して送信します。認証済みセッションを使用することにより、Authorization が必要なくなります。
    HEAD [base] HTTP/1.1
    Host: [host]
    Prefer: persistent-auth
    cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK
    
    HTTP/1.1 200 OK
    ...
    
  3. セッションが必要なくなった場合は、Prefer: persistent-auth ヘッダーなしでサーバーへの要求を実行します。
    HEAD [base] HTTP/1.1
    Host: [host]
    Authorization: Basic cmhldm1hZG1pbkBibGFjay5xdW1yYW5ldC5jb206MTIzNDU2
    
    HTTP/1.1 200 OK
    ...
    


[1] HTTPS についての説明は RFC 2818 HTTP Over TLS を参照してください。
[2] 基本認証については、RFC 2617 HTTP Authentication: Basic and Digest Access Authentication に記載されている説明を参照してください。

第3章 REST API クイックスタートの例

本章では、基本的な Red Hat Enterprise Virtualization 環境をセットアップし、仮想マシンを作成する REST API の機能の例を示します。
以下の例には、通常の標準的な前提条件に加えて、次の項目が必要となります。
  • Red Hat Enterprise Virtualization Hypervisor をインストールした、ネットワーク接続/設定済みのホスト。
  • 仮想マシンにインストールする任意のオペレーティングシステムを格納した ISO ファイル。本章では、インストール ISO の例に Red Hat Enterprise Linux Server 6 を使用しています。
  • 選択したオペレーティングシステム ISO ファイルを更新する Red Hat Enterprise Virtualization の engine-iso-uploader ツール。
以下の例では、cURL を使用して、クライアントアプリケーションによる REST 要求について具体的に説明します。HTTP 要求に対応したアプリケーションはいずれも cURL の代わりに使用できる点に注意してください。

重要

以下の例では、記載内容をわかりやすくするために、HTTP 要求ヘッダーの Host:Authorization: のフィールドを省略していますが、これらのフィールドは必須フィールドであり、ご使用の Red Hat Enterprise Virtualization Manager インストール固有のデータを記載する必要があります。

重要

cURL の例にはすべて、認証情報 (USER:PASS) と証明書の場所 (CERT) 用のプレースホルダーが含まれています。cURL を使用して実行する要求がすべて証明および認証の要件を満たしていることを確認してください。

注記

Red Hat Enterprise Virtualization Manager は、各リソースの id 属性用にグローバル一意識別子 (GUID) を生成します。以下の例に記載の識別子コードは、ご使用の Red Hat Enterprise Virtualization 環境の識別子コードとは異なる場合があります。

3.1. 例: API エントリーポイントへのアクセス

以下の要求は、API の主要エントリーポイントの表現を取得します。

例3.1 API エントリーポイントへのアクセス

要求:

GET /api HTTP/1.1
Accept: application/xml

cURL コマンド:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] https://[RHEVM Host]:443/api

結果:

HTTP/1.1 200 OK
Content-Type: application/xml

<api>
    <link rel="capabilities" href="/api/capabilities"/>
    <link rel="clusters" href="/api/clusters"/>
    <link rel="clusters/search" href="/api/clusters?search={query}"/>
    <link rel="datacenters" href="/api/datacenters"/>
    <link rel="datacenters/search" href="/api/datacenters?search={query}"/>
    <link rel="events" href="/api/events"/>
    <link rel="events/search" href="/api/events?search={query}"/>
    <link rel="hosts" href="/api/hosts"/>
    <link rel="hosts/search" href="/api/hosts?search={query}"/>
    <link rel="networks" href="/api/networks"/>
    <link rel="roles" href="/api/roles"/>
    <link rel="storagedomains" href="/api/storagedomains"/>
    <link rel="storagedomains/search" href="/api/storagedomains?search={query}"/>
    <link rel="tags" href="/api/tags"/>
    <link rel="templates" href="/api/templates"/>
    <link rel="templates/search" href="/api/templates?search={query}"/>
    <link rel="users" href="/api/users"/>
    <link rel="groups" href="/api/groups"/>
    <link rel="domains" href="/api/domains"/>
    <link rel="vmpools" href="/api/vmpools"/>
    <link rel="vmpools/search" href="/api/vmpools?search={query}"/>
    <link rel="vms" href="/api/vms"/>
    <link rel="vms/search" href="/api/vms?search={query}"/>
    <special_objects>
        <link rel="templates/blank"
          href="/api/templates/00000000-0000-0000-0000-000000000000"/>
        <link rel="tags/root"
          href="/api/tags/00000000-0000-0000-0000-000000000000"/>
    </special_objects>
    <product_info>
        <name>Red Hat Enterprise Virtualization</name>
        <vendor>Red Hat</vendor>
        <version revision="0" build="0" minor="0" major="3"/>
    </product_info>
    <summary>
        <vms>
            <total>5</total>
            <active>0</active>
        </vms>
        <hosts>
            <total>1</total>
            <active>1</active>
        </hosts>
        <users>
            <total>1</total>
            <active>1</active>
        </users>
        <storage_domains>
            <total>2</total>
            <active>2</active>
        </storage_domains>
    </summary>
</api>

エントリーポイントは、仮想化環境内のコレクションへのリンクをユーザーに提供します。各コレクションリンクの rel= 属性は、各リンクの参照ポイントを提供します。この例の次のステップでは、rel="datacenter" リンクで入手可能な datacenter コレクションについて考察します。
エントリーポイントには product_infospecial_objectssummary などのその他のデータも含まれます。このようなデータについては別の章で説明しています。

3.2. 例: データセンターコレクションの一覧表示

Red Hat Enterprise Virtualization Manager は、インストール時に Default データセンターを作成します。以下の例では Default データセンターを仮想化環境の基盤として使用します。
以下の要求は、データセンターコレクションの表現を取得します。

例3.2 データセンターコレクションの一覧表示

要求:

GET /api/datacenters HTTP/1.1
Accept: application/xml

cURL コマンド:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] \
    https://[RHEVM Host]:443/api/datacenters

結果:

HTTP/1.1 200 OK
Content-Type: application/xml

<data_centers>
    <data_center href="/api/datacenters/00000002-0002-0002-0002-0000000003ab" id="00000002-0002-0002-0002-0000000003ab">
        <name>Default</name>
        <description>The default Data Center</description>
        <link rel="storagedomains"/>
          href="/api/datacenters/00000002-0002-0002-0002-0000000003ab/storagedomains"
        <link rel="clusters"/>
          href="/api/datacenters/00000002-0002-0002-0002-0000000003ab/clusters" 
        <link rel="networks"/>
          href="/api/datacenters/00000002-0002-0002-0002-0000000003ab/networks" 
        <link rel="permissions"/>
          href="/api/datacenters/00000002-0002-0002-0002-0000000003ab/permissions" 
        <link rel="quotas"/>
          href="/api/datacenters/00000002-0002-0002-0002-0000000003ab/quotas" 
        <link rel="iscsibonds"/>
          href="/api/datacenters/00000002-0002-0002-0002-0000000003ab/iscsibonds" 
        <link rel="qoss"/>
          href="/api/datacenters/00000002-0002-0002-0002-0000000003ab/qoss" 
        <local>false</local>
        <storage_format>v3</storage_format>
        <version major="3" minor="5"/>
        <supported_versions>
            <version major="3" minor="5"/>
        </supported_versions>
        <status>
            <state>up</state>
        </status>
    </data_center>
</data_centers>

Default データセンターの id コードに注意してください。このコードは、仮想化環境のその他のリソースに関連付けて、このデータセンターを特定します。
データセンターには storagedomains サブコレクションへのリンクも含まれます。データセンターは、このサブコレクションを使用して storagedomains メインコレクションからストレージドメインをアタッチします。これについては本章の後半で説明します。

3.3. 例: ホストクラスターコレクションの一覧表示

Red Hat Enterprise Virtualization Manage は、インストール時に Default のホストクラスターを作成します。以下の例は Default クラスターを使用して Red Hat Enterprise Virtualization 環境内のリソースをグループ化します。
以下の要求は、クラスターコレクションの表現を取得します。

例3.3 ホストクラスターコレクションの一覧表示

要求:

GET /api/clusters HTTP/1.1
Accept: application/xml

cURL コマンド:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] \
    https://[RHEVM Host]:443/api/clusters

結果:

HTTP/1.1 200 OK
Content-Type: application/xml

<clusters>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95">
        <name>Default</name>
        <description>The default server cluster</description>
        <link rel="networks"
          href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks"/>
        <link rel="permissions"
          href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/permissions"/>
        <cpu id="Intel Penryn Family"/>
        <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
          href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/>
        <memory_policy>
            <overcommit percent="100"/>
            <transparent_hugepages>
                <enabled>false</enabled>
            </transparent_hugepages>
        </memory_policy>
        <scheduling_policy/>
        <version minor="0" major="3"/>
        <error_handling>
            <on_error>migrate</on_error>
        </error_handling>
    </cluster>
</clusters>

Default ホストクラスターの id コードに注意してください。このコードは、仮想化環境のその他のリソースに関連付けて、このホストクラスターを特定します。
Default クラスターは、data_center 要素の id 属性と href 属性を使用したリレーションシップにより Default データセンターに関連付けられます。
networks のサブコレクションには、このクラスターの関連付けられたネットワークリソース一覧が含まれます。次のセクションでは networks のコレクションについて詳細に考察します。

3.4. 例: 論理ネットワークコレクションの一覧表示

Red Hat Enterprise Virtualization Manager は、インストール時にデフォルトの ovirtmgmt ネットワークを作成します。このネットワークは、Red Hat Enterprise Virtualization Manager が Hypervisor ホストにアクセスするための管理ネットワークとして機能します。
このネットワークは Default クラスターに関連付けられた、Default データセンターのメンバーとなります。以下の例では、仮想マシンへの接続に ovirtmgmt ネットワークを使用しています。
以下の要求は、論理ネットワークコレクションの表現を取得します。

例3.4 論理ネットワークコレクションの一覧表示

要求:

GET /api/networks HTTP/1.1
Accept: application/xml

cURL コマンド:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] \
    https://[RHEVM Host]:443/api/networks

結果:

HTTP/1.1 200 OK
Content-Type: application/xml

<networks>
    <network id="00000000-0000-0000-0000-000000000009"
      href="/api/networks/00000000-0000-0000-0000-000000000009">
        <name>ovirtmgmt</name>
        <description>Management Network</description>
        <data_center id="01a45ff0-915a-11e0-8b87-5254004ac988"
          href="/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988"/>
        <stp>false</stp>
        <status>
            <state>operational</state>
        </status>
        <display>false</display>
    </network>
</networks>

ovirtmgmt ネットワークは、データセンターの id コードを使用したリレーションシップにより Default データセンターにアタッチされます。
ovirtmgmt ネットワークは、クラスターの network サブコレクション内のリレーションシップによっても、Default クラスターにアタッチされます。

3.5. 例: ホストコレクションの一覧表示

以下の例では、Red Hat Enterprise Virtualization Hypervisor ホストを使用しています。Red Hat Enterprise Virtualization Manager は、設定済みの Red Hat Enterprise Virtualization Hypervisor を自動的に登録します。この例は、ホストコレクションの表現を取得し、仮想化環境に登録されている hypervisor という名前の Red Hat Enterprise Virtualization Hypervisor ホストを表示します。

例3.5 ホストコレクションの一覧表示

要求:

GET /api/hosts HTTP/1.1
Accept: application/xml

cURL コマンド:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] \
    https://[RHEVM Host]:443/api/hosts

結果:

HTTP/1.1 200 OK
Accept: application/xml

<hosts>
    <host id="0656f432-923a-11e0-ad20-5254004ac988"
      href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988">
        <name>hypervisor</name>
        <actions>
            <link rel="install"
              href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/install"/>
            <link rel="activate"
              href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/activate"/>
            <link rel="fence"
              href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/fence"/>
            <link rel="deactivate"
              href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/deactivate"/>
            <link rel="approve"
              href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/approve"/>
            <link rel="iscsilogin"
              href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/iscsilogin"/>
            <link rel="iscsidiscover"
              href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/iscsidiscover"/>
            <link rel="commitnetconfig"
              href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/
              commitnetconfig"/>
        </actions>
        <link rel="storage"
          href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/storage"/>
        <link rel="nics"
          href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/nics"/>
        <link rel="tags"
          href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/tags"/>
        <link rel="permissions"
          href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/permissions"/>
        <link rel="statistics"
          href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/statistics"/>
        <address>10.64.14.110</address>
        <status>
            <state>non_operational</state>
        </status>
        <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
          href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
        <port>54321</port>
        <storage_manager>true</storage_manager>
        <power_management>
            <enabled>false</enabled>
            <options/>
        </power_management>
        <ksm>
            <enabled>false</enabled>
        </ksm>
        <transparent_hugepages>
            <enabled>true</enabled>
        </transparent_hugepages>
        <iscsi>
            <initiator>iqn.1994-05.com.example:644949fe81ce</initiator>
        </iscsi>
        <cpu>
            <topology cores="2"/>
            <name>Intel(R) Core(TM)2 Duo CPU E8400 @ 3.00GHz</name>
            <speed>2993</speed>
        </cpu>
        <summary>
            <active>0</active>
            <migrating>0</migrating>
            <total>0</total>
        </summary>
    </host>
</hosts>

Default ホストの id コードに注意してください。このコードは、仮想化環境のその他のリソースに関連付けてこのホストを特定します。
このホストは、Default のメンバーで、nics サブコレクションにアクセスすると、このホストが ovirtmgmt ネットワークに接続されていることが表示されます。

3.6. 例: CPU プロファイルの一覧表示

以下の要求は、CPU プロファイルの表現を取得します。

例3.6 CPU プロファイルの一覧表示

要求:

GET /api/cpuprofiles HTTP/1.1
Accept: application/xml

cURL コマンド:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] --cacert [CERT] https://[RHEVM Host]:443/api/cpuprofiles

結果:

HTTP/1.1 200 OK
Content-Type: application/xml

<cpu_profiles>
    <cpu_profile href="0000001a-001a-001a-001a-00000000035e" id="0000001a-001a-001a-001a-00000000035e">
        <name>Default</name>
        <link href="/api/cpuprofiles/0000001a-001a-001a-001a-00000000035e/permissions" rel="permissions"/>
        <cluster href= "/api/clusters/00000001-0001-0001-0001-00000000021b" id="00000001-0001-0001-0001-00000000021b"/>
    </cpu_profile>
    <cpu_profile href="fc4b9188-f87f-44f9-b9c5-c7665e10e0a2" id="fc4b9188-f87f-44f9-b9c5-c7665e10e0a2">
        <name>Premium</name>
        <description>Full service available</description>
        <link href="/api/cpuprofiles/fc4b9188-f87f-44f9-b9c5-c7665e10e0a2/permissions" rel="permissions"/>
        <qos href= "/api/datacenters/00000002-0002-0002-0002-0000000000f7/qoss/5afe49e3-aac4-4b7b-bb83-11b9aef285e1" id="5afe49e3-aac4-4b7b-bb83-11b9aef285e1"/>
        <cluster href= "/api/clusters/00000001-0001-0001-0001-00000000021b" id="00000001-0001-0001-0001-00000000021b"/>
    </cpu_profile>
    <cpu_profile href="48c600f4-6768-49ca-9c16-a877d0e586e5" id="48c600f4-6768-49ca-9c16-a877d0e586e5">
        <name>Budget</name>
        <description>Limited CPU</description>
        <link href="/api/cpuprofiles/48c600f4-6768-49ca-9c16-a877d0e586e5/permissions" rel="permissions"/>
        <cluster href= "/api/clusters/00000001-0001-0001-0001-00000000021b" id="00000001-0001-0001-0001-00000000021b"/>
    </cpu_profile>
    <cpu_profile href="48c600f4-6768-49ca-9c16-a877d0e586e5" id="48c600f4-6768-49ca-9c16-a877d0e586e5">
        <name>Backup</name>
        <link href="/api/cpuprofiles/d510b042-42f0-4cb2-9d2e-25fcc28d6c5f/permissions" rel="permissions"/>
        <cluster href= "/api/clusters/668cab0c-9185-4eaa-9942-658284eeecdd" id="668cab0c-9185-4eaa-9942-658284eeecdd"/>
    </cpu_profile>
</cpu_profiles>

3.7. 例: ホストの承認

hypervisor ホストリソースには、approve のアクションが含まれます。ユーザーは POST 要求を使用して、このアクションの URI にアクセスします。

例3.7 事前設定済みの Red Hat Enterprise Virtualization Hypervisor ホストの承認

要求:

POST /api/hosts/0656f432-923a-11e0-ad20-5254004ac988/approve HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

cURL コマンド:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<action/>" \
    https://[RHEVM Host]:443/api/hosts/0656f432-923a-11e0-ad20-5254004ac988/approve

POST 要求には、アクションを開始するためのメッセージエンティティーの本文が必要です。アクションには、追加のパラメーターは必要ないため、本文には空の action 要素が記載されます。
approve アクションは、Red Hat Enterprise Virtualization Hypervisor ホスト以外には使用しないでください。Red Hat Enterprise Linux ホストの場合は、仮想化環境への接続に異なるプロセスが必要となります。
これにより仮想化環境でのホストの使用が承認されアクティブ化されます。hypervisorstatusnon_operational から up に変わります。

3.8. 例: NFS データストレージの作成

NFS データストレージドメインは、エクスポートされた NFS 共有です。データセンターにアタッチされ、仮想化ゲストのイメージを格納するストレージを提供します。新規ストレージドメインを作成するには、POST 要求にストレージドメインの表現を記載し、ストレージドメインコレクションの URL に送信する必要があります。
Red Hat Enterprise Virtualization 3.6 以降では、ストレージドメインの削除後にワイプのオプションをデフォルトで有効にすることができます。この設定は、POST 要求で <wipe_after_delete> を指定します。このオプションは、ドメインの作成後に編集することが可能ですが、その場合にはすでに存在していたディスクの「削除後にワイプ」プロパティーは変更されません。

例3.8 NFS データストレージドメインの作成

要求:

POST /api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_domain>
  <name>data1</name>
  <type>data</type>
  <storage>
    <type>nfs</type>
    <address>192.168.0.10</address>
    <path>/data1</path>
  </storage>
  <host>
    <name>hypervisor</name>
  </host>
</storage_domain>

cURL コマンド:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<storage_domain><name>data1</name><type>data</type> \
    <storage><type>nfs</type><address>192.168.0.10</address> \
    <path>/data1</path></storage> \ 
    <host><name>hypervisor</name></host></storage_domain>" \
    https://[RHEVM Host]:443/api/storagedomains

API は、192.168.0.10:/data1 のエクスポートパスで data1 という名前の NFS データストレージドメインを作成し、hypervisor ホスト経由のストレージドメインへのアクセスを設定します。また、API は新たに作成したストレージドメインリソースの表現を以下のように返します。
結果:

HTTP/1.1 200 OK
Accept: application/xml

<storage_domain id="9ca7cb40-9a2a-4513-acef-dc254af57aac"
  href="/api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac">
    <name>data1</name>
    <link rel="permissions"
      href="/api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/
      permissions"/>
    <link rel="files"
      href="/api/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/files"/>
    <type>data</type>
    <master>false</master>
    <storage>
        <type>nfs</type>
        <address>192.168.0.10</address>
        <path>/data1</path>
    </storage>
    <available>175019917312</available>
    <used>27917287424</used>
    <committed>10737418240</committed>
    <storage_format>v1</storage_format>
    <host id="0656f432-923a-11e0-ad20-5254004ac988"
      href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988">
</storage_domain>

3.9. 例: NFS ISO ストレージの作成

NFS ISO ストレージドメインは、データセンターにアタッチされたマウント済みの NFS 共有です。DVD/CD-ROM の ISO および仮想フロッピーディスク (VFD) などのイメージファイル用のストレージを提供します。新規ストレージドメインを作成するには、ストレージドメインの表現を記載した POST 要求をストレージドメインコレクションの URL に送信する必要があります。
Red Hat Enterprise Virtualization 3.6 以降では、ストレージドメインの削除後にワイプのオプションをデフォルトで有効にすることができます。この設定は、POST 要求で <wipe_after_delete> を指定します。このオプションは、ドメインの作成後に編集することが可能ですが、その場合にはすでに存在していたディスクの「削除後にワイプ」プロパティーは変更されません。

例3.9 NFS ISO ストレージドメインの作成

要求:

POST /api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_domain>
  <name>iso1</name>
  <type>iso</type>
  <storage>
    <type>nfs</type>
    <address>192.168.0.10</address>
    <path>/iso1</path>
  </storage>
  <host>
    <name>hypervisor</name>
  </host>
</storage_domain>

cURL コマンド:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<storage_domain><name>iso1</name><type>iso</type> \
    <storage><type>nfs</type><address>192.168.0.10</address> \
    <path>/iso1</path></storage> \
    <host><name>hypervisor</name></host></storage_domain>" \
    https://[RHEVM Host]:443/api/storagedomains

API は、エクスポートパスが 192.168.0.10:/iso1iso1 という名前の NFS iso ストレージドメインを作成し、hypervisor ホスト経由でストレージドメインにアクセスします。また、API は新たに作成したストレージドメインリソースの表現を以下のように返します。
結果:

HTTP/1.1 200 OK
Accept: application/xml

<storage_domain id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
  href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da">
    <name>iso1</name>
    <link rel="permissions"
      href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/
      permissions"/>
    <link rel="files"
      href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files"/>
    <type>iso</type>
    <host id="" href="">
    <master>false</master>
    <storage>
        <type>nfs</type>
        <address>192.168.0.10</address>
        <path>/iso1</path>
    </storage>
    <available>82678120448</available>
    <used>18253611008</used>
    <committed>0</committed>
    <storage_format>v1</storage_format>
    <host id="0656f432-923a-11e0-ad20-5254004ac988"
      href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988">        
</storage_domain>

3.10. 例: データセンターへのストレージドメインのアタッチ

以下の例は、data1iso1 のストレージドメインを Default データセンターにアタッチします。

例3.10 Default データセンターへの data1 ストレージドメインのアタッチ

要求:

POST /api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_domain>
  <name>data1</name>
</storage_domain>

cURL コマンド:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<storage_domain><name>data1</name></storage_domain>" \
    https://[RHEVM Host]:443/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains

例3.11 Default データセンターへの iso1 ストレージドメインのアタッチ

要求:

POST /api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_domain>
  <name>iso1</name>
</storage_domain>

cURL コマンド:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<storage_domain><name>iso1</name></storage_domain>" \
    https://[RHEVM Host]:443/api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/storagedomains

上記の POST 要求は、新規作成された 2 つの storage_domain リソースを Default データセンターの storagedomains サブコレクション内に配置します。これは、storagedomains サブコレクションにアタッチされたデータセンターストレージドメインが含まれることを意味します。

3.11. 例: ストレージドメインのアクティブ化

以下の例は、Red Hat Enterprise Virtualization Manager で使用するために、data1iso1 の各ストレージドメインをアクティブ化します。

例3.12 data1 ストレージドメインのアクティブ化

要求:

POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/
9ca7cb40-9a2a-4513-acef-dc254af57aac/activate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

cURL コマンド:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<action/>" \
    https://[RHEVM Host]:443/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/9ca7cb40-9a2a-4513-acef-dc254af57aac/activate

例3.13 iso1 ストレージドメインのアクティブ化

要求:

POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/
00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/activate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

cURL コマンド:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<action/>"
    https://[RHEVM Host]:443/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/activate

これにより、両ストレージドメインがアクティブ化され、データセンターに使用できるようになります。

3.12. 例: 仮想マシンの作成

以下の例では、仮想化環境の Blank テンプレートをベースとして使用し、Default クラスター上に vm1 という名前の仮想マシンを作成します。また、この要求は、仮想マシンの memory を 512 MB に定義し、boot デバイスを仮想ハードディスクに設定します。

例3.14 仮想マシンの作成

要求:

POST /api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
    <name>vm1</name>
    <cluster>
        <name>default</name>
    </cluster>
    <template>
        <name>Blank</name>
    </template>
    <memory>536870912</memory> 
    <os>
        <boot dev="hd"/>
    </os>
    <cpu_profile id="0000001a-001a-001a-001a-00000000035e"/>
</vm>

cURL コマンド:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" -u [USER:PASS] --cacert [CERT] -d "<vm><name>vm1</name><cluster><name>default</name></cluster><template><name>Blank</name></template><memory>536870912</memory><os><boot dev='hd'/></os><cpu_profile id='0000001a-001a-001a-001a-00000000035e'/></vm>" https://[RHEVM Host]:443/api/vms

結果

HTTP/1.1 200 OK
Accept: application/xml    

<vm id="6efc0cfa-8495-4a96-93e5-ee490328cf48"
  href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48">
    <name>vm1</name>
    <actions>
        <link rel="shutdown"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/shutdown"/>
        <link rel="start"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start"/>
        <link rel="stop"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/stop"/>
        <link rel="reboot"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/reboot"/>
        <link rel="suspend"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/suspend"/>
        <link rel="detach"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/detach"/>
        <link rel="export"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/export"/>
        <link rel="move"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/move"/>
        <link rel="ticket"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/ticket"/>
        <link rel="migrate"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/migrate"/>
        <link rel="undo_snapshot"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/undo_snapshot"/>
        <link rel="commit_snapshot"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/commit_snapshot"/>
        <link rel="preview_snapshot"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/preview_snapshot"/>
        <link rel="logon"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/logon"/>
        <link rel="cancelmigration"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cancelmigration"/>
        <link rel="maintenance"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/maintenance"/>
        <link rel="clone"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/clone"/>
    </actions>
    <link rel="applications"
      href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/applications"/>
    <link rel="disks"
      href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks"/>
    <link rel="nics"
      href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics"/>
    <link rel="cdroms"
      href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms"/>
    <link rel="snapshots"
      href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/snapshots"/>
    <link rel="tags"
      href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/tags"/>
    <link rel="permissions"
      href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/permissions"/>
    <link rel="statistics"
      href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/statistics"/>
    <link rel="reporteddevices"
      href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/reporteddevices"/>
    <link rel="watchdogs"
      href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/watchdogs"/>
    <link rel="sessions"
      href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/sessions"/>
    <type>desktop</type>
    <status>
        <state>down</state>
    </status>
    <memory>536870912</memory>
    <cpu>
        <topology cores="1" sockets="1"/>
    </cpu>
    <os type="Unassigned">
        <boot dev="cdrom"/>
    </os>
    <high_availability>
        <enabled>false</enabled>
        <priority>0</priority>
    </high_availability>
    <display>
        <type>spice</type>
        <monitors>1</monitors>
        <single_qxl_pci>false</single_qxl_pci>
        <allow_override>false</allow_override>
        <smartcard_enabled>false</smartcard_enabled>
        <file_transfer_enabled>true</file_transfer_enabled>
        <copy_paste_enabled>true</copy_paste_enabled>
    </display>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <template id="00000000-0000-0000-0000-000000000000"
      href="/api/templates/00000000-0000-0000-0000-000000000000"/>
    <stop_time>2011-06-15T04:48:02.167Z</stop_time>
    <creation_time>2011-06-15T14:48:02.078+10:00</creation_time>
    <origin>rhev</origin>
    <stateless>false</stateless>
    <delete_protected>false</delete_protected>
    <sso>
        <methods>
            <method id="GUEST_AGENT"/>
        </methods>
    </sso>
    <console enabled="false"/>
    <timezone>Etc/GMT</timezone>
    <initialization>
        <configuration>
            <type>ovf</type>
            <data>...</data>
        </configuration> 
    </initialization>
    <placement_policy>
        <affinity>migratable</affinity>
    </placement_policy>
    <memory_policy>
        <guaranteed>536870912</guaranteed>
        <ballooning>true</ballooning>
    </memory_policy>
    <usb>
        <enabled>false</enabled>
    </usb>
    <soundcard_enabled>true</soundcard_enabled>
    <migration_downtime>-1</migration_downtime>
    <virtio_scsi enabled="true"/>
    <cpu_profile id="0000001a-001a-001a-001a-00000000035e"/>
    <next_run_configuration_exists>false</next_run_configuration_exists>
    <numa_tune_mode>interleave</numa_tune_mode>
</vm>

3.13. 例: 仮想マシン NIC の作成

以下の例では、仮想ネットワークインターフェースを作成して、サンプルの仮想マシンを ovirtmgmt ネットワークに接続します。

例3.15 仮想マシン NIC の作成

要求:

POST /api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics HTTP/1.1
Accept: application/xml
Content-type: application/xml

<nic>
  <interface>virtio</interface>
  <name>nic1</name>
  <network>
    <name>ovirtmgmt</name>
  </network>
</nic>

cURL コマンド:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<nic><name>nic1</name><network><name>ovirtmgmt</name></network></nic>" \
    https://[RHEVM Host]:443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/nics

3.14. 例: 仮想マシン用ストレージディスクの作成

以下の例では、サンプルの仮想マシン用に 8 GB の Copy On Write のストレージディスクを作成します。

例3.16 仮想マシン用ストレージディスクの作成

要求:

POST /api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk>
    <storage_domains>
        <storage_domain id="9ca7cb40-9a2a-4513-acef-dc254af57aac"/>  
    </storage_domains>    
    <size>8589934592</size>
    <type>system</type>
    <interface>virtio</interface>
    <format>cow</format>
    <bootable>true</bootable>
</disk>

cURL コマンド:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<disk><storage_domains> \
    <storage_domain id='9ca7cb40-9a2a-4513-acef-dc254af57aac'/> \
    </storage_domains><size>8589934592</size><type>system</type> \
    <interface>virtio</interface><format>cow</format> \
    <bootable>true</bootable></disk>" \
    https://[RHEVM Host]:443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/disks

storage_domain 要素は、data1 ストレージドメインにディスクを保存するよう API に指示します。

3.15. 例: 仮想マシンへの ISO イメージのアタッチ

サンプルの仮想マシンのブートメディアには、オペレーティングシステムインストール用 CD-ROM または DVD の ISO イメージが必要です。以下の例では、Red Hat Enterprise Server 6 の ISO を使用しています。
仮想マシンが ISO イメージを使用できるようするには、その ISO イメージが iso1 ISO ドメインで使用可能である必要があります。Red Hat Enterprise Virtualization プラットフォームは、ISO イメージを適切なユーザー権限で適切なディレクトリーパスにアップロードするためのアップローダーツールを提供しています。
ISO のアップロードが完了したら、API ユーザーは ISO ストレージドメインの files サブコレクションを要求してファイルリソースを表示します。

例3.17 ISO ストレージドメイン内の files サブコレクションの表示

要求:

GET /api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files HTTP/1.1
Accept: application/xml

cURL コマンド:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] --cacert [CERT] \
    https://[RHEVM Host]:443/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files

API は、files サブコレクションの表現を以下のように返します。
<files>
    <file id="rhel-server-6.0-x86_64-dvd.iso"
      href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/
      files/rhel-server-6.0-x86_64-dvd.iso.iso">
        <name>rhel-server-6.0-x86_64-dvd.iso.iso</name>
        <storage_domain id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
          href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/>
    </file>
</files>
API ユーザーは、rhel-server-6.0-x86_64-dvd.iso をサンプルの仮想マシンにアタッチします。ISO イメージのアタッチは、管理ポータルまたはユーザーポータルで CD/DVD を変更 を使用するのと同じです。

例3.18 仮想マシンへの ISO イメージのアタッチ

要求:

POST /api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms HTTP/1.1
Accept: application/xml
Content-type: application/xml

<cdrom>
  <file id="rhel-server-6.0-x86_64-dvd.iso"/>
</cdrom>

cURL コマンド:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<cdrom><file id='rhel-server-6.0-x86_64-dvd.iso'/></cdrom>" \
    https://[RHEVM Host]:443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/cdroms

3.16. 例: 仮想マシンの起動

仮想化環境が完成し、仮想マシンが機能するために必要なコンポーネントがすべて実装されたところで、次の例では、start アクションを使用して仮想マシンを起動します。

例3.19 仮想マシンの起動

要求:

POST /api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
  <vm>
    <os>
      <boot dev="cdrom"/>
    </os>
  </vm>
</action>

cURL コマンド:

# curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" \
    -u [USER:PASS] --cacert [CERT] \
    -d "<action><vm><os><boot dev='cdrom'/></os></vm></action>" \
    https://[RHEVM Host]:443/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48/start

追加のメッセージエンティティーは、今回のブートでのみ、仮想マシンの起動デバイスを CD-ROM に設定しています。これにより仮想マシンは、アタッチされた ISO イメージから Red Hat Enterprise Server 6 をインストールできるようになります。それ以降の起動では、ブートデバイスは disk に戻ります。

3.17. 例: システムイベントのチェック

vm1start アクションは events コレクション内に複数のエントリーを作成します。以下の例は、イベントコレクションを一覧表示し、仮想マシンを起動している API 固有のイベントを特定します。

例3.20 イベントコレクションの一覧表示

要求:

GET /api/events HTTP/1.1
Accept: application/xml

cURL コマンド:

# curl -X GET -H "Accept: application/xml" -u [USER:PASS] \
    --cacert [CERT] \
    https://[RHEVM Host]:443/api/events

結果:

<events>
    ...
    <event id="103" href="/api/events/103">
        <description>User admin logged out.</description>
        <code>31</code>
        <severity>normal</severity>
        <time>2011-06-29T17:42:41.544+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73" 
          href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
    <event id="102" href="/api/events/102">
        <description>vm1 was started by admin (Host: hypervisor).</description>
        <code>153</code>
        <severity>normal</severity>
        <time>2011-06-29T17:42:41.499+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73"
          href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
        <vm id="6efc0cfa-8495-4a96-93e5-ee490328cf48"
          href="/api/vms/6efc0cfa-8495-4a96-93e5-ee490328cf48"/>
        <host id="0656f432-923a-11e0-ad20-5254004ac988"
          href="/api/hosts/0656f432-923a-11e0-ad20-5254004ac988"/>
    </event>
    <event id="101" href="/api/events/101">
        <description>User admin logged in.</description>
        <code>30</code>
        <severity>normal</severity>
        <time>2011-06-29T17:42:40.505+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73"
          href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
    ...
</events>

以下のイベントが発生します。
  • id="101": API は admin ユーザーのユーザー名とパスワードで認証を行います。
  • id="102": API は admin ユーザーとして、hypervisor ホストで vm1 を起動します。
  • id="103": API は admin ユーザーアカウントからログアウトします。

第4章 エントリーポイント

ホストベース で構成されるエントリーポイント URI に対して GET 要求を実行して、API との対話を開始します。

例4.1 API エントリーポイントへのアクセス

ホストwww.example.com で、ベース/api の場合は、要求ではエントリーポイントが以下のように表示されます。
GET /api HTTP/1.1
Accept: application/xml
Host: www.example.com
Authorization: [base64 encoded credentials]

HTTP/1.1 200 OK
Content-Type: application/xml

<api>
    <link rel="hosts" href="/api/hosts"/>
    <link rel="vms" href="/api/vms"/>
    ...
    <product_info>
        <name>Red Hat Enterprise Virtualization</name>
        <vendor>Red Hat</vendor>
        <version revision="0" build="0" minor="1" major="3"/>
    </product_info>    
    <special_objects>
        <link rel="templates/blank" href="..."/>
        <link rel="tags/root" href="..."/>
    </special_objects>
    <summary>
        <vms>
            <total>10</total>
            <active>3</active>
        </vms>
        <hosts>
            <total>2</total>
            <active>2</active>
        </hosts>
        <users>
            <total>8</total>
            <active>2</active>
        </users>
        <storage_domains>
            <total>2</total>
            <active>2</active>
        </storage_domains>
    </summary>
</api>

注記

記載内容をわかりやすくするために、これ以降の例ではすべて Host:Authorization: の要求ヘッダーを省略しています。 また、base はデフォルトの /api パスであることを前提としています。実際のベースパスは、実装によって異なります。

4.1. 製品情報

Red Hat Enterprise Virtualization 環境が適切であるかどうかを判断できるように、エントリーポイントには product_info 要素が記載されています。これには、製品の namevendorversion などが含まれます。

例4.2 正規の Red Hat Enterprise Virtualization 環境の確認

次の要素は、正規の Red Hat Enterprise Virtualization 3.2 環境を識別します。
<api>
    ...
    <product_info>
        <name>Red Hat Enterprise Virtualization</name>
        <vendor>Red Hat</vendor>
        <version revision="0" build="0" minor="2" major="3"/>
    </product_info>
    ...
</api>

4.3. 特殊オブジェクトの要素

特殊オブジェクトの要素は、仮想化環境内の特殊固定リソースとのリレーションシップを定義します。

表4.3 特殊オブジェクト

リレーションシップ説明
templates/blank仮想化環境のデフォルトの blank 仮想マシンテンプレート。このテンプレートは、単一のクラスター内のみに存在する標準テンプレートとは対照的に、全クラスター内に存在します。
tags/root仮想化環境のタグ階層のベースとして機能する root タグ

4.4. サマリーの要素

サマリーの要素は、システムの統計の俯瞰的な概要を示します。

表4.4 サマリーの要素

要素説明
vms仮想マシンの合計数およびアクティブな仮想マシンの合計数
hostsホストの合計数およびアクティブなホストの合計数
usersユーザーの合計数およびアクティブなユーザーの合計数
storage_domainsストレージドメインの合計数およびアクティブなストレージドメインの合計数

4.5. RESTful Service Description Language (RSDL)

RESTful Service Description Language (RSDL) は、REST API 内の構造および要素の記述を単一の全体的な XML 仕様で提供します。RSDL を呼び出すには、以下の要求を使用します。
GET /api?rsdl HTTP/1.1
Accept: application/xml
これにより、以下のような形式の XML 文書が提供されます。
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rsdl href="/api?rsdl" rel="rsdl">
    <description>...</description>
    <version major="3" minor="1" build="0" revision="0"/>
    <schema href="/api?schema" rel="schema">
        <name>...</name>
        <description>...</description>
    </schema>
    <links>
        <link href="/api/capabilities" rel="get">
            ...
        </link>
        ...
    </links>
</rsdl>

表4.5 RSDL 構造の要素

要素説明
descriptionプレーンテキストで記述された RSDL 文書
versionmajor リリース、minor リリース、build および revision を含む API バージョン
schemaXML Schema (XSD) ファイルへのリンク
linksAPI 内の各 link を定義します。
link 要素には以下のような構造が含まれます。
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rsdl href="/api?rsdl" rel="rsdl">
    ...
    <links>
        <link href="/api/..." rel="...">
            <request>
                <http_method>...</http_method>
                <headers>
                    <header>
                        <name>...</name>
                        <value>...</value>
                    </header>
                    ...
                </headers>
                <body>
                    <type>...</type>
                    <parameters_set>
                        <parameter required="..." type="...">
                            <name>...</name>
                        </parameter>
                        ...
                    </parameters_set>
                </body>
            </request>
            <response>
                <type>...</type>
            </response>
        </link>
        ...
    </links>
</rsdl>

表4.6 RSDL リンク構造の要素

要素説明
linkAPI 要求の URI。URI の属性 (href) およびリレーションシップタイプの属性 (rel) が含まれます。
requestリンクに必要な要求プロパティーを定義します。
http_methodそのリンクにアクセスするメソッドのタイプ。REST API アクセスの標準 HTTP メソッド (GETPOSTPUTDELETE) が含まれます。
headersHTTP 要求のヘッダーを定義します。一連の header 要素が含まれ、ヘッダーを定義するためのヘッダーの namevalue がそれぞれに記載されます。
bodyHTTP 要求の本文を定義します。リソース typeparameter_set が記載され、それらが要求に required (必須) であるかどうかと、データ type を定義する属性を示す parameter 要素のセットが含まれます。parameter 要素には、変更すべき Red Hat Enterprise Virtualization Manager プロパティーを定義する name 要素も含まれます。また、typecollection に指定されている場合には、さらなる parameter_set サブセットも含まれます。
responseHTTP 要求の出力を定義します。出力するリソースの構造を定義する type 要素が含まれます。
Red Hat Enterprise Virtualization 環境を制御するために全リンクとパラメーター要件をマッピングするメソッドには、アプリケーション内の RSDL を使用します。

4.6. Red Hat Enterprise Virtualization Windows ゲストの VSS サポート

Red Hat Enterprise Virtualization のバックアップ/リストア API は、qemu-ga を使用した Microsoft Windows Volume Shadow Copy Service (VSS) との統合を提供します。VSS プロバイダー登録は、ゲストツールのデプロイの一環として、ゲストレベルで行われます。
qemu-ga は VSS サポートを提供し、ライブスナップショットは可能な場合に休止を試みます。

4.7. QEMU ゲストエージェントの概要

Red Hat Enterprise Linux 6.4 では、QEMU Guest Agent (QEMU GA) が Linux のゲスト仮想マシンを破損から保護していました。スナップショット要求の発行やディスクのバックアップ用コピー作成の前には、管理スタック (libvirt) が virtio-serial ポートを介して guest-fsfreeze-freeze QMP コマンドを QEMU GA に送信し、このコマンドによりゲストエージェントは FIFREEZE ioctl() カーネル関数を用いて仮想マシンの全ファイルシステムを凍結していました。この ioctl() 関数は、ゲスト仮想マシンの Linux カーネルにより実装されています。この関数によってゲスト仮想マシンのカーネル内のファイルシステムキャッシュがフラッシュされ、ファイルシステムが一貫性のある状態となり、そのファイルシステムに対するユーザースペーススレッドの書き込みアクセスが拒否されます。
処理が正常に終了したことを QEMU GA が報告した場合のみ、libvirt によりスナップショットの作成が続行されます。完了時には、libvirt が virtio-serial ポートを介して guest-fsfreeze-thaw QMP コマンドを QEMU GA に送信します。このコマンドは、FITHAW ioctl() を発行するように QEMU GA に指示します。これにより、以前に書き込みアクセスを拒否されたユーザースペーススレッドのブロックが解除され、通常の処理が再開されます。このプロセスでは、仮想ディスクのスナップショットの作成時に、アプリケーションレベルのデータで一貫した状態が確保されませんでした。これが顕著に見られたのは、スナップショットから復元したファイルシステムにおいて、fsck ユーティリティーが問題を検出しなかったにも拘らず、各種アプリケーションがスナップショットの作成時点から処理を開始できず、ユーザースペースの処理によりディスク上のファイルへ内部バッファーの書き込みが行われなかった場合などです。
Red Hat Enterprise Linux 6.5 では、ファイルとアプリケーションレベルの両方での同期 (フラッシング) が確実に行われます。ゲストのシステム管理者は、アプリケーション固有の凍結/解凍フックスクリプトを記述してインストールすることができます。ファイルシステムを凍結する前には、QEMU GA がメインフックスクリプト (QEMU GA パッケージに同梱) を起動します。メインフックスクリプトは次に、ゲストシステムの管理者が用意した個々のアプリケーション固有のスクリプトを呼び出し、それによってゲスト仮想マシンのアプリケーションがすべて一時的に非アクティブ化されます。これらのアクションはすべて、モードが「freeze」に変わってから実行されます。
ファイルシステムが凍結される直前には、ゲストシステムの管理者のスクリプトにより、データベースおよびその他のファイルシステムアプリケーションは作業バッファーを仮想ディスクにフラッシュして、それ以降のクライアント接続の受け入れを停止します。アプリケーションは次にデータファイルを一貫性のある状態にし、再アクティブ化された (または新たに起動された) アプリケーションインスタンスで (バックアップから仮想ディスクを復元した後に) プロセスの再開が可能となります。すべてのスクリプトが実行されて、それぞれのアプリケーションが非アクティブ化され、メインフックスクリプトが返されると、QEMU GA はファイルシステムの凍結を続行し、管理スタックがスナップショットを作成します。これらの処理がすべて完了した後には、スナップショットが作成されていることが確認され、ファイルシステムが書き込み要求に対するサービスを再開します。このプロセスは解凍と呼ばれます。
解凍は凍結の逆の順序で処理されます。 QEMU GA は、libvirt から指示を受けて、ゲスト仮想マシンのファイルシステムを解凍します。次に (メインスクリプトを使って) 個別のフックスクリプトを起動して、凍結プロセス中に非アクティブ化されていたアプリケーションを再開または再起動します。

4.8. VSS トランザクションフロー

バックアップの処理にあたっては、リクエスターとライターが調整して、データをバックアップする安定したシステムイメージの提供 (シャドーコピーされたボリューム)、用途に基づいたファイルのグループ化、保存されているデータに関する情報の保存といった複数の作業を実行します。これらはすべて、ライターの通常のワークフローによる割り込みを最小限に抑えた状態で行う必要があります。
リクエスター (この場合は、バックアップベンダー) は、ライターにメタデータのクエリーを実行し、このデータを処理して、シャドーコピーとバックアップの操作の開始前にライターに通知し、またシャドーコピーとバックアップの操作の後にも再度ライターに通知します。
ゲストツールのインストール後に QEMU VSS プロバイダーを Windows OS で登録する方法は以下のとおりです。
C:\Users\Administrator>vssadmin list providers
vssadmin 1.1 - Volume Shadow Copy Service administrative command-line tool
(C) Copyright 2001-2005 Microsoft Corp.

Provider name: 'QEMU Guest Agent VSS Provider'
   Provider type: Software
   Provider Id: {3629d4ed-ee09-4e0e-9a5c-6d8ba2872aef}
   Version: 0.12.1


[3] これらの形式の相違点については、Uniform Resource Locator Generic Syntax について解説した RFC 文書を参照してください (Collected ABNF for URI)。
[4] URI テンプレートの形式について解説したインターネットドラフトは、http://tools.ietf.org/html/draft-gregorio-uritemplate-03 に掲載されています。

第5章 互換性レベルのバージョン

Red Hat Enterprise Virtualization Manager に接続している各ホストには、VDSM のバージョンの 1 つがインストールされています。VDSM は、Hypervisor またはホスト上で稼働し、仮想マシン、ネットワーク、ストレージをローカルで管理する機能を提供する仮想化インフラストラクチャー内のエージェントです。Red Hat Enterprise Virtualization Manager は、現行または旧バージョンの VDSM を使用して Hypervisor およびホストの制御を行います。
Manager は同じクラスター内のホスト間における仮想マシンの移行を行います。これは、同じクラスター内の全ホストに同じバージョンまたはより新しいバージョンの VDSM がインストールされるまで、Manager が 現行バージョンの VDSM から特定の機能を除外することを意味します。
API はこの概念を、インストールされている VDSM バージョンに対応した各ホストの compatibility level として表示します。version 要素には、互換性レベルを記述する major および minor の属性が含まれます。
管理者が単一のクラスター内の全ホストを一定のレベルにアップグレードする場合には、version レベルは supported_versions 要素の下に表示されます。これは、クラスターの version が、現在そのレベルに更新可能であることを示しています。管理者がデータセンター内のクラスターをすべて一定のレベルに更新すると、そのデータセンターはそのレベルに更新できるようになります。

5.1. 互換性レベルのアップグレード

例5.1 互換性レベルのアップグレード

API は、Red Hat Enterprise Virtualization Manager 3.4 インスタンスの互換性レベルを以下のように報告します。
<host ...>
    ...
    <version major="4" minor="14" build="11" revision="0" full_version="vdsm-4.14.11-5.el6ev"/>
    ...
</host>

<cluster ...>
    ...
    <version major="3" minor="4"/>
    ...
</cluster>

<data_center ...>
    ...
    <version major="3" minor="4"/>
    </supported_versions>
    ...
</data_center>

クラスター内の全ホストが VDSM 3.5 に更新されると、API は以下のように報告します。
<host ...>
    ...
    <version major="4" minor="16" build="7" revision="4" full_version="vdsm-4.16.7.4-1.el6ev"/>
    ...
</host>

<cluster ...>
    ...
    <version major="3" minor="4"/>
    <supported_versions>
        <version major="3" minor="5"/>
    </supported_versions>
    ...
</cluster>

<data_center ...>
    ...
    <version major="3" minor="4"/>
    <supported_versions/>
    ...
</data_center>
これでクラスターを 3.5 に更新できるようになりました。 クラスターが更新されると、API は以下のように報告します。
<cluster ...>
    ...
    <version major="3" minor="5"/>
    <supported_versions/>
    ...
</cluster>

<data_center ...>
    ...
    <version major="3" minor="4"/>
    <supported_versions>
        <version major="3" minor="5"/>
    </supported_versions>
    ...
</data_center>
API ユーザーがデータセンターを 3.5 に更新し、アップグレードが完了すると、API によりこのデータセンターで Red Hat Enterprise Virtualization 3.5 の機能が利用できるようになります。

第6章 機能

capabilities コレクションは、Red Hat Enterprise Virtualization 各種バージョンでサポートしている機能についての情報を提供します。これらの機能には、アクティブな機能や特定のプロパティーに使用可能な列挙値が含まれます。
Red Hat Enterprise Virtualization 3.2 以降の全バージョンの機能に関する完全一覧を取得するには、以下の要求を送信します。
GET /api/capabilities/ HTTP/1.1
Content-Type: application/xml
Accept: application/xml

6.1. バージョン依存の機能

capabilities 要素には、互換性レベルに依存する機能を記述した、任意数の version 要素が含まれます。
version 要素には major および minor のバージョン番号の属性が含まれ、現在のバージョンレベルを示します。
以下の表現では Red Hat Enterprise Virtualization Manager の 3.03.13.23.33.43.53.6 それぞれに固有の capabilities を示しています。
<capabilities>
    <version major="3" minor="0">
        ...
    </version>
    <version major="3" minor="1">
        ...
    </version>
    <version major="3" minor="2">
        ...
    </version>
    <version major="3" minor="3">
        ...
    </version>
    <version major="3" minor="4">
        ...
    </version>
    <version major="3" minor="5">
        ...
    </version>
    <version major="3" minor="6">
        ...
    </version>
    ...
</capabilities>
version には、指定したバージョンに依存する一連の機能が含まれます。

6.2. 現行バージョン

current 要素は、指定された version がサポートされている最新の互換性レベルであるかどうかを表します。値は true または false のいずれかのブール値です。
<capabilities>
    <version major="3" minor="5">
        ...
        <current>true</current>
        ...
    </version>
</capabilities>

6.3. 機能

各バージョンには、互換性のある機能の一覧が含まれています。以下の表には、Red Hat Enterprise Virtualization 3.6 と互換性のある機能の一覧をまとめています。

表6.1 機能のタイプ

機能説明
Transparent Huge Page のメモリーポリシーホストに Tansparent Huge Page の使用可/不可を定義することができます。許容される値は true または false です。
Gluster サポートこの機能は、Gluster ボリュームおよびブリックをストレージとして使用するためのサポートを提供します。
POSIX-FS ストレージタイプこの機能は、POSIX-FS ストレージタイプに対するサポートを提供します。
ポートミラーリング仮想ネットワークインターフェースカードにポートミラーリングの使用可/不可を定義することができます。許容される値は true または false です。
サーバー時刻の表示API で現在の日付と時刻を表示します。
ホストメモリーの表示特定のホストの合計メモリー容量を表示します。
ホストのソケットの表示ホスト CPU のトポロジーを定義することができます。socketsthreads、および cores の 3 つの属性が必要です。これらの属性は、表示するホストのソケット数、スレッド数、ソケットあたりのコア数を定義します。
検索での大文字小文字の区別case-sensitive=true|false URL パラメーターを提供することにより、検索クエリーで大文字小文字を区別するかどうかを指定することができます。
GET 要求の結果の最大件数GET 要求で返される結果の最大件数を指定することができます。
JSON コンテンツタイプPOST および PUT 要求で、相関 ID を設定可能にするヘッダーを定義することができます。
ディスクのアクティブ化/非アクティブ化特定の仮想ディスクに対するアクションとして activate または deactivate を指定することにより、ディスクをアクティブ化/非アクティブ化することができます。
ネットワークインターフェースカードのアクティブ化/非アクティブ化特定のネットワークインターフェースカードに対するアクションとして activate または deactivate を指定することにより、ネットワークインターフェースカードをアクティブ化/非アクティブ化することができます。
スナップショットのリファクタリング仮想マシンのスナップショットのリファクタリングを行うことができます。
指定したストレージドメインからのテンプレートディスクの削除DELETE 要求を使用して、特定のストレージドメインから仮想マシンテンプレートのディスクを削除することができます。
フローティングディスクフローティングディスクとは、どの仮想マシンにもアタッチされていないディスクです。この機能により、フローティングディスクは特定の仮想マシン下ではなく、root コレクションに表示されます。
非同期削除asyncURL パラメーターを指定することにより、DELETE 要求が非同期で実行されるように指定することができます。
セッションベースの認証適切なヘッダーを提供することにより、クライアント/サーバーセッションを維持できるようにし、要求ごとにログインする必要をなくします。
仮想マシンのアプリケーション特定の仮想マシンにインストールされているアプリケーションを一覧表示することができます。この一覧は、その仮想マシンの applications 要素にあります。
VirtIO-SCSI サポートこの機能は、準仮想化 SCSI コントローラーデバイスに対するサポートを提供します。
カスタムリソースコメントデータセンターおよびその他のリソースにカスタムコメントを追加することができます。
ホストの機能のリフレッシュホスト上のデータを同期して、特定のホストが利用できるネットワークインターフェースの一覧をリフレッシュすることができます。
メモリースナップショット仮想マシンのスナップショットの一部としてメモリーの状態を含めることができます。
ウォッチドッグデバイス仮想マシン用のウォッチドッグデバイスを作成することができます。
SSH 認証メソッド管理者ユーザーのパスワードまたは SSH 公開鍵を使用して、SSH を介したホストとの認証を行うことができます。
SPM の強制的な選択ホストを SPM として強制的に選択することができます。
コンソールデバイス仮想マシンへのコンソールデバイスのアタッチを制御することができます。
ストレージドメイン用のストレージサーバー接続特定のストレージドメインとのストレージサーバーの接続を確認することができます。
ストレージサーバー接続のアタッチ/デタッチ特定のストレージドメインにストレージサーバー接続をアタッチ/デタッチすることができます。
QXL 用の単一 PCI単一の PCI ゲストデバイスを介して複数のビデオデバイスを表示することができます。
OVF 設定からの仮想マシン追加提供した OVF 設定から仮想マシンを追加することができます。
仮想ネットワークインターフェースカードのプロファイル特定の仮想ネットワークインターフェースカードのサービスの品質、カスタムプロパティー、ポートミラーリングを定義するプロファイルを設定することができます。
イメージストレージドメイン (テクノロジープレビュー)OpenStack Image Service (Glance) などのイメージストレージドメインからのイメージのインポートとエクスポートを行うことができます。
仮想マシンの完全修飾ドメイン名特定の仮想マシンの完全修飾ドメイン名を取得することができます。
仮想マシンへのディスクスナップショットのアタッチこの機能は、仮想マシンにディスクスナップショットをアタッチするためのサポートを提供します。
Cloud-InitCloud-Init を使用して仮想マシンの初期化を行うことができます。
Gluster ブリック管理migrateDELETE のアクションを使用して、データ移行で Gluster ブリックを削除することができます。migrate アクションおよび stopmigrate アクションでは、データを移行してブリックを再利用することができます。
バックエンドディスクのコピーと移動追加のコンテキストのディスクをコピーおよび移動することができます。
ネットワークラベルラベルを使用してホストにネットワークをプロビジョニングすることができます。
仮想マシンの再起動1 回のアクションで仮想マシンを再起動することができます。
機能の要素およびそれらの属性の完全な一覧は、該当するバージョンのセクションの最上部にあります。
<capabilities>
    <version major="3" minor="4">
        ...
        <features>
            <feature>
            	<name>Transparent-Huge-Pages Memory Policy</name>
            	<transparent_huepages/>
            </feature>
        </features>
        ...
    </version>
</capabilities>

第7章 共通の機能

7.1. 要素のプロパティーを表すアイコン

注記

本ガイドでは、全体を通して、各リソースの要素を表にまとめて説明しています。各表にはプロパティーの列があり、要素のプロパティーをアイコンで示しています。これらのアイコンの意味については、表7.1「要素のプロパティーを表すアイコン」 で説明しています。

表7.1 要素のプロパティーを表すアイコン

プロパティー説明アイコン
作成時に必要これらの要素は、リソースの作成時にクライアント提供のリソース表現に必ず記載する必要がありますが、リソースの更新時には必須ではありません。
更新不可これらの要素の値は、リソースの更新時には変更できません。API ユーザーによって値が変更されていない場合にのみ、更新時にクライアント提供の表現にこれらの要素を記載してください。変更されている場合には API がエラーを報告します。
読み取り専用これらの要素は読み取り専用です。読み取り専用要素の値の作成や変更はできません。

7.2. 表現

7.2.1. 表現

API では、以下の XML ドキュメント構造でリソースの表現を構築します。
<resource id="resource_id" href="/api/collection/resource_id">
    <name>Resource-Name</name>
    <description>A description of the resource</description>
    ...
</resource>
仮想マシンの場合には、表現は以下のようになります。
<vm id="5b9bbce5-0d72-4f56-b931-5d449181ee06"
  href="/api/vms/5b9bbce5-0d72-4f56-b931-5d449181ee06">
    <name>RHEL6-Machine</name>
    <description>Red Hat Enterprise Linux 6 Virtual Machine</description>
    ...
</vm>

7.2.2. リソース表現に共通の属性

リソース表現にはすべて、共通属性セットが含まれます。

表7.2 リソース表現に共通の属性

属性タイプ説明プロパティー
idGUID仮想化インフラストラクチャー内の各リソースには id が含まれ、 グローバル一意識別子 (GUID) として機能します。GUID は、リソース識別の第一手段です。
href文字列絶対パスとして表示したリソースの正規の場所です。

7.2.3. リソース表現に共通の要素

すべてのリソース表現には、共通する要素セットが含まれます。

表7.3 リソース表現に共通の要素

要素タイプ説明プロパティー
name文字列ユーザーによって提供される、人間が判読できるリソース名で、name はそのタイプの全リソースで一意です。
description文字列ユーザーによって提供される、人間が判読できる自由形式のリソースの説明です。 

7.3. コレクション

7.3.1. コレクション

コレクションは、同じタイプのリソースのセットです。API は、最上位コレクションとサブコレクションの両方を提供します。最上位コレクションの例としては、環境内の全仮想化ホストを含む hosts コレクションがあげられます。また、サブコレクションの例としては、ホストリソースにアタッチされた全ネットワークインターフェースカードのリソースを含む host.nics コレクションがあげられます。

7.3.2. コレクション内の全リソースの一覧

エントリーポイントから取得したコレクション URI に対して GET 要求を実行して、コレクション内のリソースの一覧を取得します。
Accept HTTP ヘッダーを追加して、応答形式の MIME タイプを定義します。
GET /api/[collection] HTTP/1.1
Accept: [MIME type]

7.3.3. 拡張リソースのサブコレクションの一覧

Accept ヘッダーに detail パラメーターを記載すると、API はコレクションの表現を拡張してサブコレクションを追加します。
GET /api/collection HTTP/1.1
Accept: application/xml; detail=subcollection
複数のサブコレクションを追加するには 2 つの方法があります。第 1 の方法では、以下に示したように、複数の detail パラメーターを区切って記述します。
GET /api/collection HTTP/1.1
Accept: application/xml; detail=subcollection1; detail=subcollection2
第 2 の方法では、以下に示したように、単一の detail パラメーターで、サブコレクションを + 演算子で区切ります。
GET /api/collection HTTP/1.1
Accept: application/xml; detail=subcollection1+subcollection2+subcollection3
API は、以下のメインコレクションで、拡張サブコレクションをサポートしています。

表7.4 拡張サブコレクションを使用するコレクション

コレクション拡張サブコレクションのサポート
hostsstatistics
vmsstatisticsnicsdisks

例7.1 vms コレクション内の拡張された statistics/nics/disks サブコレクションの要求

GET /api/vms HTTP/1.1
Accept: application/xml; detail=statistics+nics+disks

7.3.4. クエリーを使用したコレクションの検索

"collection/search" リンクに対する GET 要求は、そのコレクションの検索クエリーとなります。API は、検索クエリーの制約を満たすコレクション内のリソースのみを返します。
GET /api/collection?search={query} HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<collection>
    <resource id="resource_id" href="/api/collection/resource_id">
        ...
    </resource>
    ...
</collection>

7.3.5. 検索結果の最大表示件数のパラメーター

結果一覧のサイズを制限するには、max URL パラメーターを使用します。Red Hat Enterprise Virtualization 3.4 より前のバージョンでは、結果のデフォルトサイズは SearchResultsLimit パラメーターで制限されていました。Red Hat Enterprise Virtualization 3.4 以降のバージョンでは、SearchResultsLimit パラメーターは REST API に効果がないため、max パラメーターを指定せずに API 検索クエリーを実行すると、すべての値が返されてしまいます。API 検索クエリーによる UI のパフォーマンス低下を防ぐためには、max パラメーターを指定することを推奨します。
GET /api/collection;max=1 HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<collection>
    <resource id="resource_id" href="/api/collection/resource_id">
        <name>Resource-Name</name>
        <description>A description of the resource</description>
        ...
    </resource>
</collection>

7.3.6. 大文字と小文字の区別

デフォルトでは、検索クエリーはすべて大文字と小文字が区別されます。大文字/小文字の区別を切り替えるためのブール値オプションは、URL 構文で提供されます。

例7.2 大文字/小文字を区別しない検索クエリー

GET /api/collection;case-sensitive=false?search={query} HTTP/1.1
Accept: application/xml

7.3.7. クエリーの構文

API は、URI テンプレートを使用して GET 要求による検索 query を実行します。
GET /api/collection?search={query} HTTP/1.1
Accept: application/xml
query テンプレートの値は、API が collection に送る検索クエリーを参照します。この query は、Red Hat Enterprise Virtualization 検索クエリー言語と同じ形式を使用します。
(criteria) [sortby (element) asc|desc]
sortby 句はオプションです。結果をソートする場合にのみ必要となります。

表7.5 検索クエリーの例

コレクション条件結果
hostsvms.status=upup 状態の仮想マシンを実行中の全ホストの一覧を表示します。
vmsdomain=qa.company.com指定したドメインで稼働中の全仮想マシンの一覧を表示します。
vmsusers.name=maryユーザー名が mary のユーザーに属する全仮想マシンの一覧を表示します。
eventsseverity>normal sortby time重大度が normal を超えるすべての events の一覧を表示し、time 要素値でソートします。
eventsseverity>normal sortby time desc重大度が normal を超えるすべての events の一覧を表示し、time 要素値の降順にソートします。
API は、query テンプレートを URL エンコードして、演算子や空白など予約文字を変換する必要があります。

例7.3 URL エンコードされた検索クエリー

GET /api/vms?search=name%3Dvm1 HTTP/1.1
Accept: application/xml

7.3.8. ワイルドカード

検索クエリーで、値の一部の代わりに、アスタリスクをワイルドカードとして使用します。

例7.4 ワイルドカードを使用した name=vm* の検索クエリー

GET /api/vms?search=name%3Dvm* HTTP/1.1
Accept: application/xml
このクエリーは、vm1vm2vmavm-webserver など vm で始まる仮想マシン名をすべて表示します。

例7.5 ワイルドカードを使用した name=v*1 の検索クエリー

GET /api/vms?search=name%3Dv*1 HTTP/1.1
Accept: application/xml
このクエリーは、vm1vr1virtualmachine1 など v で始まり 1 で終わる仮想マシン名をすべて表示します。

7.3.9. ページネーション

Red Hat Enterprise Virtualization 環境の中には、リソースのコレクションが大量に含まれている場合がありますが、API は 1 つのコレクションに対する 1 回の検索クエリーに設定されているデフォルト数のリソースのみを表示します。デフォルト数以上のリソースを表示するには、page コマンドを検索クエリーに追加すると、API はコレクションを複数のページに分割します。

例7.6 リソースのページネーション

以下の例では、1 つのコレクション内の複数のリソースをページネーションします。URL エンコードされた要求は次のようになります。
GET /api/collection?search=page%201 HTTP/1.1
Accept: application/xml
次の結果ページを表示させる場合は page 値を増やします。
GET /api/collection?search=page%202 HTTP/1.1
Accept: application/xml
以下の例のように、page コマンドは、検索クエリー内で他のコマンドと併用することができます。
GET /api/collection?search=sortby%20element%20asc%20page%202 HTTP/1.1
Accept: application/xml
このクエリーにより、コレクション一覧内の第 2 ページが選択した要素の順に表示されます。

重要

REST API はステートレスです。要求はすべて 1 つずつ独立しているため、別の要求との間で状態を保持することはできません。そのため、要求と要求の間でステータスが変更されると、ページの結果に整合性がなくなります。
たとえば、仮想マシンの一覧から特定のページを要求し、次のページを要求する前にステータスが変更された場合は、出力される結果でエントリーが足りないか、重複エントリーが含まれている可能性があります。

7.3.10. コレクション内のリソース作成

新規リソースの表現を含むコレクション URI に対して POST 要求を実行して、新規リソースを作成します。
POST 要求には、Content-Type ヘッダーが必要です。このヘッダーは、要求の一部として、本文コンテンツ内の表現の MIME タイプを API に通知します。
Accept HTTP ヘッダーを追加して、応答形式の MIME タイプを定義します。
各リソースタイプには、それぞれ固有の必須プロパティーがあります。これらのプロパティーは、新規リソース作成時にクライアントから提供されます。詳細については、各リソースタイプの説明を参照してください。
必須プロパティーが存在しない場合には、作成が失敗し、表現に不足している要素が示されます。
POST /api/[collection] HTTP/1.1
Accept: [MIME type]
Content-Type: [MIME type]

[body]

7.3.11. 非同期要求

Expect: 201-created ヘッダーでユーザーによって要求が無効化されない限り、API は非同期の POST 要求を行います。
たとえば、仮想マシン、ディスク、スナップショット、テンプレートなど特定のリソースは非同期に作成されます。非同期のリソース作成の要求を実行すると 202 Accepted のステータスになります。202 Accepted のリソースの初期ドキュメント構造には creation_status 要素と作成ステータス更新用リンクも含まれます。以下が例となります。
POST /api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<resource>
    <name>Resource-Name</name>
</resource>

HTTP/1.1 202 Accepted
Content-Type: application/xml

<resource id="resource_id" href="/api/collection/resource_id">
    <name>Resource-Name</name>
    <creation_status>
        <state>pending</state>
    </creation status>
    <link rel="creation_status" 
      href="/api/collection/resource_id/creation_status/creation_status_id"/>
      ...
</resource>
creation_status リンクに対して GET 要求を実行すると、作成ステータスの更新が提供されます。
GET /api/collection/resource_id/creation_status/creation_status_id HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<creation id="creation_status_id"
  href="/api/collection/resource_id/creation_status/creation_status_id">
    <status>
        <state>complete</state>
    </status>
</creation>
非同期リソースの作成をオーバーライドするには Expect: 201-created ヘッダーが必要です。
POST /api/collection HTTP/1.1
Accept: application/xml
Content-Type: application/xml
Expect: 201-created

<resource>
    <name>Resource-Name</name>
</resource>

7.4. リソース

7.4.1. リソース

リソースは、RESTful Web サービスのデータソースです。各リソースタイプには、リソース表現 (通常 XML または JSON) を形成するために REST API が抽象化する共通のパラメーターセットが含まれています。ユーザーはリソース表現を表示して、パラメーターを編集し、API 内にあるリソースの URL にその表現を送り返して、リソースを変更することができます。またユーザーは、REST を介して個別のリソースを削除することもできます。
RESTful Web サービスは、リソースをコレクションにグループ化する作業も行います。ユーザーはコレクション内の全リソースの表現を表示することができます。またユーザーは、リソース表現を特定のコレクションに送信して、そのコレクション内に新たなリソースが作成することもできます。

7.4.2. リソースの取得

コレクション一覧から取得した URI に対して GET 要求を実行し、リソースのステータスを取得します。
Accept HTTP ヘッダーを追加して、応答形式の MIME タイプを定義します。
GET /api/[collection]/[resource_id] HTTP/1.1
Accept: [MIME type]
リソースからの追加情報は、All-Content: true ヘッダーを使用して取得することができます。RESTful Service Description Language (RSDL) により、どのリンクがこのヘッダーをサポートするかが記述されます。
GET /api/[collection]/[resource_id] HTTP/1.1
Accept: [MIME type]
All-Content: true

7.4.3. リソースの更新

前回のリソース URI GET 要求からの更新詳細を含む PUT 要求を実行して、リソースのプロパティーを変更します。変更可能なプロパティーに関する詳細は、各リソースタイプの説明を参照してください。
PUT 要求には、Content-Type ヘッダーが必要です。このヘッダーは、要求の一部として、本文コンテンツ内の表現の MIME タイプを API に通知します。
Accept HTTP ヘッダーを追加して、応答形式の MIME タイプを定義します。
PUT /api/collection/resource_id HTTP/1.1
Accept: [MIME type]
Content-Type: [MIME type]

[body]
これには、API ユーザーが変更を試みた、不変のリソースプロパティーは含まれません。完全に不変のリソースプロパティーの変更を試みると、API は応答本文内のエラーメッセージ表現で競合を報告します。
表現から省略されたプロパティーは無視されるため変更されません。

7.4.4. リソースの削除

URI に対して DELETE 要求を実行して、リソースを削除します。
Accept HTTP ヘッダーを追加して、応答形式の MIME タイプを定義します。
DELETE /api/[collection]/[resource_id] HTTP/1.1
Accept: [MIME type]
追加のプロパティーを指定するために、DELETE 要求内にオプションの本文コンテンツが必要な場合があります。オプションの本文コンテンツ付き DELETE 要求には、本文コンテンツ内の表現の MIME タイプを API に通知する Content-Type ヘッダーが必要です。DELETE 要求に本文コンテンツがない場合は Content-Type ヘッダーは省略します。

7.4.5. サブコレクションのリレーションシップ

サブコレクションのリレーションシップは、リソースとサブコレクション間の階層リンクを定義します。サブコレクションは、親リソースに関連して存在したり、意味を持ったりします。たとえば、仮想マシンに複数のネットワークインターフェースがある場合は、API は仮想マシンリソースとネットワークインターフェースのサブコレクション間のリレーションシップをマッピングすることになります。
サブコレクションは、次のリレーションシップタイプのモデリングに使用します。
  • 1 つの親リソースに複数の子リソースが含まれるようにしたり、1 つの子リソースが複数の親リソースに含まれるようにしたりすることが可能です。たとえば、仮想マシンには、複数のディスクを設定することができ、一部のディスクは複数の仮想マシンで共有されます。
  • マッピングされるリソースは、親リソースに依存します。親リソースなしでは依存するリソースは存在できません (例: 仮想マシンとスナップショット間のリンク)。
  • マッピングされるリソースは、親リソースからは独立して存在しますが、データはそのリレーションシップで関連付けられています (例: クラスターとネットワーク間のリンク)。
API は、link rel= 属性を使用して、リソースとサブコレクションとのリレーションシップを定義します。
GET /api/collection/resource_id HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<resource id="resource_id" href="/api/collection/resource_id">
    ...
    <link rel="subcollection"
      href="/api/collection/resource_id/subcollection"/>
    ...
</resource>
次に、サブコレクションに対してクエリーを実行します。
GET /api/collection/resource_id/subcollection HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<subcollection>
    <subresource id="subresource_id"
      href="/api/collection/resource_id/subcollection/subresource_id">
        ...
    </subresource>
    ...
</subcollection>

7.4.6. XML 要素のリレーションシップ

XML 要素のリンクは、リソース間のリレーションシップを表現するためのサブコレクションの代わりとして機能します。XML 要素のリンクは、単にリンク先の要素をポイントする「href」属性が記述した要素です。
XML 要素のリンクは、依存関係やリレーションシップに関連付けられたデータのないリソース間の単純な 1:N マッピングのモデリングに使用されます。(例: ホストとクラスター間のリレーションシップ)
このようなリレーションシップには、以下のような例があります。
  • サブコレクション内のリソースから親リソースへのバックリンク
  • 任意のリレーションシップがあるリソース間のリンク

例7.7 XML 要素を使用した、サブコレクションリソースからリソースへのバックリンク

GET /api/collection/resource_id/subcollection/subresource_id HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/xml

<subcollection>
    <subresource id="subresource_id"
      href="/api/collection/resource_id/subcollection/subresource_id">
        <resource id="resource_id" href="/api/collection/resource_id"/>
        ...
    </subresource>
</subcollection>

7.4.7. アクション

大半のリソースには、標準の HTTP メソッドでは実現できない関数を提供するアクションリンクの一覧が含まれています。
<resource>
    ...
    <actions>
        <link rel="start" href="/api/collection/resource_id/start"/>
        <link rel="stop" href="/api/collection/resource_id/stop"/>
        ...
    </actions>
    ...
</resource>
API は、提供された URI に対して POST 要求を実行することによってアクションを呼び出します。POST の本文には、共通およびタスク固有のパラメーターをカプセル化した action 表現が必要です。

表7.6 共通のアクションパラメーター

要素説明
asyncサーバーが 202 Accepted で即時に応答し、完了確認のポーリングのための href リンクがアクション表現に記載されている場合は true に指定します。
grace_period猶予期間 (ミリ秒単位)。アクション開始前に満了する必要があります。
個々のアクションおよびそれらのパラメーターについては、各リソースタイプの説明を参照してください。 特定のアクションには必須のパラメーターがあり、それらが指定されていない場合には fault 応答で示されます。
POST 要求には本文コンテンツに XML 表現が必要なため、アクションにも Content-Type: application/xml ヘッダーが必要です。
アクションが非同期で開始されると、202 Accepted の即時応答によりタスクのステータスをモニタリングするためのリンクが提供されます。
POST /api/collection/resource_id/action HTTP/1.1
Content-Type: application/xml
Accept: application/xml

<action>
    <async>true</async>
</action>

HTTP/1.1 202 Accepted
Content-Type: application/xml

<action id="action_id"
  href="/api/collection/resource_id/action/action_id">
    <async>true</async>
    ...
</action>
この後にアクション URL に対して GET を実行すると、非同期タスクのステータス表示が提供されます。

表7.7 アクションのステータス

ステータス説明
pendingタスクがまだ開始されていない状態です。
in_progressタスクを実行中
completeタスクが正常に完了
failedタスクが失敗 (返される action 表現にはエラーの詳細を記述する fault が含まれる)
タスクが完了すると、そのアクションのデータは一定期間維持されます。この期間が満了した後に GET を実行すると、301 Moved Permanently となり、ターゲットリソースに戻るようリダイレクトされます。
GET /api/collection/resource_id/action/action_id HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<action id="action_id"
  href="/api/collection/resource_id/action/action_id">
    <status>
        <state>pending</state>
    </status>
    <link rel="parent" /api/collection/resource_id"/>
    <link rel="replay" href="/api/collection/resource_id/action"/>
</action>
アクション表現には rel 属性によって識別される複数のリンクも記載されます。

表7.8 アクションのリレーションシップ

タイプ説明
parentこのアクションのリソースに戻るリンク
replay元のアクション URI に戻るリンク。この URI に POST を実行すると、アクションが再度開始されます。

7.4.8. パーミッション

各リソースには permissions サブコレクションが含まれます。各 permissions には user、割り当てられた role、指定リソースなどが含まれます。 以下が例となります。
GET /api/collection/resource_id/permissions HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<permissions>
    <permission id="permission-id"
      href="/api/collection/resource_id/permissions/permission_id">
        <role id="role_id" href="/api/roles/role_id"/>
        <user id="user_id" href="/api/users/user_id"/>
        <resource id="resource_id" href="/api/collection/resource_id"/>
    </permission>
    ...
</permissions>
API ユーザーがリソースの permissions サブコレクションに対して、permission 表現および Content-Type: application/xml ヘッダーを記載した POST を送信すると、リソースは新規パーミッションを取得します。以下の例に示したように、各新規パーミッションには roleuser が必要です。
POST /api/collection/resource_id/permissions HTTP/1.1
Content-Type: application/xml
Accept: application/xml

<permission>
    <role id="role_id"/>
    <user id="user_id"/>
</permission>

HTTP/1.1 201 Created
Content-Type: application/xml

<permission id="permission_id"
  href="/api/resources/resource_id/permissions/permission_id">
    <role id="role_id" href="/api/roles/role_id"/>
    <user id="user_id" href="/api/users/user_id"/>
    <resource id="resource_id" href="/api/collection/resource_id"/>
</permission>

7.4.9. エラーの処理

エラーによっては、標準の HTTP ステータスコード以外に、詳細な説明を必要とするものがあります。たとえば API は、リソース状態の更新またはアクションの失敗を、応答エンティティー本文に fault 表現を指定して報告します。fault 表現には reasondetail の文字列が含まれます。クライアントは、fault または 応答ステータスコードに応じた、想定されるリソース表現を抽出することによって、失敗した要求に対応する必要があります。このような場合の対処方法は、各リソースの説明で明確に記載しています。
PUT /api/collection/resource_id HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<resource>
    <id>id-update-test</id>
</resource>

HTTP/1.1 409 Conflict
Content-Type: application/xml

<fault>
    <reason>Broken immutability constraint</reason>
    <detail>Attempt to set immutable field: id</detail>
</fault>

第8章 バックアップ/リストア API

バックアップ/リストア API は、全体またはファイルレベルでの仮想マシンのバックアップと復元を可能にする機能のコレクションです。この API は、ライブスナップショットや REST API などの Red Hat Enterprise Virtualization の複数のコンポーネントを組み合わせて、独立系のソフトウェアプロバイダーの提供するバックアップソフトウェアが実装された仮想マシンにアタッチできる一時ボリュームを作成/操作します。
サポート対象のサードパーティーバックアップベンダーについては、Red Hat Marketplace で Red Hat Enterprise Virtualization Ecosystem をご確認ください。

8.1. 仮想マシンのバックアップ

バックアップ/リストア API を使用して仮想マシンをバックアップします。以下の手順は、バックアップ用の仮想マシンと、バックアップを管理するソフトウェアのインストール先となる仮想マシンとの合計 2 台が用意されていることを前提とします。

手順8.1 仮想マシンのバックアップ

  1. REST API を使用して、バックアップする仮想マシンのスナップショットを作成します。
    POST /api/vms/11111111-1111-1111-1111-111111111111/snapshots/ HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
    
    <snapshot>
        <description>BACKUP</description>
    </snapshot>

    注記

    仮想マシンのスナップショットを作成すると、スナップショット作成時点の仮想マシンの設定データのコピーは、そのスナップショット下の initialization 内の configuration 属性の data 属性に保管されます。

    重要

    共有可能とマークされたディスクまたは直接 LUN ディスクをベースとするディスクのスナップショットは作成できません。
  2. スナップショット下の data 属性から仮想マシンの設定データを取得します。
    GET /api/vms/11111111-1111-1111-1111-111111111111/snapshots/11111111-1111-1111-1111-111111111111 HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
  3. スナップショットのディスク ID とスナップショット ID を特定します。
    GET /api/vms/11111111-1111-1111-1111-111111111111/snapshots/11111111-1111-1111-1111-111111111111/disks HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
  4. バックアップ用仮想マシンにスナップショットをアタッチしてディスクをアクティブ化します。
    POST /api/vms/22222222-2222-2222-2222-222222222222/disks/ HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
    
    <disk id="11111111-1111-1111-1111-111111111111">
        <snapshot id="11111111-1111-1111-1111-111111111111"/>
        <active>true</active>
    </disk>
  5. バックアップ用仮想マシンでバックアップソフトウェアを使用して、スナップショット上のデータをバックアップします。
  6. バックアップ用仮想マシンからスナップショットのディスクをデタッチします。
    DELETE /api/vms/22222222-2222-2222-2222-222222222222/disks/11111111-1111-1111-1111-111111111111 HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
    
    <action>
        <detach>true</detach>
    </action>
  7. オプションとして、スナップショットを削除します。
    DELETE /api/vms/11111111-1111-1111-1111-111111111111/snapshots/11111111-1111-1111-1111-111111111111 HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
別の仮想マシンにインストールしたバックアップソフトウェアを使用して、一定時点の仮想マシンがバックアップされました。

8.2. 仮想マシンの復元

バックアップ/リストア API を使用してバックアップした仮想マシンを復元します。以下の手順は、以前のバックアップの管理に使用するソフトウェアがインストール済みの仮想マシン 1 台が用意されていることを前提とします。

手順8.2 仮想マシンの復元

  1. バックアップ用仮想マシンにディスクをアタッチします。
    POST /api/vms/22222222-2222-2222-2222-222222222222/disks/ HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
    
    <disk id="11111111-1111-1111-1111-111111111111">
    </disk>
  2. バックアップソフトウェアを使用して、ディスクにバックアップを復元します。
  3. バックアップ用仮想マシンからディスクをデタッチします。
    DELETE /api/vms/22222222-2222-2222-2222-222222222222/disks/11111111-1111-1111-1111-111111111111 HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
    
    <action>
        <detach>true</detach>
    </action>
  4. 復元する仮想マシンの設定データを使用して、新規仮想マシンを作成します。
    POST /api/vms/ HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
    
    <vm>
        <cluster>
            <name>cluster_name</name>
        </cluster>
        <name>NAME</name>
        ...
    </vm>
  5. 新規仮想マシンにディスクをアタッチします。
    POST /api/vms/33333333-3333-3333-3333-333333333333/disks/ HTTP/1.1
    Accept: application/xml
    Content-type: application/xml
    
    <disk id="11111111-1111-1111-1111-111111111111">
    </disk>
バックアップ/リストア API を使用して作成したバックアップで、仮想マシンを復元しました。

第9章 データセンター

9.1. データセンターの要素

datacenters コレクションは、Red Hat Enterprise Virtualization 環境内のデータセンターに関する情報を提供します。API ユーザーは、エントリーポイント URI から取得した rel="datacenters" リンクでこの情報にアクセスします。
以下の表には、データセンターリソースの表現に含まれる特定の要素をまとめています。

表9.1 データセンターの要素

要素タイプ説明プロパティー
name文字列プレーンテキスト形式の人間が判読できるデータセンター名。name は全クラスターリソースで一意です。
description文字列プレーンテキスト形式の人間が判読できるプロバイダーの説明 
link rel="storagedomains"リレーションシップそのデータセンターにアタッチされているストレージドメインのサブコレクションへのリンク 
link rel="clusters"リレーションシップそのデータセンターにアタッチされているクラスターのサブコレクションへのリンク 
link rel="networks"リレーションシップそのデータセンターで利用可能なネットワークのサブコレクションへのリンク 
link rel="permissions"リレーションシップデータセンターパーミッションのサブコレクションへのリンク 
link rel="quotas"リレーションシップそのデータセンターに関連付けられているクォータのサブコレクションへのリンク 
localブール値: true または falseデータセンターがローカルのデータセンター (例: all-in-one インスタンスで作成されたもの) かどうかを指定します。
storage_format列挙型データセンターのストレージ形式のバージョンの記述。列挙値の一覧は capabilities に記載されています。
version major= minor=複合型データセンターの互換性レベル
supported_versions複合型version major= minor= など、データセンターで利用可能なバージョンレベルの一覧
status以下参照データセンターのステータス
status には、uninitializedupmaintenancenot_operationalproblematiccontend の列挙値のいずか 1 つが記載されます。これらのステータスは capabilities の下の data_center_states に一覧表示されています。

9.2. データセンターの XML 表現

例9.1 データセンターの XML 表現

<data_center href="/api/datacenters/00000000-0000-0000-0000-000000000000"
    id="00000000-0000-0000-0000-000000000000">
  <name>Default</name>
  <description>The default Data Center</description>
  <link href="/api/datacenters/00000000-0000-0000-0000-000000000000/storagedomains" rel="storagedomains"/>
  <link href="/api/datacenters/00000000-0000-0000-0000-000000000000/clusters" rel="clusters"/>
  <link href="/api/datacenters/00000000-0000-0000-0000-000000000000/networks" rel="networks"/>
  <link href="/api/datacenters/00000000-0000-0000-0000-000000000000/permissions" rel="permissions"/>
  <link href="/api/datacenters/00000000-0000-0000-0000-000000000000/quotas" rel="quotas"/>
  <local>false</local>
  <storage_format>v3</storage_format>
  <version major="3" minor="4"/>
  <supported_versions>
    <version major="3" minor="4"/>
  </supported_versions>
  <status>
    <state>up</state>
  </status>
</data_center>

9.3. データセンターの JSON 表現

例9.2 データセンターの JSON 表現

{
  "data_center" : [ {
    "local" : "false",
    "storage_format" : "v3",
    "version" : {
      "major" : "3",
      "minor" : "5"
    },
    "supported_versions" : {
      "version" : [ {
        "major" : "3",
        "minor" : "5"
      } ]
    },
    "status" : {
      "state" : "up"
    },
    "name" : "Default",
    "description" : "The default Data Center",
    "href" : "/api/datacenters/00000002-0002-0002-0002-000000000255",
    "id" : "00000002-0002-0002-0002-000000000255",
    "link" : [ {
      "href" : "/api/datacenters/00000002-0002-0002-0002-000000000255/storagedomains",
      "rel" : "storagedomains"
    }, {
      "href" : "/api/datacenters/00000002-0002-0002-0002-000000000255/clusters",
      "rel" : "clusters"
    }, {
      "href" : "/api/datacenters/00000002-0002-0002-0002-000000000255/networks",
      "rel" : "networks"
    }, {
      "href" : "/api/datacenters/00000002-0002-0002-0002-000000000255/permissions",
      "rel" : "permissions"
    }, {
      "href" : "/api/datacenters/00000002-0002-0002-0002-000000000255/quotas",
      "rel" : "quotas"
    }, {
      "href" : "/api/datacenters/00000002-0002-0002-0002-000000000255/iscsibonds",
      "rel" : "iscsibonds"
    }, {
      "href" : "/api/datacenters/00000002-0002-0002-0002-000000000255/qoss",
      "rel" : "qoss"
    } ]
  } ]
}

9.4. メソッド

9.4.1. 新しいデータセンターの作成

新規データセンターの作成には namelocal の要素が必要です。

例9.3 データセンターの作成

POST /api/datacenters HTTP/1.1
Accept: application/xml
Content-type: application/xml

<data_center>
    <name>NewDatacenter</name>
    <local>false</local>
</data_center>

9.4.2. データセンターの更新

namedescriptionstorage_typeversionstorage_format の各要素は、作成後に更新が可能です。

例9.4 データセンターの更新

PUT /api/datacenters/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<data_center>
    <name>UpdatedName</name>
    <description>An updated description for the data center</description>
</data_center>

9.4.3. データセンターの削除

データセンターを削除するには、DELETE 要求を実行する必要があります。

例9.5 データセンターの削除

DELETE /api/datacenters/00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content

9.5. サブコレクション

9.5.1. ストレージドメインのサブコレクション

9.5.1.1. ストレージドメインのサブコレクション

各データセンターには、アタッチされたストレージドメイン用のサブコレクションが含まれます。API ユーザーは、標準の REST メソッドでこのサブコレクションとの対話を行ってください。
アタッチされたストレージドメインには、最上位のストレージドメインと同様の表現が記載されています。ただし、データセンター固有の status およびアクションセットが記載されている点が異なります。status 要素の状態は、capabilities の下の storage_domain_states に記載されています。

重要

API は、本セクションに記載した時点では試験段階にあり、今後変更される可能性があるため、後方互換性に関する記載内容は適用されません。

9.5.1.2. ストレージドメインのアタッチとデタッチ

データセンターは、ストレージドメインを少なくとも 1 つアタッチしなければ使用できる状態になりません。ストレージドメインをアタッチするには、API ユーザーが データセンターストレージドメインのサブコレクションを POST してください。
ストレージドメインをアタッチする際には、id または name を指定する必要があります。ストレージドメインをデータセンターにアタッチする例は以下のとおりです。

例9.6 データセンターへのストレージドメインのアタッチ

POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>

HTTP/1.1 201 Created
Location: /datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed
Content-Type: application/xml

<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
  href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/
  fabe0451-701f-4235-8f7e-e20e458819ed">
    <name>images0</name>
    <type>data</type>
    <status>
        <state>inactive</state>
    </status>
    <master>true</master>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/images/0</path>
    </storage>
    <data_center id="d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"
      href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"/>
    <actions>
        <link rel="activate"
          href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/
          storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/activate"/>
        <link rel="deactivate"
          href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/
          storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/deactivate"/>
    </actions>
</storage_domain>
データセンターからストレージドメインをデタッチするには、DELETE 要求を使用します。この要求を非同期とするには、オプションの async 要素を記載してください。

例9.7 データセンターからのストレージドメインのデタッチ

DELETE /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
  <async>true</async>
</action>

9.5.1.3. アクション

9.5.1.3.1. ストレージドメインをアクティブ化するアクション
アタッチされているストレージドメインを使用するには、データセンター上であらかじめアクティブ化しておく必要があります。アクティブ化のアクションには、アクション固有のパラメーターを取る必要はありません。

例9.8 データセンター上でストレージドメインをアクティブ化するためのアクション

POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/activate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>
9.5.1.3.2. ストレージドメインを非アクティブ化するアクション
アタッチされているストレージドメインを削除する前には、データセンター上で非アクティブ化してください。非アクティブ化のアクションは、アクション固有のパラメーターは取りません。

例9.9 データセンター上でストレージドメインを非アクティブ化するためのアクション

POST /api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/deactivate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

9.5.2. ネットワークのサブコレクション

9.5.2.1. ネットワークのサブコレクション

データセンターに関連付けられるネットワークは、networks サブコレクションで表現します。データセンターの network サブコレクションには以下の要素が含まれています。

表9.2 ネットワークの要素

要素タイプ説明
name文字列プレーンテキスト形式の人間が判読できるネットワーク名
description文字列プレーンテキスト形式の人間が判読できるネットワークの説明
rel="permissions"リレーションシップネットワークの permissions サブコレクションへのリンク
rel="vnicprofiles"リレーションシップネットワークの vnicprofiles サブコレクションへのリンク
rel="labels"リレーションシップネットワークの labels サブコレクションへのリンク
data_center id=リレーションシップネットワークが属するデータセンターへの参照
stpブール値: true または falseネットワークに対してスパニングツリープロトコルを有効にするかどうかを指定します。
mtu整数ネットワークの最大転送単位を指定します。
usages複合ネットワークの usage 要素セットを定義します。ユーザーはこのレベルでネットワークを vm および display ネットワークとして定義できます。
REST API では、標準の REST メソッドで networks サブコレクションを操作することができます。たとえば POST メソッドを使用して、ネットワークの idname を更新することができます。

例9.10 ネットワークリソースとデータセンターの関連付け

POST /api/datacenters/00000000-0000-0000-0000-000000000000/networks HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<network id="da05ac09-00be-45a1-b0b5-4a6a2438665f">
    <name>ovirtmgmt</name>
</network>

HTTP/1.1 201 Created
Location: http://{host}/clusters/00000000-0000-0000-0000-000000000000/networks/00000000-0000-0000-0000-000000000000
Content-Type: application/xml

<network href="/api/networks/00000000-0000-0000-0000-000000000000"
    id="00000000-0000-0000-0000-000000000000">
  <name>Network_001</name>
  <link href="/api/networks/00000000-0000-0000-0000-000000000000/permissions"
    rel="permissions"/>
  <link href="/api/networks/00000000-0000-0000-0000-000000000000/vnicprofiles"
    rel="vnicprofiles"/>
  <link href="/api/networks/00000000-0000-0000-0000-000000000000/labels"
    rel="labels"/>
  <data_center href="/api/datacenters/00000000-0000-0000-0000-000000000000"
    id="00000000-0000-0000-0000-000000000000"/>
  <stp>false</stp>
  <mtu>0</mtu>
  <usages>
    <usage>vm</usage>
  </usages>
</network>
PUT 要求でリソースを更新します。ネットワークの最大伝送単位は、mtu 要素の整数値を指定する PUT 要求を使用して設定されます。

例9.11 ネットワークの最大伝送単位の設定

PUT /api/datacenters/00000000-0000-0000-0000-000000000000/networks/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<network>
    <mtu>1500</mtu>
</network>
関連付けは、コレクション内の該当する要素に対する DELETE 要求で削除します。

例9.12 データセンターからのネットワークの関連付けの削除

DELETE /api/datacenters/00000000-0000-0000-0000-000000000000/networks/00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content

9.5.3. クォータのサブコレクション

9.5.3.1. クォータのサブコレクション

クォータのサブコレクションには、Red Hat Enterprise Virtualization Manager がリソースに対して課す制限が記載されています。API ユーザーは、GET メソッドを使用して、このサブコレクションとリソースを表示します。

例9.13 クォータの XML 表現

<quota href="/api/datacenters/56087282-d7a6-11e1-af44-001a4a400e0c
  /quotas/e13ff85a-b2ba-4f7b-8010-e0d057c03dfe" 
  id="e13ff85a-b2ba-4f7b-8010-e0d057c03dfe">
    <name>MyQuota</name>
    <description>A quota for my Red Hat Enterprise
      Virtualization environment</description>
    <data_center href= "/api/datacenters/56087282-d7a6-11e1-af44-001a4a400e0c" 
    id="56087282-d7a6-11e1-af44-001a4a400e0c"/>
</quota>
新規クォータの作成には name および description 要素が必要です。

例9.14 クォータの作成

POST /api/datacenters/56087282-d7a6-11e1-af44-001a4a400e0c/quotas HTTP/1.1
Accept: application/xml
Content-type: application/xml

<quota>
    <name>VMQuota</name>
    <description>My new quota for virtual machines</description>
</quota>
クォータを削除する場合は DELETE 要求が必要になります。

例9.15 クォータの削除

DELETE /api/datacenters/01a45ff0-915a-11e0-8b87-5254004ac988/quotas/e13ff85a-b2ba-4f7b-8010-e0d057c03dfe HTTP/1.1

HTTP/1.1 204 No Content

9.6. アクション

9.6.1. データセンターの強制削除のアクション

マスターストレージドメインへの接続が切断されたり、ストレージドメインを削除する際にホストが不足しているなど、ストレージドメインに解決不可能な問題が発生した場合には、データセンターを強制削除してください。このような状況に対応するために、API には force アクションが実装されています。
このアクションにより、API が Red Hat Enterprise Virtualization 環境から選択したデータセンターを削除する前に、そのデータセンターに関連付けられたデータベースエントリーが削除されます。これは、関連付けられているストレージドメインに関わらず、API がデータセンターを削除することを意味します。
このアクションには DELETE メソッドが必要です。この要求の本文には、action 表現を記載し、force パラメーターを true に設定します。またこの要求には、XML 表現を処理するための追加の Content-type: application/xml ヘッダーも本文に記載する必要があります。

例9.16 データセンター上での強制削除アクション

DELETE /api/datacenters/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
  <force>true</force>
</action>
このアクションは、以下の操作を実行します。
  • データセンターに関連付けられている data ストレージドメインのデータベース情報をすべて削除します。
  • データセンターに関連付けられている data ストレージドメイン上にある仮想マシンやテンプレートなどのリソースのデータベース情報をすべて削除します。
  • データセンターから iso ストレージドメインおよび export ストレージドメインをデタッチします。
  • データセンターのデータベース情報を削除します。
このアクションは、データセンターを空にしてからでないと削除できないという要件よりも優先されます。

重要

このアクションは、対象となるデータセンターに関連付けられたリソースのデータベースエントリーのみを削除します。データセンターに関連付けられた data ストレージドメインは、再度使用する前に手動でフォーマットする必要があります。また iso ドメインおよび export ドメインのメタデータは、他のデータセンターで使用する前に手動でクリーニングしておく必要があります。

第10章 クラスター

10.1. クラスターの要素

clusters コレクションは、Red Hat Enterprise Virtualization 環境内のクラスターに関する情報を提供します。API ユーザーは、エントリーポイント URI から取得した rel="clusters" リンクでこの情報にアクセスします。
以下の表には、クラスタリソースの表現に含まれる特定の要素をまとめています。

表10.1 クラスターの要素

要素タイプ説明プロパティー
name文字列ユーザーによって提供される、人間が判読できるクラスター名。name はそのタイプの全クラスターリソースで一意です。
description文字列ユーザーによって提供される、人間が判読できる自由形式のクラスターの説明 
link rel="networks"リレーションシップそのクラスターに関連付けられたネットワークのサブコレクションへのリンク 
link rel="permissions"リレーションシップクラスターパーミッションのサブコレクションへのリンク 
link rel="glustervolumes"リレーションシップこのクラスターに関連付けられた Red Hat Gluster Storage ボリュームのサブコレクションへのリンク 
link rel="glusterhooks"リレーションシップそのクラスターに関連付けられた Red Hat Gluster Storage ボリュームフックのサブコレクションへのリンク 
link rel="affinitygroups"リレーションシップそのクラスターに関連付けられた仮想マシンのアフィニティーグループのサブコレクションへのリンク 
cpu id=複合型クラスター内で全ホストがサポートする必要のある CPU タイプを定義するサーバーの CPU 参照
data_center id=GUIDそのクラスターのデータセンターメンバーシップへの参照
memory_policy複合型ホストのメモリー使用に関するクラスターのポリシーを定義します。
scheduling_policy複合型クラスター内のホストの負荷分散またはパワーセービングのモードを定義します。
version major= minor=複合型クラスターの互換性レベル
supported_versions複合型クラスターに設定可能な version レベルの一覧
error_handling複合型/列挙型クラスター内のホストが非稼働状態になった場合の仮想マシンの処理を定義します。capabilities 内に記載されている列挙型のプロパティーを含む on_error 要素が 1 つ必要です。 
virt_serviceブール値そのクラスターの仮想化サービスを公開するかどうかを定義します。 
gluster_serviceブール値このクラスターの Red Hat Gluster Storage サービスを公開するかどうかを定義します。 
threads_as_coresブール値プロセッサーコア合計数がホストのコア数を上回る場合に、ホストが仮想マシンを実行できるかどうかを定義します。 
tunnel_migrationブール値仮想マシンが移行中に libvirt/libvirt 間のトンネルを使用するかどうかを定義します。 
trusted_serviceブール値ホストの検証に OpenAttestation サーバーを使用するかどうかを定義します。 
ballooning_enabledブール値クラスターでバルーニングを有効化するかどうかを定義します。 
ksmブール値クラスターで ksm を有効化するかどうかを定義します。 

注記

ホストの 空きメモリーが 20% 未満に下がると、mom.Controllers.Balloon - INFO Ballooning guest:half1 from 1096400 to 1991580 のようなバルーニングコマンドが /etc/vdsm/mom.conf にログ記録されます。/etc/vdsm/mom.conf は、Memory Overcommit Manager のログファイルです。イベントは、仮想マシンがバルーンを優先しない場合にも、イベントログに追加されます。

10.2. memory_policy 要素

memory_policy 要素には次のような要素が含まれます。

表10.2 memory_policy 要素

要素タイプ説明プロパティー
overcommit percent=複合型許容されるホストのメモリー使用率。この値を超えると、そのホスト上では仮想マシンをそれ以上起動できなくなります。KSM を使用する環境では、メモリー共有により、仮想マシンは使用可能なホストメモリーを超える容量を使用することができます。推奨値には 100 (なし)、150 (サーバーの負荷)、および 200 (デスクトップの負荷) が含まれます。
transparent_hugepages複合型Transparent Hugepage の enabled ステータスを定義します。ステータスは true または false のいずれかです。capabilities 機能セットをチェックして、ご使用のバージョンが transparent hugepages をサポートしていることを確認してください。

10.3. スケジューリングポリシーの要素

scheduling_policy 要素には次のような要素が含まれます。

表10.3 スケジューリングポリシーの要素

要素タイプ説明プロパティー
policy列挙型クラスター内のホストの仮想マシンスケジューリングモード。列挙型の一覧は capabilities に記載されています。
thresholds low= high= duration=複合型ホストの CPU 制限値を定義します。high 属性は、ホストに許容される最大 CPU 使用率を制御し、この値を上回ると過負荷とみなされます。low 属性は、ホストに許容される最小 CPU 使用率を制御し、この値を下回ると使用率が低い状態とみなされます。duration 属性は、ホストが過負荷の状態で経過する必要のある秒数を示し、この値を超えると、スケジューラーが起動して負荷を別のホストに移します。

10.4. クラスターの XML 表現

例10.1 クラスターの XML 表現

<cluster id="00000000-0000-0000-0000-000000000000"
  href="/api/clusters/00000000-0000-0000-0000-000000000000">
    <name>Default</name>
    <description>The default server cluster</description>
    <link rel="networks"
      href="/api/clusters/00000000-0000-0000-0000-000000000000/networks"/>
    <link rel="permissions"
      href="/api/clusters/00000000-0000-0000-0000-000000000000/permissions"/>
          <link rel="glustervolumes"
      href="/api/clusters/00000000-0000-0000-0000-000000000000/glustervolumes"/>
          <link rel="glusterhooks"
      href="/api/clusters/00000000-0000-0000-0000-000000000000/glusterhooks"/>
          <link rel="affinitygroups"
      href="/api/clusters/00000000-0000-0000-0000-000000000000/affinitygroups"/>
    <cpu id="Intel Penryn Family"/>
        <architecture>X86_64<architecture/>
    <data_center id="00000000-0000-0000-0000-000000000000"
      href="/api/datacenters/00000000-0000-0000-0000-000000000000"/>
    <memory_policy>
        <overcommit percent="100"/>
        <transparent_hugepages>
            <enabled>false</enabled>
        </transparent_hugepages>
    </memory_policy>
    <scheduling_policies>
      <policy>evenly_distributed</policy>
      <thresholds low="10" high="75" duration="120"/>
    </scheduling_policies>
    <version minor="0" major="3"/>
    <supported_versions>
        <version minor="0"<usage> major="3"/>
    </supported_versions>
    <error_handling>
        <on_error>migrate</on_error>
    </error_handling>
    <virt_service>true</virt_service>
    <gluster_service>false</gluster_service>
    <threads_as_cores>false</threads_as_cores>
    <tunnel_migration>false</tunnel_migration>
    <trusted_service>false</trusted_service>
    <ha_reservation>false</ha_reservation>
    <ballooning_enabled>false</ballooning_enabled>
    <ksm>
        <enabled>true</enabled>
    </ksm>
</cluster>

10.5. クラスターの JSON 表現

例10.2 クラスターの JSON 表現

{
  "cluster" : [ {
    "cpu" : {
      "architecture" : "X86_64",
      "id" : "Intel Penryn Family"
    },
    "data_center" : {
      "href" : "/api/datacenters/00000002-0002-0002-0002-000000000255",
      "id" : "00000002-0002-0002-0002-000000000255"
    },
    "memory_policy" : {
      "overcommit" : {
        "percent" : "100"
      },
      "transparent_hugepages" : {
        "enabled" : "true"
      }
    },
    "scheduling_policy" : {
      "policy" : "none",
      "name" : "none",
      "href" : "/api/schedulingpolicies/b4ed2332-a7ac-4d5f-9596-99a439cb2812",
      "id" : "b4ed2332-a7ac-4d5f-9596-99a439cb2812"
    },
    "version" : {
      "major" : "3",
      "minor" : "5"
    },
    "error_handling" : {
      "on_error" : "migrate"
    },
    "virt_service" : "true",
    "gluster_service" : "false",
    "threads_as_cores" : "false",
    "tunnel_migration" : "false",
    "trusted_service" : "false",
    "ha_reservation" : "false",
    "optional_reason" : "false",
    "ballooning_enabled" : "false",
    "ksm" : {
      "enabled" : "true"
    },
    "required_rng_sources" : { },
    "name" : "Default",
    "description" : "The default server cluster",
    "href" : "/api/clusters/00000001-0001-0001-0001-0000000002fb",
    "id" : "00000001-0001-0001-0001-0000000002fb",
    "link" : [ {
      "href" : "/api/clusters/00000001-0001-0001-0001-0000000002fb/networks",
      "rel" : "networks"
    }, {
      "href" : "/api/clusters/00000001-0001-0001-0001-0000000002fb/permissions",
      "rel" : "permissions"
    }, {
      "href" : "/api/clusters/00000001-0001-0001-0001-0000000002fb/glustervolumes",
      "rel" : "glustervolumes"
    }, {
      "href" : "/api/clusters/00000001-0001-0001-0001-0000000002fb/glusterhooks",
      "rel" : "glusterhooks"
    }, {
      "href" : "/api/clusters/00000001-0001-0001-0001-0000000002fb/affinitygroups",
      "rel" : "affinitygroups"
    }, {
      "href" : "/api/clusters/00000001-0001-0001-0001-0000000002fb/cpuprofiles",
      "rel" : "cpuprofiles"
    } ]
  } ]
}

10.6. メソッド

10.6.1. クラスターの作成

新規クラスターの作成には、namecpu id=、および datacenter の各要素が必要です。datacenterid 属性または name 要素で特定します。

例10.3 クラスターの作成

POST /api/clusters HTTP/1.1
Accept: application/xml
Content-type: application/xml

<cluster>
    <name>cluster1</name>
    <cpu id="Intel Penryn Family"/>
    <data_center id="00000000-0000-0000-0000-000000000000"/>
</cluster>

10.6.2. クラスターの更新

namedescriptioncpu id=error_handling の各要素は、作成後に更新が可能です。

例10.4 クラスターの更新

PUT /api/clusters/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<cluster>
    <description>Cluster 1</description>
</cluster>

10.6.3. クラスターの削除

クラスターを削除するには DELETE 要求を実行する必要があります。

例10.5 クラスターの削除

DELETE /api/clusters/00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content

10.7. サブコレクション

10.7.1. ネットワークのサブコレクション

10.7.1.1. ネットワークのサブコレクション

クラスターに関連付けられるネットワークは networks サブコレクションで表現します。1 クラスター内のホストはすべて、これらの関連付けられたネットワークに接続します。
クラスターの network サブコレクションの表現は、以下の追加要素を除いては、標準の network リソースと同じです。

表10.4 追加のネットワーク要素

要素タイプ説明プロパティー
cluster id=リレーションシップネットワークがメンバーとなっているクラスターへの参照
requiredブール値必須または任意のネットワークステータスを定義します。 
displayブール値表示ネットワークステータスを定義します。後方互換性を維持するために使用されます。 
usages複合型ネットワークの usage 要素セットを定義します。ユーザーはこのレベルでネットワークを VM および DISPLAY ネットワークとして定義できます。 
API ユーザーは、標準の REST メソッドを使用して networks サブコレクションを操作します。ネットワーク id または name の参照を networks サブコレクションに POST することにより、そのネットワークはクラスターに関連付けられます。

例10.6 クラスターへのネットワークリソースの関連付け

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<network id="da05ac09-00be-45a1-b0b5-4a6a2438665f">
    <name>ovirtmgmt</name>
</network>

HTTP/1.1 201 Created
Location: http://{host}/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f
Content-Type: application/xml

<network id="da05ac09-00be-45a1-b0b5-4a6a2438665f"
  href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/
  da05ac09-00be-45a1-b0b5-4a6a2438665f">
    <name>ovirtmgmt</name>
    <status>
        <state>operational</state>
    </status>
    <description>Display Network</description>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
    <data_center id="d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"
      href="/api/datacenters/d70d5e2d-b8ad-494a-a4d2-c7a5631073c4"/>
    <required>true</required>
    <usages>
        <usage>VM</usage>
    </usages>
</network>
PUT 要求を使用してリソースを更新します。

例10.7 ディスプレイネットワークステータスの設定

PUT /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<network>
    <required>false</required>
    <usages>
        <usage>VM</usage>
        <usage>DISPLAY</usage>
    </usages>
</network>
PUT 要求を使用して必須または任意のネットワークステータスを設定し、required 要素のブール値 (true または false) を指定します。

例10.8 任意ネットワークステータスの設定

PUT /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<network>
    <required>false</required>
</network>
関連付けは、コレクション内の該当する要素に対する DELETE 要求で削除します。

例10.9 クラスターからのネットワーク関連付けの削除

DELETE /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/networks/da05ac09-00be-45a1-b0b5-4a6a2438665f HTTP/1.1

HTTP/1.1 204 No Content

10.7.2. ストレージボリュームのサブコレクション

10.7.2.1. Red Hat Gluster Storage ボリュームのサブコレクション

Red Hat Enterprise Virtualization では、Red Hat Gluster Storage ボリュームを作成および管理できます。Red Hat Gluster Storage ボリュームは、クラスターに関連付けられ、glustervolumes サブコレクションで表されます。
glustervolumes サブコレクション内の Red Hat Gluster Storage ボリュームリソースの表現は、以下の要素を使用して定義されます。

表10.5 Gluster ボリュームの要素

要素タイプ説明プロパティー
volume_type列挙型ボリュームタイプを定義します。ボリュームタイプのリストについては、capabilities コレクションを参照してください。
bricksリレーションシップRed Hat Gluster Storage ブリックのサブコレクションです。新規ボリュームを作成する場合は、このクラスターで作成および管理するために brick 要素のセットが要求で必要です。Red Hat Gluster Storage サーバーの server_id およびブリックディレクトリーの brick_dir 要素が必要となります。
transport_types複合型ボリューム transport_type 要素のセットを定義します。利用可能なトランスポートタイプのリストについては、capabilities コレクションを参照してください。
replica_count整数複製ボリュームのファイルレプリケーション数を定義します。
stripe_count整数ストライプボリュームのストライプ数を定義します。
options複合型追加の Red Hat Gluster Storage option 要素のセットです。各 option には、オプションの namevalue が含まれます。

例10.10 Red Hat Gluster Storage ボリュームの XML 表現

<gluster_volume id="99408929-82cf-4dc7-a532-9d998063fa95"
  href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95
  /glustervolume/e199f877-900a-4e30-8114-8e3177f47651">
    <name>GlusterVolume1</name>
    <link rel="bricks"
      href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95
      /glustervolume/e199f877-900a-4e30-8114-8e3177f47651/bricks"/>
    <volume_type>DISTRIBUTED_REPLICATE</volume_type>
    <transport_types>
        <transport_type>TCP</transport_type>
    </transport_types>
    <replica_count>2</replica_count>
    <stripe_count>1</stripe_count>
    <options>
        <option>
            <name>cluster.min-free-disk</name>
            <value>536870912</value>
        </option>
    </options>   
</gluster_volume>
POST 要求で必要な namevolume_type、および bricks をサブコレクションに送信して Red Hat Gluster Storage ボリュームを作成します。

例10.11 Red Hat Gluster Storage ボリュームの作成

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<gluster_volume>
    <name>GlusterVolume1</name>
    <volume_type>DISTRIBUTED_REPLICATE</volume_type>
    <bricks>
        <brick>
            <server_id>server1</server_id>
            <brick_dir>/exp1</brick_dir>
        </brick>
    <bricks>
</gluster_volume>
DELETE 要求を使用して Red Hat Gluster Storage ボリュームを削除します。

例10.12 Red Hat Gluster Storage ボリュームの削除

DELETE /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651 HTTP/1.1

HTTP/1.1 204 No Content

重要

glustervolumes サブコレクション内のリソースは更新できません。

10.7.2.2. ブリックサブコレクション

glustervolumes サブコレクションには、独自の bricks サブコレクションが格納されおり、Red Hat Gluster Storage ボリューム内の個々のブリックを定義します。GET 要求に関する追加の情報は、All-Content: true ヘッダーを使用して取得することができます。
ボリュームの bricks サブコレクションの表現は、以下の要素を使用して定義されます。

表10.6 ブリックの要素

要素タイプ説明プロパティー
server_id文字列Red Hat Gluster Storage サーバーへの参照
brick_dir文字列Red Hat Gluster Storage サーバーのブリックディレクトリーを定義します。
replica_count整数ボリューム内のブリックのファイルレプリケーション数を定義します。
stripe_count整数ボリューム内のブリックのストライプ数を定義します。
POST 要求で必要な server_id および brick_dir をサブコレクションに対して送信して新規ブリックを作成します。

例10.13 ブリックの追加

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/bricks HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<brick>
    <server_id>server1</server_id>
    <brick_dir>/exp1</brick_dir>
</brick>
DELETE 要求でブリックを削除します。

例10.14 ブリックの削除

DELETE /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/bricks/0a473ebe-01d2-444d-8f58-f565a436b8eb HTTP/1.1

HTTP/1.1 204 No Content

重要

bricks サブコレクション内のリソースは更新できません。

10.7.2.3. アクション

10.7.2.3.1. start アクション
start アクションは、Gluster ボリュームを使用できる状態にします。

例10.15 ボリュームの起動

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/start HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<action/>
オプションの force ブール値要素を使用して、稼働しているボリュームに対して操作を強制的に実行します。これは、稼働しているボリュームで無効なブリックプロセスを開始する場合に役に立ちます。
10.7.2.3.2. stop アクション
stop アクションは Gluster ボリュームを非アクティブ化します。

例10.16 ボリュームの停止

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/stop HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<action/>
stop アクションを強制するには、オプションの force ブール要素を使用します。
10.7.2.3.3. setOption アクション
setOption アクションは、ボリュームのオプションを設定します。

例10.17 オプションの設定

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/setoption HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<action>
    <option>
        <name>cluster.min-free-disk</name>
        <value>536870912</value>
    </option>
</action>
10.7.2.3.4. resetOption アクション
resetOption アクションは、ボリュームのオプションをリセットします。

例10.18 オプションのリセット

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/resetoption HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<action>
        <option>
            <name>cluster.min-free-disk</name>
        </option>
</action>
10.7.2.3.5. resetAllOptions アクション
resetAllOptions アクションは、ボリュームの全オプションをリセットします。

例10.19 全オプションのリセット

POST /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes/e199f877-900a-4e30-8114-8e3177f47651/resetalloptions HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<action/>

10.7.3. アフィニティーグループのサブコレクション

10.7.3.1. アフィニティーグループのサブコレクション

affinitygroups サブコレクション内の仮想マシンアフィニティーグループリソースの表現は、以下の要素を使用して定義されます。

表10.7 アフィニティーグループの要素

要素タイプ説明プロパティー
name文字列プレーンテキスト形式の人間が判読できるアフィニティーグループ名
clusterリレーションシップアフィニティーグループの適用先のクラスターへの参照 
positiveブール値: true または falseアフィニティーグループがアフィニティーグループに所属する仮想マシンに対して、ポジティブ、ネガティブいずれのアフィニティーを適用するか指定します。 
enforcingブール値: true または falseアフィニティーグループにおけるアフィニティーの強制で、アフィニティーグループに所属する仮想マシンに適用する際にハードまたはソフトのいずれを使用するかを指定します。 

例10.20 仮想マシンのアフィニティーグループの XML 表現

<affinity_group href="/api/clusters/00000000-0000-0000-0000-000000000000/affinitygroups/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
  <name>AF_GROUP_001</name>
  <cluster href="/api/clusters/00000000-0000-0000-0000-000000000000"
    id="00000000-0000-0000-0000-000000000000"/>
  <positive>true</positive>
  <enforcing>true</enforcing>
</affinity_group>
必要な name 属性を指定して POST 要求を使用して仮想マシンのアフィニティーグループを作成します。

例10.21 仮想マシンのアフィニティーグループの作成

POST https://XX.XX.XX.XX/api/clusters/00000000-0000-0000-0000-000000000000/affinitygroups HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<affinity_group>
  <name>AF_GROUP_001</name>
  <positive>true</positive>
  <enforcing>true</enforcing>
</affinity_group>
DELETE 要求で仮想マシンのアフィニティーグループを削除します。

例10.22 仮想マシンのアフィニティーグループの削除

DELETE https://XX.XX.XX.XX/api/clusters/00000000-0000-0000-0000-000000000000/affinitygroups/00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content

第11章 ネットワーク

11.1. ネットワークの要素

networks コレクションは、Red Hat Enterprise Virtualization 環境内の論理ネットワークに関する情報を提供します。API ユーザーは、エントリーポイント URL から取得した rel="networks" リンクでこの情報にアクセスします。
以下の表には、ネットワークリソースの表現に含まれる特定の要素をまとめています。

表11.1 ネットワークの要素

要素タイプ説明プロパティー
link rel="vnicprofiles"リレーションシップその論理ネットワークにアタッチされている VNIC プロファイルのサブコレクションへのリンク 
link rel="labels"リレーションシップその論理ネットワークにアタッチされているラベルのサブコレクションへのリンク 
data_center id=GUIDそのクラスターが属するデータセンターへの参照
vlan id=整数VLAN タグ
stpブール値: true または falseそのネットワークで Spanning Tree Protocol を有効にする場合は true に設定します。
mtu整数論理ネットワークの最大転送単位を指定します。この値が記載されていない場合には、論理ネットワークはデフォルト値を使用します。
statusoperational または non_operationalネットワークのステータス。これらのステータスは、capabilities の下の network_states に記載されています。
usages複合型ネットワークの usage 要素セットを定義します。ユーザーはこのレベルでネットワークを VM ネットワークとして定義することが可能です。 

重要

API は、本セクションに記載した時点では試験段階にあり、今後変更される可能性があるため、後方互換性に関する記載内容は適用されません。

11.2. ネットワークリソースの XML 表現

例11.1 ネットワークリソースの XML 表現

<network href="/api/networks/00000000-0000-0000-0000-000000000000"
  id="00000000-0000-0000-0000-000000000000">
  <name>ovirtmgmt</name>
  <description>Management Network</description>
  <link href="/api/networks/00000000-0000-0000-0000-000000000000/permissions" rel="permissions"/>
  <link href="/api/networks/00000000-0000-0000-0000-000000000000/vnicprofiles" rel="vnicprofiles"/>
  <link href="/api/networks/00000000-0000-0000-0000-000000000000/labels" rel="labels"/>
  <data_center href="/api/datacenters/00000000-0000-0000-0000-000000000000"
    id="00000000-0000-0000-0000-000000000000"/>
  <stp>false</stp>
  <mtu>0</mtu>
  <usages>
    <usage>vm</usage>
  </usages>
</network>

11.3. ネットワークリソースの JSON 表現

例11.2 ネットワークリソースの JSON 表現

{
  "network" : [ {
    "data_center" : {
      "href" : "/api/datacenters/00000002-0002-0002-0002-000000000255",
      "id" : "00000002-0002-0002-0002-000000000255"
    },
    "stp" : "false",
    "mtu" : "0",
    "usages" : {
      "usage" : [ "vm" ]
    },
    "name" : "ovirtmgmt",
    "description" : "Management Network",
    "href" : "/api/networks/00000000-0000-0000-0000-000000000009",
    "id" : "00000000-0000-0000-0000-000000000009",
    "link" : [ {
      "href" : "/api/networks/00000000-0000-0000-0000-000000000009/permissions",
      "rel" : "permissions"
    }, {
      "href" : "/api/networks/00000000-0000-0000-0000-000000000009/vnicprofiles",
      "rel" : "vnicprofiles"
    }, {
      "href" : "/api/networks/00000000-0000-0000-0000-000000000009/labels",
      "rel" : "labels"
    } ]
  } ]
}

11.4. メソッド

11.4.1. ネットワークリソースの作成

新規ネットワークの作成には name および datacenter 要素が必要です。

例11.3 ネットワークリソースの作成

POST /api/networks HTTP/1.1
Accept: application/xml
Content-type: application/xml

<network>
    <name>network 1</name>
    <data_center id="00000000-0000-0000-0000-000000000000"/>
</network>

11.4.2. ネットワークリソースの更新

namedescriptionipvlanstpdisplay の各要素は、作成後に更新が可能です。

例11.4 ネットワークリソースの更新

PUT /api/networks/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<network>
    <description>Network 1</description>
</network>

11.4.3. ネットワークリソースの削除

ネットワークを削除するには DELETE 要求を実行する必要があります。

例11.5 ネットワークの削除

DELETE /api/networks/00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content

11.5. サブコレクション

11.5.1. ネットワーク VNIC プロファイルのサブコレクション

VNIC (Virtual Network Interface Controller) プロファイル (別称: 仮想マシンインターフェースプロファイル) は、ユーザーやグループに適用してネットワーク帯域幅を制限するためのカスタマイズされたプロファイルです。各 vnicprofile には以下のような要素が含まれています。

表11.2 VNIC プロファイルの要素

要素タイプ説明
name文字列プロファイルの一意識別子
description文字列プレーンテキストで記述されたプロファイルの説明
network文字列プロファイルが適用される論理ネットワークの一意識別子
port_mirroringブール値: true または falseデフォルトは false です。

例11.6 ネットワークの vnicprofile サブコレクションの XML 表現

<vnic_profile href= "/api/vnicprofiles/f9c2f9f1-3ae2-4100-a9a5-285ebb755c0d" id="f9c2f9f1-3ae2-4100-a9a5-285ebb755c0d">
	<name>Peanuts</name>
	<description>shelled</description>
	<network href= "/api/networks/00000000-0000-0000-0000-000000000009" id="00000000-0000-0000-0000-000000000009"/>
	<port_mirroring>false</port_mirroring>
	</vnic_profile>
</vnic_profiles>

11.5.2. ネットワークラベルのサブコレクション

ネットワークラベルはプレーンテキスト形式の人間が判読できるラベルで、物理ホストのネットワークインターフェースと論理ネットワークを自動的に関連付けることができます。各 label には以下の要素が含まれています。

表11.3 ラベルの要素

要素タイプ説明
network文字列ラベルを付けるネットワークの hrefid です。

例11.7 ネットワークのラベルサブコレクションの XML 表現

<labels>
  <label href="/api/networks/00000000-0000-0000-0000-000000000000/labels/eth0" id="eth0">
    <network href="/api/networks/00000000-0000-0000-0000-000000000000"
      id="00000000-0000-0000-0000-000000000000"/>
  </label>
</labels>

11.5.3. メソッド

11.5.3.1. 論理ネットワークにラベルを付けるアクション

論理ネットワークにラベルをつけて、同じラベルを付けたホストのネットワークインターフェースと論理ネットワークを自動的に関連付けることができます。

例11.8 論理ネットワークにラベルを付けるアクション

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

<label id="Label_001" />

11.5.3.2. 論理ネットワークからのラベルの削除

論理ネットワークからラベルを削除するには DELETE 要求が必要です。

例11.9 論理ネットワークからのラベルの削除

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

HTTP/1.1 204 No Content

第12章 ストレージドメイン

12.1. ストレージドメインの要素

storagedomains コレクションは、Red Hat Enterprise Virtualization 環境内のストレージドメインに関する情報を提供します。API ユーザーは、エントリーポイント URL から取得した rel="storagedomains" リンクでこの情報にアクセスします。
以下の表には、ストレージドメインリソースの表現に含まれる特定の要素をまとめています。

表12.1 Storage domain の要素

要素タイプ説明プロパティー
link rel="permissions"リレーションシップストレージドメインパーミッションのサブコレクションへのリンク 
link rel="files"リレーションシップそのストレージドメインの files サブコレクションへのリンク 
link rel="vms"リレーションシップtypeexport に設定されているストレージドメインの vms サブコレクションへのリンク 
link rel="templates"リレーションシップtypeexport に設定されているストレージドメインの templates サブコレクションへのリンク 
type列挙型ストレージドメインのタイプ。列挙値の一覧は capabilities に記載されています。
external_status複合型/列挙型外部システムおよびプラグインがレポートするストレージドメインのヘルスステータス。state 要素には、okinfowarningerror または failure の列挙値が含まれます。 
masterブール値: true または falseそのストレージドメインがデータセンターのマスターストレージドメインとなる場合は true です。
host複合型そのストレージドメインの初期化を行うホストへの参照。このホストに対する制約は、指定された物理ストレージにアクセス可能であるという点以外はありません。
storage複合型ストレージドメインの下層のストレージについての記述
available整数空き領域 (バイト単位)
used整数使用済み領域 (バイト単位)
committed整数コミット済み領域 (バイト単位)
storage_format列挙型ストレージドメインのストレージフォーマットについての記述。列挙値の一覧は capabilities に記載されています。
wipe_after_deleteブール値: true または falseストレージドメインで削除後にワイプオプションをデフォルト設定します。このオプションは、ドメインの作成後に編集することが可能ですが、その場合にはすでに存在していたディスクの「削除後にワイプ」プロパティーは変更されません。 
warning_low_space_indicator整数容量不足の警告オプションを設定するパーセンテージ値。ストレージドメインの空き容量がこの値を下回ると、ユーザーに警告のメッセージが表示され、ログに記録されます。 
critical_space_action_blocker整数アクションをブロックする深刻な容量不足オプションを設定する値 (GB 単位)。ストレージドメインの空き容量がこの値を下回ると、ユーザーにエラーメッセージが表示され、ログに記録されます。容量を消費する新規アクションは、一時的であってもすべてブロックされます。 

重要

API は、本章に記載した時点では試験段階にあり、今後変更される可能性があるため、後方互換性に関する記載内容は適用されません。

12.2. ストレージドメインの XML 表現

例12.1 ストレージドメインの XML 表現

<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
  href="/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed">
    <name>data0</name>
    <link rel="permissions"
      href="/api/storagedomains/be24cd98-8e23-49c7-b425-1a12bd12abb0/permissions"/>
    <link rel="files"
      href="/api/storagedomains/be24cd98-8e23-49c7-b425-1a12bd12abb0/files"/>
    <type>data</type>
    <master>true</master>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/images/0</path>
    </storage>
    <available>156766306304</available>
    <used>433791696896</used>
    <committed>617401548800</committed>
    <storage_format>v1</storage_format>
    <wipe_after_delete>true</wipe_after_delete>
    <warning_low_space_indicator>10</warning_low_space_indicator>
    <critical_space_action_blocker>5</critical_space_action_blocker>
</storage_domain>

12.3. ストレージドメインの JSON 表現

例12.2 ストレージドメインの JSON 表現

{
  "storage_domain" : [ {
    "type" : "data",
    "master" : "false",
    "storage" : {
      "address" : "192.0.2.0",
      "type" : "nfs",
      "path" : "/storage/user/nfs"
    },
    "available" : 193273528320,
    "used" : 17179869184,
    "committed" : 0,
    "storage_format" : "v3",
    "name" : "NFS_01",
    "href" : "/api/storagedomains/8827b158-6d2e-442d-a7ee-c6fd4718aaba",
    "id" : "8827b158-6d2e-442d-a7ee-c6fd4718aaba",
    "link" : [ {
      "href" : "/api/storagedomains/8827b158-6d2e-442d-a7ee-c6fd4718aaba/permissions",
      "rel" : "permissions"
    }, {
      "href" : "/api/storagedomains/8827b158-6d2e-442d-a7ee-c6fd4718aaba/disks",
      "rel" : "disks"
    }, {
      "href" : "/api/storagedomains/8827b158-6d2e-442d-a7ee-c6fd4718aaba/storageconnections",
      "rel" : "storageconnections"
    }, {
      "href" : "/api/storagedomains/8827b158-6d2e-442d-a7ee-c6fd4718aaba/disksnapshots",
      "rel" : "disksnapshots"
    }, {
      "href" : "/api/storagedomains/8827b158-6d2e-442d-a7ee-c6fd4718aaba/diskprofiles",
      "rel" : "diskprofiles"
    } ]
  } ]
}

12.4. メソッド

12.4.1. ストレージドメインの作成

新規のストレージドメインの作成には nametypehoststorage の各要素が必要です。host 要素は id 属性または name 要素で特定します。
Red Hat Enterprise Virtualization 3.6 以降では、ストレージドメインの削除後にワイプのオプションをデフォルトで有効にすることができます。この設定は、POST 要求で <wipe_after_delete> を指定します。このオプションは、ドメインの作成後に編集することが可能ですが、その場合にはすでに存在していたディスクの「削除後にワイプ」プロパティーは変更されません。

例12.3 ストレージドメインの作成

POST /api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
    
<storage_domain>
    <name>data1</name>
    <type>data</type>
    <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/images/0</path>
    </storage>
</storage_domain>
作成後には、API ユーザーがそのストレージドメインをデータセンターにアタッチします。

12.4.2. ストレージドメインの更新

name および wipe after delete 要素だけが作成後に更新可能です。wipe after delete 要素を変更しても、すでに存在していたディスクの「削除後にワイプ」プロパティーは変更されません。

例12.4 ストレージドメインの更新

PUT /api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml
    
<storage_domain>
    <name>data2</name>
    ...
    <wipe_after_delete>true</wipe_after_delete>
    ...
</storage_domain>

12.4.3. ストレージドメインの削除

ストレージドメインを削除するには DELETE 要求を実行する必要があります。

例12.5 ストレージドメインの削除

DELETE /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed HTTP/1.1

HTTP/1.1 204 No Content

12.5. ストレージタイプ

12.5.1. ストレージタイプ

storage 要素には、type 要素 (列挙値) が含まれ、capabilities コレクションの下に記載されています。
また、ストレージ要素には、各ストレージの type に固有の追加要素も含まれます。次の項では、これらのストレージ type 追加要素について考察します。

12.5.2. NFS ストレージ

次の表には、storage の記述に含まれる nfs 固有の要素をまとめています。

表12.2 NFS 固有の要素

要素タイプ説明プロパティー
address文字列NFS サーバーのホスト名または IP アドレス
path文字列サーバー上でマウント可能な NFS ディレクトリーのパス

12.5.3. PosixFS ストレージ

以下の表には、storage の記述に含まれる posixfs 固有の要素をまとめています。

表12.3 PosixFS 固有の要素

要素タイプ説明プロパティー
address文字列PosixFS サーバーのホスト名または IP アドレス
path文字列サーバー上にマウント可能な PosixFS ディレクトリーのパス
vfs_type文字列PosixFS 共有の Linux 対応ファイルシステムのタイプ
mount_options文字列PosixFS 共有のマウントオプション

12.5.4. iSCSI および FCP のストレージ

以下の表には、storage の記述に含まれる iscsi および fcp の固有の要素を示します。

表12.4 iSCSI および FCP 固有の要素

要素タイプ説明プロパティー
logical_unit id=複合型論理ユニットの id。ストレージドメインは複数の iSCSI / FCP 論理ユニットも受け入れます。
override_lunsブール値すべての論理単位設定を新しい設定に置き換えるかどうかを定義します。上書きする場合は true に設定します。
logical_unit にはサブ要素セットが含まれます。

表12.5 論理ユニットの要素

要素タイプ説明プロパティー
address文字列ストレージデバイスを格納しているサーバーのアドレス
port整数サーバーのポート番号
target文字列ストレージデバイスのターゲット IQN
username文字列ターゲットにログインするための CHAP ユーザー名
password文字列ターゲットにログインするための CHAP パスワード
serial文字列ターゲットのシリアル ID
vendor_id文字列ターゲットのベンダー名
product_id文字列ターゲットの製品コード
lun_mapping整数ターゲットの論理ユニット番号デバイスマッピング
iSCSI を使用しており、logical_unit の記述に該当する LUN を使用する iSCSI ターゲットの詳細も含まれる場合には、そのターゲットはストレージの作成時に自動ログインを実行します。

12.5.5. LocalFS ストレージ

storage の記述に含まれる localfs 固有の要素

表12.6 Localfs 固有の要素

要素タイプ説明プロパティー
path文字列ホスト上のローカルストレージドメインのパス
localfs ストレージドメインには、storage_typelocalfs に設定されているデータセンターが必要です。このデータセンターには、単一のホストクラスターのみが含まれ、そのホストクラスターには単一のホストのみが含まれます。

12.6. エクスポートストレージドメイン

12.6.1. エクスポートストレージドメイン

typeexport に設定されているストレージドメインには、vms および templates のサブコレクションが含まれ、その特定のストレージドメインに格納されているインポート候補の仮想マシンおよびテンプレートが記載されています。

例12.6 エクスポートストレージドメインの仮想マシンサブコレクションの表示

GET /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<vms>
    <vm id="082c794b-771f-452f-83c9-b2b5a19c0399"
      href="/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/
      vms/082c794b-771f-452f-83c9-b2b5a19c0399">
        <name>vm1</name>
        ...
        <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
          href="/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed"/>
        <actions>
            <link rel="import" href="/api/storagedomains/
              fabe0451-701f-4235-8f7e-e20e458819ed/vms/
              082c794b-771f-452f-83c9-b2b5a19c0399/import"/>
        </actions>
    </vm>
</vms>
これらのコレクション内の仮想マシン/テンプレートに記載されている表現は、仮想マシン/テンプレートの最上位コレクション内の対応する表現と同様ですが、storage_domain 参照と import アクションも含まれている点が異なります。
import アクションは、export ストレージドメインから仮想マシンまたはテンプレートをインポートします。インポート先のクラスターおよびストレージドメインは clusterstorage_domain の参照で指定します。
仮想マシンまたはテンプレートに固有の名前を付ける場合は、オプションの name 要素を追加します。

例12.7 エクスポートストレージドメインから仮想マシンをインポートするアクション

POST /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/
082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <storage_domain>
        <name>images0</name>
    </storage_domain>
    <cluster>
        <name>Default</name>
    </cluster>
</action>

例12.8 エクスポートストレージドメインからテンプレートをインポートするアクション

POST /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/templates/
082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <storage_domain>
        <name>images0</name>
    </storage_domain>
    <cluster>
        <name>Default</name>
    </cluster>
</action>
仮想マシンを新しいエンティティーとしてインポートする場合は、オプションの clone ブール値要素を追加します。

例12.9 仮想マシンを新しいエンティティーとしてインポートする操作

POST /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/
082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <storage_domain>
        <name>images0</name>
    </storage_domain>
    <cluster>
        <name>Default</name>
    </cluster>
    <clone>true</clone>
    <vm>
        <name>MyVM</name>
    </vm>
    ...
</action>
disk id 要素を使用してインポートするディスクを選択する場合は、オプションの disks 要素を追加します。

例12.10 インポート操作を行うディスクの選択

POST /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/
082c794b-771f-452f-83c9-b2b5a19c0399/import HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <cluster>
        <name>Default</name>
    </cluster>
    <vm>
        <name>MyVM</name>
    </vm>
    ...
    <disks>
        <disk id="4825ffda-a997-4e96-ae27-5503f1851d1b"/>
    </disks>
</action>
export ストレージドメインからの仮想マシンおよびテンプレートの削除には DELETE 要求を使用します。

例12.11 エクスポートストレージドメインからの仮想マシンの削除

DELETE /api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed/vms/
082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml

HTTP/1.1 204 No Content

12.7. Glance イメージストレージドメイン

12.7.1. Glance イメージストレージドメイン

タイプが Image に設定されたストレージドメインは、外部プロバイダーとして Red Hat Enterprise Virtualization 環境に追加された OpenStack の Image Service のインスタンスを表します。これらの Glance イメージストレージドメインには、Glance イメージストレージドメインへエクスポートされた仮想マシンイメージまたはこのドメインからインポート可能な仮想マシンイメージを含む images サブコレクションが含まれています。

例12.12 Glance イメージストレージドメインのイメージサブコレクションの一覧表示

GET /api/storagedomains/00000000-0000-0000-0000-000000000000/images
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<images>
  <image href="/api/storagedomains/00000000-0000-0000-0000-000000000000/images/
    00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
    <actions>
      <link href="/api/storagedomains/00000000-0000-0000-0000-000000000000/images/
        00000000-0000-0000-0000-000000000000/import" rel="import"/>
    </actions>
    <name>RHEL_65_Disk_001</name>
    <storage_domain href="/api/storagedomains/00000000-0000-0000-0000-000000000000"
      id="00000000-0000-0000-0000-000000000000"/>
  </image>
  <image href="/api/storagedomains/00000000-0000-0000-0000-000000000000/images/
    00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
    <actions>
      <link href="/api/storagedomains/00000000-0000-0000-0000-000000000000/images/
        00000000-0000-0000-0000-000000000000/import" rel="import"/>
    </actions>
    <name>RHEL_65_Disk_002</name>
    <storage_domain href="/api/storagedomains/00000000-0000-0000-0000-000000000000"
      id="00000000-0000-0000-0000-000000000000"/>
  </image>
</images>
import アクションは、Glance イメージストレージドメインから仮想マシンのイメージをインポートします。インポート先のストレージドメインは、storage_domain 参照で、インポート先のクラスターは cluster で指定します。
仮想マシンまたはテンプレートに固有の名前を付ける場合は、オプションの name 要素を追加します。

例12.13 Glance イメージストレージドメインから仮想マシンをインポートするアクション

POST /api/storagedomains/00000000-0000-0000-000000000000/images/
00000000-0000-0000-000000000000/import HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <storage_domain>
        <name>images0</name>
    </storage_domain>
    <cluster>
        <name>images0</name>
    </cluster>
</action>
また、import_as_template 参照を指定して、イメージをテンプレートとしてインポートすることも可能です。

例12.14 Glance イメージストレージドメインから仮想マシンをテンプレートとしてインポートするアクション

POST /api/storagedomains/00000000-0000-0000-000000000000/images/
00000000-0000-0000-000000000000/import HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <storage_domain>
        <name>images0</name>
    </storage_domain>
    <cluster>
        <name>images0</name>
    </cluster>
    </import_as_template>true</import_as_template>
</action>

12.8. サブコレクション

12.8.1. ファイルのサブコレクション

各ストレージドメインの下の files サブコレクションは、クライアントで使用可能ファイルを表示する方法を提供します。このサブコレクションは、管理者が Red Hat Enterprise Virtualization Manager でアップロードした ISO イメージおよび仮想フロッピーディスク (VFD) を格納する ISO ストレージドメインを特に対象としています。
仮想マシンに CD-ROM デバイスを追加するには、ISO ストレージドメインの files サブコレクションの ISO イメージが必要です。

例12.15 ISO ストレージドメインの files サブコレクションの表示

GET /api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<files>
    <file id="en_winxp_pro_with_sp2.iso"
      href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files/
      en_winxp_pro_with_sp2.iso">
        <name>en_winxp_pro_with_sp2.iso</name>
        <type>iso</type>
        <storage_domain id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
          href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/>
    </file>
    <file id="boot.vfd"
      href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da/files/
      boot.vfd">
        <name>boot.vfd</name>
        <type>vfd</type>
        <storage_doman id="00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"
          href="/api/storagedomains/00f0d9ce-da15-4b9e-9e3e-3c898fa8b6da"/>
    </file>
</files>
他のリソースと同様に、files にも不透明な idhref の属性があります。name 要素にはファイル名が含まれます。

12.9. アクション

12.9.1. 既存のストレージドメインのインポート

API は、下層のストレージの再フォーマットせずに、Red Hat Enterprise Virtualization Manager の 1 つのインスタンスから ISO ストレージドメインまたはエクスポートストレージドメインを削除して、そのドメインを別のインスタンスにインポートする機能を提供しています。インポートの操作は、新規ストレージドメインの追加と同じですが、name は指定しません。

例12.16 既存のエクスポートストレージドメインのインポート

POST /api/storagedomains HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<storage_domain>
    <type>export</type>
    <storage>
        <type>nfs</type>
        <address>172.31.0.6</address>
        <path>/exports/RHEVX/export-domain</path>
    </storage>
    <host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"/>
</storage_domain>

HTTP/1.1 201 Created
Content-Type: application/xml

<storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"
  href="/api/storagedomains/fabe0451-701f-4235-8f7e-e20e458819ed">
    <name>export1</name>
    ...
</storage_domain>

12.9.2. ストレージドメインの削除

storage_domain 参照をストレージドメインの DELETE 要求の本文に渡します。storage_domain 参照は以下のような形式です。
<storage_domain>
    <host id="..."/>
</storage_domain>
または、
<storage_domain>
    <host>
        <name>...</name>
    </host>
</storage_domain>
ストレージドメインのフォーマット

オプションの format 要素で、ストレージドメインを削除した後にフォーマットするかどうかを指定します。

例12.17 ストレージドメイン削除後のフォーマット

<storage_domain>
    <host id="..."/>
    <format>true</format>
</storage_domain>
format 要素が渡されない場合には、ストレージドメインはフォーマットされない状態のままとなります。
ストレージドメインの論理削除

API はストレージドメインの論理削除する機能も提供します。これにより、ストレージドメインのインポート用データが保持されます。destroy 要素を使用してストレージドメインを論理的に削除し、データを保持します。

例12.18 ストレージドメインの論理削除

<storage_domain>
    <host id="..."/>
    <destroy>true</destroy>
</storage_domain>

第13章 ストレージ接続

13.1. ストレージ接続の要素

表13.1 ストレージ接続の基本要素

要素タイプ説明プロパティー
typenfsposixfslocaliscsi のいずれか 1 つストレージドメインのタイプ
address文字列ストレージドメインのホスト名または IP アドレス
(NFS および iSCSI の場合のみ必要)
host文字列ハイパーバイザーの id または namehost はオプションです。指定した場合には、ホスト経由でストレージへの接続を試み、指定しなかった場合には、データベース内のストレージ情報が保持されます。

表13.2 ファイルベースストレージのストレージ接続要素

要素タイプ説明プロパティー
path文字列ストレージドメインのマウント済みファイルパス。path は、ストレージ接続によってすでに使用されているパスには更新できません。
mount_options文字列PosixFS 共有のマウントオプション 
vfs_type文字列PosixFS 共有の Linux 対応ファイルシステムのタイプ
nfs_version文字列使用する NFS のバージョン 
nfs_timeo整数NFS クライアントが要求の完了を待機する時間 (デシ秒単位) 
nfs_retrans整数NFS クライアントが 1 つの要求を完了するのに試みる再送信の回数 

表13.3 ストレージ接続の iSCSI 要素

要素タイプ説明プロパティー
port整数iSCSI ストレージドメインに使用する TCP ポート
target文字列ストレージデバイスのターゲット IQN
username文字列ターゲットにログインするための CHAP ユーザー名 
password文字列ターゲットにログインするための CHAP パスワード 

13.2. ストレージ接続リソースの XML 表現

例13.1 ストレージ接続リソースの XML 表現

<storage_connections>
  <storage_connection href= "/api/storageconnections/608c5b96-9939-4331-96b5-197f28aa2e35"    id="608c5b96-9939-4331-96b5-197f28aa2e35">
    <address>domain.example.com</address>
    <type>nfs</type>
    <path>/var/lib/exports/iso</path>
  </storage_connection>
  <storage_connection href= "/api/storageconnections/2ebb3f78-8c22-4666-8df4-e4bb7fec6b3a" id="2ebb3f78-8c22-4666-8df4-e4bb7fec6b3a">
    <address>domain.example.com</address>
    <type>posixfs</type>
    <path>/export/storagedata/username/data</path>
    <vfs_type>nfs</vfs_type>
  </storage_connection>
</storage_connections>

13.3. メソッド

13.3.1. 新規ストレージ接続の作成

新規ストレージ接続を作成するには、POST 要求が必要です。
ストレージドメインを追加せずに新規ストレージ接続を作成することが可能です。ホストの id または name はオプションです。指定した場合には、そのホストを介してストレージへの接続を試みます。

例13.2 新規ストレージ接続の作成

POST /api/storageconnections HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_connection>
   <type>nfs</type>
   <address>domain.example.com</address>
   <path>/export/storagedata/username/data</path>
   <host>
     <name>Host_Name</name>
   </host>
</storage_connection>

13.3.2. ストレージ接続の削除

ストレージ接続の削除には DELETE 要求が必要です。ストレージ接続は、ストレージドメインと LUN ディスクのどちらもそのストレージ接続を参照していない場合にのみ削除することができます。
ホストの nameid はオプションです。指定した場合には、接続はそのホストからアンマウントされます。

例13.3 ストレージ接続の削除

DELETE /api/storageconnections/Storage_Connection_ID HTTP/1.1
Accept: application/xml
Content-type: application/xml

<host>
  <name>Host_Name</name>
</host>

13.3.3. ストレージ接続の更新

既存のストレージ接続を更新するには PUT 要求が必要です。接続を正しく更新するには、ストレージドメインはメンテナンスモードに入っているか、デタッチされている状態でなければなりません。
ホストの name または id の指定はオプションです。指定した場合には、ホストが更新されたストレージ情報への接続を試みます。

例13.4 ストレージ接続の更新

PUT /api/storageconnections/Storage_Connection_ID HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_connection>   
  <address>updated.example.domain.com</address>
  <host>
      <name>Host_name</name>
   </host>
</storage_connection>

13.3.4. iSCSI ストレージ接続の更新

既存の iSCSI ストレージ接続を更新するには PUT 要求が必要です。接続を正しく更新するには、iSCSI ストレージドメインはメンテナンスモードに入っているか、デタッチされている状態でなければなりません。

例13.5 ストレージ接続の更新

PUT /api/storageconnections/Storage_Connection_ID HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_connection>   
  <port>3456</port>
</storage_connection>

13.3.5. 既存のストレージ接続を使用する新規ストレージドメインの追加

既存のストレージ接続を使用する新規ストレージドメインを追加するには、POST 要求が必要です。これはファイルベースのストレージドメイン (NFSPOSIX、および local) にのみ適用することができます。

例13.6 既存のストレージ接続を使用する新規ストレージドメインの追加

POST /api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_domain>
  <name>New_Domain</name>
  <type>data</type>
 <storage id="Storage_Connection_ID"/>
  <host>
    <name>Host_Name</name>
  </host>
</storage_domain>

13.3.6. iSCSI ストレージへの追加ストレージ接続のアタッチ

iSCSI ストレージドメインに追加のストレージ接続をアタッチするには POST 要求が必要です。

例13.7 iSCSI ストレージへの追加ストレージ接続のアタッチ

POST /api/storagedomains/iSCSI_Domain_ID/storageconnections HTTP/1.1
Accept: application/xml
Content-type: application/xml

<storage_connection id="Storage_Connection_ID">
</storage_connection>

13.3.7. iSCSI ストレージからのストレージ接続のデタッチ

iSCSI ストレージドメインからストレージ接続をデタッチするには DELETE 要求が必要です。

例13.8 iSCSI ストレージからのストレージ接続のデタッチ

DELETE /api/storagedomains/iSCSI_Domain_ID/storageconnections/Storage_Connection_ID HTTP/1.1
Accept: application/xml
Content-type: application/xml

13.3.8. iSCSI ターゲットへの認証情報の定義

管理ポータルを使用して iSCSI ストレージドメインを追加すると、ユーザー名とパスワード 1 つずつしかそのドメインに指定できませんが、設定によっては、クラスター内のホストごとに別のユーザー名とパスワードが必要なものもあります。storageconnectionextensions 要素を使用すると、ホストごとに、固有の認証情報を各 iSCSI ターゲットに適用することができます。

例13.9 iSCSI ターゲットへの認証情報の定義

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

<storageconnectionextension>
    <target>iqn.2010.05.com.example:iscsi.targetX</target>
    <username>jimmy</username>
    <password>p@55w0Rd!</password>
</storageconnectionextension>

第14章 ホスト

14.1. ホストの要素

hosts コレクションは、Red Hat Enterprise Virtualization 環境内のホストに関する情報を提供します。API ユーザーは、エントリーポイント URL から取得した rel="hosts" リンクでこの情報にアクセスします。
GET 要求に関する追加の情報は、All-Content: true ヘッダーを使用して取得することができます。
以下の表には、ホストリソースの表現に含まれる特定の要素をまとめています。

表14.1 ホストの要素

要素タイプ説明プロパティー
link rel="storage"リレーションシップホストストレージの storage サブコレクションへのリンク
link rel="nics"リレーションシップホストのネットワークインターフェースの nics サブコレクションへのリンク 
link rel="numanodes"リレーションシップホストの NUMA ノードの numanodes サブコレクションへのリンク 
link rel="tags"リレーションシップホストのタグの tags サブコレクションへのリンク 
link rel="permissions"リレーションシップホストパーミッションの permissions サブコレクションへのリンク 
link rel="statistics"リレーションシップホストの統計の statistics サブコレクションへのリンク
link rel="hooks"リレーションシップホストのフックの hooks サブコレクションへのリンク
link rel="fenceagents"リレーションシップホストのフェンスエージェントの fenceagents サブコレクションへのリンク
link rel="katelloerrata"リレーションシップホストエラータの katelloerrata サブコレクションへのリンク
link rel="devices"リレーションシップホストデバイスの devices サブコレクションへのリンク
link rel="networkattachments"リレーションシップホストのネットワークインターフェースの networkattachments サブコレクションへのリンク
link rel="unmanagednetworks"リレーションシップ ホストの管理対象外ネットワークの unmanagednetworks サブコレクションへのリンク
link rel="storageconnectionextensions"リレーションシップホストストレージ接続の拡張機能の storageconnectionextensions サブコレクションへのリンク
name文字列ホストの一意識別子 
root_password文字列そのホストの root パスワード。規則により、作成時にクライアント提供のホストの表現のみに記載されます。
comment文字列ホストに関するコメント 
address文字列ホストの IP アドレスまたはホスト名
certificate複合型organization および subject を含むホストの証明書の詳細情報への参照
status下記参照ホストのステータス
external_status複合型/列挙型外部システムおよびプラグインがレポートするホストのヘルスステータス。state 要素には、okinfowarningerror または failure の列挙値が含まれます。 
cluster id=GUIDそのホストを含むクラスタへの参照 
port整数そのホストで実行中の VDSM デーモンのリッスンポート
typerhel または rhev-hホストタイプ
storage_manager priority=ブール値: true または falseホストがストレージマネージャーかどうかを指定します。
version major= minor= build= revision= full_version=複合型ホストの互換性レベル
hardware_information複合型manufacturerversionserial_numberproduct_nameuuidfamily など、ホストのハードウェアに関する情報 
power_management type=複合型enabledoptionskdump_detectionautomatic_pm_enabledagents などを含む、ホストの電源管理の設定オプション。ホストの電源管理オプションに関する詳しい情報は、「電源管理の要素」を参照してください。 
ksmブール値: true または falseKSM (Kernel SamePage Merging) が有効化されている場合は true 
transparent_hugepagesブール値: true または falseTransparent Hugepages が有効化されている場合は true 
iscsi複合型ホストの SCSI initiator
ssh複合型portfingerprint など、ホストとの SSH 接続に関する詳細 
cpu複合型ホスト CPU の統計。CPU の nametopology cores=topology sockets=topology threads=、および speed のサブ要素を含みます。topology cores= はコア数の合計を集計し、topology sockets= は物理 CPU の合計を集計します。仮想マシンが使用可能なコア数の合計は、ソケット数に 1 ソケットあたりのコア数を乗算した値と等しくなります。
memory整数ホストメモリーの合計容量 (バイト単位)
max_scheduling_memory整数スケジューリングに使用可能な最大メモリー量 (バイト)
summary複合型ホスト上の仮想マシンの統計のサマリー。activemigrating、および total の仮想マシン数のサブ要素が含まれます。
os type=複合型version full_version= など、ホストにインストールされたオペレーティングシステムの詳細
libvirt_version major= minor= build= revision= full_version=複合型ホストの libvirt 互換性レベル
status には次の列挙値のいずれかが含まれます: downerrorinitializinginstallinginstall_failedmaintenancenon_operationalnon_responsivepending_approvalpreparing_for_maintenanceconnectingrebootunassignedup。 これらのステータスは、capabilities の下の host_states に記載されています。

14.2. ホストの XML 表現

例14.1 ホストの XML 表現

<host href="/api/hosts/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
    <actions>
        <link href="/api/hosts/00000000-0000-0000-0000-000000000000/upgrade" rel="upgrade"/>
        <link href="/api/hosts/00000000-0000-0000-0000-000000000000/setupnetworks" rel="setupnetworks"/>
        <link href="/api/hosts/00000000-0000-0000-0000-000000000000/fence" rel="fence"/>
        <link href="/api/hosts/00000000-0000-0000-0000-000000000000/refresh" rel="refresh"/>
        <link href="/api/hosts/00000000-0000-0000-0000-000000000000/install" rel="install"/>
        <link href="/api/hosts/00000000-0000-0000-0000-000000000000/activate" rel="activate"/>
        <link href="/api/hosts/00000000-0000-0000-0000-000000000000/deactivate" rel="deactivate"/>
        <link href="/api/hosts/00000000-0000-0000-0000-000000000000/approve" rel="approve"/>
        <link href="/api/hosts/00000000-0000-0000-0000-000000000000/forceselectspm" rel="forceselectspm"/>
        <link href="/api/hosts/00000000-0000-0000-0000-000000000000/enrollcertificate" rel="enrollcertificate"/>
        <link href="/api/hosts/00000000-0000-0000-0000-000000000000/iscsilogin" rel="iscsilogin"/>
        <link href="/api/hosts/00000000-0000-0000-0000-000000000000/unregisteredstoragedomainsdiscover" rel="unregisteredstoragedomainsdiscover"/>
        <link href="/api/hosts/00000000-0000-0000-0000-000000000000/iscsidiscover" rel="iscsidiscover"/>
        <link href="/api/hosts/00000000-0000-0000-0000-000000000000/commitnetconfig" rel="commitnetconfig"/>
    </actions>
    <name>host1</name>
    <link href="/api/hosts/00000000-0000-0000-0000-000000000000/storage" rel="storage"/>
    <link href="/api/hosts/00000000-0000-0000-0000-000000000000/nics" rel="nics"/>
    <link href="/api/hosts/00000000-0000-0000-0000-000000000000/numanodes" rel="numanodes"/>
    <link href="/api/hosts/00000000-0000-0000-0000-000000000000/tags" rel="tags"/>
    <link href="/api/hosts/00000000-0000-0000-0000-000000000000/permissions" rel="permissions"/>
    <link href="/api/hosts/00000000-0000-0000-0000-000000000000/statistics" rel="statistics"/>
    <link href="/api/hosts/00000000-0000-0000-0000-000000000000/hooks" rel="hooks"/>
    <link href="/api/hosts/00000000-0000-0000-0000-000000000000/fenceagents" rel="fenceagents"/>
    <link href="/api/hosts/00000000-0000-0000-0000-000000000000/katelloerrata" rel="katelloerrata"/>
    <link href="/api/hosts/00000000-0000-0000-0000-000000000000/devices" rel="devices"/>
    <link href="/api/hosts/00000000-0000-0000-0000-000000000000/networkattachments" rel="networkattachments"/>
    <link href="/api/hosts/00000000-0000-0000-0000-000000000000/unmanagednetworks" rel="unmanagednetworks"/>
    <link href="/api/hosts/00000000-0000-0000-0000-000000000000/storageconnectionextensions" rel="storageconnectionextensions"/>
    <address>host1.example.com</address>
    <certificate>
        <organization>exampleorg</organization>
        <subject>O=exampleorg,CN=XX.XX.XX.XX</subject>
    </certificate>
    <status>
        <state>up</state>
    </status>
    <external_status>
        <state>ok</state>
    </external_status>
    <cluster href="/api/clusters/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
    <port>54321</port>
    <type>rhel</type>
    <storage_manager priority="2">false</storage_manager>
    <spm>
        <priority>2</priority>
        <status>
            <state>none</state>
        </status>
    </spm>
    <version major="4" minor="17" build="20" revision="0" full_version="vdsm-4.17.20-0.el7ev"/>
    <power_management>
        <enabled>false</enabled>
        <pm_proxies/>
        <automatic_pm_enabled>true</automatic_pm_enabled>
        <kdump_detection>true</kdump_detection>
    </power_management>
    <ksm>
        <enabled>true</enabled>
    </ksm>
    <transparent_hugepages>
        <enabled>true</enabled>
    </transparent_hugepages>
    <iscsi>
        <initiator>iqn.2001-04.com.example:diskarrays-sn-a8675309</initiator>
    </iscsi>
    <ssh>
        <port>22</port>
        <fingerprint>00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00</fingerprint>
    </ssh>
    <cpu>
        <topology cores="2" sockets="1"/>
        <name>Intel(R) Xeon(R) CPU E5430 @ 2.66GHz</name>
        <speed>2656</speed>
    </cpu>
    <memory>12430868480</memory>
    <max_scheduling_memory>12026118144</max_scheduling_memory>
    <summary>
        <active>2</active>
        <migrating>0</migrating>
        <total>3</total>
    </summary>
    <protocol>stomp</protocol>
    <os type="RHEL">
        <version full_version="7.2-9.el7_2.1"/>
    </os>
    <libvirt_version major="1" minor="2" build="17" revision="0" full_version="libvirt-1.2.17-13.el7_2.2"/>
    <kdump_status>disabled</kdump_status>
    <selinux>
        <mode>enforcing</mode>
    </selinux>
    <auto_numa_status>disable</auto_numa_status>
    <numa_supported>false</numa_supported>
    <live_snapshot_support>true</live_snapshot_support>
    <update_available>false</update_available>
    <device_passthrough>
        <enabled>true</enabled>
    </device_passthrough>
</host>

14.3. ホストの JSON 表現

例14.2 ホストの JSON 表現

{
  "host" : [ {
    "address" : "198.51.100.0",
    "certificate" : {
      "organization" : "example.com",
      "subject" : "O=example.com,CN=192.0.2.0"
    },
    "status" : {
      "state" : "up"
    },
    "cluster" : {
      "href" : "/api/clusters/00000001-0001-0001-0001-0000000002fb",
      "id" : "00000001-0001-0001-0001-0000000002fb"
    },
    "port" : "54321",
    "type" : "rhel",
    "storage_manager" : {
      "value" : "true",
      "priority" : "5"
    },
    "spm" : {
      "priority" : "5"
    },
    "version" : {
      "major" : "4",
      "minor" : "16",
      "build" : "8",
      "revision" : "1",
      "full_version" : "vdsm-4.16.8.1-6.el6ev"
    },
    "hardware_information" : {
      "manufacturer" : "System Manufacturer To Be Filled By O.E.M.",
      "version" : "System Version To Be Filled By O.E.M.",
      "serial_number" : "Serial Number To Be Filled By O.E.M.",
      "product_name" : "Product Name To Be Filled By O.E.M.",
      "uuid" : "9fa0a1a2-a3a4-a5a6-a7a8-a9aaabacadae",
      "family" : "Family To Be Filled By O.E.M.",
      "supported_rng_sources" : {
        "source" : [ "RANDOM" ]
      }
    },
    "power_management" : {
      "enabled" : "false",
      "options" : {
        "option" : [ {
          "name" : "secure",
          "value" : "false"
        } ]
      },
      "automatic_pm_enabled" : "true",
      "kdump_detection" : "true",
      "type" : "apc"
    },
    "ksm" : {
      "enabled" : "false"
    },
    "transparent_hugepages" : {
      "enabled" : "true"
    },
    "iscsi" : {
      "initiator" : "iqn.1994-05.com.example:795610ff2632"
    },
    "ssh" : {
      "port" : "22",
      "fingerprint" : "77:27:38:25:8f:60:8d:93:9c:2c:b0:cb:5e:19:f4:53"
    },
    "cpu" : {
      "topology" : {
        "sockets" : "1",
        "cores" : "4",
        "threads" : "1"
      },
      "name" : "Intel(R) Core(TM)2 Quad CPU    Q9550  @ 2.83GHz",
      "speed" : 2833
    },
    "memory" : 2989490176,
    "max_scheduling_memory" : 2584739840,
    "summary" : {
      "active" : "0",
      "migrating" : "0",
      "total" : "0"
    },
    "protocol" : "stomp",
    "os" : {
      "version" : {
        "full_version" : "6Server - 6.6.0.2.el6"
      },
      "type" : "RHEL"
    },
    "libvirt_version" : {
      "major" : "0",
      "minor" : "10",
      "build" : "2",
      "revision" : "0",
      "full_version" : "libvirt-0.10.2-46.el6_6.2"
    },
    "kdump_status" : "disabled",
    "selinux" : {
      "mode" : "enforcing"
    },
    "auto_numa_status" : "unknown",
    "numa_supported" : "false",
    "live_snapshot_support" : "true",
    "actions" : {
      "link" : [ {
        "href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/fence",
        "rel" : "fence"
      }, {
        "href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/approve",
        "rel" : "approve"
      }, {
        "href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/forceselectspm",
        "rel" : "forceselectspm"
      }, {
        "href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/iscsilogin",
        "rel" : "iscsilogin"
      }, {
        "href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/iscsidiscover",
        "rel" : "iscsidiscover"
      }, {
        "href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/commitnetconfig",
        "rel" : "commitnetconfig"
      }, {
        "href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/deactivate",
        "rel" : "deactivate"
      }, {
        "href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/install",
        "rel" : "install"
      }, {
        "href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/activate",
        "rel" : "activate"
      } ]
    },
    "name" : "Host-07",
    "href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe",
    "id" : "ea7aa772-d2af-4a5c-9350-d86f005c93fe",
    "link" : [ {
      "href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/storage",
      "rel" : "storage"
    }, {
      "href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/nics",
      "rel" : "nics"
    }, {
      "href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/numanodes",
      "rel" : "numanodes"
    }, {
      "href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/tags",
      "rel" : "tags"
    }, {
      "href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/permissions",
      "rel" : "permissions"
    }, {
      "href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/statistics",
      "rel" : "statistics"
    }, {
      "href" : "/api/hosts/ea7aa772-d2af-4a5c-9350-d86f005c93fe/hooks",
      "rel" : "hooks"
    } ]
  } ]
}

14.4. 電源管理の要素

power_management 要素は、ホストのフェンシングに必要な電源管理設定を指定する機能をユーザーに提供します。power_management を設定する際には、特定のサブ要素が必要です。

表14.2 電源管理のオプション

要素タイプ説明プロパティー
type=フェンスデバイスコード有効なフェンスデバイスコードの一覧は capabilities コレクション内にあります。
enabledブール値: true または false電源管理設定が有効化または無効化されているかを示します。
address文字列ホストの IP アドレスまたはホスト名
username文字列電源管理の有効なユーザー名 
password文字列電源管理用の有効かつ堅固なパスワード 
options複合型選択した type= のフェンシングオプション。オプションの name=""value="" の文字列で指定します。 
agents複合型複数のフェンスが使用されている場合に、フェンスエージェントのオプションを指定します。order サブ要素を使用して、フェンスエージェントの優先順位付けをします。エージェントは、フェンスアクションが成功するまで、この順番に従い順次実行されます。同じ order が指定されるフェンスエージェントが複数ある場合には、同時に実行されます。他のサブ要素には、typeipuserpasswordoptions などがあります。 
automatic_pm_enabledブール値: true または false節電のためのホストの自動電源制御を切り替えます。この値を true に設定すると、クラスターの負荷が低下した場合にホストは自動的にオフになり、必要に応じて再度電源が投入されます。この値は、ユーザーが無効にしない限り、ホストの作成時に true に設定されます。 
kdump_detectionブール値: true または falseホストがシャットダウンする前に kdump が実行中かどうかを確認する設定を切り替えます。この値を true に指定すると、kdump プロセスの間はホストのシャットダウンは行われません。この値は、ユーザーによって無効にされない限り、ホストの電源管理が有効化されている場合は true に指定されます。 
options 要素には option サブ要素の一覧が必要です。各 option には nametype の属性が必要です。capabilities コレクションに定義されているように、特定のフェンシングタイプにしか使用できないオプションがあります。
ホストリソースに対して POST 要求を実行する場合には、新規のホストにオプションの power_management 設定を記載します。power_management 設定は PUT 要求を使用して更新することができます。

例14.3 ホストの電源管理設定の XML 表現

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
    <name>host1</name>
    ...
    <power_management type="ilo">
        <enabled>true</enabled>
        <address>192.168.1.107</address>
        <username>admin</username>
        <password>p@55w0Rd!</password>
        <options>
            <option name="secure" value="true"/>
            <option name="port" value="54345"/>
            <option name="slot" value="3"/>
        </options>
        <agents>
            <agent id="07f0b9ce-923a-4a96-a532-3c898fa8b6da">
                <type>apc</type>
                <order>1</order>
                <ip>192.168.1.111</ip>
                <user>example</user>
                <password>p@55w0rd!</password>
                <port>9</port>
                <options>
                    <option name="power_wait" value="5"/> 
                    <option name="secure" value="false"/>
                </options>
            </agent>
            <agent id="50c71ba2-8495-11e0-b931-e20e458819ed">
                <type>rsa</type>
                <order>2</order>
                <ip>192.168.1.112</ip>
                <user>example</user>
                <password>p@55w0rd!</password>
                <port>9</port>
                <options>
                    <option name="power_wait" value="5"/> 
                    <option name="secure" value="false"/>
                </options>
            </agent>
        </agents>
        <automatic_pm_enabled>true</automatic_pm_enabled>
        <kdump_detection>true</kdump_detection>
    </power_management>
    ...
</host>

14.5. メモリー管理の要素

API は、ホストのメモリー管理に 2 つの設定値を提供しています。
Kernel SamePage Merging (KSM) は、メモリーページへの参照を、複数の同じページからの単一のページ参照に削減します。これにより、メモリーの密度が最適化されます。KSM は ksm 要素を使用します。

例14.4 KSM メモリー管理の設定

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

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
    <ksm>true</ksm>
</host>
Transparent Hugepage support は、メモリーページを標準の 4KB の上限を上回るサイズに拡張します。これによりメモリーの消費が低減され、ホストのパフォーマンスが向上します。Transparent Hugepage サポートには transparent_hugepages 要素を使用します。

例14.5 Transparent Hugepage メモリー管理の設定

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

<host id="2ab5e1da-b726-4274-bbf7-0a42b16a0fc3"
  href="/api/hosts/2ab5e1da-b726-4274-bbf7-0a42b16a0fc3">
    <transparent_hugepages>true</transparent_hugepages>
</host>
Transparent Hugepage がサポートされているかどうかについては、capabilities コレクションで確認することができます。

14.6. メソッド

14.6.1. ホストの作成

新規ホストの作成には nameaddress、および root_password 要素が必要です。

例14.6 ホストの作成

POST /api/hosts HTTP/1.1
Accept: application/xml
Content-type: application/xml

<host>
    <name>host2</name>
    <address>host2.example.com</address>
    <root_password>p@55w0Rd!</root_password>
</host>
新規ホストの作成は Red Hat Enterprise Linux ホストを追加する場合のみに適用されます。Red Had Enterprise Virtualization Manager は Hypervisor ホストを自動検出し、使用の承認を要求します。
root_password 要素が記載されるのは、クライアント提供の最初の表現のみです。それ以降の要求で返される表現には表示されません。

14.6.2. ホストの更新

namedescriptionclusterpower_managementtransparent_hugepagesksm の各要素は、作成後に更新が可能です。

例14.7 ホストの更新

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

<host>
    <name>host3</name>
</host>

14.6.3. ホストの削除

ホストを削除するには DELETE 要求を実行する必要があります。

例14.8 ホストの削除

DELETE /api/hosts/00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content

14.7. サブコレクション

14.7.1. ホストのネットワークアタッチメントのサブコレクション

network_attachments サブコレクションは、ホストのネットワーク設定を表現します。各 network_attachment 要素は、ホストにアタッチされたネットワークを表現しており、この要素には以下の要素が含まれます。

表14.3 ホストのネットワークアタッチメントの要素

要素
タイプ
説明
プロパティー
network id=
GUID
ホストがアタッチされたネットワークへの参照
host_nic id=
GUID
ネットワークがアタッチされるホストネットワークインターフェースへの参照
ip_address_assignments
複合型
ネットワークの IP 設定。各ip_address_assignment には、assignment_methodip address= netmask= gateway= サブ要素が含まれています。
 
properties
複合型
ネットワークのカスタムプロパティーキーを定義します。各 property には name および value のサブ要素が含まれます。「ネットワークアタッチメントのカスタムプロパティー」を参照してください。
 
reported_configurations
複合型
読み取り専用のネットワークアタッチメントの設定プロパティー一覧。ネットワークアタッチメントがデータセンターの論理ネットワーク定義と同期されてない場合には、in_sync ブール値は false です。各 reported_configuration には nameexpected_valueactual_valuein_sync サブ要素が含まれます。
host id=
GUID
ホストへの参照

例14.9 ホスト上のネットワークアタッチメントの XML 表現

<network_attachment href="/api/hosts/00000000-0000-0000-0000-000000000000/networkattachments/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
    <network href="/api/networks/00000000-0000-0000-0000-000000000009" id="00000000-0000-0000-0000-000000000009"/>
    <host_nic href="/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
    <ip_address_assignments>
        <ip_address_assignment>
            <ip address="XX.XX.XX.XX" netmask="255.255.255.0" gateway="XX.XX.XX.XX"/>
            <assignment_method>dhcp</assignment_method>
        </ip_address_assignment>
    </ip_address_assignments>
    <reported_configurations>
        <in_sync>true</in_sync>
        <reported_configuration>
            <name>mtu</name>
            <expected_value>1500</expected_value>
            <actual_value>1500</actual_value>
            <in_sync>true</in_sync>
        </reported_configuration>
        <reported_configuration>
            <name>bridged</name>
            <expected_value>true</expected_value>
            <actual_value>true</actual_value>
            <in_sync>true</in_sync>
        </reported_configuration>
        <reported_configuration>
            <name>vlan</name>
            <in_sync>true</in_sync>
        </reported_configuration>
        <reported_configuration>
            <name>boot_protocol</name>
            <expected_value>DHCP</expected_value>
            <actual_value>DHCP</actual_value>
            <in_sync>true</in_sync>
        </reported_configuration>
    </reported_configurations>
    <host href="/api/hosts/f59a29cd-587d-48a3-b72a-db537eb21957" id="f59a29cd-587d-48a3-b72a-db537eb21957"/>
</network_attachment>
ホストをネットワークにアタッチする際には、id または name を指定した networkhost_nic 要素が必要です。host_nic ID は、未使用のネットワークインターフェースカードまたはボンぢングのいずれかを参照することができます。

例14.10 ホストへのネットワークのアタッチ

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

<network_attachment>
    <network id="00000000-0000-0000-0000-000000000000"/>
    <host_nic id="00000000-0000-0000-0000-000000000000"/>
</network_attachment>
host_nicip_address_assignmentsproperties 要素は、作成後に更新可能です。host_nic ID を変更すると、ネットワークが別のネットワークインターフェースカードに移動されます。

例14.11 ホストネットワークのアタッチメントの変更

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

<network_attachment>
    <host_nic id="00000000-0000-0000-0000-000000000000"/>
    <ip_address_assignments>
        <ip_address_assignment> 
            <ip address="XX.XX.XX.XX" netmask="255.255.255.0" gateway="XX.XX.XX.XX"/>
	    <assignment_method>static</assignment_method>
	</ip_address_assignment>
    </ip_address_assignments>
    <properties>
        <property>
	    <name>bridge_opts</name>
	    <value>
	        forward_delay=1500 group_fwd_mask=0x0 multicast_snooping=1
	    </value>
        </property>
    </properties>
</network_attachment>
ネットワークアタッチメントに対する DELETE 要求を使用して、ホストからネットワークをデタッチします。

例14.12 ホストからのネットワークのデタッチ

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

HTTP/1.1 204 No Content

重要

ネットワークアタッチメントの設定への変更は明示的にコミットする必要があります。「ネットワーク設定をコミットするアクション」を参照してください。

14.7.2. ホストのネットワークインターフェースのサブコレクション

14.7.2.1. ホストのネットワークインターフェースのサブコレクション

nics サブコレクションは、ホストの物理ネットワークインターフェースを表します。GET 要求に関する追加の情報は、All-Content: true ヘッダーを使用して取得することができます。表現内の各 host_nic 要素はネットワークインターフェースとして機能し、次の要素を含みます。

表14.4 ホストのネットワークインターフェースの要素

要素タイプ説明プロパティー
name文字列ホストのネットワークインターフェース名 (例: eth0) [a]
link rel="statistics"リレーションシップホストのネットワークインターフェース統計の statistics サブコレクションへのリンク
link rel="labels"リレーションシップホストのネットワークインターフェースラベルの labels サブコレクションへのリンク
link rel="networkattachments"リレーションシップホストのネットワークインターフェース設定の networkattachments サブコレクションへのリンク 
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複合型ボンディングインターフェースの optionsslave の各 NIC の一覧 [c]
bridgedブール値ネットワークのブリッジングステータスを定義します。ブリッジされたネットワークの場合は true に、ブリッジされていないネットワークの場合は false に設定します。 
[a] ボンディングインターフェースを追加する場合にのみ必要。その他のインターフェースは読み取り専用で、追加することはできません。
[b] ボンディングインターフェースを追加する場合にのみ必要。その他のインターフェースは読み取り専用で、追加することはできません。
[c] ボンディングインターフェースを追加する場合にのみ必要。その他のインターフェースは読み取り専用で、追加することはできません。

例14.13 ホスト上のネットワークインターフェースの 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 href="/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/statistics" rel="statistics"/>
    <link href="/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/labels" rel="labels"/>
    <link href="/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/networkattachments" rel="networkattachments"/>
    <host href="/api/hosts/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
    <network href="/api/networks/00000000-0000-0000-0000-000000000000" id="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>
            <option name="mode" value="4" type="Dynamic link aggregation (802.3ad)"/>
            <option name="miimon" value="100"/>
        </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>
</host_nic>
REST API では、ボンディングインターフェースのみが作成可能です。「ボンディングインターフェース」を参照してください。その他のネットワークインターフェースにはすべて、更新可能な networkipboot_protocol の要素が含まれます。
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"/>
    <boot_protocol>static</boot_protocol>
</host_nic>
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.2.2. ボンディングインターフェース

ボンディングインターフェースは bonding 要素を含む host_nic のリソースとして表します。

表14.5 ボンディングインターフェースのプロパティー

要素タイプ説明プロパティー
options複合型ボンディングインターフェースの option 要素の一覧。各 option にはプロパティーの namevalue の属性が含まれます。 [a]
slaves複合型ボンディングインターフェースのスレーブ host_nic id= 要素の一覧 [b]
[a] ボンディングインターフェースを追加する場合にのみ必要。その他のインターフェースは読み取り専用で、追加することはできません。
[b] ボンディングインターフェースを追加する場合にのみ必要。その他のインターフェースは読み取り専用で、追加することはできません。
API ユーザーは、host_nic (POST) の作成時、または host_nic (PUT) の更新時に新しいボンディングを作成します。id または name 要素のいずれかを使用して、スレーブ host_nic 要素を特定します。新しいネットワークインターフェースを追加するには、namenetwork 要素が必要です。id 属性または name 要素で network 要素を特定します。

例14.14 ボンディングインターフェースの作成

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

<host_nic>
    <name>bond4</name>
    <network id="00000000-0000-0000-0000-000000000000"/>
    <bonding>
        <slaves>
            <host_nic id="00000000-0000-0000-0000-000000000000"/>
            <host_nic id="00000000-0000-0000-0000-000000000000"/>
        </slaves>
    </bonding>
</host_nic>

重要

ボンディングインターフェースの有効な名前は、bond0bond1bond2, bond3bond4 のみです。

例14.15 ボンディングインターフェースの削除

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.2.3. ネットワークインターフェースのネットワークアタッチメント

14.7.2.3.1. ネットワークインターフェースのネットワークアタッチメント
ホストの各ネットワークインターフェースは、ネットワークインターフェースカードのネットワークアタッチメントを表現する network_attachments サブコレクションを公開します。各 network_attachment は、ネットワークインターフェースにアタッチされるネットワークを表現しており、このサブコレクションには以下の要素が含まれます。

表14.6 ホストネットワークインターフェースのネットワークアタッチメントの要素

要素
タイプ
説明
プロパティー
network id=
GUID
インターフェースがアタッチされたネットワークへの参照
host_nic id=
GUID
ホストのネットワークインターフェースへの参照
ip_address_assignments
複合型
ネットワークの IP 設定。各ip_address_assignment には、assignment_methodip address= netmask= gateway= サブ要素が含まれています。
 
properties
複合型
ネットワークのカスタムプロパティーキーを定義します。各 property には name および value のサブ要素が含まれます。
 
reported_configurations
複合型
読み取り専用のネットワークアタッチメントの設定プロパティー一覧。ネットワークアタッチメントにコミットされていないネットワーク設定が含まれている場合には、in_sync ブール値は false です。各 reported_configuration には nameexpected_valueactual_valuein_sync サブ要素が含まれます。

例14.16 ネットワークインターフェースカードのネットワークアタッチメントのXML 表現

<network_attachment href="/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000/networkattachments/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000">
    <network href="/api/networks/00000000-0000-0000-0000-000000000009" id="00000000-0000-0000-0000-000000000009"/>
    <host_nic href="/api/hosts/00000000-0000-0000-0000-000000000000/nics/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
    <ip_address_assignments>
        <ip_address_assignment>
            <ip address="XX.XX.XX.XX" netmask="255.255.255.0" gateway="XX.XX.XX.XX"/>
            <assignment_method>static</assignment_method>
        </ip_address_assignment>
    </ip_address_assignments>
    <reported_configurations>
        <in_sync>true</in_sync>
        <reported_configuration>
            <name>mtu</name>
            <expected_value>1500</expected_value>
            <actual_value>1500</actual_value>
            <in_sync>true</in_sync>
        </reported_configuration>
        <reported_configuration>
            <name>bridged</name>
            <expected_value>true</expected_value>
            <actual_value>true</actual_value>
            <in_sync>true</in_sync>
        </reported_configuration>
        <reported_configuration>
            <name>vlan</name>
            <in_sync>true</in_sync>
        </reported_configuration>
        <reported_configuration>
            <name>boot_protocol</name>
            <expected_value>DHCP</expected_value>
            <actual_value>DHCP</actual_value>
            <in_sync>true</in_sync>
        </reported_configuration>
    </reported_configurations>
</network_attachment>
ネットワークインターフェースカードにネットワークをアタッチする場合は、id または name のいずれかと、network 要素が必要です。

例14.17 ホストのネットワークインターフェースカードに対するネットワークのアタッチ

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

<networkattachment>
    <network id="00000000-0000-0000-0000-000000000000"/>
</networkattachment>
ip_address_assignmentsproperties 要素は、作成後に更新可能です。

例14.18 ネットワークアタッチメントの変更

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

<networkattachment>
    <ip_address_assignments>
        <ip_address_assignment> 
            <ip address="XX.XX.XX.XX" netmask="255.255.255.0" gateway="XX.XX.XX.XX"/>
	    <assignment_method>static</assignment_method>
	</ip_address_assignment>
    </ip_address_assignments>
</networkattachment>
ネットワークアタッチメントに対する DELETE 要求を使用して、ネットワークインターフェースからネットワークをデタッチします。

例14.19 ホストネットワークインターフェースカードからのネットワークのデタッチ

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

HTTP/1.1 204 No Content

重要

ネットワークアタッチメントの設定への変更は明示的にコミットする必要があります。「ネットワーク設定をコミットするアクション」を参照してください。
14.7.2.3.2. ネットワークアタッチメントのカスタムプロパティー
ホストのネットワークアタッチメントにカスタムプロパティーを適用することができます。各プロパティーには namevalue のサブ要素が含まれます。カスタムプロパティーを変更するには、ネットワークアタッチメントに対して PUT 要求を実行するか、setupnetworks アクションを使用して POST 要求を実行してください。

表14.7 ホストネットワークインターフェースのカスタムブリッジオプションの要素

要素タイプ説明
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.20 ネットワークアタッチメントのプロパティーサブコレクションの XML 表現

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

14.7.2.4. ネットワークインターフェースのラベル

ホストのネットワークインターフェースカードにラベルをつけて、同じラベルが付けられた論理ネットワークとネットワークインターフェースカードを自動的に関連付けることができます。

例14.21 ネットワークインターフェースカードへのラベルのアタッチ

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" />
物理ホストのネットワークインターフェースカードからラベルを削除するには DELETE 要求が必要です。

例14.22 ネットワークインターフェースカードからのラベルの削除

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

HTTP/1.1 204 No Content

14.7.2.5. ネットワークインターフェースの統計

各ホストのネットワークインタフェースは、ホストのネットワークインターフェースの統計の statistics サブコレクションを公開します。各 statistic には、次のような要素が含まれます。

表14.8 ホストのネットワークインターフェース統計の要素

要素タイプ説明
name文字列統計エントリーの一意識別子
description文字列プレーンテキストで記述された統計の説明
unit文字列統計値測定の単位またはレート
typeGAUGE または COUNTER統計測定値のタイプ
values type=INTEGER または DECIMALその後に続く統計値のデータタイプ
value複合型datum を含むデータセット
datumvalues type を参照value に含まれるデータの 1 つ
host_nic id=リレーションシップ格納している host_nic リソースとのリレーションシップ
次の表には、ホスト上のネットワークインターフェースの統計タイプをまとめています。

表14.9 ホストの NIC 統計タイプ

名前
説明
data.current.rx
データの受信速度 (ビット毎秒)
data.current.tx
データの送信速度 (ビット毎秒)
data.total.rx
合計受信データ
data.total.tx
合計送信データ
errors.total.rx
データ受信でのエラーの合計数
errors.total.tx
データ送信でのエラーの合計数

例14.23 ホストのネットワークインターフェース統計サブコレクションの XML 表現

<statistics>
    <statistic id="00000000-0000-0000-0000-000000000000"
      href="/api/hosts/00000000-0000-0000-0000-000000000000/nics/
      00000000-0000-0000-0000-000000000000/statistics/
      00000000-0000-0000-0000-000000000000">
        <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="00000000-0000-0000-0000-000000000000"
          href="/api/hosts/00000000-0000-0000-0000-000000000000/nics/
          00000000-0000-0000-0000-000000000000"/>
    </statistic>
    ...
</statistics>

注記

上記の statistics サブコレクションは読み取り専用です。

14.7.3. ストレージのサブコレクション

storage サブコレクションは、ホストで使用可能な iSCSI および FCP ストレージの表現の一覧を提供します。このストレージは、ストレージドメインを作成する際に使用します。
サブコレクション内の各 storage の表現は SCSI LUN を表します。

例14.24 ホスト上のストレージサブコレクションの 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 は、本セクションに記載した時点では試験段階にあり、今後変更される可能性があるため、後方互換性に関する記載内容は適用されません。

14.7.4. ホスト NUMA ノードのサブコレクション

14.7.4.1. NUMA ノードのサブコレクション

numanodes サブコレクションは、ホストの NUMA トポロジーを表現します。サブコレクションの各 host_numa_node 要素は、NUMA ノードを表現します。

例14.25 ホスト上にある NUMA ノードのサブコレクションの 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.4.2. NUMA ノードの統計

各ホスト NUMA ノードは、NUMA ノードの統計の statistics サブコレクションを公開します。各 statistics には、次のような要素が含まれます。

表14.10 ホストの NUMA ノード統計の要素

要素タイプ説明
name文字列統計エントリーの一意識別子
description文字列プレーンテキストで記述された統計の説明
unit文字列統計値測定の単位またはレート
typeGAUGE または COUNTER統計測定値のタイプ
values type=INTEGER または DECIMALその後に続く統計値のデータタイプ
value複合型datum を含むデータセット
datumvalues type を参照value に含まれるデータの 1 つ
host_numa_node id=リレーションシップ格納している vm リソースとのリレーションシップ
以下の表には、ホストの NUMA ノードの統計タイプをまとめています。

表14.11 ホストの NUMA ノード統計

名前説明
memory.totalホスト上のメモリー合計 (バイト単位)
memory.usedNUMA ノード上の使用メモリー容量 (バイト単位)
memory.freeNUMA ノード上の空きメモリー容量 (バイト単位)
cpu.current.userユーザーの CPU 使用率
cpu.current.systemシステムの CPU 使用率
cpu.current.idleアイドル時の CPU 使用率

例14.26 ホスト 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.5. ホスト統計のサブコレクション

14.7.5.1. ホスト統計のサブコレクション

各ホストリソースは、ホスト固有の統計の statistics サブコレクションを公開します。各 statistics には、次のような要素が含まれます。

表14.12 VNIC プロファイルの要素

要素タイプ説明
name文字列統計エントリーの一意識別子
description文字列プレーンテキストで記述された統計の説明
unit文字列統計値測定の単位またはレート
typeGAUGE または COUNTER統計測定値のタイプ
values type=INTEGER または DECIMALその後に続く統計値のデータタイプ
value複合型datum を含むデータセット
datumvalues type を参照value に含まれるデータの 1 つ
host id=リレーションシップ格納している host リソースとのリレーションシップ
次の表には、ホストの統計タイプをまとめています。

表14.13 ホストの統計タイプ

名前
説明
memory.total
ホスト上のメモリー合計 (バイト単位)
memory.used
ホスト上の使用メモリー容量 (バイト単位)
memory.free
ホスト上の空きメモリー容量 (バイト単位)
memory.shared
ホストで共有されるメモリー容量 (バイト単位)
memory.buffers
I/O バッファー (バイト単位)
memory.cached
OS キャッシュ (バイト単位)
swap.total
ホスト上の swap メモリー容量 (バイト単位)
swap.free
ホスト上の空き swap メモリー容量 (バイト単位)
swap.used
ホスト上の使用 swap メモリー容量 (バイト単位)
swap.cached
ホストのメモリー内にもキャッシュされている swap メモリー容量 (バイト単位)
ksm.cpu.current
Kernel SamePage Merging (KSM) の CPU 使用率
cpu.current.user
ユーザーの CPU 使用率
cpu.current.system
システムの CPU 使用率
cpu.current.idle
アイドル時の CPU 使用率
cpu.load.avg.5m
5 分あたりの CPU 負荷平均

例14.27 ホストの統計サブコレクションの 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 サブコレクションは読み取り専用です。

14.8. アクション

14.8.1. VDSM をインストールするアクション

ホストに VDSM および関連ソフトウェアをインストールします。ホストのタイプは、このアクションの追加パラメーターを定義します。
  • Red Hat Enterprise Linux ホスト: このホストタイプには、ホストの root ユーザー用のパスワードを参照する root_password 要素が必要です。
  • Red Hat Enterprise Virtualization Hypervisor ホスト: このホストタイプには、Red Hat Enterprise Virtualization Manager サーバーに格納されている ISO ファイルを参照する image 要素が必要です。

例14.28 Red Hat Enterprise Linux ホストに VDSM をインストールするアクション

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

<action>
    <root_password>p@55w0Rd!</root_password>
</action>

例14.29 Red Hat Enterprise Virtualization Hypervisor ホストに VDSM をインストールするアクション

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

<action>
    <image>/usr/share/rhev-hypervisor/rhev-hypervisor.iso</image>
</action>

14.8.2. ホストをアクティブ化するアクション

仮想マシンの実行などに使用するホストをアクティブ化します。

例14.30 ホストをアクティブ化するアクション

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

<action/>

14.8.3. ホストネットワークの設定アクション

ホストで複数のネットワーク設定を構成します。setupnetworks アクションは、別のネットワークインターフェースにネットワークを移動するなど複雑なネットワーク設定に使用することができます。

例14.31 ホストのネットワーク設定を編集するアクション

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

<action>
    <modified_network_attachments>
        <network_attachment id="41561e1c-c653-4b45-b9c9-126630e8e3b9">
            <host_nic id="857a46d3-5f64-68bd-f456-c70de5b2d569"/>
        </network_attachment<
        <network_attachment id="3c3f442f-948b-4cdc-9a48-89bb0593cfbd">
            <network id="00000000-0000-0000-0000-000000000010"/>
            <ip address="10.35.1.247" netmask="255.255.254.0" gateway="10.35.1.254"/>
	    <properties>
		<property>
		    <name>bridge_opts</name>
		    <value>
			forward_delay=1500 group_fwd_mask=0x0 multicast_snooping=1
		    </value>
		</property>
	    </properties>
        </network_attachment>
    </modified_network_attachments>
    <synchronized_network_attachments>
        <network_attachment id="3c3f442f-948b-4cdc-9a48-89bb0593cfbd">
    </synchronized_network_attachments> 
    <removed_network_attachments>
        <network_attachment id="7f456dae-c57f-35d5-55a4-20b74dc53af9">
    </removed_network_attachments>
    <modified_bonds>
        <host_nic id="a56b212d-2bc4-4120-9136-53be6cacb39a">
	    <bonding>
		<slaves>
		    <host_nic id="75ac21f7-4aa3-405a-a022-341e5f525b85">
		    <host_nic id="f3dda04c-1233-41af-a111-74327b876487">
		</slaves>
	    </bonding>
        </host_nic>
    </modified_bonds>
    <removed_bonds>
        <host_nic id="36ab5c7f-647a-bc64-f5e7-ba5d74f8e4ba">
    </removed_bonds>
    <modified_labels>
        <label id="Label002">
	    <host_nic id="857a46d3-5f64-68bd-f456-c70de5b2d569"/>
        </label>
        <label>
	    <host_nic id="a56b212d-2bc4-4120-9136-53be6cacb39a"/>
	    <label id="Label003/>
        </label>
    </modified_labels>  
    <removed_labels>
        <label id="Label001">
    </removed_labels>
    <checkConnectivity>true</checkConnectivity>
    <connectivityTimeout>60</connectivityTimeout>
</action>
このアクションは、標準の NIC 要素で、指定した全ホストネットワークリソースを更新します。要求には、以下の表に記載の追加要素が含まれます。

表14.14 複数のホストネットワークインターフェースセットアップに対する要素

要素タイプ説明
modified_bonds複合型ボンディングを作成または更新します。各 host_nic 要素には、標準の bonding 要素が含まれます。「ボンディングインターフェース」を参照してください。
removed_bonds複合型削除するボンディングの ID 一覧
modified_network_attachments複合型ホスト上のネットワークアタッチメントを追加または更新します。各 network_attachment 要素には標準ホストの network_attachment 要素が含まれます。「ホストのネットワークアタッチメントのサブコレクション」を参照してください。host_nic ID を変更すると、異なるネットワークインターフェースカードにネットワークが移動されます。
synchronized_network_attachments複合型データセンターの論理ネットワーク定義と同期する必要のあるネットワークアタッチメントの ID 一覧
removed_network_attachments複合型削除するネットワークアタッチメントの ID 一覧
modified_labels複合型ラベルを作成または変更します。各 label 要素には、名前または ID で識別される label id (ラベルの作成時) と host_nicが含まれます。host_nic ID は、ラベルを異なるネットワークインターフェースカードに移動します。
removed_labels複合型削除するラベルの ID 一覧
checkConnectivityブール値ホストと Red Hat Enterprise Virtualization Manager の間の接続を検証するには、true に設定します。接続が切断されると、Red Hat Enterprise Virtualization Manager は設定を元に戻します。
connectivityTimeout整数接続の切断のタイムアウトを定義します。

14.8.4. ホストをフェンスするアクション

API ユーザーがホストの電源管理デバイスを制御するには、fence アクションを使用します。使用可能な fence_type オプションは、capabilities に記載されています。

例14.32 ホストをフェンスするアクション

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

<action>
    <fence_type>start</fence_type>
</action>

14.8.5. ホストを非アクティブ化するアクション

メンテナンスタスクを実行するために、ホストを非アクティブ化します。

例14.33 ホストを非アクティブ化するアクション

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

<action/>

14.8.6. ホストを承認するアクション

事前にインストール済みの Red Hat Enterprise Virtualization Hypervisor ホストを承認して、仮想化環境で使用できるようにします。またこのアクションは、オプションの cluster 要素を受け入れ、ホストのターゲットクラスターを定義します。

例14.34 ホストを承認するアクション

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

<action>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"/>
</action>

14.8.7. ホストの iSCSI ログインのアクション

iscsilogin のアクションは、ホストが iSCSI ターゲットにログインできるようにします。ターゲットにログインすると、格納されている LUN が host_storage コレクションで使用できるようになります

例14.35 iSCSI ターゲットへのホストのログインを可能にするアクション

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


<action>
    <iscsi>
        <address>mysan.example.com</address>
        <target>iqn.2009-08.com.example:mysan.foobar</target>
        <username>jimmy</username>
        <password>s3kr37</password>
    </iscsi>
</action>

14.8.8. ホストの iSCSI 検出のアクション

iscsidiscover のアクションは、iSCSI ポータルに対してターゲット一覧の検索クエリーを実行できるようにします。

例14.36 iSCSI ポータルに対してターゲット一覧のクエリーを実行するアクション

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

<action>
    <iscsi>
        <address>mysan.example.com</address>
        <port>3260</port>
    </iscsi>
</action>

14.8.9. ネットワーク設定をコミットするアクション

API ユーザーがネットワーク設定をコミットすることにより、ホストネットワークインターフェースのアタッチ/デタッチやボンディングインターフェースの作成/削除が永続化されます。

例14.37 ネットワーク設定をコミットするアクション

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

<action/>

重要

ネットワーク設定のコミットは、設定の変更によってホストの接続が切断されていない状態であることを Manager が確認した上でのみ行います。ホストの接続が切断されている場合には、ホストを再起動する必要があり、ネットワーク設定の変更は自動的に元の状態に戻ります。

14.8.10. SPM の設定

ホストを Storage Pool Manager (SPM) として手動で設定します。

例14.38 ホストを SPM として設定するためのアクション

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

<action/>

第15章 仮想マシン

15.1. 仮想マシンの要素

vms コレクションは、Red Hat Enterprise Virtualization 環境内の仮想マシンに関する情報を提供します。API ユーザーは、エントリーポイント URL から取得した rel="vms" リンクでこの情報にアクセスします。
GET 要求に関する追加の情報は、All-Content: true ヘッダーを使用して取得することができます。
以下の表には、仮想マシンリソースの表現に含まれる特定の要素をまとめています。

表15.1 仮想マシンの要素

要素タイプ説明プロパティー
link rel="applications"リレーションシップ仮想マシンリソースの applications サブコレクションへのリンク。仮想マシンにインストールされているアプリケーションを表示します。 
link rel="disks"リレーションシップ仮想マシンリソースの disks サブコレクションへのリンク 
link rel="nics"リレーションシップ仮想マシンリソースの nics サブコレクションへのリンク 
link rel="numanodes"リレーションシップ仮想マシンリソースの numanodes サブコレクョンへのリンク 
link rel="cdroms"リレーションシップ仮想マシンリソースの cdroms サブコレクションへのリンク 
link rel="snapshots"リレーションシップ仮想マシンリソースの snapshots サブコレクションへのリンク 
link rel="tags"リレーションシップ仮想マシンリソースの tags サブコレクションへのリンク 
link rel="permissions"リレーションシップ仮想マシンパーミッションの permissions サブコレクションへのリンク 
link rel="statistics"リレーションシップ仮想マシンリソースの statistics サブコレクションへのリンク
link rel="reporteddevices"
リレーションシップ
仮想マシンリソースの tags サブコレクションへのリンク
 
link rel="watchdogs"
リレーションシップ
仮想マシンリソースの watchdogs サブコレクションへのリンク
 
link rel="sessions"
リレーションシップ
仮想マシンリソースの sessions サブコレクションへのリンク
 
type列挙型仮想マシンのタイプ。列挙値の一覧は capabilities に記載されています。
status下記参照仮想マシンのステータス
memory整数ゲストに割り当てられたメモリーの容量 (バイト単位)
cpu複合型
仮想マシンの CPU の詳細を定義します。topology サブ要素は、ゲストが使用できる論理 sockets の数および 1 ソケットあたりのコア数を指定します。仮想マシンが使用可能なコア数の合計は、ソケット数に 1 ソケットあたりの cores 数を乗算した値に相当します。
cputune サブ要素は、一連の vcpupin 要素を使用して仮想 CPU を物理ホストの CPU にマップします。各 vcpupin 要素には仮想 CPU の属性 (vcpu) および使用する物理 ホストの CPU を定義する属性 (cpuset) が含まれます。cpuset は、単一の CPU (cpuset="0")、複数の CPU (cpuset="0,2")、CPU 範囲 (cpuset="0-3")、除外条件付きの CPU 範囲 (cpuset="0-3,^2") のいずれかに指定します。
cpu_mode サブ要素は、仮想 CPU とホスト CPU の関係の密接度を定義します。これには、custom (モードが指定されていない場合のデフォルト)、host_model (libvirt が最も適切に理解できるようにホスト CPU をコピーする)、host_passthrough (libvirt が認識できなくてもホストの全アスペクトを渡す) の 3 つの値があります。ただし、host_passthrough を指定すると仮想マシンの移行ができなくなります。
os type=文字列 (例: RHEL5WindowsXP)ゲストのオペレーティングシステムのタイプ
os boot dev=列挙型boot 要素の dev 属性によって記述される起動デバイスの一覧。列挙値の一覧は capabilities に記載されています。
os kernel文字列仮想マシンの起動用に設定されたカーネルイメージへのパス。このオプションは BIOS ブートローダーを介さない、Linux カーネルの直接のブートをサポートしています。
os initrd文字列以前に指定したカーネルで使用される initrd イメージへのパス。このオプションは BIOS ブートローダーを介さない、Linux カーネルの直接のブートをサポートしています。
os cmdline文字列定義されたカーネルも使用されるカーネルコマンドラインパラメーターの文字列。このオプションは BIOS ブートローダーを介さない、Linux カーネルの直接ブートをサポートしています。
high_availability複合型仮想マシンまたはそのホストがクラッシュした際に、その仮想マシンを自動的に再起動するようにする場合は、enabledtrue に設定します。priority 要素は、仮想マシンの再起動の順序を制御します。 
display複合型
ディスプレイの type (vnc または spice)、ポート、および monitors 数。allow_reconnect のブール値は、クライアントがディスプレイを介して再接続可能かどうかを指定します。
smartcard_enabled サブ要素は、クライアントに接続されたスマートカードがパススルーされるかどうかを指定するブール値 (true または false) です。デフォルトは false です。
 
cluster id=GUID仮想マシンのホストクラスターへの参照
template id=GUIDそのマシンのベースとなっているテンプレートへの参照
domain id=GUID仮想マシンのドメインへの参照
start_timexsd:dateTime の形式: YYYY-MM-DDThh:mm:ssその仮想マシンを起動した日付と時刻
stop_timexsd:dateTime の形式: YYYY-MM-DDThh:mm:ssその仮想マシンを終了した日付と時刻
creation_timexsd:dateTime の形式: YYYY-MM-DDThh:mm:ssその仮想マシンを作成した日付と時刻
originrhevovirtvmwarexen のいずれかその仮想マシンの元となったシステム
statelessブール値: true または false仮想マシンがステートレスの場合は true に指定します。ステートレスの仮想マシンには、ブート時に作成されたスナップショットが含まれ、シャットダウン時には削除されます。これは、再起動後に状態が永続化されないことを意味します。 
delete_protectedブール値: true または falsetrue に設定した場合には、仮想マシンは削除できません。 
sso文字列仮想マシンのシングルサインオンメソッドへの参照。ip 属性を使用する method 要素が含まれます。 
placement_policy複合型仮想マシン移行の配置ポリシーを設定します。デフォルトの host=affinity (migratableuser_migratablepinned のいずれか) が必要です。host 要素を空白にすると、優先ホストなしの設定になります。複数の host 要素を使用して、クラスター内の優先ホストのサブセットを指定します。 
memory_policy複合型仮想マシンのメモリーポリシーを設定します。仮想マシンが稼働するためのホスト上の最小限の guaranteed メモリー容量を定義します。 
quota id=GUID仮想マシンのクォータを設定します。 
custom_properties複合型パラメーターとしてカスタムのスクリプトに渡される、ユーザー定義の環境変数セット。各 custom_property には name および value の属性が含まれます。列挙値の一覧は capabilities に記載されています。 
usb複合型仮想マシンの USB ポリシーを定義します。enabled 要素をブール値に設定し、type 要素を native または legacy に設定する必要があります。 
migration_downtime整数ライブマイグレーション中に仮想マシンを停止状態にできる最大時間をミリ秒単位で示します。値が 0 の場合には、VDSM のデフォルトが使用されることになります。 
cpu_profile id=GUID仮想マシンの CPU プロファイルへの参照 
next_run_configurationブール値: true または false次回の再起動時に仮想マシンの設定の変更が適用されるには、true に設定します。 
numa_tune_mode文字列ホスト NUMA ノードのメモリー割り当てモードへ (interleavestrictpreferred のいずれか) の参照  
guest_info複合型ゲストクライアントの情報への参照。address= 属性を使用する ip 要素が含まれます。
vmpool複合型仮想マシンプールへの参照。この要素が表示されるのは、仮想マシンがプールの一部である場合のみです。
timezonetz データベース形式: Area/LocationWindows 仮想マシンに設定する Sysrprep タイムゾーン 
domain複合型Windows 仮想マシンのテンプレート用の Sysprep ドメイン設定。domains コレクションからの name が必要です。 
initialization複合型
Linux ベースの仮想マシンの場合は Cloud-Init を、Windows ベースの仮想マシンには Sysprep を使用して、起動時に仮想マシンに適用する値の一覧を定義します。

Cloud-Init

  • host_name: 仮想マシンのホスト名
  • timezone: 仮想マシンのタイムゾーン
  • user_name: 仮想マシンのユーザー名
  • root_password: ユーザーのパスワード、またはユーザーが指定されていない場合は root パスワード
  • authorized_ssh_keys: 仮想マシンの認証済みキーファイルに追加する SSH キー。改行区切りで各 SSH を指定することで、複数の SSH キーを入力することができます。
  • regenerate_ssh_keys: 仮想マシンの SSH キーを再生成するかどうか。許容値は true または false です。
  • dns_servers: スペース区切りの DNS サーバーの一覧
  • dns_search: スペース区切りの DNS 検索ドメイン一覧
  • nic_configurations: 仮想マシンのネットワークインターフェースコントローラーを定義します。ネットワークインターフェースコントローラーは、このコレクション内で nic_configuration オブジェクトとして定義され、それぞれnameipboot_protocolon_boot を指定します。
  • custom_script: 起動時に仮想マシンで実行するカスタムスクリプト

Sysprep

  • host_name: 仮想マシンのホスト名
  • domain: 仮想マシンがメンバーのドメイン
  • authorized_ssh_keys: 仮想マシンの認証済みキーファイルに追加する SSH キー。改行区切りで各 SSH を指定することで、複数の SSH キーを入力することができます。
  • regenerate_ssh_keys: 仮想マシンの SSH キーを再生成するかどうか。許容値は true または false です。
  • timezone: 仮想マシンのタイムゾーン
  • root_password: 仮想マシンの管理ユーザーのパスワード
  • custom_script: 起動時に仮想マシンで実行するカスタムスクリプト
  • input_locale: ユーザー入力のロケール
  • ui_language: ボタンやメニューなどのユーザーインターフェースの要素に使用する言語
  • system_locale: システム全体のロケール
  • user_locale: ユーザーのロケール
  • active_directory_ou: 仮想マシンが属する Active Directory ドメインの組織単位
  • org_name: 仮想マシンが属する組織名
payloads複合型
ブート時に仮想マシンにコンテンツを提供する payload 要素のセットを定義します。各 payload には type 属性 (cdrom または floppy) と file 要素が必要です。各 file 要素には、ファイルの名前と場所を指定する name 要素と、ファイルに渡すコンテンツを定義する content 要素が必要です。
payloads 要素は、cloud-init 機能によって使用されます。cloud-init を使用して仮想マシンを設定する場合には、type 属性が cd-rom に指定され、設定パラメーターを仮想マシンに渡す openstack/latest/meta_data.jsonopenstack/latest/user_dataの 2 つの file サブ要素とともに自動的に作成されます。
 
status には、以下のいずれかの列挙値が含まれます: unassigneddownuppowering_uppowered_downpausedmigrating_frommigrating_tounknownnot_respondingwait_for_launchreboot_in_progresssaving_staterestoring_statesuspendedimage_illegalimage_lockedpowering_down。これらのステータスは capabilities の下の vm_states に記載されています。

15.2. 仮想マシンの XML 表現

例15.1 仮想マシンの XML 表現

<vm id="70b4d9a7-4f73-4def-89ca-24fc5f60e01a"
  href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a">
    <actions>
        <link rel="move"
	  href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/move"/>
        <link rel="ticket"
	  href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/ticket"/>
        <link rel="reboot"
	  href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/reboot"/>
        <link rel="undo_snapshot"
	  href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/undo_snapshot"/>
        <link rel="commit_snapshot"
	  href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/commit_snapshot"/>
        <link rel="preview_snapshot"
	  href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/preview_snapshot"/>
        <link rel="logon"
	  href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/logon"/>
        <link rel="cancelmigration"
	  href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/cancelmigration"/>
        <link rel="maintenance"
	  href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/maintenance"/>
        <link rel="clone"
	  href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/clone"/>
        <link rel="migrate"
	  href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/migrate"/>
        <link rel="detach"
	  href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/detach"/>
        <link rel="export"
	  href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/export"/>
        <link rel="shutdown"
	  href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/shutdown"/>
        <link rel="start"
	  href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/start"/>
        <link rel="stop"
	  href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/stop"/>
        <link rel="suspend"
	  href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/suspend"/>
    </actions>
    <name>VM_01</name>
    <description>Testing Virtual Machine</description>
    <link rel="applications"
      href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/applications"/>
    <link rel="disks"
      href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/disks"/>
    <link rel="nics"
      href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/nics"/>
    <link rel="numanodes"
      href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/numanodes"/>
    <link rel="cdroms"
      href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/cdroms"/>
    <link rel="snapshots"
      href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/snapshots"/>
    <link rel="tags"
      href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/tags"/>
    <link rel="permissions"
      href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/permissions"/>
    <link rel="statistics"
      href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/statistics"/>
    <link rel="reporteddevices"
      href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/reporteddevices"/>
    <link rel="watchdogs"
      href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/watchdogs"/>
    <link rel="sessions"
      href="/api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a/sessions"/>
    <type>server</type>
    <status>
        <state>down</state>
    </status>
    <memory>1073741824</memory>
    <cpu>
        <topology sockets="1" cores="1"/>
        <architecture>X86_64</architecture>
    </cpu>
    <cpu_shares>0</cpu_shares>
    <bios>
        <boot_menu>
            <enabled>false</enabled>
        </boot_menu>
    </bios>
    <os type="other">
        <boot dev="hd"/>
    </os>
    <high_availability>
        <enabled>false</enabled>
        <priority>1</priority>
    </high_availability>
    <display>
        <type>spice</type>
        <monitors>1</monitors>
        <single_qxl_pci>false</single_qxl_pci>
        <allow_override>true</allow_override>
        <smartcard_enabled>false</smartcard_enabled>
        <file_transfer_enabled>true</file_transfer_enabled>
        <copy_paste_enabled>true</copy_paste_enabled>
    </display>
    <cluster href="/api/clusters/00000001-0001-0001-0001-0000000002fb" id="00000001-0001-0001-0001-0000000002fb"/>
    <template href="/api/templates/00000000-0000-0000-0000-000000000000" id="00000000-0000-0000-0000-000000000000"/>
    <stop_time>2014-12-03T14:25:45.588+10:00</stop_time>
    <creation_time>2014-12-03T14:25:45.535+10:00</creation_time>
    <origin>ovirt</origin>
    <stateless>false</stateless>
    <delete_protected>false</delete_protected>
    <sso>
        <methods>
            <method id="GUEST_AGENT"/>
        </methods>
    </sso>
    <timezone>Etc/GMT</timezone>
    <placement_policy>
        <affinity>migratable</affinity>
    </placement_policy>
    <memory_policy>
        <guaranteed>1073741824</guaranteed>
    </memory_policy>
    <usb>
        <enabled>false</enabled>
    </usb>
    <migration_downtime>-1</migration_downtime>
    <cpu_profile href="/api/cpuprofiles/0000001a-001a-001a-001a-0000000002e3" id="0000001a-001a-001a-001a-0000000002e3"/>
    <next_run_configuration_exists>false</next_run_configuration_exists>
    <numa_tune_mode>interleave</numa_tune_mode>
</vm>

15.3. 仮想マシンの追加 OVF データの XML 表現

仮想マシンの GET 要求で All-Content: true ヘッダーを使用して、仮想マシンの表現に追加の OVF データを含めます。
Accept ヘッダーを空欄にした場合には、デフォルトで application/xml となり、XML タグに影響しないようにデータは HTML エンティティーで表現されます。Accept: application/json ヘッダーを指定すると、データは標準の XML タグで返されます。以下の表現の例は、標準のブロックフォーマットを編集して、より読みやすい書式で示しています。

例15.2 仮想マシンの追加の OVF データの XML 表現

GET /api/vms/70b4d9a7-4f73-4def-89ca-24fc5f60e01a HTTP/1.1
All-Content: true
	
<?xml version='1.0' encoding='UTF-8'?> 
<ovf:Envelope xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1/" 
  xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ResourceAllocationSettingData" 
  xmlns:vssd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_VirtualSystemSettingData" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  ovf:version="3.5.0.0"> 
  <References/> 
  <Section xsi:type="ovf:NetworkSection_Type"> 
    <Info>List of networks</Info> 
    <Network ovf:name="Network 1"/> 
  </Section> 
  <Section xsi:type="ovf:DiskSection_Type"> 
    <Info>List of Virtual Disks</Info> 
  </Section> 
  <Content ovf:id="out" xsi:type="ovf:VirtualSystem_Type"> 
    <CreationDate>2014/12/03 04:25:45</CreationDate> 
    <ExportDate>2015/02/09 14:12:24</ExportDate> 
    <DeleteProtected>false</DeleteProtected> 
    <SsoMethod>guest_agent</SsoMethod> 
    <IsSmartcardEnabled>false</IsSmartcardEnabled> 
    <TimeZone>Etc/GMT</TimeZone> 
    <default_boot_sequence>0</default_boot_sequence> 
    <Generation>1</Generation> 
    <VmType>1</VmType> 
    <MinAllocatedMem>1024</MinAllocatedMem> 
    <IsStateless>false</IsStateless> 
    <IsRunAndPause>false</IsRunAndPause> 
    <AutoStartup>false</AutoStartup> 
    <Priority>1</Priority> 
    <CreatedByUserId>fdfc627c-d875-11e0-90f0-83df133b58cc</CreatedByUserId> 
    <IsBootMenuEnabled>false</IsBootMenuEnabled> 
    <IsSpiceFileTransferEnabled>true</IsSpiceFileTransferEnabled> 
    <IsSpiceCopyPasteEnabled>true</IsSpiceCopyPasteEnabled> 
    <Name>VM_export</Name> 
    <TemplateId>00000000-0000-0000-0000-000000000000</TemplateId> 
    <TemplateName>Blank</TemplateName> 
    <IsInitilized>false</IsInitilized> 
    <Origin>3</Origin> 
    <DefaultDisplayType>1</DefaultDisplayType> 
    <TrustedService>false</TrustedService> 
    <OriginalTemplateId>00000000-0000-0000-0000-000000000000</OriginalTemplateId> 
    <OriginalTemplateName>Blank</OriginalTemplateName> 
    <UseLatestVersion>false</UseLatestVersion> 
    <Section ovf:id="70b4d9a7-4f73-4def-89ca-24fc5f60e01a" 
      ovf:required="false" 
      xsi:type="ovf:OperatingSystemSection_Type"> 
      <Info>Guest Operating System</Info> 
      <Description>other</Description> 
    </Section>
    <Section xsi:type="ovf:VirtualHardwareSection_Type"> 
      <Info>1 CPU, 1024 Memeory</Info> 
      <System> 
        <vssd:VirtualSystemType>ENGINE 3.5.0.0</vssd:VirtualSystemType> 
      </System> 
      <Item> 
        <rasd:Caption>1 virtual cpu</rasd:Caption> 
        <rasd:Description>Number of virtual CPU</rasd:Description> 
        <rasd:InstanceId>1</rasd:InstanceId> 
        <rasd:ResourceType>3</rasd:ResourceType> 
        <rasd:num_of_sockets>1</rasd:num_of_sockets> 
        <rasd:cpu_per_socket>1</rasd:cpu_per_socket> 
      </Item> 
      <Item> 
        <rasd:Caption>1024 MB of memory</rasd:Caption> 
        <rasd:Description>Memory Size</rasd:Description> 
        <rasd:InstanceId>2</rasd:InstanceId> 
        <rasd:ResourceType>4</rasd:ResourceType> 
        <rasd:AllocationUnits>MegaBytes</rasd:AllocationUnits> 
        <rasd:VirtualQuantity>1024</rasd:VirtualQuantity> 
      </Item> 
      <Item> 
        <rasd:Caption>USB Controller</rasd:Caption> 
        <rasd:InstanceId>3</rasd:InstanceId> 
        <rasd:ResourceType>23</rasd:ResourceType> 
        <rasd:UsbPolicy>DISABLED</rasd:UsbPolicy> 
      </Item> 
    </Section> 
  </Content> 
</ovf:Envelope>

15.4. 仮想マシンの JSON 表現

例15.3 仮想マシンの JSON 表現

{
  "type" : "server",
  "status" : {
    "state" : "down"
  },
  "stop_reason" : "",
  "memory" : 1073741824,
  "cpu" : {
    "topology" : {
      "sockets" : "1",
      "cores" : "1"
    },
    "architecture" : "X86_64"
  },
  "cpu_shares" : "0",
  "bios" : {
    "boot_menu" : {
      "enabled" : "false"
    }
  },
  "os" : {
    "boot" : [ {
      "dev" : "hd"
    } ],
    "type" : "other"
  },
  "high_availability" : {
    "enabled" : "false",
    "priority" : "1"
  },
  "display" : {
    "type" : "spice",
    "monitors" : "1",
    "single_qxl_pci" : "false",
    "allow_override" : "false",
    "smartcard_enabled" : "false",
    "file_transfer_enabled" : "true",
    "copy_paste_enabled" : "true"
  },
  "cluster" : {
    "href" : "/api/clusters/00000001-0001-0001-0001-0000000002fb",
    "id" : "00000001-0001-0001-0001-0000000002fb"
  },
  "template" : {
    "href" : "/api/templates/00000000-0000-0000-0000-000000000000",
    "id" : "00000000-0000-0000-0000-000000000000"
  },
  "stop_time" : 1423550982110,
  "creation_time" : 1423490033647,
  "origin" : "ovirt",
  "stateless" : "false",
  "delete_protected" : "false",
  "sso" : {
    "methods" : {
      "method" : [ {
        "id" : "GUEST_AGENT"
      } ]
    }
  },
  "timezone" : "Etc/GMT",
  "initialization" : {
    "regenerate_ssh_keys" : "false",
    "nic_configurations" : { }
  },
  "placement_policy" : {
    "affinity" : "migratable"
  },
  "memory_policy" : {
    "guaranteed" : 1073741824,
    "ballooning" : "true"
  },
  "usb" : {
    "enabled" : "false"
  },
  "migration_downtime" : "-1",
  "cpu_profile" : {
    "href" : "/api/cpuprofiles/0000001a-001a-001a-001a-0000000002e3",
    "id" : "0000001a-001a-001a-001a-0000000002e3"
  },
  "next_run_configuration_exists" : "false",
  "numa_tune_mode" : "interleave",
  "actions" : {
    "link" : [ {
      "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/ticket",
      "rel" : "ticket"
    }, {
      "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/move",
      "rel" : "move"
    }, {
      "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/clone",
      "rel" : "clone"
    }, {
      "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/commit_snapshot",
      "rel" : "commit_snapshot"
    }, {
      "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/preview_snapshot",
      "rel" : "preview_snapshot"
    }, {
      "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/logon",
      "rel" : "logon"
    }, {
      "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/cancelmigration",
      "rel" : "cancelmigration"
    }, {
      "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/maintenance",
      "rel" : "maintenance"
    }, {
      "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/reboot",
      "rel" : "reboot"
    }, {
      "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/undo_snapshot",
      "rel" : "undo_snapshot"
    }, {
      "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/migrate",
      "rel" : "migrate"
    }, {
      "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/detach",
      "rel" : "detach"
    }, {
      "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/export",
      "rel" : "export"
    }, {
      "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/shutdown",
      "rel" : "shutdown"
    }, {
      "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/start",
      "rel" : "start"
    }, {
      "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/stop",
      "rel" : "stop"
    }, {
      "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/suspend",
      "rel" : "suspend"
    } ]
  },
  "name" : "VM_01",
  "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e",
  "id" : "42ec2621-7ad6-4ca2-bd68-973a44b2562e",
  "link" : [ {
    "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/applications",
    "rel" : "applications"
  }, {
    "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/disks",
    "rel" : "disks"
  }, {
    "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/nics",
    "rel" : "nics"
  }, {
    "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/numanodes",
    "rel" : "numanodes"
  }, {
    "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/cdroms",
    "rel" : "cdroms"
  }, {
    "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/snapshots",
    "rel" : "snapshots"
  }, {
    "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/tags",
    "rel" : "tags"
  }, {
    "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/permissions",
    "rel" : "permissions"
  }, {
    "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/statistics",
    "rel" : "statistics"
  }, {
    "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/reporteddevices",
    "rel" : "reporteddevices"
  }, {
    "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/watchdogs",
    "rel" : "watchdogs"
  }, {
    "href" : "/api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/sessions",
    "rel" : "sessions"
  } ]
}

15.5. メソッド

15.5.1. 仮想マシンの作成

新規仮想マシンの作成には nametemplatecluster の要素が必要です。template 要素と cluster 要素は id 属性または name 要素で特定します。CPU プロファイルの ID は cpuprofiles 属性で特定します。

例15.4 CD-ROM から起動する、512 MB の仮想マシンの作成

POST /api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
    <name>vm2</name>
    <description>Virtual Machine 2</description>
    <type>desktop</type>
    <memory>536870912</memory>
    <cluster>
        <name>default</name>
    </cluster>
    <template>
        <name>Blank</name>
    </template>
    <os>
        <boot dev="cdrom"/>
    </os>
    <cdroms>
        <cdrom>
            <file id="example_windows_7_x64_dvd_u_677543.iso"/>
        </cdrom>
    </cdroms>
    <cpu_profile id="0000001a-001a-001a-001a-00000000035e"/>
</vm>

例15.5 仮想ハードディスクから起動する 512 MB の仮想マシンの作成

POST /api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
    <name>vm2</name>
    <description>Virtual Machine 2</description>
    <type>desktop</type>
    <memory>536870912</memory>
    <cluster>
        <name>default</name>
    </cluster>
    <template>
        <name>Blank</name>
    </template>
    <os>
      <boot dev="hd"/>
    </os>
    <cpu_profile id="0000001a-001a-001a-001a-00000000035e"/>
</vm>

注記

上記の例のメモリーは、以下の計算式でバイト単位に換算します。
512MB * 1024 2 = 536870912 bytes

15.5.2. 仮想マシンの更新

namedescriptionclustertypememorycpuoshigh_availabilitydisplaytimezonedomainstatelessplacement_policymemory_policyusbpayloadsorigin、および custom_properties の各要素は作成後に更新が可能です。

例15.6 仮想マシンの搭載メモリーを 1 GB に更新

PUT /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
    <memory>1073741824</memory>
</vm>

注記

上記の例のメモリーは、以下の計算式でバイト単位に換算します。
1024MB * 1024 2 = 1073741824 bytes

注記

メモリーのホットプラグは Red Hat Enterprise Virtualization 3.6 以降でサポートされます。上記の例を使用して、仮想マシンの実行中にメモリーを増加することができます。

例15.7 仮想 CPU のホットプラグ

仮想マシンを再起動する必要なしに、仮想 CPU を実行中の仮想マシンに追加します。以下の例では、ソケットの数は 2 に変更しています。
PUT /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
    <cpu>
        <topology sockets="2" cores="1"/>
    </cpu>
</vm>

注記

CPU のホットアンプラグは現在、Red Hat Enterprise Virtualization ではサポートされていません。

例15.8 複数のホストへの仮想マシンの固定

複数のホストに固定された仮想マシンは、ライブマイグレーションできませんが、ホストに障害が発生した場合には、高可用性に設定された仮想マシンは、この仮想マシンが固定されている別のホスト上で再起動されます。たとえば、複数ホストの固定を使用すると、同じハードウェア設定が指定されたホストだけに仮想マシンを制限することができます。
PUT /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
    <high_availability>
        <enabled>true</enabled>
        <priority>1</priority>
    </high_availability>
    <placement_policy>
        <hosts>
            <host><name>Host1</name></host>
            <host><name>Host2</name></host>
        </hosts>
        <affinity>pinned</affinity>
    </placement_policy>
</vm>

15.5.3. 仮想マシンの削除

仮想マシンを削除するには DELETE 要求を実行する必要があります。

例15.9 仮想マシンの削除

DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1

HTTP/1.1 204 No Content

15.5.4. 仮想ディスクを削除せずに仮想マシンを削除する方法

仮想マシンを削除する前に仮想ディスクをデタッチしておきます。これにより、仮想ディスクが保持されます。仮想マシンの削除には DELETE 要求が必要です。

例15.10 仮想マシンの削除

DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <vm>
        <disks>
            <detach_only>true</detach_only>
        </disks>
    </vm>
</action>

15.6. サブコレクション

15.6.1. ディスクのサブコレクション

15.6.1.1. ディスクのサブコレクション

disks サブコレクションは、仮想マシン上のすべての仮想ハードディスクデバイスを表します。disk 表現には次のような要素が含まれます。

表15.2 仮想マシンディスクの要素

要素タイプ説明プロパティー
link rel="statistics"リレーションシップ仮想マシンのディスクの統計を確認するための statistics サブコレクションへのリンク
link rel="permissions"リレーションシップpermissions サブコレクションへのリンク
alias文字列ディスクの一意識別子。name ではなく alias を使用します。
image_id文字列定義されたストレージドメインに格納されている仮想マシンイメージへの参照
storage_domains複合型そのディスクと関連付けられたストレージドメイン。storage_domain 要素には 関連付けられたストレージドメインの GUID を示す id 属性が含まれます。データストレージドメイン間でのライブマイグレーションを実行するには、POST でこの要素を更新します。 [a]
size整数ディスクサイズ (バイト単位)。非推奨となり、provisioned_size に置き換えられます。
provisioned_size整数プロビジョニングされたディスクのサイズ (バイト単位)
actual_size整数ディスクの実際のサイズ (バイト単位)
statusillegalinvalidlockedok のいずれかディスクデバイスのステータス。 これらのステータスは capabilities の下の disk_states に記載されています。
interface列挙型ディスクデバイスへの接続に使用するインターフェースドライバーのタイプ。使用できる列挙値の一覧は capabilities に記載されています。 
format列挙型下層のストレージのフォーマット。列挙値の一覧は capabilities に記載されています。Copy On Write (COW) により、最小限のパフォーマンスオーバーヘッドでスナップショットを作成することができます。Raw ではスナップショットは作成できませんが、パフォーマンスが向上します。
sparseブール値: true または falsetrue: 物理ストレージの場合に指定します。ディスクを事前割り当てすべきではないためです。
bootableブール値: true または falsetrue: ディスクがブート可能とマークされている場合に指定します。 
shareableブール値: true または falsetrue: 複数の仮想マシンで共有する場合に指定します。 
wipe_after_deleteブール値: true または falsetrue: ディスクが削除される時に下層の物理ストレージがゼロ処理される必要がある場合に指定します。これにより、セキュリティーが強化されますが、より負荷の高い操作であるため、削除に要する時間が伸びる可能性があります。 
propagate_errorsブール値: true または falsetrue: ディスクエラーによって仮想マシンが一時停止せず、代わりにディスクエラーがゲスト OS に伝達される必要がある場合に指定します。 
vm id=GUID格納している仮想マシンの ID
quota id=GUIDディスククォータを設定します。 
lun_storage複合型ストレージの使用状況を確認するための直接 LUN マッピングへの参照。iSCSI または FCP デバイスの詳細情報が含む logical_unit 要素が必要。
activeブール値仮想マシンにディスクが接続されているかどうかを定義します。
read_onlyブール値ディスクが読み取り専用かどうかを定義します。
link rel="disk_profile"リレーションシップdisk_profile サブコレクションへのリンク
[a] この要素は、仮想マシンから作成されていないディスクを仮想マシンに追加する場合のみ必要です。

例15.11 ディスクデバイスの XML 表現

<disk id="ed7feafe-9aaf-458c-809a-ed789cdbd5b4"
  href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
  ed7feafe-9aaf-458c-809a-ed789cdbd5b4">
    <link rel="statistics"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
      ed7feafe-9aaf-458c-809a-ed789cdbd5b4/statistics"/>
    <link rel="permissions"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
      ed7feafe-9aaf-458c-809a-ed789cdbd5b4/permissions"/>
    <vm id="082c794b-771f-452f-83c9-b2b5a19c0399"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399"/> 
    <alias>Classic_VM</alias>
    <image_id>cac69a29-ccff-49d4-8a26-e4cdacd83e34</image_id> 
    <storage_domains>
        <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
    </storage_domains> 
    <size>12884901888</size>
    <provisioned_size>12884901888</provisioned_size>
    <actual_size>1073741824</actual_size>
    <type>system</type>
    <status>
        <state>ok</state>
    </status>
    <interface>virtio</interface>
    <format>raw</format>
    <bootable>true</bootable>
    <shareable>true</shareable>
    <wipe_after_disk>true</wipe_after_disk>
    <propagate_errors>false</propagate_errors>
    <active>true</active>
    <read_only>false</read_only>
    <disk_profile id="23fb2e0d-3062-4819-8165-3be88f2f587e"
      href="/api/diskprofiles/23fb2e0d-3062-4819-8165-3be88f2f587e"/>
    <lun_storage>
        <logical_unit id="lun1">
                ...
        </logical_unit>
    </lun_storage>
</disk>

新規の仮想ディスクを追加します。新しい内部ディスクを追加する場合は、provisioned_size 要素が必要です。storage_domains 要素を使用して、どのストレージドメインにディスクを作成するかを指定します。異なるストレージドメインには、同じ仮想マシンに対して複数のディスクを配置することができます。

例15.12 仮想マシン上での新規ディスクデバイスの作成

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk>
    <storage_domains>
        <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
    </storage_domains>        
    <provisioned_size>8589934592</provisioned_size>
    <type>system</type>
    <interface>virtio</interface>
    <format>cow</format>
    <bootable>true</bootable>
</disk>
新しい外部 (直接 LUN) ディスクを仮想マシンに追加します。この方法には、lun_storage 要素と、iSCSI または FCP デバイスの詳細情報を含む logical_unit 要素が必要です。

例15.13 仮想マシン上での新規外部 LUN ディスクデバイスの作成

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks HTTP/1.1
Accept: application/xml
Content-type: application/xml
		
<disk>
    <interface>virtio</interface>
    <lun_storage>
        <type>iscsi</type>
        <logical_unit id="lun1">
            <address>iscsi.example.com</address>
            <port>3260</port>
            <target>iqn.2010.05.com.example:iscsi.targetX</target>
        </logical_unit>
    </lun_storage>
</disk>
aliasdescriptionstorage_domainsprovisioned_sizeinterfacebootableshareablewipe_after_deletepropagate_errors の要素は、作成後に更新可能です。
仮想ディスクは、1 台または複数の仮想マシンにより使用されている最中でも、仮想マシンを一時停止、休止、リブートせずにサイズの変更が可能です。

例15.14 仮想マシンディスクの更新

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk>
    <bootable>false</bootable>
    <shareable>false</shareable>
</disk>

例15.15 仮想マシンディスクのサイズを 20 GB に更新

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk>
    <provisioned_size>21474836480</provisioned_size>
</disk>

注記

上記の例のディスクサイズは、以下の計算式でバイト単位に換算します。
20480MB * 1024 2 = 21474836480 bytes

例15.16 仮想マシンディスク名の変更

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk>
    <alias>Classic_VM2</alias>
</disk>
仮想マシンディスクを削除するには、DELETE 要求を実行する必要があります。

例15.17 仮想マシンディスクの削除

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.18 テンプレートからのディスクのクローン作成

次の例は、仮想マシンの作成中にテンプレートからディスクのクローンを作成します。
POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml
        
<vm>
    <name>cloned_vm</name>
    <template id="64d4aa08-58c6-4de2-abc4-89f19003b886"/>
    <cluster id="99408929-82cf-4dc7-a532-9d998063fa95"/>
    <disks>
        <clone>true</clone>
        <disk id="4825ffda-a997-4e96-ae27-5503f1851d1b">
            <format>COW</format>
        </disk>
        <disk id="42aef10d-3dd5-4704-aa73-56a023c1464c">
            <format>COW</format>
        </disk>
    </disks>
</vm>

重要

ディスク名に基づいた仮想マシンの検索クエリーには、name ではなく alias 検索パラメーターが必要です。

15.6.1.3. ディスク統計のサブコレクション

各仮想マシンのディスクでは、ディスク固有の統計の statistics サブコレクションを公開します。各 statistics には次のような要素が含まれます。

表15.3 仮想マシンディスク統計の要素

要素タイプ説明
name文字列統計エントリーの一意識別子
description文字列プレーンテキストで記述された統計の説明
unit文字列統計値測定の単位またはレート
typeGAUGE または COUNTER統計測定値のタイプ
values type=INTEGER または DECIMALその後に続く統計値のデータタイプ
value複合型datum を含むデータセット
datumvalues type を参照value に含まれるデータの 1 つ
disk id=リレーションシップ格納している disk リソースとのリレーションシップ
次の表には、仮想マシンディスクの統計タイプをまとめています。

表15.4 仮想マシンのディスク統計タイプ

名前
説明
data.current.read
ディスク読み込み時のデータ転送速度 (バイト/秒)
data.current.write
ディスク書き込み時のデータ転送速度 (バイト/秒)

例15.19 仮想マシンの統計サブコレクションの XML 表現

<statistics>
    <statistic id="33b9212b-f9cb-3fd0-b364-248fb61e1272"
      href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/disks/
      f28ec14c-fc85-43e1-818d-96b49d50e27b/statistics/
      33b9212b-f9cb-3fd0-b364-248fb61e1272">
        <name>data.current.read</name>
        <description>Read data rate</description>
        <values type="DECIMAL">
            <value>
                <datum>0</datum>
            </value>
        </values>
        <type>GAUGE</type>
        <unit>BYTES_PER_SECOND</unit>
        <disk id="f28ec14c-fc85-43e1-818d-96b49d50e27b" 
          href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/
          disks/f28ec14c-fc85-43e1-818d-96b49d50e27b"/>
    </statistic>
    ...
</statistics>

注記

上記の statistics サブコレクションは読み取り専用です。

15.6.1.4. フローティングディスクのアタッチおよびデタッチのアクション

メイン rel="disks" コレクションからディスクをアタッチするには、仮想マシンの disks サブコレクションに対して POST 要求を実行します。その際には、アタッチするディスクの id を指定してください。

例15.20 フローティングディスクのアタッチ

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk id="d135f1c5-b5e1-4238-9381-b3277f5a3742">
</disk>
仮想マシンの disks サブコレクションからディスクをデタッチするには、ディスクリソースに対して DELETE 要求を実行します。その際には、ディスクが破棄されないように、必ず detach のブール要素を追加してください。

例15.21 仮想マシンからのディスクのデタッチ

DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/
  d135f1c5-b5e1-4238-9381-b3277f5a3742 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <detach>true</detach>
</action>

15.6.1.5. ディスクのアクティブ化および非アクティブ化のアクション

各仮想マシンのディスクは、仮想マシンにディスクを追加/削除するための activate および deactivate アクションセットを提供します。

例15.22 仮想マシンディスクをアクティブ化するアクション

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/a42ada0e-1d69-410d-a392-a6980d873e5d/activate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

例15.23 仮想マシンディスクを非アクティブ化するアクション

POST /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/disks/a42ada0e-1d69-410d-a392-a6980d873e5d/deactivate HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>
これらのアクションを使用して、ディスクを仮想マシンにホットプラグし、新たにアタッチしたフローティングディスクをアクティブ化します。

重要

ホットプラグ機能は、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 表現には次の要素が含まれます。

表15.5 仮想マシンのネットワークインターフェースの要素

要素タイプ説明プロパティー
link rel="statistics"リレーションシップ仮想マシンのネットワークインターフェース統計の statistics サブコレクションへのリンク
network id=GUIDインターフェースを接続すべきネットワークへの参照。ネットワーク ID は空白にすることが可能。
interface列挙型ネットワークインターフェースカードに使用するドライバーのタイプ。列挙値の一覧は capabilities にあります。 
mac address=文字列インターフェースの MAC アドレス
port_mirroring複合型NIC がミラーリングされたトラフィックを受信するかどうかを定義します。network id= 参照を使用して networks 要素を定義します。
pluggedブール値NIC が仮想マシンに結線されるかどうかを定義します。
linkedブール値NIC が仮想マシンにリンクされるかどうかを定義します。

例15.24 ネットワークインターフェースの XML 表現

<nic id="7a3cff5e-3cc4-47c2-8388-9adf16341f5e" 
  ref="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/
  7a3cff5e-3cc4-47c2-8388-9adf16341f5e">
    <link rel="statistics"
      href="/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399/nics/
      7a3cff5e-3cc4-47c2-8388-9adf16341f5e/statistics"/>   
    <name>nic1</name>
    <interface>virtio</interface>
    <mac address="00:1a:4a:16:84:07"/>
    <network id="00000000-0000-0000-0000-000000000009"
      href="/api/networks/00000000-0000-0000-0000-000000000009"/>
    <vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
      href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
    <port_mirroring>
        <networks>
            <network id="56087282-d7a6-11e1-af44-001a4a400e0c"
              href="/api/networks/56087282-d7a6-11e1-af44-001a4a400e0c"/>
        </networks>
    </port_mirroring>
</nic>
新規のネットワークインタフェースを追加する際には、name および network の要素が必要です。network 要素は id 属性または name 要素で特定します。

例15.25 仮想マシン NIC の作成

POST /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics HTTP/1.1
Accept: application/xml
Content-type: application/xml

<nic>
    <name>nic1</name>
    <network id="00000000-0000-0000-0000-000000000009"/>
</nic>
ネットワークインターフェースを変更するには、PUT 要求を使用します。

例15.26 仮想マシン NIC の更新

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/nics/
7a3cff5e-3cc4-47c2-8388-9adf16341f5e HTTP/1.1
Accept: application/xml
Content-type: application/xml

<nic>
    <name>nic2</name>
    <network id="00000000-0000-0000-0000-000000000010"/>
    <type>e1000</type>
</nic>
ネットワークインターフェースの削除は DELETE 要求で行います。

例15.27 仮想マシン NIC の削除

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 には、次の要素が含まれます。

表15.6 仮想マシンのネットワークインターフェース統計の要素

要素タイプ説明
name文字列統計エントリーの一意識別子
description文字列プレーンテキストで記述された統計の説明
unit文字列統計値測定の単位またはレート
typeGAUGE または COUNTER統計測定値のタイプ
values type=INTEGER または DECIMALその後に続く統計値のデータタイプ
value複合型datum を含むデータセット
datumvalues type を参照value に含まれるデータの 1 つ
nic id=リレーションシップ格納している nic リソースとのリレーションシップ
以下の表には、仮想マシン上のネットワークインターフェースの統計タイプをまとめています。

表15.7 仮想マシンの NIC の統計タイプ

名前
説明
data.current.rx
データの受信速度 (ビット毎秒)
data.current.tx
データの送信速度 (ビット毎秒)
errors.total.rx
データ受信でのエラーの合計数
errors.total.tx
データ送信でのエラーの合計数

例15.28 仮想マシンの NIC 統計サブコレクションの XML 表現

<statistics>
    <statistic id="ecd0559f-e88f-3330-94b4-1f091b0ffdf7"
      href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/nics/
      6cd08e76-57c0-41ba-a728-7eba46ae1e36/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>
        <nic id="6cd08e76-57c0-41ba-a728-7eba46ae1e36"
          href="/api/vms/3a42530e-3bc5-4094-829d-489257894c2a/
          nics/6cd08e76-57c0-41ba-a728-7eba46ae1e36"/>
    </statistic>
    ...
</statistics>

注記

上記の statistics サブコレクションは読み取り専用です。

15.6.3. 仮想 NUMA ノードのサブコレクション

numanodes サブコレクションは、仮想マシン上の全仮想 NUMA ノードを表します。vm_numa_node 表現には次のような要素が含まれます。

表15.8 仮想 NUMA ノードの要素

要素タイプ説明プロパティー
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.29 仮想 NUMA ノードの XML 表現

<vm_numa_node href="/api/vms/c7ecd2dc-dbd3-4419-956f-1249651c0f2b/numanodes/3290b973-ed3e-4f0b-bbf5-9be10d229e50" id="3290b973-ed3e-4f0b-bbf5-9be10d229e50">
        <index>0</index>
        <memory>1024</memory>
        <cpu>
            <cores>
                <core index="0"/>
            </cores>
        </cpu>
        <vm href="/api/vms/c7ecd2dc-dbd3-4419-956f-1249651c0f2b" id="c7ecd2dc-dbd3-4419-956f-1249651c0f2b"/>
        <numa_node_pins>
            <numa_node_pin pinned="true" index="0">
                <host_numa_node id="417cdefb-8c47-4838-87f3-dd0498fdf6c7"/>
            </numa_node_pin>
        </numa_node_pins>
</vm_numa_node>
新規仮想 NUMA ノードを追加する場合は、indexmemorycpu の要素が必要です。

例15.30 新規 NUMA ノードの仮想マシンへの追加

POST /api/vms/c7ecd2dc-dbd3-4419-956f-1249651c0f2b/numanodes HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm_numa_node>
  <index>0</index>
  <memory>1024</memory>
  <cpu>
    <cores>
      <core index="0"/>
    </cores>
  </cpu>
</vm_numa_nodes>
仮想 NUMA ノードは PUT 要求で更新します。PUT 要求を使用して、仮想 NUMA ノードをホスト上の物理 NUMA ノードに固定することができます。

例15.31 仮想 NUMA ノードの更新

PUT /api/vms/c7ecd2dc-dbd3-4419-956f-1249651c0f2b/numanodes/3290b973-ed3e-4f0b-bbf5-9be10d229e50 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm_numa_node>
  <numa_node_pins>
    <numa_node_pin pinned="true" index="0">
      <host_numa_node id="417cdefb-8c47-4838-87f3-dd0498fdf6c7"/>
    </numa_node_pin>
  </numa_node_pins>
</vm_numa_node>
DELETE 要求で仮想 NUMA ノードを削除します。

例15.32 仮想 NUMA ノードの削除

DELETE /api/vms/c7ecd2dc-dbd3-4419-956f-1249651c0f2b/numanodes/3290b973-ed3e-4f0b-bbf5-9be10d229e50 HTTP/1.1

HTTP/1.1 204 No Content

15.6.4. CD-ROM のサブコレクション

cdroms サブコレクションは、仮想マシン上の CD-ROM デバイスを表します。cdrom 表現には次のエレメントが含まれます。

表15.9 仮想マシンの CD-ROM の要素

要素タイプ説明プロパティー
file id=文字列/ファイル名ISO イメージへの参照 

例15.33 CD-ROM デバイスの XML 表現

<cdrom id="00000000-0000-0000-0000-000000000000"
  href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/
  00000000-0000-0000-0000-000000000000">
    <file id="rhel-server-6.0-x86_64-dvd.iso"/>
    <vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
      href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
</cdrom>
新しい CD-ROM リソースを追加するには、PUT 要求を file id 要素とともに送信します。

例15.34 新規 CD-ROM ファイルの追加

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
      
<cdrom>
    <file id="fedora-15-x86_64-dvd.iso"/>
</cdrom>
API は、PUT 要求を使用して CD-ROM を変更します。

例15.35 CD-ROM ファイルの変更

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
      
<cdrom>
    <file id="fedora-15-x86_64-dvd.iso"/>
</cdrom>
PUT 要求に current URI 引数を追加して使用すると、API は現行セッションの CD-ROM を変更します。

例15.36 現行セッション中の CD-ROM ファイル変更

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000;current=true HTTP/1.1
Accept: application/xml
Content-type: application/xml
      
<cdrom>
    <file id="fedora-15-x86_64-dvd.iso"/>
</cdrom>
一時的に CD-ROM を取り出すには 仮想マシンの cdroms サブコレクションに PUT 要求を送信して、current=true マトリックスパラメーターを追加します。

例15.37 現行セッション中の CD-ROM ファイルの取り出し

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000;current=true HTTP/1.1
Accept: application/xml
Content-type: application/xml
<cdrom>
  <file id=""/>
</cdrom>

注記

仮想マシンをリブートすると、再度 CD-ROM が接続されます。
CD-ROM を完全に取り出すには 仮想マシンの cdroms サブコレクションに PUT 要求を送信します。

例15.38 CD-ROM ファイルの完全取り出し

PUT /api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml
<cdrom>
  <file id=""/>
</cdrom>

注記

1 台の仮想マシンに含まれる CD-ROM デバイスは 1 つのみです。

15.6.5. スナップショットのサブコレクション

15.6.5.1. スナップショットのサブコレクション

仮想マシンは、ディスクの状態を複数のスナップショットとして保存/復元します。これらのスナップショットは、rel="snapshot" サブコレクションで表現/管理されます。このサブコレクションは、他のコレクションと同様に動作します。
各仮想マシンスナップショットは、以下のサブ要素を含む各 snapshot 要素で表されます。

表15.10 仮想マシンのスナップショットの要素

要素タイプ説明プロパティー
vm id=GUIDそのスナップショットの作成元である仮想マシンの ID と URI
link rel="restore"リレーションシップその仮想マシンのスナップショットを復元するためののリンク
link rel="prev"リレーションシップその仮想マシンの前のスナップショットへのリンク
type文字列active または regular などのスナップショットの種類
datexsd:dateTime の形式: YYYY-MM-DDThh:mm:ssそのスナップショットが作成された日付と時刻
snapshot_status文字列スナップショットの現在のステータス
persist_memorystateブール値スナップショットを作成する際の仮想マシンメモリーのステータスをスナップショットに含めるかどうかを定義します。

注記

スナップショットの要素の変更には PUT を使用できません。

例15.39 仮想マシンのスナップショットの XML 表現

<snapshot id="00000000-0000-0000-0000-000000000000"
  href="/api/vms/00000000-0000-0000-0000-000000000000/snapshots/
  00000000-0000-0000-0000-000000000000">
    <actions>
      <link rel="restore"
      href="/api/vms/00000000-0000-0000-0000-000000000000/snapshots/
      00000000-0000-0000-0000-000000000000/restore"/>
    <link rel="prev"
      href="/api/vms/00000000-0000-0000-0000-000000000000/snapshots/
    </actions>
    <vm id="00000000-0000-0000-0000-000000000000"
      href="/api/vms/00000000-0000-0000-0000-000000000000"/>
    <description>Virtual Machine 1 - Snapshot A</description>
    <type>active</type>
    <date>2010-08-16T14:24:29</date>
    <snapshot_status>ok</snapshot_status>
    <persist_memorystate>false</persist_memorystate>
</snapshot>
仮想マシンスナップショットの GET 要求で All-Content: true ヘッダーを使用して、スナップショットの表現に追加の OVF データを含めます。
Accept ヘッダーを空欄にした場合には、デフォルトで application/xml となり、XML タグに影響しないようにデータは HTML エンティティーで表現されます。Accept: application/json ヘッダーを指定すると、データは標準の XML タグで返されます。以下の表現の例は、標準のブロックフォーマットを編集して、より読みやすい書式で示しています。

例15.40 スナップショットの追加の OVF データの XML 表現

GET /api/vms/42ec2621-7ad6-4ca2-bd68-973a44b2562e/snapshots HTTP/1.1
All-Content: true
	
<?xml version='1.0' encoding='UTF-8'?>
<ovf:Envelope xmlns:ovf=\"http://schemas.dmtf.org/ovf/envelope/1/\" 
  xmlns:rasd=\"http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ResourceAllocationSettingData\" 
  xmlns:vssd=\"http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_VirtualSystemSettingData\" 
  xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" ovf:version=\"3.5.0.0\"> 
  <References>
  <File ovf:href=\"ad353554-f668-46cf-aa3c-e57383de2c92/40456d92-3687-4a85-bab3-87b4cc7af459\" 
    ovf:id=\"40456d92-3687-4a85-bab3-87b4cc7af459\" ovf:size=\"10737418240\" 
    ovf:description=\"Active VM\"/>
  <Nic ovf:id=\"be14bfc8-3dbd-4ac1-ba02-c6dfa7fc707c\"/>
  </References>
  <Section xsi:type=\"ovf:NetworkSection_Type\"> 
    <Info>List of networks</Info><Network ovf:name=\"Network 1\"/>
  </Section>
  <Section 
    xsi:type=\"ovf:DiskSection_Type\"> 
    <Info>List of Virtual Disks</Info>
    <Disk ovf:diskId=\"40456d92-3687-4a85-bab3-87b4cc7af459\" 
    ovf:size=\"10\" ovf:actual_size=\"0\" 
    ovf:vm_snapshot_id=\"a209216d-2909-4802-8886-02aad55dccc8\" 
    ovf:parentRef=\"\" 
    ovf:fileRef=\"ad353554-f668-46cf-aa3c-e57383de2c92/40456d92-3687-4a85-bab3-87b4cc7af459\" 
    ovf:format=\"http://www.vmware.com/specifications/vmdk.html#sparse\" 
    ovf:volume-format=\"RAW\" 
    ovf:volume-type=\"Preallocated\" 
    ovf:disk-interface=\"VirtIO\" 
    ovf:boot=\"true\" 
    ovf:disk-alias=\"VM_01_Disk1\" 
    ovf:wipe-after-delete=\"false\"/>
  </Section>
  <Content 
    ovf:id=\"out\" 
    xsi:type=\"ovf:VirtualSystem_Type\"> 
    <CreationDate>2015/02/09 13:53:53</CreationDate> 
    <ExportDate>2015/02/10 00:39:24</ExportDate> 
    <DeleteProtected>false</DeleteProtected> 
    <SsoMethod>guest_agent</SsoMethod> 
    <IsSmartcardEnabled>false</IsSmartcardEnabled> 
    <TimeZone>Etc/GMT</TimeZone><default_boot_sequence>0</default_boot_sequence> 
    <Generation>1</Generation> 
    <VmType>1</VmType> 
    <MinAllocatedMem>1024</MinAllocatedMem> 
    <IsStateless>false</IsStateless> 
    <IsRunAndPause>false</IsRunAndPause> 
    <AutoStartup>false</AutoStartup> 
    <Priority>1</Priority> 
    <CreatedByUserId>fdfc627c-d875-11e0-90f0-83df133b58cc</CreatedByUserId> 
    <IsBootMenuEnabled>false</IsBootMenuEnabled> 
    <IsSpiceFileTransferEnabled>true</IsSpiceFileTransferEnabled> 
    <IsSpiceCopyPasteEnabled>true</IsSpiceCopyPasteEnabled> 
    <Name>VM_01</Name> 
    <TemplateId>00000000-0000-0000-0000-000000000000</TemplateId> 
    <TemplateName>Blank</TemplateName> 
    <IsInitilized>true</IsInitilized> 
    <Origin>3</Origin> 
    <DefaultDisplayType>1</DefaultDisplayType> 
    <TrustedService>false</TrustedService> 
    <OriginalTemplateId>00000000-0000-0000-0000-000000000000</OriginalTemplateId> 
    <OriginalTemplateName>Blank</OriginalTemplateName> 
    <UseLatestVersion>false</UseLatestVersion>
    <Section ovf:id=\"42ec2621-7ad6-4ca2-bd68-973a44b2562e\" ovf:required=\"false\" xsi:type=\"ovf:OperatingSystemSection_Type\"> 
      <Info>Guest Operating System</Info> 
      <Description>other</Description>
    </Section>
    <Section xsi:type=\"ovf:VirtualHardwareSection_Type\"> 
      <Info>1 CPU, 1024 Memeory</Info> 
      <System>
        <vssd:VirtualSystemType>ENGINE 3.5.0.0</vssd:VirtualSystemType>
      </System> 
      <Item> 
        <rasd:Caption>1 virtual cpu</rasd:Caption> 
        <rasd:Description>Number of virtual CPU</rasd:Description> 
        <rasd:InstanceId>1</rasd:InstanceId> 
        <rasd:ResourceType>3</rasd:ResourceType> 
        <rasd:num_of_sockets>1</rasd:num_of_sockets> 
        <rasd:cpu_per_socket>1</rasd:cpu_per_socket>
      </Item> 
      <Item> 
        <rasd:Caption>1024 MB of memory</rasd:Caption> 
        <rasd:Description>Memory Size</rasd:Description> 
        <rasd:InstanceId>2</rasd:InstanceId> 
        <rasd:ResourceType>4</rasd:ResourceType> 
        <rasd:AllocationUnits>MegaBytes</rasd:AllocationUnits> 
        <rasd:VirtualQuantity>1024</rasd:VirtualQuantity>
      </Item> 
      <Item> 
        <rasd:Caption>VM_01_Disk1</rasd:Caption> 
        <rasd:InstanceId>40456d92-3687-4a85-bab3-87b4cc7af459</rasd:InstanceId> 
        <rasd:ResourceType>17</rasd:ResourceType> 
        <rasd:HostResource>ad353554-f668-46cf-aa3c-e57383de2c92/40456d92-3687-4a85-bab3-87b4cc7af459</rasd:HostResource> 
        <rasd:Parent>00000000-0000-0000-0000-000000000000</rasd:Parent> 
        <rasd:Template>00000000-0000-0000-0000-000000000000</rasd:Template> 
        <rasd:ApplicationList></rasd:ApplicationList> 
        <rasd:StoragePoolId>00000002-0002-0002-0002-000000000255</rasd:StoragePoolId> 
        <rasd:CreationDate>2015/02/09 13:54:41</rasd:CreationDate> 
        <rasd:LastModified>1970/01/01 00:00:00</rasd:LastModified> 
        <rasd:last_modified_date>2015/02/10 00:39:22</rasd:last_modified_date> 
        <Type>disk</Type> 
        <Device>disk</Device> 
        <rasd:Address>{slot=0x06, bus=0x00, domain=0x0000, type=pci, function=0x0}</rasd:Address> 
        <BootOrder>1</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>false</IsReadOnly> 
        <Alias>virtio-disk0</Alias>
      </Item> 
      <Item> 
        <rasd:Caption>Ethernet adapter on ovirtmgmt</rasd:Caption> 
        <rasd:InstanceId>be14bfc8-3dbd-4ac1-ba02-c6dfa7fc707c</rasd:InstanceId> 
        <rasd:ResourceType>10</rasd:ResourceType> 
        <rasd:OtherResourceType>ovirtmgmt</rasd:OtherResourceType> 
        <rasd:ResourceSubType>3</rasd:ResourceSubType> 
        <rasd:Connection>ovirtmgmt</rasd:Connection> 
        <rasd:Linked>true</rasd:Linked> 
        <rasd:Name>nic1</rasd:Name> 
        <rasd:MACAddress>00:1a:4a:87:cb:00</rasd:MACAddress> 
        <rasd:speed>1000</rasd:speed> 
        <Type>interface</Type> 
        <Device>bridge</Device> 
        <rasd:Address>{slot=0x03, bus=0x00, domain=0x0000, type=pci, function=0x0}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>false</IsReadOnly> 
        <Alias>net0</Alias>
      </Item> 
      <Item> 
        <rasd:Caption>USB Controller</rasd:Caption> 
        <rasd:InstanceId>3</rasd:InstanceId> 
        <rasd:ResourceType>23</rasd:ResourceType> 
        <rasd:UsbPolicy>DISABLED</rasd:UsbPolicy>
      </Item> 
      <Item> 
        <rasd:Caption>Graphical Controller</rasd:Caption> 
        <rasd:InstanceId>17bbf0db-7cf0-4529-9b53-dee6dee41cfd</rasd:InstanceId> 
        <rasd:ResourceType>20</rasd:ResourceType> 
        <rasd:VirtualQuantity>1</rasd:VirtualQuantity> 
        <rasd:SinglePciQxl>false</rasd:SinglePciQxl> 
        <Type>video</Type> 
        <Device>qxl</Device> 
        <rasd:Address>{slot=0x02, bus=0x00, domain=0x0000, type=pci, function=0x0}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>true</IsReadOnly> 
        <Alias>video0</Alias> 
        <SpecParams>  
          <vram>32768</vram> 
          <heads>1</heads>
        </SpecParams>
      </Item> 
      <Item> 
        <rasd:Caption>CDROM</rasd:Caption> 
        <rasd:InstanceId>7ce1bd14-d98a-43ba-beee-520bdfd9c698</rasd:InstanceId> 
        <rasd:ResourceType>15</rasd:ResourceType> 
        <Type>disk</Type> 
        <Device>cdrom</Device> 
        <rasd:Address>{bus=1, controller=0, type=drive, target=0, unit=0}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>true</IsReadOnly> 
        <Alias>ide0-1-0</Alias></Item> 
      <Item> 
        <rasd:ResourceType>0</rasd:ResourceType> 
        <rasd:InstanceId>8758c42f-7523-461b-82bb-41d91e46fd36</rasd:InstanceId> 
        <Type>controller</Type> 
        <Device>usb</Device> 
        <rasd:Address>{slot=0x01, bus=0x00, domain=0x0000, type=pci, function=0x2}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>false</IsReadOnly> 
        <Alias>usb0</Alias>
      </Item> 
      <Item> 
        <rasd:ResourceType>0</rasd:ResourceType> 
        <rasd:InstanceId>58f1a596-553e-4e95-9331-64b5d8cebe2e</rasd:InstanceId> 
        <Type>controller</Type> 
        <Device>ide</Device> 
        <rasd:Address>{slot=0x01, bus=0x00, domain=0x0000, type=pci, function=0x1}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>false</IsReadOnly> 
        <Alias>ide0</Alias>
      </Item> 
      <Item> 
        <rasd:ResourceType>0</rasd:ResourceType> 
        <rasd:InstanceId>2f4f8aa5-25eb-4a31-b841-50dc48fce4a7</rasd:InstanceId> 
        <Type>channel</Type> 
        <Device>unix</Device> 
        <rasd:Address>{bus=0, controller=0, type=virtio-serial, port=1}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>false</IsReadOnly> 
        <Alias>channel0</Alias>
      </Item> 
      <Item> 
        <rasd:ResourceType>0</rasd:ResourceType> 
        <rasd:InstanceId>edaac3ed-2ab6-48b1-ae77-cc98f8b45bd8</rasd:InstanceId> 
        <Type>channel</Type> 
        <Device>unix</Device> 
        <rasd:Address>{bus=0, controller=0, type=virtio-serial, port=2}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>false</IsReadOnly> 
        <Alias>channel1</Alias>
      </Item> 
      <Item> 
        <rasd:ResourceType>0</rasd:ResourceType> 
        <rasd:InstanceId>8dfed248-5164-41d3-8b6e-46aef9798d84</rasd:InstanceId> 
        <Type>channel</Type> 
        <Device>spicevmc</Device> 
        <rasd:Address>{bus=0, controller=0, type=virtio-serial, port=3}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>false</IsReadOnly> 
        <Alias>channel2</Alias>
      </Item> 
      <Item> 
        <rasd:ResourceType>0</rasd:ResourceType> 
        <rasd:InstanceId>d184185e-ee19-442a-88f5-6a48f14164e1</rasd:InstanceId> 
        <Type>controller</Type> 
        <Device>virtio-scsi</Device> 
        <rasd:Address>{slot=0x04, bus=0x00, domain=0x0000, type=pci, function=0x0}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>false</IsReadOnly> 
        <Alias>scsi0</Alias>
      </Item> 
      <Item> 
        <rasd:ResourceType>0</rasd:ResourceType> 
        <rasd:InstanceId>374d219e-e2ff-4755-a544-d537c87e82df</rasd:InstanceId> 
        <Type>controller</Type> 
        <Device>virtio-serial</Device> 
        <rasd:Address>{slot=0x05, bus=0x00, domain=0x0000, type=pci, function=0x0}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>false</IsReadOnly> 
        <Alias>virtio-serial0</Alias>
      </Item> 
      <Item> 
        <rasd:ResourceType>0</rasd:ResourceType> 
        <rasd:InstanceId>cf3d7121-9db0-4fd1-bd12-50ce4e1ce379</rasd:InstanceId> 
        <Type>balloon</Type> 
        <Device>memballoon</Device> 
        <rasd:Address>{slot=0x07, bus=0x00, domain=0x0000, type=pci, function=0x0}</rasd:Address> 
        <BootOrder>0</BootOrder> 
        <IsPlugged>true</IsPlugged> 
        <IsReadOnly>true</IsReadOnly> 
        <Alias>balloon0</Alias> 
        <SpecParams> 
          <model>virtio</model>
        </SpecParams>
      </Item>
    </Section>
  </Content>
</ovf:Envelope>
POST メソッドを使用して実行中の仮想マシンのスナップショットを作成したり (ライブスナップショット)、シャットダウンしたりできます。

例15.41 仮想マシンのスナップショットの作成

POST /api/vms/00000000-0000-0000-0000-000000000000/snapshots/ HTTP/1.1
Accept: application/xml
Content-type: application/xml

<snapshot>
<description>Snapshot description</description>
</snapshot>

重要

OpenStack Volume (Cinder) ディスクを使用する仮想マシンのライブスナップショットを作成する前に、ゲストのファイルシステムを手動でフリーズして解凍する必要があります。詳しい情報は「仮想マシンのファイルシステムのフリーズアクション」「仮想マシンのファイルシステムアクション」を参照してください。
スナップショット表現内の rel="restore" アクションリンクを使用して、仮想マシンのスナップショットを復元することができます。

例15.42 仮想マシンのスナップショットの復元

POST /api/vms/00000000-0000-0000-0000-000000000000/snapshots/00000000-0000-0000-0000-000000000000/restore HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

15.6.5.2. スナップショットから仮想マシンのクローンを作成します。

API は、以前のマシンのスナップショットから仮想マシンを作成する機能を提供します。API ユーザーは、すべてのスナップショットで元の仮想マシンをそのまま保持しつつ、新しい仮想マシンを作成することができます。
スナップショットから仮想マシンを作成するには、仮想マシンの標準的な表現に snapshots 要素を追加する必要があります。ユーザーはこの要素を POST 要求で vms コレクションに送信します。
snapshots 要素には、仮想マシンのベースとして使用する特定のスナップショットを定義する snapshot id= 要素が含まれます。

例15.43 スナップショットからの仮想マシンのクローン作成

POST /api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
  ...
  <snapshots>
    <snapshot id="3f68ee63-0016-4f8c-9b8a-11d9f28f7c9e"/>
  </snapshots>
  ...
</vm>

15.6.6. 統計のサブコレクション

各仮想マシンのリソースは、仮想マシン固有の統計の statistics サブコレクションを公開します。各 statistic には次の要素が含まれます。

表15.11 仮想マシン統計の要素

要素タイプ説明
name文字列統計エントリーの一意識別子
description文字列プレーンテキストで記述された統計の説明
unit文字列統計値測定の単位またはレート
typeGAUGE または COUNTER統計測定値のタイプ
values type=INTEGER または DECIMALその後に続く統計値のデータタイプ
value複合型datum を含むデータセット
datumvalues type を参照value に含まれるデータの 1 つ
vm id=リレーションシップ格納している vm リソースとのリレーションシップ
以下の表には、仮想マシンの統計タイプをまとめています。

表15.12 仮想マシンの統計タイプ

名前
説明
memory.installed
仮想マシンが使用するために割り当てられたメモリー合計 (バイト単位)
memory.used
仮想マシンが現在使用中のメモリー (バイト単位)
cpu.current.guest
ゲストの CPU 使用率
cpu.current.hypervisor
Hypervisor 上の CPU オーバーヘッド (%)
cpu.current.total
現在の CPU 使用率合計

例15.44 仮想マシンの統計サブコレクションの XML 表現

<statistics>
    <statistic id="ef802239-b74a-329f-9955-be8fea6b50a4"
      href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401/
      statistics/ef802239-b74a-329f-9955-be8fea6b50a4">
        <name>memory.installed</name>
        <description>Total memory configured</description>
        <unit>BYTES</unit>
        <type>GUAGE</type>
        <values type="DECIMAL">
            <value>
                <datum>1073741824<datum>
            </value>
        </values>
        <vm id="cdc0b102-fbfe-444a-b9cb-57d2af94f401"
          href="/api/vms/cdc0b102-fbfe-444a-b9cb-57d2af94f401"/>
    </statistic>
    ...
</statistics>

注記

仮想マシンの statistics サブコレクションは読み取り専用です。

15.6.7. 仮想マシンのセッション情報の表示

仮想マシンに GET 要求を送信し、session サブコレクションを使用して、SPICE コンソールセッションを開始したユーザーと、仮想マシンにログインしたユーザーのセッション情報を表示します。
仮想マシンの session の情報は、サブコレクションとして表示されます。

例15.45 仮想マシンのセッション情報の表示

GET /api/roles/a1a701f1-aa06-4f02-af17-158be31489b3/sessions HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<sessions>
  <session id="37a6259c-c0c1-dae2-99a7-866489dff0bd"
    href= "/api/vms/a1a701f1-aa06-4f02-af17-158be31489b3/sessions/37a6259c-c0c1-dae2-99a7-866489dff0bd">
  <vm href= "/api/vms/a1a701f1-aa06-4f02-af17-158be31489b3" id="a1a701f1-aa06-4f02-af17-158be31489b3"/>
  <ip address="192.0.2.0"/>
  <user href= "/api/users/fdfc627c-d875-11e0-90f0-83df133b58cc" id="fdfc627c-d875-11e0-90f0-83df133b58cc">
    <domain href= "/api/domains/696e7465-726e-616c-696e-7465726e616c" id="696e7465-726e-616c-696e-7465726e616c">
      <name>internal</name>
    </domain>
    <user_name>admin</user_name>
    </user>
    <console_user>true</console_user>
  </session>
  <session id="37a6259c-c0c1-dae2-99a7-866489dff0bd"
    href= "/api/vms/a1a701f1-aa06-4f02-af17-158be31489b3/sessions/37a6259c-c0c1-dae2-99a7-866489dff0bd" >
    <vm href= "/api/vms/a1a701f1-aa06-4f02-af17-158be31489b3" id="a1a701f1-aa06-4f02-af17-158be31489b3"/>
    <user>
      <user_name>root</user_name>
    </user>
  </session>
</sessions>

15.7. アクション

15.7.1. 仮想マシンを起動するアクション

start のアクションは、停止、シャットダウン、またはサスペンドされている仮想マシンを起動します。

例15.46 仮想マシンを起動するアクション

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 要素を指定して start アクションを使用する操作は、管理ポータルやユーザーポータルで 1 回実行 ウィンドウを使用する操作と同じです。これらの設定は、ユーザーが仮想マシンが停止するまで維持されます。たとえば、このような要素には osdomainplacement_policycdromsstatelessdisplay type などが挙げられます。

例15.47 上書きされたパラメーターを使用して仮想マシンを起動するアクション

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_namepassword などの追加の user 認証情報がこの要素に必要になります。ドメインが domains コレクションに存在する場合は、アクションに user 認証情報は追加する必要はありません。
  • CD イメージとフロッピーディスクファイルはすでに ISO ドメインで利用できる状態でなければなりません。まだ用意されていない場合は、ISO アップローダーを使用してこれらのファイルをアップロードしてください。詳しい情報は ISO アプローダーツール を参照してください。

15.7.2. Cloud-Init アクションでの仮想マシンの起動

Cloud-Init は、仮想マシンの初期設定を自動化するツールです。このツールを使用して、ホスト名、ネットワークインターフェース、DNS サービス、承認キーの構成やユーザー名およびパスワードの設定を行います。また、custom_script タグを使用して、起動時に仮想マシンで実行するカスタムスクリプトを指定することも可能です。

注記

cloud-init 要素は、cloud-init パッケージがインストールされた仮想マシンを起動する際にだけ使用できます。cloud-init 要素を使用する場合は、initialization 要素内にあっても cloud-init 要素外の要素は無視されます。

例15.48 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. 仮想マシンを停止するアクション

stop のアクションは、仮想マシンの電源を強制的に切断します。

例15.49 仮想マシンを停止するアクション

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.50 仮想マシンにシャットダウン要求を送信するアクション

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

<action/>

15.7.5. 仮想マシンを一時停止するアクション

suspend のアクションは、仮想マシンの状態をディスクに保存してから仮想マシンを停止します。サスペンドされた仮想マシンを起動して仮想マシンの状態を復元するには、start アクションを使用します。

例15.51 仮想マシンの状態を保存してそのマシンを一時停止するアクション

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

<action/>

15.7.6. 仮想マシンを再起動するアクション

reboot アクションは仮想マシンに再起動要求を送信します。

例15.52 仮想マシンに再起動要求を送信するアクション

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

<action/>

15.7.7. 外部コンソールから仮想マシンへアクセスするためにユーザーログオンを有効にするアクション

logon アクションは、ユーザーが Red Hat Enterprise Virtualization 環境外のコンソールから仮想マシンにアクセスできるようにします。
このアクションは、rhevm-guest-agent-gdm-pluginrhevm-guest-agent-pam-module のパッケージがインストールされており、ovirt-guest-agent サービスが仮想マシンで稼働されている状態でなければなりません。
ユーザーは、外部のコンソールから仮想マシンにアクセスするには、その仮想マシンの適切なパーミッションが必要です。

例15.53 仮想マシンへのログイン

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

{}

15.7.8. 仮想マシンをプールからデタッチするアクション

detach のアクションは、仮想マシンをプールからデタッチします。

例15.54 仮想マシンをデタッチするアクション

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

<action/>

15.7.9. 仮想マシンを移行するアクション

migrate のアクションは、仮想マシンを別の物理ホストに移行します。Red Hat Enterprise Virtualization Manager は、デフォルトのホストを移行先として自動的に選択するので、移行先 host の要素はオプションとなっています。API ユーザーが特定の host を必要とする場合は、id または name いずれかのパラメーターでホストを指定することができます。

例15.55 別のホストに仮想マシンを移行するアクション

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. 仮想マシンの移行をキャンセルするアクション

cancel migration のアクションは、他の物理ホストへの仮想マシン移行を停止します。

例15.56 他のホストへの仮想マシン移行をキャンセルするアクション

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.57 仮想マシンをエクスポートストレージドメインにエクスポートするアクション

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.58 仮想マシンの認証トークンを生成するアクション

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. 仮想マシンを強制削除するアクション

障害のある仮想マシンを強制的に削除するには、force のアクションを使用します。このアクションには DELETE メソッドが必要です。要求の本文には force パラメーターを true に設定した action 表現を記載します。本文内の XML 表現を処理するには、要求に Content-type: application/xml ヘッダーを追加する必要もあります。

例15.59 仮想マシンに対する強制削除のアクション

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

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

15.7.14. 仮想マシンのファイルシステムのフリーズアクション

freezefilesystems アクションは、実行中の仮想マシンのライブスナップショットを作成する際に、QEMU ゲストエージェントを使用して仮想マシンのファイルシステムをフリーズします。通常、これは Manager で自動的に行われますが、OpenStack Volume (Cinder) ディスクを使用する仮想マシンには、REST API で手動で実行する必要があります。
ゲストのオペレーティングシステム上のファイルシステムをフリーズすることでスナップショットの一貫性を保ちます。スナップショットの作成が完了すると、ゲストのファイルシステムを解凍する必要があります。OpenStack Volume ディスクを使用しない仮想マシンでは、REST API を使用して手動でフリーズおよび解凍アクションを呼び出すこともできます。これは、スナップショットのプロセス中に失敗した場合などに有用な場合があります。

例15.60 仮想マシンのファイルシステムをフリーズするアクション

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

<action/>
スナップショットに関する詳しい情報は、『Red Hat Enterprise Virtualization 仮想マシン管理ガイド』の「スナップショットのサブコレクション」 または 「スナップショット」 のセクションを参照してください。

15.7.15. 仮想マシンのファイルシステムアクション

thawfilesystems アクションは、実行中の仮想マシンのライブスナップショットを作成する際に、QEMU ゲストエージェントを使用して仮想マシンのファイルシステムを解凍します。通常、これは Manager で自動的に行われますが、OpenStack Volume (Cinder) ディスクを使用する仮想マシンには、REST API で手動で実行する必要があります。
ゲストのオペレーティングシステム上のファイルシステムをフリーズすることでスナップショットの一貫性を保ちます。スナップショットの作成が完了すると、ゲストのファイルシステムを解凍する必要があります。OpenStack Volume ディスクを使用しない仮想マシンでは、REST API を使用して手動でフリーズおよび解凍アクションを呼び出すこともできます。これは、スナップショットのプロセス中に失敗した場合などに有用な場合があります。たとえば、仮想マシンの解凍中に応答がなくなった場合には、手動でもう一度解凍操作を実行することができます。手動でこの操作を行わない場合には仮想マシンの応答がない状態が継続されます。

例15.61 仮想マシンのファイルシステムを解凍するアクション

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

<action/>
スナップショットに関する詳しい情報は、『Red Hat Enterprise Virtualization 仮想マシン管理ガイド』の「スナップショットのサブコレクション」 または 「スナップショット」 のセクションを参照してください。

第16章 フローティングディスク

16.1. フローティングディスクの要素

disks コレクションは Red Hat Enterprise Virtualization 環境内の全ディスクについての情報を提供します。ユーザーは、ディスクと仮想マシンをアタッチ/デタッチしたり、仮想マシン間でフローティングさせることができます。 API ユーザーは、エンドポイント URL から取得した rel="disks" リンクでこの情報にアクセスします。
以下の表には、disks リソース表現に記載される特定の要素をまとめています。

表16.1 フローティングディスクの要素

要素タイプ説明プロパティー
link rel="statistics"リレーションシップ仮想マシンのディスクの統計を確認するための statistics サブコレクションへのリンク
image_idGUID定義されたストレージドメインに格納されている仮想マシンイメージへの参照
storage_domains複合型そのディスクと関連付けられたストレージドメイン。storage_domain 要素には 関連付けられたストレージドメインの GUID を示す id 属性が含まれます。データストレージドメイン間でのライブマイグレーションを実行するには、POST でこの要素を更新します。
size整数ディスクのサイズ (バイト単位)
provisioned_size整数プロビジョニングされたディスクのサイズ (バイト単位)
actual_size整数ディスクの実際のサイズ (バイト単位)
statusillegalinvalidlockedok のいずれかディスクデバイスのステータス。 これらのステータスは capabilities の下の disk_states に記載されています。
interface列挙型ディスクデバイスへの接続に使用するインターフェースドライバーのタイプ。使用できる列挙値の一覧は capabilities に記載されています。 
format列挙型下層のストレージのフォーマット。列挙値の一覧は capabilities に記載されています。Copy On Write (COW) により、最小限のパフォーマンスオーバーヘッドでスナップショットを作成することができます。Raw ではスナップショットは作成できませんが、パフォーマンスが向上します。
sparseブール値: true または falsetrue: 物理ストレージの場合に指定します。ディスクを事前割り当てすべきではないためです。
bootableブール値: true または falsetrue: ディスクがブート可能とマークされている場合に指定します。 
shareableブール値: true または falsetrue: 複数の仮想マシンで共有する場合に指定します。 
wipe_after_deleteブール値: true または falsetrue: ディスクが削除される時に下層の物理ストレージがゼロ処理される必要がある場合に指定します。これにより、セキュリティーが強化されますが、より負荷の高い操作であるため、削除に要する時間が伸びる可能性があります。 
propagate_errorsブール値: true または falsetrue: ディスクエラーによって仮想マシンが一時停止せず、代わりにディスクエラーがゲスト OS に伝達される必要がある場合に指定します。 
quota id=GUIDディスククォータを設定します。 
lunStorage複合型ストレージの使用状況を確認するための直接 LUN マッピングへの参照。iSCSI または FCP デバイスの詳細情報が含む storage 要素が必要。
activeブール値仮想マシンにディスクが接続されているかどうかを定義します。

重要

名前に基づいたディスクの検索クエリーには、name の代わりに alias 検索パラメーターが必要です。

16.2. フローティングディスクの XML 表現

例16.1 ディスクデバイスの XML 表現

<disk id="ed7feafe-9aaf-458c-809a-ed789cdbd5b4"
  href="/api/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4">
    <link rel="statistics"
      href="/api/disks/ed7feafe-9aaf-458c-809a-ed789cdbd5b4/statistics"/>  
    <storage_domains>
        <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
    </storage_domains> 
    <size>10737418240</size>
    <type>system</type>
    <status>
        <state>ok</state>
    </status>
    <interface>virtio</interface>
    <format>raw</format>
    <bootable>true</bootable>
    <shareable>true</shareable>
    <lunStorage>
        <storage>
            <logical_unit id="lun1">
                ...
            </logical_unit>
        <storage>
    </lunStorage>
</disk>

16.3. メソッド

16.3.1. フローティングディスクの作成

新規フローティングディスクを作成する際には、API は size および storage_domains の要素を必要とします。

例16.2 新規フローティングディスクデバイスの作成

POST /api/disks HTTP/1.1
Accept: application/xml
Content-type: application/xml

<disk>
    <storage_domains>
        <storage_domain id="fabe0451-701f-4235-8f7e-e20e458819ed"/>
    </storage_domains>        
    <size>8589934592</size>
    <type>system</type>
    <interface>virtio</interface>
    <format>cow</format>
</disk>

16.4. サブコレクション

16.4.1. 統計のサブコレクション

各フローティングディスクは、statistics サブコレクションでディスク固有の統計を公開します。各 statistic には以下のような要素が含まれます。

表16.2 仮想マシンディスク統計の要素

要素タイプ説明
name文字列統計エントリーの一意識別子
description文字列プレーンテキストで記述された統計の説明
unit文字列統計値測定の単位またはレート
typeGAUGE または COUNTER統計測定値のタイプ
values type=INTEGER または DECIMALその後に続く統計値のデータタイプ
value複合型datum を含むデータセット
datumvalues type を参照value に含まれるデータの 1 つ
disk id=リレーションシップ格納している disk リソースとのリレーションシップ
以下の表はフローティングディスクの統計タイプについてまとめています。

表16.3 ディスクの統計タイプ

名前
説明
data.current.read
ディスク読み込み時のデータ転送速度 (バイト/秒)
data.current.write
ディスク書き込み時のデータ転送速度 (バイト/秒)

例16.3 仮想マシンの統計サブコレクションの XML 表現

<statistics>
    <statistic id="33b9212b-f9cb-3fd0-b364-248fb61e1272"
      href="/api/disks/f28ec14c-fc85-43e1-818d-96b49d50e27b/statistics/
      33b9212b-f9cb-3fd0-b364-248fb61e1272">
        <name>data.current.read</name>
        <description>Read data rate</description>
        <values type="DECIMAL">
            <value>
                <datum>0</datum>
            </value>
        </values>
        <type>GAUGE</type>
        <unit>BYTES_PER_SECOND</unit>
        <disk id="f28ec14c-fc85-43e1-818d-96b49d50e27b" 
          href="/api/disks/f28ec14c-fc85-43e1-818d-96b49d50e27b"/>
    </statistic>
    ...
</statistics>

注記

上記の statistics サブコレクションは読み取り専用です。

16.5. アクション

16.5.1. フローティングディスクのコピー

フローティングディスクをコピーする際には、API は storage_domain 要素を必要とします。オプションの name 要素で、ディスクのエイリアスを指定します。

例16.4 フローティングディスクのコピー

POST /api/disks/54a81464-b758-495a-824b-1e7937116ae5/copy HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <storage_domain id="c8e108f7-c049-40d2-ad3d-620e4638828e"/>
    <disk>
        <name>rhel_disk2</name>
    </disk>
</action>

第17章 テンプレート

17.1. 仮想マシンテンプレートの要素

templates コレクションは、Red Hat Enterprise Virtualization 環境内の仮想マシンテンプレートに関する情報を提供します。API ユーザーは、エントリーポイント URL から取得した rel="templates" リンクでこの情報にアクセスします。
GET 要求に関する追加の情報は、All-Content: true ヘッダーを使用して取得することができます。
以下の表には、仮想マシンのテンプレートリソースの表現に含まれる特定の要素をまとめています。

表17.1 仮想マシンテンプレートの要素

要素タイプ説明プロパティー
link rel="disks"リレーションシップ仮想マシンテンプレートリソースの disks サブコレクションのリンク
link rel="nics"リレーションシップ仮想マシンテンプレートリソースの nics サブコレクションへのリンク 
link rel="cdroms"リレーションシップ仮想マシンテンプレートリソースの cdroms サブコレクションへのリンク
link rel="permissions"リレーションシップ仮想マシンテンプレートパーミッションの permissions サブコレクションへのリンク 
type列挙型テンプレートが提供する仮想マシンのタイプ。列挙値の一覧は capabilities に記載されています。
statusillegallockedok のいずれかテンプレートのステータス。これらのステータスは capabilities の下の template_states に記載されています。
memory整数ゲストに割り当てられたメモリーの容量 (バイト単位)
cpu複合型ゲストが使用できる CPU topology (sockets 数および cores 数)
os type=文字列 (例: RHEL5WindowsXP)ゲストのオペレーティングシステムのタイプ
os boot dev=列挙型boot 要素の dev 属性によって記述される起動デバイスの一覧。 列挙値の一覧は capabilities に記載されています。
os kernel文字列テンプレートで起動元として設定されているカーネルイメージへのパス 
os initrd文字列上記のカーネルと併用する initrd イメージへのパス 
os cmdline文字列上記のカーネルと併用するカーネルコマンドラインパラメーターの文字列 
cluster id=GUIDテンプレートのホストクラスターへの参照
vm id=GUIDそのテンプレートのベースとなっている仮想マシンへの参照
domain id=GUIDそのテンプレートのドメインへの参照
creation_timexsd:dateTime の形式: YYYY-MM-DDThh:mm:ssそのテンプレートが作成された日付と時刻
originrhevovirtvmwarexen のいずれかそのテンプレートの元となったシステム
high_availability複合型ホストがクラッシュした場合に仮想マシンを自動的に再起動させるには、enabledtrue に設定します。仮想マシンの再起動順序は priority 要素によって制御されます。 
display複合型ディスプレイの type (vnc または spice)、ポート、および monitors 数。allow_reconnect のブール値は、クライアントがディスプレイを介して再接続可能かどうかを指定します。 
statelessブール値: true または falseステートレスのテンプレートには、そのディスクイメージのスナップショットが含まれます。スナップショットはブート時に作成され、シャットダウン時に削除されるので、状態の変更は、再起動後には無効となります。
usb複合型仮想マシンテンプレートの USB ポリシーを定義します。enabled 要素をブール値に設定し、type 要素を native または legacy に設定する必要があります。 
placement_policy複合型仮想マシン移行の配置ポリシーを設定します。デフォルトの host=affinity (migratableuser_migratablepinned のいずれか) が必要です。host 要素を空白にすると、優先ホストなしの設定になります。 
custom_properties複合型パラメーターとしてカスタムのスクリプトに渡される、ユーザー定義の環境変数セット。各 custom_property には name および value の属性が含まれます。列挙値の一覧は capabilities に記載されています。 
timezonetz データベース形式: Area/LocationWindows 仮想マシンテンプレートに設定する Sysrprep タイムゾーン 
domain複合型Windows 仮想マシンのテンプレート用の Sysprep ドメイン設定。domains コレクションからの name が必要です。 

17.2. 仮想マシンのテンプレートの XML 表現

例17.1 仮想マシンのテンプレートの XML 表現

<template href="/api/templates/00000000-0000-0000-0000-000000000000"
  id="00000000-0000-0000-0000-000000000000">
    <actions>
        <link href="/api/templates/00000000-0000-0000-0000-000000000000/export"
          rel="export"/>
    </actions>
    <name>Blank</name>
    <description>Blank template</description>
    <comment>Blank template</comment>
    <link href="/api/templates/00000000-0000-0000-0000-000000000000/disks"
      rel="disks"/>
    <link href="/api/templates/00000000-0000-0000-0000-000000000000/nics" 
      rel="nics"/>
    <link href="/api/templates/00000000-0000-0000-0000-000000000000/cdroms"
      rel="cdroms"/>
    <link href="/api/templates/00000000-0000-0000-0000-000000000000/permissions" 
      rel="permissions"/>
    <link href="/api/templates/00000000-0000-0000-0000-000000000000/watchdogs" 
      rel="watchdogs"/>
    <type>server</type>
    <status>
        <state>ok</state>
    </status>
    <memory>536870912</memory>
    <cpu>
        <topology sockets="1" cores="1"/>
        <architecture>X86_64<architecture/>
    </cpu>
    <cpu_shares>0</cpu_shares>
    <os type="rhel_6x64">
        <boot dev="hd"/>
        <boot dev="cdrom"/>;
    </os>
    <cluster id="00000000-0000-0000-0000-000000000000"
      href="/api/clusters/00000000-0000-0000-0000-000000000000"/>
    <creation_time>2010-08-16T14:24:29</creation_time>
    <origin>ovirt</origin>
    <high_availability>
        <enabled>true</enabled>
        <priority>100</priority>
    </high_availability>
    <display>
        <type>spice</type>
        <monitors>1</monitors>
        <single_qxl_pci>false</single_qxl_pci>
        <allow_override>true</allow_override>
        <smartcard_enabled>true</smartcard_enabled>
    </display>
    <stateless>false</stateless>
    <delete_protected>false</delete_protected>
    <sso>
      <methods>
        <method id="GUEST_AGENT">true</enabled>
      </methods>
    </sso>
    <usb>
        <enabled>true</enabled>
    </usb>
    <migration_downtime>-1</migration_downtime>
    <version>
      <base_template href="/api/templates/00000000-0000-0000-0000-000000000000"
        id="00000000-0000-0000-0000-000000000000"/>
      <version_number>2</version_number>
      <version_name>RHEL65_TMPL_001</version_name>
    </version>
</template>

17.3. メソッド

17.3.1. 新規のテンプレートの作成

新規テンプレートの作成には、name 要素と vm 要素が必要です。vmid 属性または name 要素で特定します。

例17.2 仮想マシンからのテンプレート作成

POST /api/templates HTTP/1.1
Accept: application/xml
Content-type: application/xml

<template>
    <name>template1</name>
    <vm id="00000000-0000-0000-0000-000000000000"/>
</template>

17.3.2. 新しいテンプレートのサブバージョンの作成

新しいテンプレートのサブバージョンを作成するには、新規テンプレートの namevm の要素、新規テンプレートバージョンの base_templateversion_name の要素が必要です。base_templateversion_name の要素は、template セクションの version セクション内に指定する必要があります。id 属性または name 要素で vm を特定します。

例17.3 仮想マシンからのテンプレートのサブバージョンの作成

POST /api/templates HTTP/1.1
Accept: application/xml
Content-type: application/xml

<template>
  <name>template1_001</name>
  <vm id="00000000-0000-0000-0000-000000000000"/>
  <version>
    <base_template id="00000000-0000-0000-0000-000000000000"/>
    <version_name>"template1_001"</version_name>
  </version>
</template>

17.3.3. テンプレートの更新

namedescriptiontypememorycpu topologyoshigh_availabilitydisplaystatelessusbtimezone の要素はテンプレート作成後に更新できます。

例17.4 仮想マシンのテンプレートのメモリーを 1 GB に更新

PUT /api/templates/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<template>
    <memory>1073741824</memory>
</template>

17.3.4. テンプレートのサブバージョンの更新

テンプレートのサブバージョンが作成されてから更新できるのは、version_name 要素のみです。

例17.5 仮想マシンのテンプレートのサブバージョン名の更新

PUT /api/templates/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<template>
  <version>
    <version_name>template1_002</version_name>
  </version>
</template>

17.3.5. テンプレートの削除

仮想マシンテンプレートの削除には DELETE が必要です。

例17.6 仮想マシンテンプレートの削除

DELETE /api/templates/00000000-0000-0000-0000-000000000000 HTTP/1.1

HTTP/1.1 204 No Content

17.4. アクション

17.4.1. テンプレートをエクスポートするアクション

templates コレクションには export アクションが含まれています。
エクスポートのアクションは、テンプレートを Export ストレージドメインにエクスポートします。エクスポート先のストレージドメインは、storage_domain 参照で指定されます。
エクスポートのアクションは、同じ名前の仮想マシンテンプレートがエクスポート先のドメインに存在する場合に、操作が失敗したことを報告します。この動作を変更して、既存の仮想マシンテンプレートを上書きするには、exclusive パラメーターを true に設定します。

例17.7 エクスポートストレージドメインにテンプレートをエクスポートするアクション

POST /api/templates/00000000-0000-0000-0000-000000000000/export HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
    <storage_domain id="00000000-0000-0000-0000-000000000000"/>
    <exclusive>true<exclusive/>
</action>

第18章 仮想マシンのプール

18.1. 仮想マシンプールの要素

vmpools コレクションは、Red Hat Enterprise Virtualization 環境内の仮想マシンプールに関する情報を提供します。API ユーザーは、エントリーポイント URL から取得した rel="vmpools" リンクでこの情報にアクセスします。
以下の表には、仮想マシンプールのリソース表現に含まれる特定の要素をまとめています。

表18.1 仮想マシンプールの要素

要素タイプ説明プロパティー
name文字列ユーザーによって提供される、人間が判読できるプール名。 name はそのタイプの全プールリソースで一意です。
description文字列ユーザーによって提供される、人間が判読できる仮想マシンプールの説明 
link rel="permissions"リレーションシップ仮想マシンテンプレートプールパーミッションの permissions サブコレクションへのリンク 
size整数プール内の仮想マシン数
cluster id=GUIDそのプール内の仮想マシンが実行しているクラスターリソースへの参照
template id=GUIDそのプール内の仮想マシンのベースとなっているテンプレートリソースへの参照
prestarted_vms整数仮想マシンプール内で事前に起動される仮想マシンの数 
max_user_vms整数仮想マシンプールから 1 ユーザーが取得できる仮想マシンの最大数 

重要

API は、本章に記載した時点では試験段階にあり、今後変更される可能性があるため、後方互換性に関する記載内容は適用されません。

18.2. 仮想マシンプールの XML 表現

例18.1 仮想マシンプールの XML 表現

<vmpool href="/api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e">
  id="2d2d5e26-1b6e-11e1-8cda-001320f76e8e"
    <actions>
    	<link href="/api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e/allocatevm"
    	  rel="allocatevm"/>
    </actions>
    <name>VMPool1</name>
    <description>Virtual Machine Pool 1</description>
    <size>2</size>
    <cluster href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
      id="99408929-82cf-4dc7-a532-9d998063fa95"
    <template href="/api/templates/00000000-0000-0000-0000-000000000000"/>
      id="00000000-0000-0000-0000-000000000000"
    <prestarted_vms>0</prestarted_vms>
    <max_user_vms>1</max_user_vms>
</vmpool>

18.3. メソッド

18.3.1. 新規仮想マシンプールの作成

新規のプールには nameclustertemplate の各要素が必要です。cluster および templateid 属性または name 要素で特定します。

例18.2 仮想マシンプールの作成

POST /api/vmpools HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vmpool>
    <name>VM_Pool_A</name>
    <cluster href="/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95"/>
      id="99408929-82cf-4dc7-a532-9d998063fa95"
    <template href="/api/templates/00000000-0000-0000-0000-000000000000"/>
      id="00000000-0000-0000-0000-000000000000"
</vmpool>

18.3.2. 仮想マシンプールの更新

namedescriptionsizeprestarted_vms、および max_user_vms は、仮想マシンの作成後に更新することができます。

例18.3 仮想マシンプールの更新

PUT /api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vmpool>
    <name>VM_Pool_B</name>
    <description>Virtual Machine Pool B</description>
    <size>3</size>
    <prestarted_vms>1</size>
    <max_user_vms>2</size>
</vmpool>

18.3.3. 仮想マシンプールの削除

仮想マシンを削除するには DELETE 要求を実行する必要があります。

例18.4 仮想マシンの削除

DELETE /api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e HTTP/1.1

HTTP/1.1 204 No Content

18.4. アクション

18.4.1. 仮想マシンを割り当てるアクション

仮想マシンを割り当てるアクションは、仮想マシンプール内の仮想マシンを割り当てます。

例18.5 仮想マシンプールから仮想マシンを割り当てるアクション

POST /api/vmpools/2d2d5e26-1b6e-11e1-8cda-001320f76e8e/allocatevm HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action/>

第19章 ドメイン

19.1. ドメインの要素

API は、domains コレクションを使用して、組織のディレクトリーサービスからユーザーおよびグループの情報にアクセスする機能を提供します。ドメイン情報は rel="domains" リンクで参照します。

表19.1 ドメインの要素

要素タイプ説明
name文字列ドメイン名
link rel="users"リレーションシップそのドメインに関連付けられたユーザーのサブコレクションへのリンク
link rel="groups"リレーションシップそのドメインに関連付けられたグループのサブコレクションへのリンク
users サブコレクションおよび groups サブコレクションへのリンクは、検索クエリーも受け入れます。

注記

domains コレクションとそのサブコレクションは読み取り専用です。

19.2. ドメインリソースの XML 表現

例19.1 ドメインリソースの XML 表現

<domain id="77696e32-6b38-7268-6576-2e656e676c61"
  href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61">
    <name>domain.example.com</name>
    <link rel="users"
      href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/users"/>
    <link rel="groups"
      href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/groups"/>
    <link rel="users/search"
      href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/
      users?search={query}"/>
    <link rel="groups/search"
      href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/
      groups?search={query}"/>
</domain>

19.3. サブコレクション

19.3.1. ドメインユーザーのサブコレクション

users サブコレクションには、ディレクトリーサービス内の全ユーザーが含まれます。この情報は Red Hat Enterprise Virtualization 環境に新規ユーザーを追加する際に使用されます。

表19.2 ドメインユーザーの要素

要素タイプ説明
name文字列ユーザー名
last_name文字列ユーザーの姓
user_name文字列ディレクトリーサービスからのユーザー名
domain idGUID格納しているディレクトリーサービスドメイン
groups複合型そのユーザーのディレクトリーサービスグループの一覧

例19.2 ユーザーサブコレクション内のユーザーの XML 表現

<user id="225f15cd-e891-434d-8262-a66808fcb9b1"
  href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/users/
  d3b4e7be-5f57-4dac-b937-21e1771a501f">
    <name>RHEV-M Admin</name>
    <user_name>rhevmadmin@domain.example.com</user_name>
    <domain id="77696e32-6b38-7268-6576-2e656e676c61"
      href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61"/>
    <groups>
        <group>
            <name>domain.example.com/Users/Enterprise Admins</name>
        </group>
        <group>
            <name>domain.example.com/Users/Domain Admins</name>
        </group>
        ...
    </groups>
</user>

19.3.2. ドメイングループのサブコレクション

groups サブコレクションには、ディレクトリーサービス内の全グループが含まれます。ドメイン group のリソースには複数の要素セットが含まれます。

表19.3 ドメイングループの要素

要素タイプ説明
name文字列グループ名
domain idGUID格納しているディレクトリーサービスドメイン

例19.3 グループサブコレクション内のグループの XML 表現

<group id="85bf8d97-273c-4a5c-b801-b17d58330dab"
  href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61/groups/
  85bf8d97-273c-4a5c-b801-b17d58330dab">
    <name>example.com/Users/Enterprise Admins</name>
    <domain id="77696e32-6b38-7268-6576-2e656e676c61"
      href="/api/domains/77696e32-6b38-7268-6576-2e656e676c61"/>
</group>

第20章 グループ

20.1. インポートしたグループの要素

groups コレクションには、ディレクトリーサービスからインポートしたグループが含まれます。group リソースには一連の要素が含まれます。

表20.1 インポートしたグループの要素

要素タイプ説明
link rel="tags"リレーションシップそのグループにアタッチしたタグの tags サブコレクションへのリンク
link rel="permissions"リレーションシップそのグループにアタッチしたパーミッションの permissions サブコレクションへのリンク
link rel="roles"リレーションシップそのグループにアタッチされたロールの roles サブコレクションへのリンク

20.2. グループリソースの XML 表現

例20.1 グループリソースの XML 表現

<group id="85bf8d97-273c-4a5c-b801-b17d58330dab"
  href="/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab">
    <name>Everyone</name>
    <link rel="tags"
      href="/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab/tags"/>
    <link rel="permissions"
      href="/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab/permissions"/>
    <link rel="roles"
      href="/api/groups/85bf8d97-273c-4a5c-b801-b17d58330dab/roles"/>
    <domain_entry_id>
          65656530303030302D303030302D303030302D303030
    </domain_entry_id>
    <namespace>*</namespace>
</group>

20.3. ディレクトリーサービスからのグループの追加

API は、groups コレクションに POST 要求を送信して、既存のディレクトリーサービスグループを Red Hat Enterprise Virtualization Manager データベースに追加します。

例20.2 ディレクトリーサービスからのグループの追加

POST /api/group HTTP/1.1
Content-Type: application/xml
Accept: application/xml

<group>
    <name>www.example.com/accounts/groups/mygroup</name>
    <domain> 
     <name>example.com</name>
    </domain> 
</group>

第21章 ロール

21.1. ロールの要素

エントリーポイント URI から取得する rel="roles" リンクを使用してシステムロールの静的なセットにアクセスします。各 role 要素には以下が含まれます。

表21.1 ロールの要素

要素タイプ説明プロパティー
link="permits"リレーションシップロール permit の permits サブコレクションへのリンク
mutableブール値: true または falseロールの更新/削除が可能であるかどうかを定義します。mutablefalse に指定されたロールは、Red Hat Enterprise Virtualization 環境に組み込まれているロールです。
administrativeブール値: true または falseロールを管理者限定とするかどうかを定義します。

21.2. ロールコレクションの XML 表現

例21.1 ロールコレクションの XML 表現

<roles>
    <role id="00000000-0000-0000-0000-000000000001"
      href="/api/roles/00000000-0000-0000-0000-000000000001">
        <name>SuperUser</name>
        <description>Roles management administrator</description>
        <link rel="permits"
          href="/api/roles/00000000-0000-0000-0000-000000000001/permits"/>
        <mutable>false</mutable>
        <administrative>true</administrative>
    </role>
    <role id="00000000-0000-0000-0001-000000000001"
      href="/api/roles/00000000-0000-0000-0001-000000000001">
        <name>RHEVMUser</name>
        <description>RHEVM user</description>
        <link rel="permits"
          href="/api/roles/00000000-0000-0000-0001-000000000001/permits"/>
        <mutable>false</mutable>
        <administrative>false</administrative>
    </role>
    <role id="00000000-0000-0000-0001-000000000002"
       href="/api/roles/00000000-0000-0000-0001-000000000002">
        <name>RHEVMPowerUser</name>
        <description>RHEVM power user</description>
        <link rel="permits"
          href="/api/roles/00000000-0000-0000-0001-000000000002/permits"/>
        <mutable>false</mutable>
        <administrative>false</administrative>
    </role>
</roles>

21.3. メソッド

21.3.1. ロールの作成

ロールの作成には、nameadministrative、および初期の permits 一覧が必要です。

例21.2 ロールの作成

POST /api/roles HTTP/1.1
Accept: application/xml
Content-type: application/xml

<role>
    <name>Finance Role</name>
    <administrative>true</administrative>
    <permits>
        <permit id="1"/>
    </permits>
</role>

21.3.2. ロールの更新

namedescriptionadministrative の各要素は、作成後に更新が可能です。

例21.3 ロールの更新

PUT /api/roles/8de42ad7-f307-408b-80e8-9d28b85adfd7 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<role>
    <name>Engineering Role</name>
    <description>Standard users in the Engineering Role</description>
    <administrative>false</administrative>
</role>

21.3.3. ロールの削除

ロールを削除するには、DELETE 要求を実行する必要があります。

例21.4 ロールの削除

DELETE /api/roles/8de42ad7-f307-408b-80e8-9d28b85adfd7 HTTP/1.1

HTTP/1.1 204 No Content

21.4. ロールの permits のサブコレクション

21.4.1. ロールの permits のサブコレクション

各ロールには、許可されるアクション (permits) のセットが含まれ、API では、capabilities 内に記載されています。
ロールの permits はサブコレクションとして記載されます。

例21.5 ロールの permit の一覧表示

GET /api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<permits>
    <permit id="1"
      href="/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1">
        <name>create_vm</name>
        <administrative>false</administrative>
        <role id="b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"
          href="/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"/>
    </permit>
    ...
</permits>

21.4.2. ロールへの permit の割り当て

permit を割り当てるには、permits サブコレクションに対して POST 要求を実行します。id 属性または name 要素を使用して割り当てる permit を指定します。

例21.6 ロールへの permit の割り当て

POST /api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<permit id="1"/>

HTTP/1.1 201 Created
Content-Type: application/xml

<permits>
    <permit id="1"
      href="/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1">
        <name>create_vm</name>
        <administrative>false</administrative>
        <role id="b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"
          href="/api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9"/>
    </permit>
</permits>

21.4.3. ロールからの permit の削除

ロールから permit を削除するには、permit リソースに対して DELETE 要求を実行します。

例21.7 ロールからの permit の削除

DELETE /api/roles/b67dfbe2-0dbc-41e4-86d3-a2fbef02cfa9/permits/1 HTTP/1.1

HTTP/1.1 204 No Content

第22章 ユーザー

22.1. ユーザーの要素

ユーザーはトップレベルのコレクションで公開され、rel="users" リンクで参照されます。各 user 要素には以下の項目が含まれます。

表22.1 ユーザーの要素

要素タイプ説明プロパティー
user_name文字列ユーザープリンシパル名 (UPN)。UPN は、新規ユーザーを追加する際に、より利便性の高い識別子として使用されます。
link rel="tags"リレーションシップユーザーリソースの tags サブコレクションへのリンク 
link rel="roles"リレーションシップユーザーリソースの roles サブコレクションへのリンク 
name文字列自由形式のユーザー名
domain文字列格納しているディレクトリーサービスドメイン
groups複合型そのユーザーのディレクトリーサービスグループの一覧

22.2. ユーザーリソースの XML 表現

例22.1 ユーザーリソースの XML 表現

GET /api/users HTTP/1.1
Accept: application/xml

<user id="225f15cd-e891-434d-8262-a66808fcb9b1"
  href="/api/users/225f15cd-e891-434d-8262-a66808fcb9b1">
    <name>RHEV-M Admin</name>
    <actions/>
    <link rel="roles"
      href="/api/users/225f15cd-e891-434d-8262-a66808fcb9b1/roles"/>
    <link rel="tags"
      href="/api/users/225f15cd-e891-434d-8262-a66808fcb9b1/tags"/>
    <domain>domain.example.com</domain>
    <logged_in>false</logged_in>
    <user_name>rhevmadmin@domain.example.com</user_name>
    <groups>
        <group>Group Policy Creator Owners@domain.example.com/Users</group>
        <group>Domain Admins@domain.example.com/Users</group>
        <group>Enterprise Admins@domain.example.com/Users</group>
        <group>Schema Admins@domain.example.com/Users</group>
        <group>Administrators@domain.example.com/Builtin</group>
    </groups>
</user>

22.3. メソッド

22.3.1. ユーザーの追加

API は、users コレクションへの POST 要求を使用して 既存のディレクトリーサービスのユーザーを Red Hat Enterprise Virtualization Manager のデータベースに追加します。新規ユーザーの表現には 埋め込まれた roles の一覧が含まれ、ユーザーに割り当てるための初期 role が少なくとも 1 つ記載されています。たとえば、以下の要求は、2 つの初期ロールをユーザー joe@domain.example.com に割り当てます。

例22.2 ディレクトリーサービスからのユーザーと 2 つのロールの割り当て

POST /api/users HTTP/1.1
Content-Type: application/xml
Accept: application/xml

<user>
    <user_name>joe@domain.example.com</user_name>
    <roles>
        <role>
            <name>RHEVMPowerUser</name>
        </role>
        <role id="00000000-0000-0000-0001-000000000003"/>
    </roles>
</user>
新規ユーザーは、Red Hat Enterprise Virtualization Manager ユーザー ID またはディレクトリーサービスのユーザープリンシパル名 (UPN) のいずれかで特定します。ディレクトリーサービスドメインから報告されるユーザー ID の形式は、LDIF [5]などの Red Hat Enterprise Virtualization Manager で想定される形式とは異なる可能性があり、その場合には、ID のバイト順が逆で base-64 エンコードされています。したがって、通常は UPN で新規ユーザーを参照する方が便利です。

注記

Red Hat Enterprise Virtualization Manager のデータベースにユーザーを追加する前に、そのユーザーがディレクトリーサービスドメインに存在している必要があります。API ユーザーは、ユーザー作成の前に domains コレクションでこのドメインにクエリーを実行するオプションを使用することができます。
ロールは、名前または ID のいずれかで特定します。上記では、両方を方法を示しています。

22.3.2. ユーザーへのロールの追加

追加のロールをアタッチまたはデタッチする場合は、各ユーザーのロールのサブコレクションに対して POST または DELETE 要求を実行します。 以下の例では、RHEVMVDIUser ロールを特定ユーザーのロール割り当てに追加する方法を示しています。

注記

user の埋め込まれたユーザーロール一覧は、初回の作成時にのみ使用されます。作成後のユーザーロール割り当てとの対話は、roles サブコレクションを通して行われます。

例22.3 ユーザーへのロールの追加

POST /api/users/225f15cd-e891-434d-8262-a66808fcb9b1/roles HTTP/1.1
Content-Type: application/xml
Accept: application/xml

<role>
    <name>RHEVMVDIUser</name>
</role>


[5] LDAP Data Interchange Format については RFC 2849 に説明が記載されています。

第23章 タグ

23.1. タグの要素

tags コレクションは、Red Hat Enterprise Virtualization 環境内のタグに関する情報を提供します。API ユーザーは、エントリーポイント URL から取得した rel="tags" リンクでこの情報にアクセスします。
次の表には、タグリソースの表現内に含まれる特定の要素をまとめています。

表23.1 タグの要素

要素タイプ説明プロパティー
hostGUIDタグがアタッチされているホストへの参照
userGUIDタグがアタッチされているユーザーへの参照
vmGUIDタグがアタッチされている仮想マシンへの参照
parent複合型タグがアタッチされている仮想マシンへの参照 

23.2. タグリソースの XML 表現

例23.1 タグリソースの XML 表現

<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
  href="/api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
    <name>Finance</name>
    <description>Resources for the Finance department</description>
    <parent>
        <tag id="-1" href="/api/tags/-1"/>
    </parent>
</tag>

23.3. タグの関連付け

23.3.1. ホスト、ユーザー、仮想マシンへのタグの関連付け

hostuser、または vmslink rel="tags" によって参照されるコレクションは、そのエンティティーに関連付けられたタグセットを示します。
これらの tag 表現には、対象となるエンティティーへの host iduser idvm id 参照も含まれます。
エンティティーへのタグの関連付けは、コレクションに対してタグ参照を POST (id または name のいずれかでタグを特定) することによって行います。

例23.2 仮想マシンへのタグの関連付け

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

<tag>
    <name>Finance</name>
</tag>

HTTP/1.1 201 Created
Content-Type: application/xml

<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
  href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags/
  f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
    <name>Finance</name>
    <description>Resources for the Finance department</description>
    <vm id="5114bb3e-a4e6-44b2-b783-b3eea7d84720"
      href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/>
</tag>

23.3.2. タグの削除

タグの関連付けを削除するには、コレクション内の適切な要素に対して DELETE 要求を実行します。

例23.3 仮想マシンからのタグ削除

DELETE /api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e HTTP/1.1

HTTP/1.1 204 No Content

23.3.3. タグ付けしたリソースのコレクションに対するクエリーの実行

特定のタグに関連付けられたリソースセットに対してクエリーを実行する場合は、適切なコレクションの collection/search URI テンプレートを使用して tag=MyTag に一致するエンティティーの検索を行います。

例23.4 タグ付けしたリソースのコレクションに対するクエリーの実行

GET /api/vms?search=tag%3DFinance HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<vms>
    <vm id="5114bb3e-a4e6-44b2-b783-b3eea7d84720"
      href="/api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720">
        ...
    </vm>
    ...
</vms>

23.4. 親タグ

23.4.1. 親タグ

API ユーザーは、parent 要素をタグに割り当てて親タグに対して階層リンクを作成することができます。タグは、root タグを基点とする非階層的なコレクションとして表示されます。各タグ表現には親タグへのリンク要素が含まれます。

注記

root タグは、親タグが指定されていない場合にはデフォルトの親タグと仮定される特殊な擬似タグです。root タグは削除したり、親タグを割り当てることはできません。
このタグは次のように表現します。

例23.5 タグの階層

<tags>
    <tag id="-1" href="/api/tags/-1">
        <name>root</name>
        <description>root</description>
        <parent>
            <tag id="-1" href="/api/tags/-1"/>
        </parent>
    </tag>
    <tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
      href="/api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
        <name>Finance</name>
        <description>Resources for the Finance department</description>
        <parent>
            <tag id="-1" href="/api/tags/-1"/>
        </parent>
    </tag>
    <tag id="ac18dabf-23e5-12be-a383-a38b165ca7bd"
      href="/api/tags/ac18dabf-23e5-12be-a383-a38b165ca7bd">
        <name>Billing</name>
        <description>Billing Resources</description>
        <parent>
            <tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
              href="/api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"/>
        </parent>
    </tag>
</tags>
この XML 表現では、タグの階層は以下のようになります。
root              (id: -1)
  - Finance       (id: f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e)
      - Billing   (id: ac18dabf-23e5-12be-a383-a38b165ca7bd)

23.4.2. 親タグの設定

parent 要素を指定した新規タグを POST すると、親タグに関連付けられます。これには、id 属性または name 要素を使用します。

例23.6 ID 属性を使用した親タグとの関連付けの設定

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

HTTP/1.1 200 OK
Content-Type: application/xml

<tag>
    <name>Billing</name>
    <description>Billing Resources</description>
    <parent>
        <tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"/>
    </parent>
</tag>

例23.7 name 要素を使用した親タグとの関連付けの設定

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

HTTP/1.1 200 OK
Content-Type: application/xml

<tag>
    <name>Billing</name>
    <description>Billing Resources</description>
    <parent>
        <tag>
            <name>Finance</name>
        </tag>
    </parent>
</tag>

23.4.3. 親タグの変更

親の変更はタグで PUT 要求を使用して行います。

例23.8 親タグの変更

PUT /api/tags/ac18dabf-23e5-12be-a383-a38b165ca7bd HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<tag>
    <parent>
        <tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"/>
    </parent>
</tag>

第24章 イベント

24.1. イベントの要素

エントリーポイント URI から取得した rel="events" リンクは events コレクションにアクセスし、Red Hat Enterprise Virtualization Manager からのシステムイベントを表示します。

表24.1 イベントの要素

要素タイプ説明
description文字列システムイベントの説明
code整数整数型のイベントコード
severitynormalwarningerroralert のいずれかイベントの重大度レベル
timexsd:dateTime の形式: YYYY-MM-DDThh:mm:ssイベントが発生した日時を示すタイムスタンプ
correlation_id文字列Red Hat Enterprise Virtualization の複数の層にまたがるアクションの ID 文字列
user id=GUIDイベントをトリガーしたユーザーの ID コード
origin文字列イベントのソース。標準のイベントは oVirt によりレポートされます。
custom_id整数カスタムイベントのカスタムの ID 番号。標準イベントの custom_id-1 です。
flood_rate整数イベント一覧内に同じイベントが再発できないようにする時間 (秒)。デフォルトの値は、30 です。
external_status複合型ホストの外部ヘルスステータス。これには state 要素が含まれており、この要素には okinfoerrorwarningfailure のいずれかを指定することができます。

24.2. イベントコレクションの XML 表現

例24.1 イベントコレクションの XML 表現

<events>
    <event id="537" href="/api/events/537">
        <description>User vdcadmin logged in.</description>
        <code>30</code>
        <severity>normal</severity>
        <time>2011-01-12T10:48:27.827+02:00</time>
        <user id="9b9002d1-ec33-4083-8a7b-31f6b8931648"
          href="/api/users/9b9002d1-ec33-4083-8a7b-31f6b8931648"/>
    </event>
    ...
</events>

24.3. 仮想マシン作成イベントの XML 表現

event 表現には、user に加えて、イベントに関連したリソースに対する XML 要素のリレーションシップも記載されます。

例24.2 仮想マシン作成イベントの XML 表現

<event id="635" href="/api/events/635">
    <description>VM bar was created by rhevadmin.</description>
    <code>34</code>
    <severity>normal</severity>
    <time>2011-07-11T16:32:03.172+02:00</time>
    <user id="4621b611-43eb-4d2b-ae5f-1180850268c4"
      href="/api/users/4621b611-43eb-4d2b-ae5f-1180850268c4"/>
    <vm id="9b22d423-e16b-4dd8-9c06-c8e9358fbc66"
      href="/api/vms/9b22d423-e16b-4dd8-9c06-c8e9358fbc66"/>
    <storage_domain id="a8a0e93d-c570-45ab-9cd6-3c68ab31221f"
      href="/api/storagedomains/a8a0e93d-c570-45ab-9cd6-3c68ab31221f"/>
</event>
上記の表現は、仮想マシンリソースおよびストレージドメインリソースに対するXML 要素のリレーションシップを示した例です。

24.4. メソッド

24.4.1. イベントの検索

events コレクションは、他のリソースコレクションと同様の検索クエリーを提供します。events コレクションを検索する際には、特定のイベント以降のイベントを検索する追加機能があります。これにより、指定されたイベント以降の全イベントに対するクエリーを実行することができます。
イベントからクエリーを実行するには、検索クエリーの前に from パラメーターを追加する必要があります。この from 引数はイベント id コードを参照します。

例24.3 指定したイベント以降のイベントを対象とする検索

GET /api/events;from=1012?search=type%3D30 HTTP/1.1
Accept: application/xml
id="1012" 以降で、type が 30 に指定されたイベントをすべて表示します。
HTTP/1.1 200 OK
Content-Type: application/xml
<events>
    <event id="1018" href="/api/events/1018">
        <description>User admin logged in.</description>
        <code>30</code>
        <severity>normal</severity>
        <time>2011-07-11T14:03:22.485+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73"
          href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
    <event id="1016" href="/api/events/1016">
        <description>User admin logged in.</description>
        <code>30</code>
        <severity>normal</severity>
        <time>2011-07-11T14:03:07.236+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73"
          href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
    <event id="1014" href="/api/events/1014">
        <description>User admin logged in.</description>
        <code>30</code>
        <severity>normal</severity>
        <time>2011-07-11T14:02:16.009+10:00</time>
        <user id="80b71bae-98a1-11e0-8f20-525400866c73"
          href="/api/users/80b71bae-98a1-11e0-8f20-525400866c73"/>
    </event>
</events>

例24.4 特定のイベント重大度を使用した検索

GET /api/events?search=severity>normal HTTP/1.1
Accept: application/xml
重大度が normal を超えるすべてのイベントを表示します。重大度のレベルには normalwarningerror、および alert があります。
HTTP/1.1 200 OK
Content-Type: application/xml
<events>
    <event id="2823" href="/api/events/2823">
        <description>Host Host-05 has time-drift of 36002 seconds while maximum configured value is 300 seconds.</description>
        <code>604</code>
        <severity>warning</severity>
        <time>2015-07-11T14:03:22.485+10:00</time>
        <host href= "/api/hosts/44e52bb2-27d6-4d35-8038-0c4b4db89789" id="44e52bb2-27d6-4d35-8038-0c4b4db89789"/>
        <cluster href= "/api/clusters/00000001-0001-0001-0001-00000000021b" id="00000001-0001-0001-0001-00000000021b"/>
        <origin>oVirt</origin>
        <custom_id>-1</custom_id>
        <flood_rate>30</flood_rate>
    </event>
...
</events>

24.4.2. イベントのページネーション処理

仮想化環境では、一定時間が経過すると、大量のイベントが生成されますが、API は 1 回の検索でデフォルト数のイベントしか表示しません。デフォルト数以上のイベント数を表示するには、検索クエリーに page コマンドを使用すると、API が結果を複数のページに分割します。
以下の検索クエリーは、page 値を sortby と併用して、結果をページネーションするように API に指示します。
sortby time asc page 1
sortby 句は、結果を昇順または降順に順序付けするためのベース要素を定義します。events の検索クエリーの場合は、ベース要素を time に、順序を昇順 (asc) に指定すると、API は仮想化環境の作成以降の全イベントを表示します。
page 条件はページ数を定義します。1 ページは、表示するイベントのデフォルト数に相当します。ページネーションは page 1 から開始します。さらにページを表示するには、page 値を増やします。
sortby time asc page 2
sortby time asc page 3
sortby time asc page 4

例24.5 イベントのページネーション

以下の例は event リソースのページネーションを行います。URL エンコードされた要求は次のとおりです。
GET /api/events?search=sortby%20time%20asc%20page%201 HTTP/1.1
Accept: application/xml
page 値を増やして次の結果ページを表示します。
GET /api/events?search=sortby%20time%20asc%20page%202 HTTP/1.1
Accept: application/xml
from 引数を追加し、開始する id を指定します。
GET /api/events?search=sortby%20time%20asc%20page%202&from=30 HTTP/1.1
Accept: application/xml

24.4.3. イベントの追加

API では、POST 要求でカスタムイベントを events コレクションに追加することができます。新規イベントには、 descriptionseverityorigincustom_id 要素が必要です。カスタムイベントには、イベントに関連するリソースの flood_rateuser idid のコードを含めることも可能です。host および storage_domain 要素に external_status を含めて、外部のヘルスステータスを設定することも可能です。

例24.6 カスタムイベントのイベント一覧への追加

POST /api/events HTTP/1.1
Accept: application/xml
Content-type: application/xml

<event>
  <description>The heat of the host is above 30 Oc</description>
  <severity>warning</severity>
  <origin>HP Openview</origin>
  <custom_id>1</custom_id>
  <flood_rate>30</flood_rate>
  <host id="f59a29cd-587d-48a3-b72a-db537eb21957" >
    <external_status>
       <state>warning</state>
    </external_status>
  </host>
</event>

24.4.4. イベントの削除

イベント一覧からイベントを削除するには、DELETE 要求が必要になります。

例24.7 イベントの削除

DELETE /api/events/1705 HTTP/1.1

HTTP/1.1 204 No Content

付録A cURL での API の使用法

A.1. cURL での API の使用法

本付録では、REST の要求を cURL での使用に適合させる方法について説明します。cURL は、HTTP など各種プロトコルでデータを転送するためのコマンドラインツールです。Linux、Windows、Mac、Solaris など複数のプラットフォームに対応しています。大半の Linux のディストリビューションには cURL がパッケージとして同梱されています。

A.2. cURL のインストール

Red Hat Enterprise Linux ユーザーの場合は、以下のターミナルコマンドで cURL をインストールします。
yum install curl
その他のプラットフォームの場合には、cURL の Web サイトでインストール方法を確認してください (http://curl.haxx.se/)。

A.3. cURL の使用法

cURL は、コマンドラインインターフェースを使用して HTTP サーバーに要求を送信します。要求を統合するには、以下のコマンド構文が必要です。
curl [options] uri
uri はターゲットの HTTP アドレスを参照し、要求を送信します。これは API エントリーポイントパス内の Red Hat Enterprise Virtualization Manager ホスト上の場所です (/api)。

cURL のオプション

-X COMMAND, --request COMMAND
使用する要求コマンド。REST API では、GETPOSTPUTDELETE のいずれかを使用します。
-X GET
-H LINE, --header LINE
要求に追加する HTTP ヘッダー。ヘッダーが複数必要な場合は、複数のヘッダーオプションを使用します。
例: -H "Accept: application/xml" -H "Content-Type: application/xml"
-u USERNAME:PASSWORD, --user USERNAME:PASSWORD
Red Hat Enterprise Virtualization ユーザーのユーザー名とパスワード。この属性は Authorization: ヘッダーの便利な代替手段として機能します。
例: -u admin@internal:p@55w0rd!
--cacert CERTIFICATE
REST API との SSL 通信のための証明書ファイルの場所。証明書ファイルはクライアントマシン上にローカルで保存されます。SSL をバイパスする場合は -k 属性を使用します。
例: --cacert ~/Certificates/rhevm.cer
-d BODY, --data BODY
送信する要求の本文。POSTPUTDELETE などの要求で使用します。要求内に本文が存在する場合は、Content-Type: application/xml を必ず指定してください。
例: -d "<cdrom><file id='rhel-server-6.0-x86_64-dvd.iso'/></cdrom>"

A.4. 例

A.4.1. cURL を使用した GET 要求

例A.1 GET 要求

以下の GET 要求は、vms コレクション内の仮想マシンを一覧表示します。GET 要求には本文が含まれない点に注意してください。
GET /api/vms HTTP/1.1
Accept: application/xml
メソッド (GET)、ヘッダー (Accept: application/xml)、URI (https://[RHEVM-Host]:443/api/vms) を次の cURL コマンドに適用します。
$ curl -X GET -H "Accept: application/xml" -u [USER:PASS] --cacert [CERT] https://[RHEVM-Host]:443/api/vms
vms コレクションの XML 表現が表示されます。

A.4.2. cURL を使用した POST 要求

例A.2 POST 要求

次の POST 要求は、vms コレクション内に仮想マシンを作成します。POST 要求には本文が必要な点に注意してください。
POST /api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
  <name>vm1</name>
  <cluster>
    <name>default</name>
  </cluster>
  <template>
    <name>Blank</name>
  </template>
  <memory>536870912</memory> 
  <os>
    <boot dev="hd"/>
  </os>
</vm>
メソッド (POST)、ヘッダー (Accept: application/xml および Content-type: application/xml)、 URI (https://[RHEVM-Host]:443/api/vms)、要求の本文を次の cURL コマンドに適用します。
$ curl -X POST -H "Accept: application/xml" -H "Content-type: application/xml" -u [USER:PASS] --cacert [CERT] -d "<vm><name>vm1</name><cluster><name>default</name></cluster><template><name>Blank</name></template><memory>536870912</memory><os><boot dev='hd'/></os></vm>" https://[RHEVM-Host]:443/api/vms
REST API は新規仮想マシンを作成し、そのリソースの XML 表現を表示します。

A.4.3. cURL を使用した PUT 要求

例A.3 PUT 要求

以下の PUT 要求は、仮想マシンリソースのメモリーを更新します。PUT 要求には本文が必要な点に注意してください。
PUT /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<vm>
    <memory>1073741824</memory>
</vm>
メソッド (PUT)、ヘッダー (Accept: application/xmlContent-type: application/xml)、URI (https://[RHEVM-Host]:443/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399)、要求の本文を次の cURL コマンドに適用します。
$ curl -X PUT -H "Accept: application/xml" -H "Content-type: application/xml" -u [USER:PASS] --cacert [CERT] -d "<vm><memory>1073741824</memory></vm>" https://[RHEVM-Host]:443//api/vms/082c794b-771f-452f-83c9-b2b5a19c039
REST API は新しいメモリー設定で仮想マシンを更新します。

A.4.4. cURL を使用した DELETE 要求

例A.4 DELETE 要求

以下の DELETE 要求は、仮想マシンのリソースを削除します。
DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
メソッド (DELETE) および URI (https://[RHEVM-Host]:443/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399) を次の cURL コマンドに適用します。
$ curl -X DELETE -u [USER:PASS] --cacert [CERT] https://[RHEVM-Host]:443//api/vms/082c794b-771f-452f-83c9-b2b5a19c039
REST API は仮想マシンを削除します。DELETE 要求の結果が空のため、Accept: application/xml ヘッダーはオプションになります。

A.4.5. cURL を使用した 本文付きの DELETE 要求

例A.5 本文付きの DELETE 要求

以下の DELETE 要求は、オプションの本文で示されているように、仮想マシンリソースを強制削除します。
DELETE /api/vms/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<action>
  <force>true</force>
</action>
メソッド (DELETE)、ヘッダー (Accept: application/xml および Content-type: application/xml)、URI (https://[RHEVM-Host]:443/api/vms/082c794b-771f-452f-83c9-b2b5a19c0399)、要求の本文を次の cURL コマンドに適用します。
$ curl -X DELETE -H "Accept: application/xml" -H "Content-type: application/xml" -u [USER:PASS] --cacert [CERT] -d "<action><force>true</force></action>" https://[RHEVM-Host]:443//api/vms/082c794b-771f-452f-83c9-b2b5a19c039
REST API は仮想マシンを強制削除します。

付録B 列挙値の変換

B.1. 列挙値の変換

API は、Red Hat Enterprise Virtualization クエリー言語を使用して検索クエリーを実行します。クエリー言語の詳細については、『Red Hat Enterprise Virtualization 管理ガイド』 の「Red Hat Enterprise Virtualization での検索」のセクションに記載された完全な仕様を参照してください。
クエリー言語の使用時に、API の特定の列挙値には、異なる検索クエリーが必要なことに注意してください。以下の表には、これらの主要な列挙値の変換をまとめています。

表B.1 列挙値の変換

リソースタイプ
API 列挙タイプ
API 列挙値
クエリー言語プロパティー
クエリー言語値
データセンター
data_center_statesnot_operationalstatusnotoperational
ホスト
host_statesnon_responsivestatusnonresponsive
install_failedinstallfailed
preparing_for_maintenancepreparingformaintenance
non_operationalnonoperational
pending_approvalpendingapproval
仮想マシン
vm_statespowering_upstatuspoweringup
powering_downpoweringdown
migratingmigratingfrom
migratingmigratingto
not_respondingnotresponding
wait_for_launchwaitforlaunch
reboot_in_progressrebootinprogress
saving_statesavingstate
restoring_staterestoringstate
image_lockedimagelocked

付録C イベントコード

C.1. イベントコード

以下の表には、全イベントコードをまとめています。

表C.1 イベントコード

コード名前重大度メッセージ
0UNASSIGNEDInfo
1VDC_STARTInfoStarting oVirt Engine.
2VDC_STOPInfoStopping oVirt Engine.
12VDS_FAILUREErrorHost ${VdsName} is non responsive.
13VDS_DETECTEDInfoStatus of host ${VdsName} was set to ${HostStatus}.
14VDS_RECOVERInfoHost ${VdsName} is rebooting.
15VDS_MAINTENANCENormalHost ${VdsName} was switched to Maintenance Mode.
16VDS_ACTIVATEInfoActivation of host ${VdsName} initiated by ${UserName}.
17VDS_MAINTENANCE_FAILEDErrorFailed to switch Host ${VdsName} to Maintenance mode.
18VDS_ACTIVATE_FAILEDErrorFailed to activate Host ${VdsName}.(User: ${UserName}).
19VDS_RECOVER_FAILEDErrorHost ${VdsName} failed to recover.
20USER_VDS_STARTInfoHost ${VdsName} was started by ${UserName}.
21USER_VDS_STOPInfoHost ${VdsName} was stopped by ${UserName}.
22IRS_FAILUREErrorFailed to access Storage on Host ${VdsName}.
23VDS_LOW_DISK_SPACEWarningWarning, Low disk space. Host ${VdsName} has less than ${DiskSpace} MB of free space left on: ${Disks}.
24VDS_LOW_DISK_SPACE_ERRORErrorCritical, Low disk space. Host ${VdsName} has less than ${DiskSpace} MB of free space left on: ${Disks}. Low disk space might cause an issue upgrading this host.
25VDS_NO_SELINUX_ENFORCEMENTWarningHost ${VdsName} does not enforce SELinux. Current status: ${Mode}
26IRS_DISK_SPACE_LOWWarningWarning, Low disk space. ${StorageDomainName} domain has ${DiskSpace} GB of free space.
27VDS_STATUS_CHANGE_FAILED_DUE_TO_STOP_SPM_FAILUREWarningFailed to change status of host ${VdsName} due to a failure to stop the spm.
28VDS_PROVISIONWarningInstalling OS on Host ${VdsName} using Hostgroup ${HostGroupName}.
29USER_ADD_VM_TEMPLATE_SUCCESSInfoTemplate ${VmTemplateName} was created successfully.
31USER_VDC_LOGOUTInfoUser ${UserName} logged out.
32USER_RUN_VMInfoVM ${VmName} started on Host ${VdsName}
33USER_STOP_VMInfoVM ${VmName} powered off by ${UserName} (Host: ${VdsName}) (Reason: ${Reason}).
34USER_ADD_VMInfoVM ${VmName} was created by ${UserName}.
35USER_UPDATE_VMInfoVM ${VmName} configuration was updated by ${UserName}.
36USER_ADD_VM_TEMPLATE_FAILUREErrorFailed creating Template ${VmTemplateName}.
37USER_ADD_VM_STARTEDInfoVM ${VmName} creation was initiated by ${UserName}.
38USER_CHANGE_DISK_VMInfoCD ${DiskName} was inserted to VM ${VmName} by ${UserName}.
39USER_PAUSE_VMInfoVM ${VmName} was suspended by ${UserName} (Host: ${VdsName}).
40USER_RESUME_VMInfoVM ${VmName} was resumed by ${UserName} (Host: ${VdsName}).
41USER_VDS_RESTARTInfoHost ${VdsName} was restarted by ${UserName}.
42USER_ADD_VDSInfoHost ${VdsName} was added by ${UserName}.
43USER_UPDATE_VDSInfoHost ${VdsName} configuration was updated by ${UserName}.
44USER_REMOVE_VDSInfoHost ${VdsName} was removed by ${UserName}.
45USER_CREATE_SNAPSHOTInfoSnapshot '${SnapshotName}' creation for VM '${VmName}' was initiated by ${UserName}.
46USER_TRY_BACK_TO_SNAPSHOTInfoSnapshot-Preview ${SnapshotName} for VM ${VmName} was initiated by ${UserName}.
47USER_RESTORE_FROM_SNAPSHOTInfoVM ${VmName} restored from Snapshot by ${UserName}.
48USER_ADD_VM_TEMPLATEInfoCreation of Template ${VmTemplateName} from VM ${VmName} was initiated by ${UserName}.
49USER_UPDATE_VM_TEMPLATEInfoTemplate ${VmTemplateName} configuration was updated by ${UserName}.
50USER_REMOVE_VM_TEMPLATEInfoRemoval of Template ${VmTemplateName} was initiated by ${UserName}.
51USER_ADD_VM_TEMPLATE_FINISHED_SUCCESSInfoCreation of Template ${VmTemplateName} from VM ${VmName} has been completed.
52USER_ADD_VM_TEMPLATE_FINISHED_FAILUREErrorFailed to complete creation of Template ${VmTemplateName} from VM ${VmName}.
53USER_ADD_VM_FINISHED_SUCCESSInfoVM ${VmName} creation has been completed.
54USER_FAILED_RUN_VMErrorFailed to run VM ${VmName} (User: ${UserName}).
55USER_FAILED_PAUSE_VMErrorFailed to suspend VM ${VmName} (Host: ${VdsName}, User: ${UserName}).
56USER_FAILED_STOP_VMErrorFailed to power off VM ${VmName} (Host: ${VdsName}, User: ${UserName}).
57USER_FAILED_ADD_VMErrorFailed to create VM ${VmName} (User: ${UserName}).
58USER_FAILED_UPDATE_VMErrorFailed to update VM ${VmName} (User: ${UserName}).
59USER_FAILED_REMOVE_VMError
60USER_ADD_VM_FINISHED_FAILUREErrorFailed to complete VM ${VmName} creation.
61VM_DOWNInfoVM ${VmName} is down. ${ExitMessage}
62VM_MIGRATION_STARTInfoMigration started (VM: ${VmName}, Source: ${VdsName}, Destination: ${DestinationVdsName}, User: ${UserName}).
63VM_MIGRATION_DONEInfoMigration completed (VM: ${VmName}, Source: ${VdsName}, Destination: ${DestinationVdsName}, Duration: ${Duration}, Total: ${TotalDuration}, Actual downtime: ${ActualDowntime})
64VM_MIGRATION_ABORTErrorMigration failed: ${MigrationError} (VM: ${VmName}, Source: ${VdsName}, Destination: ${DestinationVdsName}).
65VM_MIGRATION_FAILEDErrorMigration failed${DueToMigrationError} (VM: ${VmName}, Source: ${VdsName}).
66VM_FAILUREErrorVM ${VmName} cannot be found on Host ${VdsName}.
67VM_MIGRATION_START_SYSTEM_INITIATEDInfoMigration initiated by system (VM: ${VmName}, Source: ${VdsName}, Destination: ${DestinationVdsName}).
68USER_CREATE_SNAPSHOT_FINISHED_SUCCESSInfoSnapshot '${SnapshotName}' creation for VM '${VmName}' has been completed.
69USER_CREATE_SNAPSHOT_FINISHED_FAILUREErrorFailed to complete snapshot '${SnapshotName}' creation for VM '${VmName}'.
70USER_RUN_VM_AS_STATELESS_FINISHED_FAILUREErrorFailed to complete starting of VM ${VmName}.
71USER_TRY_BACK_TO_SNAPSHOT_FINISH_SUCCESSInfoSnapshot-Preview ${SnapshotName} for VM ${VmName} has been completed.
72USER_CHANGE_FLOPPY_VMInfoFloppy ${DiskName} was inserted in VM ${VmName} by ${UserName}
73USER_INITIATED_SHUTDOWN_VMInfoVM shutdown initiated by ${UserName} on VM ${VmName} (Host: ${VdsName}) (Reason: ${Reason}).
74USER_FAILED_SHUTDOWN_VMErrorFailed to initiate shutdown on VM ${VmName} (Host: ${VdsName}, User: ${UserName}).
75USER_FAILED_CHANGE_FLOPPY_VMErrorFailed to change floppy ${DiskName} (User: ${UserName}).
76USER_STOPPED_VM_INSTEAD_OF_SHUTDOWNInfoVM ${VmName} was powered off ungracefully by ${UserName} (Host: ${VdsName}) (Reason: ${Reason}).
77USER_FAILED_STOPPING_VM_INSTEAD_OF_SHUTDOWNErrorFailed to power off VM ${VmName} (Host: ${VdsName}, User: ${UserName}).
78USER_ADD_DISK_TO_VMInfoAdd-Disk operation of ${DiskAlias} was initiated on VM ${VmName} by ${UserName}.
79USER_FAILED_ADD_DISK_TO_VMErrorAdd-Disk operation failed on VM ${VmName} (User: ${UserName}).
80USER_REMOVE_DISK_FROM_VMInfoDisk was removed from VM ${VmName} by ${UserName}.
81USER_FAILED_REMOVE_DISK_FROM_VMErrorFailed to remove Disk from VM ${VmName} (User: ${UserName}).
82USER_MOVED_VMInfoVM ${VmName} moving to Domain ${StorageDomainName} was initiated by ${UserName}.
83USER_FAILED_MOVE_VMErrorFailed to initiate moving of VM ${VmName} to Domain ${StorageDomainName} (User: ${UserName}).
84USER_MOVED_TEMPLATEInfoTemplate ${VmTemplateName} moving to Domain ${StorageDomainName} was initiated by ${UserName}.
85USER_FAILED_MOVE_TEMPLATEErrorFailed to initiate moving Template ${VmTemplateName} to Domain ${StorageDomainName} (User: ${UserName}).
86USER_COPIED_TEMPLATEInfoTemplate ${VmTemplateName} copy to Domain ${StorageDomainName} was initiated by ${UserName}.
87USER_FAILED_COPY_TEMPLATEErrorFailed to initiate copy of Template ${VmTemplateName} to Domain ${StorageDomainName} (User: ${UserName}).
88USER_UPDATE_VM_DISKInfoVM ${VmName} ${DiskAlias} disk was updated by ${UserName}.
89USER_FAILED_UPDATE_VM_DISKErrorFailed to update VM ${VmName} disk ${DiskAlias} (User: ${UserName}).
90VDS_FAILED_TO_GET_HOST_HARDWARE_INFOWarningCould not get hardware information for host ${VdsName}
91USER_MOVED_VM_FINISHED_SUCCESSInfoMoving VM ${VmName} to Domain ${StorageDomainName} has been completed.
92USER_MOVED_VM_FINISHED_FAILUREErrorFailed to complete moving of VM ${VmName} to Domain ${StorageDomainName}.
93USER_MOVED_TEMPLATE_FINISHED_SUCCESSInfoTemplate ${VmTemplateName} moving to Domain ${StorageDomainName} has been completed.
94USER_MOVED_TEMPLATE_FINISHED_FAILUREErrorFailed to complete moving of Template ${VmTemplateName} to Domain ${StorageDomainName}.
95USER_COPIED_TEMPLATE_FINISHED_SUCCESSInfoTemplate ${VmTemplateName} copy to Domain ${StorageDomainName} has been completed.
96USER_COPIED_TEMPLATE_FINISHED_FAILUREErrorFailed to complete copy of Template ${VmTemplateName} to Domain ${StorageDomainName}.
97USER_ADD_DISK_TO_VM_FINISHED_SUCCESSInfoThe disk ${DiskAlias} was successfully added to VM ${VmName}.
98USER_ADD_DISK_TO_VM_FINISHED_FAILUREErrorAdd-Disk operation failed to complete on VM ${VmName}.
99USER_TRY_BACK_TO_SNAPSHOT_FINISH_FAILUREErrorFailed to complete Snapshot-Preview ${SnapshotName} for VM ${VmName}.
100USER_RESTORE_FROM_SNAPSHOT_FINISH_SUCCESSInfoVM ${VmName} restoring from Snapshot has been completed.
101USER_RESTORE_FROM_SNAPSHOT_FINISH_FAILUREErrorFailed to complete restoring from Snapshot of VM ${VmName}.
102USER_FAILED_CHANGE_DISK_VMErrorFailed to change disk in VM ${VmName} (Host: ${VdsName}, User: ${UserName}).
103USER_FAILED_RESUME_VMErrorFailed to resume VM ${VmName} (Host: ${VdsName}, User: ${UserName}).
104USER_FAILED_ADD_VDSErrorFailed to add Host ${VdsName} (User: ${UserName}).
105USER_FAILED_UPDATE_VDSErrorFailed to update Host ${VdsName} (User: ${UserName}).
106USER_FAILED_REMOVE_VDSErrorFailed to remove Host ${VdsName} (User: ${UserName}).
107USER_FAILED_VDS_RESTARTErrorFailed to restart Host ${VdsName}, (User: ${UserName}).
108USER_FAILED_ADD_VM_TEMPLATEErrorFailed to initiate creation of Template ${VmTemplateName} from VM ${VmName} (User: ${UserName}).
109USER_FAILED_UPDATE_VM_TEMPLATEErrorFailed to update Template ${VmTemplateName} (User: ${UserName}).
110USER_FAILED_REMOVE_VM_TEMPLATEErrorFailed to initiate removal of Template ${VmTemplateName} (User: ${UserName}).
111USER_STOP_SUSPENDED_VMInfoSuspended VM ${VmName} has had its save state cleared by ${UserName} (Reason: ${Reason}).
112USER_STOP_SUSPENDED_VM_FAILEDErrorFailed to power off suspended VM ${VmName} (User: ${UserName}).
113USER_REMOVE_VM_FINISHEDInfoVM ${VmName} was successfully removed.
114USER_VDC_LOGIN_FAILEDErrorUser ${UserName} failed to log in.
115USER_FAILED_TRY_BACK_TO_SNAPSHOTErrorFailed to preview Snapshot ${SnapshotName} for VM ${VmName} (User: ${UserName}).
116USER_FAILED_RESTORE_FROM_SNAPSHOTErrorFailed to restore VM ${VmName} from Snapshot (User: ${UserName}).
117USER_FAILED_CREATE_SNAPSHOTErrorFailed to create Snapshot ${SnapshotName} for VM ${VmName} (User: ${UserName}).
118USER_FAILED_VDS_STARTErrorFailed to start Host ${VdsName}, (User: ${UserName}).
119VM_DOWN_ERRORErrorVM ${VmName} is down with error. ${ExitMessage}.
120VM_MIGRATION_TO_SERVER_FAILEDErrorMigration failed${DueToMigrationError} (VM: ${VmName}, Source: ${VdsName}, Destination: ${DestinationVdsName}).
121SYSTEM_VDS_RESTARTInfoHost ${VdsName} was restarted by the engine.
122SYSTEM_FAILED_VDS_RESTARTErrorA restart initiated by the engine to Host ${VdsName} has failed.
123VDS_SLOW_STORAGE_RESPONSE_TIMEWarningSlow storage response time on Host ${VdsName}.
124VM_IMPORTInfoStarted VM import of ${ImportedVmName} (User: ${UserName})
125VM_IMPORT_FAILEDErrorFailed to import VM ${ImportedVmName} (User: ${UserName})
126VM_NOT_RESPONDINGWarningVM ${VmName} is not responding.
127VDS_RUN_IN_NO_KVM_MODEErrorHost ${VdsName} running without virtualization hardware acceleration
128VM_MIGRATION_TRYING_RERUNWarningFailed to migrate VM ${VmName} to Host ${DestinationVdsName}${DueToMigrationError}. Trying to migrate to another Host.
129VM_CLEAREDInfoUnused
130USER_SUSPEND_VM_FINISH_FAILURE_WILL_TRY_AGAINErrorFailed to complete suspending of VM ${VmName}, will try again.
131USER_EXPORT_VMInfoVM ${VmName} exported to ${ExportPath} by ${UserName}
132USER_EXPORT_VM_FAILEDErrorFailed to export VM ${VmName} to ${ExportPath} (User: ${UserName})
133USER_EXPORT_TEMPLATEInfoTemplate ${VmTemplateName} exported to ${ExportPath} by ${UserName}
134USER_EXPORT_TEMPLATE_FAILEDErrorFailed to export Template ${VmTemplateName} to ${ExportPath} (User: ${UserName})
135TEMPLATE_IMPORTInfoStarted Template import of ${ImportedVmTemplateName} (User: ${UserName})
136TEMPLATE_IMPORT_FAILEDErrorFailed to import Template ${ImportedVmTemplateName} (User: ${UserName})
137USER_FAILED_VDS_STOPErrorFailed to stop Host ${VdsName}, (User: ${UserName}).
138VM_PAUSED_ENOSPCErrorVM ${VmName} has been paused due to no Storage space error.
139VM_PAUSED_ERRORErrorVM ${VmName} has been paused due to unknown storage error.
140VM_MIGRATION_FAILED_DURING_MOVE_TO_MAINTENANCEErrorMigration failed${DueToMigrationError} while Host is in 'preparing for maintenance' state.\n Consider manual intervention\: stopping/migrating Vms as Host's state will not\n turn to maintenance while VMs are still running on it.(VM: ${VmName}, Source: ${VdsName}, Destination: ${DestinationVdsName}).
141VDS_VERSION_NOT_SUPPORTED_FOR_CLUSTERErrorHost ${VdsName} is installed with VDSM version (${VdsSupportedVersions}) and cannot join cluster ${VdsGroupName} which is compatible with VDSM versions ${CompatibilityVersion}.
142VM_SET_TO_UNKNOWN_STATUSWarningVM ${VmName} was set to the Unknown status.
143VM_WAS_SET_DOWN_DUE_TO_HOST_REBOOT_OR_MANUAL_FENCEInfoVm ${VmName} was shut down due to ${VdsName} host reboot or manual fence
144VM_IMPORT_INFOInfoValue of field ${FieldName} of imported VM ${VmName} is ${FieldValue}. The field is reset to the default value
145VM_PAUSED_EIOErrorVM ${VmName} has been paused due to storage I/O problem.
146VM_PAUSED_EPERMErrorVM ${VmName} has been paused due to storage permissions problem.
147VM_POWER_DOWN_FAILEDWarningShutdown of VM ${VmName} failed.
148VM_MEMORY_UNDER_GUARANTEED_VALUEErrorVM ${VmName} on host ${VdsName} was guaranteed ${MemGuaranteed} MB but currently has ${MemActual} MB
149USER_ADDInfoUser '${NewUserName}' was added successfully to the system.
150USER_INITIATED_RUN_VMInfoStarting VM ${VmName} was initiated by ${UserName}.
151USER_INITIATED_RUN_VM_FAILEDWarningFailed to run VM ${VmName} on Host ${VdsName}.
152USER_RUN_VM_ON_NON_DEFAULT_VDSWarningGuest ${VmName} started on Host ${VdsName}. (Default Host parameter was ignored - assigned Host was not available).
153USER_STARTED_VMInfoVM ${VmName} was started by ${UserName} (Host: ${VdsName}).
154VDS_CLUSTER_VERSION_NOT_SUPPORTEDErrorHost ${VdsName} is compatible with versions (${VdsSupportedVersions}) and cannot join Cluster ${VdsGroupName} which is set to version ${CompatibilityVersion}.
155VDS_ARCHITECTURE_NOT_SUPPORTED_FOR_CLUSTERErrorHost ${VdsName} has architecture ${VdsArchitecture} and cannot join Cluster ${VdsGroupName} which has architecture ${VdsGroupArchitecture}.
156CPU_TYPE_UNSUPPORTED_IN_THIS_CLUSTER_VERSIONErrorHost ${VdsName} moved to Non-Operational state as host CPU type is not supported in this cluster compatibility version or is not supported at all
157USER_REBOOT_VMInfoUser ${UserName} initiated reboot of VM ${VmName}.
158USER_FAILED_REBOOT_VMErrorFailed to reboot VM ${VmName} (User: ${UserName}).
159USER_FORCE_SELECTED_SPMInfoHost ${VdsName} was force selected by ${UserName}
160USER_ACCOUNT_DISABLED_OR_LOCKEDErrorUser ${UserName} cannot login, as it got disabled or locked. Please contact the system administrator.
161VM_CANCEL_MIGRATIONInfoMigration cancelled (VM: ${VmName}, Source: ${VdsName}, User: ${UserName}).
162VM_CANCEL_MIGRATION_FAILEDErrorFailed to cancel migration for VM: ${VmName}
163VM_STATUS_RESTOREDInfoVM ${VmName} status was restored to ${VmStatus}.
164VM_SET_TICKETInfoUser ${UserName} initiated console session for VM ${VmName}
165VM_SET_TICKET_FAILEDErrorUser ${UserName} failed to initiate a console session for VM ${VmName}
166VM_MIGRATION_NO_VDS_TO_MIGRATE_TOWarningNo available host was found to migrate VM ${VmName} to.
167VM_CONSOLE_CONNECTEDInfoUser ${UserName} is connected to VM ${VmName}.
168VM_CONSOLE_DISCONNECTEDInfoUser ${UserName} got disconnected from VM ${VmName}.
169VM_FAILED_TO_PRESTART_IN_POOLWarningCannot pre-start VM in pool '${VmPoolName}'. The system will continue trying.
170USER_CREATE_LIVE_SNAPSHOT_FINISHED_FAILUREWarningFailed to create live snapshot '${SnapshotName}' for VM '${VmName}'. VM restart is recommended. Note that using the created snapshot might cause data inconsistency.
171USER_RUN_VM_AS_STATELESS_WITH_DISKS_NOT_ALLOWING_SNAPSHOTWarningVM ${VmName} was run as stateless with one or more of disks that do not allow snapshots (User:${UserName}).
172USER_REMOVE_VM_FINISHED_WITH_ILLEGAL_DISKSWarningVM ${VmName} has been removed, but the following disks could not be removed: ${DisksNames}. These disks will appear in the main disks tab in illegal state, please remove manually when possible.
173USER_CREATE_LIVE_SNAPSHOT_NO_MEMORY_FAILUREErrorFailed to save memory as part of Snapshot ${SnapshotName} for VM ${VmName} (User: ${UserName}).
174VM_IMPORT_FROM_CONFIGURATION_EXECUTED_SUCCESSFULLYInfoVM ${VmName} has been successfully imported from the given configuration.
175VM_IMPORT_FROM_CONFIGURATION_ATTACH_DISKS_FAILEDWarningVM ${VmName} has been imported from the given configuration but the following disk(s) failed to attach: ${DiskAliases}.
176VM_BALLOON_DRIVER_ERRORErrorThe Balloon driver on VM ${VmName} on host ${VdsName} is requested but unavailable.
177VM_BALLOON_DRIVER_UNCONTROLLEDErrorThe Balloon device on VM ${VmName} on host ${VdsName} is inflated but the device cannot be controlled (guest agent is down).
178VM_MEMORY_NOT_IN_RECOMMENDED_RANGEWarningVM ${VmName} was configured with ${VmMemInMb}mb of memory while the recommended value range is ${VmMinMemInMb}mb - ${VmMaxMemInMb}mb
179USER_INITIATED_RUN_VM_AND_PAUSEInfoStarting in paused mode VM ${VmName} was initiated by ${UserName}.
180TEMPLATE_IMPORT_FROM_CONFIGURATION_SUCCESSInfoTemplate ${VmTemplateName} has been successfully imported from the given configuration.
181TEMPLATE_IMPORT_FROM_CONFIGURATION_FAILEDErrorFailed to import Template ${VmTemplateName} from the given configuration.
182USER_FAILED_ATTACH_USER_TO_VMErrorFailed to attach User ${AdUserName} to VM ${VmName} (User: ${UserName}).
183USER_ATTACH_TAG_TO_TEMPLATEInfoTag ${TagName} was attached to Templates(s) ${TemplatesNames} by ${UserName}.
184USER_ATTACH_TAG_TO_TEMPLATE_FAILEDErrorFailed to attach Tag ${TagName} to Templates(s) ${TemplatesNames} (User: ${UserName}).
185USER_DETACH_TEMPLATE_FROM_TAGInfoTag ${TagName} was detached from Template(s) ${TemplatesNames} by ${UserName}.
186USER_DETACH_TEMPLATE_FROM_TAG_FAILEDErrorFailed to detach Tag ${TagName} from TEMPLATE(s) ${TemplatesNames} (User: ${UserName}).
187VDS_STORAGE_CONNECTION_FAILED_BUT_LAST_VDSErrorFailed to connect Host ${VdsName} to Data Center, due to connectivity errors with the Storage. Host ${VdsName} will remain in Up state (but inactive), as it is the last Host in the Data Center, to enable manual intervention by the Administrator.
188VDS_STORAGES_CONNECTION_FAILEDErrorFailed to connect Host ${VdsName} to the Storage Domains ${failedStorageDomains}.
189VDS_STORAGE_VDS_STATS_FAILEDErrorHost ${VdsName} reports about one of the Active Storage Domains as Problematic.
190UPDATE_OVF_FOR_STORAGE_DOMAIN_FAILEDWarningFailed to update VMs/Templates OVF data for Storage Domain ${StorageDomainName} in Data Center ${StoragePoolName}.
191CREATE_OVF_STORE_FOR_STORAGE_DOMAIN_FAILEDWarningFailed to create OVF store disk for Storage Domain ${StorageDomainName}.\n The Disk with the id ${DiskId} might be removed manually for automatic attempt to create new one. \n OVF updates won't be attempted on the created disk.
192CREATE_OVF_STORE_FOR_STORAGE_DOMAIN_INITIATE_FAILEDWarningFailed to create OVF store disk for Storage Domain ${StorageDomainName}. \n OVF data won't be updated meanwhile for that domain.
193DELETE_OVF_STORE_FOR_STORAGE_DOMAIN_FAILEDWarningFailed to delete the OVF store disk for Storage Domain ${StorageDomainName}.\n In order to detach the domain please remove it manually or try to detach the domain again for another attempt.
194VM_CANCEL_CONVERSIONInfoConversion cancelled (VM: ${VmName}, Source: ${VdsName}, User: ${UserName}).
195VM_CANCEL_CONVERSION_FAILEDErrorFailed to cancel conversion for VM: ${VmName}
196VM_RECOVERED_FROM_PAUSE_ERRORNormalVM ${VmName} has recovered from paused back to up.
200IMPORTEXPORT_GET_VMS_INFO_FAILEDErrorFailed to retrieve VM/Templates information from export domain ${StorageDomainName}
201IRS_DISK_SPACE_LOW_ERRORErrorCritical, Low disk space. ${StorageDomainName} domain has ${DiskSpace} GB of free space.
202IMPORTEXPORT_GET_EXTERNAL_VMS_INFO_FAILEDErrorFailed to retrieve VMs information from external server ${URL}
204IRS_HOSTED_ON_VDSInfoStorage Pool Manager runs on Host ${VdsName} (Address: ${ServerIp}).
205PROVIDER_ADDEDInfoProvider ${ProviderName} was added. (User: ${UserName})
206PROVIDER_ADDITION_FAILEDErrorFailed to add provider ${ProviderName}. (User: ${UserName})
207PROVIDER_UPDATEDInfoProvider ${ProviderName} was updated. (User: ${UserName})
208PROVIDER_UPDATE_FAILEDErrorFailed to update provider ${ProviderName}. (User: ${UserName})
209PROVIDER_REMOVEDInfoProvider ${ProviderName} was removed. (User: ${UserName})
210PROVIDER_REMOVAL_FAILEDErrorFailed to remove provider ${ProviderName}. (User: ${UserName})
213PROVIDER_CERTIFICATE_IMPORTEDInfoCertificate for provider ${ProviderName} was imported. (User: ${UserName})
214PROVIDER_CERTIFICATE_IMPORT_FAILEDErrorFailed importing Certificate for provider ${ProviderName}. (User: ${UserName})
250USER_UPDATE_VM_CLUSTER_DEFAULT_HOST_CLEAREDInfo${VmName} cluster was updated by ${UserName}, Default host was reset to auto assign.
251USER_REMOVE_VM_TEMPLATE_FINISHEDInfoRemoval of Template ${VmTemplateName} has been completed.
252SYSTEM_FAILED_UPDATE_VMErrorFailed to Update VM ${VmName} that was initiated by system.
253SYSTEM_UPDATE_VMInfoVM ${VmName} configuration was updated by system.
254VM_ALREADY_IN_REQUESTED_STATUSInfoVM ${VmName} is already ${VmStatus}, ${Action} was skipped. User: ${UserName}.
302USER_ADD_VM_POOL_WITH_VMSInfoVM Pool ${VmPoolName} (containing ${VmsCount} VMs) was created by ${UserName}.
303USER_ADD_VM_POOL_WITH_VMS_FAILEDErrorFailed to create VM Pool ${VmPoolName} (User: ${UserName}).
304USER_REMOVE_VM_POOLInfoVM Pool ${VmPoolName} was removed by ${UserName}.
305USER_REMOVE_VM_POOL_FAILEDErrorFailed to remove VM Pool ${VmPoolName} (User: ${UserName}).
306USER_ADD_VM_TO_POOLInfoVM ${VmName} was added to VM Pool ${VmPoolName} by ${UserName}.
307USER_ADD_VM_TO_POOL_FAILEDErrorFailed to add VM ${VmName} to VM Pool ${VmPoolName}(User: ${UserName}).
308USER_REMOVE_VM_FROM_POOLInfoVM ${VmName} was removed from VM Pool ${VmPoolName} by ${UserName}.
309USER_REMOVE_VM_FROM_POOL_FAILEDErrorFailed to remove VM ${VmName} from VM Pool ${VmPoolName} (User: ${UserName}).
310USER_ATTACH_USER_TO_POOLInfoUser ${AdUserName} was attached to VM Pool ${VmPoolName} by ${UserName}.
311USER_ATTACH_USER_TO_POOL_FAILEDErrorFailed to attach User ${AdUserName} to VM Pool ${VmPoolName} (User: ${UserName}).
312USER_DETACH_USER_FROM_POOLInfoUser ${AdUserName} was detached from VM Pool ${VmPoolName} by ${UserName}.
313USER_DETACH_USER_FROM_POOL_FAILEDErrorFailed to detach User ${AdUserName} from VM Pool ${VmPoolName} (User: ${UserName}).
314USER_UPDATE_VM_POOLInfoVM Pool ${VmPoolName} configuration was updated by ${UserName}.
315USER_UPDATE_VM_POOL_FAILEDErrorFailed to update VM Pool ${VmPoolName} configuration (User: ${UserName}).
316USER_ATTACH_USER_TO_VM_FROM_POOLInfoAttaching User ${AdUserName} to VM ${VmName} in VM Pool ${VmPoolName} was initiated by ${UserName}.
317USER_ATTACH_USER_TO_VM_FROM_POOL_FAILEDErrorFailed to attach User ${AdUserName} to VM from VM Pool ${VmPoolName} (User: ${UserName}).
318USER_ATTACH_USER_TO_VM_FROM_POOL_FINISHED_SUCCESSInfoUser ${AdUserName} successfully attached to VM ${VmName} in VM Pool ${VmPoolName}.
319USER_ATTACH_USER_TO_VM_FROM_POOL_FINISHED_FAILUREErrorFailed to attach user ${AdUserName} to VM ${VmName} in VM Pool ${VmPoolName}.
320USER_ADD_VM_POOL_WITH_VMS_ADD_VDS_FAILEDErrorPool ${VmPoolName} Created, but some Vms failed to create (User: ${UserName}).
325USER_REMOVE_ADUSERInfoUser ${AdUserName} was removed by ${UserName}.
326USER_FAILED_REMOVE_ADUSERErrorFailed to remove User ${AdUserName} (User: ${UserName}).
327USER_FAILED_ADD_ADUSERWarningFailed to add User '${NewUserName}' to the system.
342USER_REMOVE_SNAPSHOTInfoSnapshot '${SnapshotName}' deletion for VM '${VmName}' was initiated by ${UserName}.
343USER_FAILED_REMOVE_SNAPSHOTErrorFailed to remove Snapshot ${SnapshotName} for VM ${VmName} (User: ${UserName}).
344USER_UPDATE_VM_POOL_WITH_VMSInfoVM Pool ${VmPoolName} was updated by ${UserName}, ${VmsCount} VMs were added.
345USER_UPDATE_VM_POOL_WITH_VMS_FAILEDErrorFailed to update VM Pool ${VmPoolName}(User: ${UserName}).
346USER_PASSWORD_CHANGEDInfoPassword changed successfully for ${UserName}
347USER_PASSWORD_CHANGE_FAILEDErrorFailed to change password. (User: ${UserName})
348USER_CLEAR_UNKNOWN_VMSInfoAll VMs' status on Non Responsive Host ${VdsName} were changed to 'Down' by ${UserName}
349USER_FAILED_CLEAR_UNKNOWN_VMSErrorFailed to clear VMs' status on Non Responsive Host ${VdsName}. (User: ${UserName}).
350USER_ADD_BOOKMARKInfoBookmark ${BookmarkName} was added by ${UserName}.
351USER_ADD_BOOKMARK_FAILEDErrorFailed to add bookmark: ${BookmarkName} (User: ${UserName}).
352USER_UPDATE_BOOKMARKInfoBookmark ${BookmarkName} was updated by ${UserName}.
353USER_UPDATE_BOOKMARK_FAILEDErrorFailed to update bookmark: ${BookmarkName} (User: ${UserName})
354USER_REMOVE_BOOKMARKInfoBookmark ${BookmarkName} was removed by ${UserName}.
355USER_REMOVE_BOOKMARK_FAILEDErrorFailed to remove bookmark ${BookmarkName} (User: ${UserName})