『Python SDK Guide』

Red Hat Virtualization 4.4

Red Hat Virtualization Python SDK の使用

概要

本ガイドでは、Red Hat Virtualization Python ソフトウェア開発キットのバージョン 4 をインストールして作業する方法を説明します。

第1章 概要

Python ソフトウェア開発キットのバージョン 4 は、Python ベースのプロジェクトで Red Hat Virtualization Manager との対話を可能にするクラスのコレクションです。これらのクラスをダウンロードし、プロジェクトに追加すると、管理タスクのハイレベル自動化の機能範囲にアクセスできます。

注記

SDK のバージョン 3 はサポートされなくなりました。詳細は、RHV 4.3 のガイドを参照してください

Python 3.7 および async

Python 3.7 以降のバージョンでは、async は予約されたキーワードです。たとえば、async =True によりエラーが発生するため、以下の例のように、以前にサポートされていたサービスのメソッドに async パラメーターを使用することはできません。

dc = dc_service.update(
    types.DataCenter(
        description='Updated description',
    ),
    async=True,
)

このソリューションでは、パラメーター(async_)にアンダースコアを追加します。

dc = dc_service.update(
    types.DataCenter(
        description='Updated description',
    ),
    async_=True,
)
注記

この制限は、Python 3.7 以降にのみ適用されます。Python の以前のバージョンでは、この変更は必要ありません。

1.1. 前提条件

Python ソフトウェア開発キットをインストールするには、以下が必要になります。

  • Red Hat Enterprise Linux 8 がインストールされているシステム。Server と Workstation の両方のバリアントがサポートされます。
  • Red Hat Virtualization エンタイトルメントのサブスクリプション。
重要

ソフトウェア開発キットは、Red Hat Virtualization REST API のインターフェースです。お使いの Red Hat Virtualization 環境のバージョンに対応するソフトウェア開発キットのバージョンを使用します。たとえば、Red Hat Virtualization 4.3 を使用している場合は、V4 Python ソフトウェア開発キットを使用します。

1.2. Python Software Development Kit のインストール

Python ソフトウェア開発キットをインストールするには、以下を行います。

  1. ハードウェアプラットフォームに適した リポジトリーを有効にします。たとえば、x86-64 ハードウェアの場合は、以下を有効にします。

    # subscription-manager repos \
        --enable=rhel-8-for-x86_64-baseos-rpms \
        --enable=rhel-8-for-x86_64-appstream-rpms \
        --enable=rhv-4.4-manager-for-rhel-8-x86_64-rpms
  2. 必要なパッケージをインストールします。

    # dnf install python3-ovirt-engine-sdk4

Python ソフトウェア開発の kit は Python 3 の site-packages ディレクトリーにインストールされ、付随するドキュメントと例は /usr/share/doc/python3-ovirt-engine-sdk4 にインストールされます。

第2章 Software Development Kit の使用

本セクションでは、バージョン 4 のソフトウェア開発キットを使用する方法を説明します。

2.1. packages

以下のモジュールは、Python SDK によって最も頻繁に使用されます。

ovirtsdk4

これはトップレベルのモジュールです。最も重要な要素は Connection クラスで、サーバーへ接続し、サービスツリーのルートへの参照を取得します。

Error クラスは、エラーを報告する必要がある場合に SDK が引き上げるベース例外クラスです。

特定の種類のエラーには、基本エラークラスを拡張する特定のエラークラスがあります。

  • AuthError: 認証または承認が失敗した場合に繰り返し使用されます。
  • ConnectionError: サーバー名が解決できないか、サーバーに到達できない場合に上書きします。
  • NotFoundError: 要求されたオブジェクトが存在しないと照合されます。
  • TimeoutError: 操作のタイムアウト時に戻ります。
ovirtsdk4.types

このモジュールには、API で使用される型を実装するクラスが含まれます。たとえば、ovirtsdk4.types.Vm クラスは仮想マシンタイプの実装です。これらのクラスはデータコンテナーであり、ロジックは含まれません。

これらのクラスのインスタンスは、サービスメソッドのパラメーターおよび戻り値として使用されます。基礎となる表現に対する変換は、SDK によって透過的に処理されます。

ovirtsdk4.services

このモジュールには、API がサポートするサービスを実装するクラスが含まれます。たとえば、ovirtsdk4.services.VmsService クラスは、システムの仮想マシンのコレクションを管理するサービスの実装です。

これらのクラスのインスタンスは、サービスがある場合に SDK によって自動的に作成されます。たとえば、Vm sService クラスの新規インスタンスは、以下の方法で SDK によって自動的に作成されます。

vms_service = connection.system_service().vms_service()

コンストラクターのパラメーターおよび一般的な方法では、サービスロケーターおよびサービスメソッド以外のすべてのメソッドが今後変更される可能性があるため、これらのクラスのインスタンスを手動で作成しないようにすることをお勧めします。

ovirtsdk4.http、ovirtsdk4. readers、および ovirtsdk4.writers などの他のモジュールがあります。これらは、HTTP 通信の実装や、XML の解析とレンダリングに使用されます。今後変更される可能性がある内部実装の詳細であるため、それらは使用しないでください。後方互換性は保証されません。

2.2. サーバーへの接続

サーバーに接続するには、Connection クラスが含まれる ovirtsdk4 モジュールをインポートします これは SDK のエントリーポイントであり、API のサービスのツリーツリーのルートへのアクセスを提供します。

import ovirtsdk4 as sdk

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

この接続は、サーバーへの HTTP 接続プールや認証トークンを含む重要なリソースを保持します。これらのリソースが使用されなくなった場合に、これらのリソースを解放することは非常に重要です。

connection.close()

接続が閉じられると、再利用できません。

TLS を使用して保護されたサーバーに接続する場合は、ca .pem ファイルが必要です。通常インストールでは、Manager マシンの /etc/pki/ovirt-engine/ にあります。ca_file を指定しないと、システム全体の CA 証明書ストアが使用されます。ca.pem ファイルの取得に関する詳細は、『 REST API Guide』を参照してください

接続に成功すると、SDK は、詳細を含む ovirtsdk4.Error 例外を発生させます。

2.3. タイプの使用

ovirtsdk4.types モジュールのクラスは純粋なデータコンテナーです。ロジックや操作はありません。種別のインスタンスは作成および変更できます。

以下のようなサービスメソッドへの呼び出しで明示的に変更が渡されない限り、インスタンスの作成または変更はサーバー側では影響を受けません。サーバー側への変更は、メモリーにすでに存在するインスタンスに自動的に反映されません。

