定義済みエンティティの管理

テナントに追加の VMware Cloud Director 機能を提供する拡張機能を作成するために、サービスプロバイダは VMware Cloud Director API を使用できます。

定義済みエンティティは、VMware Cloud Director が管理できる外部リソースを表します。拡張機能とユーザーインターフェイスプラグインの開発者は、ランタイム定義エンティティを作成し、拡張機能とユーザーインターフェイスプラグインを有効にして、拡張機能固有の情報を VMware Cloud Director に保存および操作できます。拡張機能を作成して、状態または外部リソースへの参照を保存する必要がある場合、その拡張機能ではローカルデータベースの代わりにランタイム定義エンティティを使用できます。たとえば、Kubernetes 拡張機能は、管理している Kubernetes クラスタに関する情報をランタイム定義エンティティに保存できます。この拡張機能は、ランタイム定義エンティティの情報を使用して、これらのクラスタを管理するための拡張 API を提供できます。

ランタイム定義エンティティにアクセスするには、VMware Cloud Director API を使用する必要があります。管理者権限を持つユーザーは、拡張機能によって作成された定義済みエンティティの状態を確認することで、拡張機能の動作を追跡および監視できます。定義済みエンティティの状態は、拡張機能の問題をトラブルシューティングする場合にも役立ちます。

定義済みエンティティタイプ

保存できる情報のスキーマは、定義済みエンティティを使用して実行時に定義します。このスキーマは、JSON ドキュメントを使用してエンティティタイプで定義されます。定義済みエンティティタイプの作成時には、仮想マシンや vApp に類似した新しいカスタム VMware Cloud Director タイプを作成して、拡張機能および動作別に管理できます。たとえば、NativeContainerCluster というエンティティタイプについて検討する場合、このタイプの各インスタンスには特定の Kubernetes クラスタに関する情報が含まれます。クラスタに関する情報を取得するために、VMware Cloud Director Container Service Extension は VMware Cloud Director API を使用して VMware Cloud Director と通信し、必要な情報をユーザーに提供します。

定義済みエンティティタイプのインスタンスを作成すると、タイプ、スキーマ、および動作を変更できなくなります。エンティティタイプに新しい機能を追加するには、新しいバージョンのタイプを作成する必要があります。定義済みエンティティインスタンスが以前のバージョンのエンティティタイプに基づいている場合は、エンティティのタイププロパティを新しいタイプの ID に設定することで、新しいバージョンのタイプを使用するように定義済みエンティティをアップグレードできます。定義済みエンティティの作成時には、API 呼び出しで、エンティティプロパティの内容がエンティティタイプで指定された JSON スキーマと一致する必要があります。エンティティタイプへのアクセス権は、特定のユーザーと組織にのみ付与できます。エンティティタイプのバージョンごとに異なるアクセス制限を設定できます。

エンティティタイプのスキーマでは、さまざまなコンテンツフィールドへのアクセス権を指定できます。プロパティは public、protected、または private としてマークできます。

表 1. エンティティタイプのプロパティのアクセスコントロール
プロパティのステータス	アクセスコントロール
Public	すべてのユーザーがフィールドを表示および変更できます。
Protected	すべてのユーザーがフィールドを表示できます。フィールドを作成および変更できるのは、完全コントロールアクセス権を持つユーザーのみです。ユーザーには、管理者の完全コントロール：TYPE 権限、または完全コントロール：TYPE 権限と完全コントロール ACL の両方が必要です。
Private	フィールドを表示、作成、および変更できるのは、完全コントロールアクセス権を持つユーザーのみです。ユーザーには、管理者の完全コントロール：TYPE 権限、または完全コントロール：TYPE 権限と完全コントロール ACL の両方が必要です。

たとえば、エンティティプロパティ clusterState の JSON スキーマは次のようになります。

"clusterState" : {
  "type" : "string",
  "x-vcloud-restricted" : "protected"
}

インターフェイスと動作

