6.286. Vms

表6.895 メソッドの概要

名前概要

add

新しい仮想マシンを作成します。

list

システムの仮想マシンの一覧を返します。

6.286.1. add POST

新しい仮想マシンを作成します。

仮想マシンはさまざまな方法で作成できます。

  • テンプレートから。この場合、テンプレートの識別子または名前を指定する必要があります。たとえば、プレーンシェルスクリプトと XML を使用すると、次のようになります。 
#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Version: 4" \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<vm>
  <name>myvm</name>
  <template>
    <name>Blank</name>
  </template>
  <cluster>
    <name>mycluster</name>
  </cluster>
</vm>
' \
"${url}/vms"
  • スナップショットから。この場合、スナップショットの識別子を指定する必要があります。たとえば、プレーンシェルスクリプトと XML を使用すると、次のようになります。 
#!/bin/sh -ex

url="https://engine.example.com/ovirt-engine/api"
user="admin@internal"
password="..."
curl \
--verbose \
--cacert /etc/pki/ovirt-engine/ca.pem \
--user "${user}:${password}" \
--request POST \
--header "Content-Type: application/xml" \
--header "Accept: application/xml" \
--data '
<vm>
  <name>myvm</name>
  <snapshots>
    <snapshot id="266742a5-6a65-483c-816d-d2ce49746680"/>
  </snapshots>
  <cluster>
    <name>mycluster</name>
  </cluster>
</vm>
' \
"${url}/vms"

テンプレートまたはスナップショットから仮想マシンを作成する場合、通常は、仮想マシンのディスクを作成するストレージドメインを明示的に指定すると便利です。仮想マシンがテンプレートから作成された場合、マッピングを示す一連の disk_attachment 要素を渡すことで、これを行うことができます。 

<vm>
  ...
  <disk_attachments>
    <disk_attachment>
      <disk id="8d4bd566-6c86-4592-a4a7-912dbf93c298">
        <storage_domains>
          <storage_domain id="9cb6cb0a-cf1d-41c2-92ca-5a6d665649c9"/>
        </storage_domains>
      </disk>
    <disk_attachment>
  </disk_attachments>
</vm>

仮想マシンがスナップショットから作成された場合、この一連のディスクは少し異なり、id の代わりに image_id 属性を使用します。 

<vm>
  ...
  <disk_attachments>
    <disk_attachment>
      <disk>
        <image_id>8d4bd566-6c86-4592-a4a7-912dbf93c298</image_id>
        <storage_domains>
          <storage_domain id="9cb6cb0a-cf1d-41c2-92ca-5a6d665649c9"/>
        </storage_domains>
      </disk>
    <disk_attachment>
  </disk_attachments>
</vm>

XML 記述で追加の仮想マシンパラメーターを指定することができます。たとえば、2 GiB の RAM を備えた desktop タイプの仮想マシンでは、次のようなリクエスト本文を送信することで記述を追加できます。 

<vm>
  <name>myvm</name>
  <description>My Desktop Virtual Machine</description>
  <type>desktop</type>
  <memory>2147483648</memory>
  ...
</vm>

起動可能な CDROM デバイスは、次のように設定できます。 

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

CDROM から起動するには、CDROM サービス で説明されているように、まずディスクを挿入する必要があります。次に、os.boot.devices 属性を使用して、その CDROM からの起動を指定できます。 

<vm>
  ...
  <os>
    <boot>
      <devices>
        <device>cdrom</device>
      </devices>
    </boot>
  </os>
</vm>

いずれの場合も、仮想マシンが作成されるクラスターの名前または識別子は必須です。

表6.896 パラメーターの概要

名前タイプ方向概要

auto_pinning_policy

AutoPinningPolicy

In

自動 CPU および NUMA 設定を適用するかどうか、およびその適用方法を指定します。

clone

Boolean

In

仮想マシンをテンプレートから独立させる必要があるかどうかを指定します。

clone_permissions

Boolean

In

テンプレートの権限を仮想マシンにコピーするかどうかを指定します。

filter

Boolean

In

管理者ユーザーにのみ関連しています。

seal

Boolean

In

作成後に仮想マシンをシールするかどうかを指定します。

vm

Vm

In/Out

 

6.286.1.1. auto_pinning_policy

自動 CPU および NUMA 設定を適用するかどうか、およびその適用方法を指定します。

重要

エンジンのバージョン 4.5 以降、この操作は非推奨になり、後方互換性のためにのみ保持されます。これは今後削除されます。代わりに、POST に続いて 追加操作 を使用してください。

リクエストの例: 

POST /ovirt-engine/api/vms?auto_pinning_policy=existing/adjust

リクエスト本文は以下のようになります。 

<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
  <placement_policy>
    <hosts>
      <host>
        <name>myhost</name>
      </host>
    </hosts>
  </placement_policy>
</vm>

6.286.1.2. clone

仮想マシンをテンプレートから独立させる必要があるかどうかを指定します。

