Gestion des entités définies dans VMware Cloud Director

Pour créer des extensions qui fournissent des fonctionnalités VMware Cloud Director supplémentaires aux locataires, les fournisseurs de services peuvent utiliser VMware Cloud Director API.

Les entités définies représentent des ressources externes que VMware Cloud Director peut gérer. Les développeurs d'extensions et de plug-ins d'interface utilisateur peuvent créer des entités définies lors de l'exécution, ce qui permet aux extensions et aux plug-ins d'interface utilisateur de stocker et de manipuler les informations spécifiques de l'extension dans VMware Cloud Director. Si vous créez une extension et qu'elle doit stocker un état ou des références à des ressources externes, elle peut utiliser des entités définies lors de l'exécution au lieu d'une base de données locale. Par exemple, une extension Kubernetes peut stocker des informations sur les clusters Kubernetes qu'elle gère dans des entités définies au moment de l'exécution. L'extension peut ensuite fournir des API d'extension afin de gérer ces clusters à l'aide des informations provenant des entités définies lors de l'exécution.

Vous pouvez accéder aux entités définies lors de l'exécution uniquement via VMware Cloud Director API. Les utilisateurs disposant de privilèges d'administrateur peuvent suivre et observer le fonctionnement des extensions en vérifiant l'état des entités définies créées par les extensions. Les états des entités définies peuvent également vous aider à résoudre les problèmes liés aux extensions.

Type d'entité défini

Vous définissez lors de l'exécution le schéma des informations que vous pouvez stocker à l'aide d'entités définies. Le schéma est défini dans le type d'entité via un document JSON. Lorsque vous créez un type d'entité défini, vous créez un type VMware Cloud Director personnalisé semblable aux machines virtuelles et aux vApp que vous pouvez gérer par extensions et comportements. Par exemple, si nous prenons en compte le type d'entité NativeContainerCluster, chaque instance de ce type contient des informations sur un cluster Kubernetes spécifique. Pour obtenir les informations sur le cluster, VMware Cloud Director Container Service Extension communique avec VMware Cloud Director via VMware Cloud Director API et fournit les informations nécessaires aux utilisateurs.

Une fois que vous avez créé une instance d'un type d'entité défini, vous ne pouvez plus modifier le type, le schéma et les comportements. Pour ajouter de nouvelles fonctionnalités au type d'entité, vous devez créer une nouvelle version du type. Lorsqu'une instance d'entité définie est basée sur une version antérieure du type d'entité, vous pouvez mettre à niveau l'entité définie pour utiliser une version ultérieure du type en définissant la propriété de type de l'entité sur l'ID du nouveau type. Lorsque vous créez une entité définie dans l'appel d'API, le contenu de la propriété d'entité doit correspondre au schéma JSON spécifié dans le type d'entité. Vous pouvez accorder l'accès à un type d'entité uniquement à des utilisateurs et à des organisations spécifiques. Vous pouvez définir différentes restrictions d'accès aux différentes versions d'un type d'entité.

Le schéma du type d'entité peut spécifier l'accès aux différents champs de contenu. Vous pouvez marquer les propriétés en tant que public, protected ou private.

Tableau 1. Contrôle d'accès à la propriété du type d'entité
État de la propriété	Contrôle d'accès
Public	Tous les utilisateurs peuvent afficher et modifier le champ.
Protected	Tous les utilisateurs peuvent afficher le champ. Seuls les utilisateurs disposant d'un accès Contrôle total peuvent créer et modifier le champ. Les utilisateurs doivent disposer du droit Contrôle total d'administrateur : TYPE ou du droit Contrôle total : TYPE et d'une liste ACL de contrôle total.
Private	Seuls les utilisateurs disposant d'un accès Contrôle total peuvent afficher, créer et modifier le champ. Les utilisateurs doivent disposer du droit Contrôle total d'administrateur : TYPE ou du droit Contrôle total : TYPE et d'une liste ACL de contrôle total.

Par exemple, le schéma JSON de la propriété d'entité clusterState peut être le suivant.

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

Interfaces et comportements