これらのクラスのコンストラクターには、型の各属性に対して複数の任意の引数があります。これは、複数のコンストラクターへのネストされた呼び出しを使用して、オブジェクトの作成を簡素化することを目的としています。この例では、クラスター名、テンプレート、およびメモリーを指定して仮想マシンのインスタンスを作成します(バイト単位)。

from ovirtsdk4 import types

vm = types.Vm(
    name='vm1',
    cluster=types.Cluster(
        name='Default'
    ),
    template=types.Template(
        name='mytemplate'
    ),
    memory=1073741824
)

この方法でのコンストラクターの使用は推奨されていませんが、必須ではありません。コンストラクターへの呼び出しに引数なしでインスタンスを作成し、セッターを使用してステップごとにオブジェクトステップに設定することも、以下の 2 つのアプローチを組み合わせて使用することもできます。

vm = types.Vm()
vm.name = 'vm1'
vm.cluster = types.Cluster(name='Default')
vm.template = types.Template(name='mytemplate')
vm.memory=1073741824

API の仕様のオブジェクト一覧として定義される属性は、Python リストとして実装されます。たとえば、Vm タイプの custom_properties 属性は CustomProperty タイプのオブジェクトのリストとして定義されます。属性が SDK で使用される場合、それらは Python リストになります。

vm = types.Vm(
    name='vm1',
    custom_properties=[
        types.CustomProperty(...),
        types.CustomProperty(...),
        ...
    ]
)

API の列挙値として定義される属性は、Python 3 での 列挙 のネイティブサポートおよび Python 2.7 の enum 34 パッケージのネイティブサポートを使用して、Python の enum として実装されます。この例では、Vm type の status 属性は Vm Status enum を使用して定義されます。

if vm.status == types.VmStatus.DOWN:
    ...
elif vm.status == types.VmStatus.IMAGE_LOCKED:
    ....
注記

API 仕様では、XML および JSON に使用されるため、列挙 タイプの値が小文字で表示されます。ただし、Python の規則は、列挙 値を大文字にします。

タイプのインスタンスの属性の読み取りは、対応するプロパティーを使用して行います。

print("vm.name: %s" % vm.name)
print("vm.memory: %s" % vm.memory)
for custom_property in vm.custom_properties:
    ...

2.5. サービスの検索

API は複数のサービスを提供し、各サービスはサーバーの URL スペース内のパスに関連付けられます。たとえば、システムの仮想マシンのコレクションを管理するサービスは /vms に、識別子 123 で仮想マシンを管理するサービスは /vms/123 にあります。

SDK では、そのサービスのツリーのルートはシステムサービスによって実装されます。接続の system_service メソッドを呼び出します。

system_service = connection.system_service()

このシステムサービスへの参照がある場合は、それを使用して他のサービスへの参照を取得し、サービスロケーター(サービスロケーター)という *_service メソッドを呼び出すことができます。たとえば、システムの仮想マシンコレクションを管理するサービスへの参照を取得する場合は、vms _service サービスロケーターを使用します。

vms_service = system_service.vms_service()

識別子 123 で仮想マシンを管理するサービスへの参照を取得するには、仮想マシンのコレクションを管理するサービスの vm_service サービスロケーターを使用します。これは、仮想マシンの識別子をパラメーターとして使用します。

vm_service = vms_service.vm_service('123')
重要

サービスロケーターの呼び出しは、サーバーにリクエストを送信しません。返す Python オブジェクトは純粋なサービスであり、これにはデータは含まれません。たとえば、この例で呼び出される vm_service Python オブジェクトは仮想マシンの表現ではありません。これは、その仮想マシンの取得、更新、削除、起動、および停止に使用されるサービスです。

2.6. サービスの使用

サービスを取得したら、そのサービスメソッドを呼び出すことができ、サーバーに要求を送信し、実際の作業を行うことができます。

1 つのオブジェクトを管理するサービスは、通常、メソッド の取得更新および削除 をサポートします。

オブジェクトのコレクションを管理するサービスは、通常 list および add メソッドをサポートします。

単一のオブジェクトを管理するサービス(特に単一オブジェクトを管理するサービス)はどちらも、追加のアクションメソッドをサポートできます。

2.6.1. get メソッドの使用

これらのサービスメソッドは、単一オブジェクトの表現を取得するために使用されます。以下の例では、識別子 123 で仮想マシンを表します。

# Find the service that manages the virtual machine:
vms_service = system_service.vms_service()
vm_service = vms_service.vm_service('123')

# Retrieve the representation of the virtual machine:
vm = vm_service.get()

応答は、対応するタイプのインスタンスです。この場合、Python クラス ovirtsdk4.types.Vm のインスタンスになります。

一部のサービスの get メソッドは、オブジェクトの表示方法や、複数のオブジェクトが存在する場合に取得する表現を取得する方法を制御する追加のパラメーターをサポートします。たとえば、仮想マシンの現在の状態や、次回の起動時の状態は異なる可能性があるためです。仮想マシンを管理するサービスの get メソッドは、next_run ブール値パラメーターをサポートします。

# Retrieve the representation of the virtual machine, not the
# current one, but the one that will be used after the next
# boot:
vm = vm_service.get(next_run=True)

詳細は、SDK のリファレンスドキュメントを参照してください

何らかの理由でオブジェクトを取得できない場合は、SDK は ovirtsdk4.Error 例外を発生させ、エラーの詳細を追加します。これには、オブジェクトが実際に存在しない場合が含まれます。この例外は、get サービス メソッドを呼び出す際に発生します。サービスロケーターメソッドへの呼び出しは、呼び出しがサーバーにリクエストを送信しないため、オブジェクトが存在しない場合でも失敗しません。以下に例を示します。

# Call the service that manages a non-existent virtual machine.
# This call will succeed.
vm_service = vms_service.vm_service('junk')

# Retrieve the virtual machine. This call will raise an exception.
vm = vm_service.get()

2.6.2. リスト メソッドの使用

これらのサービスメソッドは、コレクションのオブジェクト表現を取得します。以下の例では、システムの仮想マシンの完全なコレクションを取得します。

# Find the service that manages the collection of virtual
# machines:
vms_service = system_service.vms_service()

# List the virtual machines in the collection
vms = vms_service.list()

その結果、対応するタイプのインスタンスが含まれる Python リストが作成されます。たとえば、この場合は、ovirt sdk4.types.Vm クラスのインスタンス一覧になります。

一部のサービスの 方法により、追加のパラメーターがサポートされます。たとえば、ほぼすべての最上位コレクションは search パラメーターをサポートし、結果や max パラメーターを指定して、サーバーで返される結果の数を制限します。この例では、my で始まる仮想マシンの名前を取得し 上限が 10 件になります。

