VMware Cloud Director object extensions are external applications that can participate in, influence, or override the logic that VMware Cloud Director applies to workflows like vApp instantiation and placement.

An object extension can participate as a peer of the system in the logic that determines the outcome of these workflows. For example, an object extension might use information provided by the system to place a VM on a specific host or assign it a specific storage profile. Operation of object extensions is transparent to system users. An extension can also allow the VMware Cloud Director procedures in which it participates to run to completion unmodified.

Object Extensibility Framework

VMware Cloud Director object extensions are implemented in a framework that has three components:
  • The VMware Cloud Director API supports VMware Cloud Director object extensions with two kinds of operations:
    • Object registration requests, which register an object extension with the system.
    • Selector extension requests, which select system objects to extend and specify the extension points and execution phases in which the extension participates.
  • Communication between the system and an object extension is handled using the system AMQP service described in #GUID-BEE98E2A-1E11-4813-AEB2-6E6FFB79E890. Extensions must create their own exchanges.
  • Extension points themselves are defined in the system. When an object extension registers with VMware Cloud Director, it can specify one more of these extension points, expressed as a URN:
    • urn:selector:providerVdc
    • urn:selector:organizationVdc
    • urn:selector:organization
An object extension that operates on a subset of these extension points can specify that subset at registration to prevent it from being associated with extension points outside the subset. An object extension that operates on all extension points does not need to specify any of them at registration.

All other operations are implemented by the extensions themselves, which read messages from their AMQP exchange and provide responses, as AMQP messages, to VMware Cloud Director.

For additional information and code examples, see VMware Sample Exchange at https://developercenter.vmware.com/samples/.

Extensibility Phases

Extensible operations are distinguished by having life cycle events such as create, update, and delete mapped to an extensibility phas e. An object extension can participate in zero or more phases of an extensible VMware Cloud Director operation. Each phase is identified by a URN.

The system collects the internal information that it uses when executing a phase and sends it to the extension as an AMQP message. If specified by the extension, the phase waits for a reply before proceeding (see Message Handling). By sending a reply that modifies values that the phase supplies, the extension can affect the outcome of the phase. XML schema definition files for the messages sent by each phase are available on the VMware Sample Exchange at https://developercenter.vmware.com/samples/.

Each phase has an inherent cardinality that establishes the number of extensions that can participate in phase operations. Some operations such as VM placement, which must take into account factors such as host configuration, affinities, and storage capabilities, can accommodate participation by multiple extensions and have a cardinality greater than 1. Others, such as creation of a VM, are not candidates for participation from multiple extensions, and have a cardinality of exactly 1.

Table 1. Extensibility Phases
Name Cardinality Timeout in Seconds Summary
urn:extensionPoint:vm:gatherRequirements 1-n 5 Gathers virtual machine placement requirements, including CPU and memory configurations, storage IOPS, and datastore affinity and provides them to the extension
urn:extensionPoint:vm:calculateSolution 1-n 60 Calculates a placement solution and provides it to the extension
urn:extensionPoint:vm:create 1 60 Creates a virtual machine

Message Handling

An object extension can specify how it wants to handle messages sent by a phase. Three types of message handling are supported.
async
async messages provide a stream of information as the system proceeds with phase execution. Extensions that specify async message handling are informed of phase operations but cannot influence the outcome of a phase.
blocking
blocking messages force the execution of the phase to block until the extension takes some action. Extensions that specify blocking message handling must reply to each message within the specified timeout interval or the system proceeds with the operation.
needsApproval
needsApproval messages force the execution of the phase to block until approved by a system administrator.

Selector Associations and Extension Policies

When it creates a SelectorExtension, an object extension can express interest in all objects of a certain type, or in a specific object. An object extension that selects an object type affects all instances of that type. Object extensions that select an object instance affect only that instance, and override the operations of any extension that might be in place for that instance's type.

Selector extension request URLs have one of the following forms, where type is one of:
  • providervdcs
  • vdcs
  • orgs
In this table:
  • API-URL is a URL of the form https://vcloud.example.com/api.
  • id is a unique identifier in the form of a UUID, as defined by RFC 4122.
Table 2. Selector Extension Request URLs
HTTP Verb Request URL Prototype Summary
GET API-URL/admin/type/extension Retrieve all extensions that are associated with the default selector policy for type.
POST API-URL/admin/type/extension Add a selector extension to the default policy for type.
GET API-URL/admin/type/extension/extension-ID Retrieve extension extension-ID associated with the default selector policy for type.
PUT API-URL/admin/type/extension/extension-ID Update extension extension-ID associated with the default selector policy for type.
DELETE API-URL/admin/type/extension/extension-ID Delete extension extension-ID from the default selector policy for type.
GET API-URL/admin/type/selector-ID/extension/ Retrieve all extensions associated with the specified selector-ID and type.
POST API-URL/admin/type/selector-ID/extension/ Add a selector extension to the specified selector-ID to update the default selector policy for type.

Extension Workflow

A typical extension implements a workflow similar to this one:
  1. Use the VMware Cloud Director API to create an extension-specific exchange on the system AMQP service. See #GUID-BEE98E2A-1E11-4813-AEB2-6E6FFB79E890.
  2. Set up a listener for that exchange.
  3. Use the VMware Cloud Director API to register with the system. See Register an Object Extension.
  4. Use the VMware Cloud Director API to create one or more selector extensions for specific objects or types of objects. See Create a Selector Extension.
  5. Listen on the AMQP exchange for messages from extension points, and take appropriate actions. For example:
    • Reply to the extension point with a message that modifies some of the values included in a previous message
    • Use the VMware Cloud Director API to create or update objects based on the results of message analysis or processing

    An extension continues handling the stream of messages from extension points if the system or the extension is active.

Related Videos