Les entités définies disposent également d'interfaces que vous pouvez utiliser pour définir des comportements. Si vous utilisez l'exemple Kubernetes, chaque type d'entité de cluster a une implémentation différente des comportements définis dans l'interface du cluster de conteneur. Les comportements de type du cluster Tanzu Kubernetes communiquent avec vSphere pour effectuer les actions nécessaires et les comportements de type de cluster de conteneur natif communiquent avec VMware Cloud Director Container Service Extension.

Tous les utilisateurs peuvent voir les interfaces des entités définies.

Il y a différentes manières de définir les comportements.

Vous pouvez créer et publier un workflow VMware Aria Automation Orchestrator et créer un comportement qui appelle le workflow.
Vous pouvez lier n'importe quelle fonctionnalité à un comportement à l'aide d'un WebHook.
Avec les comportements MQTT, vous pouvez appeler une fonctionnalité dans une extension. En utilisant MQTT, vous pouvez communiquer directement avec l'extension et celle-ci peut fournir un état plus détaillé.

Le diagramme indique que chaque type d'entité a une implémentation différente des comportements définis dans l'interface d'entité définie lors de l'exécution. — Figure 1. Interfaces d'entités définies au moment de l'exécution

Les interfaces, les types et les comportements des entités définies lors de l'exécution ont des ID d'API spécifiques.

Les ID d'API d'interface se présentent sous la forme suivante : urn:vcloud:interface:vendor_name:interface_name:version.
Les ID d'API de type se présentent sous la forme suivante : urn:vcloud:type:vendor_name:type_name:version.
Les ID d'API de comportement se présentent sous la forme urn:vcloud:behavior-interface:behavior_name:vendor_name:interface_name:version ou urn:vcloud:behavior-type:behavior_name:vendor_name:interface_name:version.

Création d'une entité définie lors de l'exécution

Pour créer une entité définie, commencez par configurer les ressources externes et ajoutez les informations nécessaires à l'entité définie. Ce processus peut nécessiter quelques itérations. Pour résoudre l'entité définie, vous devez vérifier que le contenu du schéma dispose de toutes les informations nécessaires. Si le contenu ne correspond pas au schéma JSON spécifié dans le type, l'état de l'entité définie devient Resolution_Error. Si vous renseignez correctement les informations, l'état de l'entité définie devient Resolved et est prêt à être utilisé.

Comme les tâches effectuent le suivi de toutes les opérations d'entités à long terme définies lors de l'exécution, vous pouvez utiliser l'interface utilisateur de VMware Cloud Director pour surveiller la création d'entités définies, l'appel de comportement, etc. Lorsque l'état d'une entité définie devient Resolved, la tâche correspondante dans l'interface utilisateur s'affiche en tant que Succeeded.

Lorsque vous créez une entité définie dans une organisation de locataires, vous ne pouvez pas partager l'entité définie avec des locataires d'une autre organisation. Si vous créez une entité définie dans l'organisation System, vous pouvez la partager avec des utilisateurs de locataires ou des organisations de locataires.

Exemple d'appel d'API pour créer une entité définie

L'exemple fournit un exemple d'appel d'API pour créer une entité de type 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"]
      }
   }
}

Accès aux instances d'entités définies

Deux mécanismes complémentaires contrôlent l'accès aux entités d'exécution définies.

Droits : lorsque vous créez un type d'entité définie lors de l'exécution, vous créez un bundle de droits pour ce type. Pour fournir un accès à des opérations spécifiques, vous devez attribuer les droits de ce bundle à d'autres rôles. Chaque bundle possède les cinq droits spécifiques au type suivants : Afficher : TYPE, Modifier : TYPE, Contrôle total : TYPE, Vue administrateur : TYPE et Contrôle total de l'administrateur : TYPE.

Les droits Afficher : TYPE, Modifier : TYPE et Contrôle total : TYPE fonctionnent uniquement en combinaison avec une entrée de liste ACL.
Liste de contrôle d'accès (ACL) : la table ACL contient des entrées définissant l'accès des utilisateurs à des entités spécifiques dans le système. Elle fournit un niveau de contrôle supplémentaire sur les entités. Par exemple, lorsqu'un droit Modifier : TYPE spécifie qu'un utilisateur peut modifier des entités auxquelles il a accès, la table ACL définit les entités auxquelles l'utilisateur a accès.