仮想マシンがテンプレートからデフォルトで作成される場合、仮想マシンのディスクはテンプレートのディスクに依存し、copy on write メカニズムを使用して、テンプレートとの違いだけが実際のストレージスペースを使用するようにします。このパラメーターが指定され、値が true の場合、作成された仮想マシンのディスクは 複製 され、テンプレートとは無関係になります。たとえば、独立した仮想マシンを作成するには、次のようなリクエストを送信します。 

POST /ovirt-engine/vms?clone=true

リクエスト本文は以下のようになります。 

<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>
注記

このパラメーターが true の場合、clone_permissions=true を使用する場合と同様に、テンプレートのパーミッションもコピーされます。

6.286.1.3. clone_permissions

テンプレートの権限を仮想マシンにコピーするかどうかを指定します。

このオプションのパラメーターが指定され、その値が true の場合、テンプレートのパーミッション (継承されたものではなく、直接のパーミッションのみ) が作成された仮想マシンにコピーされます。たとえば、mytemplate テンプレートから仮想マシンを作成し、そのパーミッションをコピーするには、次のようなリクエストを送信します。 

POST /ovirt-engine/api/vms?clone_permissions=true

リクエスト本文は以下のようになります。 

<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>

6.286.1.4. filter

管理者ユーザーにのみ関連しています。作成された仮想マシンでこのユーザーに UserVmManager ロールを割り当てるかどうかを示します。これにより、ユーザーは後で管理者権限を放棄して (filter=true を指定することにより)、非管理者ユーザーであるかのように仮想マシンにアクセスできるようになります。

注記

既存の仮想マシンに対する admin-as-user (filter=true を指定) POST リクエストは、以前に管理者がユーザーとして (filter=true を使用して) 作成した仮想マシン以外では失敗します。

6.286.1.5. seal

作成後に仮想マシンをシールするかどうかを指定します。

このオプションのパラメーターが指定され、その値が true の場合、仮想マシンは作成後にシールされます。値が 'false' の場合、仮想マシンはシールされません。パラメーターが提供されていない場合、仮想マシンは、シールされたテンプレートから作成され、そしてゲスト OS が Windows に設定されていない場合にのみ、シールされます。

たとえば、mytemplate テンプレートから仮想マシンを作成してシールするには、以下のようなリクエストを送信します。 

POST /ovirt-engine/api/vms?seal=true

リクエスト本文は以下のようになります。 

<vm>
  <name>myvm<name>
  <template>
    <name>mytemplate<name>
  </template>
  <cluster>
    <name>mycluster<name>
  </cluster>
</vm>

6.286.2. list GET

システムの仮想マシンの一覧を返します。

返される仮想マシンのリストの順序は、sortby 句が search パラメーターに含まれている場合にのみ保証されます。

表6.897 パラメーターの概要

名前タイプ方向概要

all_content

Boolean

In

仮想マシンのすべての属性を応答に含める必要があるかどうかを示します。

case_sensitive

Boolean

In

search パラメーターを使用して実行する検索を、大文字と小文字を区別して実行する必要があるかどうかを示します。

filter

Boolean

In

ユーザーのパーミッションにしたがって、結果をフィルターする必要があるかどうかを示します。

follow

文字列

In

たどる 必要のある内部リンクを指定します。

max

Integer

In

返すことのできる結果の最大数。

ovf_as_ova

Boolean

In

結果が、その VM の OVA ファイルに表示されるように OVF を公開する必要があるかどうかを示します。

search

文字列

In

返される仮想マシンを制限するために使用されるクエリー文字列。

vms

Vm[]

Out

 

6.286.2.1. all_content

仮想マシンのすべての属性を応答に含める必要があるかどうかを示します。

デフォルトでは、以下の属性が除外されます。

  • console
  • initialization.configuration.data - 仮想マシンを説明する OVF ドキュメント。
  • rng_source
  • soundcard
  • virtio-scsi

たとえば、仮想マシンの完全な表現を取得するには、次のようなリクエストを送信します。 

GET /ovirt-engine/api/vms?all_content=true
注記

これらの属性を含めない理由はパフォーマンスです。ほとんど使用されず、データベースへの追加のクエリーが必要です。そのため、本当に必要な場合にのみ、このパラメーターを使用するようにしてください。

6.286.2.2. case_sensitive

search パラメーターを使用して実行する検索を、大文字と小文字を区別して実行する必要があるかどうかを示します。デフォルト値は true です。つまり、大文字と小文字の区別が考慮されます。ケースを無視する場合は、false に設定します。

6.286.2.3. follow

たどる 必要のある内部リンクを指定します。これらのリンクで参照されるオブジェクトは、現在の要求の一部としてフェッチされます。詳細は、こちら を参照してください。

6.286.2.4. ovf_as_ova

結果が、その VM の OVA ファイルに表示されるように OVF を公開する必要があるかどうかを示します。仮想マシンを記述する OVF ドキュメント。このパラメーターは、all_content=True が設定されている場合にのみ機能します。OVF は initialization.configuration.data に提示されます。

以下はその例です。 

GET /vms?all_content=true&ovf_as_ova=true