Verwalten definierter Entitäten

Um Erweiterungen zu erstellen, die den Mandanten zusätzliche VMware Cloud Director-Funktionen bereitstellen, können Dienstanbieter die VMware Cloud Director-API verwenden.

Definierte Entitäten stellen externe Ressourcen dar, die von VMware Cloud Director verwaltet werden können. Erweiterungs- und UI-Plug-In-Entwickler können laufzeitdefinierte Entitäten (Runtime Defined Entities, RDEs) erstellen, sodass Erweiterungen und UI-Plug-Ins die erweiterungsspezifischen Informationen in VMware Cloud Director speichern und bearbeiten können. Wenn Sie eine Erweiterung erstellen und diese einen Status oder Verweise auf externe Ressourcen speichern muss, kann die Erweiterung laufzeitdefinierte Entitäten anstelle einer lokalen Datenbank verwenden. Beispielsweise kann eine Kubernetes-Erweiterung Informationen zu den Kubernetes-Clustern speichern, die sie in laufzeitdefinierten Entitäten verwaltet. Die Erweiterung kann anschließend Erweiterungs-APIs für die Verwaltung dieser Cluster unter Verwendung der Informationen aus den laufzeitdefinierten Entitäten bereitstellen.

Sie können auf laufzeitdefinierte Entitäten nur über die VMware Cloud Director-API zugreifen. Benutzer mit Administratorrechten können die Funktionsweise von Erweiterungen nachverfolgen und beobachten, indem sie den Status der von den Erweiterungen erstellten definierten Entitäten überprüfen. Die Zustände der definierten Entitäten können Ihnen auch bei der Behebung von Problemen mit den Erweiterungen helfen.

Definierter Entitätstyp

Sie definieren zur Laufzeit das Schema der Informationen, die Sie mithilfe definierter Entitäten speichern können. Das Schema wird im Entitätstyp über ein JSON-Dokument definiert. Wenn Sie einen definierten Entitätstyp erstellen, erstellen Sie einen neuen benutzerdefinierten VMware Cloud Director-Typ ähnlich VMs und vApps, den Sie nach Erweiterungen und Verhaltensweisen verwalten können. Wenn Sie beispielsweise den Entitätstyp NativeContainerCluster betrachten, enthält jede Instanz dieses Typs Informationen zu einem bestimmten Kubernetes-Cluster. Um die Informationen über den Cluster zu erhalten, kommuniziert VMware Cloud Director Container Service Extension mit VMware Cloud Director über die VMware Cloud Director-API und stellt den Benutzern die erforderlichen Informationen zur Verfügung.

Sobald Sie eine Instanz eines definierten Entitätstyps erstellt haben, können Sie den Typ, das Schema und die Verhaltensweisen nicht mehr ändern. Um dem Entitätstyp neue Funktionen hinzuzufügen, müssen Sie eine neue Version des Typs erstellen. Wenn eine Instanz einer definierten Entität auf einer früheren Version des Entitätstyps basiert, können Sie die definierte Entität aktualisieren, damit sie eine höhere Version des Typs verwendet. Legen Sie dazu die Eigenschaft „Typ“ der Entität auf die ID des neuen Typs fest. Wenn Sie eine definierte Entität erstellen, muss der Inhalt der Entitätseigenschaft im API-Aufruf mit dem im Entitätstyp angegebenen JSON-Schema übereinstimmen. Sie haben die Möglichkeit, nur bestimmten Benutzern und Organisationen Zugriff auf einen Entitätstyp zu gewähren. Sie können verschiedene Zugriffsbeschränkungen für die verschiedenen Versionen eines Entitätstyps festlegen.

Das Schema des Entitätstyps kann den Zugriff auf die verschiedenen Inhaltsfelder angeben. Sie können Eigenschaften als public, protected oder private markieren.

Tabelle 1. Zugriffssteuerung für die Eigenschaft „Entitätstyp“
Eigenschaftsstatus	Zugriffssteuerung
Public	Alle Benutzer können das Feld anzeigen und ändern.
Protected	Alle Benutzer können das Feld anzeigen. Nur Benutzer mit der Zugriffsberechtigung „Vollständige Kontrolle“ können das Feld erstellen und ändern. Die Benutzer müssen über das Administratorrecht „Vollständige Kontrolle: TYPE“ oder sowohl über das Recht „Vollständige Kontrolle: TYPE“ als auch über eine Zugriffskontrollliste (ACL) mit vollständiger Kontrolle verfügen.
Private	Nur Benutzer mit der Zugriffsberechtigung „Vollständige Kontrolle“ können das Feld anzeigen, erstellen und ändern. Die Benutzer müssen über das Administratorrecht „Vollständige Kontrolle: TYPE“ oder sowohl über das Recht „Vollständige Kontrolle: TYPE“ als auch über eine Zugriffskontrollliste (ACL) mit vollständiger Kontrolle verfügen.

Das JSON-Schema für die Entitätseigenschaft clusterState kann beispielsweise wie folgt lauten.

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

