To create extensions that provide additional VMware Cloud Director capabilities to the tenants, service providers can use the VMware Cloud Director API.

Defined entities represent external resources that VMware Cloud Director can manage. Extension and UI plug-in developers can create runtime defined entities, enabling extensions and UI plug-ins to store and manipulate the extension-specific information in VMware Cloud Director. If you create an extension and it needs to store a state or references to external resources, the extension can use runtime defined entities instead of a local database. For example, a Kubernetes extension can store information about the Kubernetes clusters it manages in runtime defined entities. The extension can then provide extension APIs for managing those clusters using the information from the runtime defined entities.

You can access runtime defined entities only through the VMware Cloud Director API. Users with admin privileges can track and observe the way extensions operate by verifying the state of the defined entities that the extensions create. The states of the defined entities can also help you to troubleshoot problems with the extensions.

Defined Entity Type

You define at runtime the schema of the information that you can store by using defined entities. The schema is defined in the entity type through a JSON document. When you create a defined entity type, you create a new custom VMware Cloud Director type similar to VMs and vApps which you can manage by extensions and behaviors. For example, if we consider the entity type NativeContainerCluster, each instance of this type contains information about a specific Kubernetes cluster. To obtain the information about the cluster, the VMware Cloud Director Container Service Extension communicates with VMware Cloud Director through the VMware Cloud Director API and provides the necessary information to the users.

Once you create an instance of a defined entity type, you cannot change the type, schema, and behaviors anymore. To add new functionalities to the entity type, you must create a new version of the type. When a defined entity instance is based on an earlier version of the entity type, you can upgrade the defined entity to use a later version of the type by setting the type property of the entity to the ID of the new type. When you create a defined entity, in the API call, the contents of the entity property must match the JSON schema specified in the entity type. You can grant access to an entity type only to specific users and organizations. You can set different access restrictions to the different versions of an entity type.

The schema of the entity type can specify the access to the different content fields. You can mark properties as public, protected, or private.

Table 1. Entity Type Property Access Control
Property Status Access Control
Public All users can view and modify the field.
Protected All users can view the field. Only users with Full Control access can create and modify the field. The users must have the Admin Full Control: TYPE right or both the Full Control: TYPE right and a Full Control ACL.
Private Only users with Full Control access can view, create, and modify the field. The users must have the Admin Full Control: TYPE right or both the Full Control: TYPE right and a Full Control ACL
For example, the JSON schema for the entity property clusterState can be the following. 
"clusterState" : {
  "type" : "string",
  "x-vcloud-restricted" : "protected"
}

Interfaces and Behaviors

Defined entities also have interfaces that you can use to define behaviors. If we use the Kubernetes example, each cluster entity type has a different implementation of the behaviors defined in the container cluster interface. The Tanzu Kubernetes cluster type behaviors communicate with vSphere to perform the necessary actions and the native container cluster type behaviors communicate with the VMware Cloud Director Container Service Extension.

All users can see the interfaces of defined entities.

There are different ways to define behaviors.

  • You can create and publish a VMware Aria Automation Orchestrator workflow and create а behavior that invokes the workflow.
  • You can link any functionality to a behavior by using a WebHook.
  • With MQTT behaviors, you can call a functionality in an extension. By using MQTT you can communicate with the extension directly and the extension can provide a more detailed status.
Figure 1. Runtime Defined Entity Interfaces
The diagram shows that each entity type has a different implementation of the behaviors defined in the runtime defined entity interface.
Runtime defined entity interfaces, types, and behaviors have specific API IDs.
  • Interface API IDs are in the form of urn:vcloud:interface:vendor_name:interface_name:version.
  • Type API IDs are in the form of urn:vcloud:type:vendor_name:type_name:version.
  • Behavior API IDs are in the form of urn:vcloud:behavior-interface:behavior_name:vendor_name:interface_name:version or urn:vcloud:behavior-type:behavior_name:vendor_name:interface_name:version.

Creating a Runtime Defined Entity