vms = vms_service.list(search='name=my*', max=10)
注記

すべての リスト メソッドがこれらのパラメーターをサポートする訳ではありません。リスト メソッドによっては、他のパラメーターをサポートするものもあります。詳細は、SDK のリファレンスドキュメントを参照してください

何らかの理由で返される結果のリストが空の場合は、戻り値が空のリストになります。None になることはありません。

結果の取得中にエラーが発生した場合には、SDK は、エラーの詳細を含む ovirtsdk4.Error 例外を発生させます。

2.6.3. 追加 メソッドの使用

これらのサービスメソッドにより、新しい要素がコレクションに追加されます。それらは、追加するオブジェクトを記述した関連タイプのインスタンスを受け取り、それを追加する要求を送信し、追加されたオブジェクトを記述するタイプのインスタンスを返します。

この例では、vm1 という新しい仮想マシンを追加します。

from ovirtsdk4 import types

# Add the virtual machine:
vm = vms_service.add(
    vm=types.Vm(
        name='vm1',
        cluster=types.Cluster(
            name='Default'
        ),
        template=types.Template(
            name='mytemplate'
        )
    )
)

何らかの理由でオブジェクトを作成できない場合、SDK は、エラーの詳細を含む ovirtsdk4.Error 例外を発生させます。None を返すことはありません。

重要

この add メソッドによって返される Python オブジェクトは、適切なタイプのインスタンスです。これはサービスではなく、データのコンテナーです。この例では、返されるオブジェクトは ovirtsdk4.types.Vm クラスのインスタンス です。仮想マシンの作成後に、仮想マシンの取得や起動などの操作を実施する必要があります。まず、そのサービスを管理するサービスを見つけ、対応するサービスロケーターを呼び出す必要があります。

# Add the virtual machine:
vm = vms_service.add(
  ...
)

# Find the service that manages the virtual machine:
vm_service = vms_service.vm_service(vm.id)

# Start the virtual machine
vm_service.start()

オブジェクトは非同期に作成されます。新しい仮想マシンを作成すると、add メソッドは、仮想マシンが完全に作成され、使用できる準備ができる前に応答を返します。オブジェクトのステータスをポーリングして、完全に作成されることを確認することが推奨されます。仮想マシンでは、ステータスが DOWN になるまで確認する必要があります。

# Add the virtual machine:
vm = vms_service.add(
  ...
)

# Find the service that manages the virtual machine:
vm_service = vms_service.vm_service(vm.id)

# Wait until the virtual machine is down, indicating that it is
# completely created:
while True:
    time.sleep(5)
    vm = vm_service.get()
    if vm.status == types.VmStatus.DOWN:
        break

ループを使用してオブジェクトのステータスを取得し、get メソッドで status 属性が更新されていることを確認します。

2.6.4. 更新 メソッドの使用

これらのサービスメソッドは、既存のオブジェクトを更新します。これらは、更新の実行、更新するリクエストの送信、更新されたオブジェクトを記述するタイプのインスタンスを返します。

この例では、仮想マシンの名前を vm1 から newvm に更新します。

from ovirtsdk4 import types

# Find the virtual machine, and then the service that
# manages it:
vm = vms_service.list(search='name=vm1')[0]
vm_service = vm_service.vm_service(vm.id)

# Update the name:
updated_vm = vm_service.update(
    vm=types.Vm(
        name='newvm'
    )
)

更新の実行時には、オブジェクトの 完全な 表現を送信しないでください。更新する属性のみを送信します。次の作業を行わないでください。

# Retrieve the complete representation:
vm = vm_service.get()

# Update the representation, in memory, without sending a request
# to the server:
vm.name = 'newvm'

# Send the update. Do *not* do this.
vms_service.update(vm)

完全な表現を送信すると、2 つの問題が発生します。

  • そのため、リソースが必要と比べ、多くの情報を送信することになります。
  • サーバーは、変更予定されていないものであっても、オブジェクトのすべての属性の更新を試みます。これにより、サーバー側でバグが発生する可能性があります。

一部のサービスの更新は、更新方法または更新する方法を制御する追加のパラメーターをサポートします。たとえば、仮想マシンの現在の状態、または仮想マシンの次回起動時に使用される状態のいずれかを更新する必要がある場合があります。仮想マシンを管理するサービスの更新 方法は、next_run ブール値パラメーターをサポートします。

# Update the memory of the virtual machine to 1 GiB,
# not during the current run, but after next boot:
vm = vm_service.update(
    vm=types.Vm(
        memory=1073741824
    ),
    next_run=True
)

何らかの理由で更新を実行できない場合は、SDK は、エラーの詳細を含む ovirtsdk4.Error 例外を発生させます。None を返すことはありません。

この更新メソッドによって返される Python オブジェクトは、適切なタイプのインスタンスです。これはサービスではなく、データ用のコンテナーです。この例では、返されるオブジェクトは ovirtsdk4.types.Vm クラスのインスタンス になります。

2.6.5. 削除 メソッドの使用

これらのサービスメソッドは、既存のオブジェクトを削除します。これらは、単一のオブジェクトを管理するサービスのメソッドであるため、通常はパラメーターを取りません。したがって、このサービスは削除するオブジェクトを認識している。

以下の例では、識別子 123 の仮想マシンを削除します。

# Find the virtual machine by name:
vm = vms_service.list(search='name=123')[0]

# Find the service that manages the virtual machine using the ID:
vm_service = vms_service.vm_service(vm.id)

# Remove the virtual machine:
vm_service.remove()

一部のサービスの remove メソッドは、削除する方法や削除方法を制御する追加のパラメーターをサポートします。たとえば、un detach_only のブール値パラメーターを使用して、ディスクを維持したまま仮想マシンを削除できます。

# Remove the virtual machine while preserving the disks:
vm_service.remove(detach_only=True)

オブジェクトが正常に削除されると、削除 メソッドは None を返します。削除されたオブジェクトを返しません。何らかの理由でオブジェクトを削除できない場合、SDK は、エラーの詳細を含む ovirtsdk4.Error 例外を発生させます。

2.6.6. 他のアクションメソッドの使用

仮想マシンの停止や起動など、さまざまな操作を実行するサービスメソッドもあります。

# Start the virtual machine:
vm_service.start()

これらのメソッドの多くは、操作を変更するパラメーターが含まれます。たとえば、仮想マシンを起動する方法は、cloud -init を使用して起動する場合は、use_cloud_ init パラメーターをサポートします。