Schnittstellen und Verhaltensweisen

Definierte Entitäten verfügen auch über Schnittstellen, mit denen Sie Verhaltensweisen definieren können. Bei unserem Kubernetes-Beispiel weist jeder Cluster-Entitätstyp eine andere Implementierung der in der Container-Cluster-Schnittstelle definierten Verhaltensweisen auf. Die Verhaltensweisen des Clustertyps Tanzu Kubernetes kommunizieren mit vSphere, um die erforderlichen Aktionen auszuführen, und die Verhaltensweisen des nativen Container-Cluster-Typs kommunizieren mit VMware Cloud Director Container Service Extension.

Alle Benutzer können die Schnittstellen von definierten Entitäten sehen.

Es gibt verschiedene Möglichkeiten zum Definieren von Verhaltensweisen.

Sie können einen vRealize Operations-Workflow erstellen und veröffentlichen und eine Verhaltensweise erstellen, das den Workflow aufruft.
Sie können eine beliebige Funktionalität mit einer Verhaltensweise verknüpfen, indem Sie einen WebHook verwenden.
Mit MQTT-Verhaltensweisen können Sie eine Funktionalität in einer Erweiterung aufrufen. Mithilfe von MQTT können Sie direkt mit der Erweiterung kommunizieren und die Erweiterung kann einen detaillierteren Status bereitstellen.

Das Diagramm zeigt, dass jeder Entitätstyp eine andere Implementierung der Verhaltensweisen aufweist, die in der Schnittstelle für laufzeitdefinierte Entitäten definiert sind. — Abbildung 1. Schnittstellen für laufzeitdefinierte Entitäten

Schnittstellen, Typen und Verhaltensweisen von laufzeitdefinierten Entitäten haben spezifische API-IDs.

Schnittstellen-API-IDs haben das Format urn:vcloud:interface:vendor_name:interface_name:version.
Typ-API-IDs haben das Format urn:vcloud:type:vendor_name:type_name:version.
Verhaltensweisen-API-IDs haben das Format urn:vcloud:behavior-interface:behavior_name:vendor_name:interface_name:version oder urn:vcloud:behavior-type:behavior_name:vendor_name:interface_name:version.

Erstellen einer laufzeitdefinierten Entität

Um eine definierte Entität zu erstellen, konfigurieren Sie zunächst die externen Ressourcen und fügen Sie der definierten Entität die erforderlichen Informationen hinzu. Dieser Vorgang erfordert möglicherweise einige Iterationen. Um die definierte Entität aufzulösen, müssen Sie sicherstellen, dass der Inhalt des Schemas alle erforderlichen Informationen enthält. Wenn der Inhalt nicht mit dem im Typ angegebenen JSON-Schema übereinstimmt, ändert sich der Status der definierten Entität in Resolution_Error. Wenn Sie die Informationen korrekt eingeben, ändert sich der Status der definierten Entität in Resolved und kann verwendet werden.

Da Aufgaben alle Vorgänge der laufzeitdefinierten Entität mit langer Ausführungszeit nachverfolgen, können Sie die VMware Cloud Director-Benutzeroberfläche zum Überwachen der Erstellung definierter Entitäten, Aufrufen von Verhaltensweisen usw. verwenden. Wenn sich der Status einer definierten Entität in Resolved ändert, wird die entsprechende Aufgabe in der Benutzeroberfläche als Succeeded angezeigt.

Wenn Sie eine definierte Entität in einer Mandantenorganisation erstellen, können Sie die definierte Entität nicht für Mandanten in einer anderen Organisation freigeben. Wenn Sie eine definierte Entität in der Organisation System erstellen, können Sie sie für Mandantenbenutzer oder Mandantenorganisationen freigeben.

Beispiel-API-Aufruf zum Erstellen einer definierten Entität

Das Beispiel enthält einen Beispiel-API-Aufruf zum Erstellen einer neuen Entität des Typs pksContainerCluster.

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

Zugriff auf Instanzen definierter Entitäten

Zwei sich ergänzende Mechanismen steuern den Zugriff auf laufzeitdefinierte Entitäten.

Rechte: Wenn Sie einen laufzeitdefinierten Entitätstyp erstellen, erstellen Sie ein Rechtepaket für den Typ. Um Zugriff auf bestimmte Vorgänge zu ermöglichen, müssen Sie die Rechte aus diesem Paket anderen Rollen zuweisen. Jedes Paket verfügt über fünf typspezifische Rechte: Ansicht: TYPE, Bearbeiten: TYPE, Vollständige Kontrolle: TYPE, Administratoransicht: TYPE und Vollständige Kontrolle des Administrators: TYPE.

Die Rechte Ansicht: TYPE, Bearbeiten: TYPE und Vollständige Kontrolle: TYPE funktionieren nur in Kombination mit einem ACL-Eintrag.
Zugriffssteuerungsliste (ACL): Die ACL-Tabelle enthält Einträge, die den Zugriff der Benutzer auf bestimmte Entitäten im System definieren. Sie bietet eine zusätzliche Kontrollebene für die Entitäten. Beispiel: Das Recht Bearbeiten: TYPE gibt an, dass ein Benutzer Entitäten ändern kann, auf die er Zugriff hat, und die ACL-Tabelle legt fest, auf welche Entitäten der Benutzer Zugriff hat.