To create a defined entity, you start by configuring the external resources and adding the necessary information to the defined entity. This process might require a few iterations. To resolve the defined entity, you must verify that the contents of the schema have all the necessary information. If the contents do not match the JSON schema specified in the type, the defined entity state changes to Resolution_Error. If you fill in the information correctly, the defined entity state changes to Resolved and is ready to use.

Because tasks track all long-running runtime defined entity operations, you can use the VMware Cloud Director UI to monitor the creation of defined entities, behavior invocation, and so on. When the status of a defined entity changes to Resolved, the corresponding task in the UI appears as Succeeded.

When you create a defined entity in one tenant organization, you cannot share the defined entity with tenants in another organization. If you create a defined entity in the System organization, you can share it with tenant users or tenant organizations.

Sample API Call to Create a Defined Entity

The example provides a sample API call to create a new entity of the pksContainerCluster type.

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

Access to Defined Entity Instances

Two complementary mechanisms control the access to runtime defined entities.

  • Rights - When you create a runtime defined entity type, you create a rights bundle for the type. To provide access to specific operations, you must assign rights from this bundle to other roles. Each bundle has five type-specific rights: View: TYPE, Edit: TYPE, Full Control: TYPE, Administrator View: TYPE, and Administrator Full Control: TYPE.

    The View: TYPE, Edit: TYPE, and Full Control: TYPE rights work only in combination with an ACL entry.

  • Access Control List (ACL) - The ACL table contains entries defining the access users have to specific entities in the system. It provides an extra level of control over the entities. For example, while an Edit: TYPE right specifies that a user can modify entities to which they have access, the ACL table defines which entities the user has access to.

    System administrators with the View General ACL right can view the ACLs assigned to a specific defined entity by using the accessControls API. See VMware Cloud Director OpenAPI.

    System administrators with the Manage General ACL right can create, modify, and remove specific ACLs by using the accessControls API.

Table 2. Rights and ACL Entries for RDE Operations
Entity Operation Option Description
Read Administrator View: TYPE right Users with this right can see all runtime defined entities of this type within an organization.
View: TYPE right and ACL entry >= View Users with this right and a read-level ACL can view runtime defined entities of this type.
Modify Administrator Full Control: TYPE right Users with this right can create, view, modify, and delete runtime defined entities of this type in all organizations.
Edit: TYPE right and ACL entry >= Change Users with this right and modify-level ACL can create, view, and modify runtime defined entities of this type.
Delete Administrator Full Control: TYPE right Users with this right can create, view, modify, and delete runtime defined entities of this type in all organizations.
Full Control: TYPE right and ACL entry = Full Control Users with this right and full control-level ACL can create, view, modify, and delete runtime defined entities of this type.

You can use the VMware Cloud Director API or UI to publish the rights bundle to any organizations you want to manage the entities of this type. After publishing the rights bundle, you can assign rights from the bundle to roles within the organization.

You can use the VMware Cloud Director API to edit the ACL table.

Access to Defined Entity Interface and Type Operations

Defined entity interface and type operations require specific rights that certain service providers might not have. Before performing an operation, verify that you have the necessary rights.

Table 3. Rights for Defined Entity Interface and Type Operations
Operation Requirement
View and query interface All users have the necessary rights.
Create interface You must have the Create new custom entity definition right.
Edit interface You must have the Edit custom entity definition right.
Delete interface You must have the Delete custom entity definition right.
Create type You must have the Create new custom entity definition right.
View type The minimum requirement is ReadOnly Type ACL.
Edit and delete type You must have the Edit/Delete custom entity definition right and a FullControl Type ACL .

Working with Runtime Defined Entities

To invoke behaviors on a defined entity, it must be in the Resolved state. To delete a defined entity, it must be in the Resolved or Resolution_Error state.

You can modify entity types and interfaces only if they do not have instances. You can only modify the referenced entity type by changing its version.

To diagnose issues with the access to defined entities,you can use the entity ACL query APIs and verify the necessary rights. In addition, the rights bundle of an entity type must be published to the tenants that you want to use it.