管理定义的实体

要创建可为租户提供额外 VMware Cloud Director 功能的扩展，服务提供商可以使用 VMware Cloud Director API。

定义的实体表示 VMware Cloud Director 可以管理的外部资源。扩展和 UI 插件开发人员可以创建运行时定义的实体，从而使扩展和 UI 插件能够在 VMware Cloud Director 中存储和操作扩展特定的信息。如果创建的扩展需要存储状态或对外部资源的引用，则该扩展可以使用运行时定义的实体，而不是本地数据库。例如，Kubernetes 扩展可以将有关其管理的 Kubernetes 集群的信息存储在运行时定义的实体中。然后，该扩展可以提供扩展 API，从而使用运行时定义的实体中的信息管理这些集群。

只能通过 VMware Cloud Director API 访问运行时定义的实体。具有管理员特权的用户可以通过验证扩展所创建定义实体的状态来跟踪和观察扩展的运行方式。定义的实体的状态还有助于对扩展问题进行故障排除。

定义的实体类型

在运行时定义可使用定义的实体存储的信息的结构定义。结构定义通过 JSON 文档在实体类型中进行定义。在创建定义的实体类型时，将创建一个新的自定义 VMware Cloud Director 类型，类似于可以通过扩展和行为进行管理的 VM 和 vApp。例如，如果我们设想实体类型 NativeContainerCluster，则此类型的每个实例都包含有关特定 Kubernetes 集群的信息。要获取有关该集群的信息，Container Service Extension 将通过 VMware Cloud Director API 与 VMware Cloud Director 通信，然后向用户提供必要的信息。

创建定义的实体类型的实例后，将不再能够更改此类型、结构定义和行为。要向实体类型添加新功能，必须创建该类型的新版本。如果定义的实体实例基于实体类型的早期版本，则可以通过将实体的类型属性设置为新类型的 ID，升级定义的实体，以使用类型的更高版本。创建定义的实体时，在 API 调用中，实体属性的内容必须与实体类型中指定的 JSON 架构相匹配。只能将对实体类型的访问权限授予特定的用户和组织。可以为实体类型的不同版本设置不同的访问限制。

实体类型的结构定义可以指定对不同内容字段的访问权限。可以将属性标记为 public、protected 或 private。

表 1. 实体类型属性访问控制
属性状态	访问控制
Public	所有用户都可以查看和修改该字段。
Protected	所有用户都可以查看该字段。只有具有完全控制访问权限的用户才能创建和修改该字段。这些用户必须具有管理员完全控制：类型权限，或同时具有完全控制：类型权限和完全控制 ACL。
Private	只有具有完全控制访问权限的用户才能查看、创建和修改该字段。这些用户必须具有管理员完全控制：类型权限，或同时具有完全控制：类型权限和完全控制 ACL。

例如，实体属性 clusterState 的 JSON 结构定义可能如下所示。

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

接口和行为

定义的实体还具有可用于定义行为的接口。如果使用 Kubernetes 示例，则每个集群实体类型对容器集群接口中定义的行为都采用不同的实现形式。Tanzu Kubernetes 集群类型行为通过与 vSphere 进行通信来执行必要的操作，而本机容器集群类型行为与 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 UI 监控定义的实体的创建、行为调用等。当定义的实体的状态更改为 Resolved 时，UI 中的相应任务将显示为 Succeeded。

在一个租户组织中创建定义的实体时，无法与另一个组织中的租户共享该定义的实体。如果在 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"]
      }
   }
}

访问定义的实体实例

两种相互补充的机制控制对运行时定义的实体的访问。

权限 - 创建运行时定义的实体类型时，会为该类型创建一个权限包。要提供对特定操作的访问权限，您必须将此包中的权限分配给其他角色。每个包都有五个特定于类型的权限：查看：类型、编辑：类型、完全控制：类型、管理员查看：类型以及管理员完全控制：类型。

查看：类型、编辑：类型和完全控制：类型权限仅与 ACL 条目结合使用。
访问控制列表 (ACL) - ACL 表包含的条目定义用户对系统中的特定实体具有的访问权限。ACL 表对这些实体提供额外的一层控制。例如，编辑：类型权限指定用户可以修改其有权访问的实体时，ACL 表定义用户有权访问哪些实体。

具有查看常规 ACL 权限的系统管理员可以使用 accessControls API 查看分配给特定定义实体的 ACL。有关 VMware Cloud Director API 参考材料，请参见 code.vmware.com。

具有管理常规 ACL 权限的系统管理员可以使用 accessControls API 创建、修改和移除特定 ACL。

表 2. RDE 操作的权限和 ACL 条目
实体操作	选项	描述
读取	管理员查看：类型权限	具有此权限的用户可以查看组织中此类型的所有运行时定义的实体。
读取	查看：类型权限 + ACL 条目 >= 查看	具有此权限和读取级别 ACL 的用户可以查看此类型的运行时定义的实体。
修改	管理员完全控制：类型权限	具有此权限的用户可以创建、查看、修改和删除所有组织中此类型的运行时定义的实体。
修改	编辑：类型权限 + ACL 条目 >= 更改	具有此权限和修改级别 ACL 的用户可以创建、查看和修改此类型的运行时定义的实体。
删除	管理员完全控制：类型权限	具有此权限的用户可以创建、查看、修改和删除所有组织中此类型的运行时定义的实体。
删除	完全控制：类型权限 + ACL 条目 = 完全控制	具有此权限和完全控制级别 ACL 的用户可以创建、查看、修改和删除此类型的运行时定义的实体。

您可以使用 VMware Cloud Director API 或 UI 将权限包发布到您希望管理此类型实体的任何组织。发布权限包后，您可以将包中的权限分配给组织中的角色。

您可以使用 VMware Cloud Director API 编辑 ACL 表。

访问定义的实体接口和类型操作

定义的实体接口和类型操作需要某些服务提供商可能没有的特定权限。执行操作之前，请确认您具有必要的权限。

表 3. 定义的实体接口和类型操作所需的权限
操作	要求
查看和查询界面	所有用户都具有必要的权限。
创建接口	您必须具有创建新的自定义实体定义权限。
编辑接口	您必须具有编辑自定义实体定义权限。
删除接口	您必须具有删除自定义实体定义权限。
创建类型	您必须具有创建新的自定义实体定义权限。
查看类型	最低要求为 `ReadOnly` 类型 ACL。
编辑和删除类型	您必须具有编辑/删除自定义实体定义权限和 `FullControl` 类型 ACL。

使用运行时定义的实体

要在定义的实体上调用行为，该实体必须处于 Resolved 状态。要删除定义的实体，该实体必须处于 Resolved 或 Resolution_Error 状态。

仅当实体类型和接口没有实例时，才能对其进行修改。只能通过更改引用的实体类型版本来修改该实体类型。

要诊断定义的实体的访问问题，可以使用实体 ACL 查询 API 并验证必要的权限。此外，必须将实体类型的权限包发布到要使用实体类型的租户。