# Start the virtual machine:
vm_service.start(cloud_init=True)

ほとんどのアクションメソッドは、成功時に None を返し、失敗すると ovirtsdk4.Error を発生させます。いくつかのアクションメソッドの戻り値。たとえば、ストレージドメインを管理するサービスには、ストレージドメインがすでにデータセンターにアタッチされているかどうかを確認し、ブール値を返す is_attached アクションメソッドがあります。

# Check if the storage domain is attached to a data center:
sds_service = system_service.storage_domains_service()
sd_service = sds_service.storage_domain_service('123')
if sd_service.is_attached():
    ...

SDK のリファレンスドキュメントを参照して、各サービスがサポートするアクションメソッド、それらが実行されるパラメーター、および返す値を確認します。

2.7. 関連情報

詳細情報およびサンプルは、以下のリソースを参照してください。

モジュールの生成

以下のモジュールの pydoc を使用してドキュメントを生成することができます。

  • ovirtsdk.api
  • ovirtsdk.infrastructure.brokers
  • ovirtsdk.infrastructure.errors

本書は ovirt-engine-sdk-python パッケージで提供されます。Manager マシンで以下のコマンドを実行し、これらのドキュメントの最新バージョンを表示します。

$ pydoc [MODULE]

第3章 Python の例

3.1. 概要

本セクションでは、Python SDK を使用して基本的な Red Hat Virtualization 環境に仮想マシンを作成する手順を説明します。

これらの例では、ovirt -engine-sdk -python パッケージが提供する ovirtsdk Python ライブラリーを使用します。このパッケージは、Red Hat Subscription Manager の Red Hat Virtualization サブスクリプションプールに割り当てられたシステムで利用できます。ソフトウェアをダウンロードするシステムをサブスクライブする方法は、「Python Software Development Kit のインストール」 を参照してください。

以下も必要になります。

  • Red Hat Virtualization Manager のネットワークインストール。
  • ネットワークおよび設定された Red Hat Virtualization Host
  • 仮想マシンへのインストール用のオペレーティングシステムを含む ISO イメージファイル。
  • Red Hat Virtualization 環境を構成する論理オブジェクトと物理オブジェクトの両方の理解
  • Python プログラミング言語の理解

この例には、認証情報のプレースホルダー(ユーザー名の場合はadmin@internalパスワードの password )が含まれます。プレースホルダーを、お使いの環境の認証要件に置き換えます。

Red Hat Virtualization Manager は、各リソースの id 属性にグローバルに一意の識別子(GUID)を生成します。これらの例の ID コードは、Red Hat Virtualization 環境の識別子コードとは異なります。

この例には、基本的な例外およびエラー処理ロジックのみが含まれます。SDK に固有の例外処理の詳細は、ovirt sdk.infrastructure.errors モジュールの pydoc を参照してください。

$ pydoc ovirtsdk.infrastructure.errors

3.2. バージョン 4 での Red Hat Virtualization Manager への接続

Red Hat Virtualization Manager に接続するには、スクリプトの開始時にクラスをインポートして、ovirtsdk4.sdk モジュールから Connection クラスのインスタンスを作成する必要があります。

import ovirtsdk4 as sdk

Connection クラスのコンストラクターは多数の引数を取ります。サポートされる引数は次のとおりです。