定義済みエンティティには、動作の定義に使用できるインターフェイスもあります。Kubernetes の例を使用する場合、各クラスタエンティティタイプには、コンテナクラスタインターフェイスで定義された動作の異なる実装があります。Tanzu Kubernetes クラスタタイプの動作では vSphere と通信して必要なアクションを実行し、ネイティブのコンテナクラスタタイプの動作では VMware Cloud Director Container Service Extension と通信します。

すべてのユーザーは、定義済みエンティティのインターフェイスを表示できます。

動作を定義する方法は複数あります。

vRealize Operations ワークフローを作成および公開し、ワークフローを呼び出す動作を作成できます。
Webhook を使用して、任意の機能を動作にリンクできます。
MQTT の動作では、拡張機能に含まれる機能を呼び出すことができます。MQTT を使用すると、拡張機能と直接通信できます。拡張機能はより詳細なステータスを提供できます。

この図は、各エンティティタイプには、ランタイム定義エンティティのインターフェイスで定義された動作の異なる実装があることを示しています。 — 図 1. ランタイム定義エンティティのインターフェイス

ランタイム定義エンティティのインターフェイス、タイプ、および動作には特定の API ID があります。

インターフェイス API ID の形式：urn:vcloud:interface:vendor_name:interface_name:version
タイプ API ID の形式：urn:vcloud:type:vendor_name:type_name:version
動作 API ID の形式：urn:vcloud:behavior-interface:behavior_name:vendor_name:interface_name:version または urn:vcloud:behavior-type:behavior_name:vendor_name:interface_name:version

ランタイム定義エンティティの作成

定義済みエンティティを作成するには、まず外部リソースを構成し、定義済みエンティティに必要な情報を追加します。このプロセスには、数回の反復が必要な場合があります。定義済みエンティティを解決するには、スキーマの内容に必要な情報がすべて含まれていることを確認する必要があります。内容がタイプで指定された JSON スキーマと一致しない場合は、定義済みエンティティの状態が Resolution_Error に変わります。情報を正しく入力すると、定義済みエンティティの状態が Resolved に変わり、使用可能になります。

実行時間の長いランタイム定義エンティティのすべての操作がタスクによって追跡されるため、VMware Cloud Director ユーザーインターフェイスを使用して、定義済みエンティティの作成や動作の呼び出しなどを監視できます。定義済みエンティティのステータスが Resolved に変わると、ユーザーインターフェイスの対応するタスクが Succeeded と表示されます。

1 つのテナント組織に作成した定義済みエンティティを別の組織内のテナントと共有することはできません。System 組織に作成した定義済みエンティティは、テナントユーザーまたはテナント組織と共有できます。

定義済みエンティティを作成するためのサンプル API 呼び出し

次の例は、pksContainerCluster タイプの新しいエンティティを作成するためのサンプル API 呼び出しを示しています。

POST https://host/cloudapi/1.0.0/entityTypes/urn:vcloud:type:vendorA:pksContainerCluster:1.0.0
{
   "name": "testEntity",
   "entity": {
      "cluster": {
         "name": "testCluster",
         "nodes": ["node1"]
      }
   }
}

定義済みエンティティインスタンスへのアクセス

ランタイム定義エンティティへのアクセスは 2 つの補完的なメカニズムで制御されます。

権限 - ランタイム定義エンティティタイプを作成した場合は、そのタイプの権限バンドルを作成します。特定の操作に対するアクセス権を提供するには、このバンドルから他のロールに権限を割り当てる必要があります。各バンドルには、表示：TYPE、編集：TYPE、完全コントロール：TYPE、管理者の表示：TYPE、管理者の完全コントロール：TYPE という 5 つのタイプ固有の権限があります。

