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
.
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 |
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.
- 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
orurn: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.
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.
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.