url
Manager のベース URL(例: https://server.example.com/ovirt-engine/api)が含まれる文字列
username
接続するユーザー名を指定します(例: admin@internal )。このパラメーターは必須です。
パスワード
username パラメーターで指定したユーザー名のパスワードを指定します。このパラメーターは必須です。
token
ユーザー名とパスワードの代わりに API にアクセスするためのオプションのトークンです。token パラメーターが指定されていない場合、SDK は自動的に作成されます。
insecure
サーバーの TLS 証明書とホスト名をチェックするかどうかを示すブール値フラグ。
ca_file
信頼される CA 証明書を含む PEM ファイル。サーバーによって提示される証明書は、これらの CA 証明書を使用して検証されます。ca_file パラメーターが設定されていない場合、システム全体の CA 証明書ストアが使用されます。
debug

デバッグ出力を生成するかどうかを示すブール値フラグ。値が True で、ログ パラメーターが None ではない場合には、サーバーへ送信され、受信されたデータはログに書き込まれます。

注記

ユーザー名とパスワードはデバッグログに書き込まれるため、注意して処理します。

圧縮はデバッグモードで無効になり、デバッグメッセージはプレーンテキストとして送信されます。

log
ログメッセージが書き込まれるロガー。
kerberos
デフォルトの Basic 認証の代わりに Kerberos 認証を使用するかどうかを示すブール値フラグ。
timeout
応答を待つ最大時間(秒単位)。0 (デフォルト)を指定すると永久に待機します。応答を受け取る前にタイムアウトが期限切れになると、例外が発生します。
compress
SDK がサーバーに圧縮応答を送信するように要求するかどうかを示すブール値フラグ。デフォルトは True です。これは、このパラメーターが True に設定されている場合でも圧縮されていないデータを返すサーバーのヒントです。圧縮はデバッグモードで無効になり、デバッグメッセージはプレーンテキストとして送信されます。
sso_url
サーバーのベース SSO URL を含む文字列。デフォルトの SSO URL は、sso_url が指定されていない場合に URL から計算されます。
sso_revoke_url
SSO revoke サービスのベース URL を含む文字列。これは、外部認証サービスを使用している場合にのみ指定する必要があります。デフォルトでは、この URL は url パラメーターの値から自動的に算出されるため、Manager の一部である SSO トークンが SSO サービスを使用して実行されます。
sso_token_name
SSO サーバーから返された JSON SSO 応答のトークン名。デフォルト値は access_token です。
ヘッダー
すべてのリクエストで送信される必要がある、ヘッダーを持つディクショナリー。
connections
ホストを開く最大接続数。値が 0 (デフォルト)の場合、接続数は無制限になります。
pipeline
応答を待たずに HTTP パイプラインに配置する要求の最大数。値が 0 (デフォルト)の場合、パイプライン処理は無効になります。
import ovirtsdk4 as sdk

# Create a connection to the server:
connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

connection.test()

print("Connected successfully!")

connection.close()

サポートされるメソッドの全一覧については、Manager マシンで ovirtsdk.api モジュールのドキュメントを生成することができます。

$ pydoc ovirtsdk.api

3.3. データセンターの一覧表示

データセンター コレクションには、環境内のすべてのデータセンターが含まれます。

例3.1 データセンターの一覧表示

以下の例では、データセンターコレクションの データセンター を一覧表示して、コレクション内の各データセンターの基本情報を出力します。

V4

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

dcs_service = connection.system_service().dcs_service()

dcs = dcs_service.list()

for dc in dcs:
    print("%s (%s)" % (dc.name, dc.id))

connection.close()

デフォルト データセンターのみが存在する環境において、これはアクティベートされず、サンプルがテキストを出力します。

Default (00000000-0000-0000-0000-000000000000)

3.4. クラスターの一覧表示

クラスター コレクションには、環境のすべてのクラスターが含まれます。

例3.2 クラスターの一覧表示

この例では、クラスターコレクションの クラスター を一覧表示し、コレクションの各クラスターの基本情報を出力します。

V4

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

cls_service = connection.system_service().clusters_service()

cls = cls_service.list()

for cl in cls:
    print("%s (%s)" % (cl.name, cl.id))

connection.close()

デフォルト クラスターのみが存在する環境では、サンプルによってテキストが出力されます。

Default (00000000-0000-0000-0000-000000000000)

3.5. ホストの一覧表示

ホストコレクション には環境内の全ホストが含まれます。

例3.3 ホストの一覧表示

以下の例では、ホストコレクションの ホスト とその ID を一覧表示します。

V4

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

host_service = connection.system_service().hosts_service()

hosts = host_service.list()

for host in hosts:
    print("%s (%s)" % (host.name, host.id))

connection.close()

ホスト MyHost が 1 つだけアタッチされている環境では、サンプルがテキストを出力します。

MyHost (00000000-0000-0000-0000-000000000000)

3.6. 論理ネットワークの一覧表示

ネットワーク コレクションには、環境内のすべての論理ネットワークが含まれます。

例3.4 論理ネットワークの一覧表示

以下の例では、ネットワーク コレクションの論理ネットワークを一覧表示して、コレクションの各 ネットワークの基本情報を出力します。

V4

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

nws_service = connection.system_service().networks_service()

nws = nws_service.list()

for nw in nws:
    print("%s (%s)" % (nw.name, nw.id))

connection.close()

デフォルトの管理ネットワークのみが存在する環境では、例ではテキストを出力します。

ovirtmgmt (00000000-0000-0000-0000-000000000000)

3.7. 仮想マシンおよび合計ディスクサイズの一覧表示

vms コレクションには、仮想マシンに割り当てられる各 ディスク の詳細を記述するディスクコレクションが含まれます。

例3.5 仮想マシンの一覧および合計ディスクサイズ

以下の例では、仮想マシンの一覧とその合計ディスクサイズをバイト単位で出力します。

V4

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

vms_service = connection.system_service().vms_service()

virtual_machines = vms_service.list()

if len(virtual_machines) > 0:

    print("%-30s  %s" % ("Name", "Disk Size"))
    print("==================================================")

    for virtual_machine in virtual_machines:
        vm_service = vms_service.vm_service(virtual_machine.id)
        disk_attachments = vm_service.disk_attachments_service().list()
        disk_size = 0
        for disk_attachment in disk_attachments:
            disk = connection.follow_link(disk_attachment.disk)
            disk_size += disk.provisioned_size

            print("%-30s: %d" % (virtual_machine.name, disk_size))

この例では、仮想マシンの名前とそのディスクサイズを出力します。

Name                          Disk Size
==================================================
vm1                           50000000000

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

Red Hat Virtualization 環境を最初に作成したら、少なくともデータストレージドメインと ISO ストレージドメインを定義する必要があります。データストレージドメインは、ISO ストレージドメインがゲストオペレーティングシステムのインストールメディアを保存する一方で、仮想ディスクを保存します。

storagedomains コレクションには環境内のすべてのストレージドメインが含まれ、ストレージドメインの追加および削除に使用できます。

注記

この例のコードは、リモート NFS 共有が Red Hat Virtualization で使用するように設定されていることを前提としています。NFS 共有の準備に関する詳細は、『 管理ガイド』 を参照してください。

例3.6 NFS データストレージの作成

この例では、NFS データドメインを storagedomains コレクションに追加します。

V4

V4 では、add メソッドを使用して 新しいストレージドメインを追加し、type クラスを使用して以下のパラメーターを渡します。

  • ストレージドメインの名前。
  • データセンター コレクションから取得したデータセンターオブジェクト。
  • ホストコレクションから取得された ホスト オブジェクト。
  • 追加するストレージドメインのタイプ(data、iso または export)。
  • 使用するストレージ形式(v1、v2、または v3)
import ovirtsdk4 as sdk
import ovirtsdk4.types as types

# Create the connection to the server:
connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Get the reference to the storage domains service:
sds_service = connection.system_service().storage_domains_service()

# Create a new NFS storage domain:
sd = sds_service.add(
    types.StorageDomain(
        name='mydata',
        description='My data',
        type=types.StorageDomainType.DATA,
        host=types.Host(
            name='myhost',
        ),
        storage=types.HostStorage(
            type=types.StorageType.NFS,
            address='_FQDN_',
            path='/nfs/ovirt/path/to/mydata',
        ),
    ),
)

# Wait until the storage domain is unattached:
sd_service = sds_service.storage_domain_service(sd.id)
while True:
    time.sleep(5)
    sd = sd_service.get()
    if sd.status == types.StorageDomainStatus.UNATTACHED:
        break

print("Storage Domain '%s' added (%s)." % (sd.name(), sd.id()))

connection.close()

追加 メソッド呼び出しに成功すると、例ではテキストを出力します。

Storage Domain 'mydata' added (00000000-0000-0000-0000-000000000000).

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

仮想マシンを作成するには、ゲストオペレーティングシステム用にインストールメディアが必要です。インストールメディアは ISO ストレージドメインに保存されます。

注記

この例のコードは、リモート NFS 共有が Red Hat Virtualization で使用するように設定されていることを前提としています。NFS 共有の準備に関する詳細は、『 管理ガイド』 を参照してください。

例3.7 NFS ISO ストレージの作成

この例では、NFS ISO ドメインを storagedomains コレクションに追加します。

V4

V4 では、add メソッドを使用して 新しいストレージドメインを追加し、type クラスを使用して以下のパラメーターを渡します。

  • ストレージドメインの名前。
  • データセンター コレクションから取得したデータセンターオブジェクト。
  • ホストコレクションから取得された ホスト オブジェクト。
  • 追加するストレージドメインのタイプ(data、iso または export)。
  • 使用するストレージ形式(v1、v2、または v3)
import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Get the reference to the storage domains service:
sds_service = connection.system_service().storage_domains_service()

# Use the "add" method to create a new NFS storage domain:
sd = sds_service.add(
    types.StorageDomain(
        name='myiso',
        description='My ISO',
        type=types.StorageDomainType.ISO,
        host=types.Host(
            name='myhost',
        ),
        storage=types.HostStorage(
            type=types.StorageType.NFS,
            address='FQDN',
            path='/nfs/ovirt/path/to/myiso',
        ),
    ),
)

# Wait until the storage domain is unattached:
sd_service = sds_service.storage_domain_service(sd.id)
while True:
    time.sleep(5)
    sd = sd_service.get()
    if sd.status == types.StorageDomainStatus.UNATTACHED:
        break

print("Storage Domain '%s' added (%s)." % (sd.name(), sd.id()))

# Close the connection to the server:
connection.close()

追加 メソッド呼び出しに成功すると、例ではテキストを出力します。

Storage Domain 'myiso' added (00000000-0000-0000-0000-000000000000).

3.10. ストレージドメインのデータセンターへの割り当て

Red Hat Virtualization にストレージドメインを追加したら、そのストレージドメインをデータセンターにアタッチし、使用する準備が整う前にアクティブ化する必要があります。

例3.8 ストレージドメインのデータセンターへの割り当て

この例では、既存の NFS ストレージドメイン mydata を既存の データセンター(デフォルト)に接続し ています。アタッチアクションは、データセンターの ストレージドメインコレクション の追加 方法により容易になります。これらの例は、データおよび ISO ストレージドメインの両方を割り当てるために使用できます。

V4

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

# Create the connection to the server:
connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Locate the service that manages the storage domains and use it to
# search for the storage domain:
sds_service = connection.system_service().storage_domains_service()
sd = sds_service.list(search='name=mydata')[0]

# Locate the service that manages the data centers and use it to
# search for the data center:
dcs_service = connection.system_service().data_centers_service()
dc = dcs_service.list(search='name=Default')[0]

# Locate the service that manages the data center where we want to
# attach the storage domain:
dc_service = dcs_service.data_center_service(dc.id)

# Locate the service that manages the storage domains that are attached
# to the data centers:
attached_sds_service = dc_service.storage_domains_service()

# Use the "add" method of service that manages the attached storage
# domains to attach it:
attached_sds_service.add(
    types.StorageDomain(
        id=sd.id,
    ),
)

# Wait until the storage domain is active:
attached_sd_service = attached_sds_service.storage_domain_service(sd.id)
while True:
    time.sleep(5)
    sd = attached_sd_service.get()
    if sd.status == types.StorageDomainStatus.ACTIVE:
        break

print("Attached data storage domain '%s' to data center '%s' (Status: %s)." %
  (sd.name(), dc.name(), sd.status.state()))

# Close the connection to the server:
connection.close()

追加 メソッドへの呼び出しに成功すると、サンプルは以下のテキストを出力します。

Attached data storage domain 'data1' to data center 'Default' (Status: maintenance).

Status: maintenance は、ストレージドメインが依然としてアクティブにする必要があることを示します。

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

ストレージドメインを Red Hat Virtualization に追加し、データセンターにアタッチしたら、使用する準備が整う前にアクティブ化する必要があります。

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

この例では、データセンターにアタッチされた NFS ストレージドメイン mydataデフォルト )を有効にします。この アクティブ化 アクションは、ストレージドメインの activate メソッドにより容易になります。