Les administrateurs système disposant du droit Afficher la liste ACL générale peuvent afficher les listes ACL attribuées à une entité définie spécifique à l'aide de l'API accessControls. Reportez-vous à la section VMware Cloud Director OpenAPI.

Les administrateurs système disposant du droit Gérer la liste ACL générale peuvent créer, modifier et supprimer des listes ACL spécifiques à l'aide de l'API accessControls.

Tableau 2. Droits et entrées de liste ACL pour les opérations de RDE
Opération d'entité	Option	Description
Lire	Droit Vue administrateur : TYPE	Les utilisateurs disposant de ce droit peuvent voir toutes les entités définies lors de l'exécution de ce type dans une organisation.
Lire	Droit Afficher : TYPE et entrée de liste ACL >= Afficher	Les utilisateurs disposant de ce droit et d'une liste ACL de niveau lecture peuvent afficher les entités définies lors de l'exécution de ce type.
Modifier	Droit Contrôle total de l'administrateur : TYPE	Les utilisateurs disposant de ce droit peuvent créer, afficher, modifier et supprimer des entités définies lors de l'exécution de ce type dans toutes les organisations.
Modifier	Droit Modifier : TYPE et entrée de liste ACL >= Modifier	Les utilisateurs disposant de ce droit et d'une liste ACL de niveau modification peuvent créer, afficher et modifier les entités définies lors de l'exécution de ce type.
Supprimer	Droit Contrôle total de l'administrateur : TYPE	Les utilisateurs disposant de ce droit peuvent créer, afficher, modifier et supprimer des entités définies lors de l'exécution de ce type dans toutes les organisations.
Supprimer	Droit Contrôle total : TYPE et entrée de liste ACL = Contrôle total	Les utilisateurs disposant de ce droit et d'une liste ACL de niveau contrôle total peuvent créer, afficher, modifier et supprimer les entités définies lors de l'exécution de ce type.

Vous pouvez utiliser l'API ou l'interface utilisateur de VMware Cloud Director afin de publier le bundle de droits pour n'importe quelle organisation devant gérer les entités de ce type. Après la publication du bundle de droits, vous pouvez attribuer les droits du bundle à des rôles au sein de l'organisation.

Vous pouvez utiliser l'API VMware Cloud Director pour modifier la table ACL.

Accès à l'interface d'entité définie et aux opérations de type

Les opérations d'interface et de type d'entité définies nécessitent des droits spécifiques dont certains fournisseurs de services peuvent ne pas disposer. Avant d'effectuer une opération, vérifiez que vous disposez des droits nécessaires.

Tableau 3. Droits pour l'interface d'entité définie et les opérations de type
Opération	Exigence
Afficher et interroger l'interface	Tous les utilisateurs disposent des droits nécessaires.
Créer une interface	Vous devez disposer du droit Créer une définition d'entité personnalisée.
Modifier l'interface	Vous devez disposer du droit Modifier la définition d'entité personnalisée.
Supprimer l'interface	Vous devez disposer du droit Supprimer la définition d'entité personnalisée.
Créer un type	Vous devez disposer du droit Créer une définition d'entité personnalisée.
Type d'affichage	La configuration minimale requise est une liste ACL de type `ReadOnly`.
Modifier et supprimer le type	Vous devez disposer du droit Modifier/supprimer la définition de l'entité personnalisée et d'une liste ACL de type `FullControl`.

Utilisation d'entités définies lors de l'exécution

Pour appeler des comportements sur une entité définie, celle-ci doit être dans l'état Resolved. Pour supprimer une entité définie, celle-ci doit être dans l'état Resolved ou Resolution_Error.

Vous pouvez modifier les types d'entités et les interfaces uniquement s'ils n'ont pas d'instances. Vous pouvez uniquement modifier le type d'entité référencé en changeant sa version.

Pour diagnostiquer les problèmes d'accès aux entités définies, vous pouvez utiliser les API de requête de la liste ACL d'entité et vérifier les droits nécessaires. En outre, le bundle de droits d'un type d'entité doit être publié sur les locataires sur lesquels vous souhaitez l'utiliser.