Systemadministratoren mit dem Recht Allgemeine ACL anzeigen können mithilfe der accessControls-API die ACLs anzeigen, die einer bestimmten definierten Entität zugewiesen wurden. Die VMware Cloud Director-API-Referenz finden Sie unter https://developer.vmware.com/.

Systemadministratoren mit dem Recht Allgemeine ACL verwalten können bestimmte ACLs mithilfe der accessControls-API erstellen, ändern und entfernen.

Tabelle 2. Rechte und ACL-Einträge für RDE-Vorgänge
Vorgang für Entität	Option	Beschreibung
Lesen	Recht Administratoransicht: TYPE	Benutzer mit diesem Recht können alle laufzeitdefinierten Entitäten dieses Typs innerhalb einer Organisation sehen.
Lesen	Recht Ansicht: TYPE und ACL-Eintrag >= Ansicht	Benutzer mit diesem Recht und einer ACL auf Leseebene können laufzeitdefinierte Entitäten dieses Typs anzeigen.
Ändern	Recht Vollständige Kontrolle des Administrators: TYPE	Benutzer mit diesem Recht können laufzeitdefinierte Entitäten dieses Typs in allen Organisationen erstellen, anzeigen, ändern und löschen.
Ändern	Recht Bearbeiten: TYPE und ACL-Eintrag >= Ändern	Benutzer mit diesem Recht und einer ACL auf Änderungsebene können laufzeitdefinierte Entitäten dieses Typs erstellen, anzeigen und ändern.
Löschen	Recht Vollständige Kontrolle des Administrators: TYPE	Benutzer mit diesem Recht können laufzeitdefinierte Entitäten dieses Typs in allen Organisationen erstellen, anzeigen, ändern und löschen.
Löschen	Recht Vollständige Kontrolle: TYPE und ACL-Eintrag = Vollständige Kontrolle	Benutzer mit diesem Recht und einer ACL mit vollständiger Kontrolle können laufzeitdefinierte Entitäten dieses Typs erstellen, anzeigen, ändern und löschen.

Sie können die VMware Cloud Director-API oder -Benutzeroberfläche verwenden, um das Rechtepaket in allen Organisationen zu veröffentlichen, die die Entitäten dieses Typs verwalten sollen. Nachdem Sie das Rechtepaket veröffentlicht haben, besteht die Möglichkeit, den Rollen innerhalb der Organisation Rechte aus dem Paket zuzuweisen.

Mit der VMware Cloud Director-API können Sie die ACL-Tabelle bearbeiten.

Zugriff auf Schnittstellen- und Typvorgänge für definierte Entitäten

Schnittstellen- und Typvorgänge für definierte Entitäten erfordern spezifische Rechte, über die bestimmte Dienstanbieter möglicherweise nicht verfügen. Stellen Sie vor dem Ausführen eines Vorgangs sicher, dass Sie über die erforderlichen Rechte verfügen.

Tabelle 3. Rechte für Schnittstellen- und Typvorgänge für definierte Entitäten
Vorgang	Anforderung
Schnittstelle anzeigen und abfragen	Alle Benutzer verfügen über die erforderlichen Rechte.
Schnittstelle erstellen	Sie benötigen das Recht Neue benutzerdefinierte Entitätsdefinition erstellen.
Schnittstelle bearbeiten	Sie benötigen das Recht Benutzerdefinierte Entitätsdefinition bearbeiten.
Schnittstelle löschen	Sie benötigen das Recht Benutzerdefinierte Entitätsdefinition löschen.
Typ erstellen	Sie benötigen das Recht Neue benutzerdefinierte Entitätsdefinition erstellen.
Typ anzeigen	Die Mindestanforderung ist eine ACL vom Typ `ReadOnly`.
Typ bearbeiten und löschen	Sie benötigen das Recht Benutzerdefinierte Entitätsdefinition bearbeiten/löschen und eine ACL vom Typ `FullControl`.

Arbeiten mit laufzeitdefinierten Entitäten

Um Verhaltensweisen für eine definierte Entität aufzurufen, muss sie den Zustand Resolved aufweisen. Um eine definierte Entität zu löschen, muss sie den Zustand Resolved oder Resolution_Error aufweisen.

Sie können Entitätstypen und Schnittstellen nur dann ändern, wenn sie keine Instanzen aufweisen. Sie können den referenzierten Entitätstyp nur ändern, indem Sie seine Version ändern.

Um Probleme mit dem Zugriff auf definierte Entitäten zu diagnostizieren, können Sie die ACL-Abfrage-APIs der Entität verwenden und die erforderlichen Rechte überprüfen. Darüber hinaus muss das Rechtepaket eines Entitätstyps für die Mandanten veröffentlicht werden, die es verwenden sollen.