V4

import ovirtsdk4 as sdk

connection = sdk.Connection
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Locate the service that manages the storage domains and use it to
# search for the storage domain:
sds_service = connection.system_service().storage_domains_service()
sd = sds_service.list(search='name=mydata')[0]

# Locate the service that manages the data centers and use it to
# search for the data center:
dcs_service = connection.system_service().data_centers_service()
dc = dcs_service.list(search='name=Default')[0]

# Locate the service that manages the data center where we want to
# attach the storage domain:
dc_service = dcs_service.data_center_service(dc.id)

# Locate the service that manages the storage domains that are attached
# to the data centers:
attached_sds_service = dc_service.storage_domains_service()

# Activate storage domain:
attached_sd_service = attached_sds_service.storage_domain_service(sd.id)
attached_sd_service.activate()

# Wait until the storage domain is active:
while True:
    time.sleep(5)
    sd = attached_sd_service.get()
    if sd.status == types.StorageDomainStatus.ACTIVE:
        break

print("Attached data storage domain '%s' to data center '%s' (Status: %s)." %
  (sd.name(), dc.name(), sd.status.state()))

# Close the connection to the server:
connection.close()

アクティブ化 リクエストに成功すると、例ではテキストを出力します。

Activated storage domain 'mydata' in data center 'Default' (Status: active).

status: active は、ストレージドメインがアクティベートされたことを示します。

3.12. ISO ストレージドメイン内のファイルの一覧表示

storagedomains コレクションには、ストレージドメインの ファイル を記述するファイルコレクションが含まれます。

例3.10 ISO ストレージドメイン内のファイルの一覧表示

以下の例では、各 ISO ストレージドメイン内の ISO ファイルの一覧を出力します。

V4

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

storage_domains_service = connection.system_service().storage_domains_service()

storage_domains = storage_domains_service.list()

for storage_domain in storage_domains:
    if(storage_domain.type == types.StorageDomainType.ISO):
        print(storage_domain.name + ":\n")
        files = storage_domain.files_service().list()

        for file in files:
            print("%s" % file.name + "\n")

connection.close()

この例ではテキストを出力します。

ISO_storage_domain:
file1
file2

3.13. 仮想マシンの作成

仮想マシンの作成は複数のステップで実行されます。ここで説明している最初のステップは、仮想マシンオブジェクト自体を作成することです。

例3.11 仮想マシンの作成

この例では、以下の要件で仮想マシン vm1 を作成します。

  • 512 MB のメモリー(バイト単位)
  • デフォルトクラスターにアタッチされているのでデフォルトの データセンターです。
  • デフォルトの Blank テンプレートに基づいています。
  • 仮想ハードディスクドライブから起動します。

V4

V4 では、オプションは add メソッドを使用して types として追加されます。

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Get the reference to the "vms" service:
vms_service = connection.system_service().vms_service()

