vCloud Director object extensions are external applications that can participate in, influence, or override the logic that vCloud 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 vCloud Director procedures in which it participates to run to completion unmodified.

vCloud Director object extensions are implemented in a framework that has three components:

The vCloud API supports vCloud 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 Configure the vCloud Director AMQP Service. Extensions must create their own exchanges.

Extension points themselves are defined in the system. When an object extension registers with vCloud Director, it can specify one more of these extension points, expressed as a URN:




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 vCloud Director.

For additional information and code examples, see VMware Sample Exchange at

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 vCloud 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

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.

Extensibility Phases



Timeout in Seconds





Gathers virtual machine placement requirements, including CPU and memory configurations, storage IOPS, and datastore affinity and provides them to the extension




Calculates a placement solution and provides it to the extension




Creates a virtual machine

An object extension can specify how it wants to handle messages sent by a phase. Three types of message handling are supported.


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 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 messages force the execution of the phase to block until approved by a system administrator.

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:




In this table:

API-URL is a URL of the form

id is a unique identifier in the form of a UUID, as defined by RFC 4122.

Selector Extension Request URLs


Request URL Prototype




Retrieve all extensions that are associated with the default selector policy for type.



Add a selector extension to the default policy for type.



Retrieve extension extension-ID associated with the default selector policy for type.



Update extension extension-ID associated with the default selector policy for type.



Delete extension extension-ID from the default selector policy for type.



Retrieve all extensions associated with the specified selector-ID and type.



Add a selector extension to the specified selector-ID to update the default selector policy for type.

A typical extension implements a workflow similar to this one:


Use the vCloud API to create an extension-specific exchange on the system AMQP service. See Configure the vCloud Director AMQP Service.


Set up a listener for that exchange.


Use the vCloud API to register with the system. See Register an Object Extension.


Use the vCloud API to create one or more selector extensions for specific objects or types of objects. See Create a Selector Extension.


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 vCloud 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.