表示：TYPE、編集：TYPE、および完全コントロール：TYPE 権限は、ACL エントリと組み合わせた場合のみ機能します。
アクセスコントロールリスト (ACL) - ACL テーブルには、システム内の特定のエンティティに対してユーザーが保持しているアクセス権を定義するエントリが含まれています。これによりエンティティの制御レベルを強化することができます。たとえば、編集：TYPE 権限は、ユーザーがアクセス権を持つエンティティは、そのユーザーが変更できることを示します。一方、ACL テーブルは、そのユーザーがアクセスできるエンティティを定義します。

全般 ACL の表示権限を持つシステム管理者は、accessControls API を使用して特定の定義済みエンティティに割り当てられた ACL を表示できます。VMware Cloud Director API リファレンスについては、https://developer.vmware.com/を参照してください。

全般 ACL の管理権限を持つシステム管理者は、accessControls API を使用して特定の ACL を作成、変更、および削除することができます。

表 2. RDE 操作に関する権限および ACL エントリ
エンティティの操作	オプション	説明
読み取り	管理者の表示：TYPE 権限	この権限を持つユーザーは、組織内にあるこのタイプのすべてのランタイム定義エンティティを表示できます。
読み取り	表示：TYPE 権限および表示以上の ACL エントリ	この権限および読み取りレベルの ACL を持つユーザーは、このタイプのランタイム定義エンティティを表示できます。
変更	管理者の完全コントロール：TYPE 権限	この権限を持つユーザーは、すべての組織内にあるこのタイプのランタイム定義エンティティを作成、表示、変更、および削除できます。
変更	編集：TYPE 権限および変更以上の ACL エントリ	この権限および変更レベルの ACL を持つユーザーは、このタイプのランタイム定義エンティティを作成、表示、および変更できます。
削除	管理者の完全コントロール：TYPE 権限	この権限を持つユーザーは、すべての組織内にあるこのタイプのランタイム定義エンティティを作成、表示、変更、および削除できます。
削除	完全コントロール：TYPE 権限および完全コントロールの ACL エントリ	この権限および完全コントロールレベルの ACL を持つユーザーは、このタイプのランタイム定義エンティティを作成、表示、変更、および削除できます。

VMware Cloud Director API またはユーザーインターフェイスを使用して、このタイプのエンティティを管理する組織に権限バンドルを公開できます。権限バンドルを公開した後に、バンドルから組織内のロールに権限を割り当てることができます。

VMware Cloud Director API を使用して、ACL テーブルを編集できます。

定義済みエンティティのインターフェイスとタイプの操作へのアクセス

定義済みエンティティのインターフェイスとタイプの操作には、特定のサービスプロバイダには付与されていない可能性のある特定の権限が必要です。操作を実行する前に、必要な権限が付与されていることを確認します。

表 3. 定義済みエンティティのインターフェイスとタイプの操作に必要な権限
操作	要件
インターフェイスの表示とクエリ	すべてのユーザーに必要な権限が付与されている。
インターフェイスの作成	カスタムエンティティ定義の新規作成権限が必要。
インターフェイスの編集	カスタムエンティティ定義の編集権限が必要。
インターフェイスの削除	カスタムエンティティ定義の削除権限が必要。
タイプの作成	カスタムエンティティ定義の新規作成権限が必要。
タイプの表示	最小要件は `ReadOnly` タイプ ACL。
タイプの編集と削除	カスタムエンティティ定義の編集/削除権限と `FullControl` タイプ ACL が必要。

ランタイム定義エンティティの操作

定義済みエンティティで動作を呼び出すには、エンティティの状態が Resolved である必要があります。定義済みエンティティを削除するには、エンティティの状態が Resolved または Resolution_Error である必要があります。

エンティティタイプとインターフェイスは、インスタンスがない場合にのみ変更できます。参照先のエンティティタイプを変更するには、そのバージョンを変更する必要があります。

定義済みエンティティへのアクセスに関する問題を診断するには、エンティティ ACL クエリ API を使用して、必要な権限を確認します。また、エンティティタイプの権限バンドルは、それを使用するテナントに公開する必要があります。

定義済みエンティティ タイプ