# Use the "add" method to create a new virtual machine:
vms_service.add(
    types.Vm(
        name='vm1',
        memory = 512*1024*1024
        cluster=types.Cluster(
            name='Default',
        ),
        template=types.Template(
            name='Blank',
        ),
        os=types.OperatingSystem(boot=types.Boot(devices=[types.BootDevice.HD)]
    ),
)

print("Virtual machine '%s' added." % vm.name)

# Close the connection to the server:
connection.close()

追加 要求に成功すると、例ではテキストを出力します。

Virtual machine 'vm1' added.

3.14. 仮想 NIC の作成

新規に作成された仮想マシンにネットワークアクセスを持たせるには、仮想 NIC を作成し、割り当てる必要があります。

例3.12 仮想 NIC の作成

この例では、NIC、nic1 を作成し、これを仮想マシン vm1 に割り当てます。この例の NIC は virtio ネットワークデバイスで、ovirt mgmt 管理ネットワークにアタッチされます。

V4

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Locate the virtual machines service and use it to find the virtual
# machine:
vms_service = connection.system_service().vms_service()
vm = vms_service.list(search='name=vm1')[0]

# Locate the service that manages the network interface cards of the
# virtual machine:
nics_service = vms_service.vm_service(vm.id).nics_service()

# Locate the vnic profiles service and use it to find the ovirmgmt
# network's profile id:
profiles_service = connection.system_service().vnic_profiles_service()
profile_id = None
for profile in profiles_service.list():
    if profile.name == 'ovirtmgmt':
        profile_id = profile.id
        break

# Use the "add" method of the network interface cards service to add the
# new network interface card:

nic = nics_service.add(
    types.Nic(
        name='nic1',
        interface=types.NicInterface.VIRTIO,
        vnic_profile=types.VnicProfile(id=profile_id),
    ),
)

print("Network interface '%s' added to '%s'." % (nic.name, vm.name))

connection.close()

追加 要求に成功すると、例ではテキストを出力します。

Network interface 'nic1' added to 'vm1'.

3.15. 仮想マシンディスクの作成

新規に作成された仮想マシンが永続ストレージにアクセスできることを確認するには、ディスクを作成して割り当てる必要があります。

例3.13 仮想マシンディスクの作成

この例では、8 GB の virtio ディスクを作成し、これを仮想マシン vm1 に割り当てます。ディスクには以下の要件があります。

  • data1 という名前のストレージドメインに保管される
  • 8 GB のサイズ。
  • データではなく) システム タイプディスク。
  • virtio ストレージデバイス。
  • COW 形式。
  • 使用可能なブートデバイスとしてマークされている。

V4

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Locate the virtual machines service and use it to find the virtual
# machine:
vms_service = connection.system_service().vms_service()
vm = vms_service.list(search='name=vm1')[0]

# Locate the service that manages the disk attachments of the virtual
# machine:
disk_attachments_service = vms_service.vm_service(vm.id).disk_attachments_service()

# Use the "add" method of the disk attachments service to add the disk.
# Note that the size of the disk, the `provisioned_size` attribute, is
# specified in bytes, so to create a disk of 10 GiB the value should
# be 10 * 2^30.
disk_attachment = disk_attachments_service.add(
    types.DiskAttachment(
        disk=types.Disk(
            format=types.DiskFormat.COW,
            provisioned_size=8*1024*1024,
            storage_domains=[
                types.StorageDomain(
                    name='data1',
                ),
            ],
        ),
        interface=types.DiskInterface.VIRTIO,
        bootable=True,
        active=True,
    ),
)

# Wait until the disk status is OK:
disks_service = connection.system_service().disks_service()
disk_service = disks_service.disk_service(disk_attachment.disk.id)
while True:
    time.sleep(5)
    disk = disk_service.get()
    if disk.status == types.DiskStatus.OK:
        break

print("Disk '%s' added to '%s'." % (disk.name(), vm.name()))

# Close the connection to the server:
connection.close()

追加 要求に成功すると、例ではテキストを出力します。

Disk 'vm1_Disk1' added to 'vm1'.

3.16. ISO イメージの仮想マシンへの割り当て

新規に作成された仮想マシンにゲストオペレーティングシステムをインストールするには、オペレーティングシステムインストールメディアを含む ISO ファイルをアタッチする必要があります。ISO ファイルを検索するには、「ISO ストレージドメイン内のファイルの一覧表示」 を参照してください。

例3.14 ISO イメージの仮想マシンへの割り当て

この例では、仮想マシンの cdrom の追加 方法を使用して、my _iso_file.isovm1 仮想マシンに割り当てます。

V4

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Get the reference to the "vms" service:
vms_service = connection.system_service().vms_service()

# Find the virtual machine:
vm = vms_service.list(search='name=vm1')[0]

# Locate the service that manages the virtual machine:
vm_service = vms_service.vm_service(vm.id)

# Locate the service that manages the CDROM devices of the virtual machine:
cdroms_service = vm_service.cdroms_service()

# Get the first CDROM:
cdrom = cdroms_service.list()[0]

# Locate the service that manages the CDROM device found in previous step:
cdrom_service = cdroms_service.cdrom_service(cdrom.id)

# Change the CD of the VM to 'my_iso_file.iso'. By default the
# operation permanently changes the disk that is visible to the
# virtual machine after the next boot, but has no effect
# on the currently running virtual machine. If you want to change the
# disk that is visible to the current running virtual machine, change
# the `current` parameter's value to `True`.
cdrom_service.update(
    cdrom=types.Cdrom(
        file=types.File(
            id='my_iso_file.iso'
        ),
    ),
    current=False,
)

print("Attached CD to '%s'." % vm.name())

# Close the connection to the server:
connection.close()

追加 要求に成功すると、例ではテキストを出力します。

Attached CD to 'vm1'.

例3.15 仮想マシンからの cdrom の取り出し

この例では、仮想マシンの cdrom コレクションから ISO イメージを拒否します。

V4

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Get the reference to the "vms" service:
vms_service = connection.system_service().vms_service()

# Find the virtual machine:
vm = vms_service.list(search='name=vm1')[0]

# Locate the service that manages the virtual machine:
vm_service = vms_service.vm_service(vm.id)

# Locate the service that manages the CDROM devices of the VM:
cdroms_service = vm_service.cdroms_service()

# Get the first found CDROM:
cdrom = cdroms_service.list()[0]

# Locate the service that manages the CDROM device found in previous step
# of the VM:
cdrom_service = cdroms_service.cdrom_service(cdrom.id)

cdrom_service.remove()

print("Removed CD from '%s'." % vm.name())

connection.close()

要求 の削除 または削除 に成功すると、サンプルにテキストが出力されます。

Removed CD from 'vm1'.

3.17. ディスクの割り当て

仮想マシンへのディスクの割り当てを解除できます。

ディスクの割り当て解除

V4

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Get the reference to the "vms" service:
vms_service = connection.system_service().vms_service()

# Find the virtual machine:
vm = vms_service.list(search='name=vm1')[0]

# Locate the service that manages the virtual machine:
vm_service = vms_service.vm_service(vm.id)

attachments_service = vm_service.disk_attachments_service()
attachment = next(
    (a for a in disk_attachments if a.disk.id == disk.id), None
)

# Remove the attachment. The default behavior is that the disk is detached
# from the virtual machine, but not deleted from the system. If you wish to
# delete the disk, change the detach_only parameter to "False".
attachment.remove(detach_only=True)

print("Detached disk %s successfully!" % attachment)

# Close the connection to the server:
connection.close()

要求 の削除 または削除 に成功すると、サンプルにテキストが出力されます。

Detached disk vm1_disk1 successfully!

3.18. 仮想マシンの起動

仮想マシンを起動できます。

例3.16 仮想マシンの起動

この例では、start メソッドを使用して仮想マシンを起動します

V4

import time
import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Get the reference to the "vms" service:
vms_service = connection.system_service().vms_service()

# Find the virtual machine:
vm = vms_service.list(search='name=vm1')[0]

# Locate the service that manages the virtual machine, as that is where
# the action methods are defined:
vm_service = vms_service.vm_service(vm.id)

# Call the "start" method of the service to start it:
vm_service.start()

# Wait until the virtual machine is up:
while True:
    time.sleep(5)
    vm = vm_service.get()
    if vm.status == types.VmStatus.UP:
        break

print("Started '%s'." % vm.name())

# Close the connection to the server:
connection.close()

起動 リクエストに成功すると、例ではテキストを出力します。

Started 'vm1'.

UP ステータスは、仮想マシンが実行していることを示します。

3.19. 上書きされたパラメーターを使用した仮想マシンの起動

仮想マシンを起動し、そのデフォルトパラメーターを上書きできます。

例3.17 上書きされたパラメーターでの仮想マシンの起動

この例では、Windows ISO で仮想マシンを起動し、Windows ドライバーが含まれる virtio-win_x86.vfd floppy ディスクをアタッチします。このアクションは、管理ポータルで Run Once ウィンドウを使用して仮想マシンを起動する場合と同じです。

V4

import time
import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Get the reference to the "vms" service:
vms_service = connection.system_service().vms_service()

# Find the virtual machine:
vm = vms_service.list(search='name=vm1')[0]

# Locate the service that manages the virtual machine:
vm_service = vms_service.vm_service(vm.id)

# Locate the service that manages the CDROM devices of the virtual machine:
cdroms_service = vm_service.cdroms_service()

# Get the first CDROM:
cdrom = cdroms_service.list()[0]

# Locate the service that manages the CDROM device found in previous step:
cdrom_service = cdroms_service.cdrom_service(cdrom.id)

# Change the CD of the VM to 'windows_example.iso':
cdrom_service.update(
    cdrom=types.Cdrom(
        file=types.File(
            id='windows_example.iso'
        ),
    ),
    current=False,
)

# Call the "start" method of the service to start it:
vm_service.start(
    vm=types.Vm(
        os=types.OperatingSystem(
            boot=types.Boot(
                devices=[
                    types.BootDevice.CDROM,
                ]
            )
        ),
    )
)

# Wait until the virtual machine's status is "UP":
while True:
    time.sleep(5)
    vm = vm_service.get()
    if vm.status == types.VmStatus.UP:
        break

print("Started '%s'." % vm.name())

# Close the connection to the server:
connection.close()
注記

CD イメージおよびフロッピーディスクファイルは、仮想マシンで利用できる必要があります。詳細は、「 データストレージドメインへのイメージのアップロード 」を参照してください。

3.20. Cloud-Init での仮想マシンの起動

Cloud-Init ツールを使用して、特定の設定で仮想マシンを起動できます。

例3.18 Cloud-Init での仮想マシンの起動

この例では、Cloud-Init ツールを使用して、eth0 インターフェースのホスト名および静的 IP を設定するために Cloud-Init ツールを使用して仮想マシンを起動する方法を示しています。

V4

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Find the virtual machine:
vms_service = connection.system_service().vms_service()
vm = vms_service.list(search = 'name=vm1')[0]

# Find the service that manages the virtual machine:
vm_service = vms_service.vm_service(vm.id)

# Start the virtual machine enabling cloud-init and providing the
# password for the `root` user and the network configuration:
vm_service.start(
    use_cloud_init=True,
    vm=types.Vm(
        initialization=types.Initialization(
        user_name='root',
        root_password='password',
        host_name='MyHost.example.com',
        nic_configurations=[
            types.NicConfiguration(
                name='eth0',
                on_boot=True,
                boot_protocol=types.BootProtocol.STATIC,
                ip=types.Ip(
                    version=types.IpVersion.V4,
                    address='10.10.10.1',
                    netmask='255.255.255.0',
                    gateway='10.10.10.1'
                )
            )
        )
    )
)

# Close the connection to the server:
connection.close()

3.21. システムイベントの確認

Red Hat Virtualization Manager は、多数のシステムイベントの記録およびログを記録します。これらのイベントログは、ユーザーインターフェース、システムログファイル、および API を使用してアクセスできます。ovirtsdk ライブラリーは、イベントコレクションを使用して イベント を公開します。

例3.19 システムイベントの確認

この例では、イベント コレクションが一覧表示されます。

list メソッドの query パラメーターは、使用できるすべてのページが返されることを確認します。デフォルトでは、list メソッドは結果の最初のページのみを返します。これは、長さの 100 レコードです。

返される一覧は逆の時系列でソートされ、イベントが発生した順序で表示します。

V4

import ovirtsdk4 as sdk
import ovirtsdk4.types as types

connection = sdk.Connection(
    url='https://engine.example.com/ovirt-engine/api',
    username='admin@internal',
    password='password',
    ca_file='ca.pem',
)

# Find the service that manages the collection of events:
events_service = connection.system_service().events_service()

page_number = 1
events = events_service.list(search='page %s' % page_number)
while events:
    for event in events:
        print(
            "%s %s CODE %s - %s" % (
                event.time,
                event.severity,
                event.code,
                event.description,
            )
        )
    page_number = page_number + 1
    events = events_service.list(search='page %s' % page_number)

# Close the connection to the server:
connection.close()

これらのサンプルは、以下の形式で出力イベントです。

YYYY-MM-DD_T_HH:MM:SS NORMAL CODE 30 - User admin@internal logged in.
YYYY-MM-DD_T_HH:MM:SS NORMAL CODE 153 - VM vm1 was started by admin@internal (Host: MyHost).
YYYY-MM-DD_T_HH:MM:SS NORMAL CODE 30 - User admin@internal logged in.